From 3b6370ced0de326b34a89db2ce13bcdfa276bbc5 Mon Sep 17 00:00:00 2001 From: Laurent Le Brun Date: Fri, 17 Feb 2017 13:13:58 +0000 Subject: Add more links and explainations in the rules page -- PiperOrigin-RevId: 147827926 MOS_MIGRATED_REVID=147827926 --- site/versions/master/docs/skylark/rules.md | 54 +++++++++++++++++------------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/site/versions/master/docs/skylark/rules.md b/site/versions/master/docs/skylark/rules.md index a93ece56e0..61f80edbe5 100644 --- a/site/versions/master/docs/skylark/rules.md +++ b/site/versions/master/docs/skylark/rules.md @@ -7,16 +7,20 @@ title: Rules **Status: Experimental**. We may make breaking changes to the API, but we will help you update your code. -A rule defines a series of actions that Bazel should perform on inputs to get a -set of outputs. For example, a C++ binary rule might take a set of .cpp -files (the inputs), run `g++` on them (the action), and return an executable -file (the output). +A rule defines a series of [actions](#actions) that Bazel should perform on +inputs to get a set of outputs. For example, a C++ binary rule might take a set +of .cpp files (the inputs), run `g++` on them (the action), and return an +executable file (the output). Note that, from Bazel's perspective, `g++` and the standard C++ libraries are also inputs to this rule. As a rule writer, you must consider not only the user-provided inputs to a rule, but also all of the tools and libraries required to execute the actions (called _implicit inputs_). +Before creating or modifying any rule, make sure you are familiar with the +[extensibility model](concepts.md) (understand the three phases and the +differences between macros and rules). + ## Rule creation In a `.bzl` file, use the [rule](lib/globals.html#rule) @@ -40,8 +44,9 @@ attribute, you can refer to it with a label, and you can see it in The rule is analyzed when you explicitly build it, or if it is a dependency of the build. In this case, Bazel will execute its `implementation` function. This function decides what the outputs of the rule are and how to build them (using -`actions`). During analysis, no external command can be executed: actions will -be run in the execution phase. +[actions](#actions)). During the [analysis phase](concepts.md#evaluation-model), +no external command can be executed. Instead, actions are registered and +will be run in the execution phase, if their output is needed for the build. ## Attributes @@ -93,13 +98,14 @@ metal_compile = rule( ## Implementation function -Every rule requires an `implementation` function. It contains the actual -logic of the rule and is executed strictly in the Analysis Phase. The function -has exactly one input parameter, `ctx`, and it may return -the [runfiles](#runfiles) and [providers](#providers) -of the rule. The input parameter `ctx` can be used to access attribute values, -outputs and dependent targets, and files. It also has some helper functions. -See [the library](lib/ctx.html) for more context. Example: +Every rule requires an `implementation` function. It contains the actual logic +of the rule and is executed strictly in the +[analysis phase](concepts.md#evaluation-model). The function has exactly one +input parameter, `ctx`, and it may return the [runfiles](#runfiles) +and [providers](#providers) of the rule. The input parameter `ctx` can be used +to access attribute values, outputs and dependent targets, and files. It also +has some helper functions. See [the library](lib/ctx.html) for more context. +Example: ```python def impl(ctx): @@ -215,15 +221,16 @@ There are three ways to create actions: Actions take a set (which can be empty) of input files and generate a (non-empty) set of output files. -The set of input and output files must be known during the analysis phase. It -might depend on the value of attributes and information from dependencies, but -it cannot depend on the result of the execution. For example, if your action -runs the unzip command, you must specify which files you expect to be inflated -(before running unzip). +The set of input and output files must be known during the +[analysis phase](concepts.md#evaluation-model). It might depend on the value +of attributes and information from dependencies, but it cannot depend on the +result of the execution. For example, if your action runs the unzip command, you +must specify which files you expect to be inflated (before running unzip). Actions are comparable to pure functions: They should depend only on the provided inputs, and avoid accessing computer information, username, clock, -network, or I/O devices (except for reading inputs and writing outputs). +network, or I/O devices (except for reading inputs and writing outputs). This is +important because the output will be cached and reused. **If an action generates a file that is not listed in its outputs**: This is fine, but the file will be ignored and cannot be used by other rules. @@ -473,8 +480,8 @@ if ctx.config.coverage_enabled: 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). During the analysis -phase, the rule must generate the output file `ctx.outputs.executable`. +[rule function](lib/globals.html#rule). The `implementation` function of the +rule must generate the output file `ctx.outputs.executable`. [See example](cookbook.md#outputs-executable) ## Test rules @@ -483,8 +490,9 @@ 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 they -must generate the output file `ctx.outputs.executable`. +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`. Test rules inherit the following attributes: `args`, `flaky`, `local`, `shard_count`, `size`, `timeout`. -- cgit v1.2.3