OLD | NEW |
1 // Copyright 2015 The Crashpad Authors. All rights reserved. | 1 // Copyright 2015 The Crashpad Authors. All rights reserved. |
2 // | 2 // |
3 // Licensed under the Apache License, Version 2.0 (the "License"); | 3 // Licensed under the Apache License, Version 2.0 (the "License"); |
4 // you may not use this file except in compliance with 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 | 5 // You may obtain a copy of the License at |
6 // | 6 // |
7 // http://www.apache.org/licenses/LICENSE-2.0 | 7 // http://www.apache.org/licenses/LICENSE-2.0 |
8 // | 8 // |
9 // Unless required by applicable law or agreed to in writing, software | 9 // Unless required by applicable law or agreed to in writing, software |
10 // distributed under the License is distributed on an "AS IS" BASIS, | 10 // distributed under the License is distributed on an "AS IS" BASIS, |
(...skipping 20 matching lines...) Expand all Loading... |
31 https://chromium.googlesource.com/chromium/mini_chromium/+/master/README[mini_ch
romium’s | 31 https://chromium.googlesource.com/chromium/mini_chromium/+/master/README[mini_ch
romium’s |
32 README] provides more detail. | 32 README] provides more detail. |
33 | 33 |
34 == Prerequisites | 34 == Prerequisites |
35 | 35 |
36 To develop Crashpad, the following tools are necessary, and must be | 36 To develop Crashpad, the following tools are necessary, and must be |
37 present in the `$PATH` environment variable: | 37 present in the `$PATH` environment variable: |
38 | 38 |
39 * Chromium’s | 39 * Chromium’s |
40 https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. | 40 https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. |
41 * http://git-scm.com/[Git]. This is provided by Xcode on Mac OS X and by | 41 * https://git-scm.com/[Git]. This is provided by Xcode on Mac OS X and by |
42 depot_tools on Windows. | 42 depot_tools on Windows. |
43 * https://www.python.org/[Python]. This is provided by the operating system on | 43 * https://www.python.org/[Python]. This is provided by the operating system on |
44 Mac OS X, and by depot_tools on Windows. | 44 Mac OS X, and by depot_tools on Windows. |
45 * Appropriate development tools. For Mac OS X, this is | 45 * Appropriate development tools. For Mac OS X, this is |
46 https://developer.apple.com/xcode/[Xcode], and for Windows, it’s | 46 https://developer.apple.com/xcode/[Xcode], and for Windows, it’s |
47 https://www.visualstudio.com/[Visual Studio]. | 47 https://www.visualstudio.com/[Visual Studio]. |
48 | 48 |
49 == Getting the Source Code | 49 == Getting the Source Code |
50 | 50 |
51 The main source code repository is a Git repository hosted at | 51 The main source code repository is a Git repository hosted at |
(...skipping 10 matching lines...) Expand all Loading... |
62 | 62 |
63 === Initial Checkout | 63 === Initial Checkout |
64 | 64 |
65 [subs="verbatim,quotes"] | 65 [subs="verbatim,quotes"] |
66 ---- | 66 ---- |
67 $ *mkdir \~/crashpad* | 67 $ *mkdir \~/crashpad* |
68 $ *cd ~/crashpad* | 68 $ *cd ~/crashpad* |
69 $ *fetch crashpad* | 69 $ *fetch crashpad* |
70 ---- | 70 ---- |
71 | 71 |
72 `fetch crashpad` performs the initial `gclient sync`, establishing a | 72 `fetch crashpad` performs the initial `git clone` and `gclient sync`, |
73 fully-functional local checkout. | 73 establishing a fully-functional local checkout. |
74 | 74 |
75 === Subsequent Checkouts | 75 === Subsequent Checkouts |
76 | 76 |
77 [subs="verbatim,quotes"] | 77 [subs="verbatim,quotes"] |
78 ---- | 78 ---- |
79 $ *cd ~/crashpad/crashpad* | 79 $ *cd ~/crashpad/crashpad* |
80 $ *git pull -r* | 80 $ *git pull -r* |
81 $ *gclient sync* | 81 $ *gclient sync* |
82 ---- | 82 ---- |
83 | 83 |
84 == Building | 84 == Building |
85 | 85 |
86 Crashpad uses https://gyp.gsrc.io/[GYP] to generate | 86 Crashpad uses https://gyp.gsrc.io/[GYP] to generate |
87 https://martine.github.io/ninja/[Ninja] build files. The build is described by | 87 https://ninja-build.org/[Ninja] build files. The build is described by `.gyp` |
88 `.gyp` files throughout the Crashpad source code tree. The | 88 files throughout the Crashpad source code tree. The `build/gyp_crashpad.py` |
89 `build/gyp_crashpad.py` script runs GYP properly for Crashpad, and is also | 89 script runs GYP properly for Crashpad, and is also called when you run `fetch |
90 called when you run `fetch crashpad`, `gclient sync`, or `gclient runhooks`. | 90 crashpad`, `gclient sync`, or `gclient runhooks`. |
91 | 91 |
92 The Ninja build files and build output are in the `out` directory. Both debug- | 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 | 93 and release-mode configurations are available. The examples below show the debug |
94 configuration. To build and test the release configuration, substitute `Release` | 94 configuration. To build and test the release configuration, substitute `Release` |
95 for `Debug`. | 95 for `Debug`. |
96 | 96 |
97 [subs="verbatim,quotes"] | 97 [subs="verbatim,quotes"] |
98 ---- | 98 ---- |
99 $ *cd ~/crashpad/crashpad* | 99 $ *cd ~/crashpad/crashpad* |
100 $ *ninja -C out/Debug* | 100 $ *ninja -C out/Debug* |
101 ---- | 101 ---- |
102 | 102 |
103 Ninja is part of the | 103 Ninja is part of the |
104 https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no | 104 https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no |
105 need to install it separately. | 105 need to install it separately. |
106 | 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 |
107 == Testing | 181 == Testing |
108 | 182 |
109 Crashpad uses https://github.com/google/googletest/[Google Test] as its | 183 Crashpad uses https://github.com/google/googletest/[Google Test] as its |
110 unit-testing framework, and some tests use | 184 unit-testing framework, and some tests use |
111 https://github.com/google/googletest/tree/master/googlemock/[Google Mock] as | 185 https://github.com/google/googletest/tree/master/googlemock/[Google Mock] as |
112 well. Its tests are currently split up into several test executables, each | 186 well. Its tests are currently split up into several test executables, each |
113 dedicated to testing a different component. This may change in the future. After | 187 dedicated to testing a different component. This may change in the future. After |
114 a successful build, the test executables will be found at | 188 a successful build, the test executables will be found at |
115 `out/Debug/crashpad_*_test`. | 189 `out/Debug/crashpad_*_test`. |
116 | 190 |
117 [subs="verbatim,quotes"] | 191 [subs="verbatim,quotes"] |
118 ---- | 192 ---- |
119 $ *cd ~/crashpad/crashpad* | 193 $ *cd ~/crashpad/crashpad* |
120 $ *out/Debug/crashpad_minidump_test* | 194 $ *out/Debug/crashpad_minidump_test* |
121 $ *out/Debug/crashpad_util_test* | 195 $ *out/Debug/crashpad_util_test* |
122 ---- | 196 ---- |
123 | 197 |
124 A script is provided to run all of Crashpad’s tests. It accepts a single | 198 A script is provided to run all of Crashpad’s tests. It accepts a single |
125 argument that tells it which configuration to test. | 199 argument that tells it which configuration to test. |
126 | 200 |
127 [subs="verbatim,quotes"] | 201 [subs="verbatim,quotes"] |
128 ---- | 202 ---- |
129 $ *cd ~/crashpad/crashpad* | 203 $ *cd ~/crashpad/crashpad* |
130 $ *python build/run_tests.py Debug* | 204 $ *python build/run_tests.py Debug* |
131 ---- | 205 ---- |
132 | 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 |
133 == Contributing | 240 == Contributing |
134 | 241 |
135 Crashpad’s contribution process is very similar to | 242 Crashpad’s contribution process is very similar to |
136 https://dev.chromium.org/developers/contributing-code[Chromium’s contribution | 243 https://dev.chromium.org/developers/contributing-code[Chromium’s contribution |
137 process]. | 244 process]. |
138 | 245 |
139 === Code Review | 246 === Code Review |
140 | 247 |
141 A code review must be conducted for every change to Crashpad’s source code. Code | 248 A code review must be conducted for every change to Crashpad’s source code. Code |
142 review is conducted on https://codereview.chromium.org/[Chromium’s Rietveld] | 249 review is conducted on https://chromium-review.googlesource.com/[Chromium’s |
143 system, and all code reviews must be sent to an appropriate reviewer, with a Cc | 250 Gerrit] system, and all code reviews must be sent to an appropriate reviewer, |
144 sent to | 251 with a Cc sent to |
145 https://groups.google.com/a/chromium.org/group/crashpad-dev[crashpad-dev]. The | 252 https://groups.google.com/a/chromium.org/group/crashpad-dev[crashpad-dev]. The |
146 `codereview.settings` file specifies this environment to `git-cl`. | 253 https://chromium.googlesource.com/crashpad/crashpad/+/master/codereview.settings
[`codereview.settings`] |
| 254 file specifies this environment to `git-cl`. |
147 | 255 |
148 `git-cl` is part of the | 256 `git-cl` is part of the |
149 https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no | 257 https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no |
150 need to install it separately. | 258 need to install it separately. |
151 | 259 |
152 [subs="verbatim,quotes"] | 260 [subs="verbatim,quotes"] |
153 ---- | 261 ---- |
154 $ *cd ~/crashpad/crashpad* | 262 $ *cd ~/crashpad/crashpad* |
155 $ *git checkout -b work_branch origin/master* | 263 $ *git checkout -b work_branch origin/master* |
156 _…do some work…_ | 264 _…do some work…_ |
157 $ *git add …* | 265 $ *git add …* |
158 $ *git commit* | 266 $ *git commit* |
159 $ *git cl upload* | 267 $ *git cl upload* |
160 ---- | 268 ---- |
161 | 269 |
162 Uploading a patch to Rietveld does not automatically request a review. You must | 270 The https://polygerrit.appspot.com/[PolyGerrit interface] to Gerrit, undergoing |
163 select a reviewer and mail your request to them (with a Cc to crashpad-dev) from | 271 active development, is recommended. To switch from the classic GWT-based Gerrit |
164 the Rietveld issue page after running `git cl upload`. If you have lost track of | 272 UI to PolyGerrit, click the PolyGerrit link in a Gerrit review page’s footer. |
165 the issue page, `git cl issue` will remind you of its URL. Alternatively, you | |
166 can request review when uploading to Rietveld by using `git cl upload | |
167 --send-mail` | |
168 | 273 |
169 Git branches maintain their association with Rietveld issues, so if you need to | 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 |
170 make changes based on review feedback, you can do so on the correct Git branch, | 282 make changes based on review feedback, you can do so on the correct Git branch, |
171 committing your changes locally with `git commit`. You can then upload a new | 283 committing your changes locally with `git commit`. You can then upload a new |
172 patch set with `git cl upload` and let your reviewer know you’ve addressed the | 284 patch set with `git cl upload` and let your reviewer know you’ve addressed the |
173 feedback. | 285 feedback. |
174 | 286 |
175 === Landing Changes | 287 === Landing Changes |
176 | 288 |
177 After code review is complete and “LGTM” (“looks good to me”) has been received | 289 After code review is complete and “Code-Review: +1” has been received from all |
178 from all reviewers, project members can commit the patch themselves: | 290 reviewers, project members can commit the patch themselves: |
179 | 291 |
180 [subs="verbatim,quotes"] | 292 [subs="verbatim,quotes"] |
181 ---- | 293 ---- |
182 $ *cd ~/crashpad/crashpad* | 294 $ *cd ~/crashpad/crashpad* |
183 $ *git checkout work_branch* | 295 $ *git checkout work_branch* |
184 $ *git cl land* | 296 $ *git cl land* |
185 ---- | 297 ---- |
186 | 298 |
| 299 Alternatively, patches can be committed by clicking the “Submit” button in the |
| 300 Gerrit UI. |
| 301 |
187 Crashpad does not currently have a | 302 Crashpad does not currently have a |
188 https://dev.chromium.org/developers/testing/commit-queue[commit queue], so | 303 https://dev.chromium.org/developers/testing/commit-queue[commit queue], so |
189 contributors that are not project members will have to ask a project member to | 304 contributors who are not project members will have to ask a project member to |
190 commit the patch for them. Project members can commit changes on behalf of | 305 commit the patch for them. Project members can commit changes on behalf of |
191 external contributors by patching the change into a local branch and landing it: | 306 external contributors by clicking the “Submit” button in the Gerrit UI. |
192 | |
193 [subs="verbatim,quotes"] | |
194 ---- | |
195 $ *cd ~/crashpad/crashpad* | |
196 $ *git checkout -b for_external_contributor origin/master* | |
197 $ *git cl patch 12345678* _# 12345678 is the Rietveld issue number_ | |
198 $ *git cl land -c \'External Contributor <external@contributor.org>'* | |
199 ---- | |
200 | 307 |
201 === External Contributions | 308 === External Contributions |
202 | 309 |
203 Copyright holders must complete the | 310 Copyright holders must complete the |
204 https://developers.google.com/open-source/cla/individual[Individual Contributor | 311 https://developers.google.com/open-source/cla/individual[Individual Contributor |
205 License Agreement] or | 312 License Agreement] or |
206 https://developers.google.com/open-source/cla/corporate[Corporate Contributor | 313 https://developers.google.com/open-source/cla/corporate[Corporate Contributor |
207 License Agreement] as appropriate before any submission can be accepted, and | 314 License Agreement] as appropriate before any submission can be accepted, and |
208 must be listed in the `AUTHORS` file. Contributors may be listed in the | 315 must be listed in the `AUTHORS` file. Contributors may be listed in the |
209 `CONTRIBUTORS` file. | 316 `CONTRIBUTORS` file. |
210 | 317 |
211 == Buildbot | 318 == Buildbot |
212 | 319 |
213 The https://build.chromium.org/p/client.crashpad/[Crashpad Buildbot] performs | 320 The https://build.chromium.org/p/client.crashpad/[Crashpad Buildbot] performs |
214 automated builds and tests of Crashpad. Before checking out or updating the | 321 automated builds and tests of Crashpad. Before checking out or updating the |
215 Crashpad source code, and after checking in a new change, it is prudent to check | 322 Crashpad source code, and after checking in a new change, it is prudent to check |
216 the Buildbot to ensure that “the tree is green.” | 323 the Buildbot to ensure that “the tree is green.” |
OLD | NEW |