8000 gh-89480: Document the gdb helpers by pablogsal · Pull Request #115657 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

gh-89480: Document the gdb helpers #115657

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Feb 23, 2024
Merged

gh-89480: Document the gdb helpers #115657

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
9fcccce
gh-89480: Document the gdb helpers
pablogsal Feb 19, 2024
bb74f8c
Update info; remove stuff specific to CPython internals
encukou Feb 19, 2024
4639810
Another editing pass
encukou Feb 20, 2024
8acd7a3
Apply suggestions from code review
encukou Feb 20, 2024
deb10f1
Apply suggestions from code review
encukou Feb 21, 2024
c0fc1ac
Rewordings, heading fixes
encukou Feb 21, 2024
e646760
Rewrite the introduction based on Carol's comment
encukou Feb 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Rewordings, heading fixes
  • Loading branch information
@encukou
encukou committed Feb 21, 2024
commit c0fc1ac61d2336a551f4a4c59825bd315b7644fb
34 changes: 20 additions & 14 deletions Doc/howto/gdb_helpers.rst
View file 8000
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,26 @@
.. _gdb:

===========
GDB support
===========
=========================================================
Debugging C API extensions and CPython Internals with GDB
=========================================================

.. highlight:: none

If you experience low-level problems such as crashes or deadlocks
(e.g. when debugging extensions or tinkering with parts of CPython
which are written in C), it can be convenient to use a low-level
If you experience low-level problems such as crashes or deadlocks,
especially when debugging extensions or tinkering with parts of CPython
which are written in C, it can be convenient to use a low-level
debugger such as GDB in order to diagnose and fix the issue.
By default, however, GDB (or any of its front-ends) doesn't know about
high-level information specific to the CPython interpreter, such as which
Python function is currently executing, or what type or value has a given
Python object represented by a standard ``PyObject *`` pointer.
We hereafter present two ways to overcome this limitation.
This guide introduces an extenstion that provides this information to GDB.

This guide assumes you are familiar with GDB, and focuses on Python-specific
The guide assumes you are familiar with GDB, and focuses on Python-specific
details.
It is a consolidation of guidance from the CPython
`devguide <https://devguide.python.org>`_ and the
`Python wiki <https://wiki.python.org/moin/DebuggingWithGdb>`_


Prerequisites
Expand All @@ -36,8 +39,8 @@ not at all. Below, we include tips for a few common systems as examples.
Note that even if the instructions match your system, they might be outdated.


Python built from source
------------------------
Setup with Python built from source
-----------------------------------

When you build CPython from source, debugging information should be available,
and the build should add a ``python-gdb.py`` file to the root directory of
Expand All @@ -58,8 +61,8 @@ with instructions on how to do this.
You can also add multiple paths, separated by ``:``.


Linux distros
-------------
Setup for Python from a Linux distro
------------------------------------

Most Linux systems provide debug information for the system Python
in a package called ``python-debuginfo``, ``python-dbg`` or similar.
Expand All @@ -84,8 +87,8 @@ However, this will not install the ``python-gdb.py`` extension;
you generally do need to install the debug info package separately.


Debug build and Development mode
================================
Using the Debug build and Development mode
==========================================

For easier debugging, you might want to:

Expand All @@ -102,6 +105,9 @@ make the process easier.
Using the ``python-gdb`` extension
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems to be the actual how-to.

You could also add a short introductory paragraph like "After installing the dependencies, you can now use the `python-gdb extension to ...".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous section tells you how to set things up, this tessl you how to use it :)

==================================

When the extension is loaded, it provides two main features:
pretty printers for Python values, and additional commands.

Pretty-printers
---------------

Expand Down
0