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_format

bzlformat_format(name, output_suffix, srcs)

Formats Starlark source files using Buildifier.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
output_suffix	The suffix added to the formatted output filename.	String	optional	".formatted"
srcs	The Starlark source files to format.	List of labels	required

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, format_visibility, update_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
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

RETURNS

None.