1# LLDB Debugger
2
3
4## Introduction
5
6Low Level Debugger (LLDB) is a next-generation, high-performance debugger. For details, visit the [LLDB official website](https://lldb.llvm.org/).
7
8LLDB used in OpenHarmony is developed on [LLVM 15.0.4](https://github.com/llvm/llvm-project/releases/tag/llvmorg-15.0.4). It is the default debugger in DevEco Studio and supports debugging of C and C++ applications.
9
10
11## How to Obtain
12
13Obtain the OpenHarmony SDK. Then find LLDB in the **\ohos-sdk\[system]\native\llvm** directory of the SDK, where **system** can be **windows**, **linux**, or **darwin**.
14
15For example, for Windows, **lldb.exe** is stored in **\ohos-sdk\windows\native\llvm\bin** after the SDK is decompressed.
16
17
18## Functions
19
20The following lists some functions supported by LLDB. For more functions and related commands, see [LLDB Usage Guide](https://gitee.com/openharmony/third_party_llvm-project/blob/master/lldb/README.md) and [LLDB official manual](https://lldb.llvm.org).
21
22- Logging
23
24- Breakpoint management
25
26- Watchpoint management
27
28- Expression processing
29
30- Viewing variables
31
32- Process/Thread management
33
34- Assembly processing
35
36- Obtaining source code information
37
38- Signal processing
39
40- Launching a process
41
42- Attaching to a process
43
44
45## When to Use
46
47- Local debugging
48  - Local debugging in the Linux x86_64 environment
49
50     LLDB supports debugging of C and C++ applications in the Linux x86_64 environment.
51  - Local debugging on the macOS desktop
52
53     LLDB supports debugging of C and C++ applications on the macOS desktop (including macOS x86_64 and M1).
54
55- Remote debugging
56  - Remote debugging based on DevEco Studio
57
58     LLDB supports remote debugging of native C++ applications by connecting to OpenHarmony devices or emulators from the Windows and macOS desktops based on DevEco Studio.
59  - Remote debugging through direct connection
60
61     LLDB supports remote debugging of C and C++ applications by directly connecting to OpenHarmony devices from Windows, macOS desktop, and Linux x86_64 environment.
62
63
64## Local Debugging
65
66> **NOTE**
67>
68> The local debugging procedure for Linux x86_64 is the same as that for macOS.
69
70**Procedure**
71
72- Using LLDB to start and debug an application
73
74  The following walks you through on how to debug an executable file named **a.out** in the Linux x86_64 environment. The file contains debugging information and is generated by the Clang compiler, which is of the same version as LLDB.
75
76  1. Obtain the executable file **a.out**.
77  2. Run LLDB and specify the file to debug as **a.out**.
78
79      ```lldb
80      ./lldb a.out
81      ```
82  3. Set breakpoints at the **main** function in the code.
83
84      ```lldb
85      (lldb) b main
86      ```
87  4. Run the application, and it stops at the first breakpoint.
88
89      ```lldb
90      (lldb) run
91      ```
92  5. Continue to run the application.
93
94      ```lldb
95      (lldb) continue
96      ```
97  6. List all the breakpoints.
98
99      ```lldb
100      (lldb) breakpoint list
101      ```
102  7. Show the arguments and local variables of the current frame.
103
104      ```lldb
105      (lldb) frame variable
106      ```
107  8. Run debugging commands as required to continue debugging.
108  9. Exit debugging.
109
110      ```lldb
111      (lldb) quit
112      ```
113
114- Using LLDB to debug a started application
115
116  The following walks you through on how to debug an executable file named **a.out** in the macOS environment. The file contains user input and debugging information and is generated by the Clang compiler.
117
118  1. Start the application on Command Line Interface (CLI) 1. (The message "Please input a number of type int" is displayed.)
119
120      ```shell
121      ./a.out
122      ```
123  2. Run LLDB on CLI 2.
124
125      ```shell
126      ./lldb
127      ```
128  3. Attach to the application.
129
130      ```lldb
131      (lldb) process attach --name a.out
132      ```
133  4. Set a breakpoint in line 10 of **hello.cpp**.
134
135      ```lldb
136      (lldb) breakpoint set --file hello.cpp --line 10
137      ```
138  5. On CLI 1, enter a number of the int type.
139
140      ```shell
141      88
142      ```
143  6. Continue to run the application on CLI 2. The application stops at the breakpoint.
144
145      ```lldb
146      (lldb) continue
147      ```
148  7. Run debugging commands as required to continue debugging.
149  8. Detach from the application.
150
151      ```lldb
152      (lldb) detach
153      ```
154  9. Exit debugging.
155
156      ```lldb
157      (lldb) quit
158      ```
159
160  > **NOTE**
161  >
162  > You can also perform step 4 in prior to step 3.
163
164
165## Remote Debugging
166
167> **NOTE**
168> - During remote debugging, **lldb-server** and **lldb** must be used together.
169>
170> - The remote debugging procedures for Windows, Linux x86_64, and macOS are the same.
171
172**Procedure**
173
174The following walks you through on how to remotely debug an executable file named **a.out** by connecting to an Arm-based OpenHarmony device (for example, RK3568 development board) from the Windows platform.
175
176> **NOTE**
177>
178> In the command below, **/data/local/tmp** indicates the specified directory on the device.
179>
180> **8080** is the listening port, which can be customized.
181>
182> You must have the execute permission on the **lldb-server** and **a.out** files of the device.
183
1841. Open CLI 1 and push **lldb-server** and **a.out** to the device. (**a.out** is generated when you compile **hello.cpp** using the Clang compiler.)
185
186   ```shell
187   hdc file send lldb-server /data/local/tmp
188   hdc file send a.out /data/local/tmp
189   ```
190
1912. Run **lldb-server**.
192
193   ```shell
194   hdc shell ./data/local/tmp/lldb-server p --server --listen "*:8080"
195   ```
196
1973. Open CLI 2 and run the binary file **lldb**.
198
199   ```shell
200   ./lldb
201   ```
202
2034. Select and connect to the remote device on the LLDB CLI.
204
205   ```lldb
206   (lldb) platform select remote-ohos
207   (lldb) platform connect connect://localhost:8080
208   ```
209
2105. Specify the binary file **a.out** on the device to be debugged.
211
212   ```lldb
213   (lldb) target create /data/local/tmp/a.out
214   ```
215
2166. Set breakpoints at the **main** function in the code.
217
218   ```lldb
219   (lldb) b main
220   ```
221
2227. Start the application.
223
224   ```lldb
225   (lldb) run
226   ```
227
2288. Display source code for the current target process.
229
230   ```lldb
231   (lldb) source list
232   ```
233
2349. Run debugging commands as required to continue debugging.
235
23610. Exit debugging.
237
238    ```lldb
239    (lldb) quit
240    ```
241