| 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 |
|---|
Chromium Code Reviews
Issue 2731293003:
Move ios documentation from //docs to //docs/ios. (Closed)
