Contributing to GDB

Quick access and useful resources for contributing to GDB.

Quick Access

Official Site:

• GDB: The GNU Project Debugger
  • GDB Mailing Lists
  • GDB Documentation

Documentation for Users:

• Debugging with GDB

Documentation for Contributors:

• GDB Wiki
  • Contribution Checklist
  • Internals
    • Internals Coding-Standards
      • GDB C/C++ Coding Standards
      • GDB Python Coding Standards
      • GDB Testsuite Coding Standards
  • Testing GDB
  • GDBTestcaseCookbook
  • FAQ

Git repo:

• sourceware.org Git
• Unofficial mirror on GitHub

Bug List:

• Sourceware Bugzilla – Components for gdb

Mailing List:

• sourceware.org Mailing Lists
• The Gdb-patches Archives

Sending Patch:

• git send-email with Gmail

Setting Up

Please setup a dedicated virtual machine for building and testing GDB. I recall that many test fails when running the test suite in docker. I’m not sure if it’s still the case.

Clone the Source Repo

Follow the guide on the GDB website:

git clone https://sourceware.org/git/binutils-gdb.git
cd binutils-gdb

Install Dependencies

Assuming you are using Debian/Ubuntu, install the dependencies following a guide for apt-get build-dep and the GDB BuildBot configuration guide:

sudo sed -i.bak 's/^# *deb-src/deb-src/g' /etc/apt/sources.list
sudo apt-get update
sudo apt-get -y build-dep gdb
sudo apt-get -y install texinfo flex bison
sudo apt-get -y install emacs

Build and Install

Follow the README of GDB:

# Assume current directory is in binutils-gdb
./configure
make -j8
# if OOM, reduce the number of workers, such as:
# make -j4

and install it:

sudo make install

To prevent future compilation errors, you can delete the build artifacts by undoing every modification after the last commit:

git reset --hard
git clean -d -x -f

Test

Follow the testing guide of GDB:

Running the entire test suite:

# Assume current directory is in binutils-gdb
make check -j8

Copy the test results under binutils-gdb to somewhere else:

gdb/testsuite/gdb.sum
gdb/testsuite/gdb.log

and delete the test results under binutils-gdb.

I suggest repeat the process of running the entire test suite and storing the test results 2 to 3 times. Since the test result is pretty noisy, having multiple test results enables you to observe the intrinsic test noise. The information of the intrinsic test noise can help a lot when testing your patch in the later steps.

Contributing

Create and checkout a Git branch with an arbitrary name.

Follow the contribution check list.

Test

Assume you now have a working patch and the corresponding test casea. Both of them are committed to the new Git branch.

First, make sure the unmodified GDB fails the test case, for example:

# Assume current directory is in binutils-gdb
cd gdb/testsuite
make check TESTS="gdb.base/break.exp"

Second, install the patched GDB:

# Assume current directory is in binutils-gdb
./configure
make -j8
sudo make install

and verify the patched GDB passes the test case:

# Assume current directory is in binutils-gdb
cd gdb/testsuite
make check TESTS="gdb.base/break.exp"

Finally, run the entire testsuite:

# Assume current directory is in binutils-gdb
make check -j8

Copy the test results under binutils-gdb to somewhere else:

gdb/testsuite/gdb.sum
gdb/testsuite/gdb.log

and delete the test results under binutils-gdb.

I suggest running the entire test suite at least twice, and compare with the test results of the unmodified GDB to make sure there are no regressions other than the intrinsic noises.

Sending an Email Patch

Fix the commit dates:

git rebase --ignore-date origin/master

Fix the author info:

git commit --amend --author="$YOUR_NAME <$YOUR_EMAIL>" --no-edit

You can submit the patch through git send-email with:

git send-email -1 -cc $YOUR_EMAIL

• You may want to append the base commit information by editing the email:

  base-commit: $COMMIT_ID`
  

• If you are submitting a new version of an existing patch, find the Message ID of the previous email by following this post and reply the email by adding the following option:

  --in-reply-to=$MESSAGE_ID
  

  and make sure to edit the title prefix of the patch from [PATCH] to [PATCH v2] or [PATCH v3] or etc.

• If you simply want to reply to the email, write the email content to ./msg and run git send-email without the -1 option and with the following option:

  --annotate msg
  

• After verifying you can successfully receive the email, you can now send it to the mailing list by adding the following option:

  --to "gdb-patches@sourceware.org"
  

  or adding more receivers with:

  --to "$NAME <$EMAIL>"
  

If you are submitting a multi-part patch, you may consider something like the following:

git send-email -3 --compose -cc $YOUR_EMAIL

In most cases, you don’t want to submit a multi-part patch. It is totally fine to store the patch and the test case in the same commit.