# bazelbuild/rules_go architecture

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

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

## Overview

This project is the “rules_go” repository – a set of Bazel rules that let you build Go code (including libraries, binaries, tests, cgo, cross-compilation, and protocol buffers) using Bazel. The purpose is to integrate and support the Go toolchain within Bazel builds, while also providing helper tools, test suites, and documentation to guide users.

##### Main Components
- Bazel Build System & Workspace: At the core, the repository defines BUILD files, WORKSPACE rules, and Bazel configuration files (e.g., MODULE.bazel, WORKSPACE, .bazelrc). These serve as the entry point to the build system.
- Core Go Rules: The “go” directory contains the core rule definitions (e.g., go_library, go_binary, go_test) and support files that directly interact with the Go compiler and toolchain. These are the central building blocks.
- Proto Rules & Integration: The “proto” directory and related documentation (e.g., proto/core.rst) encapsulate support for protocol buffers via go_proto_library and related tools. This component shows how protocol buffer support integrates into the overall Go rule ecosystem.
- Toolchain & Dependencies: The “go/toolchain” and “go/tools” directories (as well as “go/config”, “go/deps.bzl”, etc.) manage the registration of toolchains, downloading SDKs, dependency resolution (including go_repository), and integration with Gazelle. They are responsible for configuring, selecting, and wrapping the Go environment.
- Extras & Analysis: Under “go/extras” and also “go/nogo”, the repository contains helper rules for static analysis (nogo) and extra capabilities such as gomock support.
- Tests and Legacy Support: The extensive “tests” directory covers multiple test scenarios for rules, including integration tests, cross-compilation tests, coverage tests, and various edge cases. There is also legacy code under “tests/legacy”.
- External Integrations: The “third_party” folder and references to external repositories (e.g., GitHub links, links to Bazel’s official documentation) highlight the integration points with other tools (Gazelle, grpc, etc.).

##### Out Relationships and Interactions
- How the Bazel workspace and configuration files (WORKSPACE, MODULE.bazel, .bazelrc, etc.) feed into the build process by selecting toolchains and loading external repositories.
- How core rules (in the “go” directory) interact with the Go toolchain and compilers, and how they call or instantiate the tools in “go/tools”.
- Demonstrate the dependency flow: from BUILD files invoking go_library and go_binary rules to external repositories (managed via go_repository or Gazelle) that provide third-party libraries.
- Testing infrastructure – include tests’ critical role in validating core rules and extras (pointing to directories such as “tests” and “tests/core”) and how these tests simulate various build configurations such as cgo, cross-compilation, and platform-specific builds.
- Documentation and examples as reference modules that provide context to developers and users.

##### Architectural Patterns and Design Principles
- Modular Architecture: Each major functionality (core rules, proto support, toolchains, extras, tests) is separated into distinct directories with clear responsibilities.
- Declarative Build Configuration: The heavy use of BUILD.bazel and WORKSPACE files shows a declarative style where dependencies and build targets are explicitly specified.
- Extensibility: The presence of extra rules (like nogo, gomock support) and the integration of Gazelle (for generating BUILD files) emphasize an extensible design.
- Platform Abstraction: The project handles multiple platforms (Linux, macOS, Windows, amd64, arm64) with dedicated configurations and conditional selections, shown in directories like “go/platform” and test setups.
- Toolchain Management: The separation of go toolchain definitions and the ability to delegate to external tools (like the Go SDK downloader) are core to its design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Bazel Build System & Workspace"]:::workspace
    B["Core Go Rules"]:::core
    C["Toolchain & Dependencies"]:::toolchain
    D["Proto Rules & Integration"]:::proto
    F["Documentation & Examples"]:::docs
    G["Tests and Legacy Support"]:::tests
    H["External Integrations"]:::external

    A -->|"configures"| B
    A -->|"selects"| C
    A -->|"integrates"| D
    A -->|"references"| F
    A -->|"triggers"| G
    A -->|"integrates"| H

    B -->|"uses"| C
    B -->|"integrates"| D
    B -->|"depends"| H

    subgraph "Extras & Analysis"
        E1["Extras (gomock)"]:::extras
        E2["Static Analysis (nogo)"]:::extras
    end

    A -->|"includes"| E1
    A -->|"includes"| E2
    E1 -->|"validatedBy"| G
    E2 -->|"analyzedBy"| G

    click A "https://github.com/bazelbuild/rules_go/tree/master/WORKSPACE"
    click B "https://github.com/bazelbuild/rules_go/tree/master/go/"
    click C "https://github.com/bazelbuild/rules_go/tree/master/go/toolchain/"
    click D "https://github.com/bazelbuild/rules_go/tree/master/proto/"
    click E1 "https://github.com/bazelbuild/rules_go/tree/master/extras/"
    click E2 "https://github.com/bazelbuild/rules_go/blob/master/go/nogo.rst"
    click F "https://github.com/bazelbuild/rules_go/tree/master/docs/"
    click G "https://github.com/bazelbuild/rules_go/tree/master/tests/"
    click H "https://github.com/bazelbuild/rules_go/tree/master/third_party/"

    classDef workspace fill:#FFEE88,stroke:#333,stroke-width:2px,color:#000;
    classDef core fill:#B3E6FF,stroke:#333,stroke-width:2px,color:#000;
    classDef toolchain fill:#CCFFCC,stroke:#333,stroke-width:2px,color:#000;
    classDef proto fill:#FFCCE6,stroke:#333,stroke-width:2px,color:#000;
    classDef extras fill:#E6CCFF,stroke:#333,stroke-width:2px,color:#000;
    classDef docs fill:#FFFFCC,stroke:#333,stroke-width:2px,color:#000;
    classDef tests fill:#FFCCCC,stroke:#333,stroke-width:2px,color:#000;
    classDef external fill:#D9D9D9,stroke:#333,stroke-width:2px,color:#000;
```
