• DeveloperTips

List of requirements for patches

See ContributionChecklist.

GDB Internals documentation

GDB has an official InternalsManual.

Jeremy Bennett wrote Howto: Porting the GNU Debugger, which is a good source of information as well. It is primarily aimed at engineers who will port GDB to a new target for the first time, but contains an overview of GDB Internals that is of general interest.

Editing configure.ac

After editing gdb/configure.ac, you need to regenerate gdb/configure, gdb/config.in and gdb/aclocal.m4:

$ pwd
/path/to/binutils-gdb/gdb
$ autoreconf -vf

Please note:

• You need to install the correct versions of Autoconf (which provides autoreconf, autoconf and autoheader) and Automake (which provides aclocal). The correct versions are the ones mentioned in the README-maintainer-mode file in the top directory, and also at the beginning of gdb/aclocal.m4 and gdb/configure. Note that you should install these tools from upstream release tarballs, as distros often patch them. If you regenerate the files and get unrelated changes in the generated files, you're most likely using the wrong versions of the tools, or your distro's tools.

• Don't include the changes to these generated files in your patch when you post it to the mailing list. These files are big and unnecessary for code review.

Editing gdbarch.h/gdbarch.c

Don't. These are generated files. Edit gdbarch.py instead, and then run it.

See Internals Target-Architecture-Definition.

Updating GDB's import of gnulib

GDB now imports various modules from the gnulib project, located in gdb/gnulib. This import is used when building both GDB and GDBserver.

To facilitate the update of our import, a script called update-gnulib.sh has been created to automate the process. To run this script:

    % cd /path/to/gdb-sources/gdb/gnulib
    % ./update-gnulib.sh /path/to/gnulib-git-repository

When run without change, the new import should be identical to the previous one. This is actually a good test to perform before making any update to our import, to make sure that everything is correctly setup.

The script maintains the two key pieces of information from which the import is created as constants defined inside the script:

• GNULIB_COMMIT_SHA1 - which commit from the gnulib respository is to be used for the import;

• IMPORTED_GNULIB_MODULES - which modules to import from gnulib.

When updating the import, please only modify one element at a time. For instance, if you want to import a new module only defined in a later version of gnulib, please first update the import to use the newer commit as a first patch, and then update the import to include the new module as a second patch.

Setting up pre-commit

pre-commit is a tool that can hook into git to do some actions at certain stages of the git workflow (typically when the pre-commit hook is called, hence the name). There is a .pre-commit-config.yaml file at the root of the repository describing some actions (which are not described here, since they are subject to change).

Installing pre-commit:

• Install the pre-commit tool the way you prefer, perhaps using your OS' package manager, or with pip install pre-commit.

• To test it, go to the binutils-gdb repository root and run pre-commit.

• If the used version of python is older than required, this may fail, but that can be fixed by using a more recent python in a python virtual environment. Make sure to re-install the pre-commit hooks, because they hardcode the python version.

Installing the pre-commit hooks in .git/hooks:

• Go to the binutils-gdb repository root and run pre-commit install.

• To test it, run .git/hooks/pre-commit.

Periodically, maintainers can run pre-commit autoupdate to see if there are new versions of hooks available and push the changes to .pre-commit-config.yaml to the repo.

Usage example: at the time of writing, there is a single action, to run black on the gdb directory whenever a Python file is modified. When trying to git commit while a Python file is improperly formatted, you'll get something like:

$ git commit
black....................................................................Failed
- hook id: black
- files were modified by this hook

reformatted gdb/python/lib/gdb/dap/breakpoint.py

All done! ✨ 🍰 ✨
1 file reformatted.

It is possible to skip running hooks if needed with the SKIP environment variable.

Debugging gdbserver on uClinux / Linux with no MMU

GDB has issues with breakpoints set in gdbserver on !MMU targets. Ulrich Weigand has a tip to make it work:

