DOCSEARCHbyAlgolia
Submit Docs

rules_go

repository·master·Indexed 23 days ago

https://github.com/bazel-contrib/rules_go

Bazel rules for building, testing, and managing Go projects. Provides support for modules, cgo, cross-compilation, and static analysis. Includes integration with Gazelle for build file generation, Bzlmod support for dependency management via the go_sdk module extension, and configuration guides for editor support (gopls) across VS Code, Neovim, Vim, Sublime Text, Helix, and Zed using a GOPACKAGESDRIVER launcher script.

Tokens
34.1K
Snippets
80
Records
159
Agent score
78%

What's inside rules_go

  1. Overview of rules_go capabilities

    master

    The rules_go project provides Bazel rules for Go development.

    Supported features:

    • Building libraries, binaries, and tests using go_library, go_binary, and go_test.
    • Go modules support via go_deps.
    • Vendoring and cgo.
    • Cross-compilation.
    • Automatic BUILD file generation via Gazelle.
    • Build-time static code analysis via nogo.
    • Protocol buffers support.
    • Remote execution and coverage.
    • gopls integration for editor support.

    Limitations:

    • C/C++ integration is limited to cgo (and SWIG).

    Supported Platforms (Tested/Supported):

    • Linux, macOS, Windows
    • amd64, arm64

    Requirements:

    • Bazel ≥ 6.5.0 (required since version v0.51.0).
    • Go SDK ≥ 1.18.

  2. What is nogo and how does it compare to golangci-lint?

    master

    Concept: nogo

    nogo is a runner binary that executes a collection of Go analysis.Analyzer instances. It is integrated into the rules_go build process as a validation action that runs in parallel with the Go compiler.

    Comparison with golangci-lint

    Featurenogogolangci-lint
    IntegrationNative Bazel (runs via GoCompilePkg action)External tool/runner
    PerformanceBenefits from Bazel's incremental builds and cachingTypically runs as a separate, full-repo pass
    Best Use CaseLarge codebases where incremental builds are criticalSmaller codebases or when ergonomic auto-fixing is needed
    Auto-fixingManual via nogo_fix output groupHighly ergonomic built-in support

    Because nogo leverages Bazel's action orchestration, it is significantly more efficient for large-scale development where you only want to analyze the code that has changed.

  5. How to use Skylib in rules_go projects

    master

    The go/private/skylib directory is a partial copy of bazel-skylib used internally by rules_go (specifically for repository rules imported via //go:deps.bzl).

    Important Usage Rule: If you need to use Skylib functions in your own Bazel files (outside of the logic provided by //go:deps.bzl), do not use the files in this directory. Instead, you must use the official external Skylib repository, @bazel_skylib.

  6. Understand the Go toolchain layers

    master

    The Go toolchain in rules_go is composed of three distinct layers:

    1. The SDK: A directory tree containing the Go source, standard library, and pre-compiled binaries (the Go distribution). rules_go requires SDK version 1.18 or later.
    2. The Toolchain: Implementation of go_toolchain for various target platforms. Bazel selects the appropriate toolchain based on the execution and target platforms (via --host_platform and --platforms).
    3. The Context: An abstraction used by custom rules to access the SDK, toolchain, and standard library information, and to perform compilation or linking actions.

  7. Configure Go build settings

    master

    The Go toolchain can be configured using Bazel build settings defined in the @io_bazel_rules_go//go/config package. These settings can be applied globally via command-line flags or specifically to individual go_binary or go_test targets using attributes.

    Common use cases include enabling race detection, disabling cgo, or enabling static linking.

  8. Understand the core Go rules

    master

    Most Go projects can be built using three core rules that reimplement the low-level plumbing of the standard go build command:

    • go_library: Builds a single package. It requires a list of source files (srcs) and a list of dependencies (deps). Every go_library must have an importpath, which is the unique identifier used to import that package in Go source files.
    • go_binary: Builds a single main package and links it into an executable. It can use the embed attribute to include the content of a go_library (compiled together in the same package). You can target alternative platforms by configuring attributes like goos and goarch.
    • go_test: Builds a test executable. Similar to go test, it manages three distinct packages: an internal test package (using embed to compile with the library being tested), an external test package, and a generated test main package.

  9. Understand the GoArchive provider

    master
    The GoArchive provider contains information about a compiled archive and its direct and transitive dependencies. It is used during the compilation and linking of Go libraries and binaries. Most metadata about the archive itself is stored in the data field as GoArchiveData.

  10. Configure cross-compilation in go_binary

    master

    To force cross-compilation for a specific architecture or operating system, use the goarch and goos attributes.

    Important: Setting these attributes disables cgo by default because cross-compiling C/C++ toolchains are rarely available. If you need to force cgo during cross-compilation, you must set pure = "off".

  11. Design principles of Go providers

    master

    The Go provider architecture relies on two main principles:

    1. Efficiency: Providers share only the information necessary for core rules to operate.
    2. Immutability: All providers are designed to hold only immutable data. This is required because only immutable objects can be stored in a depset. This design enables features like the direct and transitive fields on GoArchive, which rely on the immutability of GoArchiveData to function correctly.

  12. Understand the GoArchiveData provider

    master
    The GoArchiveData provider contains immutable information about a compiled Go package. Because it does not contain information about dependencies or references to other providers, it is suitable for use in depsets. It is referenced via the data field of a GoArchive.