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.
rules_xcodeproj is a set of Bazel rules that generate fully-featured Xcode projects directly from your existing Bazel workspace. Instead of maintaining a separate Xcode project by hand — or fighting drift between your build system and your IDE — you define your targets once in BUILD files and let rules_xcodeproj synthesize a .xcodeproj that works seamlessly with Xcode’s debugger, indexer, previews, and test runner.
The motivation is straightforward: large Apple-platform codebases benefit enormously from Bazel’s reproducible, incremental, and remote-cacheable builds, but engineers still need Xcode for a productive day-to-day workflow. rules_xcodeproj bridges that gap, giving you the best of both worlds without sacrificing either.
Features
Full Xcode Feature Support
Autocomplete, syntax highlighting, jump-to-definition (indexing), debugging, runtime sanitizers, inline warnings and errors, test selection and running, and SwiftUI Previews all work exactly as you’d expect in a native Xcode project.
Focused Projects
Include only a meaningful subset of your monorepo’s targets in Xcode. Unfocused targets — those outside your current area of work — are built transparently by Bazel, keeping your project snappy and your analysis graph small.
Multi-Platform Support
Generate projects targeting iOS, macOS, tvOS, visionOS, and watchOS — including embedded targets such as App Clips, App Extensions, and Watch Apps, as well as dynamic frameworks.
Custom Xcode Schemes
Define exactly the schemes you want using the
xcschemes API. Control build, run, test, profile, and analyze actions, environment variables, launch arguments, and more, all from your BUILD files.Multiple Build Modes
Choose between Build with Xcode (BwX) — where Xcode drives compilation — and Build with Bazel (BwB) — where Bazel handles every build action and Xcode is the UI. Pick the mode that fits your team’s workflow.
Minimal Configuration
A single
xcodeproj rule pointing at your top-level targets is all that is required to produce a working project. No per-file mappings, no build-setting spreadsheets, no manual scheme editing.Who Uses It
rules_xcodeproj is trusted in production at some of the largest Apple-platform engineering organizations in the world:- amo · BazelPods · Cash App · Envoy Mobile · Ergatta
- Faire Wholesale · Gojek · Lyft · Mercari
- Reddit · Robinhood · Slack · Snap · Spotify
- Square · SwiftLint · Ten Ten · Tinder · Tokopedia
Using rules_xcodeproj at your company? Open a pull request on the GitHub repository to add your organization to the list.
Compatibility
The table below shows the officially tested compatibility matrix. Newer versions of supporting tools may work but are not guaranteed.| rules_xcodeproj | Bazel | rules_apple | rules_swift | Xcode | macOS | Supporting Branch |
|---|---|---|---|---|---|---|
| 2.13.0+ | 7.0–9.x | 4.0.0+ | 3.0.2+ | 13.3–16.x | 13–15.x | main |
| 2.10.0+ | 7.0–9.x | 3.16.1+ | 1.18.0+ | 13.3–16.x | 13–15.x | — |
| 1.17.0+ | 6.3–7.x | 1.0.1–2.x | 1.x | 13.3–15.x | 13–14.x | — |
| 1.16.0 | 6.3–7.x | 1.0.1–2.x | 1.x | 13.3–15.2 | 13–14.x | — |
| 1.14.0–1.15.0 | 6.1–7.x | 1.0.1–2.x | 1.x | 13.3–15.2 | 13–14.x | — |
| 1.7.0–1.13.0 | 5.3–6.x | 1.0.1–2.x | 1.x | 13.3–15.2 | 12–13.x | — |
| 1.4.0–1.6.0 | 5.3–6.x | 1.0.1–2.x | 1.x | 13.3–14.3 | 12–13.x | — |
| 1.0–1.3.3 | 5.3–6.x | 1.0.1–2.x | 1.x | 13.3–14.2 | 12–13.x | — |
Design Philosophy
rules_xcodeproj is guided by a small set of high-level design goals:- Only the
xcodeprojrule is required — a single rule pointing at your top-level targets produces a working project with no additional boilerplate. - Projects are customizable — additional rules and providers let you precisely control schemes, target representation, build settings, and run-script phases without touching the generated
.xcodeproj. - Outputs mirror
bazel build— the build products Xcode sees are as close as possible to what Bazel produces on the command line, reducing “works on my machine” surprises. - Xcode feels native — the generated project behaves like one you would have crafted by hand, keeping the full Xcode feature set available.
- All project definition lives in
BUILDfiles — generated files are not checked in; the source of truth is always your Bazel build graph.
Next Steps
Installation
Add rules_xcodeproj to your Bazel workspace using Bzlmod.
Quickstart
Generate your first Xcode project from a Bazel iOS app in minutes.