Skip to content

Commit dac0d40

Browse files
Googlercopybara-github
Googler
authored and
copybara-github
committed
Improve "Common Attributes" section
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
1 parent 082d987 commit dac0d40

32 files changed

+179
-134
lines changed

‎src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,8 @@ private void processAttributeDocs(Iterable<RuleDocumentation> ruleDocEntries,
246246
ruleDoc.addAttribute(PredefinedAttributes.TEST_ATTRIBUTES.get(attrName));
247247
} else if (PredefinedAttributes.COMMON_ATTRIBUTES.containsKey(attrName)) {
248248
ruleDoc.addAttribute(PredefinedAttributes.COMMON_ATTRIBUTES.get(attrName));
249+
} else if (PredefinedAttributes.TYPICAL_ATTRIBUTES.containsKey(attrName)) {
250+
ruleDoc.addAttribute(PredefinedAttributes.TYPICAL_ATTRIBUTES.get(attrName));
249251
}
250252
}
251253
}

‎src/main/java/com/google/devtools/build/docgen/DocgenConsts.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ public class DocgenConsts {
6262

6363
public static final String VAR_SECTION_STARLARK_BUILTIN = "SECTION_BUILTIN";
6464

65+
public static final String TYPICAL_ATTRIBUTES = "typical";
6566
public static final String COMMON_ATTRIBUTES = "common";
6667
public static final String TEST_ATTRIBUTES = "test";
6768
public static final String BINARY_ATTRIBUTES = "binary";

‎src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,9 @@ private void writeCommonDefinitionsPage(String outputDir, RuleLinkExpander expan
6868
throws IOException {
6969
Page page = TemplateEngine.newPage(DocgenConsts.COMMON_DEFINITIONS_TEMPLATE);
7070
page.add("expander", expander);
71+
page.add(
72+
"typicalAttributes",
73+
expandCommonAttributes(PredefinedAttributes.TYPICAL_ATTRIBUTES, expander));
7174
page.add("commonAttributes",
7275
expandCommonAttributes(PredefinedAttributes.COMMON_ATTRIBUTES, expander));
7376
page.add("testAttributes",

‎src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -42,19 +42,29 @@ public class PredefinedAttributes {
4242
"templates/attributes/test/local.html");
4343

4444
/**
45-
* List of common attributes documentation, relative to {@link com.google.devtools.build.docgen}.
45+
* List of typical (defined by most rules, but not implicitly added to all rules) attributes
46+
* documentation, relative to {@link com.google.devtools.build.docgen}.
4647
*/
48+
public static final ImmutableList<String> TYPICAL_ATTRIBUTES_DOCFILES =
49+
ImmutableList.of(
50+
"templates/attributes/typical/data.html",
51+
"templates/attributes/typical/deps.html",
52+
"templates/attributes/typical/licenses.html",
53+
"templates/attributes/typical/srcs.html");
54+
55+
/**
56+
* List of common (implicitly added to all rules) attributes documentation, relative to {@link
57+
* com.google.devtools.build.docgen}.
58+
*/
59+
// TODO(b/177233238): This should also document applicable_licenses and transitive_configs.
4760
public static final ImmutableList<String> COMMON_ATTRIBUTES_DOCFILES =
4861
ImmutableList.of(
4962
"templates/attributes/common/compatible_with.html",
50-
"templates/attributes/common/data.html",
5163
"templates/attributes/common/deprecation.html",
52-
"templates/attributes/common/deps.html",
5364
"templates/attributes/common/distribs.html",
5465
"templates/attributes/common/exec_compatible_with.html",
5566
"templates/attributes/common/exec_properties.html",
5667
"templates/attributes/common/features.html",
57-
"templates/attributes/common/licenses.html",
5868
"templates/attributes/common/restricted_to.html",
5969
"templates/attributes/common/tags.html",
6070
"templates/attributes/common/target_compatible_with.html",
@@ -74,8 +84,7 @@ public class PredefinedAttributes {
7484

7585
private static ImmutableMap<String, RuleDocumentationAttribute> generateAttributeMap(
7686
String commonType, ImmutableList<String> filenames) {
77-
ImmutableMap.Builder<String, RuleDocumentationAttribute> builder =
78-
ImmutableMap.<String, RuleDocumentationAttribute>builder();
87+
ImmutableMap.Builder<String, RuleDocumentationAttribute> builder = ImmutableMap.builder();
7988
for (String filename : filenames) {
8089
String name = Files.getNameWithoutExtension(filename);
8190
try {
@@ -92,6 +101,9 @@ private static ImmutableMap<String, RuleDocumentationAttribute> generateAttribut
92101
return builder.build();
93102
}
94103

104+
public static final ImmutableMap<String, RuleDocumentationAttribute> TYPICAL_ATTRIBUTES =
105+
generateAttributeMap(DocgenConsts.TYPICAL_ATTRIBUTES, TYPICAL_ATTRIBUTES_DOCFILES);
106+
95107
public static final ImmutableMap<String, RuleDocumentationAttribute> COMMON_ATTRIBUTES =
96108
generateAttributeMap(DocgenConsts.COMMON_ATTRIBUTES, COMMON_ATTRIBUTES_DOCFILES);
97109

‎src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,9 @@ public void generateDocumentation(List<String> inputDirs, String outputDir, Stri
5454
page.add("expander", expander);
5555

5656
// Populate variables for Common Definitions section.
57+
page.add(
58+
"typicalAttributes",
59+
expandCommonAttributes(PredefinedAttributes.TYPICAL_ATTRIBUTES, expander));
5760
page.add("commonAttributes",
5861
expandCommonAttributes(PredefinedAttributes.COMMON_ATTRIBUTES, expander));
5962
page.add("testAttributes",

‎src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/args.html‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,14 @@
77
</p>
88

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

1616
<p>
1717
<em class="harmful">NOTE: The arguments are not passed when you run the target
18-
outside of bazel (for example, by manually executing the binary in
18+
outside of Bazel (for example, by manually executing the binary in
1919
<code>bazel-bin/</code>).</em>
2020
</p>
21-
22-
<p>
23-
Most binary rules permit an <code>args</code> attribute, but where
24-
this attribute is not allowed, this fact is documented under the
25-
specific rule.
26-
</p>

‎src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/env.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,6 @@
1313

1414
<p>
1515
<em class="harmful">NOTE: The environment variables are not set when you run the target
16-
outside of bazel (for example, by manually executing the binary in
16+
outside of Bazel (for example, by manually executing the binary in
1717
<code>bazel-bin/</code>).</em>
1818
</p>

‎src/main/java/com/google/devtools/build/docgen/templates/attributes/common/compatible_with.html‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
1-
<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
1+
<p><code>List of <a href="../build-ref.html#labels">labels</a>; optional;
2+
<a href="#configurable-attributes">nonconfigurable</a></code></p>
23

34
<p>
4-
The list of environments this rule can be built for, in addition to
5+
The list of environments this target can be built for, in addition to
56
default-supported environments.
67
</p>
78

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

‎src/main/java/com/google/devtools/build/docgen/templates/attributes/common/data.html‎

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deprecation.html‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
<p><code>String; optional; <a href="#configurable-attributes">nonconfigurable</a></code></p>
22

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

2121
<p>
@@ -25,10 +25,10 @@
2525
</p>
2626

2727
<p>
28-
If a deprecated rule depends on another deprecated rule, no warning
28+
If a deprecated target depends on another deprecated target, no warning
2929
message is issued.
3030
</p>
3131

3232
<p>
33-
Once people have stopped using it, the package can be removed.
33+
Once people have stopped using it, the target can be removed.
3434
</p>

0 commit comments

Comments
 (0)