Misc style improvements - Upgrades / downgrades some section header sizes to clearer positions - Mild reorganization for clearer content flow - Capitalization typo fixes Serves https://github.com/bazelbuild/bazel/issues/10794 Closes #10820. PiperOrigin-RevId: 296229327
diff --git a/site/docs/backward-compatibility.md b/site/docs/backward-compatibility.md index 500f1a0..a3df992 100644 --- a/site/docs/backward-compatibility.md +++ b/site/docs/backward-compatibility.md
@@ -26,9 +26,9 @@ 1. APIs and behavior guarded by an `--experimental_*` flag can change at any time. 1. Users should never run their production builds with `--experimental_*` or `--incompatible_*` flags. -### How to follow this policy +## How to follow this policy -* [For Bazel Users - how to update +* [For Bazel users - how to update Bazel](updating-bazel.html) * [For contributors - best practices for incompatible changes](https://bazel.build/breaking-changes-guide.html) * <a href='https://github.com/bazelbuild/continuous-integration/tree/master/docs/release-playbook.%6D%64'>For release managers - how to update issue labels and release</a>
diff --git a/site/docs/configurable-attributes.md b/site/docs/configurable-attributes.md index 2c74ca8..4ecf439 100644 --- a/site/docs/configurable-attributes.md +++ b/site/docs/configurable-attributes.md
@@ -90,6 +90,7 @@ <td><code>[":generic_lib"]</code></td> </tr> </table> + `select()` serves as a placeholder for a value that will be chosen based on *configuration conditions*. These conditions are labels that refer to [`config_setting`](be/general.html#config_setting) targets. By using `select()` @@ -733,7 +734,7 @@ ## FAQ -## <a name="macros-select"></a>Why doesn't select() work in macros? +### <a name="macros-select"></a>Why doesn't select() work in macros? select() *does* work in rules! See [Rules compatibility](#rules) for details. @@ -844,7 +845,7 @@ DEBUG: /myworkspace/myproject/defs.bzl:15:3: My name is sad_macro_less_sad with custom message: FIRST STRING. ``` -## <a name="boolean-select"></a>Why does select() always return true? +### <a name="boolean-select"></a>Why does select() always return true? Because *macros* (but not rules) by definition [can't evaluate select(s)](#macros-select), any attempt to do so usually produces an error: @@ -888,7 +889,7 @@ [Pythonic](https://docs.python.org/release/2.5.2/lib/truth.html) design standards, all objects aside from a very small number of exceptions automatically return true. -## <a name="inspectable-select"></a>Can I read select() like a dict? +### <a name="inspectable-select"></a>Can I read select() like a dict? Fine. Macros [can't](#macros-select) evaluate select(s) because macros are evaluated before Bazel knows what the command line flags are. @@ -946,7 +947,7 @@ ) ``` -## <a name="bind-select"></a>Why doesn't select() work with bind()? +### <a name="bind-select"></a>Why doesn't select() work with bind()? Because [`bind()`](be/workspace.html#bind) is a WORKSPACE rule, not a BUILD rule.
diff --git a/site/docs/test-encyclopedia.html b/site/docs/test-encyclopedia.html index cde88be..2536fa5 100644 --- a/site/docs/test-encyclopedia.html +++ b/site/docs/test-encyclopedia.html
@@ -41,7 +41,7 @@ specification takes precedence.</p> -<h3>Purpose of Tests</h3> +<h2>Purpose of Tests</h2> <p>The purpose of Bazel tests is to confirm some property of the source files checked into the repository. (In this document, "source files" includes test data, @@ -62,7 +62,7 @@ <p>Currently, such behavior is not enforced. However, test runners reserve the right to add such enforcement in the future.</p> -<h3>Role of the Build System</h3> +<h2>Role of the Build System</h2> <p>Test rules are analogous to binary rules in that each must yield an executable program. For some languages, this is a stub program which combines @@ -79,7 +79,7 @@ image provided by the test runner, rather than hardcoded references to absolute locations in the source or output tree.</p> -<h3>Role of the Test Runner</h3> +<h2>Role of the Test Runner</h2> <p>From the point of view of the test runner, each test is a program which can be invoked with <code>execve()</code>. There may be other ways to execute @@ -193,7 +193,7 @@ <p>When executing a test, the test runner must establish certain initial conditions.</p> -<h3>Initial Conditions</h3> +<h2>Initial Conditions</h2> <p>The test runner must invoke each test with the path to the test executable in <code>argv[0]</code>. This path must be relative and @@ -310,7 +310,7 @@ <p>The initial scheduling policy and priority are unspecified.</p> -<h3>Role of the Host System</h3> +<h2>Role of the Host System</h2> <p>In addition to the aspects of user context under direct control of the test runner, the operating system on which tests execute must satisfy certain @@ -380,7 +380,7 @@ <p>X Windows may or may not be available. Tests that need an X server should start Xvfb.</p> -<h3>Test interaction with the filesystem</h3> +<h2>Test interaction with the filesystem</h2> <p>All file paths specified in test environment variables point to somewhere on the local filesystem, unless otherwise specified.</p> @@ -423,7 +423,7 @@ Bazel sees the file when the test finishes, it will assume that the test exited prematurely and mark it as having failed.</p> -<h3 id="tag-conventions">Tag conventions</h3> +<h2 id="tag-conventions">Tag conventions</h2> <p> Some tags in the test rules have a special @@ -478,7 +478,7 @@ </table> *Note: bazel <code>query</code> does not respect the manual tag. -<h3>Runfiles</h3> +<h2>Runfiles</h2> <p>In the following, assume there is a *_binary() rule labeled <code>//foo/bar:unittest</code>, with a run-time dependency on the rule labeled <code>//deps/server:server</code>.</p>
diff --git a/site/docs/updating-bazel.md b/site/docs/updating-bazel.md index 4e1e637..3c41ef8 100644 --- a/site/docs/updating-bazel.md +++ b/site/docs/updating-bazel.md
@@ -5,33 +5,56 @@ # Updating Bazel -Bazel defined a [backwards compatibility policy](https://docs.bazel.build/versions/master/backward-compatibility.html) -(see [guidance for rolling out incompatible changes](https://www.bazel.build/breaking-changes-guide.html) if you are the author of one). -This page summarized best practices on how to test and migrate your project with upcoming incompatible -changes and how to provide feedback to the incompatible change authors. +The Bazel project has a [backwards compatibility +policy](https://docs.bazel.build/versions/master/backward-compatibility.html) +(see [guidance for rolling out incompatible +changes](https://www.bazel.build/breaking-changes-guide.html) if you are the +author of one). That page summarizes best practices on how to test and migrate +your project with upcoming incompatible changes and how to provide feedback to +the incompatible change authors. +## Managing Bazel versions with Bazelisk + +The Bazel team implemented a Bazel wrapper called +[bazelisk](https://github.com/bazelbuild/bazelisk) that helps you manage Bazel +versions. + +Bazelisk can: +* Auto-update Bazel to the latest version +* Build the project with a Bazel version specified in the .bazelversion + file. Check in that file into your version control to ensure reproducibility + of your builds. +* Help migrate your project for incompatible changes (see above) +* Easily try release candidates ## Recommended migration process -Bazel backwards compatibility policy is designed to avoid _upgrade cliffs_: -any project can be prepared for the next Bazel release without breaking compatibility with the current release. +Bazel backwards compatibility policy is designed to avoid _upgrade cliffs_: any +project can be prepared for the next Bazel release without breaking +compatibility with the current release. We recommend the following process for project migration: -1. Assume that your project already works with a given Bazel release, say 0.26, and you want to prepare - for the next release, say 0.27 +1. Assume that your project already works with a given Bazel release, say 0.26, + and you want to prepare for the next release, say 0.27 2. Find all incompatible changes for which the migration can be started: they are marked with - "migration-\<release\>" label on GitHub, for example "[migration-0.26](https://github.com/bazelbuild/bazel/issues?utf8=%E2%9C%93&q=label%3Amigration-0.26+)". -3. Each of those issues has an associated `--incompatible_*` flag. For each of them, build your project - with that flag enabled, and if the build is unsuccessful, fix the project according to - [migration recipe](https://docs.bazel.build/versions/master/backward-compatibility.html#incompatible-changes-and-migration-recipes) as specified in the corresponding GitHub issue: + "migration-\<release\>" label on GitHub, for example + "[migration-0.26](https://github.com/bazelbuild/bazel/issues?utf8=%E2%9C%93&q=label%3Amigration-0.26+)". +3. Each of those issues has an associated `--incompatible_*` flag. For each of + them, build your project with that flag enabled, and if the build is + unsuccessful, fix the project according to [migration + recipe](https://docs.bazel.build/versions/master/backward-compatibility.html#incompatible-changes-and-migration-recipes) + as specified in the corresponding GitHub issue: * Migration guidance is available in the associated GitHub issue. * Migration is always possible in such a way that the project continues to build with and without the flag. - * For some of the incompatible changes migration tooling is available, for example as part of [buildifier](https://github.com/bazelbuild/buildtools/releases). Be sure to check the GitHub issue for migration instructions. + * For some of the incompatible changes migration tooling is available, for + example as part of + [buildifier](https://github.com/bazelbuild/buildtools/releases). Be sure + to check the GitHub issue for migration instructions. * Please report any migration problems by commenting associated GitHub issue. -4. After all changes are migrated, you can continue to build your project without any flags: - it will be ready for the next Bazel release. +4. After all changes are migrated, you can continue to build your project + without any flags: it will be ready for the next Bazel release. ### Migrating with Bazelisk @@ -39,17 +62,7 @@ [Bazelisk](https://github.com/bazelbuild/bazelisk) can greatly simplify the migration process described above. -* `bazelisk --strict` will build given targets with all incompatible flags for changes with appropriate migration-* labels. -* `bazelisk --migrate` will do even more: it will try every flag and report those for which the build was unsuccessful - - -## Managing Bazel versions with Bazelisk - -Bazel team implemented a Bazel wrapper called [bazelisk](https://github.com/bazelbuild/bazelisk) that helps you -manage Bazel versions. - -Bazelisk can: -* Autoupdate Bazel to the latest version -* Build the project with a Bazel version specified in the .bazelversion file. Check in that file into your version control to ensure reproducibility of your builds. -* Help migrate your project for incompatible changes (see above) -* Easily try release candidates +* `bazelisk --strict` will build given targets with all incompatible flags for + changes with appropriate migration-* labels. +* `bazelisk --migrate` will do even more: it will try every flag and report + those for which the build was unsuccessful