How bazelbuild/rules_swift works
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)