diff options
| -rw-r--r-- | site/docs/skylark/cookbook.md | 22 | ||||
| -rw-r--r-- | site/docs/skylark/rules.md | 10 | ||||
| -rw-r--r-- | src/main/java/com/google/devtools/build/lib/rules/SkylarkActionFactory.java | 8 |
3 files changed, 28 insertions, 12 deletions
diff --git a/site/docs/skylark/cookbook.md b/site/docs/skylark/cookbook.md index 9b5c789a73..84268ae3ea 100644 --- a/site/docs/skylark/cookbook.md +++ b/site/docs/skylark/cookbook.md @@ -200,6 +200,8 @@ should avoid calling it repeatedly within BUILD file. Minimalist example of a rule that does nothing. If you build it, the target will succeed (with no generated file). +[See example on github](https://github.com/bazelbuild/examples/tree/master/rules/empty) + `empty.bzl`: ```python @@ -222,6 +224,8 @@ empty(name = "nothing") Example of a rule that shows how to declare attributes and access them. +[See example on github](https://github.com/bazelbuild/examples/tree/master/rules/attributes) + `printer.bzl`: ```python @@ -272,7 +276,9 @@ the user. The output has the same name as the rule, with a `.size` suffix. While convenient, Shell commands should be used carefully. Generating the command-line can lead to escaping and injection issues. It can also create portability problems. It is often better to declare a binary target in a -BUILD file and execute it. See the example [executing a binary](#execute-bin). +BUILD file and execute it. + +See the example [executing a binary](#execute-bin). `size.bzl`: @@ -557,13 +563,11 @@ value of an attribute (the attribute must be private and have type `label` or `list of labels`). The parameters of this function must correspond to the attributes that are accessed in the function body. -Note: For legacy reasons, the function takes the configuration as an additional -parameter. Please do not rely on the configuration since it will be removed in -the future. - The example below computes the md5 sum of a file. The file can be preprocessed using a filter. The exact dependencies depend on the filter chosen by the user. +[See example on github](https://github.com/bazelbuild/examples/tree/master/rules/computed_dependencies) + `hash.bzl`: ```python @@ -573,7 +577,7 @@ _filters = { "none": None, } -def _get_filter(filter, cfg=None): # requires attribute "filter" +def _get_filter(filter): # requires attribute "filter" # Return the value for the attribute "_filter_bin" # It can be a label or None. return _filters[filter] @@ -760,6 +764,8 @@ sum( This example shows how to create a default executable output. +[See example on github](https://github.com/bazelbuild/examples/tree/master/rules/executable) + `extension.bzl`: ```python @@ -790,6 +796,8 @@ executable_rule(name = "my_rule") This example shows how to create default outputs for a rule. +[See example on github](https://github.com/bazelbuild/examples/tree/master/rules/default_outputs) + `extension.bzl`: ```python @@ -824,6 +832,8 @@ This example shows how to create custom (user defined) outputs for a rule. This rule takes a list of output file name templates from the user and creates each of them containing a "Hello World!" message. +[See example on github](https://github.com/bazelbuild/examples/tree/master/rules/custom_outputs) + `extension.bzl`: ```python diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md index d56789e11d..5b476760fa 100644 --- a/site/docs/skylark/rules.md +++ b/site/docs/skylark/rules.md @@ -173,14 +173,14 @@ A target can declare output files, which must be generated by the target's actions. There are three ways to create output files: * If the rule is marked `executable`, it creates an output file of the same name - as the rule's. [See example](cookbook.md#outputs-executable) + as the rule's. [See example](https://github.com/bazelbuild/examples/blob/master/rules/executable/executable.bzl) * The rule can declare default `outputs`, which are always generated. - [See example](cookbook.md#outputs-default) + [See example](https://github.com/bazelbuild/examples/blob/master/rules/default_outputs/extension.bzl) * The rule can have output or output list type attributes. In that case the output files come from the actual attribute values. - [See example](cookbook.md#outputs-custom) + [See example](https://github.com/bazelbuild/examples/blob/master/rules/custom_outputs/extension.bzl) Each output file must have exactly one generating action. See the [library](lib/ctx.html#outputs) for more context. @@ -579,7 +579,7 @@ 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](cookbook.md#outputs-executable) +[See example](https://github.com/bazelbuild/examples/blob/master/rules/executable/executable.bzl) ## Test rules @@ -591,6 +591,8 @@ 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) + Test rules inherit the following attributes: `args`, `flaky`, `local`, `shard_count`, `size`, `timeout`. The defaults of inherited attributes cannot be changed, but you can use a macro with default arguments: diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkActionFactory.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkActionFactory.java index ea7fd9ee71..4360561628 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkActionFactory.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkActionFactory.java @@ -206,7 +206,9 @@ public class SkylarkActionFactory implements SkylarkValue { "Creates a file write action. When the action is executed, it will write the given content " + "to a file. This is used to generate files using information available in the " + "analysis phase. If the file is large and with a lot of static content, consider " - + "using <a href=\"#expand_template\">expand_template</a>.", + + "using <a href=\"#expand_template\">expand_template</a>. " + + "<a href=\"https://github.com/laurentlb/examples/blob/master/rules/executable/executable.bzl\">" + + "See example of use</a>", parameters = { @Param(name = "output", type = Artifact.class, doc = "the output file.", named = true), @Param( @@ -641,7 +643,9 @@ public class SkylarkActionFactory implements SkylarkValue { + "using the <code>substitutions</code> dictionary. Whenever a key of the " + "dictionary appears in the template, it is replaced with the associated value. " + "There is no special syntax for the keys. You may for example use curly braces " - + "to avoid conflicts (e.g. <code>{KEY}</code>).", + + "to avoid conflicts (e.g. <code>{KEY}</code>). " + + "<a href=\"https://github.com/laurentlb/examples/blob/master/rules/expand_template/hello.bzl\">" + + "See example of use</a>", parameters = { @Param( name = "template", |