Configuration

Directives

These are special comments that are placed anywhere in a BUILD file. They govern behavior as the generator visits files beneath this folder. Sub-packages can override the settings of their parent folder.

Built-in

Some directives are built-in to gazelle, while others are specific to an extension. Unfortunately, some of the built-in directives are specific to Go, which is just a historical accident since it originally was written for Go.

Here are some important ones to know:

• # gazelle:exclude pattern Prevents Gazelle from processing a file or directory if the given doublestar.Match pattern matches.
• # gazelle:map_kind from_kind to_kind to_kind_load Customizes the kind of rules generated by Gazelle. Most commonly, this would be used to replace the rules provided by a ruleset with custom macros. For example, using a custom macro instead of go_library:
Copy

# gazelle:map_kind go_library go_lib //tools/go:defs.bzl

• # gazelle:resolve source-lang [import-lang] import-string label Specifies an explicit mapping from an import string to a label for Dependency resolution. For example, a go import of lib-my-proto resolving to a target in //foo
Copy

# gazelle:resolve go example.com/foo //foo:my_go_library

Per-language

Individual extensions can add their own, for example, the python extension has its own directives:

GitHub rules_python/gazelle/README.md at main · bazelbuild/rules_python

And the JavaScript extension from Aspect does as well:

Configuration Directives | Aspect Docs

You can configure Aspect CLI using directives, which are specially-formatted

docs.aspect.build

Avoiding the need for directives

Directives are required when the source code doesn’t sufficiently describe what Gazelle needs to do. An alternative approach is to introduce load-bearing syntax in the source code. This way the information about the dependency graph stays in source files, not magic comments in BUILD files.

As one example, you can use triple-slash directives in Typescript to declare “ambient” library dependencies:

• /// <reference path="..." /> This directive is the most common of this group. It serves as a declaration of dependency between files.
• /// <reference lib="..." /> This directive allows a file to explicitly include an existing built-in lib file.

Of course, the Gazelle extension that reads the source file has to have logic that parses this syntax and uses it to inform dependency resolution or updates to attributes.

Next Lesson