{"id":18812152,"url":"https://github.com/drorspei/py-gdb-tools","last_synced_at":"2025-09-12T07:35:03.691Z","repository":{"id":132912264,"uuid":"139978571","full_name":"drorspei/py-gdb-tools","owner":"drorspei","description":"Tools for interacting with gdb from another python process","archived":false,"fork":false,"pushed_at":"2018-10-19T14:54:52.000Z","size":2047,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-22T03:38:42.542Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/drorspei.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":"2018-07-06T11:53:22.000Z","updated_at":"2018-10-19T14:54:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"638c8641-ce71-4825-a3ea-3ae489b5af6f","html_url":"https://github.com/drorspei/py-gdb-tools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/drorspei/py-gdb-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drorspei%2Fpy-gdb-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drorspei%2Fpy-gdb-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drorspei%2Fpy-gdb-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drorspei%2Fpy-gdb-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drorspei","download_url":"https://codeload.github.com/drorspei/py-gdb-tools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drorspei%2Fpy-gdb-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274776978,"owners_count":25347641,"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","status":"online","status_checked_at":"2025-09-12T02:00:09.324Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-07T23:29:57.850Z","updated_at":"2025-09-12T07:35:03.644Z","avatar_url":"https://github.com/drorspei.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# py-gdb-tools\nA library for extracting values from gdb - in a separate python process.\n\nCurrently you can extract `std::vector\u003cdouble\u003e` or `Eigen::Matrix\u003cdouble\u003e`, and int like primitives. Later editions will add support for all primitives and combinations of stl classes and primitives.\n\nExtracting can mean one of two things: either sending the value over to a running python process, or saving to a file that can be read later with python. The first option is useful for dynamic debugging - get to a breakpoint, send the value over to python, analyze it a bit, say, with a plot, then find your bug. The second option is useful for letting the program run for a while, saving values to a file as it goes, then reading that file and looking at everything somehow, say, with a big plot. Sometime soon I'll write a similar feature for pdb (\"python's gdb\"), and then you could automatically compare values from a c++ process with values from a python process.\n\nIn the rest of this readme I explain how to send values over to python, how to save to and read from a file, how to save automatically without stopping at the breakpoints, and how to send automatically to a running python process. There are also explanations of how to send single values with old syntax that I was using as I was writing this library, with a nifty screen cast gif, though these are less relevant now.\n\nThe automatic file saving approach allows you to gather logs of a run without instrumenting your program. The main trade-off here is between the performance hit of running under gdb, and the time it would take to write logging into your code. For certain application, such as comparing c++ code with python code (which I do often), the performance of the run is not an issue, while adding logging is quite the hassle. py-gdb-tools offers a quick solution for big debugging jobs.\n\n## Getting vector/Eigen::Matrix values from gdb in python:\n\nRunning `py_gdb_tools_gdb.py` (with `source`) starts a server in the background that listens to requests for values of vectors/Eigen matrices. Here's how to use it:\n\n1. Run gdb on your process,\n2. enter `source /path/to/py_gdb_tools_gdb.py`,\n3. set a breakpoint somewhere,\n4. run the process and reach the breakpoint,\n5. run python and import/execfile `py_gdb_tools_python.py`,\n6. enter in python:\n\n```\npgt = PgtPythonSide().start()\nval = pgt.get('symbol_name')\n```\n\n7. that's it, you have a numpy array in `val`.\n\n## Saving values to a file:\n\npy-gdb-tools adds the command `pgt_var_to_file` to your gdb which lets you save a variable to a file and later read it from python using `read_pgt_file`:\n\n1. Run gdb and source `py_gdb_tools_gdb.py`,\n2. enter `pgt_var_to_file path/to/file.cpp:lineno symbol_name /path/to/output/file`,\n3. run program,\n4. in python use `read_pgt_file('/path/to/output/file')`\n\nNote that `read_pgt_file` is a generator that yields pairs of variable names and associated data.\n\n## Automating saving values to a file:\n\nIt's also easy to create a script that will add breakpoints that save variables to a file. For example, say we want to debug `example.cpp` from the examples folder. We create a file `example.py` that contains the line\n\n    VarToFileBreakpoint('examples/example.cpp:6', 'v', '/tmp/example.pgt')\n\nNow we can run gdb, source `py_gdb_tools_gdb.py`, then source `examples/example.py`, and finally let gdb run. The program will run and exit normally, and we'll have a new file at `/tmp/example.pgt`. We can read the file using `read_pgt_file` from `py_gdb_tools_python.py`.\n\n## Automating sending values to a server:\n\nSimilarly to saving to a file, you can use `VarToServerBreakpoint` in a python script to automate sending values to a listening server.\n\n## Automatically loading py-gdb-tools in all of your gdb session:\n\nOn linux (or at least on my ubuntu) there's a file that gdb runs every time, and it is located at `/etc/gdb/gdbinit` (on some machines I've worked on it was at `/etc/gdb/.gdbinit`). You can add the following line to the file, and py-gdb-tools will be loaded automatically in all of your gdb sessions:\n\n    source /path/to/py_gdb_tools_gdb.py\n\n## Sending a single vector/Eigen::Matrix from gdb to python:\n\nThis was written before the gdb-side server option and might still be relevant in some cases.\n\n1. Run gdb with some process,\n2. enter in `source /path/to/py_gdb_tools_gdb.py`,\n3. in python load `py_gdb_tools_python.py` (say with `execfile` or `exec`),\n4. enter `vec = recv_double_vec()` in python,\n5. enter `send_double_vec symbol_name` in gdb,\n6. you should now have a variable called `vec` in python!\n\nSending a vector from gdb to python is helpful in case you want to plot the vector, do some analysis in the middle of debugging, or compare with other values.\n\nTo use a different port than the default of 50010, use `send_double_vec port=PORT symbol_name` in gdb and `vec = recv_double_vec(port=PORT)` in python.\n\n![Image](https://github.com/drorspei/py-gdb-tools/blob/master/examples/example.gif)\n\n## Sending many vectors/eigen matrices:\n\nThe following was also written before the gdb-side server option, so maybe not so relevant anymore.\n\nIf you're going to be sending many values, you can use the `PgtPythonSide` class on the python side. It listens in the background for incoming data, so you don't need to write `recv_double_vec` yourself:\n\n1. Run gdb with some process,\n2. enter in `source /path/to/py_gdb_tools_gdb.py`,\n3. in python load `py_gdb_tools_python.py` (say with `execfile` or `exec`),\n4. enter `pgt = PgtPythonSide().start()` in python,\n5. enter `send_double_vec symbol_name`,\n6. you can now access the variable using `pgt.received[-1]` or `pgt.vars['symbol_name']`\n\n### Requirements\n\nUm this is a bit awkward... Currently `py_gdb_tools_gdb.py` is written for python 3, and `py_gdb_tools_python.py` is written for python 2.7. This is because my gdb runs python 3, but I use python 2.7 at my work. This can easily be dealt with if the need arises.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrorspei%2Fpy-gdb-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrorspei%2Fpy-gdb-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrorspei%2Fpy-gdb-tools/lists"}