rules_and_macros_overview.md

Rules and Macros

The rules and macros described below are used to format, test and copy Starlark source files.

On this page:

• bzlformat_format
• bzlformat_pkg
• bzlformat_missing_pkgs
• bzlformat_lint_test

bzlformat_format

bzlformat_format(name, srcs, fix_lint_warnings, output_suffix, warnings)

Formats Starlark source files using Buildifier.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
srcs	The Starlark source files to format.	List of labels	required
fix_lint_warnings	Should lint warnings be fixed, if possible.	Boolean	optional	True
output_suffix	The suffix added to the formatted output filename.	String	optional	".formatted"
warnings	The warnings that should be fixed if lint fix is enabled.	String	optional	"all"

bzlformat_lint_test

bzlformat_lint_test(name, srcs, warnings)

Lints the specified Starlark files using Buildifier.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
srcs	The Starlark source files to lint.	List of labels	required
warnings	The warnings that should be fixed if lint fix is enabled.	String	optional	"all"

bzlformat_missing_pkgs

bzlformat_missing_pkgs(name, exclude)

Defines executable targets that find, test and fix any Bazel packages that are missing bzlformat_pkg declarations.

Assuming that the name attribute is bzlformat_missing_pkgs, the following targets are defined:

bzlformat_missing_pkgs_find: Find and report any Bazel packages that
                             are missing the `bzlformat_pkg`
                             declaration.
bzlformat_missing_pkgs_test: Like the find target except it fails if
                             any missing packages are found. This is
                             useful to run in CI test runs to ensure
                             that all is well.
bzlformat_missing_pkgs_fix: Adds `bzlformat_pkg` declarations to any
                            Bazel packages that are missing the
                            declaration.

PARAMETERS

Name	Description	Default Value
name	A string that acts as the prefix for the target names that are defined.	none
exclude	A list of packages to exclude from the find, test and fix operations. Each package should be specifed in the format //path/to/package.	[]

RETURNS

None.

bzlformat_pkg

bzlformat_pkg(name, srcs, lint_test, format_visibility, update_visibility, lint_test_visibility)

Defines targets that format, test, and update the specified Starlark source files.

NOTE: Any labels detected in the srcs will be ignored.

PARAMETERS

Name	Description	Default Value
name	The prefix string that is used when creating the targets.	"bzlformat"
srcs	Optional. A list of Starlark source files. If no value is provided, any files that match *.bzl, BUILD or BUILD.bazel are used.	None
lint_test	Optional. A bool specifying whether a lint test should be defined.	True
format_visibility	Optional. A list of Bazel visibility declarations for the format targets.	None
update_visibility	Optional. A list of Bazel visibility declarations for the update target.	None
lint_test_visibility	Optional. A list of Bazel visibility declarations for the lint test target.	None

RETURNS

None.