Skip to content

Commit d9cf6db

Browse files
noahfalkgewarren
noahfalk
and
gewarren
authored
Add LLDB docs (#44902)
* Add LLDB docs Adding docs that show how to install and use LLDB and dotnet debugger extensions together. We've long had docs about the extensions themselves, but learn.microsoft.com had nothing that showed how to put it together with LLDB. Some of the LLDB info comes from https://github.com/dotnet/diagnostics/blob/main/documentation/lldb/linux-instructions.md. I left out distros where users need to build LLDB, but we could add that in the future if needed. Co-authored-by: Genevieve Warren <[email protected]>
1 parent 1175f1d commit d9cf6db

File tree

3 files changed

+198
-1
lines changed

3 files changed

+198
-1
lines changed

‎docs/core/diagnostics/debugger-extensions.md

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ helpviewer_keywords:
1111

1212
# .NET debugger extensions
1313

14-
The .NET debugger extensions let you view information about code that's running inside the .NET runtime, both on live processes and dumps. The extensions are preinstalled with [Windbg](/windows-hardware/drivers/debugger/debugger-download-tools), and can be [downloaded](dotnet-debugger-extensions.md) for use with LLDB. You can use the .NET debugger extensions to:
14+
The .NET debugger extensions let you view information about code that's running inside the .NET runtime, both on live processes and dumps. The extensions work with [Windbg](/windows-hardware/drivers/debugger/debugger-download-tools) and [LLDB](https://lldb.llvm.org/). You can use the .NET debugger extensions to:
1515

1616
- Collect information about the managed heap.
1717
- Look for heap corruptions.
@@ -20,6 +20,16 @@ The .NET debugger extensions let you view information about code that's running
2020

2121
The .NET debugger extensions include commands from the existing [dotnet-sos](dotnet-sos.md) tool as well as new commands. A limited set of commands are also now supported for the Native AOT runtime.
2222

23+
## Install
24+
25+
### Windows
26+
27+
Install Windbg from the [Windows SDK](/windows-hardware/drivers/debugger/debugger-download-tools). Windbg versions 10.0.18317.1001 and later automatically load the extensions from the Microsoft extension gallery.
28+
29+
### Linux
30+
31+
To install LLDB and the .NET debugger extensions, see [Install and use LLDB on Linux](lldb-linux.md).
32+
2333
## Syntax
2434

2535
Under windbg: `![command] [options]`

‎docs/core/diagnostics/lldb-linux.md

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
---
2+
title: Install and use LLDB on Linux
3+
description: Instructions for installing and using LLDB to debug a .NET application on Linux
4+
ms.date: 02/13/2025
5+
---
6+
7+
# Install and use LLDB on Linux
8+
9+
[LLDB](https://lldb.llvm.org/) is a powerful, open-source debugger that's part of the LLVM project. When you're debugging .NET applications on Linux, you can use LLDB with the [.NET debugger extensions](debugger-extensions.md) to inspect managed application state. LLDB can work with both dumps and live processes.
10+
11+
## Install
12+
13+
### Install LLDB
14+
15+
The .NET debugger extensions require at least LLDB 3.9 but version 10.0 or later is recommended. The following sections provide instructions for installing LLDB on popular Linux distributions.
16+
17+
#### AzureLinux 2.0 and later
18+
19+
To install the LLDB packages:
20+
21+
```console
22+
sudo tdnf install lldb
23+
```
24+
25+
To launch LLDB:
26+
27+
```console
28+
lldb
29+
```
30+
31+
#### Ubuntu 20.04 and later
32+
33+
To install the LLDB packages:
34+
35+
```console
36+
sudo apt-get update
37+
sudo apt-get install lldb
38+
```
39+
40+
To launch LLDB:
41+
42+
```console
43+
lldb
44+
```
45+
46+
#### Alpine 3.9 and later
47+
48+
To install the LLDB packages:
49+
50+
```console
51+
apk update
52+
apk add lldb
53+
```
54+
55+
To launch LLDB:
56+
57+
```console
58+
lldb
59+
```
60+
61+
#### Debian 9 and later
62+
63+
To install the LLDB packages:
64+
65+
```console
66+
sudo apt-get install lldb-3.9 python-lldb-3.9
67+
```
68+
69+
To launch LLDB:
70+
71+
```console
72+
lldb-3.9
73+
```
74+
75+
#### Fedora 29 and later
76+
77+
To install the LLDB packages:
78+
79+
```console
80+
sudo dnf install lldb python2-lldb
81+
```
82+
83+
To launch LLDB:
84+
85+
```console
86+
lldb
87+
```
88+
89+
#### RHEL 7.5 and later
90+
91+
See [LLDB](https://access.redhat.com/documentation/en-us/red_hat_developer_tools/1/html/using_llvm_12.0.1_toolset/assembly_llvm#proc_installing-comp-toolset_assembly_llvm) on RedHat's website.
92+
93+
### Install the .NET debugger extensions
94+
95+
Install the .NET debugger extensions using the [dotnet-debugger-extensions](dotnet-debugger-extensions.md) install tool. The installer creates a `.lldbinit` file in your home directory that automatically loads the extensions when you start LLDB.
96+
97+
> [!NOTE]
98+
> The version of the debugger extensions does not need to match the version of the .NET runtime. We recommend using the latest extension version.
99+
100+
> [!NOTE]
101+
> Installing with [dotnet-sos](dotnet-sos.md) instead of [dotnet-debugger-extensions](dotnet-debugger-extensions.md) also works, but only installs a subset of the extension commands.
102+
103+
## Getting started with LLDB
104+
105+
This example shows using LLDB to attach to a pre-existing .NET application (`dotnet webapp.dll`) that's running on the machine.
106+
107+
1. Use the `ps` command to find the process ID (PID) of the .NET application you want to debug.
108+
109+
```console
110+
$ ps -ao pid,cmd
111+
PID CMD
112+
697 -bash
113+
229233 dotnet webapp.dll
114+
229696 ps -ao pid,cmd
115+
... other processes omitted for brevity ...
116+
```
117+
118+
In this case, the PID of the .NET application to debug is 229233.
119+
120+
1. Run LLDB and attach to the process.
121+
122+
Launch LLDB using the appropriate command for your distribution (shown previously in the [Install LLDB](#install-lldb) section). Often this is just `lldb`, but some distros require a version number in the name, like `lldb-3.9`.
123+
124+
```console
125+
$ lldb
126+
Current symbol store settings:
127+
-> Cache: /home/username/.dotnet/symbolcache
128+
-> Server: https://msdl.microsoft.com/download/symbols/ Timeout: 4 RetryCount: 0
129+
(lldb)
130+
```
131+
132+
1. At the `(lldb)` prompt, run the process attach command.
133+
134+
```console
135+
(lldb) process attach --pid 229233
136+
Process 229233 stopped
137+
* thread #1, name = 'dotnet', stop reason = signal SIGSTOP
138+
frame #0: 0x00007f2ca7c11117 libc.so.6`___lldb_unnamed_symbol3457 + 231
139+
libc.so.6`___lldb_unnamed_symbol3457:
140+
-> 0x7f2ca7c11117 <+231>: movl %r12d, %edi
141+
0x7f2ca7c1111a <+234>: movq %rax, %rbx
142+
0x7f2ca7c1111d <+237>: callq 0x7f2ca7c10a60 ; ___lldb_unnamed_symbol3445
143+
0x7f2ca7c11122 <+242>: jmp 0x7f2ca7c11089 ; <+89>
144+
thread #2, name = 'dotnet-ust', stop reason = signal SIGSTOP
145+
frame #0: 0x00007f2ca7c9e88d libc.so.6`syscall + 29
146+
libc.so.6`syscall:
147+
... more output omitted ...
148+
```
149+
150+
The debugger is now attached and you can use both built-in LLDB commands and .NET debugger extension commands to inspect the process state.
151+
152+
> [!NOTE]
153+
> If LLDB outputs 'error: attach failed: Operation not permitted', this means you don't have sufficient privileges to debug. The most reliable way to resolve this is to quit LLDB and restart using sudo. When elevated LLDB won't automatically run the normal .lldbinit script, you can do so explicitly by using the `--source` argument on the command line: `sudo lldb --source ~/.lldbinit`.
154+
155+
1. Run an example command
156+
157+
The clrstack command displays the stack trace for .NET code on the currently selected thread.
158+
159+
```console
160+
(lldb) clrstack
161+
OS Thread Id: 0x497 (1)
162+
Child SP IP Call Site
163+
00007FFD0877D260 00007f2ca7c11117 [HelperMethodFrame_1OBJ: 00007ffd0877d260]
164+
System.Threading.Monitor.ObjWait(Int32, System.Object)
165+
00007FFD0877D390 00007F2C2864AA0E System.Threading.Monitor.Wait(System.Object, Int32)
166+
00007FFD0877D3A0 00007F2C28654625 System.Threading.ManualResetEventSlim.Wait(Int32,
167+
System.Threading.CancellationToken)
168+
00007FFD0877D420 00007F2C286684A8 System.Threading.Tasks.Task.SpinThenBlockingWait(Int32,
169+
System.Threading.CancellationToken)
170+
00007FFD0877D480 00007F2C2866832D System.Threading.Tasks.Task.InternalWaitCore(Int32,
171+
System.Threading.CancellationToken)
172+
00007FFD0877D4D0 00007F2C286B2508 System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(System.Threading.Tasks.Task, System.Threading.Tasks.ConfigureAwaitOptions)
173+
00007FFD0877D4F0 00007F2C29281B45 Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.Run(Microsoft.Extensions.Hosting.IHost)
174+
00007FFD0877D510 00007F2C29121A7D Program.<Main>$(System.String[]) [/home/username/app/Program.cs @ 25]
175+
```
176+
177+
## Next steps
178+
179+
To learn more about the commands available when debugging .NET applications with LLDB, see the documentation for the [.NET debugger extensions](debugger-extensions.md) and [LLDB](https://lldb.llvm.org/).
180+
181+
## See also
182+
183+
- [LLDB](https://lldb.llvm.org/) for more information about the LLDB debugger.
184+
- [.NET debugger extensions](debugger-extensions.md) for a reference of the extension commands available.
185+
- [dotnet-symbol](dotnet-symbol.md) for more details on installing and using the symbol download tool.

‎docs/navigate/tools-diagnostics/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -487,6 +487,8 @@ items:
487487
href: ../../core/diagnostics/collect-dumps-crash.md
488488
- name: Frequently asked questions
489489
href: ../../core/diagnostics/faq-dumps.yml
490+
- name: Install and use LLDB on Linux
491+
href: ../../core/diagnostics/lldb-linux.md
490492
- name: Symbols
491493
href: ../../core/diagnostics/symbols.md
492494
- name: EventPipe

0 commit comments

Comments
 (0)