diff --git a/site/docs/test-encyclopedia.html b/site/docs/test-encyclopedia.html index 250a3a9a00d5f6..3eda20949a86e9 100644 --- a/site/docs/test-encyclopedia.html +++ b/site/docs/test-encyclopedia.html @@ -30,10 +30,10 @@

Objective

for and expected behavior of Bazel tests. It will also impose requirements on the test runner and the build system. -Our intent is to help test authors avoid relying on unspecified -behavior, and thus give the testing infrastructure more freedom to make -implementation changes. We will also take the opportunity to tighten up some -holes which currently allow many tests to pass despite not being +The test environment specification helps test authors avoid relying on +unspecified behavior, and thus gives the testing infrastructure more freedom +to make implementation changes. The specification tightens up some +holes that currently allow many tests to pass despite not being properly hermetic, deterministic, and reentrant.

This page is intended to be both normative and authoritative. If diff --git a/site/docs/toolchains.md b/site/docs/toolchains.md index 740c4f7a7a2116..10038dd92ff8ce 100644 --- a/site/docs/toolchains.md +++ b/site/docs/toolchains.md @@ -19,7 +19,7 @@ platform constraints. ## Motivation Let's first look at the problem toolchains are designed to solve. Suppose you -were writing rules to support the "bar" programming language. Your `bar_binary` +are writing rules to support the "bar" programming language. Your `bar_binary` rule would compile `*.bar` files using the `barc` compiler, a tool that itself is built as another target in your workspace. Since users who write `bar_binary` targets shouldn't have to specify a dependency on the compiler, you make it an @@ -47,7 +47,7 @@ implementation function just like any other attribute: BarcInfo = provider( doc = "Information about how to invoke the barc compiler.", # In the real world, compiler_path and system_lib might hold File objects, - # but for simplicity we'll make them strings instead. arch_flags is a list + # but for simplicity they are strings for this example. arch_flags is a list # of strings. fields = ["compiler_path", "system_lib", "arch_flags"], ) @@ -88,7 +88,7 @@ bar_binary( ) ``` -We can improve on this solution by using `select` to choose the `compiler` +You can improve on this solution by using `select` to choose the `compiler` [based on the platform](configurable-attributes.html): ```python @@ -134,7 +134,8 @@ need know the complete set of available platforms and toolchains. Under the toolchain framework, instead of having rules depend directly on tools, they instead depend on *toolchain types*. A toolchain type is a simple target that represents a class of tools that serve the same role for different -platforms. For instance, we can declare a type that represents the bar compiler: +platforms. For instance, you can declare a type that represents the bar +compiler: ```python # By convention, toolchain_type targets are named "toolchain_type" and @@ -179,7 +180,7 @@ def _bar_binary_impl(ctx): [`ToolchainInfo` provider](skylark/lib/platform_common.html#ToolchainInfo) of whatever target Bazel resolved the toolchain dependency to. The fields of the `ToolchainInfo` object are set by the underlying tool's rule; in the next -section we'll define this rule such that there is a `barcinfo` field that wraps +section, this rule is defined such that there is a `barcinfo` field that wraps a `BarcInfo` object. Bazel's procedure for resolving toolchains to targets is described @@ -208,7 +209,7 @@ def _bar_aspect_impl(target, ctx): ## Defining toolchains -To define some toolchains for a given toolchain type, we need three things: +To define some toolchains for a given toolchain type, you need three things: 1. A language-specific rule representing the kind of tool or tool suite. By convention this rule's name is suffixed with "\_toolchain". @@ -253,11 +254,11 @@ The rule must return a `ToolchainInfo` provider, which becomes the object that the consuming rule retrieves using `ctx.toolchains` and the label of the toolchain type. `ToolchainInfo`, like `struct`, can hold arbitrary field-value pairs. The specification of exactly what fields are added to the `ToolchainInfo` -should be clearly documented at the toolchain type. Here we have returned the -values wrapped in a `BarcInfo` object in order to reuse the schema defined -above; this style may be useful for validation and code reuse. +should be clearly documented at the toolchain type. In this example, the values +return wrapped in a `BarcInfo` object to reuse the schema defined above; this +style may be useful for validation and code reuse. -Now we can define targets for specific `barc` compilers. +Now you can define targets for specific `barc` compilers. ```python bar_toolchain( @@ -281,7 +282,7 @@ bar_toolchain( ) ``` -Finally, we create `toolchain` definitions for the two `bar_toolchain` targets. +Finally, you create `toolchain` definitions for the two `bar_toolchain` targets. These definitions link the language-specific targets to the toolchain type and provide the constraint information that tells Bazel when the toolchain is appropriate for a given platform. @@ -326,7 +327,7 @@ for a real-world example. ## Registering and building with toolchains -At this point all the building blocks are assembled, and we just need to make +At this point all the building blocks are assembled, and you just need to make the toolchains available to Bazel's resolution procedure. This is done by registering the toolchain, either in a `WORKSPACE` file using `register_toolchains()`, or by passing the toolchains' labels on the command @@ -336,7 +337,7 @@ line using the `--extra_toolchains` flag. register_toolchains( "//bar_tools:barc_linux_toolchain", "//bar_tools:barc_windows_toolchain", - # Target patterns are also permitted, so we could have also written: + # Target patterns are also permitted, so you could have also written: # "//bar_tools:all", ) ``` @@ -413,7 +414,7 @@ The resolution steps are as follows. the list of available execution platforms is filtered to remove any that do not match the execution constraints. -1. For each available execution platform, we associate each toolchain type with +1. For each available execution platform, you associate each toolchain type with the first available toolchain, if any, that is compatible with this execution platform and the target platform. diff --git a/site/docs/updating-bazel.md b/site/docs/updating-bazel.md index b3d99559218f9e..8d8bf775e3dcca 100644 --- a/site/docs/updating-bazel.md +++ b/site/docs/updating-bazel.md @@ -36,7 +36,7 @@ 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: +Follow this 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 diff --git a/site/docs/user-manual.html b/site/docs/user-manual.html index 21c69a7e01261e..df47225e046f68 100644 --- a/site/docs/user-manual.html +++ b/site/docs/user-manual.html @@ -78,8 +78,8 @@