Gdbserver uses a direct call to the Linux "clone" system call at startup,
and for some reason GDB gets really confused by this.

When I want to debug gdbserver, I generally simply comment out the call
to linux_test_for_tracefork in linux-nat.c:initialize_low to avoid this.

Writing testcases

See GDBTestcaseCookbook.

Finding Gnats bug entries in the Bugzilla database

If you ever had to find an old bug in the Bugzilla database, you probably stumbled upon this situation. There are some old entries from the now-retired Gnats database, which can be found by:

• Adding 7105 to the Gnats bug number;

• Search for "Converted from Gnats NNN", where NNN is the Gnats bug number.

• Use "gdb 123" Location with Mozilla bookmark keyword "gdb", URL "http://localhost/~user/cgi-bin/buggdb.php?id=%s" and install this file as "~/public_html/cgi-bin/buggdb.php".

git hash mentioned in Bugzilla or mailing list discussion not found?

GDB used CVS as its main CSV up until October 2013, when it moved to git. The current git repository shares no ancestry with the old git mirror. The old git mirror is still available. See GitMirrors.

Making admin changes to bugzilla

Sometimes there's a need to add a new component, or make other admin changes to gdb's bugzilla. Send requests to overseers@sourceware.org. Even gdb admins are not allowed admin access to this website (and those that have it work for Red Hat). Feel free to discuss requested changes on gdb@sourceware.org, but to put them into effect you have to talk to The Powers That Be.

You can also try #overseers on irc.freenode.net, but email is the official way.

Closing obsolete bugs

Bugzilla is (at least as of this writing) full of lots of old bugs that have too low a priority relative to everything else to put any time into. To improve the S/N ratio of bugs we do care about it's best to just close these old bugs out. The way to do this is to close them as RESOLVED/OBSOLETE. An example of this is here: https://sourceware.org/bugzilla/show_bug.cgi?id=8769

As for what the rules are that defines whether a bug falls into this category, good question.

Obviously build problems for gdb versions older than, say, 7.0, is pretty safe.

If possible (and relatively easy) you could try to reproduce the bug in git head, and if not reproducible, and if the gdb version in the bug report is older than 7.0, then the author thinks it's safe to close these out too.

Feel free to add comments to any PR asking whether the bug is old enough to close out. If such a question goes unanswered for a year, and the gdb version in the bug is older than, say, 7.0, then the author thinks it's safe to close these out too. A year may seem like a long time, but relative to how old some of the bugs are that need to be cleaned out, it's amply conservative and still useful.

The author thinks we could be slightly more aggressive with closing some of the older bugs. The above is intended to be a start.

Regenerating CGEN files

Here are the steps to regenerating the cgen files. Cgen is a tool for describing a cpu and then generating the opcodes and simulator files from that description.

https://sourceware.org/cgen/

• Put guile 1.8.8 in $PATH.

ftp://ftp.gnu.org/pub/gnu/guile/guile-1.8.8.tar.gz

No special configure options are needed, just --prefix.

• Check out cgen.

bash$ cd /place/to/put/cgen
bash$ cvs -d :pserver:anoncvs@sourceware.org:/cvs/src co cgen

Make sure the build can find it.

bash$ ln -s $(pwd)/src/cgen $git/cgen

There's a TODO to be able to specify the path to cgen when configuring binutils,gdb. This step will go away, but until then.

• Apply this patch.

https://sourceware.org/ml/gdb-patches/2015-06/msg00395.html

This step will go away when some form of that patch is applied.

• Build all the sims.

Generated files that need regenerating will be, including the opcodes files.

bash$ cd $build
bash$ $git/configure --prefix=$(pwd)/rel \
    --enable-cgen-maint \
    --enable-targets=all \
    --enable-sim
bash$ make all-sim

Downloading and applying patches from the mailing list

If you want to apply a patch (or patch series) from the mailing list in your local development tree, you will first need to download it. If you already have the message in your email client, there is probably a way to export the message as a file. For instance, in Thunderbird, you can select one or more messages and hit ctrl-s to save them. Once this is done, do:

