{"id":17670395,"url":"https://github.com/malor/cpython-lldb","last_synced_at":"2025-04-05T03:05:58.677Z","repository":{"id":34277033,"uuid":"38164727","full_name":"malor/cpython-lldb","owner":"malor","description":"LLDB extension for debugging Python programs","archived":false,"fork":false,"pushed_at":"2024-11-18T08:05:06.000Z","size":203,"stargazers_count":84,"open_issues_count":2,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-29T02:04:40.987Z","etag":null,"topics":["cpython","debugging","lldb","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/malor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-27T15:22:03.000Z","updated_at":"2025-03-26T16:04:47.000Z","dependencies_parsed_at":"2024-04-01T20:46:56.086Z","dependency_job_id":"5ec12d6f-4c0b-412f-a908-c2074ba796fa","html_url":"https://github.com/malor/cpython-lldb","commit_stats":{"total_commits":95,"total_committers":4,"mean_commits":23.75,"dds":0.08421052631578951,"last_synced_commit":"a3c56aec1a9e366788fc959488a7a96a0d238211"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malor%2Fcpython-lldb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malor%2Fcpython-lldb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malor%2Fcpython-lldb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malor%2Fcpython-lldb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/malor","download_url":"https://codeload.github.com/malor/cpython-lldb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280262,"owners_count":20912967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpython","debugging","lldb","python"],"created_at":"2024-10-24T01:42:38.719Z","updated_at":"2025-04-05T03:05:58.655Z","avatar_url":"https://github.com/malor.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Overview\n========\n\n![build status](https://github.com/malor/cpython-lldb/actions/workflows/tests.yml/badge.svg)\n\n`cpython_lldb` is an LLDB extension for debugging Python programs.\n\nIt can be useful for troubleshooting stuck threads and crashes in the interpreter\nor external libraries. Unlike most Python debuggers, LLDB allows attaching to a\nrunning process without instrumenting it in advance, as well as loading a process\ncoredump to perform an offline (or post-mortem) analysis of a problem.\n\nWhen analyzing the state of a Python process, normally you would only have\naccess to *interpreter-level* information: most variables would be of type\n`PyObject*`, and stack traces would only contain CPython internal calls and\ncalls to library functions. Unless you are a CPython developer troubleshooting\nthe interpreter implementation, that is typically not very useful. This extension,\nhowever, allows you to extract *application-level* information about execution of\na program: print the values of variables, list the source code, display Python\nstack traces, etc.\n\nWhile CPython already provides a similar extension for gdb [out of the box](\nhttps://github.com/python/cpython/blob/master/Tools/gdb/libpython.py),\nLLDB might be the debugger of choice on some operating systems, e.g.\non Mac OS.\n\nThis extension requires CPython to be built with debugging symbols enabled, which\nis not the case for some Linux distros (notably Arch Linux). CPython official\n[Docker images](https://hub.docker.com/_/python) are known to work correctly, as they\nare used for integration testing.\n\n\nFeatures\n========\n\n`cpython_lldb` targets CPython 3.5+ and supports the following features:\n\n* pretty-printing of built-in types (int, bool, float, bytes, str, none, tuple, list, set, frozenset, dict)\n* printing of Python-level stack traces\n* printing of local variables\n* listing the source code\n* walking up and down the Python call stack\n\nInstallation\n============\n\nIf your version of LLDB is linked against system libpython, it's recommended\nthat you install the extension to the user site packages directory and allow\nit to be loaded automatically on start of a new LLDB session:\n\n```shell\n$ python -m pip install --user cpython-lldb\n$ echo \"command script import cpython_lldb\" \u003e\u003e ~/.lldbinit\n$ chmod +x ~/.lldbinit\n```\n\nAlternatively, you can install the extension to some other location and tell LLDB\nto load it from there, e.g. ~/.lldb:\n\n```shell\n$ mkdir -p ~/.lldb/cpython_lldb\n$ python -m pip install --target ~/.lldb/cpython_lldb cpython-lldb\n$ echo \"command script import ~/.lldb/cpython_lldb/cpython_lldb.py\" \u003e\u003e ~/.lldbinit\n$ chmod +x ~/.lldbinit\n```\n\nMacOS\n-----\nLLDB bundled with MacOS is linked with the system version of CPython which may not even\nbe in your PATH. To locate the right version of the interpreter, use:\n```shell\n$ lldb --print-script-interpreter-info\n```\nThe output of the command above is a JSON with the following structure:\n```\n{\n  \"executable\":\"/Library/.../Python3.framework/Versions/3.9/bin/python3\",\n  \"language\":\"python\",\n  \"lldb-pythonpath\":\"/Library/.../LLDB.framework/Resources/Python\",\n  \"prefix\":\"/Library/.../Python3.framework/Versions/3.9\"\n}\n```\nWhere the value for \"executable\" is the CPython version that should be used to install\n`cpython_lldb` for LLDB to be able to successfully import the script:\n```shell\n$(lldb --print-script-interpreter-info | jq -r .executable) -m pip install cpython_lldb\n```\n\nUsage\n=====\n\nStart a new LLDB session:\n\n```shell\n$ lldb /usr/bin/python\n```\n\nor attach to an existing CPython process:\n\n```shell\n$ lldb /usr/bin/python -p $PID\n```\n\nIf you've followed the installation steps, the extension will now be automatically\nloaded on start of a new LLDB session and register some Python-specific commands:\n\n```\n(lldb) help\n...\nCurrent user-defined commands:\n  py-bt     -- Print a Python-level call trace of the selected thread.\n  py-down   -- Select a newer Python stack frame.\n  py-list   -- List the source code of the Python module that is currently being executed.\n  py-locals -- Print the values of local variables in the selected Python frame.\n  py-up     -- Select an older Python stack frame.\nFor more information on any command, type 'help \u003ccommand-name\u003e'.\n```\n\nPretty-printing\n---------------\n\nAll known `PyObject`'s (i.e. built-in types) are automatically pretty-printed\nwhen encountered, as if you tried to get a `repr()` of something in Python REPL,\ne.g.:\n\n```\n(lldb) frame variable v\n(PyObject *) v = 0x0000000100793c00 42\n(lldb) p v-\u003eob_type-\u003etp_name\n(const char *) $3 = 0x000000010017d42a \"int\"\n```\n\nStack traces\n------------\n\nUse `py-bt` to print a full application-level stack trace of the current thread, e.g.:\n\n```\n(lldb) py-bt\nTraceback (most recent call last):\n  File \"test.py\", line 15, in \u003cmodule\u003e\n    fc()\n  File \"test.py\", line 12, in fc\n    fb()\n  File \"test.py\", line 8, in fb\n    fa()\n  File \"test.py\", line 2, in fa\n    abs(1)\n```\n\nWalking up and down the call stack\n----------------------------------\n\nUse `py-up` and `py-down` to select an older or a newer Python call stack frame, e.g.:\n\n```\n(lldb) py-up\n  File \"/Users/malor/src/cpython/test.py\", line 6, in cb\n    self.ca()\n(lldb) py-up\n  File \"/Users/malor/src/cpython/test.py\", line 20, in f_static\n    c.cb()\n(lldb) py-down\n  File \"/Users/malor/src/cpython/test.py\", line 6, in cb\n    self.ca()\n(lldb) py-down\n  File \"/Users/malor/src/cpython/test.py\", line 3, in ca\n    abs(1)\n(lldb) py-down\n*** Newest frame\n```\n\nPrinting of local variables\n---------------------------\n\nUse `py-locals` to print the values of local variables in the selected frame:\n\n```\n(lldb) py-locals\na = 42\nargs = (1, 2, 3)\nb = [1, u'hello', u'\\\\u0442\\\\u0435\\\\u0441\\\\u0442']\nc = ([1], 2, [[3]])\nd = u'test'\ne = {u'a': -1, u'b': 0, u'c': 1}\neggs = 42\nkwargs = {u'foo': 'spam'}\nspam = u'foobar'\n```\n\nListing the source code\n-----------------------\n\nUse `py-list` to list the source code that is currently being executed in the selected\nPython frame, e.g.:\n\n```\n(lldb) py-list\n    1    SOME_CONST = 42\n    2\n    3\n    4    def fa():\n   \u003e5        abs(1)\n    6        return 1\n    7\n    8\n    9    def fb():\n   10        1 + 1\n```\n\nThe command also accepts optional `start` and `end` arguments that allow to\nlist the source code within a specific range of lines, e.g.:\n\n```\n(lldb) py-list 4\n    4    def fa():\n   \u003e5        abs(1)\n    6        return 1\n    7\n    8\n    9    def fb():\n   10        1 + 1\n   11        fa()\n   12\n   13\n   14    def fc():\n```\n\nor:\n\n```\n(lldb) py-list 4 11\n    4    def fa():\n   \u003e5        abs(1)\n    6        return 1\n    7\n    8\n    9    def fb():\n   10        1 + 1\n   11        fa()\n```\n\nPotential issues and how to solve them\n======================================\n\nCPython 2.7.x\n-------------\n\nCPython 2.7.x is not supported. There are currently no plans to support it in the future.\n\nMissing debugging symbols\n-------------------------\n\nCPython debugging symbols are required. You can check if they are available as follows:\n\n```shell\n$ lldb /usr/bin/python\n$ (lldb) type lookup PyObject\n```\n\nIf debugging symbols are not available, you'll see something like:\n\n```shell\nno type was found matching 'PyObject'\n```\n\nSome Linux distros ship debugging symbols separately. To fix the problem on Debian / Ubuntu do:\n\n```shell\n$ sudo apt-get install python-dbg\n```\n\non CentOS / Fedora / RHEL do:\n\n```shell\n$ sudo yum install python-debuginfo\n```\n\nOther distros, like Arch Linux, do not provide debugging symbols in the package repos. In this case,\nyou would need to build CPython from source. Please refer to the official [CPython](https://devguide.python.org/setup/#compiling)\nor [distro](https://wiki.archlinux.org/index.php/Debug_-_Getting_Traces) documentation for instructions.\n\nAlternatively, you can use the official CPython [Docker images](https://hub.docker.com/_/python).\n\n\nBroken LLDB scripting\n---------------------\n\nSome Linux distros (notably Debian Stretch) are shipped with a version of LLDB in which using Python scripting\ntriggers a segmentation fault when executing any non-trivial operation:\n\n```shell\n$ lldb\n(lldb) script\nPython Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.\n\u003e\u003e\u003e import io\n\u003e\u003e\u003e Segmentation fault\n```\n\nIt's recommended that you use the latest LLDB release from the official [APT repo](https://apt.llvm.org/) instead\nof the one shipped with your distro.\n\nSee this [page](https://github.com/vadimcn/vscode-lldb/wiki/Troubleshooting) for advice on troubleshooting LLDB.\n\nDevelopment\n===========\n\nRunning tests\n-------------\n\nTests currently require `make` and `docker` to be installed.\n\nTo run the tests against the *latest* released CPython version, do:\n\n```\n$ make test\n```\n\nTo run the tests against a specific CPython (or LLDB) version, do:\n\n```\n$ PY_VERSION=X.Y LLDB_VERSION=Z make test\n```\n\nSupported CPython versions are:\n* `3.7`\n* `3.8`\n* `3.9`\n* `3.10`\n\nSupported LLDB versions:\n* `9`\n* `10`\n* `11`\n* `15`\n* `16`\n\nContributors\n============\n\nKudos to everyone who have contributed to this project!\n\n* Marco Neumann\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmalor%2Fcpython-lldb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmalor%2Fcpython-lldb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmalor%2Fcpython-lldb/lists"}