Skip to content

Commit

Permalink
Improve "Common Attributes" section
Browse files Browse the repository at this point in the history
Creates a separate section for attributes which are added to most build rules, but not implicitly added to Starlark rules. deps, data, and licenses are moved to that section.

srcs is also added to the new section, since I think that's as notable a naming convention to highlight as "deps" and "data".

The section on "deps" is updated to note:
* That "deps" generally should contain only specific rules and not files
* How "deps" generally varies between language specific rules
* The general relationship between "srcs" and "deps".

Also, a bit that says "deps" are always included in runfiles is removed. That's not even usually true. Though it may be true in some cases that source code is needed at runtime and therefore should be included in runfiles (this could be the case for build rules for some interpreted languages, for example), often source code is not needed at runtime and shouldn't be included in runfiles.

The section on "data" is updated to note:
* That generally "data" permits arbitrary dependencies
* That default outputs and runfiles from targets in data should be included in the runfiles of consumers
* The general relationship between "data" and "srcs"
* What Starlark rules need to do to handle data in their implementation functions

The remainder of the section is updated to:
* Consistently use "target" instead of "rule" to refer to rule targets. "Rule target" is unnecessary, file targets don't have attributes
* Use a consistent format the type of the attribute
* Consistently omit that optional list or dictionary attributes default to empty lists or dictionaries
* Use False instead of 0 for the default values of attributes whose type is "boolean"

And did a bit of copyediting.

A line from the introduction to the "common attributes" section that mentions it's an error to list the same label twice in a label-list attribute is pruned. That's true, but it seems misplaced here, it's not very related to the rest of this section.

"applicable_licenses" and "transitive_configs" are not yet documented.

RELNOTES: None.
PiperOrigin-RevId: 351577116
  • Loading branch information
