DOCSEARCHbyAlgolia
Submit Docs

CodeLLDB Documentation

repository·master·Indexed 25 days ago

https://github.com/vadimcn/codelldb

A high-performance debugger extension primarily for VS Code, optimized for C++ and Rust. It provides advanced visualization, Python scripting, and support for multiple architectures including AArch64, ARM, AVR, MSP430, RISCV, and X86. The extension supports various compiled languages such as Ada, Fortran, Kotlin Native, Nim, Objective-C, Pascal, Swift, and Zig, and includes features like conditional breakpoints, memory views, and remote debugging for embedded systems.

Tokens
17.5K
Snippets
32
Records
125
Agent score
85%

What's inside CodeLLDB

  1. Overview of CodeLLDB features

    master

    CodeLLDB is a debugger extension providing advanced debugging capabilities including:

    • Breakpoints: Conditional breakpoints, function breakpoints, logpoints, hardware data access breakpoints (watchpoints), and caller exclusion.
    • Views: Disassembly view with instruction-level stepping, Memory view, Loaded modules view, and HTML rendering for advanced visualizations.
    • Execution: Launch debuggee in integrated or external terminals, Step Into Targets, and Reverse debugging (experimental, requires compatible backend).
    • Scripting: Python scripting support.
    • Configuration: Workspace-level defaults for launch configurations and Remote debugging support.

  2. Supported languages in CodeLLDB

    master

    CodeLLDB is primarily optimized for C++ and Rust, featuring built-in visualizers for standard library types like vectors, strings, and maps.

    It is also compatible with other compiled languages that generate compatible debugging information, including:

    • Ada
    • Fortran
    • Kotlin Native
    • Nim
    • Objective-C
    • Pascal
    • Swift
    • Zig

  3. Connect to an lldb-server agent for remote debugging

    master

    To debug a process on a remote machine using lldb-server, follow these steps:

    1. On the remote machine, run: lldb-server platform --server --listen *:<port>
    2. In your local VS Code launch.json, create a configuration that selects the platform and connects to the remote host.

    Note: The executable specified in the program property will be automatically copied to the lldb-server current directory on the remote machine. If you need to perform additional remote setup (like creating directories), use the preRunCommands sequence with platform commands like platform mkdir or platform put-file.

    {
    "name": "Remote launch",
    "type": "lldb",
    "request": "launch",
    "program": "${workspaceFolder}/build/debuggee",
    "initCommands": [
        "platform select <platform>", // e.g., 'remote-linux', 'remote-macosx'
        "platform connect connect://<remote_host>:<port>",
    ],
    "env": {
        "PATH": "..."
    }
}

  4. Enable Rust Language Support

    master

    To enable LLDB data formatters provided by the Rust toolchain, add "sourceLanguages": ["rust"] to your launch configuration.

    You can also override the toolchain or sysroot using these settings:

    • lldb.script.lang.rust.toolchain: Override toolchain name (e.g., beta).
    • lldb.script.lang.rust.sysroot: Set toolchain sysroot directly (e.g., /home/user/.rustup/toolchains/beta-x86_64-unknown-linux-gnu).

  5. Use Cargo support for debugging Rust projects

    master

    CodeLLDB has built-in support for Cargo workspaces, allowing you to debug targets without manually configuring binary paths. To use this, replace the program property in your VSCode launch configuration with a cargo object or array.

    When using the object syntax, you can specify arguments, environment variables, the working directory, and problem matchers. Arguments provided in the top-level args array of the launch configuration will be appended to the arguments passed to the debug target by Cargo.

    {
    "type": "lldb",
    "request": "launch",
    "cargo": {
        "args": ["test", "foo", "--", "--test-threads=3"],
        "env": { "RUSTFLAGS": "-Clinker=ld.mold" },
        "cwd": "${workspaceFolder}",
        "problemMatcher": "$rustc"
    },
    "args": ["--test=test1"]
}

    For a shorter version providing only Cargo arguments:

    {
    "type": "lldb",
    "request": "launch",
    "cargo": ["test", "foo", "--", "--test-threads=3", "--test=test1"]
}

  6. Start debugging via VSCode URLs

    master

    You can trigger debugging sessions from outside VS Code using specific URI schemes. These are useful for attaching a debugger to a process that is currently running (e.g., a build script or a test runner).

    Supported URL Formats

    1. By Configuration Name: vscode://vadimcn.vscode-lldb/launch?name=<configuration name>,[folder=<path>]
    2. By Command Line: vscode://vadimcn.vscode-lldb/launch/command?<env>=<val>&<command-line>
    3. By YAML Config: vscode://vadimcn.vscode-lldb/launch/config?<yaml>

    Note: All URLs must be URI encoded. Use code --open-url "<uri>" to invoke them via the CLI.

  7. Build CodeLLDB targets

    master

    Use make within the build directory to build specific components. Common targets include:

    • adapter: Builds the debug adapter.
    • extension: Builds the VSCode extension.
    • debuggee: Builds the debuggee subproject (used for testing).
    • tests: Builds extension tests.
    • vsix_bootstrap: Builds a VSIX package containing only the VSCode extension.
    • vsix_full: Builds a VSIX package including all required native binaries for the current platform.
    • dev_debugging: Builds the extension, adapter, and debuggee needed to debug the extension itself. After building, run code --extensionDevelopmentPath=${workspaceFolder}/build to launch.
    cd build