$ git am -3 <patch files...>

The -3 switch makes git use 3 way merge, which sometimes helps git figure things out if the patch doesn't apply cleanly (see the man page of git-am for more details).

It is also possible to download patches from our public-inbox instance. Click the "raw" link on a message, save it, and apply it with git am.

A handy way to grab longer series from public-inbox is to use b4. Configure this in your git repository:

$ git config b4.midmask https://inbox.sourceware.org/gdb-patches/%s
$ git config b4.linkmask https://inbox.sourceware.org/gdb-patches/%s
$ git config b4.searchmask https://inbox.sourceware.org/gdb-patches/all/?x=m&t=1&q=%s

Then, let's say you wanted to download this series of 12 patches, copy the Message-ID of any patch in the series (or the cover letter), and pass it to b4 am:

$ b4 am 20230511144832.17974-1-simon.marchi@efficios.com
Looking up https://inbox.sourceware.org/gdb-patches/20230511144832.17974-1-simon.marchi%40efficios.com
Grabbing thread from inbox.sourceware.org/gdb-patches/20230511144832.17974-1-simon.marchi%40efficios.com/t.mbox.gz
Analyzing 14 messages in the thread
Checking attestation on all messages, may take a moment...
---
  [PATCH 1/12] gdb: get gdbarch from syscall_catchpoint instead of location
  [PATCH 2/12] gdb: make some breakpoint methods use `this`
  [PATCH 3/12] gdb: constify breakpoint::print_it parameter
  [PATCH 4/12] gdb: add breakpoint "has locations" methods
  [PATCH 5/12] gdb: add breakpoint::first_loc methods
  [PATCH 6/12] gdbsupport: add missing increment/decrement operators to reference_to_pointer_iterator
  [PATCH 7/12] gdb: link breakpoint locations with intrusive_list
  [PATCH 8/12] gdb: remove bp_location_pointer_iterator
  [PATCH 9/12] gdb: link breakpoints with intrusive_list
  [PATCH 10/12] gdbsupport: make basic_safe_iterator::operator* return the same thing as underlying iterator
  [PATCH 11/12] gdbsupport: make filtered_iterator::operator* return the same thing as underlying iterator
  [PATCH 12/12] gdb: remove breakpoint_pointer_iterator
---
Total patches: 12
---
Cover: ./20230511_simon_marchi_use_intrusive_list_for_breakpoints_and_breakpoint_locations.cover
 Link: https://inbox.sourceware.org/gdb-patches/20230511144832.17974-1-simon.marchi@efficios.com
 Base: not specified
       git am ./20230511_simon_marchi_use_intrusive_list_for_breakpoints_and_breakpoint_locations.mbx    

All messages of the series are concatenated in that mbx (mbox) file, which you can apply:

$ git am -3 ./20230511_simon_marchi_use_intrusive_list_for_breakpoints_and_breakpoint_locations.mbx
Applying: gdb: get gdbarch from syscall_catchpoint instead of location
Applying: gdb: make some breakpoint methods use `this`
Applying: gdb: constify breakpoint::print_it parameter
Applying: gdb: add breakpoint "has locations" methods
Applying: gdb: add breakpoint::first_loc methods
Applying: gdbsupport: add missing increment/decrement operators to reference_to_pointer_iterator
Applying: gdb: link breakpoint locations with intrusive_list
Applying: gdb: remove bp_location_pointer_iterator
Applying: gdb: link breakpoints with intrusive_list
Applying: gdbsupport: make basic_safe_iterator::operator* return the same thing as underlying iterator
Applying: gdbsupport: make filtered_iterator::operator* return the same thing as underlying iterator
Applying: gdb: remove breakpoint_pointer_iterator        

For Thunderbird users, the Copy Message ID extension can be handy to quickly get the ID of a message.