blob: e45bfcb5711ec7a159b36d3adaf0bb3d8b25d7da [file] [log] [blame] [view]
michaeldo8cccf2142017-03-06 22:12:021# Checking out and building Chromium for iOS
2
3There are instructions for other platforms linked from the
4[get the code](../get_the_code.md) page.
5
6## Instructions for Google Employees
7
8Are you a Google employee? See
9[go/building-chrome](https://goto.google.com/building-chrome) instead.
10
11[TOC]
12
13## System requirements
14
Sylvain Defresne92455aa2021-09-29 15:01:3615* A 64-bit Mac running 11.3 or later.
Sylvain Defresne9137dcc2022-02-24 16:14:1516* [Xcode](https://developer.apple.com/xcode) 13.1 or higher.
michaeldo8cccf2142017-03-06 22:12:0217
18## Install `depot_tools`
19
20Clone the `depot_tools` repository:
21
22```shell
23$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
24```
25
26Add `depot_tools` to the end of your PATH (you will probably want to put this
27in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned `depot_tools` to
28`/path/to/depot_tools`:
29
30```shell
31$ export PATH="$PATH:/path/to/depot_tools"
32```
33
34## Get the code
35
36Create a `chromium` directory for the checkout and change to it (you can call
37this whatever you like and put it wherever you like, as
38long as the full path has no spaces):
39
40```shell
41$ mkdir chromium && cd chromium
42```
43
44Run the `fetch` tool from `depot_tools` to check out the code and its
45dependencies.
46
47```shell
48$ fetch ios
49```
50
51If you don't want the full repo history, you can save a lot of time by
52adding the `--no-history` flag to `fetch`.
53
54Expect the command to take 30 minutes on even a fast connection, and many
55hours on slower ones.
56
57When `fetch` completes, it will have created a hidden `.gclient` file and a
58directory called `src` in the working directory. The remaining instructions
59assume you have switched to the `src` directory:
60
61```shell
62$ cd src
63```
64
65*Optional*: You can also [install API
66keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your
67build to talk to some Google services, but this is not necessary for most
68development and testing purposes.
69
70## Setting up the build
71
72Since the iOS build is a bit more complicated than a desktop build, we provide
73`ios/build/tools/setup-gn.py`, which will create four appropriately configured
74build directories under `out` for Release and Debug device and simulator
Sylvain Defresnefc11bcd2020-06-26 13:42:0075builds, and generates an appropriate Xcode project (`out/build/all.xcodeproj`)
76as well.
michaeldo8cccf2142017-03-06 22:12:0277
Sylvain Defresnefc11bcd2020-06-26 13:42:0078More information about [developing with Xcode](xcode_tips.md). *Xcode project
79is an artifact, any changes made in the project itself will be ignored.*
Mike Doughertyd8947a592020-05-07 19:43:4680
michaeldo8cccf2142017-03-06 22:12:0281You can customize the build by editing the file `$HOME/.setup-gn` (create it if
82it does not exist). Look at `src/ios/build/tools/setup-gn.config` for
83available configuration options.
84
85From this point, you can either build from Xcode or from the command line using
Dirk Pranke8bd55f22018-10-24 21:22:1086`autoninja`. `setup-gn.py` creates sub-directories named
michaeldo8cccf2142017-03-06 22:12:0287`out/${configuration}-${platform}`, so for a `Debug` build for simulator use:
88
89```shell
Dirk Pranke8bd55f22018-10-24 21:22:1090$ autoninja -C out/Debug-iphonesimulator gn_all
michaeldo8cccf2142017-03-06 22:12:0291```
92
Dirk Pranke8bd55f22018-10-24 21:22:1093(`autoninja` is a wrapper that automatically provides optimal values for the
94arguments passed to `ninja`.)
95
Mike Doughertyd8947a592020-05-07 19:43:4696Note: The `setup-gn.py` script needs to run every time one of the `BUILD.gn`
97files is updated (either by you or after rebasing). If you forget to run it,
98the list of targets and files in the Xcode solution may be stale. You can run
99the script directly or use either `gclient sync` or `gclient runhooks` which
100will run `setup-gn.py` for you as part of the update hooks.
michaeldo8cccf2142017-03-06 22:12:02101
Sylvain Defresne9932328e2020-07-09 10:44:40102You can add a custom hook to `.gclient` file to configure `setup-gn.py` to
103be run as part of `gclient runhooks`. In that case, your `.gclient` file
104would look like this:
105
106```
107solutions = [
108 {
109 "name" : "src",
110 "url" : "https://chromium.googlesource.com/chromium/src.git",
111 "deps_file" : "DEPS",
112 "managed" : False,
113 "custom_deps" : {},
114 "custom_vars" : {},
115 "custom_hooks": [{
116 "name": "setup_gn",
117 "pattern": ".",
118 "action": [
Takuto Ikutad36eb352022-03-01 01:39:48119 "python3",
Sylvain Defresne9932328e2020-07-09 10:44:40120 "src/ios/build/tools/setup-gn.py",
121 ]
122 }],
123 "safesync_url": "",
124 },
125]
126target_os = ["ios"]
127target_os_only = True
128```
129
michaeldo8cccf2142017-03-06 22:12:02130You can also follow the manual instructions on the
131[Mac page](../mac_build_instructions.md), but make sure you set the
132GN arg `target_os="ios"`.
133
134## Building for device
135
136To be able to build and run Chromium and the tests for devices, you need to
137have an Apple developer account (a free one will work) and the appropriate
138provisioning profiles, then configure the build to use them.
139
140### Code signing identity
141
142Please refer to the Apple documentation on how to get a code signing identity
143and certificates. You can check that you have a code signing identity correctly
144installed by running the following command.
145
146```shell
147$ xcrun security find-identity -v -p codesigning
148 1) 0123456789ABCDEF0123456789ABCDEF01234567 "iPhone Developer: [email protected] (XXXXXXXXXX)"
149 1 valid identities found
150```
151
152If the command output says you have zero valid identities, then you do not
153have a code signing identity installed and need to get one from Apple. If
154you have more than one identity, the build system may select the wrong one
155automatically, and you can use the `ios_code_signing_identity` gn variable
156to control which one to use by setting it to the identity hash, e.g. to
157`"0123456789ABCDEF0123456789ABCDEF01234567"`.
158
159### Mobile provisioning profiles
160
161Once you have the code signing identity, you need to decide on a prefix
162for the application bundle identifier. This is controlled by the gn variable
163`ios_app_bundle_id_prefix` and usually corresponds to a reversed domain name
164(the default value is `"org.chromium"`).
165
166You then need to request provisioning profiles from Apple for your devices
167for the following bundle identifiers to build and run Chromium with these
168application extensions:
169
Javier Ernesto Flores Roblese68ab7e52021-01-20 18:14:34170- `${prefix}.chrome.ios.dev`
171- `${prefix}.chrome.ios.dev.ContentTodayExtension`
172- `${prefix}.chrome.ios.dev.CredentialProviderExtension`
Sylvain Defresnec2117082021-10-29 10:05:48173- `${prefix}.chrome.ios.dev.IntentsExtension`
Javier Ernesto Flores Roblese68ab7e52021-01-20 18:14:34174- `${prefix}.chrome.ios.dev.SearchTodayExtension`
175- `${prefix}.chrome.ios.dev.ShareExtension`
176- `${prefix}.chrome.ios.dev.TodayExtension`
177- `${prefix}.chrome.ios.dev.WidgetKitExtension`
michaeldo8cccf2142017-03-06 22:12:02178
179All these certificates need to have the "App Groups"
180(`com.apple.security.application-groups`) capability enabled for
181the following groups:
182
183- `group.${prefix}.chrome`
184- `group.${prefix}.common`
185
186The `group.${prefix}.chrome` is only shared by Chromium and its extensions
187to share files and configurations while the `group.${prefix}.common` is shared
188with Chromium and other applications from the same organisation and can be used
189to send commands to Chromium.
190
Takuto Ikutad36eb352022-03-01 01:39:48191`${prefix}.chrome.ios.dev.CredentialProviderExtension` needs the AutoFill
192Credential Provider Entitlement, which corresponds to the key
Javier Ernesto Flores Roblese68ab7e52021-01-20 18:14:34193`com.apple.developer.authentication-services.autofill-credential-provider`
194Please refer to Apple's documentation on how to set this up.
195
michaeldo8cccf2142017-03-06 22:12:02196### Mobile provisioning profiles for tests
197
Justin Cohena819c112019-08-17 02:19:19198In addition to that, you need a different provisioning profile for each
michaeldo8cccf2142017-03-06 22:12:02199test application. Those provisioning profile will have a bundle identifier
200matching the following pattern `${prefix}.gtest.${test-suite-name}` where
201`${test-suite-name}` is the name of the test suite with underscores changed
202to dashes (e.g. `base_unittests` app will use `${prefix}.gest.base-unittests`
203as bundle identifier).
204
205To be able to run the EarlGrey tests on a device, you'll need two provisioning
206profiles for EarlGrey and OCHamcrest frameworks:
207
208- `${prefix}.test.OCHamcrest`
209- `${prefix}.test.EarlGrey`
210
211In addition to that, then you'll need one additional provisioning profile for
Justin Cohena819c112019-08-17 02:19:19212the XCTest module too. It must match the pattern:
213`${prefix}.gtest.${test-suite-name}-module`.
michaeldo8cccf2142017-03-06 22:12:02214
215### Other applications
216
217Other applications like `ios_web_shell` usually will require mobile provisioning
218profiles with bundle identifiers that may usually match the following pattern
219`${prefix}.${application-name}` and may require specific capabilities.
220
221Generally, if the mobile provisioning profile is missing then the code signing
222step will fail and will print the bundle identifier of the bundle that could not
223be signed on the command line, e.g.:
224
225```shell
Dirk Pranke8bd55f22018-10-24 21:22:10226$ autoninja -C out/Debug-iphoneos ios_web_shell
michaeldo8cccf2142017-03-06 22:12:02227ninja: Entering directory `out/Debug-iphoneos'
228FAILED: ios_web_shell.app/ios_web_shell ios_web_shell.app/_CodeSignature/CodeResources ios_web_shell.app/embedded.mobileprovision
229python ../../build/config/ios/codesign.py code-sign-bundle -t=iphoneos -i=0123456789ABCDEF0123456789ABCDEF01234567 -e=../../build/config/ios/entitlements.plist -b=obj/ios/web/shell/ios_web_shell ios_web_shell.app
230Error: no mobile provisioning profile found for "org.chromium.ios-web-shell".
231ninja: build stopped: subcommand failed.
232```
233
234Here, the build is failing because there are no mobile provisioning profiles
235installed that could sign the `ios_web_shell.app` bundle with the identity
236`0123456789ABCDEF0123456789ABCDEF01234567`. To fix the build, you'll need to
237request such a mobile provisioning profile from Apple.
238
239You can inspect the file passed via the `-e` flag to the `codesign.py` script
Quinten Yearsley317532d2021-10-20 17:10:31240to check which capabilities are required for the mobile provisioning profile
michaeldo8cccf2142017-03-06 22:12:02241(e.g. `src/build/config/ios/entitlements.plist` for the above build error,
242remember that the paths are relative to the build directory, not to the source
243directory).
244
245If the required capabilities are not enabled on the mobile provisioning profile,
246then it will be impossible to install the application on a device (Xcode will
247display an error stating that "The application was signed with invalid
248entitlements").
249
Dave Tapuskafeb0745b2023-02-07 21:47:47250## Building Blink for iOS
251
252The iOS build supports compiling the blink web platform. To compile blink
253set a gn arg in your `.setup-gn` file. Note the blink web platform is
254experimental code and should only be used for analysis.
255
256```
257[gn_args]
258use_blink = true
259```
260Note that only certain targets support blink. `content_shell` being the
261most useful.
262
263```shell
264$ autoninja -C out/Debug-iphonesimulator content_shell
265```
266
267To run on a live device you will need to set the
268`com.apple.developer.kernel.extended-virtual-addressing` entitlement.
269
Mark Cogan0abda9652020-04-15 11:22:07270## Running apps from the command line
michaeldo8cccf2142017-03-06 22:12:02271
272Any target that is built and runs on the bots (see [below](#Troubleshooting))
273should run successfully in a local build. To run in the simulator from the
274command line, you can use `iossim`. For example, to run a debug build of
275`Chromium`:
276
277```shell
278$ out/Debug-iphonesimulator/iossim out/Debug-iphonesimulator/Chromium.app
279```
280
Mike Pinkerton90553fe2017-12-13 16:40:30281With Xcode 9, `iossim` no longer automatically launches the Simulator. This must now
282be done manually from within Xcode (`Xcode > Open Developer Tool > Simulator`), and
283also must be done *after* running `iossim`.
284
Vaclav Brozek09fe5ec2017-07-18 11:13:16285### Passing arguments
286
287Arguments needed to be passed to the test application through `iossim`, such as
288`--gtest_filter=SomeTest.FooBar` should be passed through the `-c` flag:
289
290```shell
Sylvain Defresned019a702018-02-01 10:11:51291$ out/Debug-iphonesimulator/iossim \
Vaclav Brozek09fe5ec2017-07-18 11:13:16292 -c "--gtest_filter=SomeTest.FooBar --gtest_repeat=3" \
293 out/Debug-iphonesimulator/base_unittests.app
294```
295
Mike Baxleycb99a9f2017-07-12 15:16:11296### Running EarlGrey tests
297
298EarlGrey tests are run differently than other test targets, as there is an
299XCTest bundle that is injected into the target application. Therefore you must
300also pass in the test bundle:
301
302```shell
303$ out/Debug-iphonesimulator/iossim \
304 out/Debug-iphonesimulator/ios_chrome_ui_egtests.app \
305 out/Debug-iphonesimulator/ios_chrome_ui_egtests.app/PlugIns/ios_chrome_ui_egtests_module.xctest
306```
307
Sylvain Defresned019a702018-02-01 10:11:51308### Running on specific simulator
309
310By default, `iossim` will pick an arbitrary simulator to run the tests. If
311you want to run them on a specific simulator, you can use `-d` to pick the
312simulated device and `-s` to select the iOS version.
313
314For example, to run the tests on a simulated iPhone 6s running iOS 10.0,
315you would invoke `iossim` like this.
316
317```shell
318$ out/Debug-iphonesimulator/iossim -d 'iPhone 6s' -s '10.0' \
319 out/Debug-iphonesimulator/base_unittests.app
320```
321
322Please note that by default only a subset of simulator devices are installed
323with Xcode. You may have to install additional simulators in Xcode (or even
324an older version of Xcode) to be able to run on a specific configuration.
325
326Go to "Preferences > Components" tab in Xcode to install other simulator images
327(this is the location the setting is in Xcode 9.2; it may be different in other
328version of the tool).
329
michaeldo8cccf2142017-03-06 22:12:02330## Update your checkout
331
332To update an existing checkout, you can run
333
334```shell
335$ git rebase-update
336$ gclient sync
337```
338
339The first command updates the primary Chromium source repository and rebases
340any of your local branches on top of tip-of-tree (aka the Git branch
Andrew Williamsbbc1a1e2021-07-21 01:51:22341`origin/main`). If you don't want to use this script, you can also just use
michaeldo8cccf2142017-03-06 22:12:02342`git pull` or other common Git commands to update the repo.
343
344The second command syncs dependencies to the appropriate versions and re-runs
345hooks as needed.
346
347## Tips, tricks, and troubleshooting
348
Mark Cogan0abda9652020-04-15 11:22:07349Remember that the XCode project you interact with while working on Chromium is a
350build artifact, generated from the `BUILD.gn` files. Do not use it to add new
351files; instead see the procedures for [working with
352files](working_with_files.md).
353
michaeldo8cccf2142017-03-06 22:12:02354If you have problems building, join us in `#chromium` on `irc.freenode.net` and
355ask there. As mentioned above, be sure that the
356[waterfall](https://build.chromium.org/buildbot/waterfall/) is green and the tree
357is open before checking out. This will increase your chances of success.
358
Sylvain Defresne01e2ded2020-12-02 11:18:30359### Debugging
360
361To help with deterministic builds, and to work with Goma, the path to source
362files in debugging symbols are relative to source directory. To allow Xcode
363to find the source files, you need to ensure to have an `~/.lldbinit-Xcode`
364file with the following lines into it (substitute {SRC} for your actual path
365to the root of Chromium's sources):
366
367```
368script sys.path[:0] = ['{SRC}/tools/lldb']
369script import lldbinit
370```
371
372This will also allow you to see the content of some of Chromium types in the
Jan Wilken Dörrie85285b02021-03-11 23:38:47373debugger like `std::u16string`, ... If you want to use `lldb` directly, name
Sylvain Defresne01e2ded2020-12-02 11:18:30374the file `~/.lldbinit` instead of `~/.lldbinit-Xcode`.
375
Sylvain Defresne1d01bff02021-01-29 01:13:10376Note: if you are using `ios/build/tools/setup-gn.py` to generate the Xcode
377project, the script also generate an `.lldbinit` file next to the project and
378configure Xcode to use that file instead of the global one.
379
Sylvain Defresne7080fe3b2020-11-16 15:57:51380### Changing the version of Xcode
381
382To change the version of Xcode used to build Chromium on iOS, please follow
383the steps below:
384
3851. Launch the new version of Xcode.app.
386
387 This is required as Xcode may need to install some components into
388 the system before the new version can be used from the command-line.
389
3901. Reboot your computer.
391
392 This is required as some of Xcode components are daemons that are not
393 automatically stopped when updating Xcode, and command-line tools will
394 fail if the daemon version is incompatible (usually `actool` fails).
395
3961. Run `gn gen`.
397
398 This is required as the `ninja` files generated by `gn` encodes some
399 information about Xcode (notably the path to the SDK, ...) that will
400 change with each version. It is not possible to have `ninja` re-run
401 `gn gen` automatically when those changes unfortunately.
402
403 If you have a downstream chekout, run `gclient runhooks` instead of
404 `gn gen` as it will ensure that `gn gen` will be run automatically
405 for all possible combination of target and configuration from within
406 Xcode.
407
408If you skip some of those steps, the build may occasionally succeed, but
409it has been observed in the past that those steps are required in the
410vast majority of the situation. Please save yourself some painful build
411debugging and follow them.
412
413If you use `xcode-select` to switch between multiple version of Xcode,
414you will have to follow the same steps.
415
michaeldo8cccf2142017-03-06 22:12:02416### Improving performance of `git status`
417
ishermance1d9d82017-05-12 23:10:04418#### Increase the vnode cache size
419
michaeldo8cccf2142017-03-06 22:12:02420`git status` is used frequently to determine the status of your checkout. Due
421to the large number of files in Chromium's checkout, `git status` performance
422can be quite variable. Increasing the system's vnode cache appears to help.
423By default, this command:
424
425```shell
426$ sysctl -a | egrep kern\..*vnodes
427```
428
429Outputs `kern.maxvnodes: 263168` (263168 is 257 * 1024). To increase this
430setting:
431
432```shell
433$ sudo sysctl kern.maxvnodes=$((512*1024))
434```
435
436Higher values may be appropriate if you routinely move between different
437Chromium checkouts. This setting will reset on reboot, the startup setting can
438be set in `/etc/sysctl.conf`:
439
440```shell
441$ echo kern.maxvnodes=$((512*1024)) | sudo tee -a /etc/sysctl.conf
442```
443
444Or edit the file directly.
445
ishermance1d9d82017-05-12 23:10:04446#### Configure git to use an untracked cache
447
448If `git --version` reports 2.8 or higher, try running
449
450```shell
451$ git update-index --test-untracked-cache
452```
453
454If the output ends with `OK`, then the following may also improve performance of
455`git status`:
456
457```shell
458$ git config core.untrackedCache true
459```
460
461If `git --version` reports 2.6 or higher, but below 2.8, you can instead run
michaeldo8cccf2142017-03-06 22:12:02462
463```shell
464$ git update-index --untracked-cache
465```
466
467### Xcode license agreement
468
469If you're getting the error
470
471> Agreeing to the Xcode/iOS license requires admin privileges, please re-run as
472> root via sudo.
473
474the Xcode license hasn't been accepted yet which (contrary to the message) any
475user can do by running:
476
477```shell
478$ xcodebuild -license
479```
480
481Only accepting for all users of the machine requires root:
482
483```shell
484$ sudo xcodebuild -license
485```