From dac0d40d0eb903f5cb70341398d1a333c19adf3a Mon Sep 17 00:00:00 2001 From: Googler Date: Wed, 13 Jan 2021 06:56:57 -0800 Subject: [PATCH] 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 --- .../build/docgen/BuildDocCollector.java | 2 ++ .../devtools/build/docgen/DocgenConsts.java | 1 + .../MultiPageBuildEncyclopediaProcessor.java | 3 ++ .../build/docgen/PredefinedAttributes.java | 24 ++++++++++---- .../SinglePageBuildEncyclopediaProcessor.java | 3 ++ .../templates/attributes/binary/args.html | 10 ++---- .../templates/attributes/binary/env.html | 2 +- .../attributes/common/compatible_with.html | 12 +++---- .../templates/attributes/common/data.html | 20 ------------ .../attributes/common/deprecation.html | 10 +++--- .../templates/attributes/common/deps.html | 32 ------------------- .../templates/attributes/common/distribs.html | 2 +- .../common/exec_compatible_with.html | 13 +++++--- .../attributes/common/exec_properties.html | 2 +- .../templates/attributes/common/features.html | 4 +-- .../attributes/common/restricted_to.html | 7 ++-- .../templates/attributes/common/tags.html | 13 ++++---- .../common/target_compatible_with.html | 11 +++---- .../templates/attributes/common/testonly.html | 3 +- .../attributes/common/toolchains.html | 12 +++---- .../attributes/common/visibility.html | 5 +-- .../templates/attributes/test/args.html | 6 ++-- .../attributes/test/env_inherit.html | 2 +- .../templates/attributes/test/flaky.html | 10 +++--- .../templates/attributes/test/local.html | 5 ++- .../attributes/test/shard_count.html | 3 +- .../templates/attributes/typical/data.html | 26 +++++++++++++++ .../templates/attributes/typical/deps.html | 31 ++++++++++++++++++ .../{common => typical}/licenses.html | 3 +- .../templates/attributes/typical/srcs.html | 13 ++++++++ .../docgen/templates/be/common-definitions.vm | 20 ++++++++---- .../build/docgen/templates/be/overview.vm | 3 +- 32 files changed, 179 insertions(+), 134 deletions(-) delete mode 100644 src/main/java/com/google/devtools/build/docgen/templates/attributes/common/data.html delete mode 100644 src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deps.html create mode 100644 src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/data.html create mode 100644 src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/deps.html rename src/main/java/com/google/devtools/build/docgen/templates/attributes/{common => typical}/licenses.html (87%) create mode 100644 src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/srcs.html diff --git a/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java b/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java index 552976c61d2323..a7438ad21eb07b 100644 --- a/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java +++ b/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java @@ -246,6 +246,8 @@ private void processAttributeDocs(Iterable 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)); } } } diff --git a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java index af957ff4c41cad..19a4ae71aab2b2 100644 --- a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java +++ b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java @@ -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"; diff --git a/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java b/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java index 9bbdf6300f0f93..d930041f66e1c9 100644 --- a/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java +++ b/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java @@ -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", diff --git a/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java b/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java index d839ccadaf2534..e0f8608f7ffe67 100644 --- a/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java +++ b/src/main/java/com/google/devtools/build/docgen/PredefinedAttributes.java @@ -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 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 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", @@ -74,8 +84,7 @@ public class PredefinedAttributes { private static ImmutableMap generateAttributeMap( String commonType, ImmutableList filenames) { - ImmutableMap.Builder builder = - ImmutableMap.builder(); + ImmutableMap.Builder builder = ImmutableMap.builder(); for (String filename : filenames) { String name = Files.getNameWithoutExtension(filename); try { @@ -92,6 +101,9 @@ private static ImmutableMap generateAttribut return builder.build(); } + public static final ImmutableMap TYPICAL_ATTRIBUTES = + generateAttributeMap(DocgenConsts.TYPICAL_ATTRIBUTES, TYPICAL_ATTRIBUTES_DOCFILES); + public static final ImmutableMap COMMON_ATTRIBUTES = generateAttributeMap(DocgenConsts.COMMON_ATTRIBUTES, COMMON_ATTRIBUTES_DOCFILES); diff --git a/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java b/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java index 883b1411e92d3b..346cc339b3791d 100644 --- a/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java +++ b/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java @@ -54,6 +54,9 @@ public void generateDocumentation(List 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", diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/args.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/args.html index 01cb9c7e2b9ad4..aa17f6d5ab272c 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/args.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/args.html @@ -7,7 +7,7 @@

