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:
- Appropriate development tools.
- On macOS, install Xcode. The latest version is generally recommended.
- On Windows, install Visual Studio with C++ support and the Windows SDK. MSVS 2015 and MSVS 2017 are both supported. Some tests also require the CDB debugger, installed with Debugging Tools for Windows.
- Chromium’s depot_tools.
- Git. This is provided by Xcode on macOS and by depot_tools on Windows.
- Python. This is provided by the operating system on macOS, and by depot_tools on Windows.
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. On Windows, four configurations are available: Debug and
Release produce 32-bit x86 executables, and Debug_x64 and Release_x64
produce x86_64 executables.
$ 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-r15b.
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-r15b/build/tools/make_standalone_toolchain.py \
--arch=arm64 --api=21 --install-dir=android-ndk-r15b_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 the standalone toolchain
assembled above, use gyp_crashpad_android.py. This script is a wrapper for
gyp_crashpad.py that sets several environment variables directing the build to
the standalone toolchain, and several GYP options to identify an Android build.
This must be done after any gclient sync, or instead of any gclient runhooks
operation.
$ cd ~/crashpad/crashpad
$ python build/gyp_crashpad_android.py \
--ndk ~/android-ndk-r15b_arm64_api21 \
--generator-output out/android_arm64_api21
gyp_crashpad_android.py detects the build type based on the characteristics of
the standalone toolchain given in its --ndk argument.
gyp_crashpad_android.py sets the build up to use Clang by default. It’s also
possible to use GCC by providing the --compiler=gcc argument to
gyp_crashpad_android.py.
The Android port is incomplete, but targets known to be working include
crashpad_test, crashpad_util, and their tests. This list will grow over
time. To build, direct ninja to the specific out directory chosen by the
--generator-output argument to gyp_crashpad_android.py.
$ ninja -C out/android_arm64_api21/out/Debug \
crashpad_test_test crashpad_util_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, a path to the directory containing the test executables.
$ cd ~/crashpad/crashpad
$ python build/run_tests.py out/Debug
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, 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/test_paths_test_data_root.txt \
/data/local/tmp/crashpad_test_data_root/test/
[100%] /data/local/tmp/crashpad_test_data_root/test/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
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 try
server 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 try server and commit queue share infrastructure and a Gerrit label. The
patch will be tested on try bots in a variety of configurations. Status
information will be available on Gerrit. Try server 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 the try server 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.”