OLD | NEW |
1 # Checking out and building Chromium for iOS | 1 # Checking out and building Chromium for iOS |
2 | 2 |
3 There are instructions for other platforms linked from the | 3 There are instructions for other platforms linked from the |
4 [get the code](get_the_code.md) page. | 4 [get the code](get_the_code.md) page. |
5 | 5 |
6 ## Instructions for Google Employees | 6 ## Instructions for Google Employees |
7 | 7 |
8 Are you a Google employee? See | 8 Are you a Google employee? See |
9 [go/building-chrome](https://goto.google.com/building-chrome) instead. | 9 [go/building-chrome](https://goto.google.com/building-chrome) instead. |
10 | 10 |
11 [TOC] | 11 [TOC] |
12 | 12 |
13 ## System requirements | 13 ## System requirements |
14 | 14 |
15 * A 64-bit Mac running 10.11+. | 15 * A 64-bit Mac running 10.11+. |
16 * [Xcode](https://developer.apple.com/xcode) 8.0+. | 16 * [Xcode](https://developer.apple.com/xcode) 8.0+. |
17 * The OS X 10.10 SDK. Run | 17 * The OS X 10.10 SDK. Run |
18 | 18 |
19 ```shell | 19 ```shell |
20 $ ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs | 20 $ ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs |
21 ``` | 21 ``` |
22 | 22 |
23 to check whether you have it. Building with the 10.11 SDK works too, but | 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. | 24 the releases currently use the 10.10 SDK. |
25 * The current version of the JDK (required for the Closure compiler). | 25 * The current version of the JDK (required for the Closure compiler). |
26 | 26 |
27 ## Install `depot_tools` | 27 ## Install `depot_tools` |
28 | 28 |
29 Clone the `depot_tools` repository: | 29 Clone the `depot_tools` repository: |
30 | 30 |
31 ```shell | 31 ```shell |
32 $ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git | 32 $ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git |
(...skipping 41 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
74 *Optional*: You can also [install API | 74 *Optional*: You can also [install API |
75 keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your | 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 | 76 build to talk to some Google services, but this is not necessary for most |
77 development and testing purposes. | 77 development and testing purposes. |
78 | 78 |
79 ## Setting up the build | 79 ## Setting up the build |
80 | 80 |
81 Since the iOS build is a bit more complicated than a desktop build, we provide | 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 | 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 | 83 build directories under `out` for Release and Debug device and simulator |
84 builds, and generates an appropriate Xcode workspace as well. | 84 builds, and generates an appropriate Xcode workspace as well. |
85 | 85 |
86 This script is run automatically by fetch (as part of `gclient runhooks`). | 86 This script is run automatically by fetch (as part of `gclient runhooks`). |
87 | 87 |
88 You can customize the build by editing the file `$HOME/.setup-gn` (create it if | 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 | 89 it does not exist). Look at `src/ios/build/tools/setup-gn.config` for |
90 available configuration options. | 90 available configuration options. |
91 | 91 |
92 From this point, you can either build from Xcode or from the command line using | 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 | 93 `ninja`. `setup-gn.py` creates sub-directories named |
94 `out/${configuration}-${platform}`, so for a `Debug` build for simulator use: | 94 `out/${configuration}-${platform}`, so for a `Debug` build for simulator use: |
95 | 95 |
96 ```shell | 96 ```shell |
97 $ ninja -C out/Debug-iphonesimulator gn_all | 97 $ ninja -C out/Debug-iphonesimulator gn_all |
98 ``` | 98 ``` |
99 | 99 |
100 Note: you need to run `setup-gn.py` script every time one of the `BUILD.gn` | 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, | 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. | 102 the list of targets and files in the Xcode solution may be stale. |
103 | 103 |
104 You can also follow the manual instructions on the | 104 You can also follow the manual instructions on the |
105 [Mac page](mac_build_instructions.md), but make sure you set the | 105 [Mac page](mac_build_instructions.md), but make sure you set the |
106 GN arg `target_os="ios"`. | 106 GN arg `target_os="ios"`. |
107 | 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 |
108 ## Running apps from the commandline | 227 ## Running apps from the commandline |
109 | 228 |
110 Any target that is built and runs on the bots (see [below](#Troubleshooting)) | 229 Any target that is built and runs on the bots (see [below](#Troubleshooting)) |
111 should run successfully in a local build. To run in the simulator from the | 230 should run successfully in a local build. To run in the simulator from the |
112 command line, you can use `iossim`. For example, to run a debug build of | 231 command line, you can use `iossim`. For example, to run a debug build of |
113 `Chromium`: | 232 `Chromium`: |
114 | 233 |
115 ```shell | 234 ```shell |
116 $ out/Debug-iphonesimulator/iossim out/Debug-iphonesimulator/Chromium.app | 235 $ out/Debug-iphonesimulator/iossim out/Debug-iphonesimulator/Chromium.app |
117 ``` | 236 ``` |
(...skipping 69 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
187 | 306 |
188 ```shell | 307 ```shell |
189 $ xcodebuild -license | 308 $ xcodebuild -license |
190 ``` | 309 ``` |
191 | 310 |
192 Only accepting for all users of the machine requires root: | 311 Only accepting for all users of the machine requires root: |
193 | 312 |
194 ```shell | 313 ```shell |
195 $ sudo xcodebuild -license | 314 $ sudo xcodebuild -license |
196 ``` | 315 ``` |
OLD | NEW |