Apple Support for Bazel

This repository contains the Apple CC toolchain, Apple related platforms and constraints definitions, and small helper functions for rules authors targeting Apple platforms.

If you want to build iOS, tvOS, visionOS, watchOS, or macOS apps, use rules_apple.

If you want to build Swift use rules_swift.

See the documentation for the helper rules provided by this repository.

Installation

Copy the MODULE.bazel or WORKSPACE snippets from the releases page into your project.

Toolchain setup

The Apple CC toolchain in by this repository provides toolchains for building for Apple platforms besides macOS. Since Bazel 7 this toolchain is required when targeting those platforms but the toolchain also supports Bazel 6.

To use the Apple CC toolchain, pull this repository into your build and add this to your .bazelrc:

build --enable_platform_specific_config
build:macos --apple_crosstool_top=@local_config_apple_cc//:toolchain
build:macos --crosstool_top=@local_config_apple_cc//:toolchain
build:macos --host_crosstool_top=@local_config_apple_cc//:toolchain

This ensures that all rules provided by rules_apple, as well as other rules like cc_binary, all use the toolchain provided by this repository when building on macOS.

NOTE: This toolchain requires a full Xcode installation, not just the Xcode Command Line Tools. If you only need to build for macOS and don't want to require a full Xcode installation in your build, use the builtin Unix toolchain provided by Bazel.

bzlmod

If you're using bzlmod with the --crosstool_top configurations you must expose the local_config_apple_cc repository to your project by putting this in your MODULE.bazel:

apple_cc_configure = use_extension("@build_bazel_apple_support//crosstool:setup.bzl", "apple_cc_configure_extension")
use_repo(apple_cc_configure, "local_config_apple_cc")

Incompatible toolchain resolution

Bazel 7.x enabled a new discovery method for CC toolchains. With this new method you no longer need to pass any --*crosstool_top flags. Instead you just need to depend on apple_support and bazel automatically picks the right toolchain based on what you're building. If you have any issues with this you can temporarily disable it with --incompatible_enable_cc_toolchain_resolution=false. If you do please file an issue here.

NOTE: If you're using bzlmod and depend on both apple_support and rules_cc in your MODULE.bazel, apple_support's bazel_dep must come before rules_cc in order to take precedence over the default CC toolchains.

Toolchain configuration

There are many different flags you can flip to configure how the toolchain works. Here are some of the more commonly useful ones:

• Setting DEVELOPER_DIR in the environment. This is recommended so that the toolchain can be invalidated when the DEVELOPER_DIR changes, which ensures that toolchain binaries will be rebuilt with the new version of Xcode so that caches are correctly shared across machines.
• Setting BAZEL_ALLOW_NON_APPLICATIONS_XCODE=1 in the environment (or using --repo_env) allows the toolchain to discover Xcode versions outside of the /Applications directory to avoid header inclusion errors from bazel. This is not enabled by default because /Applications is the standard directory, and this improves toolchain setup performance.