-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 run command or as a test. These arguments are passed before the ones that are specified on the bazel run or bazel test command line. @@ -15,12 +15,6 @@

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 bazel-bin/).

- -

-Most binary rules permit an args attribute, but where -this attribute is not allowed, this fact is documented under the -specific rule. -

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/env.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/env.html index 80cb86bcbbfbf5..8885781f28c2b9 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/env.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/env.html @@ -13,6 +13,6 @@

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 bazel-bin/).

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/compatible_with.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/compatible_with.html index 16fc1fefd53e92..3beb7eeee0026b 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/compatible_with.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/compatible_with.html @@ -1,15 +1,15 @@ -

List of labels; optional; nonconfigurable

+

List of labels; optional; + nonconfigurable

-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.

-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 ConstraintSemantics for details.

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/data.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/data.html deleted file mode 100644 index 5be4ef2009bcf4..00000000000000 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/data.html +++ /dev/null @@ -1,20 +0,0 @@ -

List of labels; optional

- -

-The list of files needed by this rule at runtime. -

- -

-Targets named in the data attribute will appear in -the *.runfiles area of this rule, if it has one. This -may include data files needed by a binary or library, or other -programs needed by it. See the -data dependencies section for more -information about how to depend on and use data files. -

- -

-Almost all rules permit a data attribute, but where -this attribute is not allowed, this fact is documented under the -specific rule. -

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deprecation.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deprecation.html index abd667df563cd3..9ee89e4dcb10a5 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deprecation.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deprecation.html @@ -1,8 +1,8 @@

String; optional; nonconfigurable

-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 @@ -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 deprecation attribute is -depended upon by another rule. +depended upon by a target in another package.

@@ -25,10 +25,10 @@

-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.

-Once people have stopped using it, the package can be removed. +Once people have stopped using it, the target can be removed.

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deps.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deps.html deleted file mode 100644 index 806e3dedc7a470..00000000000000 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deps.html +++ /dev/null @@ -1,32 +0,0 @@ -

List of labels; optional

- -

-A list of dependencies of this rule. -

- -

-The precise semantics of what it means for this rule to depend on -another using deps are specific to the kind of this rule, -and the rule-specific documentation below goes into more detail. -At a minimum, though, the targets named via deps will -appear in the *.runfiles area of this rule, if it has -one. -

- -

-Most often, a deps dependency is used to allow one -module to use symbols defined in another module written in the -same programming language and separately compiled. Cross-language -dependencies are also permitted in many cases: for example, -a java_library rule may depend on C++ code in -a cc_library rule, by declaring the latter in -the deps attribute. See the definition -of dependencies for more -information. -

- -

-Almost all rules permit a deps attribute, but where -this attribute is not allowed, this fact is documented under the -specific rule. -

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/distribs.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/distribs.html index cd468dddd49b35..c54f7fc3c478de 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/distribs.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/distribs.html @@ -1,7 +1,7 @@

List of strings; optional; nonconfigurable

- 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. diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.html index a920e6ad09e75d..c027e398139efe 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_compatible_with.html @@ -1,11 +1,14 @@ -

List of labels; optional; nonconfigurable

+

+List of labels; optional; +nonconfigurable +

A list of constraint_values 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 - toolchain resolution - for details. -

+to restrict the list of available execution platforms. For more details, see +the description of + toolchain resolution. +

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_properties.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_properties.html index ae6f0094cd30bc..9d3d73a1ca6734 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_properties.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/exec_properties.html @@ -1,4 +1,4 @@ -

Dictionary of strings. Default is an empty dictionary.

+

Dictionary of strings; optional

A dictionary of strings that will be added to the exec_properties of a platform selected for this target. See exec_properties of the platform rule.

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/features.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/features.html index 5ac9dd96c81acd..9358816f071742 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/features.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/features.html @@ -1,11 +1,11 @@ -

