Skip to content

Commit

Permalink
Make macro conventions consistent across documentation
Browse files Browse the repository at this point in the history
bzl-style.md says to prefix macros with "_". macros.md says not to.

I updated documentation to be consistent the macros.md, because the code in the macros is slightly shorted and because I think the users are mostly not following the convention.

PiperOrigin-RevId: 463597233
Change-Id: I9ecb76cc61d59c1dbcf8f4afee0ad0d79e016b8d
  • Loading branch information
comius authored and copybara-github committed Jul 27, 2022
1 parent a11db84 commit 6e4bf7d
Showing 1 changed file with 6 additions and 6 deletions.
12 changes: 6 additions & 6 deletions site/en/rules/bzl-style.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,17 +135,15 @@ referenced directly at the Bazel CLI or in BUILD files: In that case, only the
*end users* of those targets need to know about them, and any build problems
introduced by macros are never far from their usage.

For macros that define internal targets (implementation details of the macro
For macros that define generated targets (implementation details of the macro
which are not supposed to be referred to at the CLI or depended on by targets
not instantiated by that macro), follow these best practices:

* A macro should take a `name` argument and define a target with that name.
That target becomes that macro's *main target*.
* All other targets defined by a macro should:
* Have their names preceded with an underscore (`_`), followed by the
value of the `name` attribute. For instance, if the macro is supplied
with the name *resources*, internal targets should have names
beginning with *_resources*.
* Generated targets, that is all other targets defined by a macro, should:
* Have their names prefixed by `<name>` or `_<name>`. For example, using
`name = '%s_bar' % (name)`.
* Have restricted visibility (`//visibility:private`), and
* Have a `manual` tag to avoid expansion in wildcard targets (`:all`,
`...`, `:*`, etc).
Expand All @@ -169,6 +167,8 @@ goals.

As a rule of thumb, the more macros resemble the rules, the better.

See also [macros](/rules/macros#conventions).

## Rules {:#rules}

* Rules, aspects, and their attributes should use lower_case names ("snake
Expand Down

0 comments on commit 6e4bf7d

Please sign in to comment.