# bazelbuild/rules_swift architecture

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

- Interactive diagram: https://gitdiagram.com/bazelbuild/rules_swift
- Repository: https://github.com/bazelbuild/rules_swift

## Overview

##### Project type and purpose
- This is an **open‐source Bazel plugin/ruleset** (“rules_swift”) providing build rules for Swift code.
- Purpose: Define `swift_library`, `swift_binary`, `swift_test`, plus mixed‐language, proto integration, toolchain support, and auxiliary build‐time tools.

##### File structure
Top‐level directories reveal architectural areas:
- **swift/**: Core Starlark rule definitions (API surface and internal implementations, providers, aspects, toolchain configs)
- **proto/**: Starlark macros and scripts for Swift + Protobuf integration (e.g., `swift_proto_library`)
- **mixed_language/**: Extensions for interoperability between Swift, Objective-C, C, and C++
- **tools/**: Compiled helpers and scripts invoked by rules (e.g., protoc_wrapper, test_discoverer, test_observer, worker)
- **examples/**: Sample WORKSPACE/BUILD files demonstrating rule usage across Apple platforms and cross‐platform scenarios
- **test/**: Bazel tests validating rule behavior; fixtures to exercise build logic
- **third_party/**: External overlays for dependencies (Swift argument parser, Swift NIO, gRPC Swift, etc.)
- **.bazelci**, **.bcr**, **.github**: CI and release pipelines
- **doc/**: Reference and how-tos

##### Readme insights
- Declares the core API (`swift_binary`, `swift_library`, etc.)
- Recommends toolchain environment variables, custom toolchain invocation
- Points to `doc/` for details on features, debugging, and aspects

##### Main components & interactions
a. **User Workspace / BUILD Files** (top-level “client” of the rules)
b. **Bazel Core Engine**
- Evaluates BUILD stanzas
- Loads rule code from `@rules_swift`
c. **Swift Rules Module**
- **API Layer** (`swift/swift.bzl`, `swift/swift_library.bzl`, etc.)
- **Internal Logic** (`swift/internal/*.bzl`)—attributes, actions, symbol‐graph aspects, module maps
- **Toolchain Config** (`swift/toolchains/...`)—action configs, compile/link settings
d. **Proto Integration Module** (`proto/*.bzl`, copy scripts)
e. **Mixed‐Language Module** (`mixed_language/*.bzl`, module map extenders)
f. **Build‐Time Tools** (compiled C++/Swift binaries + scripts under `tools/`)
- **protoc_wrapper**: generates Swift from .proto
- **test_discoverer**, **test_observer**: detect and report tests
- **worker**: persistent compiler/linker service
- **mixed_language_module_map_extender**, **mkdir_and_run**, etc.
g. **External Services / Tools**
- **Swift Compiler (`swiftc`)**, **Clang**, **Protobuf Compiler**
- **Third-party libraries** (Swift Argument Parser, Swift NIO, gRPC Swift, JSON, etc.)
h. **Examples & Tests** (consume rules to verify functionality)

Relationships and data flows:
- BUILD files → Bazel Core → loads **Swift Rules Module**
- Rules → define **Actions** that invoke **Build-Time Tools** or external compilers
- **Toolchain Config** supplies flags to tool invocations
- **Proto** and **Mixed-Language** modules augment rule graph via aspects or additional actions
- **Third-party overlays** supply external dependencies at workspace resolution
- **Examples/Tests** depend on rule targets and demonstrate flows

##### Architectural patterns and principles
- **Layered Plugin Architecture**: Clear API vs. internal implementations
- **Aspects & Providers**: share metadata (e.g., module maps, symbol graphs) across rules
- **Extensibility**: proto and mixed_language modules plug into core behavior
- **Worker Model**: long-lived compiler/linker daemons to speed up builds
- **Tooling Segregation**: compiled helpers live alongside Starlark to support complex runtime logic

##### Elements
- Use **rectangles** for code modules (swift/, proto/, mixed_language/, tools/)
- from BUILD files to Bazel Core
- from Core to rule modules (load)
- from rules to actions/tools
- from actions to external compilers
- Core rule layers (blue)
- Extensions (green)
- Tools (orange)
- External compilers/services (gray)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer Layer
    U_BUILD["BUILD (top-level)"]:::consumer
    U_WORKSPACE["WORKSPACE"]:::consumer
    U_BZLMD["WORKSPACE.bzlmod"]:::consumer
    U_EXAMPLES["examples/"]:::consumer

    %% Bazel Core
    BAZEL["Bazel Core Engine"]:::core

    %% Rule Modules
    subgraph "Swift Rules Module"
        direction TB
        subgraph "API Layer"
            direction TB
            SWIFT_BZL["swift/swift.bzl"]:::core
            SWIFT_LIBRARY["swift/swift_library.bzl"]:::core
            SWIFT_BINARY["swift/swift_binary.bzl"]:::core
            SWIFT_TEST["swift/swift_test.bzl"]:::core
            SWIFT_LIB_GROUP["swift/swift_library_group.bzl"]:::core
            SWIFT_IMPORT["swift/swift_import.bzl"]:::core
            SWIFT_COMP_PLUGIN["swift/swift_compiler_plugin.bzl"]:::core
            SWIFT_COMP_PLUGIN_IMPORT["swift/swift_compiler_plugin_import.bzl"]:::core
            SWIFT_CROSS_IMPORT["swift/swift_cross_import_overlay.bzl"]:::core
            SWIFT_EXT_SYM["swift/swift_extract_symbol_graph.bzl"]:::core
            SWIFT_FEATURE_ALLOW["swift/swift_feature_allowlist.bzl"]:::core
            SWIFT_INTEROP_HINT["swift/swift_interop_hint.bzl"]:::core
            SWIFT_INTEROP_INFO["swift/swift_interop_info.bzl"]:::core
            SWIFT_MODULE_MAP["swift/swift_module_mapping.bzl"]:::core
            SWIFT_OVERLAY["swift/swift_overlay.bzl"]:::core
            SWIFT_OVERLAY_HELP["swift/swift_overlay_helpers.bzl"]:::core
            SWIFT_PKG_CONF["swift/swift_package_configuration.bzl"]:::core
            SWIFT_SYM_ASPECT["swift/swift_symbol_graph_aspect.bzl"]:::core
            SWIFT_SYN_INT_ASPECT["swift/swift_synthesize_interface_aspect.bzl"]:::core
            SWIFT_EXTENSIONS["swift/extensions.bzl"]:::core
            SWIFT_EXTRAS["swift/extras.bzl"]:::core
            SWIFT_PROVIDERS["swift/providers.bzl"]:::core
            SWIFT_REPOS["swift/repositories.bzl"]:::core
            SWIFT_MOD_NAME["swift/module_name.bzl"]:::core
        end
        subgraph "Internal Logic"
            direction TB
            SWIFT_INTERNAL["swift/internal/"]:::core
        end
        subgraph "Toolchain Config"
            direction TB
            SWIFT_TOOLCHAINS["swift/toolchains/"]:::core
        end
    end

    %% Extensions
    PROTO["Proto Integration Module"]:::ext
    MIXED_LANG["Mixed-Language Module"]:::ext
    THIRD_PARTY["Third-Party Overlays"]:::ext

    %% Build-Time Tools
    TOOLS["tools/"]:::tools

    %% External Services
    SWIFTC["Swift Compiler (swiftc)"]:::external
    CLANG["Clang"]:::external
    PROTOC["Protobuf Compiler (protoc)"]:::external

    %% Examples & Tests
    EX_TESTS["Examples & Tests (examples/, test/)"]:::consumer

    %% Documentation & CI
    DOC["doc/"]:::docs
    CI[".github/, .bazelci, .bcr"]:::docs

    %% Connections
    U_BUILD -->|loads rules| BAZEL
    U_WORKSPACE -->|workspace setup| BAZEL
    U_BZLMD -->|bzlmod configure| BAZEL
    U_EXAMPLES -->|demo usage| BAZEL

    BAZEL -->|load| SWIFT_BZL
    BAZEL -->|load| PROTO
    BAZEL -->|load| MIXED_LANG
    BAZEL -->|resolve| THIRD_PARTY

    SWIFT_BZL -->|defines actions| SWIFT_INTERNAL
    SWIFT_INTERNAL -->|generates actions| TOOLS
    SWIFT_TOOLCHAINS -->|provides flags| TOOLS

    PROTO -->|aspects & actions| TOOLS
    MIXED_LANG -->|aspects & actions| TOOLS

    TOOLS -->|execute swiftc| SWIFTC
    TOOLS -->|execute clang| CLANG
    TOOLS -->|run protoc_wrapper| PROTOC

    EX_TESTS -->|validate rules| BAZEL
    U_EXAMPLES -->|build| EX_TESTS

    BAZEL -->|docs reference| DOC
    BAZEL -->|CI pipelines| CI

    %% Click Events
    click U_BUILD "https://github.com/bazelbuild/rules_swift/tree/master/BUILD"
    click U_WORKSPACE "https://github.com/bazelbuild/rules_swift/tree/master/WORKSPACE"
    click U_BZLMD "https://github.com/bazelbuild/rules_swift/blob/master/WORKSPACE.bzlmod"
    click U_EXAMPLES "https://github.com/bazelbuild/rules_swift/tree/master/examples/"
    click SWIFT_BZL "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift.bzl"
    click SWIFT_LIBRARY "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_library.bzl"
    click SWIFT_BINARY "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_binary.bzl"
    click SWIFT_TEST "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_test.bzl"
    click SWIFT_LIB_GROUP "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_library_group.bzl"
    click SWIFT_IMPORT "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_import.bzl"
    click SWIFT_COMP_PLUGIN "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_compiler_plugin.bzl"
    click SWIFT_COMP_PLUGIN_IMPORT "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_compiler_plugin_import.bzl"
    click SWIFT_CROSS_IMPORT "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_cross_import_overlay.bzl"
    click SWIFT_EXT_SYM "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_extract_symbol_graph.bzl"
    click SWIFT_FEATURE_ALLOW "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_feature_allowlist.bzl"
    click SWIFT_INTEROP_HINT "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_interop_hint.bzl"
    click SWIFT_INTEROP_INFO "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_interop_info.bzl"
    click SWIFT_MODULE_MAP "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_module_mapping.bzl"
    click SWIFT_OVERLAY "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_overlay.bzl"
    click SWIFT_OVERLAY_HELP "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_overlay_helpers.bzl"
    click SWIFT_PKG_CONF "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_package_configuration.bzl"
    click SWIFT_SYM_ASPECT "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_symbol_graph_aspect.bzl"
    click SWIFT_SYN_INT_ASPECT "https://github.com/bazelbuild/rules_swift/blob/master/swift/swift_synthesize_interface_aspect.bzl"
    click SWIFT_EXTENSIONS "https://github.com/bazelbuild/rules_swift/blob/master/swift/extensions.bzl"
    click SWIFT_EXTRAS "https://github.com/bazelbuild/rules_swift/blob/master/swift/extras.bzl"
    click SWIFT_PROVIDERS "https://github.com/bazelbuild/rules_swift/blob/master/swift/providers.bzl"
    click SWIFT_REPOS "https://github.com/bazelbuild/rules_swift/blob/master/swift/repositories.bzl"
    click SWIFT_MOD_NAME "https://github.com/bazelbuild/rules_swift/blob/master/swift/module_name.bzl"
    click SWIFT_INTERNAL "https://github.com/bazelbuild/rules_swift/tree/master/swift/internal/"
    click SWIFT_TOOLCHAINS "https://github.com/bazelbuild/rules_swift/tree/master/swift/toolchains/"
    click PROTO "https://github.com/bazelbuild/rules_swift/tree/master/proto/"
    click MIXED_LANG "https://github.com/bazelbuild/rules_swift/tree/master/mixed_language/"
    click THIRD_PARTY "https://github.com/bazelbuild/rules_swift/tree/master/third_party/"
    click TOOLS "https://github.com/bazelbuild/rules_swift/tree/master/tools/"
    click EX_TESTS "https://github.com/bazelbuild/rules_swift/tree/master/test/"
    click DOC "https://github.com/bazelbuild/rules_swift/tree/master/doc/"
    click CI "https://github.com/bazelbuild/rules_swift/tree/master/.github/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef ext fill:#d4edda,stroke:#155724,color:#155724;
    classDef tools fill:#ffeeba,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef consumer fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef docs fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
