Docs: Update Starlark files PiperOrigin-RevId: 369868764
diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md index 0f7cf27..f52654b 100644 --- a/site/docs/skylark/rules.md +++ b/site/docs/skylark/rules.md
@@ -25,12 +25,11 @@ the actions. Before creating or modifying any rule, ensure you are familiar with Bazel's -[build phases](concepts.md). It will be important to understand the three phases -of a build (loading, analysis and execution). It will also be useful to learn -about [macros](macros.md) to understand the difference between rules and macros. -To get started, we recommend that you first follow the -[Rules Tutorial](rules-tutorial.md). The current page can be used as a -reference. +[build phases](concepts.md). It is important to understand the three +phases of a build (loading, analysis, and execution). It is also useful to +learn about [macros](macros.md) to understand the difference between rules and +macros. To get started, first review the [Rules Tutorial](rules-tutorial.md). +Then, use this page as a reference. A few rules are built into Bazel itself. These *native rules*, such as `cc_library` and `java_binary`, provide some core support for certain languages. @@ -201,16 +200,16 @@ ) ``` -In this example, every target of type `example_library` will have an implicit +In this example, every target of type `example_library` has an implicit dependency on the compiler `//tools:example_compiler`. This allows `example_library`'s implementation function to generate actions that invoke the compiler, even though the user did not pass its label as an input. Since -`_compiler` is a private attribute, we know for sure that `ctx.attr._compiler` +`_compiler` is a private attribute, it follows that `ctx.attr._compiler` will always point to `//tools:example_compiler` in all targets of this rule -type. Alternatively, we could have named the attribute `compiler` without the -underscore and kept the default value. That would let users substitute a +type. Alternatively, you can name the attribute `compiler` without the +underscore and keep the default value. This allows users to substitute a different compiler if necessary, but it requires no awareness of the compiler's -label otherwise. +label. Implicit dependencies are generally used for tools that reside in the same repository as the rule implementation. If the tool comes from the @@ -819,7 +818,7 @@ ```python def _impl(ctx): - # Using ctx.fragments.cpp would lead to an error since it was not declared. + # Using ctx.fragments.cpp leads to an error since it was not declared. x = ctx.fragments.java ... @@ -928,7 +927,7 @@ [`ctx.runfiles`](lib/ctx.html#runfiles) and the [`runfiles`](lib/runfiles.html) type have a complex set of features, many of which are kept for legacy reasons. -We make the following recommendations to reduce complexity: +The following recommendations help reduce complexity: * **Avoid** use of the `collect_data` and `collect_default` modes of [`ctx.runfiles`](lib/ctx.html#runfiles). These modes implicitly collect
diff --git a/site/docs/skylark/testing.md b/site/docs/skylark/testing.md index abe3050..87d4376 100644 --- a/site/docs/skylark/testing.md +++ b/site/docs/skylark/testing.md
@@ -157,9 +157,11 @@ * The test suite function, which calls the loading-time functions for each test, and declares a `test_suite` target bundling all tests together. -We recommend the following naming convention. Let `foo` stand for the part of -the test name that describes what the test is checking (`provider_contents` in -the above example). For example, a JUnit test method would be named `testFoo`. +For consistency, follow the recommended naming convention: Let `foo` stand for +the part of the test name that describes what the test is checking +(`provider_contents` in the above example). For example, a JUnit test method +would be named `testFoo`. + Then: * the macro which generates the test and target under test should should be @@ -381,7 +383,7 @@ myrule_validation_test = rule( implementation = _myrule_validation_test_impl, attrs = {"target": attr.label(allow_single_file=True), - # We need an implicit dependency in order to access the template. + # You need an implicit dependency in order to access the template. # A target could potentially override this attribute to modify # the test logic. "_script": attr.label(allow_single_file=True, @@ -408,17 +410,17 @@ srcs = [":myrule_validator.sh.template"], ) -# Needed for each target whose artifacts are to be checked. Notice that we no +# Needed for each target whose artifacts are to be checked. Notice that you no # longer have to specify the output file name in a data attribute, or its # $(location) expansion in an args attribute, or the label for the script -# (unless we want to override it). +# (unless you want to override it). myrule_validation_test( name = "validate_mytarget", target = ":mytarget", ) ``` -Alternatively, instead of using a template expansion action, we could have +Alternatively, instead of using a template expansion action, you could have inlined the template into the .bzl file as a string and expanded it during the analysis phase using the `str.format` method or `%`-formatting.
diff --git a/site/docs/skylark/tutorial-creating-a-macro.md b/site/docs/skylark/tutorial-creating-a-macro.md index e3ff353..8da206f 100644 --- a/site/docs/skylark/tutorial-creating-a-macro.md +++ b/site/docs/skylark/tutorial-creating-a-macro.md
@@ -6,11 +6,15 @@ # Creating a Macro -Let's suppose you need to run a tool as part of your build. For example, you +Imagine that you need to run a tool as part of your build. For example, you may want to generate or preprocess a source file, or compress a binary. In this -tutorial, we are going to resize an image. +tutorial, you are going to create a macro that resizes an image. -The easiest way is to use a `genrule`: +Macros are suitable for simple tasks. If you want to do anything more +complicated, for example add support for a new programming language, consider +creating a [rule](rules.md). Rules give you more control and flexibility. + +The easiest way to create a macro that resizes an image is to use a `genrule`: ``` python genrule( @@ -28,8 +32,7 @@ ``` If you need to resize more images, you may want to reuse the code. To do that, -we are going to define a function in a separate `.bzl` file. Let's call the file -`miniature.bzl`: +define a function in a separate `.bzl` file, and call the file `miniature.bzl`: ``` python def miniature(name, src, size="100x100", **kwargs): @@ -50,17 +53,17 @@ * By convention, macros have a `name` argument, just like rules. -* We document the behavior of a macro by using a +* To document the behavior of a macro, use [docstring](https://www.python.org/dev/peps/pep-0257/) like in Python. * To call a `genrule`, or any other native rule, use `native.`. -* `**kwargs` is used to forward the extra arguments to the underlying `genrule` +* Use `**kwargs` to forward the extra arguments to the underlying `genrule` (it works just like in [Python](https://docs.python.org/3/tutorial/controlflow.html#keyword-arguments)). This is useful, so that a user can use standard attributes like `visibility`, or `tags`. -Now, you can use the macro from the `BUILD` file: +Now, use the macro from the `BUILD` file: ``` python load("//path/to:miniature.bzl", "miniature") @@ -76,7 +79,3 @@ data = [":logo_miniature"], ) ``` - -Macros are suitable for simple tasks. If you want to do anything more -complicated, for example add support for a new programming language, consider -creating a [rule](rules.md). Rules will give you more control and flexibility.
diff --git a/site/docs/skylark/tutorial-custom-verbs.md b/site/docs/skylark/tutorial-custom-verbs.md index e1cfd10..0cc4874 100644 --- a/site/docs/skylark/tutorial-custom-verbs.md +++ b/site/docs/skylark/tutorial-custom-verbs.md
@@ -19,13 +19,14 @@ may run in a sandbox, with limited network access, and aren't guaranteed to be re-run with every `bazel build`. -Instead, we rely on `bazel run`: the workhorse for tasks we *want* to have side -effects. Bazel users are accustomed to rules that create executables, and rule -authors can follow a common set of patterns to extend this to "custom verbs". +Instead, rely on `bazel run`: the workhorse for tasks that you *want* to have +side effects. Bazel users are accustomed to rules that create executables, and +rule authors can follow a common set of patterns to extend this to +"custom verbs". ### In the wild: `rules_k8s` -For an example, consider [`rules_k8s`](https://github.com/bazelbuild/rules_k8s), -the Kubernetes rules for Bazel. Suppose we have the following target: +For example, consider [`rules_k8s`](https://github.com/bazelbuild/rules_k8s), +the Kubernetes rules for Bazel. Suppose you have the following target: ```python # BUILD file in //application/k8s @@ -52,7 +53,7 @@ produces two targets. The first is a standard `nodejs_test` target which compares some generated output against a "golden" file (that is, a file containing the expected output). This can be built and run with a normal `bazel -test` invocation. In `angular-cli`, we can run [one such +test` invocation. In `angular-cli`, you can run [one such target](https://github.com/angular/angular-cli/blob/e1269cb520871ee29b1a4eec6e6c0e4a94f0b5fc/etc/api/BUILD) with `bazel test //etc/api:angular_devkit_core_api`. @@ -61,8 +62,9 @@ a `nodejs_binary` target that updates the golden file, instead of comparing against it. Effectively, the same test script can be written to run in "verify" or "accept" mode, based on how it's invoked. This follows the same pattern -we've learned already! There is no native `bazel test-accept` command, but the -same effect can be achieved with `bazel run //etc/api:angular_devkit_core_api.accept`. +you've learned already: there is no native `bazel test-accept` command, but the +same effect can be achieved with +`bazel run //etc/api:angular_devkit_core_api.accept`. This pattern can be quite powerful, and turns out to be quite common once you learn to recognize it. @@ -77,7 +79,7 @@ effects based on the output of the primary target, like publishing the resulting binary or updating the expected test output. -To illustrate this, we'll wrap an imaginary rule that generates a website with +To illustrate this, wrap an imaginary rule that generates a website with [Sphinx](https://www.sphinx-doc.org) with a macro to create an additional target that allows the user to publish it when ready. Consider the following existing rule for generating a website with Sphinx: @@ -106,7 +108,7 @@ ) ``` -Finally, we define the following macro to create targets for both of the above +Finally, define the following macro to create targets for both of the above rules together: ```python @@ -118,7 +120,8 @@ _sphinx_publisher(name = "%s.publish" % name, site = name, **kwargs) ``` -In our `BUILD` files, we use the macro as though it just creates the primary target: +In the `BUILD` files, use the macro as though it just creates the primary +target: ```python sphinx_site( @@ -131,10 +134,9 @@ standard, single Bazel rule. When built, the rule generates some configuration and runs Sphinx to produce an HTML site, ready for manual inspection. However, an additional "docs.publish" target is also created, which builds a script for -publishing the site. Once we check the output of the primary target, we can use -`bazel run :docs.publish` to publish it for public consumption, just like an -imaginary `bazel publish` command. - +publishing the site. Once you check the output of the primary target, you can +use `bazel run :docs.publish` to publish it for public consumption, just like +an imaginary `bazel publish` command. It's not immediately obvious what the implementation of the `_sphinx_publisher` rule might look like. Often, actions like this write a _launcher_ shell script. @@ -146,7 +148,6 @@ HTML, and this small script is all that's necessary to combine the two together. - In `rules_k8s`, this is indeed what `.apply` does: [`expand_template`](https://github.com/bazelbuild/rules_k8s/blob/f10e7025df7651f47a76abf1db5ade1ffeb0c6ac/k8s/object.bzl#L213-L241) writes a very simple Bash script, based on
diff --git a/site/docs/skylark/tutorial-sharing-variables.md b/site/docs/skylark/tutorial-sharing-variables.md index ab58da9..1570abc 100644 --- a/site/docs/skylark/tutorial-sharing-variables.md +++ b/site/docs/skylark/tutorial-sharing-variables.md
@@ -8,7 +8,7 @@ `BUILD` files are intended to be simple and declarative. They will typically consist of a series of a target declarations. As your code base and your `BUILD` -files are getting larger, you will probably notice some duplication, e.g. +files get larger, you will probably notice some duplication, such as: ``` python cc_library( @@ -32,9 +32,8 @@ Code refactoring and code reuse might prevent this kind of automated modification. -With that in mind, it is possible to share values, if you still believe it would -be useful (e.g. values must be kept in sync). We can update the previous example -and introduce a variable: +If it is useful to share values (for example, if values must be kept in sync), +you can introduce a variable: ``` python COPTS = ["-DVERSION=5"] @@ -53,8 +52,8 @@ ) ``` -The value `COPTS` is now used by multiple declarations. By convention, we use -uppercase letters to name global constants. +Multiple declarations now use the value `COPTS`. By convention, use uppercase +letters to name global constants. ## Sharing variables across multiple BUILD files
diff --git a/site/docs/skylark/windows_tips.md b/site/docs/skylark/windows_tips.md index 1f960ce..ea225cf 100644 --- a/site/docs/skylark/windows_tips.md +++ b/site/docs/skylark/windows_tips.md
@@ -41,8 +41,8 @@ Absolute paths on Windows start with a drive letter, e.g. `C:\foo\bar.txt`. There's no single filesystem root. - Be aware of this if your rule checks if a path is absolute. (Absolute paths should be avoided - though, they are often non-portable.) + Be aware of this if your rule checks if a path is absolute. Absolute paths + should be avoided since they are often non-portable. Solutions: @@ -84,8 +84,8 @@ ``` <sup>[1]</sup>: Strictly speaking - [Junctions are not Symbolic Links](https://superuser.com/a/343079), but for sake of build actions - we may regard Junctions as Directory Symlinks. + [Junctions are not Symbolic Links](https://superuser.com/a/343079), but for + the sake of build actions you may regard Junctions as Directory Symlinks. - **Replace `/` with `\` in paths in actions / envvars.**