Skip to content

codelldb

Launch CodeLLDB to debug rust code.

Usage

Tip

This package only depends on the Python standard library, so you can integrate it freely.

Configuring CodeLLDB rpc server

Please refer to the CodeLLDB documentation to set up the rpc server, and add the following content to .vscode/settings.json:

{
  "lldb.rpcServer": {
    "host": "localhost",
    "port": 9552,
    "token": "secret",
  }
}

Launching the CodeLLDB debugger from Python

from codelldb import debug

if True:  # Replace with your condition to debug
    debug(
        host="localhost",
        port=9552,
        token="secret",
    )

Functions:

Name Description
debug

Launch CodeLLDB to debug rust code.

__all__ module-attribute 

__all__ = ['debug']

DebugError

Bases: Exception

debug 

debug(host: str, port: int, token: Optional[str] = None) -> None

Launch CodeLLDB to debug rust code.

Raises:

Type Description
DebugError

Failed to launch CodeLLDB.
Source code in python/codelldb/src/codelldb/__init__.py 
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def debug(host: str, port: int, token: Optional[str] = None) -> None:
    """Launch CodeLLDB to debug rust code.

    Raises:
        DebugError: Failed to launch CodeLLDB.
    """
    token_data = f"token: {token}" if token else ""
    # See: <https://github.com/vadimcn/codelldb/blob/v1.10.0/MANUAL.md#rpc-server>
    # Line-oriented YAML Syntax: <https://github.com/vadimcn/codelldb/blob/v1.10.0/MANUAL.md#debugging-externally-launched-code>
    # Arg: <https://github.com/vadimcn/codelldb/blob/v1.10.0/MANUAL.md#attaching-to-a-running-process>
    rpc_data = dedent(f"""\
        name: "CodeLLDB: Attach to Process"
        type: "lldb"
        request: "attach"
        pid: {getpid()}
        sourceLanguages:
            - rust
            - c
            - cpp
        {token_data}
    """)

    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        s.connect((host, port))

        s.sendall(rpc_data.encode("utf-8"))

        s.shutdown(socket.SHUT_WR)

        response = s.recv(1024)

        if not response:
            raise DebugError(
                "Failed to get response from lldb rpc server, "
                "maybe the rpc `token` is not correct."
            )

        try:
            response = json.loads(response)
            assert isinstance(response, dict)
        except Exception as e:
            raise DebugError(
                f"Failed to parse response from lldb rpc server: {response}"
            ) from e

        if response.get("success") is not True:  # pyright: ignore[reportUnknownMemberType]
            raise DebugError(
                f"Seems like lldb rpc server failed to attach to the process: {response}"
            )