OLD | NEW |
1 # Checking out and building Chromium for iOS | 1 # This document has moved |
2 | 2 |
3 There are instructions for other platforms linked from the | 3 NOTE: Please update your link to this file! |
4 [get the code](get_the_code.md) page. | |
5 | 4 |
6 ## Instructions for Google Employees | 5 The new file location is [//docs/ios/build_instructions.md](ios/build_instructio
ns.md) |
7 | |
8 Are you a Google employee? See | |
9 [go/building-chrome](https://goto.google.com/building-chrome) instead. | |
10 | |
11 [TOC] | |
12 | |
13 ## System requirements | |
14 | |
15 * A 64-bit Mac running 10.11+. | |
16 * [Xcode](https://developer.apple.com/xcode) 8.0+. | |
17 * The OS X 10.10 SDK. Run | |
18 | |
19 ```shell | |
20 $ ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs | |
21 ``` | |
22 | |
23 to check whether you have it. Building with the 10.11 SDK works too, but | |
24 the releases currently use the 10.10 SDK. | |
25 * The current version of the JDK (required for the Closure compiler). | |
26 | |
27 ## Install `depot_tools` | |
28 | |
29 Clone the `depot_tools` repository: | |
30 | |
31 ```shell | |
32 $ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git | |
33 ``` | |
34 | |
35 Add `depot_tools` to the end of your PATH (you will probably want to put this | |
36 in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned `depot_tools` to | |
37 `/path/to/depot_tools`: | |
38 | |
39 ```shell | |
40 $ export PATH="$PATH:/path/to/depot_tools" | |
41 ``` | |
42 | |
43 ## Get the code | |
44 | |
45 Create a `chromium` directory for the checkout and change to it (you can call | |
46 this whatever you like and put it wherever you like, as | |
47 long as the full path has no spaces): | |
48 | |
49 ```shell | |
50 $ mkdir chromium && cd chromium | |
51 ``` | |
52 | |
53 Run the `fetch` tool from `depot_tools` to check out the code and its | |
54 dependencies. | |
55 | |
56 ```shell | |
57 $ fetch ios | |
58 ``` | |
59 | |
60 If you don't want the full repo history, you can save a lot of time by | |
61 adding the `--no-history` flag to `fetch`. | |
62 | |
63 Expect the command to take 30 minutes on even a fast connection, and many | |
64 hours on slower ones. | |
65 | |
66 When `fetch` completes, it will have created a hidden `.gclient` file and a | |
67 directory called `src` in the working directory. The remaining instructions | |
68 assume you have switched to the `src` directory: | |
69 | |
70 ```shell | |
71 $ cd src | |
72 ``` | |
73 | |
74 *Optional*: You can also [install API | |
75 keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your | |
76 build to talk to some Google services, but this is not necessary for most | |
77 development and testing purposes. | |
78 | |
79 ## Setting up the build | |
80 | |
81 Since the iOS build is a bit more complicated than a desktop build, we provide | |
82 `ios/build/tools/setup-gn.py`, which will create four appropriately configured | |
83 build directories under `out` for Release and Debug device and simulator | |
84 builds, and generates an appropriate Xcode workspace as well. | |
85 | |
86 This script is run automatically by fetch (as part of `gclient runhooks`). | |
87 | |
88 You can customize the build by editing the file `$HOME/.setup-gn` (create it if | |
89 it does not exist). Look at `src/ios/build/tools/setup-gn.config` for | |
90 available configuration options. | |
91 | |
92 From this point, you can either build from Xcode or from the command line using | |
93 `ninja`. `setup-gn.py` creates sub-directories named | |
94 `out/${configuration}-${platform}`, so for a `Debug` build for simulator use: | |
95 | |
96 ```shell | |
97 $ ninja -C out/Debug-iphonesimulator gn_all | |
98 ``` | |
99 | |
100 Note: you need to run `setup-gn.py` script every time one of the `BUILD.gn` | |
101 file is updated (either by you or after rebasing). If you forget to run it, | |
102 the list of targets and files in the Xcode solution may be stale. | |
103 | |
104 You can also follow the manual instructions on the | |
105 [Mac page](mac_build_instructions.md), but make sure you set the | |
106 GN arg `target_os="ios"`. | |
107 | |
108 ## Building for device | |
109 | |
110 To be able to build and run Chromium and the tests for devices, you need to | |
111 have an Apple developer account (a free one will work) and the appropriate | |
112 provisioning profiles, then configure the build to use them. | |
113 | |
114 ### Code signing identity | |
115 | |
116 Please refer to the Apple documentation on how to get a code signing identity | |
117 and certificates. You can check that you have a code signing identity correctly | |
118 installed by running the following command. | |
119 | |
120 ```shell | |
121 $ xcrun security find-identity -v -p codesigning | |
122 1) 0123456789ABCDEF0123456789ABCDEF01234567 "iPhone Developer: someone@example
.com (XXXXXXXXXX)" | |
123 1 valid identities found | |
124 ``` | |
125 | |
126 If the command output says you have zero valid identities, then you do not | |
127 have a code signing identity installed and need to get one from Apple. If | |
128 you have more than one identity, the build system may select the wrong one | |
129 automatically, and you can use the `ios_code_signing_identity` gn variable | |
130 to control which one to use by setting it to the identity hash, e.g. to | |
131 `"0123456789ABCDEF0123456789ABCDEF01234567"`. | |
132 | |
133 ### Mobile provisioning profiles | |
134 | |
135 Once you have the code signing identity, you need to decide on a prefix | |
136 for the application bundle identifier. This is controlled by the gn variable | |
137 `ios_app_bundle_id_prefix` and usually corresponds to a reversed domain name | |
138 (the default value is `"org.chromium"`). | |
139 | |
140 You then need to request provisioning profiles from Apple for your devices | |
141 for the following bundle identifiers to build and run Chromium with these | |
142 application extensions: | |
143 | |
144 - `${prefix}.chrome.ios.herebedragons` | |
145 - `${prefix}.chrome.ios.herebedragons.ShareExtension` | |
146 - `${prefix}.chrome.ios.herebedragons.TodayExtension` | |
147 | |
148 All these certificates need to have the "App Groups" | |
149 (`com.apple.security.application-groups`) capability enabled for | |
150 the following groups: | |
151 | |
152 - `group.${prefix}.chrome` | |
153 - `group.${prefix}.common` | |
154 | |
155 The `group.${prefix}.chrome` is only shared by Chromium and its extensions | |
156 to share files and configurations while the `group.${prefix}.common` is shared | |
157 with Chromium and other applications from the same organisation and can be used | |
158 to send commands to Chromium. | |
159 | |
160 ### Mobile provisioning profiles for tests | |
161 | |
162 In addition to that, you need provisioning profiles for the individual test | |
163 suites that you want to run. Their bundle identifier depends on whether the | |
164 gn variable `ios_automatically_manage_certs` is set to true (the default) | |
165 or false. | |
166 | |
167 If set to true, then you just need a provisioning profile for the bundle | |
168 identifier `${prefix}.gtest.generic-unit-test` but you can only have a | |
169 single test application installed on the device (all the test application | |
170 will share the same bundle identifier). | |
171 | |
172 If set to false, then you need a different provisioning profile for each | |
173 test application. Those provisioning profile will have a bundle identifier | |
174 matching the following pattern `${prefix}.gtest.${test-suite-name}` where | |
175 `${test-suite-name}` is the name of the test suite with underscores changed | |
176 to dashes (e.g. `base_unittests` app will use `${prefix}.gest.base-unittests` | |
177 as bundle identifier). | |
178 | |
179 To be able to run the EarlGrey tests on a device, you'll need two provisioning | |
180 profiles for EarlGrey and OCHamcrest frameworks: | |
181 | |
182 - `${prefix}.test.OCHamcrest` | |
183 - `${prefix}.test.EarlGrey` | |
184 | |
185 In addition to that, then you'll need one additional provisioning profile for | |
186 the XCTest module too. This module bundle identifier depends on whether the | |
187 gn variable `ios_automatically_manage_certs` is set to true or false. If set | |
188 to true, then `${prefix}.test.gtest.generic-unit-test.generic-unit-test-module` | |
189 will be used, otherwise it will match the following pattern: | |
190 `${prefix}.test.${test-suite-name}.${test-suite-name}-module`. | |
191 | |
192 ### Other applications | |
193 | |
194 Other applications like `ios_web_shell` usually will require mobile provisioning | |
195 profiles with bundle identifiers that may usually match the following pattern | |
196 `${prefix}.${application-name}` and may require specific capabilities. | |
197 | |
198 Generally, if the mobile provisioning profile is missing then the code signing | |
199 step will fail and will print the bundle identifier of the bundle that could not | |
200 be signed on the command line, e.g.: | |
201 | |
202 ```shell | |
203 $ ninja -C out/Debug-iphoneos ios_web_shell | |
204 ninja: Entering directory `out/Debug-iphoneos' | |
205 FAILED: ios_web_shell.app/ios_web_shell ios_web_shell.app/_CodeSignature/CodeRes
ources ios_web_shell.app/embedded.mobileprovision | |
206 python ../../build/config/ios/codesign.py code-sign-bundle -t=iphoneos -i=012345
6789ABCDEF0123456789ABCDEF01234567 -e=../../build/config/ios/entitlements.plist
-b=obj/ios/web/shell/ios_web_shell ios_web_shell.app | |
207 Error: no mobile provisioning profile found for "org.chromium.ios-web-shell". | |
208 ninja: build stopped: subcommand failed. | |
209 ``` | |
210 | |
211 Here, the build is failing because there are no mobile provisioning profiles | |
212 installed that could sign the `ios_web_shell.app` bundle with the identity | |
213 `0123456789ABCDEF0123456789ABCDEF01234567`. To fix the build, you'll need to | |
214 request such a mobile provisioning profile from Apple. | |
215 | |
216 You can inspect the file passed via the `-e` flag to the `codesign.py` script | |
217 to check which capabilites are required for the mobile provisioning profile | |
218 (e.g. `src/build/config/ios/entitlements.plist` for the above build error, | |
219 remember that the paths are relative to the build directory, not to the source | |
220 directory). | |
221 | |
222 If the required capabilities are not enabled on the mobile provisioning profile, | |
223 then it will be impossible to install the application on a device (Xcode will | |
224 display an error stating that "The application was signed with invalid | |
225 entitlements"). | |
226 | |
227 ## Running apps from the commandline | |
228 | |
229 Any target that is built and runs on the bots (see [below](#Troubleshooting)) | |
230 should run successfully in a local build. To run in the simulator from the | |
231 command line, you can use `iossim`. For example, to run a debug build of | |
232 `Chromium`: | |
233 | |
234 ```shell | |
235 $ out/Debug-iphonesimulator/iossim out/Debug-iphonesimulator/Chromium.app | |
236 ``` | |
237 | |
238 ## Update your checkout | |
239 | |
240 To update an existing checkout, you can run | |
241 | |
242 ```shell | |
243 $ git rebase-update | |
244 $ gclient sync | |
245 ``` | |
246 | |
247 The first command updates the primary Chromium source repository and rebases | |
248 any of your local branches on top of tip-of-tree (aka the Git branch | |
249 `origin/master`). If you don't want to use this script, you can also just use | |
250 `git pull` or other common Git commands to update the repo. | |
251 | |
252 The second command syncs dependencies to the appropriate versions and re-runs | |
253 hooks as needed. | |
254 | |
255 ## Tips, tricks, and troubleshooting | |
256 | |
257 If you have problems building, join us in `#chromium` on `irc.freenode.net` and | |
258 ask there. As mentioned above, be sure that the | |
259 [waterfall](https://build.chromium.org/buildbot/waterfall/) is green and the tre
e | |
260 is open before checking out. This will increase your chances of success. | |
261 | |
262 ### Improving performance of `git status` | |
263 | |
264 `git status` is used frequently to determine the status of your checkout. Due | |
265 to the large number of files in Chromium's checkout, `git status` performance | |
266 can be quite variable. Increasing the system's vnode cache appears to help. | |
267 By default, this command: | |
268 | |
269 ```shell | |
270 $ sysctl -a | egrep kern\..*vnodes | |
271 ``` | |
272 | |
273 Outputs `kern.maxvnodes: 263168` (263168 is 257 * 1024). To increase this | |
274 setting: | |
275 | |
276 ```shell | |
277 $ sudo sysctl kern.maxvnodes=$((512*1024)) | |
278 ``` | |
279 | |
280 Higher values may be appropriate if you routinely move between different | |
281 Chromium checkouts. This setting will reset on reboot, the startup setting can | |
282 be set in `/etc/sysctl.conf`: | |
283 | |
284 ```shell | |
285 $ echo kern.maxvnodes=$((512*1024)) | sudo tee -a /etc/sysctl.conf | |
286 ``` | |
287 | |
288 Or edit the file directly. | |
289 | |
290 If `git --version` reports 2.6 or higher, the following may also improve | |
291 performance of `git status`: | |
292 | |
293 ```shell | |
294 $ git update-index --untracked-cache | |
295 ``` | |
296 | |
297 ### Xcode license agreement | |
298 | |
299 If you're getting the error | |
300 | |
301 > Agreeing to the Xcode/iOS license requires admin privileges, please re-run as | |
302 > root via sudo. | |
303 | |
304 the Xcode license hasn't been accepted yet which (contrary to the message) any | |
305 user can do by running: | |
306 | |
307 ```shell | |
308 $ xcodebuild -license | |
309 ``` | |
310 | |
311 Only accepting for all users of the machine requires root: | |
312 | |
313 ```shell | |
314 $ sudo xcodebuild -license | |
315 ``` | |
OLD | NEW |