OLD | NEW |
1 <!-- | 1 <!-- |
2 Copyright 2015 The Crashpad Authors. All rights reserved. | 2 Copyright 2015 The Crashpad Authors. All rights reserved. |
3 | 3 |
4 Licensed under the Apache License, Version 2.0 (the "License"); | 4 Licensed under the Apache License, Version 2.0 (the "License"); |
5 you may not use this file except in compliance with the License. | 5 you may not use this file except in compliance with the License. |
6 You may obtain a copy of the License at | 6 You may obtain a copy of the License at |
7 | 7 |
8 http://www.apache.org/licenses/LICENSE-2.0 | 8 http://www.apache.org/licenses/LICENSE-2.0 |
9 | 9 |
10 Unless required by applicable law or agreed to in writing, software | 10 Unless required by applicable law or agreed to in writing, software |
(...skipping 73 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
84 Crashpad uses [GYP](https://gyp.gsrc.io/) to generate | 84 Crashpad uses [GYP](https://gyp.gsrc.io/) to generate |
85 [Ninja](https://ninja-build.org/) build files. The build is described by `.gyp` | 85 [Ninja](https://ninja-build.org/) build files. The build is described by `.gyp` |
86 files throughout the Crashpad source code tree. The | 86 files throughout the Crashpad source code tree. The |
87 [`build/gyp_crashpad.py`](https://chromium.googlesource.com/crashpad/crashpad/+/
master/build/gyp_crashpad.py) | 87 [`build/gyp_crashpad.py`](https://chromium.googlesource.com/crashpad/crashpad/+/
master/build/gyp_crashpad.py) |
88 script runs GYP properly for Crashpad, and is also called when you run `fetch | 88 script runs GYP properly for Crashpad, and is also called when you run `fetch |
89 crashpad`, `gclient sync`, or `gclient runhooks`. | 89 crashpad`, `gclient sync`, or `gclient runhooks`. |
90 | 90 |
91 The Ninja build files and build output are in the `out` directory. Both debug- | 91 The Ninja build files and build output are in the `out` directory. Both debug- |
92 and release-mode configurations are available. The examples below show the debug | 92 and release-mode configurations are available. The examples below show the debug |
93 configuration. To build and test the release configuration, substitute `Release` | 93 configuration. To build and test the release configuration, substitute `Release` |
94 for `Debug`. | 94 for `Debug`. On Windows, four configurations are available: `Debug` and |
| 95 `Release` produce 32-bit x86 executables, and `Debug_x64` and `Release_x64` |
| 96 produce x86_64 executables. |
95 | 97 |
96 ``` | 98 ``` |
97 $ cd ~/crashpad/crashpad | 99 $ cd ~/crashpad/crashpad |
98 $ ninja -C out/Debug | 100 $ ninja -C out/Debug |
99 ``` | 101 ``` |
100 | 102 |
101 Ninja is part of the | 103 Ninja is part of the |
102 [depot_tools](https://dev.chromium.org/developers/how-tos/depottools). There’s | 104 [depot_tools](https://dev.chromium.org/developers/how-tos/depottools). There’s |
103 no need to install it separately. | 105 no need to install it separately. |
104 | 106 |
105 ### Android | 107 ### Android |
106 | 108 |
107 Crashpad’s Android port is in its early stages. This build relies on | 109 Crashpad’s Android port is in its early stages. This build relies on |
108 cross-compilation. It’s possible to develop Crashpad for Android on any platform | 110 cross-compilation. It’s possible to develop Crashpad for Android on any platform |
109 that the [Android NDK (Native Development | 111 that the [Android NDK (Native Development |
110 Kit)](https://developer.android.com/ndk/) runs on. | 112 Kit)](https://developer.android.com/ndk/) runs on. |
111 | 113 |
112 If it’s not already present on your system, [download the NDK package for your | 114 If it’s not already present on your system, [download the NDK package for your |
113 system](https://developer.android.com/ndk/downloads/) and expand it to a | 115 system](https://developer.android.com/ndk/downloads/) and expand it to a |
114 suitable location. These instructions assume that it’s been expanded to | 116 suitable location. These instructions assume that it’s been expanded to |
115 `~/android-ndk-r13`. | 117 `~/android-ndk-r14`. |
116 | 118 |
117 To build Crashpad, portions of the NDK must be reassembled into a [standalone | 119 To build Crashpad, portions of the NDK must be reassembled into a [standalone |
118 toolchain](https://developer.android.com/ndk/guides/standalone_toolchain.html). | 120 toolchain](https://developer.android.com/ndk/guides/standalone_toolchain.html). |
119 This is a repackaged subset of the NDK suitable for cross-compiling for a single | 121 This is a repackaged subset of the NDK suitable for cross-compiling for a single |
120 Android architecture (such as `arm`, `arm64`, `x86`, and `x86_64`) targeting a | 122 Android architecture (such as `arm`, `arm64`, `x86`, and `x86_64`) targeting a |
121 specific [Android API | 123 specific [Android API |
122 level](https://source.android.com/source/build-numbers.html). The standalone | 124 level](https://source.android.com/source/build-numbers.html). The standalone |
123 toolchain only needs to be built from the NDK one time for each set of options | 125 toolchain only needs to be built from the NDK one time for each set of options |
124 desired. To build a standalone toolchain targeting 64-bit ARM and API level 21 | 126 desired. To build a standalone toolchain targeting 64-bit ARM and API level 21 |
125 (Android 5.0 “Lollipop”), run: | 127 (Android 5.0 “Lollipop”), run: |
126 | 128 |
127 ``` | 129 ``` |
128 $ cd ~ | 130 $ cd ~ |
129 $ python android-ndk-r13/build/tools/make_standalone_toolchain.py \ | 131 $ python android-ndk-r14/build/tools/make_standalone_toolchain.py \ |
130 --arch=arm64 --api=21 --install-dir=android-ndk-r13_arm64_api21 | 132 --arch=arm64 --api=21 --install-dir=android-ndk-r14_arm64_api21 |
131 ``` | 133 ``` |
132 | 134 |
133 Note that Chrome uses Android API level 21 for 64-bit platforms and 16 for | 135 Note that Chrome uses Android API level 21 for 64-bit platforms and 16 for |
134 32-bit platforms. See Chrome’s | 136 32-bit platforms. See Chrome’s |
135 [`build/config/android/config.gni`](https://chromium.googlesource.com/chromium/s
rc/+/master/build/config/android/config.gni) | 137 [`build/config/android/config.gni`](https://chromium.googlesource.com/chromium/s
rc/+/master/build/config/android/config.gni) |
136 which sets `_android_api_level` and `_android64_api_level`. | 138 which sets `_android_api_level` and `_android64_api_level`. |
137 | 139 |
138 To configure a Crashpad build for Android using this standalone toolchain, set | 140 To configure a Crashpad build for Android using the standalone toolchain |
139 several environment variables directing the build to the standalone toolchain, | 141 assembled above, use `gyp_crashpad_android.py`. This script is a wrapper for |
140 along with GYP options to identify an Android build. This must be done after any | 142 `gyp_crashpad.py` that sets several environment variables directing the build to |
141 `gclient sync`, or instead of any `gclient runhooks` operation. The environment | 143 the standalone toolchain, and several GYP options to identify an Android build. |
142 variables only need to be set for this `gyp_crashpad.py` invocation, and need | 144 This must be done after any `gclient sync`, or instead of any `gclient runhooks` |
143 not be permanent. | 145 operation. |
144 | 146 |
145 ``` | 147 ``` |
146 $ cd ~/crashpad/crashpad | 148 $ cd ~/crashpad/crashpad |
147 $ CC_target=~/android-ndk-r13_arm64_api21/bin/clang \ | 149 $ python build/gyp_crashpad_android.py \ |
148 CXX_target=~/android-ndk-r13_arm64_api21/bin/clang++ \ | 150 --ndk ~/android-ndk-r14_arm64_api21 \ |
149 AR_target=~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-ar \ | 151 --generator-output out/android_arm64_api21 |
150 NM_target=~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-nm \ | |
151 READELF_target=~/android-ndk-r13_arm64_api21/bin/aarch64-linux-android-readelf
\ | |
152 python build/gyp_crashpad.py \ | |
153 -DOS=android -Dtarget_arch=arm64 -Dclang=1 \ | |
154 --generator-output=out_android_arm64_api21 -f ninja-android | |
155 ``` | 152 ``` |
156 | 153 |
157 It is also possible to use GCC instead of Clang by making the appropriate | 154 `gyp_crashpad_android.py` detects the build type based on the characteristics of |
158 substitutions: `aarch64-linux-android-gcc` for `CC_target`; | 155 the standalone toolchain given in its `--ndk` argument. |
159 `aarch64-linux-android-g++` for `CXX_target`; and `-Dclang=0` as an argument to | |
160 `gyp_crashpad.py`. | |
161 | 156 |
162 Target “triplets” to use for `ar`, `nm`, `readelf`, `gcc`, and `g++` are: | 157 `gyp_crashpad_android.py` sets the build up to use Clang by default. It’s also |
| 158 possible to use GCC by providing the `--compiler=gcc` argument to |
| 159 `gyp_crashpad_android.py`. |
163 | 160 |
164 | Architecture | Target “triplet” | | 161 The Android port is incomplete, but targets known to be working include |
165 |:-------------|:------------------------| | 162 `crashpad_test`, `crashpad_util`, and their tests. This list will grow over |
166 | `arm` | `arm-linux-androideabi` | | 163 time. To build, direct `ninja` to the specific `out` directory chosen by the |
167 | `arm64` | `aarch64-linux-android` | | 164 `--generator-output` argument to `gyp_crashpad_android.py`. |
168 | `x86` | `i686-linux-android` | | |
169 | `x86_64` | `x86_64-linux-android` | | |
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 | 165 |
176 ``` | 166 ``` |
177 $ ninja -C out_android_arm64_api21/out/Debug crashpad_test_test | 167 $ ninja -C out/android_arm64_api21/out/Debug \ |
| 168 crashpad_test_test crashpad_util_test |
178 ``` | 169 ``` |
179 | 170 |
180 ## Testing | 171 ## Testing |
181 | 172 |
182 Crashpad uses [Google Test](https://github.com/google/googletest/) as its | 173 Crashpad uses [Google Test](https://github.com/google/googletest/) as its |
183 unit-testing framework, and some tests use [Google | 174 unit-testing framework, and some tests use [Google |
184 Mock](https://github.com/google/googletest/tree/master/googlemock/) as well. Its | 175 Mock](https://github.com/google/googletest/tree/master/googlemock/) as well. Its |
185 tests are currently split up into several test executables, each dedicated to | 176 tests are currently split up into several test executables, each dedicated to |
186 testing a different component. This may change in the future. After a successful | 177 testing a different component. This may change in the future. After a successful |
187 build, the test executables will be found at `out/Debug/crashpad_*_test`. | 178 build, the test executables will be found at `out/Debug/crashpad_*_test`. |
188 | 179 |
189 ``` | 180 ``` |
190 $ cd ~/crashpad/crashpad | 181 $ cd ~/crashpad/crashpad |
191 $ out/Debug/crashpad_minidump_test | 182 $ out/Debug/crashpad_minidump_test |
192 $ out/Debug/crashpad_util_test | 183 $ out/Debug/crashpad_util_test |
193 ``` | 184 ``` |
194 | 185 |
195 A script is provided to run all of Crashpad’s tests. It accepts a single | 186 A script is provided to run all of Crashpad’s tests. It accepts a single |
196 argument that tells it which configuration to test. | 187 argument, a path to the directory containing the test executables. |
197 | 188 |
198 ``` | 189 ``` |
199 $ cd ~/crashpad/crashpad | 190 $ cd ~/crashpad/crashpad |
200 $ python build/run_tests.py Debug | 191 $ python build/run_tests.py out/Debug |
201 ``` | 192 ``` |
202 | 193 |
203 ### Android | 194 ### Android |
204 | 195 |
205 To test on Android, use [ADB (Android Debug | 196 To test on Android, use [ADB (Android Debug |
206 Bridge)](https://developer.android.com/studio/command-line/adb.html) to `adb | 197 Bridge)](https://developer.android.com/studio/command-line/adb.html) to `adb |
207 push` test executables and test data to a device or emulator, then use `adb | 198 push` test executables and test data to a device or emulator, then use `adb |
208 shell` to get a shell to run the test executables from. ADB is part of the | 199 shell` to get a shell to run the test executables from. ADB is part of the |
209 [Android SDK](https://developer.android.com/sdk/). Note that it is sufficient to | 200 [Android SDK](https://developer.android.com/sdk/). Note that it is sufficient to |
210 install just the command-line tools. The entire Android Studio IDE is not | 201 install just the command-line tools. The entire Android Studio IDE is not |
211 necessary to obtain ADB. | 202 necessary to obtain ADB. |
212 | 203 |
213 This example runs `crashpad_test_test` on a device. This test executable has a | 204 This example runs `crashpad_test_test` on a device. This test executable has a |
214 run-time dependency on a second executable and a test data file, which are also | 205 run-time dependency on a second executable and a test data file, which are also |
215 transferred to the device prior to running the test. | 206 transferred to the device prior to running the test. |
216 | 207 |
217 ``` | 208 ``` |
218 $ cd ~/crashpad/crashpad | 209 $ cd ~/crashpad/crashpad |
219 $ adb push out_android_arm64_api21/out/Debug/crashpad_test_test /data/local/tmp/ | 210 $ adb push out/android_arm64_api21/out/Debug/crashpad_test_test /data/local/tmp/ |
220 [100%] /data/local/tmp/crashpad_test_test | 211 [100%] /data/local/tmp/crashpad_test_test |
221 $ adb push \ | 212 $ adb push \ |
222 out_android_arm64_api21/out/Debug/crashpad_test_test_multiprocess_exec_tes
t_child \ | 213 out/android_arm64_api21/out/Debug/crashpad_test_test_multiprocess_exec_tes
t_child \ |
223 /data/local/tmp/ | 214 /data/local/tmp/ |
224 [100%] /data/local/tmp/crashpad_test_test_multiprocess_exec_test_child | 215 [100%] /data/local/tmp/crashpad_test_test_multiprocess_exec_test_child |
225 $ adb shell mkdir -p /data/local/tmp/crashpad_test_data_root/test | 216 $ adb shell mkdir -p /data/local/tmp/crashpad_test_data_root/test |
226 $ adb push test/paths_test_data_root.txt \ | 217 $ adb push test/paths_test_data_root.txt \ |
227 /data/local/tmp/crashpad_test_data_root/test/ | 218 /data/local/tmp/crashpad_test_data_root/test/ |
228 [100%] /data/local/tmp/crashpad_test_data_root/test/paths_test_data_root.txt | 219 [100%] /data/local/tmp/crashpad_test_data_root/test/paths_test_data_root.txt |
229 $ adb shell | 220 $ adb shell |
230 device:/ $ cd /data/local/tmp | 221 device:/ $ cd /data/local/tmp |
231 device:/data/local/tmp $ CRASHPAD_TEST_DATA_ROOT=crashpad_test_data_root \ | 222 device:/data/local/tmp $ CRASHPAD_TEST_DATA_ROOT=crashpad_test_data_root \ |
232 ./crashpad_test_test | 223 ./crashpad_test_test |
(...skipping 82 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
315 file. Contributors may be listed in the | 306 file. Contributors may be listed in the |
316 [`CONTRIBUTORS`](https://chromium.googlesource.com/crashpad/crashpad/+/master/CO
NTRIBUTORS) | 307 [`CONTRIBUTORS`](https://chromium.googlesource.com/crashpad/crashpad/+/master/CO
NTRIBUTORS) |
317 file. | 308 file. |
318 | 309 |
319 ## Buildbot | 310 ## Buildbot |
320 | 311 |
321 The [Crashpad Buildbot](https://build.chromium.org/p/client.crashpad/) performs | 312 The [Crashpad Buildbot](https://build.chromium.org/p/client.crashpad/) performs |
322 automated builds and tests of Crashpad. Before checking out or updating the | 313 automated builds and tests of Crashpad. Before checking out or updating the |
323 Crashpad source code, and after checking in a new change, it is prudent to check | 314 Crashpad source code, and after checking in a new change, it is prudent to check |
324 the Buildbot to ensure that “the tree is green.” | 315 the Buildbot to ensure that “the tree is green.” |
OLD | NEW |