328 lines
12 KiB
Markdown
328 lines
12 KiB
Markdown
<!--
|
||
Copyright 2015 The Crashpad Authors
|
||
|
||
Licensed under the Apache License, Version 2.0 (the "License");
|
||
you may not use this file except in compliance with the License.
|
||
You may obtain a copy of the License at
|
||
|
||
http://www.apache.org/licenses/LICENSE-2.0
|
||
|
||
Unless required by applicable law or agreed to in writing, software
|
||
distributed under the License is distributed on an "AS IS" BASIS,
|
||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
See the License for the specific language governing permissions and
|
||
limitations under the License.
|
||
-->
|
||
|
||
# Developing Crashpad
|
||
|
||
## Status
|
||
|
||
[Project status](status.md) information has moved to its own page.
|
||
|
||
## Introduction
|
||
|
||
Crashpad is a [Chromium project](https://www.chromium.org/Home). Most of its
|
||
development practices follow Chromium’s. In order to function on its own in
|
||
other projects, Crashpad uses
|
||
[mini_chromium](https://chromium.googlesource.com/chromium/mini_chromium/), a
|
||
small, self-contained library that provides many of Chromium’s useful low-level
|
||
base routines. [mini_chromium’s
|
||
README](https://chromium.googlesource.com/chromium/mini_chromium/+/main/README.md)
|
||
provides more detail.
|
||
|
||
## Prerequisites
|
||
|
||
To develop Crashpad, the following tools are necessary, and must be present in
|
||
the `$PATH` environment variable:
|
||
|
||
* Appropriate development tools.
|
||
* On macOS, install [Xcode](https://developer.apple.com/xcode/). The latest
|
||
version is generally recommended.
|
||
* On Windows, install [Visual Studio](https://www.visualstudio.com/) with
|
||
C++ support and the Windows SDK. The latest version is generally
|
||
recommended. Some tests also require the CDB debugger, installed with
|
||
[Debugging Tools for
|
||
Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/).
|
||
* On Linux, obtain appropriate tools for C++ development through any
|
||
appropriate means including the system’s package manager. On Debian and
|
||
Debian-based distributions, the `build-essential`, `zlib1g-dev`, and any
|
||
one of the `libcurl4-*-dev` packages such as `libcurl4-openssl-dev` should
|
||
suffice.
|
||
* Chromium’s
|
||
[depot_tools](https://www.chromium.org/developers/how-tos/depottools).
|
||
* [Git](https://git-scm.com/). This is provided by Xcode on macOS, by
|
||
depot_tools on Windows, and through any appropriate means including the
|
||
system’s package manager on Linux.
|
||
* [Python](https://www.python.org/). This is provided by the operating system
|
||
on macOS, by depot_tools on Windows, and through any appropriate means
|
||
including the system’s package manager on Linux.
|
||
|
||
## 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`](https://www.chromium.org/developers/how-tos/depottools#TOC-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](https://www.chromium.org/developers/how-tos/depottools). There’s
|
||
no need to install them separately.
|
||
|
||
### Initial Checkout
|
||
|
||
```
|
||
$ mkdir ~/crashpad
|
||
$ cd ~/crashpad
|
||
$ fetch crashpad
|
||
```
|
||
|
||
`fetch crashpad` performs the initial `git clone` and `gclient sync`,
|
||
establishing a fully-functional local checkout.
|
||
|
||
### Subsequent Checkouts
|
||
|
||
```
|
||
$ cd ~/crashpad/crashpad
|
||
$ git pull -r
|
||
$ gclient sync
|
||
```
|
||
|
||
## Building
|
||
|
||
### Windows, Mac, Linux, Fuchsia
|
||
|
||
On Windows, Mac, Linux, and Fuchsia, Crashpad uses
|
||
[GN](https://gn.googlesource.com/gn) to generate
|
||
[Ninja](https://ninja-build.org/) 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](https://www.chromium.org/developers/how-tos/depottools). There’s
|
||
no need to install them separately.
|
||
|
||
#### Fuchsia
|
||
|
||
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"]`).
|
||
|
||
#### Optional Linux Configs
|
||
|
||
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"
|
||
```
|
||
|
||
### Android
|
||
|
||
This build relies on cross-compilation. It’s possible to develop Crashpad for
|
||
Android on any platform that the [Android NDK (Native Development
|
||
Kit)](https://developer.android.com/ndk/) runs on.
|
||
|
||
If it’s not already present on your system, [download the NDK package for your
|
||
system](https://developer.android.com/ndk/downloads/) 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`](https://chromium.googlesource.com/chromium/src/+/main/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
|
||
```
|
||
|
||
## Testing
|
||
|
||
Crashpad uses [Google Test](https://github.com/google/googletest/) as its
|
||
unit-testing framework, and some tests use [Google
|
||
Mock](https://github.com/google/googletest/tree/master/googlemock/) 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\*
|
||
```
|
||
|
||
### Windows
|
||
|
||
On Windows, `end_to_end_test.py` requires the CDB debugger, installed with
|
||
[Debugging Tools for
|
||
Windows](https://docs.microsoft.com/windows-hardware/drivers/debugger/). This
|
||
can be installed either as part of the [Windows Driver
|
||
Kit](https://docs.microsoft.com/windows-hardware/drivers/download-the-wdk) or
|
||
the [Windows
|
||
SDK](https://developer.microsoft.com/windows/downloads/windows-10-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.
|
||
|
||
### Android
|
||
|
||
To test on Android, [ADB (Android Debug
|
||
Bridge)](https://developer.android.com/studio/command-line/adb.html) from the
|
||
[Android SDK](https://developer.android.com/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.
|
||
|
||
### Fuchsia
|
||
|
||
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
|
||
```
|
||
|
||
## Contributing
|
||
|
||
Crashpad’s contribution process is very similar to [Chromium’s contribution
|
||
process](https://chromium.googlesource.com/chromium/src/+/main/docs/contributing.md).
|
||
|
||
### Code Review
|
||
|
||
A code review must be conducted for every change to Crashpad’s source code. Code
|
||
review is conducted on [Chromium’s
|
||
Gerrit](https://chromium-review.googlesource.com/) system, and all code reviews
|
||
must be sent to an appropriate reviewer, with a Cc sent to
|
||
[crashpad-dev](https://groups.google.com/a/chromium.org/group/crashpad-dev). The
|
||
[`codereview.settings`](https://chromium.googlesource.com/crashpad/crashpad/+/main/codereview.settings)
|
||
file specifies this environment to `git-cl`.
|
||
|
||
`git-cl` is part of the
|
||
[depot_tools](https://www.chromium.org/developers/how-tos/depottools). 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](https://chromium.googlesource.com/chromium/src/+/main/docs/infra/trybot_usage.md)
|
||
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.
|
||
|
||
### Landing Changes
|
||
|
||
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](https://chromium.googlesource.com/chromium/src/+/main/docs/infra/cq.md)
|
||
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
|
||
```
|
||
|
||
### External Contributions
|
||
|
||
Copyright holders must complete the [Individual Contributor License
|
||
Agreement](https://cla.developers.google.com/about/google-individual) or
|
||
[Corporate Contributor License
|
||
Agreement](https://cla.developers.google.com/about/google-corporate) as
|
||
appropriate before any submission can be accepted, and must be listed in the
|
||
[`AUTHORS`](https://chromium.googlesource.com/crashpad/crashpad/+/main/AUTHORS)
|
||
file. Contributors may be listed in the
|
||
[`CONTRIBUTORS`](https://chromium.googlesource.com/crashpad/crashpad/+/main/CONTRIBUTORS)
|
||
file.
|
||
|
||
## Buildbot
|
||
|
||
The [Crashpad Buildbot](https://ci.chromium.org/p/crashpad/g/main/console)
|
||
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.”
|