Project status information has moved to its own page.
Crashpad is a Chromium project. Most of its development practices follow Chromium’s. In order to function on its own in other projects, Crashpad uses mini_chromium, a small, self-contained library that provides many of Chromium’s useful low-level base routines. mini_chromium’s README provides more detail.
To develop Crashpad, the following tools are necessary, and must be present in the $PATH
environment variable:
build-essential
, zlib1g-dev
, and any one of the libcurl4-*-dev
packages such as libcurl4-openssl-dev
should suffice.The main source code repository is a Git repository hosted at https://chromium.googlesource.com/crashpad/crashpad. Although it is possible to check out this repository directly with git clone
, Crashpad’s dependencies are managed by gclient
instead of Git submodules, so to work on Crashpad, it is best to use fetch
to get the source code.
fetch
and gclient
are part of the depot_tools. There’s no need to install them separately.
$ mkdir ~/crashpad $ cd ~/crashpad $ fetch crashpad
fetch crashpad
performs the initial git clone
and gclient sync
, establishing a fully-functional local checkout.
$ cd ~/crashpad/crashpad $ git pull -r $ gclient sync
On Windows, Mac, Linux, and Fuchsia, Crashpad uses GN to generate Ninja build files. For example,
$ cd ~/crashpad/crashpad $ gn gen out/Default $ ninja -C out/Default
You can then use gn args out/Default
or edit out/Default/args.gn
to configure the build, for example things like is_debug=true
or target_cpu="x86"
.
GN and Ninja are part of the depot_tools. There’s no need to install them separately.
In order to instruct gclient to download the Fuchsia SDK, you need to add the following to ~/crashpad/.gclient
:
target_os=["fuchsia"]
If you're using this tree to develop for multiple targets, you can also add other entries to the the list (e.g. target_os=["fuchsia", "mac"]
).
To pull and use Crashpad's version of clang and sysroot, make the following changes.
Add the following to ~/crashpad/.gclient
.
"custom_vars": { "pull_linux_clang": True },
Add these args to out/Default/args.gn
.
clang_path = "//third_party/linux/clang/linux-amd64" target_sysroot = "//third_party/linux/sysroot"
This build relies on cross-compilation. It’s possible to develop Crashpad for Android on any platform that the Android NDK (Native Development Kit) runs on.
If it’s not already present on your system, download the NDK package for your system and expand it to a suitable location. These instructions assume that it’s been expanded to ~/android-ndk-r21b
.
Note that Chrome uses Android API level 21 for both 64-bit platforms and 32-bit platforms. See Chrome’s build/config/android/config.gni
which sets android32_ndk_api_level
and android64_ndk_api_level
.
Set these gn args
target_os = "android" android_ndk_root = ~/android-ndk-r21b android_api_level = 21
Crashpad uses Google Test as its unit-testing framework, and some tests use Google Mock as well. Its tests are currently split up into several test executables, each dedicated to testing a different component. This may change in the future. After a successful build, the test executables will be found at out/Debug/crashpad_*_test
.
$ cd ~/crashpad/crashpad $ out/Debug/crashpad_minidump_test $ out/Debug/crashpad_util_test
A script is provided to run all of Crashpad’s tests. It accepts a single argument, a path to the directory containing the test executables.
$ cd ~/crashpad/crashpad $ python build/run_tests.py out/Debug
To run a subset of the tests, use the --gtest_filter
flag, e.g., to run all the tests for MinidumpStringWriter:
$ python build/run_tests.py out/Debug --gtest_filter MinidumpStringWriter\*
On Windows, end_to_end_test.py
requires the CDB debugger, installed with Debugging Tools for Windows. This can be installed either as part of the Windows Driver Kit or the Windows SDK. If the Windows SDK has already been installed (possibly with Visual Studio) but Debugging Tools for Windows is not present, it can be installed from Add or remove programs→Windows Software Development Kit.
To test on Android, ADB (Android Debug Bridge) from the Android SDK must be in the PATH
. Note that it is sufficient to install just the command-line tools from the Android SDK. The entire Android Studio IDE is not necessary to obtain ADB.
When asked to test an Android build directory, run_tests.py
will detect a single connected Android device (including an emulator). If multiple devices are connected, one may be chosen explicitly with the ANDROID_DEVICE
environment variable. run_tests.py
will upload test executables and data to a temporary location on the detected or selected device, run them, and clean up after itself when done.
To test on Fuchsia, you need a connected device running Fuchsia. Run:
$ gn gen out/fuchsia --args 'target_os="fuchsia" target_cpu="x64" is_debug=true' $ ninja -C out/fuchsia $ python build/run_tests.py out/fuchsia
If you have multiple devices running, you will need to specify which device you want using their hostname, for instance:
$ ZIRCON_NODENAME=scare-brook-skip-dried python build/run_tests.py out/fuchsia
Crashpad’s contribution process is very similar to Chromium’s contribution process.
A code review must be conducted for every change to Crashpad’s source code. Code review is conducted on Chromium’s Gerrit system, and all code reviews must be sent to an appropriate reviewer, with a Cc sent to crashpad-dev. The codereview.settings
file specifies this environment to git-cl
.
git-cl
is part of the depot_tools. There’s no need to install it separately.
$ cd ~/crashpad/crashpad $ git checkout -b work_branch origin/main …do some work… $ git add … $ git commit $ git cl upload
Uploading a patch to Gerrit does not automatically request a review. You must select a reviewer on the Gerrit review page after running git cl upload
. This action notifies your reviewer of the code review request. If you have lost track of the review page, git cl issue
will remind you of its URL. Alternatively, you can request review when uploading to Gerrit by using git cl upload --send-mail
.
Git branches maintain their association with Gerrit reviews, so if you need to make changes based on review feedback, you can do so on the correct Git branch, committing your changes locally with git commit
. You can then upload a new patch set with git cl upload
and let your reviewer know you’ve addressed the feedback.
The most recently uploaded patch set on a review may be tested on a trybot by running git cl try
or by clicking the “CQ Dry Run” button in Gerrit. These set the “Commit-Queue: +1” label. This does not mean that the patch will be committed, but the trybot and commit queue share infrastructure and a Gerrit label. The patch will be tested on trybots in a variety of configurations. Status information will be available on Gerrit. Trybot access is available to Crashpad and Chromium committers.
After code review is complete and “Code-Review: +1” has been received from all reviewers, the patch can be submitted to Crashpad’s commit queue by clicking the “Submit to CQ” button in Gerrit. This sets the “Commit-Queue: +2” label, which tests the patch on trybots before landing it. Commit queue access is available to Crashpad and Chromium committers.
Although the commit queue is recommended, if needed, project members can bypass the commit queue and land patches without testing by using the “Submit” button in Gerrit or by committing via git cl land
:
$ cd ~/crashpad/crashpad $ git checkout work_branch $ git cl land
Copyright holders must complete the Individual Contributor License Agreement or Corporate Contributor License Agreement as appropriate before any submission can be accepted, and must be listed in the AUTHORS
file. Contributors may be listed in the CONTRIBUTORS
file.
The Crashpad Buildbot performs automated builds and tests of Crashpad. Before checking out or updating the Crashpad source code, and after checking in a new change, it is prudent to check the Buildbot to ensure that “the tree is green.”