diff options
3 files changed, 59 insertions, 45 deletions
diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md index 2c7e696e68..61aa86c8e3 100644 --- a/site/docs/skylark/rules.md +++ b/site/docs/skylark/rules.md @@ -225,13 +225,13 @@ output*. There are multiple ways for a rule to introduce a predeclared output: automatically, usually by substituting into a template. [See example](https://github.com/bazelbuild/examples/blob/master/rules/default_outputs/extension.bzl) -* If the rule is marked [`executable`](lib/globals.html#rule.executable), an - output is created with the same name as the rule instance itself. - (Technically, the file has no label since it would clash with the rule - instance's own label, but it is still considered a predeclared output.) By - default, this file serves as the binary to run if the target appears on the - command line of a `bazel run` or `bazel test` command. Use the `executable` - argument of `DefaultInfo` to override this behavior. +* If the rule is marked [`executable`](lib/globals.html#rule.executable) or + [`test`](lib/globals.html#rule.test), an output is created with the same name + as the rule instance itself. (Technically, the file has no label since it + would clash with the rule instance's own label, but it is still considered a + predeclared output.) By default, this file serves as the binary to run if the + target appears on the command line of a `bazel run` or `bazel test` command. + See [Executable rules](#executable-rules-and-test-rules) below. [See example](https://github.com/bazelbuild/examples/blob/master/rules/executable/executable.bzl) All predeclared outputs can be accessed within the rule's implementation @@ -636,27 +636,34 @@ if ctx.configuration.coverage_enabled: # Do something to turn on coverage for this compile action ``` -## Executable rules - -An executable rule is a rule that users can run using `bazel run`. - -To make a rule executable, set `executable=True` in the -[rule function](lib/globals.html#rule). The `implementation` function of the -rule must generate the output file `ctx.outputs.executable`. - -[See example](https://github.com/bazelbuild/examples/blob/master/rules/executable/executable.bzl) - -## Test rules - -Test rules are run using `bazel test`. - -To create a test rule, set `test=True` in the -[rule function](lib/globals.html#rule). The name of the rule must -also end with `_test`. Test rules are implicitly executable, which means that -the `implementation` function of the rule must generate the output file -`ctx.outputs.executable`. - -[See example](https://github.com/bazelbuild/examples/blob/master/rules/test_rule/line_length.bzl) +## Executable rules and test rules + +Executable rules define targets that can be invoked by a `bazel run` command. +Test rules are a special kind of executable rule whose targets can also be +invoked by a `bazel test` command. Executable and test rules are created by +setting the respective [`executable`](lib/globals.html#rule.executable) or +[`test`](lib/globals.html#rule.test) argument to true when defining the rule. + +Test rules (but not necessarily their targets) must have names that end in +`_test`. Non-test rules must not have this suffix. + +Both kinds of rules automatically predeclare an output file, which is made +available to the rule implementation function under the name +`ctx.outputs.executable`. The rule implementation function should produce an +action that will generate a corresponding executable file on the file system. +This means that if you use `ctx.actions.write()` to produce the file, then you +should pass `is_executable=True`; and if you use `ctx.actions.run()` or +`ctx.actions.run_shell()` instead, then you should ensure that the binary or +script being invoked sets the executable bit when it creates the file. + +By default, this executable is what will be invoked by the `run` or `test` +commands. Alternatively, you can override this behavior by passing a different +file to the `executable` argument of a returned `DefaultInfo` provider. In that +case, you should not attempt to create an action that has +`ctx.outputs.executable` as an input or output. + +See examples of an [executable rule](https://github.com/bazelbuild/examples/blob/master/rules/executable/executable.bzl) +and a [test rule](https://github.com/bazelbuild/examples/blob/master/rules/test_rule/line_length.bzl). Test rules inherit the following attributes: `args`, `flaky`, `local`, `shard_count`, `size`, `timeout`. The defaults of inherited attributes cannot be diff --git a/src/main/java/com/google/devtools/build/lib/actions/AbstractAction.java b/src/main/java/com/google/devtools/build/lib/actions/AbstractAction.java index 7e264670b8..dcc5080ca6 100644 --- a/src/main/java/com/google/devtools/build/lib/actions/AbstractAction.java +++ b/src/main/java/com/google/devtools/build/lib/actions/AbstractAction.java @@ -63,10 +63,16 @@ import javax.annotation.concurrent.GuardedBy; name = "Action", category = SkylarkModuleCategory.BUILTIN, doc = - "An action created on a <a href=\"ctx.html\">ctx</a> object. You can retrieve these " - + "using the <a href=\"globals.html#Actions\">Actions</a> provider. Some fields are only " - + "applicable for certain kinds of actions. Fields that are inapplicable are set to " - + "<code>None</code>." + "An action created during rule analysis." + + "<p>This object is visible for the purpose of testing, and may be obtained from an " + + "<a href=\"globals.html#Actions\">Actions</a> provider. It is normally not necessary " + + "to access `Action` objects or their fields within a rule's implementation function. " + + "You may instead want to see the " + + "<a href='../rules.$DOC_EXT#actions'>Rules page</a> for a general discussion of how to " + + "use actions when defining custom rules, or the <a href='actions.html'>API reference" + + "</a> for creating actions." + + "<p>Some fields of this object are only applicable for certain kinds of actions. " + + "Fields that are inapplicable are set to <code>None</code>." ) public abstract class AbstractAction implements Action, SkylarkValue { /** 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 b58432c1ef..c5096c9c6b 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 @@ -359,8 +359,12 @@ public class SkylarkRuleClassFunctions { @SkylarkSignature( name = "rule", doc = - "Creates a new rule. Store it in a global value, so that it can be loaded and called " - + "from BUILD files.", + "Creates a new rule, which can be called from a BUILD file or a macro to create targets." + + "<p>Rules must be assigned to global variables in a .bzl file; the name of the " + + "global variable is the rule's name." + + "<p>Test rules are required to have a name ending in <code>_test</code>, while all " + + "other rules must not have this suffix. (This restriction applies only to rules, not " + + "to their targets.)", returnType = BaseFunction.class, parameters = { @Param( @@ -379,13 +383,11 @@ public class SkylarkRuleClassFunctions { defaultValue = "False", doc = "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.)" + + "<code>blaze test</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. See the " + + "<a href='../rules.$DOC_EXT#executable-rules-and-test-rules'>Rules page</a> for " + + "more information." ), @Param( name = "attrs", @@ -427,10 +429,9 @@ public class SkylarkRuleClassFunctions { defaultValue = "False", doc = "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." + + "a <code>blaze run</code> command. See the " + + "<a href='../rules.$DOC_EXT#executable-rules-and-test-rules'>Rules page</a> for " + + "more information." ), @Param( name = "output_to_genfiles", |