mirror of
https://github.com/vczh-libraries/Release.git
synced 2026-08-17 17:31:44 +08:00
103 lines
4.9 KiB
Markdown
103 lines
4.9 KiB
Markdown
# Debugging a Project
|
|
|
|
- Go to `Windows Specific` section if you are on Windows.
|
|
- Go to `Linux/macOS Specific` section if you are on Linux/macOS.
|
|
- Go to `macOS Specific` section if you are on macOS.
|
|
|
|
## Windows Specific
|
|
|
|
Debugging can be useful when you lack necessary information.
|
|
CDB accepts exactly the same commands as WinDBG.
|
|
|
|
### Start a Debugger
|
|
|
|
Read `REPO-ROOT/Project.md` to understand the solution folder and the unit test project name you are working with.
|
|
Additional information can be found in the first line of `REPO-ROOT/.github/Scripts/Execute.log`.
|
|
Choose the executable for the intended configuration and read its arguments from the matching `*.vcxproj.user` file.
|
|
|
|
Run CDB directly from `SOLUTION-ROOT` in a PTY-backed tool session:
|
|
|
|
```powershell
|
|
cd SOLUTION-ROOT
|
|
& $env:CDBPATH -lines "ABSOLUTE-PATH-TO-EXECUTABLE" ARGUMENTS
|
|
```
|
|
|
|
Keep the session ID returned by the tool. The process is paused at the initial breakpoint, giving you a chance to configure source mode and set breakpoints. Send these commands as newline-terminated stdin, one round at a time, and wait for output between rounds:
|
|
|
|
```text
|
|
l+s;l+t
|
|
g
|
|
```
|
|
|
|
Do not leave unbounded debugger output flowing through the terminal. If output repeats continuously, interrupt execution immediately and configure the relevant exception or output filter before continuing.
|
|
|
|
### Stop a Debugger
|
|
|
|
- If the debugged process is running or stuck, send Ctrl-C (`\u0003`).
|
|
- Send `q` to terminate the debugged process and CDB.
|
|
- If CDB does not respond, terminate the exact CDB process first and then the exact debugged process.
|
|
|
|
### Sending Commands to CDB
|
|
|
|
Send commands to the same PTY-backed session. The effect of commands lasts for the whole session. For example, after you execute `.frame X`, you do not need to repeat it to use `dx` under the same call stack frame later.
|
|
|
|
Multiple commands can be executed in sequence, separated by ";".
|
|
The `-lines` option and the `l+s;l+t` commands enable source mode, which means you can see source files and line numbers in the call stack, and step in/out/over work line by line.
|
|
CDB accepts exactly the same commands as WinDBG, and here are some recommended commands:
|
|
- **g**: continue until hitting a breakpoint or crashing.
|
|
- **k**n: print current call stack.
|
|
- **kn LINES**: print first `LINES` of the current call stack.
|
|
- **.frame NUMBER**: inspect the call stack frame labeled with `NUMBER`. `kn` will show the number, file and line along with the call stack.
|
|
- **dv**: list all available variables in the current call stack frame.
|
|
- **dx EXPRESSION**: evaluate the `EXPRESSION` and print the result. `EXPRESSION` can be any valid C programming language expression. When you specify a type (especially when doing casting), full namespaces are required, do not start with `::`.
|
|
- **bp `FILE:LINE`**: set a breakpoint at the specified line in `FILE`, starting from 0. A pair of "`" characters are required around the target, this is not Markdown syntax.
|
|
- **bl**, **.bpcmds**, **be NUMBERS**, **bd NUMBERS**, **bc NUMBERS**, **bsc NUMBER CONDITION**: list, list with attached commands, enable, disable, delete, attach a command to breakpoint(s).
|
|
- **p**: step over, aka execute the complete current line.
|
|
- **t**: step in, aka execute the current line, if any function is called, goes into the function.
|
|
- **pt**: step out, aka run until the end of the current function.
|
|
|
|
Load the installed `vlpp.natvis` file with `.nvload` when structured visualization is needed.
|
|
It formats some primitive types defined in the `Vlpp` project,
|
|
including `WString` and other string types, `Nullable`, `Variant`, container types, etc.
|
|
The formatting applies to the **dx** command,
|
|
when you want to see raw data instead of formatted printing,
|
|
use **dx (EXPRESSION),!**.
|
|
|
|
You can also use `dv -rX` to expand "X" levels of fields. The default option is `-r0`, which only expands one level of fields.
|
|
|
|
### Commands to Avoid
|
|
|
|
- Only use **dv** without any parameters.
|
|
- DO NOT use **dt**.
|
|
|
|
## Linux/macOS Specific
|
|
|
|
Like building and running, debugging must be performed from the same folder that contains `vmake`:
|
|
- If the repo has only one project, it is in `REPO-ROOT/Test/Linux`.
|
|
- If the repo has multiple projects, it is in `REPO-ROOT/Test/Linux/PROJECT-NAME`.
|
|
- The `PROJECT-NAME` name follows `PROJECT-NAME.vcxproj`.
|
|
You are required to `cd` to such folder before launching `lldb`, otherwise relative paths to the binary and source files will be wrong.
|
|
|
|
`lldb` is going to block the terminal and wait for interaction, you should always start `lldb` in a PTY-backed tool session, for example:
|
|
|
|
```bash
|
|
lldb -- ./Bin/UnitTest /C
|
|
```
|
|
|
|
Keep the session ID returned by the tool. Send debugger commands as newline-terminated stdin, one round at a time, and wait for output between rounds.
|
|
|
|
End the session with:
|
|
|
|
```text
|
|
quit
|
|
```
|
|
|
|
If the debugged process is still running or stuck, send Ctrl-C (`\u0003`), then send:
|
|
|
|
```text
|
|
process kill
|
|
quit
|
|
```
|
|
|
|
For non-interactive one-shot debugging, wrap `lldb` with `timeout` so it cannot block forever.
|