Googler authored and copybara-github committed Jan 13, 2021
1 parent 082d987 commit dac0d40
Show file tree
Hide file tree
Showing 32 changed files with 179 additions and 134 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -246,6 +246,8 @@ private void processAttributeDocs(Iterable<RuleDocumentation> ruleDocEntries,
ruleDoc.addAttribute(PredefinedAttributes.TEST_ATTRIBUTES.get(attrName));
} else if (PredefinedAttributes.COMMON_ATTRIBUTES.containsKey(attrName)) {
ruleDoc.addAttribute(PredefinedAttributes.COMMON_ATTRIBUTES.get(attrName));
} else if (PredefinedAttributes.TYPICAL_ATTRIBUTES.containsKey(attrName)) {
ruleDoc.addAttribute(PredefinedAttributes.TYPICAL_ATTRIBUTES.get(attrName));
}
}
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ public class DocgenConsts {

public static final String VAR_SECTION_STARLARK_BUILTIN = "SECTION_BUILTIN";

public static final String TYPICAL_ATTRIBUTES = "typical";
public static final String COMMON_ATTRIBUTES = "common";
public static final String TEST_ATTRIBUTES = "test";
public static final String BINARY_ATTRIBUTES = "binary";
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,9 @@ private void writeCommonDefinitionsPage(String outputDir, RuleLinkExpander expan
throws IOException {
Page page = TemplateEngine.newPage(DocgenConsts.COMMON_DEFINITIONS_TEMPLATE);
page.add("expander", expander);
page.add(
"typicalAttributes",
expandCommonAttributes(PredefinedAttributes.TYPICAL_ATTRIBUTES, expander));
page.add("commonAttributes",
expandCommonAttributes(PredefinedAttributes.COMMON_ATTRIBUTES, expander));
page.add("testAttributes",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -42,19 +42,29 @@ public class PredefinedAttributes {
"templates/attributes/test/local.html");

/**
* List of common attributes documentation, relative to {@link com.google.devtools.build.docgen}.
* List of typical (defined by most rules, but not implicitly added to all rules) attributes
* documentation, relative to {@link com.google.devtools.build.docgen}.
*/
public static final ImmutableList<String> TYPICAL_ATTRIBUTES_DOCFILES =
ImmutableList.of(
"templates/attributes/typical/data.html",
"templates/attributes/typical/deps.html",
"templates/attributes/typical/licenses.html",
"templates/attributes/typical/srcs.html");

/**
* List of common (implicitly added to all rules) attributes documentation, relative to {@link
* com.google.devtools.build.docgen}.
*/
// TODO(b/177233238): This should also document applicable_licenses and transitive_configs.
public static final ImmutableList<String> COMMON_ATTRIBUTES_DOCFILES =
ImmutableList.of(
"templates/attributes/common/compatible_with.html",
"templates/attributes/common/data.html",
"templates/attributes/common/deprecation.html",
"templates/attributes/common/deps.html",
"templates/attributes/common/distribs.html",
"templates/attributes/common/exec_compatible_with.html",
"templates/attributes/common/exec_properties.html",
"templates/attributes/common/features.html",
"templates/attributes/common/licenses.html",
"templates/attributes/common/restricted_to.html",
"templates/attributes/common/tags.html",
"templates/attributes/common/target_compatible_with.html",
Expand All @@ -74,8 +84,7 @@ public class PredefinedAttributes {

private static ImmutableMap<String, RuleDocumentationAttribute> generateAttributeMap(
String commonType, ImmutableList<String> filenames) {
ImmutableMap.Builder<String, RuleDocumentationAttribute> builder =
ImmutableMap.<String, RuleDocumentationAttribute>builder();
ImmutableMap.Builder<String, RuleDocumentationAttribute> builder = ImmutableMap.builder();
for (String filename : filenames) {
String name = Files.getNameWithoutExtension(filename);
try {
Expand All @@ -92,6 +101,9 @@ private static ImmutableMap<String, RuleDocumentationAttribute> generateAttribut
return builder.build();
}

public static final ImmutableMap<String, RuleDocumentationAttribute> TYPICAL_ATTRIBUTES =
generateAttributeMap(DocgenConsts.TYPICAL_ATTRIBUTES, TYPICAL_ATTRIBUTES_DOCFILES);

public static final ImmutableMap<String, RuleDocumentationAttribute> COMMON_ATTRIBUTES =
generateAttributeMap(DocgenConsts.COMMON_ATTRIBUTES, COMMON_ATTRIBUTES_DOCFILES);

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,9 @@ public void generateDocumentation(List<String> inputDirs, String outputDir, Stri
page.add("expander", expander);

// Populate variables for Common Definitions section.
page.add(
"typicalAttributes",
expandCommonAttributes(PredefinedAttributes.TYPICAL_ATTRIBUTES, expander));
page.add("commonAttributes",
expandCommonAttributes(PredefinedAttributes.COMMON_ATTRIBUTES, expander));
page.add("testAttributes",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,20 +7,14 @@
</p>

<p>
Command line arguments that bazel will pass to the target when it is executed
Command line arguments that Bazel will passes to the target when it is executed
either by the <code>run</code> command or as a test. These arguments are
passed before the ones that are specified on the <code>bazel run</code> or
<code>bazel test</code> command line.
</p>

<p>
<em class="harmful">NOTE: The arguments are not passed when you run the target
outside of bazel (for example, by manually executing the binary in
outside of Bazel (for example, by manually executing the binary in
<code>bazel-bin/</code>).</em>
</p>

<p>
Most binary rules permit an <code>args</code> attribute, but where
this attribute is not allowed, this fact is documented under the
specific rule.
</p>
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,6 @@

<p>
<em class="harmful">NOTE: The environment variables are not set when you run the target
outside of bazel (for example, by manually executing the binary in
outside of Bazel (for example, by manually executing the binary in
<code>bazel-bin/</code>).</em>
</p>
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional;
<a href="#configurable-attributes">nonconfigurable</a></code></p>

<p>
The list of environments this rule can be built for, in addition to
The list of environments this target can be built for, in addition to
default-supported environments.
</p>

<p>
This is part of Bazel's soft-launched constraint system, which lets users
declare which rules can and cannot depend on each other. For example,
externally deployable binaries shouldn't depend on libraries with
company-secret code. See
This is part of Bazel's constraint system, which lets users declare which
targets can and cannot depend on each other. For example, externally deployable
binaries shouldn't depend on libraries with company-secret code. See
<a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/analysis/constraints/ConstraintSemantics.java#L46">
ConstraintSemantics</a> for details.
</p>

This file was deleted.

Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
<p><code>String; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>

<p>
An explanatory warning message associated with this rule.
Typically this is used to notify users that a rule has become obsolete,
An explanatory warning message associated with this target.
Typically this is used to notify users that a target has become obsolete,
or has become superseded by another rule, is private to a package, or is
perhaps considered harmful for some reason. It is a good idea to include
some reference (like a webpage, a bug number or example migration CLs) so
Expand All @@ -15,7 +15,7 @@
This attribute has no effect on the way things are built, but it
may affect a build tool's diagnostic output. The build tool issues a
warning when a rule with a <code>deprecation</code> attribute is
depended upon by another rule.
depended upon by a target in another package.
</p>

<p>
Expand All @@ -25,10 +25,10 @@
</p>

<p>
If a deprecated rule depends on another deprecated rule, no warning
If a deprecated target depends on another deprecated target, no warning
message is issued.
</p>

<p>
Once people have stopped using it, the package can be removed.
Once people have stopped using it, the target can be removed.
</p>

This file was deleted.

Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<p><code>List of strings; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>

<p>
A list of distribution-method strings to be used for this particular build rule.
A list of distribution-method strings to be used for this particular target.

This is part of a deprecated licensing API that Bazel no longer uses. Don't
use this.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,11 +1,14 @@
<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
<p>
<code>List of <a href="../build-ref.html#labels">labels</a>; optional;
<a href="#configurable-attributes">nonconfigurable</a></code>
</p>

<p>
A list of
<code><a href="platform.html#constraint_value">constraint_values</a></code>
that must be present in the execution platform for this target. This is in
addition to any constraints already set by the rule type. Constraints are used
to restrict the list of available execution platforms, see the description of
<a href="../toolchains.html#toolchain-resolution">toolchain resolution</a>
for details.
</p>
to restrict the list of available execution platforms. For more details, see
the description of
<a href="../toolchains.html#toolchain-resolution">toolchain resolution</a>.
</p>
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<p><code>Dictionary of strings. Default is an empty dictionary.</code></p>
<p><code>Dictionary of strings; optional</code></p>

<p> A dictionary of strings that will be added to the <code>exec_properties</code> of a platform selected for this target. See <code>exec_properties</code> of the <a href="platform.html">platform</a> rule.</p>

Expand Down
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
<p><code>List of <i>features</i>. Default is the empty list.</code></p>
<p><code>List of <i>feature</i> strings; optional</code></p>

<p>A feature is string tag that can be enabled or disabled on a target. The
meaning of a feature depends on the rule itself.</p>

<p>This <code>features</code> attribute is combined with the <a href="${link
package}">package</a> level <code>features</code> attribute. For example, if
the features ["a", "b"] are enabled on the package level, and a rule
the features ["a", "b"] are enabled on the package level, and a target's
<code>features</code> attribute contains ["-a", "c"], the features enabled for the
rule will be "b" and "c".
<a href="https://github.com/bazelbuild/examples/blob/master/rules/features/BUILD">
Expand Down
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional;
<a href="#configurable-attributes">nonconfigurable</a></code></p>

<p>
The list of environments this rule can be built for, <i>instead</i> of
The list of environments this target can be built for, <i>instead</i> of
default-supported environments.
</p>

<p>
This is part of Bazel's soft-launched constraint system. See
This is part of Bazel's constraint system. See
<code><a href="#common.compatible_with">compatible_with</a></code>
for details.
</p>
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@
<p>
<code>List of arbitrary text tags. Tags may be any valid string; default is
the empty list; <a href="#configurable-attributes">nonconfigurable</a></code>
<code>List of strings; optional; <a href="#configurable-attributes">nonconfigurable</a></code>
</p>

<p>
<i>Tags</i> can be used on any rule. <i>Tags</i> on test and
<code>test_suite</code> rules are useful for categorizing the tests.
<i>Tags</i> on non-test rules are used to control sandboxed execution of
<i>Tags</i> on non-test targets are used to control sandboxed execution of
<code>genrule</code>s and

<a href="/versions/{{ site.version }}/skylark/index.html">Starlark</a>
Expand All @@ -15,9 +14,9 @@

<p>
Bazel modifies the behavior of its sandboxing code if it finds the following
keywords in the <code>tags</code> attribute of any test rule or
<code>genrule</code>, or the keys of <code>execution_requirements</code> for
any Starlark action.
keywords in the <code>tags</code> attribute of any test or <code>genrule</code>
target, or the keys of <code>execution_requirements</code> for any Starlark
action.
</p>

<ul>
Expand Down Expand Up @@ -111,4 +110,4 @@
</ul>

See <a href="../test-encyclopedia.html#tag-conventions">Tag Conventions</a> in the
Test Encyclopedia for more conventions on tags attached to test rules.
Test Encyclopedia for more conventions on tags attached to test targets.
Original file line number Diff line number Diff line change
@@ -1,16 +1,15 @@
<p>
<code>List of <a href="../build-ref.html#labels">labels</a>; optional; default
is the empty list</code>
<code>List of <a href="../build-ref.html#labels">labels</a>; optional</code>
</p>

<p>
A list of
<code><a href="platform.html#constraint_value">constraint_value</a></code>s
that must be present in the target platform for this target to be considered
"compatible". This is in addition to any constraints already set by the rule
type. If the target platform does not satisfy all listed constraints then the
target is considered "incompatible". Incompatible targets are skipped for
building and testing when the target pattern is expanded
<em>compatible</em>. This is in addition to any constraints already set by the
rule type. If the target platform does not satisfy all listed constraints then
the target is considered <em>incompatible</em>. Incompatible targets are
skipped for building and testing when the target pattern is expanded
(e.g. `//...`, `:all`). When explicitly specified on the command line,
incompatible targets cause Bazel to print an error and cause a build or test
failure.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
<p><code>Boolean; optional; default False except as noted; <a href="#configurable-attributes">nonconfigurable</a></code></p>
<p><code>Boolean; optional; default False except for test and test suite targets;
<a href="#configurable-attributes">nonconfigurable</a></code></p>

<p>
If True, only testonly targets (such as tests) can depend on this target.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>

<p>
The set of targets whose <a href="${link make-variables}">Make variables</a> the rule is allowed
to access. These rules are either rules that provide
the <code>TemplateVariableInfo</code> provider or special targets for toolchain types built into
Bazel.
These include:
The set of targets whose <a href="${link make-variables}">Make variables</a> this target is
allowed to access. These targets are either instances of rules that provide
<code>TemplateVariableInfo</code> or special targets for toolchain types built into Bazel. These
include:

<ul>
<li><code>@bazel_tools//tools/cpp:current_cc_toolchain</code>
Expand All @@ -16,5 +15,6 @@
Note that this is distinct from the concept of
<a href="../toolchains.html#toolchain-resolution">toolchain resolution</a>
that is used by rule implementations for platform-dependent configuration. You cannot use this
attribute to determine which specific cc_toolchain or java_toolchain a target will use.
attribute to determine which specific <code>cc_toolchain</code> or <code>java_toolchain</code> a
target will use.
</p>
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
otherwise; <a href="#configurable-attributes">nonconfigurable</a></code></p>

<p>
The <code>visibility</code> attribute on a rule controls whether the rule can
be used by other packages. See the documentation for <a href="../visibility.md">visibility</a>.
The <code>visibility</code> attribute on a target controls whether the target
can be used in other packages. See the documentation for
<a href="../visibility.md">visibility</a>.
</p>
Loading

0 comments on commit dac0d40

Please sign in to comment.