| OLD | NEW |
|---|
| (Empty) |
| 1 // Copyright 2015 The Crashpad Authors. All rights reserved. | |
| 2 // | |
| 3 // Licensed under the Apache License, Version 2.0 (the "License"); | |
| 4 // you may not use this file except in compliance with the License. | |
| 5 // You may obtain a copy of the License at | |
| 6 // | |
| 7 // http://www.apache.org/licenses/LICENSE-2.0 | |
| 8 // | |
| 9 // Unless required by applicable law or agreed to in writing, software | |
| 10 // distributed under the License is distributed on an "AS IS" BASIS, | |
| 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| 12 // See the License for the specific language governing permissions and | |
| 13 // limitations under the License. | |
| 14 | |
| 15 :doctype: article | |
| 16 | |
| 17 = Developing Crashpad | |
| 18 | |
| 19 == Status | |
| 20 | |
| 21 link:status.html[Project status] information has moved to its own page. | |
| 22 | |
| 23 == Introduction | |
| 24 | |
| 25 Crashpad is a https://dev.chromium.org/Home[Chromium project]. Most of | |
| 26 its development practices follow Chromium’s. In order to function on its | |
| 27 own in other projects, Crashpad uses | |
| 28 https://chromium.googlesource.com/chromium/mini_chromium/[mini_chromium], | |
| 29 a small, self-contained library that provides many of Chromium’s useful | |
| 30 low-level base routines. | |
| 31 https://chromium.googlesource.com/chromium/mini_chromium/+/master/README[mini_ch
romium’s | |
| 32 README] provides more detail. | |
| 33 | |
| 34 == Prerequisites | |
| 35 | |
| 36 To develop Crashpad, the following tools are necessary, and must be | |
| 37 present in the `$PATH` environment variable: | |
| 38 | |
| 39 * Chromium’s | |
| 40 https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. | |
| 41 * https://git-scm.com/[Git]. This is provided by Xcode on Mac OS X and by | |
| 42 depot_tools on Windows. | |
| 43 * https://www.python.org/[Python]. This is provided by the operating system on | |
| 44 Mac OS X, and by depot_tools on Windows. | |
| 45 * Appropriate development tools. For Mac OS X, this is | |
| 46 https://developer.apple.com/xcode/[Xcode], and for Windows, it’s | |
| 47 https://www.visualstudio.com/[Visual Studio]. | |
| 48 | |
| 49 == Getting the Source Code | |
| 50 | |
| 51 The main source code repository is a Git repository hosted at | |
| 52 https://chromium.googlesource.com/crashpad/crashpad. Although it is possible to | |
| 53 check out this repository directly with `git clone`, Crashpad’s dependencies are | |
| 54 managed by | |
| 55 https://dev.chromium.org/developers/how-tos/depottools#TOC-gclient[`gclient`] | |
| 56 instead of Git submodules, so to work on Crashpad, it is best to use `fetch` to | |
| 57 get the source code. | |
| 58 | |
| 59 `fetch` and `gclient` are part of the | |
| 60 https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no | |
| 61 need to install them separately. | |
| 62 | |
| 63 === Initial Checkout | |
| 64 | |
| 65 [subs="verbatim,quotes"] | |
| 66 ---- | |
| 67 $ *mkdir \~/crashpad* | |
| 68 $ *cd ~/crashpad* | |
| 69 $ *fetch crashpad* | |
| 70 ---- | |
| 71 | |
| 72 `fetch crashpad` performs the initial `git clone` and `gclient sync`, | |
| 73 establishing a fully-functional local checkout. | |
| 74 | |
| 75 === Subsequent Checkouts | |
| 76 | |
| 77 [subs="verbatim,quotes"] | |
| 78 ---- | |
| 79 $ *cd ~/crashpad/crashpad* | |
| 80 $ *git pull -r* | |
| 81 $ *gclient sync* | |
| 82 ---- | |
| 83 | |
| 84 == Building | |
| 85 | |
| 86 Crashpad uses https://gyp.gsrc.io/[GYP] to generate | |
| 87 https://ninja-build.org/[Ninja] build files. The build is described by `.gyp` | |
| 88 files throughout the Crashpad source code tree. The `build/gyp_crashpad.py` | |
| 89 script runs GYP properly for Crashpad, and is also called when you run `fetch | |
| 90 crashpad`, `gclient sync`, or `gclient runhooks`. | |
| 91 | |
| 92 The Ninja build files and build output are in the `out` directory. Both debug- | |
| 93 and release-mode configurations are available. The examples below show the debug | |
| 94 configuration. To build and test the release configuration, substitute `Release` | |
| 95 for `Debug`. | |
| 96 | |
| 97 [subs="verbatim,quotes"] | |
| 98 ---- | |
| 99 $ *cd ~/crashpad/crashpad* | |
| 100 $ *ninja -C out/Debug* | |
| 101 ---- | |
| 102 | |
| 103 Ninja is part of the | |
| 104 https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no | |
| 105 need to install it separately. | |
| 106 | |
| 107 === Android | |
| 108 | |
| 109 Crashpad’s Android port is in its early stages. This build relies on | |
| 110 cross-compilation. It’s possible to develop Crashpad for Android on any platform | |
| 111 that the https://developer.android.com/ndk/[Android NDK (Native Development | |
| 112 Kit)] runs on. | |
| 113 | |
| 114 If it’s not already present on your system, | |
| 115 https://developer.android.com/ndk/downloads/[download the NDK package for your | |
| 116 system] and expand it to a suitable location. These instructions assume that | |
| 117 it’s been expanded to `~/android-ndk-r13`. | |
| 118 | |
| 119 To build Crashpad, portions of the NDK must be reassembled into a | |
| 120 https://developer.android.com/ndk/guides/standalone_toolchain.html[standalone | |
| 121 toolchain]. This is a repackaged subset of the NDK suitable for cross-compiling | |
| 122 for a single Android architecture (such as `arm`, `arm64`, `x86`, and `x86_64`) | |
| 123 targeting a specific | |
| 124 https://source.android.com/source/build-numbers.html[Android API level]. The | |
| 125 standalone toolchain only needs to be built from the NDK one time for each set | |
| 126 of options desired. To build a standalone toolchain targeting 64-bit ARM and API | |
| 127 level 21 (Android 5.0 “Lollipop”), run: | |
| 128 | |
| 129 [subs="verbatim,quotes"] | |
| 130 ---- | |
| 131 $ *cd ~* | |
| 132 $ *python android-ndk-r13/build/tools/make_standalone_toolchain.py \ | |
| 133 --arch=arm64 --api=21 --install-dir=android-ndk-r13_arm64_api21* | |
| 134 ---- | |
| 135 | |
| 136 Note that Chrome uses Android API level 21 for 64-bit platforms and 16 for | |
| 137 32-bit platforms. See Chrome’s | |
| 138 https://chromium.googlesource.com/chromium/src/+/master/build/config/android/con
fig.gni[`build/config/android/config.gni`] | |
| 139 which sets `_android_api_level` and `_android64_api_level`. | |
| 140 | |
| 141 To configure a Crashpad build for Android using this standalone toolchain, | |
| 142 set several environment variables directing the build to the standalone | |
| 143 toolchain, along with GYP options to identify an Android build. This must be | |
| 144 done after any `gclient sync`, or instead of any `gclient runhooks` operation. | |
| 145 The environment variables only need to be set for this `gyp_crashpad.py` | |
| 146 invocation, and need not be permanent. | |
| 147 | |
| 148 [subs="verbatim,quotes"] | |
| 149 ---- | |
| 150 $ *cd \~/crashpad/crashpad* | |
| 151 $ *CC_target=\~/android-ndk-r13_arm64_api21/bin/clang \ | |
| 152 CXX_target=\~/android-ndk-r13_arm64_api21/bin/clang++ \ | |
| 153 AR_target=\~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-ar \ | |
| 154 NM_target=\~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-nm \ | |
| 155 READELF_target=~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-readelf
\ | |
| 156 python build/gyp_crashpad.py \ | |
| 157 -DOS=android -Dtarget_arch=arm64 -Dclang=1 \ | |
| 158 --generator-output=out_android_arm64_api21 -f ninja-android* | |
| 159 ---- | |
| 160 | |
| 161 Target “triplets” to use for `ar`, `nm`, and `readelf` are: | |
| 162 | |
| 163 [width="40%",cols="1,3",frame="topbot"] | |
| 164 |=== | |
| 165 |`arm` |`arm-linux-androideabi` | |
| 166 |`arm64` |`aarch64-linux-android` | |
| 167 |`x86` |`i686-linux-android` | |
| 168 |`x86_64` |`x86_64-linux-android` | |
| 169 |=== | |
| 170 | |
| 171 The port is incomplete, but targets known to be working include `crashpad_util`, | |
| 172 `crashpad_test`, and `crashpad_test_test`. This list will grow over time. To | |
| 173 build, direct `ninja` to the specific `out` directory chosen by | |
| 174 `--generator-output` above. | |
| 175 | |
| 176 [subs="verbatim,quotes"] | |
| 177 ---- | |
| 178 $ *ninja -C out_android_arm64_api21/out/Debug crashpad_test_test* | |
| 179 ---- | |
| 180 | |
| 181 == Testing | |
| 182 | |
| 183 Crashpad uses https://github.com/google/googletest/[Google Test] as its | |
| 184 unit-testing framework, and some tests use | |
| 185 https://github.com/google/googletest/tree/master/googlemock/[Google Mock] as | |
| 186 well. Its tests are currently split up into several test executables, each | |
| 187 dedicated to testing a different component. This may change in the future. After | |
| 188 a successful build, the test executables will be found at | |
| 189 `out/Debug/crashpad_*_test`. | |
| 190 | |
| 191 [subs="verbatim,quotes"] | |
| 192 ---- | |
| 193 $ *cd ~/crashpad/crashpad* | |
| 194 $ *out/Debug/crashpad_minidump_test* | |
| 195 $ *out/Debug/crashpad_util_test* | |
| 196 ---- | |
| 197 | |
| 198 A script is provided to run all of Crashpad’s tests. It accepts a single | |
| 199 argument that tells it which configuration to test. | |
| 200 | |
| 201 [subs="verbatim,quotes"] | |
| 202 ---- | |
| 203 $ *cd ~/crashpad/crashpad* | |
| 204 $ *python build/run_tests.py Debug* | |
| 205 ---- | |
| 206 | |
| 207 === Android | |
| 208 | |
| 209 To test on Android, use | |
| 210 https://developer.android.com/studio/command-line/adb.html[ADB (Android Debug | |
| 211 Bridge)] to `adb push` test executables and test data to a device or emulator, | |
| 212 then use `adb shell` to get a shell to run the test executables from. ADB is | |
| 213 part of the https://developer.android.com/sdk/[Android SDK]. Note that it is | |
| 214 sufficient to install just the command-line tools. The entire Android Studio IDE | |
| 215 is not necessary to obtain ADB. | |
| 216 | |
| 217 This example runs `crashpad_test_test` on a device. This test executable has a | |
| 218 run-time dependency on a second executable and a test data file, which are also | |
| 219 transferred to the device prior to running the test. | |
| 220 | |
| 221 [subs="verbatim,quotes"] | |
| 222 ---- | |
| 223 $ *cd ~/crashpad/crashpad* | |
| 224 $ *adb push out_android_arm64_api21/out/Debug/crashpad_test_test /data/local/tmp
/* | |
| 225 [100%] /data/local/tmp/crashpad_test_test | |
| 226 $ *adb push \ | |
| 227 out_android_arm64_api21/out/Debug/crashpad_test_test_multiprocess_exec_tes
t_child \ | |
| 228 /data/local/tmp/* | |
| 229 [100%] /data/local/tmp/crashpad_test_test_multiprocess_exec_test_child | |
| 230 $ *adb shell mkdir -p /data/local/tmp/crashpad_test_data_root/test* | |
| 231 $ *adb push test/paths_test_data_root.txt \ | |
| 232 /data/local/tmp/crashpad_test_data_root/test/* | |
| 233 [100%] /data/local/tmp/crashpad_test_data_root/test/paths_test_data_root.txt | |
| 234 $ *adb shell* | |
| 235 device:/ $ *cd /data/local/tmp* | |
| 236 device:/data/local/tmp $ *CRASHPAD_TEST_DATA_ROOT=crashpad_test_data_root \ | |
| 237 ./crashpad_test_test* | |
| 238 ---- | |
| 239 | |
| 240 == Contributing | |
| 241 | |
| 242 Crashpad’s contribution process is very similar to | |
| 243 https://dev.chromium.org/developers/contributing-code[Chromium’s contribution | |
| 244 process]. | |
| 245 | |
| 246 === Code Review | |
| 247 | |
| 248 A code review must be conducted for every change to Crashpad’s source code. Code | |
| 249 review is conducted on https://chromium-review.googlesource.com/[Chromium’s | |
| 250 Gerrit] system, and all code reviews must be sent to an appropriate reviewer, | |
| 251 with a Cc sent to | |
| 252 https://groups.google.com/a/chromium.org/group/crashpad-dev[crashpad-dev]. The | |
| 253 https://chromium.googlesource.com/crashpad/crashpad/+/master/codereview.settings
[`codereview.settings`] | |
| 254 file specifies this environment to `git-cl`. | |
| 255 | |
| 256 `git-cl` is part of the | |
| 257 https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no | |
| 258 need to install it separately. | |
| 259 | |
| 260 [subs="verbatim,quotes"] | |
| 261 ---- | |
| 262 $ *cd ~/crashpad/crashpad* | |
| 263 $ *git checkout -b work_branch origin/master* | |
| 264 _…do some work…_ | |
| 265 $ *git add …* | |
| 266 $ *git commit* | |
| 267 $ *git cl upload* | |
| 268 ---- | |
| 269 | |
| 270 The https://polygerrit.appspot.com/[PolyGerrit interface] to Gerrit, undergoing | |
| 271 active development, is recommended. To switch from the classic GWT-based Gerrit | |
| 272 UI to PolyGerrit, click the PolyGerrit link in a Gerrit review page’s footer. | |
| 273 | |
| 274 Uploading a patch to Gerrit does not automatically request a review. You must | |
| 275 select a reviewer on the Gerrit review page after running `git cl upload`. This | |
| 276 action notifies your reviewer of the code review request. If you have lost track | |
| 277 of the review page, `git cl issue` will remind you of its URL. Alternatively, | |
| 278 you can request review when uploading to Gerrit by using `git cl upload | |
| 279 --send-mail`. | |
| 280 | |
| 281 Git branches maintain their association with Gerrit reviews, so if you need to | |
| 282 make changes based on review feedback, you can do so on the correct Git branch, | |
| 283 committing your changes locally with `git commit`. You can then upload a new | |
| 284 patch set with `git cl upload` and let your reviewer know you’ve addressed the | |
| 285 feedback. | |
| 286 | |
| 287 === Landing Changes | |
| 288 | |
| 289 After code review is complete and “Code-Review: +1” has been received from all | |
| 290 reviewers, project members can commit the patch themselves: | |
| 291 | |
| 292 [subs="verbatim,quotes"] | |
| 293 ---- | |
| 294 $ *cd ~/crashpad/crashpad* | |
| 295 $ *git checkout work_branch* | |
| 296 $ *git cl land* | |
| 297 ---- | |
| 298 | |
| 299 Alternatively, patches can be committed by clicking the “Submit” button in the | |
| 300 Gerrit UI. | |
| 301 | |
| 302 Crashpad does not currently have a | |
| 303 https://dev.chromium.org/developers/testing/commit-queue[commit queue], so | |
| 304 contributors who are not project members will have to ask a project member to | |
| 305 commit the patch for them. Project members can commit changes on behalf of | |
| 306 external contributors by clicking the “Submit” button in the Gerrit UI. | |
| 307 | |
| 308 === External Contributions | |
| 309 | |
| 310 Copyright holders must complete the | |
| 311 https://developers.google.com/open-source/cla/individual[Individual Contributor | |
| 312 License Agreement] or | |
| 313 https://developers.google.com/open-source/cla/corporate[Corporate Contributor | |
| 314 License Agreement] as appropriate before any submission can be accepted, and | |
| 315 must be listed in the `AUTHORS` file. Contributors may be listed in the | |
| 316 `CONTRIBUTORS` file. | |
| 317 | |
| 318 == Buildbot | |
| 319 | |
| 320 The https://build.chromium.org/p/client.crashpad/[Crashpad Buildbot] performs | |
| 321 automated builds and tests of Crashpad. Before checking out or updating the | |
| 322 Crashpad source code, and after checking in a new change, it is prudent to check | |
| 323 the Buildbot to ensure that “the tree is green.” | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2555353002:
Update Crashpad to 32981a3ee9d7c2769fb27afa038fe2e194cfa329 (Closed)
