aboutsummaryrefslogtreecommitdiffhomepage
path: root/src/main/java/com/google/devtools/build/docgen/templates
diff options
context:
space:
mode:
Diffstat (limited to 'src/main/java/com/google/devtools/build/docgen/templates')
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/args.html10
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/binary/output_licenses.html22
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/common/data.html11
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deprecation.html24
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/common/deps.html20
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/common/distribs.html4
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/common/licenses.html4
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/common/obsolete.html9
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html18
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/common/testonly.html20
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/common/visibility.html99
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/test/args.html7
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/test/flaky.html5
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/test/local.html1
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/test/shard_count.html1
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/test/size.html8
-rw-r--r--src/main/java/com/google/devtools/build/docgen/templates/attributes/test/timeout.html9
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" &rArr; "short",
+"medium" &rArr; "moderate", etc...). "short" means 1 minute, "moderate"
+5 minutes, and "long" 15 minutes.