How bazelbuild/rules_go works
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.