rules_xcodeproj

This repository contains rules for Bazel that can be used to generate Xcode projects from targets in your workspace.

If you run into any problems with these rules, please check our FAQ, check if another issue already exists and comment on it, or file a new issue!

Features

Screenshot of a rules_xcodeproj generated project open in Xcode

Full support for Xcode features:
- Indexing (i.e. autocomplete, syntax highlighting, jump to definition)
- Debugging
- Runtime sanitizers
- Inline warnings and errors
- Fix-its (currently only in BwX mode)
- Test selection and running
- Embedded Targets (App Clips, App Extensions, and Watch Apps)
- Dynamic frameworks
- SwiftUI Previews
Focused Projects
- Include a subset of your targets in Xcode
- Unfocused targets are built with Bazel
- Works in BwX mode as well!
Comprehensive Bazel rules support
- Core Bazel C/C++/Objective-C
- rules_swift
- rules_apple
- rules_ios
- Most likely your custom rules as well!
Minimal configuration needed (see the usage section below)
Multiple ways of building your project in Xcode
- Build your Bazel targets with Bazel (a.k.a Build with Bazel or BwB mode)
- Build your Bazel targets with Xcode, not Bazel (a.k.a. Build with Xcode or BwX mode)¹
It “just works”

We’ve also documented the high-level design goals of the ruleset.

Projects using rules_xcodeproj

BazelPods
Cash App
Envoy Mobile
Ergatta
Lyft
Mercari
Robinhood
Slack
Snap
Spotify
SwiftLint
Ten Ten
Tinder
Tokopedia

If you are also using rules_xcodeproj for your project, feel free to open a PR to include it in the list above.

Compatibility

rules_xcodeproj	Bazel	rules_apple	rules_swift	Xcode	macOS	Supporting Branch
1.7.0+	5.3–6.x	1.0.1–2.x	1.x	13.3–15.x	12–13.x	`main`
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	-

More versions of these tools and rulesets might be supported, but these are the ones we’ve officially tested with.

Installation

From the release you wish to use, copy the Bzlmod or WORKSPACE snippet into your repository.

Usage

Please see the documentation in the docs directory and examples in the examples directory.

Simple iOS example

Given a root level BUILD file:

load(
  "@build_bazel_rules_apple//apple:ios.bzl",
  "ios_application",
  "ios_unit_test",
)
load("@build_bazel_rules_swift//swift:swift.bzl", "swift_library")
load(
    "@rules_xcodeproj//xcodeproj:defs.bzl",
    "top_level_target",
    "xcodeproj",
)

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

ios_application(
    name = "App",
    bundle_id = "com.example.app",
    families = ["iphone", "ipad"],
    infoplists = [":Info.plist"],
    minimum_os_version = "15.0",
    visibility = ["//visibility:public"],
    deps = [":Lib"],
)

swift_library(
    name = "Lib",
    srcs = glob(["src/*.swift"]),
)

ios_unit_test(
    name = "Tests",
    bundle_id = "com.example.tests",
    minimum_os_version = "15.0",
    test_host = ":App",
    visibility = ["//visibility:public"],
    deps = [":TestLib"],
)

swift_library(
    name = "TestLib",
    srcs = glob(["test/*.swift"]),
)

You can then create the Xcode project with:

bazel run //:xcodeproj

The generated project will be in the workspace next to the BUILD file at App.xcodeproj.

Acknowledgements

Inspired by Tulsi and the custom project generators at Target and Lyft.
Made possible by XcodeProj.
Initial design and development by @brentleyjones.
Logo by @pennig.
Donated to the Mobile Native Foundation by BuildBuddy.

Build with Bazel mode is the build mode with first class support. We will try to make Build with Xcode mode work with every project, but there are limitations that can make the experience subpar, or not work at all. We recommend using BwB mode if possible. ↩

Kila2/rules_xcodeproj