1<!-- 2Copyright 2015 The Crashpad Authors. All rights reserved. 3 4Licensed under the Apache License, Version 2.0 (the "License"); 5you may not use this file except in compliance with the License. 6You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10Unless required by applicable law or agreed to in writing, software 11distributed under the License is distributed on an "AS IS" BASIS, 12WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13See the License for the specific language governing permissions and 14limitations under the License. 15--> 16 17# Developing Crashpad 18 19## Status 20 21[Project status](status.md) information has moved to its own page. 22 23## Introduction 24 25Crashpad is a [Chromium project](https://www.chromium.org/Home). Most of its 26development practices follow Chromium’s. In order to function on its own in 27other projects, Crashpad uses 28[mini_chromium](https://chromium.googlesource.com/chromium/mini_chromium/), a 29small, self-contained library that provides many of Chromium’s useful low-level 30base routines. [mini_chromium’s 31README](https://chromium.googlesource.com/chromium/mini_chromium/+/master/README.md) 32provides more detail. 33 34## Prerequisites 35 36To develop Crashpad, the following tools are necessary, and must be present in 37the `$PATH` environment variable: 38 39 * Appropriate development tools. 40 * On macOS, install [Xcode](https://developer.apple.com/xcode/). The latest 41 version is generally recommended. 42 * On Windows, install [Visual Studio](https://www.visualstudio.com/) with 43 C++ support and the Windows SDK. MSVS 2015 and MSVS 2017 are both 44 supported. Some tests also require the CDB debugger, installed with 45 [Debugging Tools for 46 Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/). 47 * Chromium’s 48 [depot_tools](https://www.chromium.org/developers/how-tos/depottools). 49 * [Git](https://git-scm.com/). This is provided by Xcode on macOS and by 50 depot_tools on Windows. 51 * [Python](https://www.python.org/). This is provided by the operating system 52 on macOS, and by depot_tools on Windows. 53 54## Getting the Source Code 55 56The main source code repository is a Git repository hosted at 57https://chromium.googlesource.com/crashpad/crashpad. Although it is possible to 58check out this repository directly with `git clone`, Crashpad’s dependencies are 59managed by 60[`gclient`](https://www.chromium.org/developers/how-tos/depottools#TOC-gclient) 61instead of Git submodules, so to work on Crashpad, it is best to use `fetch` to 62get the source code. 63 64`fetch` and `gclient` are part of the 65[depot_tools](https://www.chromium.org/developers/how-tos/depottools). There’s 66no need to install them separately. 67 68### Initial Checkout 69 70``` 71$ mkdir ~/crashpad 72$ cd ~/crashpad 73$ fetch crashpad 74``` 75 76`fetch crashpad` performs the initial `git clone` and `gclient sync`, 77establishing a fully-functional local checkout. 78 79### Subsequent Checkouts 80 81``` 82$ cd ~/crashpad/crashpad 83$ git pull -r 84$ gclient sync 85``` 86 87## Building 88 89### Windows, Mac, Linux, Fuchsia 90 91On Windows, Mac, Linux, and Fuchsia Crashpad uses 92[GN](https://gn.googlesource.com/gn) to generate 93[Ninja](https://ninja-build.org/) build files. For example, 94 95``` 96$ cd ~/crashpad/crashpad 97$ gn gen out/Default 98$ ninja -C out/Default 99``` 100 101You can then use `gn args out/Default` or edit `out/Default/args.gn` to 102configure the build, for example things like `is_debug=true` or 103`target_cpu="x86"`. 104 105GN and Ninja are part of the 106[depot_tools](https://www.chromium.org/developers/how-tos/depottools). There’s 107no need to install them separately. 108 109#### Fuchsia 110 111In order to instruct gclient to download the Fuchsia SDK, you need to add the 112following to `~/crashpad/.gclient`. 113 114``` 115target_os=["fuchsia"] 116``` 117 118If you're using this tree to develop for multiple targets, you can also add 119other entries to the the list (e.g. `target_os=["fuchsia", "mac"]`). 120 121#### Optional Linux Configs 122 123To pull and use Crashpad's version of clang and sysroot, make the following 124changes. 125 126Add the following to `~/crashpad/.gclient`. 127``` 128"custom_vars": { "pull_linux_clang": True }, 129``` 130Add these args to `out/Default/args.gn`. 131``` 132clang_path = "//third_party/linux/clang/linux-amd64" 133target_sysroot = "//third_party/linux/sysroot" 134``` 135 136### Android 137 138This build relies on cross-compilation. It’s possible to develop Crashpad for 139Android on any platform that the [Android NDK (Native Development Kit)] 140(https://developer.android.com/ndk/) runs on. 141 142If it’s not already present on your system, [download the NDK package for your 143system](https://developer.android.com/ndk/downloads/) and expand it to a 144suitable location. These instructions assume that it’s been expanded to 145`~/android-ndk-r20`. 146 147Note that Chrome uses Android API level 21 for 64-bit platforms and 16 for 14832-bit platforms. See Chrome’s 149[`build/config/android/config.gni`](https://chromium.googlesource.com/chromium/src/+/master/build/config/android/config.gni) 150which sets `_android_api_level` and `_android64_api_level`. 151 152To configure a Crashpad build for Android use `gyp_crashpad_android.py`. This 153script is a wrapper for `gyp_crashpad.py` that sets several environment 154variables directing the build to the toolchain, and several GYP options to 155identify an Android build. This must be done after any `gclient sync`, or 156instead of any `gclient runhooks` operation. 157 158``` 159$ cd ~/crashpad/crashpad 160python build/gyp_crashpad_android.py \ 161 --ndk ~/usr/lib/android-ndk-r20 --arch arm64 --api-level 21 \ 162 --generator-output=out/android_arm64_api21 \ 163``` 164 165To build, direct `ninja` to the specific `out` directory chosen by the 166`--generator-output` argument to `gyp_crashpad_android.py`. 167 168``` 169$ ninja -C out/android_arm64_api21/out/Debug all 170``` 171 172## Testing 173 174Crashpad uses [Google Test](https://github.com/google/googletest/) as its 175unit-testing framework, and some tests use [Google 176Mock](https://github.com/google/googletest/tree/master/googlemock/) as well. Its 177tests are currently split up into several test executables, each dedicated to 178testing a different component. This may change in the future. After a successful 179build, the test executables will be found at `out/Debug/crashpad_*_test`. 180 181``` 182$ cd ~/crashpad/crashpad 183$ out/Debug/crashpad_minidump_test 184$ out/Debug/crashpad_util_test 185``` 186 187A script is provided to run all of Crashpad’s tests. It accepts a single 188argument, a path to the directory containing the test executables. 189 190``` 191$ cd ~/crashpad/crashpad 192$ python build/run_tests.py out/Debug 193``` 194 195To run a subset of the tests, use the --gtest\_filter flag, e.g., to run all the 196tests for MinidumpStringWriter: 197 198```sh 199$ python build/run_tests.py out/Debug --gtest_filter MinidumpStringWriter* 200``` 201 202### Windows 203 204On Windows, `end_to_end_test.py` requires the CDB debugger, installed with 205[Debugging Tools for 206Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/). 207This can be installed either as part of the [Windows Driver 208Kit](https://go.microsoft.com/fwlink/p?LinkID=239721) or the [Windows 209SDK](https://go.microsoft.com/fwlink/p?LinkID=271979). If the Windows SDK has 210already been installed (possibly with Visual Studio) but Debugging Tools for 211Windows is not present, it can be installed from Add or remove programs→Windows 212Software Development Kit. 213 214### Android 215 216To test on Android, [ADB (Android Debug 217Bridge)](https://developer.android.com/studio/command-line/adb.html) from the 218[Android SDK](https://developer.android.com/sdk/) must be in the `PATH`. Note 219that it is sufficient to install just the command-line tools from the Android 220SDK. The entire Android Studio IDE is not necessary to obtain ADB. 221 222When asked to test an Android build directory, `run_tests.py` will detect a 223single connected Android device (including an emulator). If multiple devices are 224connected, one may be chosen explicitly with the `ANDROID_DEVICE` environment 225variable. `run_tests.py` will upload test executables and data to a temporary 226location on the detected or selected device, run them, and clean up after itself 227when done. 228 229### Fuchsia 230 231To test on Fuchsia, you need a connected device running Fuchsia and then run: 232 233```sh 234$ gn gen out/fuchsia --args='target_os="fuchsia" target_cpu="x64" is_debug=true' 235$ ninja -C out/fuchsia 236$ python build/run_tests.py out/fuchsia 237``` 238 239If you have multiple devices running, you will need to specify which device you 240want using their hostname, for instance: 241 242```sh 243$ export ZIRCON_NODENAME=scare-brook-skip-dried; \ 244 python build/run_tests.py out/fuchsia; \ 245 unset ZIRCON_NODENAME 246``` 247 248## Contributing 249 250Crashpad’s contribution process is very similar to [Chromium’s contribution 251process](https://www.chromium.org/developers/contributing-code). 252 253### Code Review 254 255A code review must be conducted for every change to Crashpad’s source code. Code 256review is conducted on [Chromium’s 257Gerrit](https://chromium-review.googlesource.com/) system, and all code reviews 258must be sent to an appropriate reviewer, with a Cc sent to 259[crashpad-dev](https://groups.google.com/a/chromium.org/group/crashpad-dev). The 260[`codereview.settings`](https://chromium.googlesource.com/crashpad/crashpad/+/master/codereview.settings) 261file specifies this environment to `git-cl`. 262 263`git-cl` is part of the 264[depot_tools](https://www.chromium.org/developers/how-tos/depottools). There’s 265no need to install it separately. 266 267``` 268$ cd ~/crashpad/crashpad 269$ git checkout -b work_branch origin/master 270…do some work… 271$ git add … 272$ git commit 273$ git cl upload 274``` 275 276Uploading a patch to Gerrit does not automatically request a review. You must 277select a reviewer on the Gerrit review page after running `git cl upload`. This 278action notifies your reviewer of the code review request. If you have lost track 279of the review page, `git cl issue` will remind you of its URL. Alternatively, 280you can request review when uploading to Gerrit by using `git cl upload 281--send-mail`. 282 283Git branches maintain their association with Gerrit reviews, so if you need to 284make changes based on review feedback, you can do so on the correct Git branch, 285committing your changes locally with `git commit`. You can then upload a new 286patch set with `git cl upload` and let your reviewer know you’ve addressed the 287feedback. 288 289The most recently uploaded patch set on a review may be tested on a [try 290server](https://www.chromium.org/developers/testing/try-server-usage) by running 291`git cl try` or by clicking the “CQ Dry Run” button in Gerrit. These set the 292“Commit-Queue: +1” label. This does not mean that the patch will be committed, 293but the try server and commit queue share infrastructure and a Gerrit label. The 294patch will be tested on try bots in a variety of configurations. Status 295information will be available on Gerrit. Try server access is available to 296Crashpad and Chromium committers. 297 298### Landing Changes 299 300After code review is complete and “Code-Review: +1” has been received from all 301reviewers, the patch can be submitted to Crashpad’s [commit 302queue](https://www.chromium.org/developers/testing/commit-queue) by clicking the 303“Submit to CQ” button in Gerrit. This sets the “Commit-Queue: +2” label, which 304tests the patch on the try server before landing it. Commit queue access is 305available to Crashpad and Chromium committers. 306 307Although the commit queue is recommended, if needed, project members can bypass 308the commit queue and land patches without testing by using the “Submit” button 309in Gerrit or by committing via `git cl land`: 310 311``` 312$ cd ~/crashpad/crashpad 313$ git checkout work_branch 314$ git cl land 315``` 316 317### External Contributions 318 319Copyright holders must complete the [Individual Contributor License 320Agreement](https://developers.google.com/open-source/cla/individual) or 321[Corporate Contributor License 322Agreement](https://developers.google.com/open-source/cla/corporate) as 323appropriate before any submission can be accepted, and must be listed in the 324[`AUTHORS`](https://chromium.googlesource.com/crashpad/crashpad/+/master/AUTHORS) 325file. Contributors may be listed in the 326[`CONTRIBUTORS`](https://chromium.googlesource.com/crashpad/crashpad/+/master/CONTRIBUTORS) 327file. 328 329## Buildbot 330 331The [Crashpad Buildbot](https://build.chromium.org/p/client.crashpad/) performs 332automated builds and tests of Crashpad. Before checking out or updating the 333Crashpad source code, and after checking in a new change, it is prudent to check 334the Buildbot to ensure that “the tree is green.” 335