Status
Project status information has moved to its own page.
Introduction
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.
Prerequisites
To develop Crashpad, the following tools are necessary, and must be present in the $PATH environment variable:
-
Chromium’s depot_tools.
-
Git. This is provided by Xcode on Mac OS X and by depot_tools on Windows.
-
Python. This is provided by the operating system on Mac OS X, and by depot_tools on Windows.
-
Appropriate development tools. For Mac OS X, this is Xcode, and for Windows, it’s Visual Studio.
Getting the Source Code
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.
Initial Checkout
$ mkdir ~/crashpad $ cd ~/crashpad $ fetch crashpad
fetch crashpad performs the initial gclient sync, establishing a fully-functional local checkout.
Subsequent Checkouts
$ cd ~/crashpad/crashpad $ git pull -r $ gclient sync
Building
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.
Testing
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
Contributing
Crashpad’s contribution process is very similar to Chromium’s contribution process.
Code Review
A code review must be conducted for every change to Crashpad’s source code. Code review is conducted on Chromium’s Rietveld 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 Rietveld does not automatically request a review. You must select a reviewer and mail your request to them (with a Cc to crashpad-dev) from the Rietveld issue page after running git cl upload. If you have lost track of the issue page, git cl issue will remind you of its URL. Alternatively, you can request review when uploading to Rietveld by using git cl upload --send-mail
Git branches maintain their association with Rietveld issues, 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.
Landing Changes
After code review is complete and “LGTM” (“looks good to me”) has been received from all reviewers, project members can commit the patch themselves:
$ cd ~/crashpad/crashpad $ git checkout work_branch $ git cl land
Crashpad does not currently have a commit queue, so contributors that 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 patching the change into a local branch and landing it:
$ cd ~/crashpad/crashpad $ git checkout -b for_external_contributor origin/master $ git cl patch 12345678 # 12345678 is the Rietveld issue number $ git cl land -c 'External Contributor <external@contributor.org>'
External Contributions
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.
Buildbot
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.”