--package_path

- If you use a non-default package path, we recommend that you specify - it in your Bazel configuration file for + If you use a non-default package path, specify it in your + Bazel configuration file for convenience.

@@ -1161,8 +1161,8 @@

--save_temps

generated for the set of targets specified on the command line.

- Note that our implementation of --save_temps does not use the compiler's - -save-temps flag. Instead, we do two passes, one with -S + Note that the implementation of --save_temps does not use the compiler's + -save-temps flag. Instead, there are two passes, one with -S and one with -E. A consequence of this is that if your build fails, Bazel may not yet have produced the ".i" or ".ii" and ".s" files. If you're trying to use --save_temps to debug a failed compilation, @@ -2150,20 +2150,17 @@

The clean command

The clean command is provided primarily as a means of reclaiming disk space for workspaces that are no longer needed. - However, we recognize that Bazel's incremental rebuilds might not be - perfect; clean may be used to recover a consistent + Bazel's incremental rebuilds may not be + perfect so clean can be used to recover a consistent state when problems arise.

- Bazel's design is such that these problems are fixable; we consider - such bugs a high priority, and will do our best fix them. If you - ever find an incorrect incremental build, please file a bug report. - We encourage developers to get out of the habit of - using clean and into that of reporting bugs in the - tools. + Bazel's design is such that these problems are fixable and + these bugs are a high priority to be fixed. If you + ever find an incorrect incremental build, file a bug report, and report bugs in the tools + rather than using clean.

-

Running executables

The bazel run command is similar to bazel build, except @@ -2823,9 +2820,8 @@

--output_user_root=dir--output_base. The directory must either not exist or be owned by the calling user. In the past, this was allowed to point to a directory shared among various users - but it's not allowed any longer. (We can reconsider allowing this once - #11100 - is addressed.) + but it's not allowed any longer. This may be allowed once the following is addressed: + #11100.

