diff options
author | 2018-02-26 08:38:43 -0800 | |
---|---|---|
committer | 2018-02-26 08:40:40 -0800 | |
commit | 61dcfc77ceced86883e156d45a4c675d6d11278c (patch) | |
tree | 305f9826211f6a3d1bbf877aed6dd8094bada04f /src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java | |
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/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java')
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java | 62 |
1 files changed, 39 insertions, 23 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", |