diff options
3 files changed, 53 insertions, 13 deletions
diff --git a/site/versions/master/docs/skylark/rules.md b/site/versions/master/docs/skylark/rules.md index c730c8423d..47f27abb13 100644 --- a/site/versions/master/docs/skylark/rules.md +++ b/site/versions/master/docs/skylark/rules.md @@ -203,7 +203,7 @@ If left unspecified, it will contain all the declared outputs. ```python def _impl(ctx): # ... - return struct(files=depset([file1, file2])) + return DefaultInfo(files=depset([file1, file2])) ``` This can be useful for exposing files generated with @@ -488,6 +488,37 @@ with an error describing the conflict. To fix, you will need to modify your any targets using your rule, as well as targets of any kind that depend on those targets. +## Output groups + +By default Bazel builds a target's +[default outputs](#default-outputs). However, a rule can also create + other outputs that are not part of a typical build but might still be useful, + such as debug information files. The facility for this is _output groups_. + +A rule can declare that a certain file belongs to a certain output group by returning +the [OutputGroupInfo](lib/globals.html#OutputGroupInfo) provider. Fields of +that provider are output group names: + +```python +def _impl(ctx): + name = ... + binary = ctx.new_file(name) + debug_file = ctx.new_file(name + ".pdb") + # ... add actions to generate these files + return [DefaultInfo(files = depset([binary])), + OutputGroupInfo(debug_files = depset([debug_file]), + all_files = depset([binary, debug_file]))] +``` + +By default, only the `binary` file will be built. +The user can specify an [`--output_groups=debug_files`](../command-line-reference.html#build) +flag on the command line. In that case, only `debug_file` will be built. If the user +specifies `--output_groups=all_files`, both `binary` and `debug_file` will be build. + +> Note: [OutputGroupInfo](skylark/lib/globals.html#OutputGroupInfo) is a regular +> [provider](#providers), and dependencies of a target can examine it using +> the `target[OutputGroupInfo]` syntax. + ## Code coverage instrumentation A rule can use the `instrumented_files` provider to provide information about diff --git a/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java b/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java index e05edfd587..8b692716a1 100644 --- a/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java +++ b/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java @@ -227,7 +227,6 @@ public class BuildRequest implements OptionsClassProvider { converter = Converters.CommaSeparatedOptionListConverter.class, allowMultiple = true, defaultValue = "", - optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, help = "Specifies which output groups of the top-level targets to build. If omitted, a default " + "set of output groups are built. When specified the default set is overridden." diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java index 25c38d7a2d..2e8769eb75 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java @@ -195,18 +195,20 @@ public class SkylarkRuleClassFunctions { name = "DefaultInfo", returnType = ClassObjectConstructor.class, doc = - "A provider that is provided by every rule, even if it iss not returned explicitly. " + "A provider that is provided by every rule, even if it is not returned explicitly. " + "A <code>DefaultInfo</code> accepts the following parameters:" + + "<ul>" + "<li><code>files</code></li>" - + "<ul><li><code>runfiles</code></li>" + + "<li><code>runfiles</code></li>" + "<li><code>data_runfiles</code></li>" + "<li><code>default_runfiles</code></li>" + "</ul>" + "Each instance of the default provider contains the following standard " + "fields: " + + "<ul>" + "<li><code>files</code></li>" + "<li><code>files_to_run</code></li>" - + "<ul><li><code>data_runfiles</code></li>" + + "<li><code>data_runfiles</code></li>" + "<li><code>default_runfiles</code></li>" + "</ul>" ) @@ -215,7 +217,12 @@ public class SkylarkRuleClassFunctions { @SkylarkSignature( name = "OutputGroupInfo", returnType = ClassObjectConstructor.class, - doc = "todo" + doc = + "Provides information about output groups the rule provides.<br>" + + "Instantiate this provider with <br>" + + "<pre class=language-python>" + + "OutputGroupInfo(group1 = <files>, group2 = <files>...)</pre>" + + "See <a href=\"../rules.html#output-groups\">Output Groups</a> for more information" ) private static final ClassObjectConstructor outputGroupInfo = OutputGroupProvider.SKYLARK_CONSTRUCTOR; @@ -239,13 +246,16 @@ public class SkylarkRuleClassFunctions { ) private static final ClassObjectConstructor actions = ActionsProvider.SKYLARK_CONSTRUCTOR; - @SkylarkSignature(name = "provider", returnType = ClassObjectConstructor.class, doc = - "Creates a declared provider 'constructor'. The return value of this" - + "function can be used to create \"struct-like\" values. Example:<br>" - + "<pre class=\"language-python\">data = provider()\n" - + "d = data(x = 2, y = 3)\n" - + "return d.x + d.y # returns 5</pre>", - useLocation = true + @SkylarkSignature( + name = "provider", + returnType = ClassObjectConstructor.class, + doc = + "Creates a declared provider 'constructor'. The return value of this" + + "function can be used to create \"struct-like\" values. Example:<br>" + + "<pre class=\"language-python\">data = provider()\n" + + "d = data(x = 2, y = 3)\n" + + "print(d.x + d.y) # prints 5</pre>", + useLocation = true ) private static final BuiltinFunction provider = new BuiltinFunction("provider") { |