View this readme on GitHub (working hyperlinks!)
- Attach or Launch
- Redirect debuggee stdio to a file or a terminal.
- Breakpoints (function, conditional, regex)
- Disassembly View
- Line or instruction stepping
- Hover tips
- Watch
- Multiple threads
- Configurable variable formatting
- LLDB commands
- Expression evaluation
- Rust language support
- Visual Studio Code 1.5.0.
- LLDB with Python scripting support on system PATH. (Installing LLDB)
See VS Code Debugging page for general instructions.
Create a new launch configuration to either launch your program or attach to already running process:
| parameter | type | req | |
|---|---|---|---|
| name | string | Y | Launch configuration name. |
| type | string | Y | Set to lldb. |
| request | string | Y | Set to launch. |
| program | string | Y | Path to debuggee executable. |
| args | string | [string] | Command line parameters. If this is a string, it will be split using shell-like syntax. | |
| cwd | string | Working directory. | |
| env | dictionary | Additional environment variables. Tip: you may refer to existing environment variables like so: ${env.VARIABLE}. |
|
| stdio | string | [string] | dictionary | Stdio configuration (see below). | |
| terminal | string | Destination for debuggee's stdio streams:
|
|
| stopOnEntry | boolean | Whether to stop debuggee immediately after launching. | |
| initCommands | [string] | LLDB commands executed upon debugger startup. | |
| preRunCommands | [string] | LLDB commands executed just before launching the program. | |
| sourceLanguages | [string] | A list of source languages used in the program. This is used for setting exception breakpoints, since they tend to be language-specific. |
Note that attaching to a running process may be restricted on some systems. You may need to adjust system configuration to enable it.
| parameter | type | req | |
|---|---|---|---|
| name | string | Y | Launch configuration name. |
| type | string | Y | Set to lldb. |
| request | string | Y | Set to attach. |
| program | string | Y | Path to debuggee executable. |
| pid | number | The process id to attach to. pid may be omitted, in which case the debugger will attempt to locate an already running instance of the program. | |
| stopOnEntry | boolean | Whether to stop debuggee immediately after attaching. | |
| initCommands | [string] | LLDB commands executed upon debugger startup. | |
| preRunCommands | [string] | LLDB commands executed just before attaching. | |
| sourceLanguages | [string] | A list of source languages used in the program. This is used for setting exception breakpoints, since they tend to be language-specific. |
The stdio property is a list of redirection targets for each of debuggee's stdio streams:
null(default) will connect the stream to a terminal (as specified by the terminal launch property)1."/some/path"will cause the stream to be redirected to the specified file, pipe or TTY device 2.
For example, "stdio": [null, null, "/tmp/my.log"] will connect stdin and stdout to a terminal, while sending
stderr to the a file.
- You may also use dictionary syntax:
"stdio": { "stdin": null, "stdout": null, "stderr": "/tmp/my.log" }. - A scalar value will configure all three streams identically:
"stdio": null.
1 On Windows debuggee is always launched in a new window, however stdio streams may still be redirected
as described above.
2 Use tty command inside a terminal window to find out its TTY device path.
When setting a function breakpoint, if the first character of the function name is '/',
the rest of the string is interpreted as a regular expression. This shall cause a breakpoint to
be set in every function matching the expression (the list of locations may be examined
using break list command).
When stepping into a compile unit which does not have a debug info, CodeLLDB will instead display
disassembly of the current function. This behavior may be controlled using LLDB: Show Disassembly
and LLDB: Toggle Disassembly commands. The former allows to choose between never,
auto (the default) and always, the latter toggles between auto and always.
When is disassembly view, the 'step over' and 'step into' debug actions will step by instruction instead of by line.
You may change the default display format of variables using the LLDB: Display Format command.
When evaluating expressions from Debug Console or in the 'Watch' view, you may also control
formatting of individual expressions by adding a suffix. For example $rax,x will format the value
as hex. Here's the full list:
| suffix | format |
|---|---|
| x | Hex |
| o | Octal |
| d | Decimal |
| u | Unsigned decimal |
| b | Binary |
| f | Float (reinterprets bits, no casting is done) |
| p | Pointer |
| s | C string |
| y | Bytes |
| Y | Bytes with ASCII |
VS Code UI does not provide access to all the bells and whistles of the underlying LLDB engine. To access advanced features
you may enter LLDB commands into Debug Console.
If you would like to evaluate an expression instead, prefix it with '?'.
Note that any debugger state changes that you make directly through LLDB commands will not be reflected in the UI and will not be persisted across debug sessions.
(New in v0.3.0) CodeLLDB leverages Python interpreter to evaluate expressions in Debug Console and the Watch view.
The debuggee variables are represented by a special wrapper class that implements
most of the usual Python operators on top of the view provided by LLDB variable formatters.
This means that things like indexing a std::vector with an integer, or comparing a std::string
to a string literal, just work!
Unlike regular Python scripts, though, all identifiers are interpreted as variable names. If you need
to use an actual Python keyword, prefix it with '@'. For example: [sqrt(x) @for x @in y].
You may also use the LLDB's built-in C++ expression evaluator. Just add an extra ? in front of
the expression (i.e. ?? in Debug Console and ? in Watch). Note, however, that C++ evaluator
ignores variable formatters, so you will have to operate on raw data structures.
CodeLLDB supports visualization of most common Rust data types:
- Built-in types: tuples, enums, arrays, array and string slices.
- Standard library types: Vec, String, CString, OSString.
To enable this feature, add "sourceLanguages": ["rust"] into your launch configuration.
Note: There is a known incompatibility of debug info emitted by rustc and LLDB 3.8:
you won't be able to step through code or inspect variables if you have this version.
The workaround is to use either LLDB 3.7 or 3.9. On OSX, LLDB shipped with Xcode 8 is known to
have this problem fixed.
On Debian-derived distros (e.g. Ubuntu), run sudo apt-get install python-lldb-x.y, where x.y is the LLDB version.
You may need to create symlinks to lldb and lldb-server manually.
See this page for installing nightlies.
- Download and install XCode.
- Install XCode Command Line Tools by running
xcode-select --install
No binary downloads are available at this time. You are gonna have to build your own. Sorry :(
- Bug fixes.
- Variable visualizers for Rust.
- New expression evaluator.
- Bug fixes.
- Bug fixes.
- Added 'terminal' launch config option. '*' in stdio config now behaves identically to null.
- Moved static variables out to their own scope.
- Disassembly in symbolless locations should work now.
- Resume debuggee after attach, unless stopOnEntry is true.
- Added disassembly view.
- Added variable formatting.
- Added support for setting variable values (primitive types only).
- Added regex breakpoints.
- Infer
.exetarget extension on Windows. argsmay now be a string.
First released version.