List of features. Default is the empty list.

+

List of feature strings; optional

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

This features attribute is combined with the package level features 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 features attribute contains ["-a", "c"], the features enabled for the rule will be "b" and "c". diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/restricted_to.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/restricted_to.html index fb0ece459cbcbd..c3c2e5b6f18556 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/restricted_to.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/restricted_to.html @@ -1,12 +1,13 @@ -

List of labels; optional; nonconfigurable

+

List of labels; optional; + nonconfigurable

-The list of environments this rule can be built for, instead of +The list of environments this target can be built for, instead of default-supported environments.

-This is part of Bazel's soft-launched constraint system. See +This is part of Bazel's constraint system. See compatible_with for details.

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html index f7a1fde401baab..4ffcbc9263154b 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html @@ -1,12 +1,11 @@

- List of arbitrary text tags. Tags may be any valid string; default is - the empty list; nonconfigurable + List of strings; optional; nonconfigurable

Tags can be used on any rule. Tags on test and test_suite rules are useful for categorizing the tests. - Tags on non-test rules are used to control sandboxed execution of + Tags on non-test targets are used to control sandboxed execution of genrules and Starlark @@ -15,9 +14,9 @@

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

    @@ -111,4 +110,4 @@
See Tag Conventions in the -Test Encyclopedia for more conventions on tags attached to test rules. +Test Encyclopedia for more conventions on tags attached to test targets. diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/target_compatible_with.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/target_compatible_with.html index c65186acb52806..5e698f9b07f5c3 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/target_compatible_with.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/target_compatible_with.html @@ -1,16 +1,15 @@

-List of labels; optional; default -is the empty list +List of labels; optional

