iOS Build Instructions

Note: Upstreaming of iOS code is still a work in progress. In particular, note that it is not currently possible to build an actual Chromium app. Currently, the buildable binaries are ios_web_shell (a minimal wrapper around the web layer), and various unit tests.


  • A Mac running 10.11+.
  • Xcode 8.0+.
  • depot_tools.
  • The current version of the JDK (required for the closure compiler).

Getting the source

To checkout the source, use fetch ios command from depot_tools in a new empty directory.

# You can use a different location for your checkout of Chromium on iOS
# by updating this variable. All shell snippets will refer to it.
fetch ios

Setting up

Chromium on iOS is built using the Ninja tool and the Clang compiler. See both of those pages for further details on how to tune the build.

Before you build, you may want to install API keys so that Chrome-integrated Google services work. This step is optional if you aren't testing those features.

Quick setup

To setup the repository for building Chromium on iOS code, it is recommended to use the src/ios/build/tools/ script that creates a Xcode workspace configured to build the different targets for device and simulator.

cd "$CHROMIUM_IOS/src"
open out/build/all.xcworkspace

You can customize the build by editing the file $HOME/.setup-gn (create it if it does not exists). Look at src/ios/build/tools/setup-gn.config for available configuration options.

From this point, you can either build from Xcode or from the command-line using ninja. The script creates sub-directories named out/${configuration}-${platform}, so for a Debug build for simulator use:

ninja -C out/Debug-iphonesimulator gn_all

Note: you need to run script every time one of the file is updated (either by you or after rebasing). If you forget to run it, the list of targets and files in the Xcode solution may be stale.

Advanced setup

You can run gn manually to configure the build yourself. In that case, refer to mac build instructions for help on how to do that.

To build for iOS, you have to set target_os to "ios". Please also note that is_component_build is not supported when building for iOS and must be set to false.


Any target that is built and runs on the bots (see below) should run successfully in a local build. As of the time of writing, this is only ios_web_shell and unit test targets—see the note at the top of this page. Check the bots periodically for updates; more targets (new components) will come on line over time.

To run in the simulator from the command line, you can use iossim. For example, to run a debug build of ios_web_shell:

out/Debug-iphonesimulator/iossim out/Debug-iphonesimulator/


If your build fails, check the iOS columns of the Mac waterfall (the last two) to see if the bots are green. In general they should be, since failures on those bots will close the tree.