# bazel-ios/rules_ios architecture

> Architecture diagram of the GitHub repository bazel-ios/rules_ios, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bazel-ios/rules_ios
- Repository: https://github.com/bazel-ios/rules_ios

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Bazel Core"
        rc[".bazelrc"]:::config
        workspace["WORKSPACE"]:::config
        module["MODULE.bazel"]:::config
        buildCore["BUILD.bazel"]:::config
    end

    subgraph "External Repositories"
        repoRulesApple["rules_apple"]:::external
        repoRulesSwift["rules_swift"]:::external
        repoAppleSupport["apple_support"]:::external
        repoProtobuf["protobuf_deps"]:::external
        repobzl["rules/repositories.bzl"]:::config
        modwork["WORKSPACE.bzlmod"]:::config
    end

    subgraph "rules_ios Core"
        rulesBuild["rules/BUILD.bazel"]:::core
        appRule["app.bzl"]:::core
        frameworkRule["framework.bzl"]:::core
        testRule["test.bzl"]:::core
        libraryRule["library.bzl"]:::core
        extensionRule["extension.bzl"]:::core
        featuresRule["features.bzl"]:::core
        providersRule["providers.bzl"]:::core
        moduleExtRule["module_extensions.bzl"]:::core
        subsBSRule["substitute_build_settings.bzl"]:::core
        plistsRule["plists.bzl"]:::core
        hmapRule["hmap.bzl"]:::core
        importMMRule["import_middleman.bzl"]:::core
        precompResRule["precompiled_apple_resource_bundle.bzl"]:::core
        analysisTests["rules/analysis_tests/"]:::core
    end

    subgraph "Static Data & Specs"
        dataBuild["data/BUILD.bazel"]:::data
        xcspecs["data/xcspecs.bzl"]:::data
        xcspecEvals["data/xcspec_evals.bzl"]:::data
    end

    subgraph "Data Generators"
        genBuild["data_generators/BUILD.bazel"]:::data
        extractor["data_generators/xcspec_extractor.py"]:::data
    end

    subgraph "Tooling Layer"
        compileAspect["compile_only_aspect.bzl"]:::tool
        arm64sim["tools/m1_utils/arm64-to-sim"]:::tool
        updDyn["tools/m1_utils/update_dynamic.sh"]:::tool
        updInPlace["tools/m1_utils/update_in_place.sh"]:::tool
        updStatic["tools/m1_utils/update_static.sh"]:::tool
        xcodeCfg["tools/toolchains/xcode_configure/xcode_configure.bzl"]:::tool
        xcodeLocator["tools/toolchains/xcode_configure/xcode_locator.m"]:::tool
        xcodeStub["tools/toolchains/xcode_configure/xcode_locator_stub.sh"]:::tool
        vmdSh["tools/vmd/vmd.sh"]:::tool
        iosVmRunner["tools/vmd/ios_vm_test_runner.sh"]:::tool
        vmRunnerBzl["tools/vmd/vm_test_runner.bzl"]:::tool
        xcodeVer["tools/xcode_version_computation/main.swift"]:::tool
        xctestLoc["tools/xctest_absolute_source_locations/xctest_absolute_source_locations.m"]:::tool
    end

    subgraph "Tests & CI"
        testsDir["tests/"]:::test
        ciTests[".github/workflows/tests.yml<br>.github/workflows/preflight_env.sh"]:::test
        releaseCI[".github/workflows/create_release.yml<br>.github/workflows/generate_release_notes.sh<br>.github/workflows/preflight_env.sh"]:::test
    end

    subgraph "Documentation & Design"
        docsDir["docs/"]:::doc
        designFile["design/APPLE_FRAMEWORK.md"]:::doc
    end

    subgraph "Outputs & Artifacts"
        appOut["App.app"]:::output
        frameworksOut[".frameworks"]:::output
        testBundles["Test Bundles"]:::output
        xcodeProj["Xcode Projects"]:::output
    end

    %% Relationships
    rc -->|invokes| repoRulesApple
    rc --> repoRulesSwift
    rc --> repoAppleSupport
    rc --> repoProtobuf
    rc --> rulesBuild

    repoRulesApple --> rulesBuild
    repoRulesSwift --> rulesBuild
    repoAppleSupport --> rulesBuild
    repoProtobuf --> rulesBuild
    repobzl --> rulesBuild
    modwork --> rulesBuild

    genBuild --> extractor
    extractor --> xcspecs
    xcspecs --> rulesBuild
    xcspecEvals --> rulesBuild
    dataBuild --> rulesBuild

    rulesBuild --> appRule
    rulesBuild --> frameworkRule
    rulesBuild --> testRule
    rulesBuild --> libraryRule
    rulesBuild --> extensionRule
    rulesBuild --> featuresRule
    rulesBuild --> providersRule
    rulesBuild --> moduleExtRule
    rulesBuild --> subsBSRule
    rulesBuild --> plistsRule
    rulesBuild --> hmapRule
    rulesBuild --> importMMRule
    rulesBuild --> precompResRule
    rulesBuild --> analysisTests

    rulesBuild --> compileAspect
    rulesBuild --> arm64sim
    rulesBuild --> updDyn
    rulesBuild --> updInPlace
    rulesBuild --> updStatic
    rulesBuild --> xcodeCfg
    rulesBuild --> xcodeLocator
    rulesBuild --> xcodeStub
    rulesBuild --> vmdSh
    rulesBuild --> iosVmRunner
    rulesBuild --> vmRunnerBzl
    rulesBuild --> xcodeVer
    rulesBuild --> xctestLoc

    compileAspect --> appOut
    xcodeCfg --> xcodeProj
    arm64sim --> frameworksOut
    vmdSh --> testBundles

    testsDir --> rulesBuild
    ciTests --> rulesBuild
    releaseCI --> rulesBuild

    docsDir --> rulesBuild
    designFile --> rulesBuild

    rulesBuild --> appOut
    rulesBuild --> frameworksOut
    rulesBuild --> testBundles
    rulesBuild --> xcodeProj

    %% Click Events
    click rc "https://github.com/bazel-ios/rules_ios/blob/master/.bazelrc"
    click workspace "https://github.com/bazel-ios/rules_ios/tree/master/WORKSPACE"
    click module "https://github.com/bazel-ios/rules_ios/blob/master/MODULE.bazel"
    click buildCore "https://github.com/bazel-ios/rules_ios/blob/master/BUILD.bazel"
    click repobzl "https://github.com/bazel-ios/rules_ios/blob/master/rules/repositories.bzl"
    click modwork "https://github.com/bazel-ios/rules_ios/blob/master/WORKSPACE.bzlmod"
    click rulesBuild "https://github.com/bazel-ios/rules_ios/blob/master/rules/BUILD.bazel"
    click appRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/app.bzl"
    click frameworkRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/framework.bzl"
    click testRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/test.bzl"
    click libraryRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/library.bzl"
    click extensionRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/extension.bzl"
    click featuresRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/features.bzl"
    click providersRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/providers.bzl"
    click moduleExtRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/module_extensions.bzl"
    click subsBSRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/substitute_build_settings.bzl"
    click plistsRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/plists.bzl"
    click hmapRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/hmap.bzl"
    click importMMRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/import_middleman.bzl"
    click precompResRule "https://github.com/bazel-ios/rules_ios/blob/master/rules/precompiled_apple_resource_bundle.bzl"
    click analysisTests "https://github.com/bazel-ios/rules_ios/tree/master/rules/analysis_tests/"
    click dataBuild "https://github.com/bazel-ios/rules_ios/blob/master/data/BUILD.bazel"
    click xcspecs "https://github.com/bazel-ios/rules_ios/blob/master/data/xcspecs.bzl"
    click xcspecEvals "https://github.com/bazel-ios/rules_ios/blob/master/data/xcspec_evals.bzl"
    click genBuild "https://github.com/bazel-ios/rules_ios/blob/master/data_generators/BUILD.bazel"
    click extractor "https://github.com/bazel-ios/rules_ios/blob/master/data_generators/xcspec_extractor.py"
    click compileAspect "https://github.com/bazel-ios/rules_ios/blob/master/tools/compile_only_aspect.bzl"
    click arm64sim "https://github.com/bazel-ios/rules_ios/tree/master/tools/m1_utils/arm64-to-sim"
    click updDyn "https://github.com/bazel-ios/rules_ios/blob/master/tools/m1_utils/update_dynamic.sh"
    click updInPlace "https://github.com/bazel-ios/rules_ios/blob/master/tools/m1_utils/update_in_place.sh"
    click updStatic "https://github.com/bazel-ios/rules_ios/blob/master/tools/m1_utils/update_static.sh"
    click xcodeCfg "https://github.com/bazel-ios/rules_ios/blob/master/tools/toolchains/xcode_configure/xcode_configure.bzl"
    click xcodeLocator "https://github.com/bazel-ios/rules_ios/blob/master/tools/toolchains/xcode_configure/xcode_locator.m"
    click xcodeStub "https://github.com/bazel-ios/rules_ios/blob/master/tools/toolchains/xcode_configure/xcode_locator_stub.sh"
    click vmdSh "https://github.com/bazel-ios/rules_ios/blob/master/tools/vmd/vmd.sh"
    click iosVmRunner "https://github.com/bazel-ios/rules_ios/blob/master/tools/vmd/ios_vm_test_runner.sh"
    click vmRunnerBzl "https://github.com/bazel-ios/rules_ios/blob/master/tools/vmd/vm_test_runner.bzl"
    click xcodeVer "https://github.com/bazel-ios/rules_ios/blob/master/tools/xcode_version_computation/main.swift"
    click xctestLoc "https://github.com/bazel-ios/rules_ios/blob/master/tools/xctest_absolute_source_locations/xctest_absolute_source_locations.m"
    click testsDir "https://github.com/bazel-ios/rules_ios/tree/master/tests/"
    click ciTests "https://github.com/bazel-ios/rules_ios/blob/master/.github/workflows/tests.yml"
    click releaseCI "https://github.com/bazel-ios/rules_ios/blob/master/.github/workflows/create_release.yml"

    %% Styles
    classDef config fill:#cccccc,stroke:#333,stroke-width:1px
    classDef external fill:#b3ffb3,stroke:#333
    classDef core fill:#cce5ff,stroke:#333
    classDef data fill:#e6ccff,stroke:#333
    classDef tool fill:#ffdead,stroke:#333
    classDef test fill:#ffcccc,stroke:#333
    classDef doc fill:#c2c2d6,stroke:#333
    classDef output fill:#d9b3ff,stroke:#333
```