A list of constraint_values 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 +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 (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. diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/testonly.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/testonly.html index 7c3871538a36db..736e49e0dccdb8 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/testonly.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/testonly.html @@ -1,4 +1,5 @@ -

Boolean; optional; default False except as noted; nonconfigurable

+

Boolean; optional; default False except for test and test suite targets; + nonconfigurable

If True, only testonly targets (such as tests) can depend on this target. diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/toolchains.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/toolchains.html index be8933449a2ef7..645337d69fa63e 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/toolchains.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/toolchains.html @@ -1,11 +1,10 @@

List of labels; optional; nonconfigurable

- The set of targets whose Make variables the rule is allowed - to access. These rules are either rules that provide - the TemplateVariableInfo provider or special targets for toolchain types built into -Bazel. -These include: + The set of targets whose Make variables this target is + allowed to access. These targets are either instances of rules that provide + TemplateVariableInfo or special targets for toolchain types built into Bazel. These + include:

  • @bazel_tools//tools/cpp:current_cc_toolchain @@ -16,5 +15,6 @@ Note that this is distinct from the concept of toolchain resolution 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 cc_toolchain or java_toolchain a + target will use.

    diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html index 749b02a60acbaa..ab95f54a526cef 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html @@ -4,6 +4,7 @@ otherwise; nonconfigurable

    -The visibility attribute on a rule controls whether the rule can -be used by other packages. See the documentation for visibility. +The visibility attribute on a target controls whether the target +can be used in other packages. See the documentation for +visibility.

    diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/args.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/args.html index 7dab0d99d15570..c384583a3c5296 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/args.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/args.html @@ -3,10 +3,10 @@ "Make variable" substitution, and Bourne shell tokenization

    -

    Add these arguments to the --test_arg -when executed by bazel test.

    +

    Command line arguments that Bazel passes to the target when it is +executed with bazel test.

    -These arguments are passed before the --test_arg values +These arguments are passed before any --test_arg values specified on the bazel test command line.

    diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env_inherit.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env_inherit.html index a2c8366696087d..22cceb477d854f 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env_inherit.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/env_inherit.html @@ -1,4 +1,4 @@ -

    List of strings; optional

    +

    List of strings; optional

    Specifies additional environment variables to inherit from the external environment when the test is executed by bazel test. diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/flaky.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/flaky.html index 3447010c80410e..6fc8590214e6e6 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/flaky.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/flaky.html @@ -1,12 +1,12 @@ -

    Boolean; optional; nonconfigurable

    +

    Boolean; optional; default False; nonconfigurable

    Marks test as flaky.

    -If set, executes the test up to 3 times before being declared as failed. -By default this attribute is set to 0 and test is considered to be stable. -Note, that use of this attribute is generally discouraged - we do prefer -all tests to be stable. +If set, executes the test up to three times, marking it as failed only if it +fails each time. By default, this attribute is set to False and the test is +executed only once. Note, that use of this attribute is generally discouraged - +tests should pass reliably when their assertions are upheld.

    diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html index 17d2683d93b920..a6e8c0ecc3c5a1 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html @@ -1,7 +1,6 @@ -

    Boolean; optional; nonconfigurable

    +

    Boolean; default False; nonconfigurable

    Forces the test to be run locally, without sandboxing.

    -

    By default this attribute is set to 0 and the default testing strategy is -used. This is equivalent to providing "local" as a tag +

    Setting this to True is equivalent to providing "local" as a tag (tags=["local"]).

    diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html index 2e7b4030aec9da..c9af3c9765bb04 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html @@ -1,5 +1,4 @@ -

    Non-negative integer less than or equal to 50; -optional

    +

    Non-negative integer less than or equal to 50; optional

    Specifies the number of parallel shards to use to run the test.

    diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/data.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/data.html new file mode 100644 index 00000000000000..e86ab042aa03a1 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/data.html @@ -0,0 +1,26 @@ + +

    List of labels; optional

    + +

    +Files needed by this rule at runtime. May list file or rule targets. Generally +allows any target. +

    + +

    +The default outputs and runfiles of targets in the data attribute +should appear in the *.runfiles area of any executable which is +output by or has a runtime dependency on this target. This may include data +files or binaries used when this target's +srcs are executed. See the +data dependencies section for more +information about how to depend on and use data files. +

    + +

    +New rules should define a data attribute if they process +inputs which might use other inputs at runtime. Rules' implementation functions +must also populate the target's +runfiles from the outputs and runfiles of any data attribute, +as well as runfiles from any dependency attribute which provides either +source code or runtime dependencies. +

    diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/deps.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/deps.html new file mode 100644 index 00000000000000..6efe4e60ef1446 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/deps.html @@ -0,0 +1,31 @@ + +

    List of labels; optional

    + +

    +Dependencies for this target. Generally should only list rule targets. (Though +some rules permit files to be listed directly in deps, this +should be avoided when possible.) +

    + +

    +Language-specific rules generally limit the listed targets to those with +specific providers. +

    + +

    +The precise semantics of what it means for a target to depend on another using +deps are specific to the kind of rule, and the rule-specific +documentation goes into more detail. For rules which process source code, +deps generally specifies code dependencies used by the code in +srcs. +

    + +

    +Most often, a deps dependency is used to allow one module to use +symbols defined in another module written in the same programming language and +separately compiled. Cross-language dependencies are also permitted in many +cases: For example, a java_library target may depend on C++ code +in a cc_library target, by listing the latter in the +deps attribute. See the definition of +dependencies for more information. +

    diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/licenses.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/licenses.html similarity index 87% rename from src/main/java/com/google/devtools/build/docgen/templates/attributes/common/licenses.html rename to src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/licenses.html index d8392992fc0758..ca28662a6662b6 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/licenses.html +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/licenses.html @@ -1,7 +1,8 @@ +

    List of strings; optional; nonconfigurable

    - A list of license-type strings to be used for this particular build rule. + A list of license-type 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. diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/srcs.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/srcs.html new file mode 100644 index 00000000000000..9b7b1ade6bb2f5 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/typical/srcs.html @@ -0,0 +1,13 @@ +

    List of labels; + optional

    + +

    +Files processed or included by this rule. Generally lists files directly, but +may list rule targets (like filegroup or genrule) to +include their default outputs. +

    + +

    +Language-specific rules often require that the listed files have particular +file extensions. +

    diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm index 08c69a02610616..717db6ddbde2e1 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm +++ b/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm @@ -11,7 +11,7 @@ title: Common Definitions

    Common definitions

    This section defines various terms and concepts that are common to -many functions or build rules below. +many functions or build rules.

    #if (!$singlePage) @@ -20,6 +20,7 @@ many functions or build rules below.