diff options
author | brandjon <brandjon@google.com> | 2018-02-26 08:38:43 -0800 |
---|---|---|
committer | Copybara-Service <copybara-piper@google.com> | 2018-02-26 08:40:40 -0800 |
commit | 61dcfc77ceced86883e156d45a4c675d6d11278c (patch) | |
tree | 305f9826211f6a3d1bbf877aed6dd8094bada04f /src/main | |
parent | 4ee8f5d79f49dd3592e27b43528535b67f449625 (diff) |
Revamp docs for default outputs / output groups
- collapsed these into one section
- removed the term "implicit outputs"
- add explanation for what these are first, then how to control them
- update docs for DefaultInfo
- also update docs for test/executable args of rule()
RELNOTES: None
PiperOrigin-RevId: 187026641
Diffstat (limited to 'src/main')
2 files changed, 50 insertions, 32 deletions
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java index 6f7a1bfd62..5e30bb4abe 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java @@ -232,23 +232,33 @@ public class SkylarkRuleClassFunctions { name = "DefaultInfo", returnType = Provider.class, doc = - "A provider that is provided by every rule, even if it is not returned explicitly. " - + "A <code>DefaultInfo</code> accepts the following parameters:" + "A provider that gives general information about a target's direct and transitive files. " + + "Every rule type has this provider, even if it is not returned explicitly by the " + + "rule's implementation function." + + "<p>The <code>DefaultInfo</code> constructor accepts the following parameters:" + "<ul>" - + "<li><code>executable</code></li>" - + "<li><code>files</code></li>" - + "<li><code>runfiles</code></li>" - + "<li><code>data_runfiles</code></li>" - + "<li><code>default_runfiles</code></li>" + + "<li><code>executable</code>: If this rule is marked " + + "<a href='globals.html#rule.executable'><code>executable</code></a> or " + + "<a href='globals.html#rule.test'><code>test</code></a>, this is a " + + "<a href='File.html'><code>File</code></a> object representing the file that should " + + "be executed to run the target. By default it is the predeclared output " + + "<code>ctx.outputs.executable</code>." + + "<li><code>files</code>: A <a href='depset.html'><code>depset<code></a> of " + + "<a href='File.html'><code>File</code></a> objects representing the default outputs " + + "to build when this target is specified on the blaze command line. By default it is " + + "all predeclared outputs." + + "<li><code>runfiles</code>" + + "<li><code>data_runfiles</code>" + + "<li><code>default_runfiles</code>" + "</ul>" - + "Each instance of the default provider contains the following standard " - + "fields: " + + "Each <code>DefaultInfo</code> instance has the following fields: " + "<ul>" - + "<li><code>files</code></li>" - + "<li><code>files_to_run</code></li>" - + "<li><code>data_runfiles</code></li>" - + "<li><code>default_runfiles</code></li>" + + "<li><code>files</code>" + + "<li><code>files_to_run</code>" + + "<li><code>data_runfiles</code>" + + "<li><code>default_runfiles</code>" + "</ul>" + + "See the <a href='../rules.$DOC_EXT'>rules</a> page for more information." ) private static final Provider defaultInfo = DefaultInfo.PROVIDER; @@ -256,12 +266,12 @@ public class SkylarkRuleClassFunctions { name = "OutputGroupInfo", returnType = Provider.class, doc = - "Provides information about output groups the rule provides.<br>" + "A provider that indicates what output groups a rule has.<br>" + "Instantiate this provider with <br>" + "<pre class=language-python>" + "OutputGroupInfo(group1 = <files>, group2 = <files>...)</pre>" - + "See <a href=\"../rules.$DOC_EXT#output-groups\">Output Groups</a> " - + "for more information." + + "See <a href=\"../rules.$DOC_EXT#requesting-output-files\">Requesting output files" + + "</a> for more information." ) private static final Provider outputGroupInfo = OutputGroupInfo.SKYLARK_CONSTRUCTOR; @@ -374,10 +384,14 @@ public class SkylarkRuleClassFunctions { type = Boolean.class, defaultValue = "False", doc = - "Whether this rule is a test rule. " - + "If True, the rule must end with <code>_test</code> (otherwise it must " - + "not), and there must be an action that generates " - + "<code>ctx.outputs.executable</code>." + "Whether this rule is a test rule, that is, whether it may be the subject of a " + + "<code>blaze test</code> or <code>blaze run</code> command. All test rules are " + + "automatically considered <a href='#rule.executable'>executable</a>; it is " + + "unnecessary (and discouraged) to explicitly set <code>executable = True</code> " + + "for a test rule." + + "<p>Test rules must have names ending in the suffix <code>\"_test\"</code>; " + + "non-test rules must not use this suffix. (Note that this applies only to the " + + "name of the rule, not its targets.)" ), @Param( name = "attrs", @@ -418,9 +432,11 @@ public class SkylarkRuleClassFunctions { type = Boolean.class, defaultValue = "False", doc = - "whether this rule is marked as executable or not. If True, " - + "there must be an action that generates " - + "<code>ctx.outputs.executable</code>." + "Whether this rule is considered executable, that is, whether it may be the subject of " + + "a <code>blaze run</code> command. Executable rules automatically get a " + + "predeclared output that is addressable as <code>ctx.outputs.executable</code>. " + + "See the <a href='../rules.$DOC_EXT#output-files'>Rules page</a> for more " + + "information." ), @Param( name = "output_to_genfiles", diff --git a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleContext.java b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleContext.java index ce082a3aea..fe468845c5 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleContext.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleContext.java @@ -118,8 +118,8 @@ public final class SkylarkRuleContext implements SkylarkValue { + "<code>None</code>. If an optional attribute is not specified in the rule " + "then the corresponding struct value is <code>None</code>. If a label type is not " + "marked as <code>executable=True</code>, no corresponding struct field is generated. " - + "<a href=\"https://github.com/bazelbuild/examples/blob/master/rules/actions_run/execute.bzl\">" - + "See example of use</a>."; + + "<a href=\"https://github.com/bazelbuild/examples/blob/master/rules/actions_run/" + + "execute.bzl\">See example of use</a>."; public static final String FILES_DOC = "A <code>struct</code> containing files defined in label or label list " + "type attributes. The struct fields correspond to the attribute names. The struct " @@ -127,7 +127,8 @@ public final class SkylarkRuleContext implements SkylarkValue { + "It is a shortcut for:" + "<pre class=language-python>[f for t in ctx.attr.<ATTR> for f in t.files]</pre> " + "In other words, use <code>files</code> to access the " - + "<a href=\"../rules.$DOC_EXT#default-outputs\">default output</a> of dependencies. " + + "<a href=\"../rules.$DOC_EXT#requesting-output-files\">default outputs</a> of a " + + "dependency. " + "<a href=\"https://github.com/bazelbuild/examples/blob/master/rules/depsets/foo.bzl\">" + "See example of use</a>."; public static final String FILE_DOC = @@ -139,17 +140,18 @@ public final class SkylarkRuleContext implements SkylarkValue { + "marked as <code>allow_single_file</code>, no corresponding struct field is generated. " + "It is a shortcut for:" + "<pre class=language-python>list(ctx.attr.<ATTR>.files)[0]</pre>" - + "In other words, use <code>file</code> to access the " - + "<a href=\"../rules.$DOC_EXT#default-outputs\">default output</a> of a dependency. " - + "<a href=\"https://github.com/bazelbuild/examples/blob/master/rules/expand_template/hello.bzl\">" - + "See example of use</a>."; + + "In other words, use <code>file</code> to access the (singular) " + + "<a href=\"../rules.$DOC_EXT#requesting-output-files\">default output</a> of a " + + "dependency. " + + "<a href=\"https://github.com/bazelbuild/examples/blob/master/rules/expand_template/" + + "hello.bzl\">See example of use</a>."; public static final String ATTR_DOC = "A struct to access the values of the attributes. The values are provided by " + "the user (if not, a default value is used). The attributes of the struct and the " + "types of their values correspond to the keys and values of the <code>attrs</code> " + "dict provided to the <code>rule</code> function. " - + "<a href=\"https://github.com/bazelbuild/examples/blob/master/rules/attributes/printer.bzl\">" - + "See example of use</a>."; + + "<a href=\"https://github.com/bazelbuild/examples/blob/master/rules/attributes/" + + "printer.bzl\">See example of use</a>."; public static final String SPLIT_ATTR_DOC = "A struct to access the values of attributes with split configurations. If the attribute is " + "a label list, the value of split_attr is a dict of the keys of the split (as strings) " |