If the --output_base option is specified, it overrides @@ -2939,7 +2935,7 @@

--batch

WARNING: --batch is sufficiently slower than standard client/server mode. Additionally it might not support all of the features and optimizations which are made possible by a persistent Bazel server. If you're using --batch - for the purpose of build isolation, we recommend using the command option + for the purpose of build isolation, you should use the command option --nokeep_state_after_build, which guarantees that no incremental in-memory state is kept between builds. In order to restart the Bazel server and JVM after a build, please explicitly do so using the "shutdown" command. diff --git a/site/docs/windows.md b/site/docs/windows.md index f057a4d2c26bae..f76a1debf329cc 100644 --- a/site/docs/windows.md +++ b/site/docs/windows.md @@ -10,8 +10,8 @@ instructions, see [Install Bazel on Windows](install-windows.html). ## Known issues -We mark Windows-related Bazel issues on GitHub with the "team-Windows" -label. [You can see the open issues here.](https://github.com/bazelbuild/bazel/issues?q=is%3Aopen+is%3Aissue+label%3Ateam-Windows) +Windows-related Bazel issues are marked with the "team-Windows" +label on GitHub. [You can see the open issues here.](https://github.com/bazelbuild/bazel/issues?q=is%3Aopen+is%3Aissue+label%3Ateam-Windows) ## Best practices @@ -52,10 +52,10 @@ build --enable_runfiles ### Running Bazel: MSYS2 shell vs. command prompt vs. PowerShell -We recommend running Bazel from the command prompt (`cmd.exe`) or from +**Recommendation:** Run Bazel from the command prompt (`cmd.exe`) or from PowerShell. -As of 2020-01-15, we **do not recommend** running Bazel from `bash` -- either +As of 2020-01-15, **do not** run Bazel from `bash` -- either from MSYS2 shell, or Git Bash, or Cygwin, or any other Bash variant. While Bazel may work for most use cases, some things are broken, like [interrupting the build with Ctrl+C from MSYS2](https://github.com/bazelbuild/bazel/issues/10573)). @@ -115,9 +115,9 @@ rules that use `ctx.actions.run_shell()` and `ctx.resolve_command()`. This applies not only to rules in your project, but to rules in any of the external repositories your project depends on (even transitively). -We may explore the option to use Windows Subsystem for Linux (WSL) to build -these rules, but as of 2020-01-15 it is not a priority for the Bazel-on-Windows -subteam. +In the future, there may be an option to use Windows Subsystem for +Linux (WSL) to build these rules, but currently it is not a priority for +the Bazel-on-Windows subteam. ### Setting environment variables @@ -215,8 +215,9 @@ example](https://github.com/bazelbuild/bazel/tree/master/examples/windows/dll). From 0.29.0, Bazel supports building with LLVM's MSVC-compatible compiler driver (`clang-cl.exe`). **Requirement**: To build with Clang, you have to install **both** -[LLVM](http://releases.llvm.org/download.html) and Visual C++ Build tools, because although we use -`clang-cl.exe` as compiler, we still need to link to Visual C++ libraries. +[LLVM](http://releases.llvm.org/download.html) and Visual C++ Build tools, +because although you use `clang-cl.exe` as compiler, you still need to link to +Visual C++ libraries. Bazel can automatically detect LLVM installation on your system, or you can explicitly tell Bazel where LLVM is installed by `BAZEL_LLVM`. diff --git a/site/docs/workspace-log.md b/site/docs/workspace-log.md index bd20173683ef93..17f0362c1beea0 100644 --- a/site/docs/workspace-log.md +++ b/site/docs/workspace-log.md @@ -5,7 +5,7 @@ title: Finding non-hermetic behavior in WORKSPACE rules # Finding Non-Hermetic Behavior in WORKSPACE Rules -In the following, we say that a host machine is the machine where Bazel runs. +In the following, a host machine is the machine where Bazel runs. When using remote execution, the actual build and/or test steps are not happening on the host machine, but are instead sent off to the remote execution