From 61dcfc77ceced86883e156d45a4c675d6d11278c Mon Sep 17 00:00:00 2001 From: brandjon Date: Mon, 26 Feb 2018 08:38:43 -0800 Subject: 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 --- .../skylark/SkylarkRuleClassFunctions.java | 62 ++++++++++++++-------- .../lib/analysis/skylark/SkylarkRuleContext.java | 20 +++---- 2 files changed, 50 insertions(+), 32 deletions(-) (limited to 'src/main/java/com/google/devtools') 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 DefaultInfo 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." + + "

The DefaultInfo constructor accepts the following parameters:" + "

" - + "Each instance of the default provider contains the following standard " - + "fields: " + + "Each DefaultInfo instance has the following fields: " + "
    " - + "
  • files
    • " - + "
  • files_to_run
    • " - + "
  • data_runfiles
    • " - + "
  • default_runfiles
    • " + + "
  • files" + + "
  • files_to_run" + + "
  • data_runfiles" + + "
  • default_runfiles" + "
" + + "See the rules 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.
" + "A provider that indicates what output groups a rule has.
" + "Instantiate this provider with
" + "
"
             + "OutputGroupInfo(group1 = <files>, group2 = <files>...)
" - + "See Output Groups " - + "for more information." + + "See Requesting output files" + + " 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 _test (otherwise it must " - + "not), and there must be an action that generates " - + "ctx.outputs.executable." + "Whether this rule is a test rule, that is, whether it may be the subject of a " + + "blaze test or blaze run command. All test rules are " + + "automatically considered executable; it is " + + "unnecessary (and discouraged) to explicitly set executable = True " + + "for a test rule." + + "

Test rules must have names ending in the suffix \"_test\"; " + + "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 " - + "ctx.outputs.executable." + "Whether this rule is considered executable, that is, whether it may be the subject of " + + "a blaze run command. Executable rules automatically get a " + + "predeclared output that is addressable as ctx.outputs.executable. " + + "See the Rules page 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 { + "None. If an optional attribute is not specified in the rule " + "then the corresponding struct value is None. If a label type is not " + "marked as executable=True, no corresponding struct field is generated. " - + "" - + "See example of use."; + + "See example of use."; public static final String FILES_DOC = "A struct 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:" + "

[f for t in ctx.attr.<ATTR> for f in t.files]
" + "In other words, use files to access the " - + "default output of dependencies. " + + "default outputs of a " + + "dependency. " + "" + "See example of use."; public static final String FILE_DOC = @@ -139,17 +140,18 @@ public final class SkylarkRuleContext implements SkylarkValue { + "marked as allow_single_file, no corresponding struct field is generated. " + "It is a shortcut for:" + "
list(ctx.attr.<ATTR>.files)[0]
" - + "In other words, use file to access the " - + "default output of a dependency. " - + "" - + "See example of use."; + + "In other words, use file to access the (singular) " + + "default output of a " + + "dependency. " + + "See example of use."; 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 attrs " + "dict provided to the rule function. " - + "" - + "See example of use."; + + "See example of use."; 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) " -- cgit v1.2.3