How bazel-ios/rules_ios works
Project Type and Purpose
• This is an open-source plugin/extension for the Bazel build system, providing end-to-end iOS support (apps, frameworks, Xcode project generation, Apple Silicon, testing, etc.).
• The README calls it “rules_ios”—a Starlark-based rule set that plugs into Bazel to let developers build and test iOS targets seamlessly.
High-Level Architecture Overview
At a high level the system is a layered “plugin” architecture around Bazel:
• Bazel Core (CLI + Server + Execution Engine)
• External Rule Dependencies (rules_apple, rules_swift, apple_support, protobuf, etc.)
• rules_ios Package
• rule definitions in rules/
• static data & canned spec files in data/
• code generators in data_generators/
• helper scripts & toolchains in tools/
• design docs & examples in docs/ and tests/
• Outputs: Xcode projects, iOS application bundles, static/dynamic frameworks, test bundles.
Main Components
a. Bazel CLI & Daemon
• Entry point: .bazelrc, WORKSPACE, MODULE.bazel + BUILD.bazel files
b. External Repositories
• rules_apple, rules_swift, apple_support, protobuf_deps (loaded via http_archive or bzlmod)
c. rules_ios Core
• rules/ directory with Starlark rule definitions (app.bzl, framework.bzl, test.bzl, etc.)
• data/ (prebuilt spec data)
• data_generators/ (Python scripts to generate or transform spec data)
d. Tooling Layer
• tools/ (xcode_configure, vmd test runners, arm64-to-sim, compile_only_aspect, etc.)
e. Testing & Validation
• tests/ (hundreds of Bazel integration & analysis tests under tests/ios, tests/macos)
• CI workflows under .github
f. Documentation & Design
• docs/ (Markdown docs covering features, patterns, examples)
• design/ (architectural notes, APPLE_FRAMEWORK.md)
Relationships and Data Flow
• Developer invokes “bazel build” or “bazel test”
→ Bazel loads WORKSPACE/MODULE.bazel → fetches external repos → loads rules_ios’s BUILD & .bzl files
→ Starlark interpreter runs rule definitions (rules/apple, rules/swift, rules_ios)
→ data_generators produce spec fragments → data is fed into rule implementations
→ execution phase invokes Xcode toolchain, Swift compiler, clang, lipo, linker, vfs_overlay, etc.
→ Tools (vmd, xcode_configure) may be called at specific build/test phases
→ Final artifacts (App.app, .frameworks, test bundles, Xcode projects) are written to Bazel’s output tree
• Tests in tests/ drive integration coverage of each rule; CI orchestrates builds and test runs.
Architectural Patterns & Principles
• Plugin/Extension: rules_ios is a Bazel plugin, principally composed of Starlark rule libraries.
• Layering: clear separation between Bazel core, external rule dependencies, rules_ios implementation, tooling, and tests.
• Code Generation: Python scripts in data_generators auto-create portions of the rule data to ensure up-to-date spec lists.
• Reuse: rules_ios reuses logic from rules_apple and rules_swift; layered dependencies are pinned in repositories.bzl.
• Testing First: Heavy reliance on Bazel’s own testing mechanisms, with dedicated integration test directories.
Final Touches
• Keep it detailed: capture each sub-component of rules_ios even if it’s “just” a Starlark library.