The purpose of this binary is to provide tools for temporary Xcode installations, e.g. to build and test Chrome / Chromium on Mac OS X and iOS.
Specifically, it provides tools for creating appropriate Xcode CIPD packages and then installing them on demand on bots and developer machines.
depot_tools
The mac_toolchain
tool is available in depot_tools
as a shim which automatically installs the binary on Mac OS X.
For depot_tool
-independent installation (e.g. on a bot, in a recipe), the preferred method of installing this tool is through CIPD, e.g.:
$ echo 'infra/tools/mac_toolchain/${platform} latest' | cipd ensure -ensure-file - -root .
will install the mac_toolchain
binary in the current directory (as specified by the -root
argument).
Note, that the CIPD package currently exists only for Mac OS, and not for any other platform, since Xcode installation only makes sense on a Mac.
You can also create shim scripts to install the actual binaries automatically, and optionally pin the mac_toolchain
package to a specific revision. Pinning to latest
will always install the latest available revision. For inspiration, see cipd_manifest.txt
in depot_tools
, and the corresponding shims, e.g. vpython
.
The prebuilt CIPD package is configured and built automatically for (almost) every committed revision of infra.git
. It's configuration file is mac_toolchain.yaml
.
Since this is a standard Go package, you can also install it by running go install
in this folder. See the infra/go/README.md
file for the Go setup.
mac_toolchain install -xcode-version XXXX -output-dir /path/to/root
Add -kind mac
or -kind ios
argument to install a package for mac or ios tasks. iOS kind has iOS SDK and default iOS runtime installed additionally. If not specified, the tool installs a mac kind.
This will install the requested version of Xcode.app
in the /path/to/root
folder. Run mac_toolchain help install
for more information.
Note: to access the Xcode packages, you may need to run:
cipd auth-login
or pass the appropriate -service-account-json
argument to cipd ensure
.
Download the Xcode zip file from your Apple's Developer account, unpack it, and point the script at the resulting Xcode.app
.
mac_toolchain upload -xcode-path /path/to/Xcode.app
This will split up the Xcode.app
container into several CIPD packages and will upload and tag them properly. Run mac_toolchain help upload
for more options.
The upload command is meant to be run manually, and it will upload many GB of data. Be patient.
mac_toolchain uploads the default iOS runtime and the rest of Xcode to different CIPD packages. It's also able to download an Xcode package without any iOS runtime bundled.
This is useful when we want to assemble an Xcode with it's core program and the only runtime needed for iOS test tasks in infra.
Runtime related features are added at around mid 2021. Design and related changes were tracked in crbug.com/1191260.
Two types of iOS runtimes are stored in CIPD path infra_internal/ios/xcode/ios_runtime
, distinguished through different combinations of tags and refs:
manually_uploaded
type: Uploaded with mac_toolchain upload-runtime
command.
xcode_default
type: Uploaded when uploading an Xcode. Packages of this type are labeled with both runtime version & Xcode version.
Use mac_toolchain install-runtime
. Either or both runtime version and Xcode version are accepted as input. Please read mac_toolchain help install-runtime
to learn the logic of choosing an appropriate runtime with given input combinations.
When uploading an Xcode, the runtime bundled in the Xcode version is uploaded automatically as an xcode_default
package.
Use mac_toolchain upload-runtime
to upload a manually_uploaded
runtime package. It's recommended to only use this command on the official runtimes downloaded through Xcode to system library /Library/Developer/CoreSimulator/Profiles/Runtimes/
.
Use following command to download an Xcode package without runtime
mac_toolchain install -kind ios -xcode-version SOME_VERSION -output-dir path/to/Xcode.app -with-runtime=False
This is specifically used in iOS tester machines across chromium infra where mac_toolchain is invoked to download Xcode. iOS test runner further downloads the requested runtime in task and assembles a full Xcode package with runtime from multiple packages downloaded (or read from cache).
To debug the packages locally (for e.g. uploading an Xcode), run:
mac_toolchain package -output-dir path/to/dir -xcode-path /path/to/Xcode.app
This will drop mac.cipd
, ios.cipd
, ios_runtime.cipd
files in path/to/out
directory and will not try to upload the packages to CIPD server.
You can then install Xcode from these local packages with:
cipd pkg-deploy -root path/to/Xcode.app path/to/out/mac.cipd cipd pkg-deploy -root path/to/Xcode.app path/to/out/ios.cipd cipd pkg-deploy -root path/to/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Library/Developer/CoreSimulator/Profiles/Runtimes path/to/out/ios_runtime.cipd