diff options
Diffstat (limited to 'src/main/java/com/google/devtools/build/docgen/templates')
17 files changed, 272 insertions, 0 deletions
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 new file mode 100644 index 0000000000..9bc0a5c209 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/args.html @@ -0,0 +1,10 @@ +Add these arguments to the target when executed by +<code>bazel run</code>. +<i>(List of strings; optional; subject to +<a href="#make_variables">"Make variable"</a> substitution and +<a href="#sh-tokenization">Bourne shell tokenization</a>)</i><br/> +These arguments are passed to the target before the target options +specified on the <code>bazel run</code> command line. +<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> diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/output_licenses.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/output_licenses.html new file mode 100644 index 0000000000..8716afabd0 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/output_licenses.html @@ -0,0 +1,22 @@ +The licenses of the output files that this binary generates. +<i>(List of strings; optional)</i><br/> +Describes the licenses of the output of the binary generated by +the rule. When a binary is referenced in a host attribute (for +example, the <code>tools</code> attribute of +a <code>genrule</code>), this license declaration is used rather +than the union of the licenses of its transitive closure. This +argument is useful when a binary is used as a tool during the +build of a rule, and it is not desirable for its license to leak +into the license of that rule. If this attribute is missing, the +license computation proceeds as if the host dependency was a +regular dependency. +<p>(For more about the distinction between host and target +configurations, +see <a href="bazel-user-manual.html#configurations">Build +configurations</a> in the Bazel manual.) +<p><em class="harmful">WARNING: in some cases (specifically, in +genrules) the build tool cannot guarantee that the binary +referenced by this attribute is actually used as a tool, and is +not, for example, copied to the output. In these cases, it is the +responsibility of the user to make sure that this is +true.</em></p> 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 new file mode 100644 index 0000000000..a0815ed77b --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/data.html @@ -0,0 +1,11 @@ +The list of files needed by this rule at runtime. +<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/> +Targets named in the <code>data</code> attribute will appear in +the <code>*.runfiles</code> 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 +<a href="build-ref.html#data">data dependencies</a> section for more +information about how to depend on and use data files. +<p>Almost all rules permit a <code>data</code> attribute, but where +this attribute is not allowed, this fact is documented under the +specific rule.</p> 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 new file mode 100644 index 0000000000..707fc0739d --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deprecation.html @@ -0,0 +1,24 @@ +<i>(String; optional)</i><br/> +An explanatory warning message associated with this rule. +Typically this is used to notify users that a rule 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 +that one can easily find out what changes are required to avoid the message. +If there is a new target that can be used as a drop in replacement, it is a +good idea to just migrate all users of the old target. +<p> +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.</p> +<p> +Intra-package dependencies are exempt from this warning, so that, +for example, building the tests of a deprecated rule does not +encounter a warning.</p> +<p> +If a deprecated rule depends on another deprecated rule, no warning +message is issued.</p> +<p> +Once people have stopped using it, the package can be removed or marked as +<a href="#common.obsolete"><code>obsolete</code></a>.</p> 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 new file mode 100644 index 0000000000..9b42a2b9ca --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deps.html @@ -0,0 +1,20 @@ +A list of dependencies of this rule. +<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/> +The precise semantics of what it means for this rule to depend on +another using <code>deps</code> 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 <code>deps</code> will +appear in the <code>*.runfiles</code> area of this rule, if it has +one. +<p>Most often, a <code>deps</code> 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 <code>java_library</code> rule may depend on C++ code in +a <code>cc_library</code> rule, by declaring the latter in +the <code>deps</code> attribute. See the definition +of <a href="build-ref.html#deps">dependencies</a> for more +information.</p> +<p>Almost all rules permit a <code>deps</code> attribute, but where +this attribute is not allowed, this fact is documented under the +specific rule.</p> 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 new file mode 100644 index 0000000000..4ce607870a --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/distribs.html @@ -0,0 +1,4 @@ +<i>(List of strings; optional)</i><br/> +A list of distribution-method strings to be used for this particular build rule. +Overrides the <code>BUILD</code>-file scope defaults defined by the +<a href="#distribs"><code>distribs()</code></a> directive. 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/common/licenses.html new file mode 100644 index 0000000000..e0f831e4a1 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/licenses.html @@ -0,0 +1,4 @@ +<i>(List of strings; optional)</i><br/> +A list of license-type strings to be used for this particular build rule. +Overrides the <code>BUILD</code>-file scope defaults defined by the +<a href="#licenses"><code>licenses()</code></a> directive. diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/obsolete.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/obsolete.html new file mode 100644 index 0000000000..93363c5245 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/obsolete.html @@ -0,0 +1,9 @@ +<i>(Boolean; optional; default 0)</i><br/> +If 1, only obsolete targets can depend on this target. It is an error when +a non-obsolete target depends on an obsolete target. +<p> +As a transition, one can first mark a package as in +<a href="#common.deprecation"><code>deprecation</code></a>.</p> +<p> +This attribute is useful when you want to prevent a target from +being used but are yet not ready to delete the sources.</p> 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 new file mode 100644 index 0000000000..e26672cb2a --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html @@ -0,0 +1,18 @@ +List of arbitrary text tags. Tags may be any valid string; default is the +empty list.<br/> +<i>Tags</i> can be used on any rule; but <i>tags</i> are most useful +on test and <code>test_suite</code> rules. Tags on non-test rules +are only useful to humans and/or external programs. +<i>Tags</i> are generally used to annotate a test's role in your debug +and release process. Typically, tags are most useful for C++ and +Python tests, which +lack any runtime annotation ability. The use of tags and size elements +gives flexibility in assembling suites of tests based around codebase +check-in policy. +<p> +A few tags have special meaning to the build tool, such as +indicating that a particular test cannot be run remotely, for +example. Consult +the <a href='bazel-user-manual.html#tags_keywords'>Bazel +documentation</a> for details. +</p> 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 new file mode 100644 index 0000000000..0e9a80f765 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/testonly.html @@ -0,0 +1,20 @@ +<i>(Boolean; optional; default 0 except as noted)</i><br /> +If 1, only testonly targets (such as tests) can depend on this target. +<p>Equivalently, a rule that is not <code>testonly</code> is not allowed to +depend on any rule that is <code>testonly</code>.</p> +<p>Tests (<code>*_test</code> rules) +and test suites (<a href="#test_suite">test_suite</a> rules) +are <code>testonly</code> by default.</p> +<p>By virtue of +<a href="#package.default_testonly"><code>default_testonly</code></a>, +targets under <code>javatests</code> are <code>testonly</code> by default.</p> +<p>This attribute is intended to mean that the target should not be +contained in binaries that are released to production.</p> +<p>Because testonly is enforced at build time, not run time, and propagates +virally through the dependency tree, it should be applied judiciously. For +example, stubs and fakes that +are useful for unit tests may also be useful for integration tests +involving the same binaries that will be released to production, and +therefore should probably not be marked testonly. Conversely, rules that +are dangerous to even link in, perhaps because they unconditionally +override normal behavior, should definitely be marked testonly.</p> 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 new file mode 100644 index 0000000000..65e6ce309b --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html @@ -0,0 +1,99 @@ +<i>(List of <a href="build-ref.html#labels">labels</a>; optional; +default private)</i><br/> +<p>The <code>visibility</code> attribute on a rule controls whether +the rule can be used by other packages. Rules are always visible to +other rules declared in the same package.</p> +<p>There are five forms (and one temporary form) a visibility label can take: +<ul> +<li><code>["//visibility:public"]</code>: Anyone can use this rule.</li> +<li><code>["//visibility:private"]</code>: Only rules in this package +can use this rule. Rules in <code>javatests/foo/bar</code> +can always use rules in <code>java/foo/bar</code>. +</li> +<li><code>["//some/package:__pkg__", "//other/package:__pkg__"]</code>: +Only rules in <code>some/package</code> and <code>other/package</code> +(defined in <code>some/package/BUILD</code> and +<code>other/package/BUILD</code>) have access to this rule. Note that +sub-packages do not have access to the rule; for example, +<code>//some/package/foo:bar</code> or +<code>//other/package/testing:bla</code> wouldn't have access. +<code>__pkg__</code> is a special target and must be used verbatim. +It represents all of the rules in the package. +</li> +<li><code>["//project:__subpackages__", "//other:__subpackages__"]</code>: +Only rules in packages <code>project</code> or <code>other</code> or +in one of their sub-packages have access to this rule. For example, +<code>//project:rule</code>, <code>//project/library:lib</code> or +<code>//other/testing/internal:munge</code> are allowed to depend on +this rule (but not <code>//independent:evil</code>) +</li> +<li><code>["//some/package:my_package_group"]</code>: +A <a href="#package_group">package group</a> is +a named set of package names. Package groups can also grant access rights +to entire subtrees, e.g.<code>//myproj/...</code>. +</li> + +</ul> +<p>The visibility specifications of + +<code>//visibility:public</code> and <code>//visibility:private</code> +can not be combined with any other visibility specifications. +A visibility specification may contain a combination of package labels +(i.e. <code>//foo:__pkg__</code>) and <code>package_group</code>s.</p> +<p>If a rule does not specify the visibility attribute, +the <code><a href="#package">default_visibility</a></code> +attribute of the <code><a href="#package">package</a></code> +statement in the BUILD file containing the rule is used +(except <a href="#exports_files">exports_files</a> + +).</p> +<p>If the default visibility for the package is not specified, +the rule is private.</p> +<p><b>Example</b>:</p> +<p> +File <code>//frobber/bin/BUILD</code>: +</p> +<pre class="code"> +# This rule is visible to everyone +cc_binary( + name = "executable", + visibility = ["//visibility:public"], + deps = [":library"], +) + +# This rule is visible only to rules declared in the same package +cc_library( + name = "library", + visibility = ["//visibility:private"], +) + +# This rule is visible to rules in package //object and //noun +cc_library( + name = "subject", + visibility = [ + "//noun:__pkg__", + "//object:__pkg__", + ], +) + +# See package group "//frobber:friends" (below) for who can access this rule. +cc_library( + name = thingy, + visibility = ["//frobber:friends"], +) +</pre> +<p> +File <code>//frobber/BUILD</code>: +</p> +<pre class="code"> +# This is the package group declaration to which rule //frobber/bin:thingy refers. +# +# Our friends are packages //frobber, //fribber and any subpackage of //fribber. +package_group( + name = "friends", + packages = [ + "//fribber/...", + "//frobber", + ], +) +</pre> 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 new file mode 100644 index 0000000000..3991ac46b3 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/args.html @@ -0,0 +1,7 @@ +Add these arguments to the <code>--test_arg</code> +when executed by <code>bazel test</code>. +<i>(List of strings; optional; subject to +<a href="#make_variables">"Make variable"</a> substitution and +<a href="#sh-tokenization">Bourne shell tokenization</a>)</i><br/> +These arguments are passed before the <code>--test_arg</code> values +specified on the <code>bazel test</code> command line. 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 new file mode 100644 index 0000000000..be0eea747d --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/flaky.html @@ -0,0 +1,5 @@ +Marks test as flaky. <i>(Boolean; optional)</i><br/> +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. 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 new file mode 100644 index 0000000000..7c89b545c5 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html @@ -0,0 +1 @@ +<div></div> 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 new file mode 100644 index 0000000000..7c89b545c5 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html @@ -0,0 +1 @@ +<div></div> diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/size.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/size.html new file mode 100644 index 0000000000..54853458f7 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/size.html @@ -0,0 +1,8 @@ +How "heavy" the test is +<i>(String "enormous", "large" "medium" or "small", +default is "medium")</i><br/> +A classification of the test's "heaviness": how much time/resources +it needs to run. +Unittests are considered "small", integration tests "medium", and +end-to-end tests "large" or "enormous". Bazel uses the size only +to determine a default timeout. diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/timeout.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/timeout.html new file mode 100644 index 0000000000..a43e6680b6 --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/test/timeout.html @@ -0,0 +1,9 @@ +How long the test is +normally expected to run before returning. +<i>(String "eternal", "long", "moderate", or "short" +with the default derived from a test's size attribute)</i><br/> +While a test's size attribute controls resource estimation, a test's +timeout may be set independently. If not explicitly specified, the +timeout is based on the test's size (with "small" ⇒ "short", +"medium" ⇒ "moderate", etc...). "short" means 1 minute, "moderate" +5 minutes, and "long" 15 minutes. |