make ${target}

  8. Use Regex Breakpoints

    master
    Prefix a function name with /re to create a regular expression breakpoint. This will set a breakpoint in every function that matches the expression. You can verify the created locations using the break list command.

  9. Configure the CMake build system

    master

    Create a build directory in the project root and run cmake. You must provide a toolchain file to avoid linker errors and specify the path to the LLDB package.

    Platform-specific setup:

    • Windows: Use the "x64 Native Tools Command Prompt" to ensure the MSVC environment is correctly configured.
    • macOS: It is recommended to start a new shell using xcrun --sdk macosx zsh.

    Note on LLDB package: The ${path to LLDB package} should point to a zip archive containing the subset of LLDB files required at runtime. Pre-built packages are available on the llvm-project releases.

    cd codelldb
mkdir build
cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchain-x86_64-linux-gnu.cmake -DLLDB_PACKAGE=${path to LLDB package}

  10. Attach to a running process

    master

    You can attach the debugger to an existing process using the attach request.

    Configuration Attributes

    • program (string): Path to the executable on the host machine. Equivalent to target create <program>.
    • pid (number): The process ID to attach to. If omitted, the debugger attempts to find a running instance of the program. You can use ${command:pickProcess} or ${command:pickMyProcess} for interactive selection.
    • stopOnEntry (boolean): If true, stops the debuggee immediately after attaching.
    • waitFor (boolean): If true, waits for the process to launch.

    OS Restrictions

    On some systems (e.g., many Linux distributions), the ptrace syscall is restricted by default. You may need to adjust system settings to allow attaching to processes.

    {
    "name": "Pick Process Attach",
    "type": "lldb",
    "request": "attach",
    "pid": "${command:pickProcess}"
}

  12. Configure an alternate Liblldb backend

    master

    If you want to use a custom LLDB build (e.g., for Swift-specific extensions), you can point CodeLLDB to a different liblldb shared library.

    1. Use the Use Alternate Backend... command in VSCode to automatically locate the library from an lldb executable.
    2. Or, manually set the lldb.library setting to the path of the shared library:
      • Linux: $LLDB_INSTALL_ROOT/lib/liblldb.so.<version>
      • MacOS: $LLDB_FRAMEWORK/LLDB (framework) or $LLDB_INSTALL_ROOT/lib/liblldb.<version>.dylib
      • Windows: $LLDB_INSTALL_ROOT/bin/liblldb.dll