bazel-gazelle

Gazelle supports # keep comments to prevent specific parts of a build file from being modified or removed during the generation process. This is useful when you need to manually add dependencies that Gazelle cannot automatically resolve (e.g., dependencies on generated files).

# keep can be used in three ways:

1. Before a rule: Protects the entire rule.
2. Before an attribute: Protects a specific attribute within a rule.
3. After a string within a list: Protects a specific element in a list (most common for deps).

Supported formats:

• # keep (literal)
• # keep: <description> (description prefixed by a colon)

go_library(
    name = "go_default_library",
    srcs = ["magic.go"],
    visibility = ["//visibility:public"],
    deps = [
        "@com_github_example_gen//:go_default_library",  # keep
        "@com_github_example_gen//a/b/c:go_default_library",  # keep: this is also important
    ],
)

Lazy indexing allows Gazelle to run quickly by avoiding a full scan of all build files in a repository while still supporting index-based dependency resolution. This enables millisecond-level updates for specific directories.

Requirements:

• User Configuration: Users must point to directories that might contain libraries based on import strings.
• Language Extension Support: Extensions must implement logic to interpret configuration directives and map import strings to directory paths.

Example (Go): If a user has a module dependency example.com/b located at replace/b, they can use the go_search directive in their top-level build file to tell Gazelle how to resolve imports:

# gazelle:go_search replace/b example.com/b

When Gazelle encounters an import like example.com/b/c, it will index replace/b/c and make those targets available for resolution.

Implementation for Language Extensions: To support lazy indexing, an extension should:

1. Register the directive (e.g., go_search) in the KnownDirectives and Configure methods of the Configurer implementation.
2. Convert import strings (e.g., example.com/b/c) into directory paths (e.g., replace/b/c).
3. Return these paths via GenerateResult.RelsToIndex within the Language.GenerateRules method.

During the Generate stage, Gazelle calls extension methods in a specific order to manage rule creation and merging:

1. Configure: Called in pre-order for every directory visited. Extensions use this to read directives from BUILD files. This is the only method called in pre-order; all others are post-order.
2. Fix: Called in directories with existing BUILD files to transform or fix deprecated rule usage.
3. GenerateRules: Called in each directory. It returns rules that should exist and rules that should be removed. Note: This method must not modify the rules parsed from the BUILD file directly.
4. merger.MergeFile: Combines generated rules with existing ones.
   • Unmatched rules are added to the end of the file.
   • Attributes are merged: 'mergeable' attributes managed by Gazelle can overwrite existing values (unless marked with # keep), while non-mergeable attributes are only set if they don't exist.
   • Rules returned in an empty list by GenerateRules can be deleted if not marked with # keep.
5. Imports: Called on each rule after merging to build the in-memory index used for the Resolve stage. This is skipped if -index=none is used.

Gazelle resolves library import strings (e.g., import "golang.org/x/sys/unix") to Bazel labels (e.g., @org_golang_x_sys//unix:go_default_library) using the following priority:

1. Standard Library: No explicit dependency is written (e.g., Go's fmt).
2. # gazelle:resolve Directive: If a directive matches the import, the provided label is used.
3. Proto Rules: If enabled, special rules map Well Known Types and specific protobuf libraries (like ptypes or descriptor) to specific rules. This can be disabled via # gazelle:proto disable_global or -proto disable_global.
4. Library Index: If the import is in the indexed library rules, it resolves to that library.
   • -index=all: Builds a full index of the repo (slow).
   • -index=lazy: Uses language extensions to visit specific directories (fast).
5. Prefix Convention: If -index=none is used and the import matches the current go_prefix, Gazelle generates a label following a convention (e.g., //src/foo/bar:go_default_library).
6. External/Static/Vendored Modes:
   • external (Default): Transforms imports into external repository labels (e.g., @org_golang_x_sys//...). It assumes a matching go_repository exists in WORKSPACE but does not verify it.
   • static: Similar to external, but skips unknown imports instead of attempting network resolution. This is the default for go_repository rules.
   • vendored: Transforms imports into labels within the vendor directory (e.g., //vendor/golang.org/x/sys/unix:go_default_library).

When merger.MergeFile processes rules, it follows these steps:

1. Matching: It attempts to match a generated rule with an existing rule. A match occurs if:
   • The rule has the same kind and name (e.g., go_binary with name = "server").
   • OR one of its matchable attributes (defined in Kinds) has the same value (e.g., go_library with importpath = "example.com/foo").
   • OR the rule kind's MatchAny flag is set in the Kinds map.
2. Unmatched Rules: If no match is found, rules from the Gen list are added, and rules from the Empty list are ignored.
3. Matched Rules: If a match is found, rule.MergeRules is called:
   • New attributes: Added to the existing rule.
   • Missing attributes: If an attribute is in the existing rule but not the new one, it is deleted if it is marked as mergeable in Kinds, otherwise it is preserved (useful for human-written attributes).
   • Conflicting attributes: If an attribute exists in both:
     • If not mergeable: The existing (human-written) value is preserved.
     • If mergeable: The values are merged (e.g., merging lists). Extension authors can implement custom logic via the rule.Merger interface.
4. Deletion: If a rule becomes "empty" (no non-empty attributes like srcs or deps remain) after merging with an Empty list rule, the rule is deleted from the BUILD file.