Skip to main content

​
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:
  • # 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 example.com/foo resolving to a target in //foo
  • # gazelle:resolve_regexp source-lang [import-lang] import-string-regexp label Like resolve, but matches imports against an RE2 regular expression instead of an exact string — handy for mapping a whole namespace at once. Subpattern captures can be referenced in the label as $1, $2, etc.
  • # gazelle:generation_mode create_and_update|update_only Controls whether Gazelle creates new BUILD files or only updates existing ones. The default (create_and_update) creates new files. Setting it to update_only is useful when adopting Gazelle incrementally — Gazelle will update packages you’ve already onboarded but won’t touch directories that don’t yet have a BUILD file.

​
Per-language

Individual extensions can add their own, for example, the python extension has its own directives: Python Directives And the JavaScript extension from Aspect does as well: JavaScript Directives

​
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.