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:
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
Crashpad uses GYP to generate Ninja build files. The build is described by .gyp files throughout the Crashpad source code tree. The build/gyp_crashpad.py script runs GYP properly for Crashpad, and is also called when you run fetch crashpad, gclient sync, or gclient runhooks.
The Ninja build files and build output are in the out directory. Both debug- and release-mode configurations are available. The examples below show the debug configuration. To build and test the release configuration, substitute Release for Debug.
$ cd ~/crashpad/crashpad $ ninja -C out/Debug
Ninja is part of the depot_tools. There’s no need to install it separately.
Crashpad’s Android port is in its early stages. 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-r13.
To build Crashpad, portions of the NDK must be reassembled into a standalone toolchain. This is a repackaged subset of the NDK suitable for cross-compiling for a single Android architecture (such as arm, arm64, x86, and x86_64) targeting a specific Android API level. The standalone toolchain only needs to be built from the NDK one time for each set of options desired. To build a standalone toolchain targeting 64-bit ARM and API level 21 (Android 5.0 “Lollipop”), run:
$ cd ~
$ python android-ndk-r13/build/tools/make_standalone_toolchain.py \
--arch=arm64 --api=21 --install-dir=android-ndk-r13_arm64_api21
Note that Chrome uses Android API level 21 for 64-bit platforms and 16 for 32-bit platforms. See Chrome’s build/config/android/config.gni which sets _android_api_level and _android64_api_level.
To configure a Crashpad build for Android using this standalone toolchain, set several environment variables directing the build to the standalone toolchain, along with GYP options to identify an Android build. This must be done after any gclient sync, or instead of any gclient runhooks operation. The environment variables only need to be set for this gyp_crashpad.py invocation, and need not be permanent.
$ cd ~/crashpad/crashpad
$ CC_target=~/android-ndk-r13_arm64_api21/bin/clang \
CXX_target=~/android-ndk-r13_arm64_api21/bin/clang++ \
AR_target=~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-ar \
NM_target=~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-nm \
READELF_target=~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-readelf \
python build/gyp_crashpad.py \
-DOS=android -Dtarget_arch=arm64 -Dclang=1 \
--generator-output=out_android_arm64_api21 -f ninja-android
It is also possible to use GCC instead of Clang by making the appropriate substitutions: aarch64-linux-android-gcc for CC_target; aarch64-linux-android-g++ for CXX_target; and -Dclang=0 as an argument to gyp_crashpad.py.
Target “triplets” to use for ar, nm, readelf, gcc, and g++ are:
| Architecture | Target “triplet” |
|---|---|
arm | arm-linux-androideabi |
arm64 | aarch64-linux-android |
x86 | i686-linux-android |
x86_64 | x86_64-linux-android |
The port is incomplete, but targets known to be working include crashpad_util, crashpad_test, and crashpad_test_test. This list will grow over time. To build, direct ninja to the specific out directory chosen by --generator-output above.
$ ninja -C out_android_arm64_api21/out/Debug crashpad_test_test
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 that tells it which configuration to test.
$ cd ~/crashpad/crashpad $ python build/run_tests.py Debug
To test on Android, use ADB (Android Debug Bridge) to adb push test executables and test data to a device or emulator, then use adb shell to get a shell to run the test executables from. ADB is part of the Android SDK. Note that it is sufficient to install just the command-line tools. The entire Android Studio IDE is not necessary to obtain ADB.
This example runs crashpad_test_test on a device. This test executable has a run-time dependency on a second executable and a test data file, which are also transferred to the device prior to running the test.
$ cd ~/crashpad/crashpad
$ adb push out_android_arm64_api21/out/Debug/crashpad_test_test /data/local/tmp/
[100%] /data/local/tmp/crashpad_test_test
$ adb push \
out_android_arm64_api21/out/Debug/crashpad_test_test_multiprocess_exec_test_child \
/data/local/tmp/
[100%] /data/local/tmp/crashpad_test_test_multiprocess_exec_test_child
$ adb shell mkdir -p /data/local/tmp/crashpad_test_data_root/test
$ adb push test/paths_test_data_root.txt \
/data/local/tmp/crashpad_test_data_root/test/
[100%] /data/local/tmp/crashpad_test_data_root/test/paths_test_data_root.txt
$ adb shell
device:/ $ cd /data/local/tmp
device:/data/local/tmp $ CRASHPAD_TEST_DATA_ROOT=crashpad_test_data_root \
./crashpad_test_test
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/master …do some work… $ git add … $ git commit $ git cl upload
The PolyGerrit interface to Gerrit, undergoing active development, is recommended. To switch from the classic GWT-based Gerrit UI to PolyGerrit, click the PolyGerrit link in a Gerrit review page’s footer.
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.
After code review is complete and “Code-Review: +1” has been received from all reviewers, project members can commit the patch themselves:
$ cd ~/crashpad/crashpad $ git checkout work_branch $ git cl land
Alternatively, patches can be committed by clicking the “Submit” button in the Gerrit UI.
Crashpad does not currently have a commit queue, so contributors who are not project members will have to ask a project member to commit the patch for them. Project members can commit changes on behalf of external contributors by clicking the “Submit” button in the Gerrit UI.
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.”