Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MobileNativeFoundation/rules_xcodeproj/llms.txt

Use this file to discover all available pages before exploring further.

The xcodeproj rule (actually a macro wrapper around the underlying rule) is the primary entry point for generating an Xcode project from your Bazel workspace. Load it in your BUILD file with: 
load("@rules_xcodeproj//xcodeproj:defs.bzl", "xcodeproj")
The kwargs argument passes through globally available Bazel attributes such as visibility and features to the underlying rule. The project is written to disk when you run the generated runner target (e.g. bazel run //:xcodeproj).

​
Minimal example

xcodeproj(
    name = "xcodeproj",
    project_name = "App",
    tags = ["manual"],
    top_level_targets = [
        top_level_target(":App", target_environments = ["device", "simulator"]),
        ":Tests",
    ],
)

​
Attributes

​
name
string
required
A unique name for this target. This is the label you run with bazel run to generate the project. If project_name is not set, this value is also used as the .xcodeproj filename.
​
top_level_targets
list
required
A list of top-level targets to include in the generated project. Each entry can be:
​
project_name
string
The name to use for the .xcodeproj file. If not specified, the value of name is used.Default: None (uses name)
​
bazel_path
string
The path to the bazel binary or a wrapper script. Relative paths are resolved using the PATH environment variable set at project generation time. To reference a workspace-relative binary, prepend ./ (e.g. "./bazelw").Default: "bazel"
​
bazel_env
dict[string, string]
A dict of environment variables to set when invoking bazel_path. Use this for variables required by Bazel actions (e.g. JAVA_HOME, ANDROID_HOME) or by a wrapper bazel_path script.
  • If a value is None, the variable is resolved from the environment at project generation time.
  • Values that reference environment variables are also resolved at generation time.
  • To include a literal $, escape it with two backslashes.
If PATH is omitted it defaults to /bin:/usr/bin. If LANG is omitted it defaults to en_US.UTF-8.Default: {"LANG": "en_US.UTF-8", "PATH": "/bin:/usr/bin"}
​
config
string
The basename of the Bazel configs used during project generation and Xcode builds. For example, setting this to "projectx_xcodeproj" makes the following configs available in your .bazelrc:
  • projectx_xcodeproj
  • projectx_xcodeproj_generator
  • projectx_xcodeproj_indexbuild
  • projectx_xcodeproj_swiftuipreviews
Default: "rules_xcodeproj"
​
default_xcode_configuration
string
The name of the Xcode configuration to use when building, unless a custom scheme overrides it. If not set, the first configuration alphabetically is used. See xcode_configurations to define available configurations.Default: None
​
extra_files
list[label]
A list of extra files to add to the Xcode project navigator. These files are not associated with any particular target.Default: []
​
associated_extra_files
dict[string, list[label]]
A dict of extra files to add to the project, associated with a specific target. The key is a label string for the target and the value is a list of files. Files are only added when the associated target is focused.Default: {}
​
focused_targets
list[string]
A list of target label strings. When specified, only these targets (plus the top-level targets) are included in the generated project. All other transitive dependencies behave as if they were in unfocused_targets.Default: []
​
unfocused_targets
list[string]
A list of target label strings to explicitly exclude from the generated project. This overrides any matching entries in focused_targets. Excluded targets are replaced with pre-built artifacts.Default: []
​
install_directory
string
The workspace-relative directory where the .xcodeproj will be written. Defaults to the directory containing the BUILD file where xcodeproj is declared. Pass "" to write to the workspace root.Default: None (directory of the declaring BUILD file)
​
minimum_xcode_version
string
The minimum Xcode version supported by the generated project, expressed as a dot-separated version string (e.g. "14", "14.1", "15.0.1"). Higher values enable more features. Defaults to the Xcode version Bazel uses during generation.Default: None
​
post_build
string
A shell script to run after each build inside Xcode (e.g. "./post-build.sh" or "$SRCROOT/post-build.sh"). The script runs in Bazel’s execution root. Because it also runs during Index Build, add a guard like if [ "$ACTION" == "build" ]; then ... if that is undesirable.Default: None
​
pre_build
string
A shell script to run before each build inside Xcode (e.g. "./pre-build.sh" or "$SRCROOT/pre-build.sh"). The script runs in Bazel’s execution root. Add a guard for $ACTION == "build" if you want to skip execution during Index Build.Default: None
​
scheme_autogeneration_mode
string
Controls how Xcode schemes are automatically generated:
  • "auto" — generates a scheme for every buildable target when no custom schemes are provided; suppresses autogeneration when custom schemes exist.
  • "none" — never autogenerates schemes.
  • "all" — always generates a scheme for every buildable target, even when custom schemes are also provided.
Default: "auto"
​
scheme_autogeneration_config
xcschemes.autogeneration_config
A value returned by xcschemes.autogeneration_config. Provides fine-grained configuration of autogenerated schemes (pre/post actions, test options, name exclusion patterns, etc.). Only meaningful when scheme_autogeneration_mode is not "none".Default: None
​
target_name_mode
string
Controls how Xcode target names are generated:
  • "auto" — uses the product name when available and unambiguous; falls back to the target name, then the full label on collision.
  • "label" — always uses the full Bazel label as the Xcode target name.
Default: "auto"
​
xcode_configurations
dict[string, dict]
A dict mapping Xcode configuration names to Bazel transition settings. For example:
xcode_configurations = {
    "Dev": {
        "//command_line_option:compilation_mode": "dbg",
    },
    "AppStore": {
        "//command_line_option:compilation_mode": "opt",
    },
}
See the Bazel configuration documentation for details on transition settings dictionaries.Default: {"Debug": {}}
​
xcschemes
list[xcschemes.scheme]
A list of values returned by xcschemes.scheme. Works in conjunction with scheme_autogeneration_mode to define custom Xcode schemes.Default: []
​
project_options
project_options
A value returned by project_options(). Configures project-level settings such as indentation style, tab width, organization name, and development region.Default: None
​
import_index_build_indexstores
bool
Whether to import the index stores produced by Index Build into Xcode’s index. Enabling this speeds up Xcode’s code intelligence but increases disk I/O. Disable it if the overhead outweighs the benefit for your project size.Default: True
​
generator_bazel_env
dict[string, string]
A dict of environment variables applied only during project generation (i.e. when running the generator target with bazel run). These values are not written into the .xcodeproj and do not affect subsequent Xcode builds. Behaves identically to bazel_env otherwise.Default: {}

​
CPU attributes

The following attributes control the CPU architectures used when building targets for each platform and environment. Changing any of these values affects the Starlark transition hash for all transitive dependencies of the relevant targets, even if they do not target that platform.
​
ios_device_cpus
string
Value passed to --ios_multi_cpus for targets built with the "device" environment.Default: "arm64"
​
ios_simulator_cpus
string
Value passed to --ios_multi_cpus for targets built with the "simulator" environment. When unset, defaults to sim_arm64 on Apple Silicon or x86_64 on Intel.Default: None
​
tvos_device_cpus
string
Value passed to --tvos_cpus for targets built with the "device" environment.Default: "arm64"
​
tvos_simulator_cpus
string
Value passed to --tvos_cpus for targets built with the "simulator" environment. Defaults to sim_arm64 on Apple Silicon or x86_64 on Intel when unset.Default: None
​
visionos_device_cpus
string
Value passed to --visionos_cpus for targets built with the "device" environment.Default: "arm64"
​
visionos_simulator_cpus
string
Value passed to --visionos_cpus for targets built with the "simulator" environment.Default: "sim_arm64"
​
watchos_device_cpus
string
Value passed to --watchos_cpus for targets built with the "device" environment.Default: "arm64_32"
​
watchos_simulator_cpus
string
Value passed to --watchos_cpus for targets built with the "simulator" environment. Defaults to arm64 on Apple Silicon or x86_64 on Intel when unset.Default: None

Build docs developers (and LLMs) love

Get started for freeTalk to us