diff --git a/concepts/build-files.mdx b/concepts/build-files.mdx new file mode 100644 index 0000000..03aa65c --- /dev/null +++ b/concepts/build-files.mdx @@ -0,0 +1,149 @@ +--- +title: 'BUILD files' +--- + + + +The previous sections described packages, targets and labels, and the +build dependency graph abstractly. This section describes the concrete syntax +used to define a package. + +By definition, every package contains a `BUILD` file, which is a short +program. + +Note: The `BUILD` file can be named either `BUILD` or `BUILD.bazel`. If both +files exist, `BUILD.bazel` takes precedence over `BUILD`. +For simplicity's sake, the documentation refers to these files simply as `BUILD` +files. + +`BUILD` files are evaluated using an imperative language, +[Starlark](https://github.com/bazelbuild/starlark/). + +They are interpreted as a sequential list of statements. + +In general, order does matter: variables must be defined before they are +used, for example. However, most `BUILD` files consist only of declarations of +build rules, and the relative order of these statements is immaterial; all +that matters is _which_ rules were declared, and with what values, by the +time package evaluation completes. + +When a build rule function, such as `cc_library`, is executed, it creates a +new target in the graph. This target can later be referred using a label. + +In simple `BUILD` files, rule declarations can be re-ordered freely without +changing the behavior. + +To encourage a clean separation between code and data, `BUILD` files cannot +contain function definitions, `for` statements or `if` statements (but list +comprehensions and `if` expressions are allowed). Functions can be declared in +`.bzl` files instead. Additionally, `*args` and `**kwargs` arguments are not +allowed in `BUILD` files; instead list all the arguments explicitly. + +Crucially, programs in Starlark can't perform arbitrary I/O. This invariant +makes the interpretation of `BUILD` files hermetic — dependent only on a known +set of inputs, which is essential for ensuring that builds are reproducible. +For more details, see [Hermeticity](/basics/hermeticity). + +Because `BUILD` files need to be updated whenever the dependencies of the +underlying code change, they are typically maintained by multiple people on a +team. `BUILD` file authors should comment liberally to document the role +of each build target, whether or not it is intended for public use, and to +document the role of the package itself. + +## Loading an extension + +Bazel extensions are files ending in `.bzl`. Use the `load` statement to import +a symbol from an extension. + +``` +load("//foo/bar:file.bzl", "some_library") +``` + +This code loads the file `foo/bar/file.bzl` and adds the `some_library` symbol +to the environment. This can be used to load new rules, functions, or constants +(for example, a string or a list). Multiple symbols can be imported by using +additional arguments to the call to `load`. Arguments must be string literals +(no variable) and `load` statements must appear at top-level — they cannot be +in a function body. + +The first argument of `load` is a [label](/concepts/labels) identifying a +`.bzl` file. If it's a relative label, it is resolved with respect to the +package (not directory) containing the current `bzl` file. Relative labels in +`load` statements should use a leading `:`. + +`load` also supports aliases, therefore, you can assign different names to the +imported symbols. + +``` +load("//foo/bar:file.bzl", library_alias = "some_library") +``` + +You can define multiple aliases within one `load` statement. Moreover, the +argument list can contain both aliases and regular symbol names. The following +example is perfectly legal (please note when to use quotation marks). + +``` +load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule") +``` + +In a `.bzl` file, symbols starting with `_` are not exported and cannot be +loaded from another file. + +You can use [load visibility](/concepts/visibility#load-visibility) to restrict +who may load a `.bzl` file. + +## Types of build rules + +The majority of build rules come in families, grouped together by +language. For example, `cc_binary`, `cc_library` +and `cc_test` are the build rules for C++ binaries, +libraries, and tests, respectively. Other languages use the same +naming scheme, with a different prefix, such as `java_*` for +Java. Some of these functions are documented in the +[Build Encyclopedia](/reference/be/overview), but it is possible +for anyone to create new rules. + +* `*_binary` rules build executable programs in a given language. After a + build, the executable will reside in the build tool's binary + output tree at the corresponding name for the rule's label, + so `//my:program` would appear at (for example) `$(BINDIR)/my/program`. + + In some languages, such rules also create a runfiles directory + containing all the files mentioned in a `data` + attribute belonging to the rule, or any rule in its transitive + closure of dependencies; this set of files is gathered together in + one place for ease of deployment to production. + +* `*_test` rules are a specialization of a `*_binary` rule, used for automated + testing. Tests are simply programs that return zero on success. + + Like binaries, tests also have runfiles trees, and the files + beneath it are the only files that a test may legitimately open + at runtime. For example, a program `cc_test(name='x', + data=['//foo:bar'])` may open and read `$TEST_SRCDIR/workspace/foo/bar` during execution. + (Each programming language has its own utility function for + accessing the value of `$TEST_SRCDIR`, but they are all + equivalent to using the environment variable directly.) + Failure to observe the rule will cause the test to fail when it is + executed on a remote testing host. + +* `*_library` rules specify separately-compiled modules in the given + programming language. Libraries can depend on other libraries, + and binaries and tests can depend on libraries, with the expected + separate-compilation behavior. + + + + Learn about labels and target references + + + Understand build dependencies + + + +## File encoding + +`BUILD` and `.bzl` files should be encoded in UTF-8, of which ASCII is a valid +subset. Arbitrary byte sequences are currently allowed, but may stop being +supported in the future. + diff --git a/concepts/dependencies.mdx b/concepts/dependencies.mdx new file mode 100644 index 0000000..2e2699c --- /dev/null +++ b/concepts/dependencies.mdx @@ -0,0 +1,231 @@ +--- +title: 'Dependencies' +--- + + + +A target `A` _depends upon_ a target `B` if `B` is needed by `A` at build or +execution time. The _depends upon_ relation induces a +[Directed Acyclic Graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) +(DAG) over targets, and it is called a _dependency graph_. + +A target's _direct_ dependencies are those other targets reachable by a path +of length 1 in the dependency graph. A target's _transitive_ dependencies are +those targets upon which it depends via a path of any length through the graph. + +In fact, in the context of builds, there are two dependency graphs, the graph +of _actual dependencies_ and the graph of _declared dependencies_. Most of the +time, the two graphs are so similar that this distinction need not be made, but +it is useful for the discussion below. + +## Actual and declared dependencies + +A target `X` is _actually dependent_ on target `Y` if `Y` must be present, +built, and up-to-date in order for `X` to be built correctly. _Built_ could +mean generated, processed, compiled, linked, archived, compressed, executed, or +any of the other kinds of tasks that routinely occur during a build. + +A target `X` has a _declared dependency_ on target `Y` if there is a dependency +edge from `X` to `Y` in the package of `X`. + +For correct builds, the graph of actual dependencies _A_ must be a subgraph of +the graph of declared dependencies _D_. That is, every pair of +directly-connected nodes `x --> y` in _A_ must also be directly connected in +_D_. It can be said that _D_ is an _overapproximation_ of _A_. + +Important: _D_ should not be too much of an overapproximation of _A_ because +redundant declared dependencies can make builds slower and binaries larger. + +`BUILD` file writers must explicitly declare all of the actual direct +dependencies for every rule to the build system, and no more. + +Failure to observe this principle causes undefined behavior: the build may fail, +but worse, the build may depend on some prior operations, or upon transitive +declared dependencies the target happens to have. Bazel checks for missing +dependencies and report errors, but it's not possible for this checking to be +complete in all cases. + +You need not (and should not) attempt to list everything indirectly imported, +even if it is _needed_ by `A` at execution time. + +During a build of target `X`, the build tool inspects the entire transitive +closure of dependencies of `X` to ensure that any changes in those targets are +reflected in the final result, rebuilding intermediates as needed. + +The transitive nature of dependencies leads to a common mistake. Sometimes, +code in one file may use code provided by an _indirect_ dependency — a +transitive but not direct edge in the declared dependency graph. Indirect +dependencies don't appear in the `BUILD` file. Because the rule doesn't +directly depend on the provider, there is no way to track changes, as shown in +the following example timeline: + +### 1. Declared dependencies match actual dependencies + +At first, everything works. The code in package `a` uses code in package `b`. +The code in package `b` uses code in package `c`, and thus `a` transitively +depends on `c`. + + +### Comparing a/BUILD and **b**/BUILD + +![Declared dependency graph with arrows connecting a, b, and c](/docs/images/a_b_c.svg) + +![Actual dependency graph that matches the declared dependency + graph with arrows connecting a, b, and c](/docs/images/a_b_c.svg) + + +The declared dependencies overapproximate the actual dependencies. All is well. + +### 2. Adding an undeclared dependency + +A latent hazard is introduced when someone adds code to `a` that creates a +direct _actual_ dependency on `c`, but forgets to declare it in the build file +`a/BUILD`. + +![Declared dependency graph with arrows connecting a, b, and c](/docs/images/a_b_c.svg) + +![Actual dependency graph with arrows connecting a, b, and c. An + arrow now connects A to C as well. This does not match the + declared dependency graph](/docs/images/a_b_c_ac.svg) + + +The declared dependencies no longer overapproximate the actual dependencies. +This may build ok, because the transitive closures of the two graphs are equal, +but masks a problem: `a` has an actual but undeclared dependency on `c`. + +### 3. Divergence between declared and actual dependency graphs + +The hazard is revealed when someone refactors `b` so that it no longer depends on +`c`, inadvertently breaking `a` through no +fault of their own. + +![Declared dependency graph with arrows connecting a and b. + b no longer connects to c, which breaks a's connection to c](/docs/images/ab_c.svg) + +![Actual dependency graph that shows a connecting to b and c, + but b no longer connects to c](/docs/images/a_b_a_c.svg) + + +The declared dependency graph is now an underapproximation of the actual +dependencies, even when transitively closed; the build is likely to fail. + +The problem could have been averted by ensuring that the actual dependency from +`a` to `c` introduced in Step 2 was properly declared in the `BUILD` file. + +## Types of dependencies + +Most build rules have three attributes for specifying different kinds of +generic dependencies: `srcs`, `deps` and `data`. These are explained below. For +more details, see +[Attributes common to all rules](/reference/be/common-definitions). + +Many rules also have additional attributes for rule-specific kinds of +dependencies, for example, `compiler` or `resources`. These are detailed in the +[Build Encyclopedia](/reference/be/). + +### `srcs` dependencies + +Files consumed directly by the rule or rules that output source files. + +### `deps` dependencies + +Rule pointing to separately-compiled modules providing header files, +symbols, libraries, data, etc. + +### `data` dependencies + +A build target might need some data files to run correctly. These data files +aren't source code: they don't affect how the target is built. For example, a +unit test might compare a function's output to the contents of a file. When you +build the unit test you don't need the file, but you do need it when you run +the test. The same applies to tools that are launched during execution. + +The build system runs tests in an isolated directory where only files listed as +`data` are available. Thus, if a binary/library/test needs some files to run, +specify them (or a build rule containing them) in `data`. For example: + +``` +# I need a config file from a directory named env: +java_binary( + name = "setenv", + ... + data = [":env/default_env.txt"], +) + +# I need test data from another directory +sh_test( + name = "regtest", + srcs = ["regtest.sh"], + data = [ + "//data:file1.txt", + "//data:file2.txt", + ... + ], +) +``` + +These files are available using the relative path `path/to/data/file`. In tests, +you can refer to these files by joining the paths of the test's source +directory and the workspace-relative path, for example, +`${TEST_SRCDIR}/workspace/path/to/data/file`. + +## Using labels to reference directories + +As you look over our `BUILD` files, you might notice that some `data` labels +refer to directories. These labels end with `/.` or `/` like these examples, +which you should not use: + +**Not recommended** — `data = ["//data/regression:unittest/."]` + +**Not recommended** — `data = ["testdata/."]` + +**Not recommended** — `data = ["testdata/"]` + +This seems convenient, particularly for tests because it allows a test to +use all the data files in the directory. + +But try not to do this. In order to ensure correct incremental rebuilds (and +re-execution of tests) after a change, the build system must be aware of the +complete set of files that are inputs to the build (or test). When you specify +a directory, the build system performs a rebuild only when the directory itself +changes (due to addition or deletion of files), but won't be able to detect +edits to individual files as those changes don't affect the enclosing directory. +Rather than specifying directories as inputs to the build system, you should +enumerate the set of files contained within them, either explicitly or using the +[`glob()`](/reference/be/functions#glob) function. (Use `**` to force the +`glob()` to be recursive.) + +**Recommended** — `data = glob(["testdata/**"])` + +Unfortunately, there are some scenarios where directory labels must be used. +For example, if the `testdata` directory contains files whose names don't +conform to the [label syntax](/concepts/labels#labels-lexical-specification), +then explicit enumeration of files, or use of the +[`glob()`](/reference/be/functions#glob) function produces an invalid labels +error. You must use directory labels in this case, but beware of the +associated risk of incorrect rebuilds described above. + +If you must use directory labels, keep in mind that you can't refer to the +parent package with a relative `../` path; instead, use an absolute path like +`//data/regression:unittest/.`. + +Note: Directory labels are only valid for data dependencies. If you try to use +a directory as a label in an argument other than `data`, it will fail and you +will get a (probably cryptic) error message. + +Any external rule, such as a test, that needs to use multiple files must +explicitly declare its dependence on all of them. You can use `filegroup()` to +group files together in the `BUILD` file: + +``` +filegroup( + name = 'my_data', + srcs = glob(['my_unittest_data/*']) +) +``` + +You can then reference the label `my_data` as the data dependency in your test. + +**Previous:** [BUILD files](/concepts/build-files) | **Next:** [Visibility](/concepts/visibility) + + diff --git a/concepts/labels.mdx b/concepts/labels.mdx new file mode 100644 index 0000000..1b7cccc --- /dev/null +++ b/concepts/labels.mdx @@ -0,0 +1,256 @@ +--- +title: 'Labels' +--- + + + +A **label** is an identifier for a target. A typical label in its full canonical +form looks like: + +```none +@@myrepo//my/app/main:app_binary +``` + +The first part of the label is the repository name, `@@myrepo`. The double-`@` +syntax signifies that this is a [*canonical* repo +name](/external/overview#canonical-repo-name), which is unique within +the workspace. Labels with canonical repo names unambiguously identify a target +no matter which context they appear in. + +Often the canonical repo name is an arcane string that looks like +`@@rules_java++toolchains+local_jdk`. What is much more commonly seen is +labels with an [*apparent* repo name](/external/overview#apparent-repo-name), +which looks like: + +``` +@myrepo//my/app/main:app_binary +``` + +The only difference is the repo name being prefixed with one `@` instead of two. +This refers to a repo with the apparent name `myrepo`, which could be different +based on the context this label appears in. + +In the typical case that a label refers to the same repository from which +it is used, the repo name part may be omitted. So, inside `@@myrepo` the first +label is usually written as + +``` +//my/app/main:app_binary +``` + +The second part of the label is the un-qualified package name +`my/app/main`, the path to the package +relative to the repository root. Together, the repository name and the +un-qualified package name form the fully-qualified package name +`@@myrepo//my/app/main`. When the label refers to the same +package it is used in, the package name (and optionally, the colon) +may be omitted. So, inside `@@myrepo//my/app/main`, +this label may be written either of the following ways: + +``` +app_binary +:app_binary +``` + +It is a matter of convention that the colon is omitted for files, +but retained for rules, but it is not otherwise significant. + +The part of the label after the colon, `app_binary` is the un-qualified target +name. When it matches the last component of the package path, it, and the +colon, may be omitted. So, these two labels are equivalent: + +``` +//my/app/lib +//my/app/lib:lib +``` + +The name of a file target in a subdirectory of the package is the file's path +relative to the package root (the directory containing the `BUILD` file). So, +this file is in the `my/app/main/testdata` subdirectory of the repository: + +``` +//my/app/main:testdata/input.txt +``` + +Strings like `//my/app` and `@@some_repo//my/app` have two meanings depending on +the context in which they are used: when Bazel expects a label, they mean +`//my/app:app` and `@@some_repo//my/app:app`, respectively. But, when Bazel +expects a package (e.g. in `package_group` specifications), they reference the +package that contains that label. + +A common mistake in `BUILD` files is using `//my/app` to refer to a package, or +to *all* targets in a package--it does not. Remember, it is +equivalent to `//my/app:app`, so it names the `app` target in the `my/app` +package of the current repository. + +However, the use of `//my/app` to refer to a package is encouraged in the +specification of a `package_group` or in `.bzl` files, because it clearly +communicates that the package name is absolute and rooted in the top-level +directory of the workspace. + +Relative labels cannot be used to refer to targets in other packages; the +repository identifier and package name must always be specified in this case. +For example, if the source tree contains both the package `my/app` and the +package `my/app/testdata` (each of these two directories has its own +`BUILD` file), the latter package contains a file named `testdepot.zip`. Here +are two ways (one wrong, one correct) to refer to this file within +`//my/app:BUILD`: + +**Wrong** — `testdata` is a different package, so you can't use a relative path + +``` +testdata/testdepot.zip +``` + +**Correct** — refer to `testdata` with its full path + +``` +//my/app/testdata:testdepot.zip +``` + +Labels starting with `@@//` are references to the main +repository, which will still work even from external repositories. +Therefore `@@//a/b/c` is different from +`//a/b/c` when referenced from an external repository. +The former refers back to the main repository, while the latter +looks for `//a/b/c` in the external repository itself. +This is especially relevant when writing rules in the main +repository that refer to targets in the main repository, and will be +used from external repositories. + +For information about the different ways you can refer to targets, see +[target patterns](/run/build#specifying-build-targets). + +### Lexical specification of a label + +Label syntax discourages use of metacharacters that have special meaning to the +shell. This helps to avoid inadvertent quoting problems, and makes it easier to +construct tools and scripts that manipulate labels, such as the +[Bazel Query Language](/query/language). + +The precise details of allowed target names are below. + +### Target names — `{{ "" }}package-name{{ "" }}:target-name` + +`target-name` is the name of the target within the package. The name of a rule +is the value of the `name` attribute in the rule's declaration in a `BUILD` +file; the name of a file is its pathname relative to the directory containing +the `BUILD` file. + +Target names must be composed entirely of characters drawn from the set `a`–`z`, +`A`–`Z`, `0`–`9`, and the punctuation symbols `!%-@^_"#$&'()*-+,;<=>?[]{|}~/.`. + +Filenames must be relative pathnames in normal form, which means they must +neither start nor end with a slash (for example, `/foo` and `foo/` are +forbidden) nor contain multiple consecutive slashes as path separators +(for example, `foo//bar`). Similarly, up-level references (`..`) and +current-directory references (`./`) are forbidden. + +**Wrong** — Do not use `..` to refer to files in other packages + +**Correct** — Use `//package-name:filename` + +While it is common to use `/` in the name of a file target, avoid the use of +`/` in the names of rules. Especially when the shorthand form of a label is +used, it may confuse the reader. The label `//foo/bar/wiz` is always a shorthand +for `//foo/bar/wiz:wiz`, even if there is no such package `foo/bar/wiz`; it +never refers to `//foo:bar/wiz`, even if that target exists. + +However, there are some situations where use of a slash is convenient, or +sometimes even necessary. For example, the name of certain rules must match +their principal source file, which may reside in a subdirectory of the package. + +### Package names — `//package-name:{{ "" }}target-name{{ "" }}` + +The name of a package is the name of the directory containing its `BUILD` file, +relative to the top-level directory of the containing repository. +For example: `my/app`. + +On a technical level, Bazel enforces the following: + +* Allowed characters in package names are the lowercase letters `a` through `z`, + the uppercase letters `A` through `Z`, the digits `0` through `9`, the + characters ``! \"#$%&'()*+,-.;<=>?@[]^_`{|}`` (yes, there's a space character + in there!), and of course forward slash `/` (since it's the directory + separator). +* Package names may not start or end with a forward slash character `/`. +* Package names may not contain the substring `//`. This wouldn't make + sense---what would the corresponding directory path be? +* Package names may not contain the substring `/./` or `/../` or `/.../` etc. + This enforcement is done to avoid confusion when translating between a logical + package name and a physical directory name, given the semantic meaning of the + dot character in path strings. + +On a practical level: + +* For a language with a directory structure that is significant to its module + system (for example, Java), it's important to choose directory names that are + valid identifiers in the language. For example, don't start with a leading + digit and avoid special characters, especially underscores and hyphens. +* Although Bazel supports targets in the workspace's root package (for example, + `//:foo`), it's best to leave that package empty so all meaningful packages + have descriptive names. + +## Rules + +A rule specifies the relationship between inputs and outputs, and the +steps to build the outputs. Rules can be of one of many different +kinds (sometimes called the _rule class_), which produce compiled +executables and libraries, test executables and other supported +outputs as described in the [Build Encyclopedia](/reference/be/overview). + +`BUILD` files declare _targets_ by invoking _rules_. + +In the example below, we see the declaration of the target `my_app` +using the `cc_binary` rule. + +```python +cc_binary( + name = "my_app", + srcs = ["my_app.cc"], + deps = [ + "//absl/base", + "//absl/strings", + ], +) +``` + +Every rule invocation has a `name` attribute (which must be a valid +[target name](#target-names)), that declares a target within the package +of the `BUILD` file. + +Every rule has a set of _attributes_; the applicable attributes for a given +rule, and the significance and semantics of each attribute are a function of +the rule's kind; see the [Build Encyclopedia](/reference/be/overview) for a +list of rules and their corresponding attributes. Each attribute has a name and +a type. Some of the common types an attribute can have are integer, label, list +of labels, string, list of strings, output label, list of output labels. Not +all attributes need to be specified in every rule. Attributes thus form a +dictionary from keys (names) to optional, typed values. + +The `srcs` attribute present in many rules has type "list of labels"; its +value, if present, is a list of labels, each being the name of a target that is +an input to this rule. + +In some cases, the name of the rule kind is somewhat arbitrary, and more +interesting are the names of the files generated by the rule, and this is true +of genrules. For more information, see +[General Rules: genrule](/reference/be/general#genrule). + +In other cases, the name is significant: for `*_binary` and `*_test` rules, +for example, the rule name determines the name of the executable produced by +the build. + +This directed acyclic graph over targets is called the _target graph_ or +_build dependency graph_, and is the domain over which the +[Bazel Query tool](/query/guide) operates. + + + + Learn about build targets + + + Understand BUILD file syntax + + + diff --git a/configure/windows.mdx b/configure/windows.mdx new file mode 100644 index 0000000..ca2c08f --- /dev/null +++ b/configure/windows.mdx @@ -0,0 +1,311 @@ +--- +title: 'Using Bazel on Windows' +--- + + + +This page covers Best Practices for using Bazel on Windows. For installation +instructions, see [Install Bazel on Windows](/install/windows). + +## Known issues + +Windows-related Bazel issues are marked with the "area-Windows" label on GitHub. +[GitHub-Windows]. + +[GitHub-Windows]: https://github.com/bazelbuild/bazel/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-Windows + +## Best practices + +### Avoid long path issues + +Some tools have the [Maximum Path Length Limitation](https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#maximum-path-length-limitation) on Windows, including the MSVC compiler. +To avoid hitting this issue, you can specify a short output directory for Bazel by the [\-\-output_user_root](/reference/command-line-reference#flag--output_user_root) flag. + +For example, add the following line to your bazelrc file: + +```none +startup --output_user_root=C:/tmp +``` + +### Enable symlink support + +Some features require Bazel to be able to create file symlinks on Windows, +either by enabling +[Developer Mode](https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development) +(on Windows 10 version 1703 or newer), or by running Bazel as an administrator. +This enables the following features: + +* [\-\-windows_enable_symlinks](/reference/command-line-reference#flag--windows_enable_symlinks) +* [\-\-enable_runfiles](/reference/command-line-reference#flag--enable_runfiles) + +To make it easier, add the following lines to your bazelrc file: + +```none +startup --windows_enable_symlinks + +build --enable_runfiles +``` + +**Note**: Creating symlinks on Windows is an expensive operation. The `--enable_runfiles` flag can potentially create a large amount of file symlinks. Only enable this feature when you need it. + +{/* TODO(pcloudy): https://github.com/bazelbuild/bazel/issues/6402 + Write a doc about runfiles library and add a link to it here */} + +### Running Bazel: MSYS2 shell vs. command prompt vs. PowerShell + +**Recommendation:** Run Bazel from the command prompt (`cmd.exe`) or from +PowerShell. + +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)). +Also, if you choose to run under MSYS2, you need to disable MSYS2's +automatic path conversion, otherwise MSYS will convert command line arguments +that _look like_ Unix paths (such as `//foo:bar`) into Windows paths. See +[this StackOverflow answer](https://stackoverflow.com/a/49004265/7778502) +for details. + +### Using Bazel without Bash (MSYS2) + +#### Using bazel build without Bash + +Bazel versions before 1.0 used to require Bash to build some rules. + +Starting with Bazel 1.0, you can build any rule without Bash unless it is a: + +- `genrule`, because genrules execute Bash commands +- `sh_binary` or `sh_test` rule, because these inherently need Bash +- Starlark rule that uses `ctx.actions.run_shell()` or `ctx.resolve_command()` + +However, `genrule` is often used for simple tasks like +[copying a file](https://github.com/bazelbuild/bazel-skylib/blob/main/rules/copy_file.bzl) +or [writing a text file](https://github.com/bazelbuild/bazel-skylib/blob/main/rules/write_file.bzl). +Instead of using `genrule` (and depending on Bash) you may find a suitable rule +in the +[bazel-skylib repository](https://github.com/bazelbuild/bazel-skylib/tree/main/rules). +When built on Windows, **these rules do not require Bash**. + +#### Using bazel test without Bash + +Bazel versions before 1.0 used to require Bash to `bazel test` anything. + +Starting with Bazel 1.0, you can test any rule without Bash, except when: + +- you use `--run_under` +- the test rule itself requires Bash (because its executable is a shell script) + +#### Using bazel run without Bash + +Bazel versions before 1.0 used to require Bash to `bazel run` anything. + +Starting with Bazel 1.0, you can run any rule without Bash, except when: + +- you use `--run_under` or `--script_path` +- the test rule itself requires Bash (because its executable is a shell script) + +#### Using sh\_binary and sh\_* rules, and ctx.actions.run_shell() without Bash + +You need Bash to build and test `sh_*` rules, and to build and test Starlark +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). + +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 + +Environment variables you set in the Windows Command Prompt (`cmd.exe`) are only +set in that command prompt session. If you start a new `cmd.exe`, you need to +set the variables again. To always set the variables when `cmd.exe` starts, you +can add them to the User variables or System variables in the `Control Panel > +System Properties > Advanced > Environment Variables...` dialog box. + +## Build on Windows + +### Build C++ with MSVC + +To build C++ targets with MSVC, you need: + +* [The Visual C++ compiler](/install/windows#install-vc). + +* (Optional) The `BAZEL_VC` and `BAZEL_VC_FULL_VERSION` environment variable. + + Bazel automatically detects the Visual C++ compiler on your system. + To tell Bazel to use a specific VC installation, you can set the + following environment variables: + + For Visual Studio 2017 and 2019, set one of `BAZEL_VC`. Additionally you may also set `BAZEL_VC_FULL_VERSION`. + + * `BAZEL_VC` the Visual C++ Build Tools installation directory + + ``` + set BAZEL_VC=C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC + ``` + + * `BAZEL_VC_FULL_VERSION` (Optional) Only for Visual Studio 2017 and 2019, the full version + number of your Visual C++ Build Tools. You can choose the exact Visual C++ Build Tools + version via `BAZEL_VC_FULL_VERSION` if more than one version are installed, otherwise Bazel + will choose the latest version. + + ``` + set BAZEL_VC_FULL_VERSION=14.16.27023 + ``` + + For Visual Studio 2015 or older, set `BAZEL_VC`. (`BAZEL_VC_FULL_VERSION` is not supported.) + + * `BAZEL_VC` the Visual C++ Build Tools installation directory + + ``` + set BAZEL_VC=C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC + ``` + +* The [Windows + SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk). + + The Windows SDK contains header files and libraries you need when building + Windows applications, including Bazel itself. By default, the latest Windows SDK installed will + be used. You also can specify Windows SDK version by setting `BAZEL_WINSDK_FULL_VERSION`. You + can use a full Windows 10 SDK number such as 10.0.10240.0, or specify 8.1 to use the Windows 8.1 + SDK (only one version of Windows 8.1 SDK is available). Please make sure you have the specified + Windows SDK installed. + + **Requirement**: This is supported with VC 2017 and 2019. The standalone VC 2015 Build Tools doesn't + support selecting Windows SDK, you'll need the full Visual Studio 2015 installation, otherwise + `BAZEL_WINSDK_FULL_VERSION` will be ignored. + + ``` + set BAZEL_WINSDK_FULL_VERSION=10.0.10240.0 + ``` + +If everything is set up, you can build a C++ target now! + +Try building a target from one of our [sample +projects](https://github.com/bazelbuild/bazel/tree/master/examples): + +``` +bazel build //examples/cpp:hello-world +bazel-bin\examples\cpp\hello-world.exe +``` + +By default, the built binaries target x64 architecture. To build for ARM64 +architecture, use + +```none +--platforms=//:windows_arm64 --extra_toolchains=@local_config_cc//:cc-toolchain-arm64_windows +``` + +You can introduce `@local_config_cc` in `MODULE.bazel` with + +```python +bazel_dep(name = "rules_cc", version = "0.1.1") +cc_configure = use_extension("@rules_cc//cc:extensions.bzl", "cc_configure_extension") +use_repo(cc_configure, "local_config_cc") +``` + +To build and use Dynamically Linked Libraries (DLL files), see [this +example](https://github.com/bazelbuild/bazel/tree/master/examples/windows/dll). + +**Command Line Length Limit**: To prevent the +[Windows command line length limit issue](https://github.com/bazelbuild/bazel/issues/5163), +enable the compiler parameter file feature via `--features=compiler_param_file`. + +### Build C++ with Clang + +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 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`. + +* `BAZEL_LLVM` the LLVM installation directory + + ```posix-terminal + set BAZEL_LLVM=C:\Program Files\LLVM + ``` + +To enable the Clang toolchain for building C++, there are several situations. + +* In Bazel 7.0.0 and newer: Add a platform target to your `BUILD file` (eg. the + top level `BUILD` file): + + ``` + platform( + name = "x64_windows-clang-cl", + constraint_values = [ + "@platforms//cpu:x86_64", + "@platforms//os:windows", + "@bazel_tools//tools/cpp:clang-cl", + ], + ) + ``` + + Then enable the Clang toolchain by specifying the following build flags: + + ``` + --extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows-clang-cl --extra_execution_platforms=//:x64_windows-clang-cl + ``` + +* In Bazel older than 7.0.0 but newer than 0.28: Enable the Clang toolchain by + a build flag `--compiler=clang-cl`. + + If your build sets the flag + [\-\-incompatible_enable_cc_toolchain_resolution] + (https://github.com/bazelbuild/bazel/issues/7260) + to `true`, then use the approach for Bazel 7.0.0. + +* In Bazel 0.28 and older: Clang is not supported. + +### Build Java + +To build Java targets, you need: + +* [The Java SE Development Kit](/install/windows#install-jdk) + +On Windows, Bazel builds two output files for `java_binary` rules: + +* a `.jar` file +* a `.exe` file that can set up the environment for the JVM and run the binary + +Try building a target from one of our [sample +projects](https://github.com/bazelbuild/bazel/tree/master/examples): + +``` +bazel build //examples/java-native/src/main/java/com/example/myproject:hello-world +bazel-bin\examples\java-native\src\main\java\com\example\myproject\hello-world.exe +``` + +### Build Python + +To build Python targets, you need: + +* The [Python interpreter](/install/windows#install-python) + +On Windows, Bazel builds two output files for `py_binary` rules: + +* a self-extracting zip file +* an executable file that can launch the Python interpreter with the + self-extracting zip file as the argument + +You can either run the executable file (it has a `.exe` extension) or you can run +Python with the self-extracting zip file as the argument. + +Try building a target from one of our [sample +projects](https://github.com/bazelbuild/bazel/tree/master/examples): + +``` +bazel build //examples/py_native:bin +bazel-bin\examples\py_native\bin.exe +python bazel-bin\examples\py_native\bin.zip +``` + +If you are interested in details about how Bazel builds Python targets on +Windows, check out this [design +doc](https://github.com/bazelbuild/bazel-website/blob/master/designs/_posts/2016-09-05-build-python-on-windows.md). + diff --git a/contribute/search.mdx b/contribute/search.mdx new file mode 100644 index 0000000..1a391e7 --- /dev/null +++ b/contribute/search.mdx @@ -0,0 +1,279 @@ +--- +title: 'Searching the codebase' +--- + + + +## Product overview + +Bazel's [code search and source browsing interface](https://source.bazel.build) +is a web-based tool for browsing Bazel source code repositories. You can +use these features to navigate among different repositories, branches, and +files. You can also view history, diffs, and blame information. + +## Getting started + +Note: For the best experience, use the latest version of Chrome, Safari, or +Firefox. + +To access the code search and source browsing interface, open +[https://source.bazel.build](https://source.bazel.build) in your web browser. + +The main screen appears. This screen contains the following components: + +1. The Breadcrumb toolbar. This toolbar displays your current location in the +repository and allows you to move quickly to another location such as another +repository, or another location within a repository, such as a file, branch, or +commit. + +1. A list of repositories that you can browse. + +At the top of the screen is a search box. You can use this box to search for +specific files and code. + +## Working with repositories + +### Opening a repository + +To open a repository, click its name from the main screen. + +Alternatively, you can use the Breadcrumb toolbar to browse for a +specificrepository. This toolbar displays your current location in the +repository and allows you to move quickly to another location such as another +repository, or another location within a repository, such as a file, branch, or +commit. + +### Switch repositories + +To switch to a different repository, select the repository from the Breadcrumb toolbar. + +### View a repository at a specific commit + +To view a repository at a specific commit: + +1. From the view of the repository, select the file. +1. From the Breadcrumb toolbar, open the **Branch** menu. +1. In the submenu that appears, click **Commit**. +1. Select the commit you want to view. + +The interface now shows the repository as it existed at that commit. + +### Open a branch, commit, or tag + +By default, the code search and source browsing interface opens a repository to +the default branch. To open a different branch, from the Breadcrumb toolbar, +click the **Branch/Commit/Tag** menu. A submenu opens, allowing you to select a +branch using a branch name, a tag name, or through a search box. + +* To select a branch using a branch name, select **Branch** and then click the + name of the branch. +* To select a branch using a tag name, select **Tag** and + then click the tag name. +* To select a branch using a commit id, select **Commit** and then click the + commit id. +* To search for a branch, commit, or tag, select the corresponding item and + type a search term in the search box. + +## Working with files + +When you select a repository from the main screen, the screen changes to display +a view of that repository. If a README file exists, its contents appear in the +file pane, located on the right side of the screen. Otherwise, a list of +repository's files and folders appear. On the left side of the screen is a tree +view of the repository's files and folders. You can use this tree to browse and +open specific files. + +Notice that, when you are viewing a repository, the Breadcrumb toolbar now has +three components: + +* A **Repository** menu, from which you can select different repositories +* A **Branch/Commit/Tag** menu, from which you can select specific branches, + tags, or commits +* A **File path** box, which displays the name of the current file or folder + and its corresponding path + +### Open a file + +You can open a file by browsing to its directory and selecting it. The view of +the repository updates to show the contents of the file in the file pane, and +its location in the repository in the tree pane. + +### View file changes + +To view file changes: + +1. From the view of the repository, select the file. +1. Click **BLAME**, located in the upper-right corner. + +The file pane updates to display who made changes to the file and when. + +### View change history + +To view the change history of a file: + +1. From the view of the repository, select the file. +1. Click **HISTORY**, located in the upper-right corner. + The **Change history** pane appears, showing the commits for this file. + +### View code reviews + +For Gerrit code reviews, you can open the tool directly from the Change History pane. + +To view the code review for a file: + +1. From the view of the repository, select the file. +1. Click **HISTORY**, located in the upper-right corner. The Change History pane + appears, showing the commits for this file. +1. Hover over a commit. A **More** button (three vertical dots) appears. +1. Click the **More** button. +1. Select **View code review**. + +The Gerrit Code Review tool opens in a new browser window. + +### Open a file at a specific commit + +To open a file at a specific commit: + +1. From the view of the repository, select the file. +1. Click **HISTORY**, located in the upper-right corner. The Change History pane + appears, showing the commits for this file. +1. Hover over a commit. A **VIEW** button appears. +1. Click the **VIEW** button. + +### Compare a file to a different commit + +To compare a file at a different commit: + +1. From the view of the repository, select the file. To compare from two + different commits, first open the file at that commit. +1. Hover over a commit. A **DIFF** button appears. +1. Click the **DIFF** button. + +The file pane updates to display a side-by-side comparison between the two +files. The oldest of the two commits is always on the left. + +In the Change History pane, both commits are highlighted, and a label indicates +if the commit is displayed on the left or the right. + +To change either file, hover over the commit in the Change History pane. Then, +click either the **Left** or **Right** button to have the open the commit on the +left or right side of the diff. + +### Browsing cross references + +Another way to browse source repositories is through the use of cross +references. These references appear automatically as hyperlinks within a given +source file. + +To make cross references easier to identify, click **Cross References**, +located in the upper-right corner. This option displays an underline below all +cross references in a file. + +**Note:** If **Cross References** is grayed out, it indicates that +cross references are not available for that file. + +Click a cross reference to open the Cross Reference pane. This pane contains +two sections: + +* A **Definition** section, which lists the file or files that define the + reference +* A **References** section, which lists the files in which the reference also + appears + +Both sections display the name of the file, as well as the line or lines +that contains the reference. To open a file from the Cross Reference pane, +click the line number entry. The file appears in a new section of the pane, +allowing you to continue to browse the file while keeping the original file +in view. + +You can continue to browse cross references using the Cross Reference pane, just +as you can in the File pane. When you do, the pane displays a breadcrumb trail, +which you can use to navigate between different cross references. + +## Searching for code + +You can search for specific files or code snippets using the search box located +at the top of the screen. Searches are always against the default branch. + +All searches use [RE2 regular expressions](https://github.com/google/re2/wiki/Syntax) +by default. If you do not want to use regular expressions, enclose your search +in double quotes ( " ). + +**Note:** To quickly search for a specific file, either add a backslash in front +of the period, or enclose the entire file name in quotes. + +``` +foo\.java +"foo.java" +``` + +You can refine your search using the following filters. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FilterOther optionsDescriptionExample
lang:language:Perform an exact match by file language.lang:java test
file:filepath:
+path:
+f:
case:yesMake the search case sensitive. By default, searches are not case-sensitive.case:yes Hello World
class:Search for a class name.class:MainClass
function:func:Search for a function name.function:print
-Negates the term from the search.hello -world
\Escapes special characters, such as ., \, or (.run\(\)
"[term]"Perform a literal search."class:main"
+ +## Additional Support + +To report an issue, click the **Feedback** button that appears in the top +right-hand corner of the screen and enter your feedback in the provided form. + diff --git a/copy-upstream-docs.sh b/copy-upstream-docs.sh index e45aa66..74f5813 100755 --- a/copy-upstream-docs.sh +++ b/copy-upstream-docs.sh @@ -25,15 +25,8 @@ LOCAL_FILES=" BROKEN_FILES=" community/roadmaps-configurability.mdx community/users.mdx -concepts/build-files.mdx -concepts/dependencies.mdx -concepts/labels.mdx configure/integrate-cpp.mdx -configure/windows.mdx -contribute/search.mdx -docs/cc-toolchain-config-reference.mdx docs/mobile-install.mdx -docs/user-manual.mdx extending/config.mdx extending/legacy-macros.mdx extending/macros.mdx @@ -47,9 +40,6 @@ external/vendor.mdx install/windows.mdx query/guide.mdx query/language.mdx -query/quickstart.mdx -reference/flag-cheatsheet.mdx -reference/test-encyclopedia.mdx reference/command-line-reference.mdx reference/be/be-nav.mdx reference/be/functions.mdx @@ -59,7 +49,6 @@ remote/ci.mdx remote/dynamic.mdx rules/language.mdx rules/windows.mdx -run/build.mdx start/go.mdx tutorials/ccp-toolchain-config.mdx " diff --git a/docs/cc-toolchain-config-reference.mdx b/docs/cc-toolchain-config-reference.mdx new file mode 100644 index 0000000..79853e9 --- /dev/null +++ b/docs/cc-toolchain-config-reference.mdx @@ -0,0 +1,785 @@ +--- +title: 'C++ Toolchain Configuration' +--- + + + +## Overview + +To invoke the compiler with the right options, Bazel needs some knowledge about +the compiler internals, such as include directories and important flags. +In other words, Bazel needs a simplified model of the compiler to understand its +workings. + +Bazel needs to know the following: + +* Whether the compiler supports thinLTO, modules, dynamic linking, or PIC + (position independent code). +* Paths to the required tools such as gcc, ld, ar, objcopy, and so on. +* The built-in system include directories. Bazel needs these to validate that + all headers that were included in the source file were properly declared in + the `BUILD` file. +* The default sysroot. +* Which flags to use for compilation, linking, archiving. +* Which flags to use for the supported compilation modes (opt, dbg, fastbuild). +* Make variables specifically required by the compiler. + +If the compiler has support for multiple architectures, Bazel needs to configure +them separately. + +[`CcToolchainConfigInfo`](/rules/lib/providers/CcToolchainConfigInfo) is a provider that provides the necessary level of +granularity for configuring the behavior of Bazel's C++ rules. By default, +Bazel automatically configures `CcToolchainConfigInfo` for your build, but you +have the option to configure it manually. For that, you need a Starlark rule +that provides the `CcToolchainConfigInfo` and you need to point the +[`toolchain_config`](/reference/be/c-cpp#cc_toolchain.toolchain_config) attribute of the +[`cc_toolchain`](/reference/be/c-cpp#cc_toolchain) to your rule. +You can create the `CcToolchainConfigInfo` by calling +[`cc_common.create_cc_toolchain_config_info()`](/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info). +You can find Starlark constructors for all structs you'll need in the process in +[`@rules_cc//cc:cc_toolchain_config_lib.bzl`](https://github.com/bazelbuild/rules_cc/blob/master/cc/cc_toolchain_config_lib.bzl). + + +When a C++ target enters the analysis phase, Bazel selects the appropriate +`cc_toolchain` target based on the `BUILD` file, and obtains the +`CcToolchainConfigInfo` provider from the target specified in the +`cc_toolchain.toolchain_config` attribute. The `cc_toolchain` target +passes this information to the C++ target through a `CcToolchainProvider`. + +For example, a compile or link action, instantiated by a rule such as +`cc_binary` or `cc_library`, needs the following information: + +* The compiler or linker to use +* Command-line flags for the compiler/linker +* Configuration flags passed through the `--copt/--linkopt` options +* Environment variables +* Artifacts needed in the sandbox in which the action executes + +All of the above information except the artifacts required in the sandbox is +specified in the Starlark target that the `cc_toolchain` points to. + +The artifacts to be shipped to the sandbox are declared in the `cc_toolchain` +target. For example, with the `cc_toolchain.linker_files` attribute you can +specify the linker binary and toolchain libraries to ship into the sandbox. + +## Toolchain selection + +The toolchain selection logic operates as follows: + +1. User specifies a `cc_toolchain_suite` target in the `BUILD` file and points + Bazel to the target using the + [`--crosstool_top` option](/docs/user-manual#flag--crosstool_top). + +2. The `cc_toolchain_suite` target references multiple toolchains. The + values of the `--cpu` and `--compiler` flags determine which of those + toolchains is selected, either based only on the `--cpu` flag value, or + based on a joint `--cpu | --compiler` value. The selection process is as + follows: + + * If the `--compiler` option is specified, Bazel selects the + corresponding entry from the `cc_toolchain_suite.toolchains` + attribute with `--cpu | --compiler`. If Bazel does not find + a corresponding entry, it throws an error. + + * If the `--compiler` option is not specified, Bazel selects + the corresponding entry from the `cc_toolchain_suite.toolchains` + attribute with just `--cpu`. + + * If no flags are specified, Bazel inspects the host system and selects a + `--cpu` value based on its findings. See the + [inspection mechanism code](https://source.bazel.build/bazel/+/1b73bc37e184e71651eb631223dcce321ba16211:src/main/java/com/google/devtools/build/lib/analysis/config/AutoCpuConverter.java). + +Once a toolchain has been selected, corresponding `feature` and `action_config` +objects in the Starlark rule govern the configuration of the build (that is, +items described later). These messages allow the implementation of +fully fledged C++ features in Bazel without modifying the +Bazel binary. C++ rules support multiple unique actions documented in detail +[in the Bazel source code](https://source.bazel.build/bazel/+/4f547a7ea86df80e4c76145ffdbb0c8b75ba3afa:tools/build_defs/cc/action_names.bzl). + +## Features + +A feature is an entity that requires command-line flags, actions, +constraints on the execution environment, or dependency alterations. A feature +can be something as simple as allowing `BUILD` files to select configurations of +flags, such as `treat_warnings_as_errors`, or interact with the C++ rules and +include new compile actions and inputs to the compilation, such as +`header_modules` or `thin_lto`. + +Ideally, `CcToolchainConfigInfo` contains a list of features, where each +feature consists of one or more flag groups, each defining a list of flags +that apply to specific Bazel actions. + +A feature is specified by name, which allows full decoupling of the Starlark +rule configuration from Bazel releases. In other words, a Bazel release does not +affect the behavior of `CcToolchainConfigInfo` configurations as long as those +configurations do not require the use of new features. + +A feature is enabled in one of the following ways: + +* The feature's `enabled` field is set to `true`. +* Bazel or the rule owner explicitly enable it. +* The user enables it through the `--feature` Bazel option or `features` rule + attribute. + +Features can have interdependencies, depend on command line flags, `BUILD` file +settings, and other variables. + +### Feature relationships + +Dependencies are typically managed directly with Bazel, which simply enforces +the requirements and manages conflicts intrinsic to the nature of the features +defined in the build. The toolchain specification allows for more granular +constraints for use directly within the Starlark rule that govern feature +support and expansion. These are: + +| Constraint | Description | +|------------|-------------| +| `requires = [feature_set (features = ['feature-name-1', 'feature-name-2']),]` | Feature-level. The feature is supported only if the specified required features are enabled. For example, when a feature is only supported in certain build modes (`opt`, `dbg`, or `fastbuild`). If `requires` contains multiple `feature_set`s the feature is supported if any of the `feature_set`s is satisfied (when all specified features are enabled). | +| `implies = ['feature']` | Feature-level. This feature implies the specified feature(s). Enabling a feature also implicitly enables all features implied by it (that is, it functions recursively). Also provides the ability to factor common subsets of functionality out of a set of features, such as the common parts of sanitizers. Implied features cannot be disabled. | +| `provides = ['feature']` | Feature-level. Indicates that this feature is one of several mutually exclusive alternate features. For example, all of the sanitizers could specify `provides = ["sanitizer"]`. This improves error handling by listing the alternatives if the user asks for two or more mutually exclusive features at once. | +| `with_features = [with_feature_set(features = ['feature-1'], not_features = ['feature-2'],),]` | Flag set-level. A feature can specify multiple flag sets with multiple. When `with_features` is specified, the flag set will only expand to the build command if there is at least one `with_feature_set` for which all of the features in the specified `features` set are enabled, and all the features specified in `not_features` set are disabled. If `with_features` is not specified, the flag set will be applied unconditionally for every action specified. | + +## Actions + +Actions provide the flexibility to modify the circumstances under +which an action executes without assuming how the action will be run. An +`action_config` specifies the tool binary that an action invokes, while a +`feature` specifies the configuration (flags) that determine how that tool +behaves when the action is invoked. + +[Features](#features) reference actions to signal which Bazel actions +they affect since actions can modify the Bazel action graph. The +`CcToolchainConfigInfo` provider contains actions that have flags and tools +associated with them, such as `c++-compile`. Flags are assigned to each action +by associating them with a feature. + +Each action name represents a single type of action performed by Bazel, such as +compiling or linking. There is, however, a many-to-one relationship between +actions and Bazel action types, where a Bazel action type refers to a Java class +that implements an action (such as `CppCompileAction`). In particular, the +"assembler actions" and "compiler actions" in the table below are +`CppCompileAction`, while the link actions are `CppLinkAction`. + +### Assembler actions + +| Action | Description | +|--------|-------------| +| `preprocess-assemble` | Assemble with preprocessing. Typically for `.S` files. | +| `assemble` | Assemble without preprocessing. Typically for `.s` files. | + +### Compiler actions + +| Action | Description | +|--------|-------------| +| `cc-flags-make-variable` | Propagates `CC_FLAGS` to genrules. | +| `c-compile` | Compile as C. | +| `c++-compile` | Compile as C++. | +| `c++-header-parsing` | Run the compiler's parser on a header file to ensure that the header is self-contained, as it will otherwise produce compilation errors. Applies only to toolchains that support modules. | + +### Link actions + +| Action | Description | +|--------|-------------| +| `c++-link-dynamic-library` | Link a shared library containing all of its dependencies. | +| `c++-link-nodeps-dynamic-library` | Link a shared library only containing `cc_library` sources. | +| `c++-link-executable` | Link a final ready-to-run library. | + +### AR actions + +AR actions assemble object files into archive libraries (`.a` files) via `ar` +and encode some semantics into the name. + +| Action | Description | +|--------|-------------| +| `c++-link-static-library` | Create a static library (archive). | + +### LTO actions + +| Action | Description | +|--------|-------------| +| `lto-backend` | ThinLTO action compiling bitcodes into native objects. | +| `lto-index` | ThinLTO action generating global index. | + +## Using action_config + +The `action_config` is a Starlark struct that describes a Bazel +action by specifying the tool (binary) to invoke during the action and sets of +flags, defined by features. These flags apply constraints to the action's +execution. + +The `action_config()` constructor has the following parameters: + +| Attribute | Description | +|-----------|-------------| +| `action_name` | The Bazel action to which this action corresponds. Bazel uses this attribute to discover per-action tool and execution requirements. | +| `tools` | The executable to invoke. The tool applied to the action will be the first tool in the list with a feature set that matches the feature configuration. Default value must be provided. | +| `flag_sets` | A list of flags that applies to a group of actions. Same as for a feature. | +| `env_sets` | A list of environment constraints that applies to a group of actions. Same as for a feature. | + +An `action_config` can require and imply other features and +action_configs as dictated by the +[feature relationships](#feature-relationships) described earlier. This behavior +is similar to that of a feature. + +The last two attributes are redundant against the corresponding attributes on +features and are included because some Bazel actions require certain flags or +environment variables and the goal is to avoid unnecessary `action_config`+`feature` +pairs. Typically, sharing a single feature across multiple `action_config`s is +preferred. + +You can not define more than one `action_config` with the same `action_name` +within the same toolchain. This prevents ambiguity in tool paths +and enforces the intention behind `action_config` - that an action's properties +are clearly described in a single place in the toolchain. + +### Using tool constructor + +An`action_config` can specify a set of tools via its `tools` parameter. +The `tool()` constructor takes in the following parameters: + +| Field | Description | +|-------|-------------| +| `path` | Path to the tool in question (relative to the current location). | +| `with_features` | A list of feature sets out of which at least one must be satisfied for this tool to apply. | + +For a given `action_config`, only a single `tool` applies +its tool path and execution requirements to the Bazel action. A tool is selected +by iterating through the `tools` attribute on an `action_config` until a tool +with a `with_feature` set matching the feature configuration is found +(see [Feature relationships](#feature-relationships) earlier on this page +for more information). You should end your tool lists with a default +tool that corresponds to an empty feature configuration. + +### Example usage + +Features and actions can be used together to implement Bazel actions +with diverse cross-platform semantics. For example, debug symbol generation on +macOS requires generating symbols in the compile action, then invoking a +specialized tool during the link action to create compressed dsym archive, and +then decompressing that archive to produce the application bundle and `.plist` +files consumable by Xcode. + +With Bazel, this process can instead be implemented as follows, with +`unbundle-debuginfo` being a Bazel action: + + load("@rules_cc//cc:defs.bzl", "ACTION_NAMES") + + action_configs = [ + action_config ( + action_name = ACTION_NAMES.cpp_link_executable, + tools = [ + tool( + with_features = [ + with_feature(features=["generate-debug-symbols"]), + ], + path = "toolchain/mac/ld-with-dsym-packaging", + ), + tool (path = "toolchain/mac/ld"), + ], + ), + ] + + features = [ + feature( + name = "generate-debug-symbols", + flag_sets = [ + flag_set ( + actions = [ + ACTION_NAMES.c_compile, + ACTION_NAMES.cpp_compile + ], + flag_groups = [ + flag_group( + flags = ["-g"], + ), + ], + ) + ], + implies = ["unbundle-debuginfo"], + ), + ] + + +This same feature can be implemented entirely differently for Linux, which uses +`fission`, or for Windows, which produces `.pdb` files. For example, the +implementation for `fission`-based debug symbol generation might look as +follows: + + load("@rules_cc//cc:defs.bzl", "ACTION_NAMES") + + action_configs = [ + action_config ( + name = ACTION_NAMES.cpp_compile, + tools = [ + tool( + path = "toolchain/bin/gcc", + ), + ], + ), + ] + + features = [ + feature ( + name = "generate-debug-symbols", + requires = [with_feature_set(features = ["dbg"])], + flag_sets = [ + flag_set( + actions = [ACTION_NAMES.cpp_compile], + flag_groups = [ + flag_group( + flags = ["-gsplit-dwarf"], + ), + ], + ), + flag_set( + actions = [ACTION_NAMES.cpp_link_executable], + flag_groups = [ + flag_group( + flags = ["-Wl", "--gdb-index"], + ), + ], + ), + ], + ), + ] + + +### Flag groups + +`CcToolchainConfigInfo` allows you to bundle flags into groups that serve a +specific purpose. You can specify a flag within using pre-defined variables +within the flag value, which the compiler expands when adding the flag to the +build command. For example: + + flag_group ( + flags = ["%{output_execpath}"], + ) + + +In this case, the contents of the flag will be replaced by the output file path +of the action. + +Flag groups are expanded to the build command in the order in which they appear +in the list, top-to-bottom, left-to-right. + +For flags that need to repeat with different values when added to the build +command, the flag group can iterate variables of type `list`. For example, the +variable `include_path` of type `list`: + + flag_group ( + iterate_over = "include_paths", + flags = ["-I%{include_paths}"], + ) + +expands to `-I` for each path element in the `include_paths` list. All +flags (or `flag_group`s) in the body of a flag group declaration are expanded as +a unit. For example: + + flag_group ( + iterate_over = "include_paths", + flags = ["-I", "%{include_paths}"], + ) + +expands to `-I ` for each path element in the `include_paths` list. + +A variable can repeat multiple times. For example: + + flag_group ( + iterate_over = "include_paths", + flags = ["-iprefix=%{include_paths}", "-isystem=%{include_paths}"], + ) + +expands to: + + -iprefix=<inc0> -isystem=<inc0> -iprefix=<inc1> -isystem=<inc1> + +Variables can correspond to structures accessible using dot-notation. For +example: + + flag_group ( + flags = ["-l%{libraries_to_link.name}"], + ) + +Structures can be nested and may also contain sequences. To prevent name clashes +and to be explicit, you must specify the full path through the fields. For +example: + + flag_group ( + iterate_over = "libraries_to_link", + flag_groups = [ + flag_group ( + iterate_over = "libraries_to_link.shared_libraries", + flags = ["-l%{libraries_to_link.shared_libraries.name}"], + ), + ], + ) + + +### Conditional expansion + +Flag groups support conditional expansion based on the presence of a particular +variable or its field using the `expand_if_available`, `expand_if_not_available`, +`expand_if_true`, `expand_if_false`, or `expand_if_equal` attributes. For example: + + + flag_group ( + iterate_over = "libraries_to_link", + flag_groups = [ + flag_group ( + iterate_over = "libraries_to_link.shared_libraries", + flag_groups = [ + flag_group ( + expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive", + flags = ["--whole_archive"], + ), + flag_group ( + flags = ["-l%{libraries_to_link.shared_libraries.name}"], + ), + flag_group ( + expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive", + flags = ["--no_whole_archive"], + ), + ], + ), + ], + ) + +Note: The `--whole_archive` and `--no_whole_archive` options are added to +the build command only when a currently iterated library has an +`is_whole_archive` field. + +## CcToolchainConfigInfo reference + +This section provides a reference of build variables, features, and other +information required to successfully configure C++ rules. + +### CcToolchainConfigInfo build variables + +The following is a reference of `CcToolchainConfigInfo` build variables. + +Note: The **Action** column indicates the relevant action type, if applicable. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Variable Action Description
source_file compileSource file to compile.
input_file stripArtifact to strip.
output_file compile, stripCompilation output.
output_assembly_file compileEmitted assembly file. Applies only when the compile action emits assembly text, typically when using the --save_temps flag. The contents are the same as for output_file.
output_preprocess_file compilePreprocessed output. Applies only to compile actions that only preprocess the source files, typically when using the --save_temps flag. The contents are the same as for output_file.
includes compileSequence of files the compiler must unconditionally include in the compiled source.
include_paths compileSequence directories in which the compiler searches for headers included using #include<foo.h> and #include "foo.h".
quote_include_paths compileSequence of -iquote includes - directories in which the compiler searches for headers included using #include "foo.h".
system_include_paths compileSequence of -isystem includes - directories in which the compiler searches for headers included using #include <foo.h>.
dependency_file compileThe .d dependency file generated by the compiler.
preprocessor_defines compileSequence of defines, such as --DDEBUG.
pic compileCompiles the output as position-independent code.
gcov_gcno_file compileThe gcov coverage file.
per_object_debug_info_file compileThe per-object debug info (.dwp) file.
stripopts stripSequence of stripopts.
legacy_compile_flags compileSequence of flags from legacy CROSSTOOL fields such as compiler_flag, optional_compiler_flag, cxx_flag, and optional_cxx_flag.
user_compile_flags compileSequence of flags from either the copt rule attribute or the --copt, --cxxopt, and --conlyopt flags.
unfiltered_compile_flags compileSequence of flags from the unfiltered_cxx_flag legacy CROSSTOOL field or the unfiltered_compile_flags feature. These are not filtered by the nocopts rule attribute.
sysroot The sysroot.
runtime_library_search_directories linkEntries in the linker runtime search path (usually set with the -rpath flag).
library_search_directories linkEntries in the linker search path (usually set with the -L flag).
libraries_to_link linkFlags providing files to link as inputs in the linker invocation.
def_file_path linkLocation of def file used on Windows with MSVC.
linker_param_file linkLocation of linker param file created by bazel to overcome command line length limit.
output_execpath linkExecpath of the output of the linker.
generate_interface_library link"yes" or "no" depending on whether interface library should be generated.
interface_library_builder_path linkPath to the interface library builder tool.
interface_library_input_path linkInput for the interface library ifso builder tool.
interface_library_output_path linkPath where to generate interface library using the ifso builder tool.
legacy_link_flags linkLinker flags coming from the legacy CROSSTOOL fields.
user_link_flags linkLinker flags coming from the --linkopt or linkopts attribute.
linkstamp_paths linkA build variable giving linkstamp paths.
force_pic linkPresence of this variable indicates that PIC/PIE code should be generated (Bazel option `--force_pic` was passed).
strip_debug_symbols linkPresence of this variable indicates that the debug symbols should be stripped.
is_cc_test linkTruthy when current action is a cc_test linking action, false otherwise.
is_using_fission compile, linkPresence of this variable indicates that fission (per-object debug info) is activated. Debug info will be in .dwo files instead of .o files and the compiler and linker need to know this.
fdo_instrument_path compile, link Path to the directory that stores FDO instrumentation profile.
fdo_profile_path compile Path to FDO profile.
fdo_prefetch_hints_path compile Path to the cache prefetch profile.
cs_fdo_instrument_path compile, link Path to the directory that stores context sensitive FDO instrumentation profile.
+ +### Well-known features + +The following is a reference of features and their activation +conditions. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Feature Documentation
opt | dbg | fastbuild Enabled by default based on compilation mode.
static_linking_mode | dynamic_linking_mode Enabled by default based on linking mode.
per_object_debug_info Enabled if the supports_fission feature is specified and enabled and the current compilation mode is specified in the --fission flag.
supports_start_end_lib If enabled (and the option --start_end_lib is set), Bazel will not link against static libraries but instead use the --start-lib/--end-lib linker options to link against objects directly. This speeds up the build since Bazel doesn't have to build static libraries.
supports_interface_shared_libraries If enabled (and the option --interface_shared_objects is set), Bazel will link targets that have linkstatic set to False (cc_tests by default) against interface shared libraries. This makes incremental relinking faster.
supports_dynamic_linker If enabled, C++ rules will know the toolchain can produce shared libraries.
static_link_cpp_runtimes If enabled, Bazel will link the C++ runtime statically in static linking mode and dynamically in dynamic linking mode. Artifacts specified in the cc_toolchain.static_runtime_lib or cc_toolchain.dynamic_runtime_lib attribute (depending on the linking mode) will be added to the linking actions.
supports_pic If enabled, toolchain will know to use PIC objects for dynamic libraries. The `pic` variable is present whenever PIC compilation is needed. If not enabled by default, and `--force_pic` is passed, Bazel will request `supports_pic` and validate that the feature is enabled. If the feature is missing, or couldn't be enabled, `--force_pic` cannot be used.
static_linking_mode | dynamic_linking_mode Enabled by default based on linking mode.
no_legacy_features Prevents Bazel from adding legacy features to the C++ configuration when present. See the complete list of features below.
shorten_virtual_includes If enabled, virtual include header files are linked under bin/_virtual_includes/<hash of target path> instead of bin/<target package path>/_virtual_includes/<target name>. Useful on Windows to avoid long path issue with MSVC.
+ +#### Legacy features patching logic + +

+ Bazel applies the following changes to the toolchain's features for backwards + compatibility: + +

+

+ +This is a long list of features. The plan is to get rid of them once +[Crosstool in Starlark](https://github.com/bazelbuild/bazel/issues/5380) is +done. For the curious reader see the implementation in +[CppActionConfigs](https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/rules/cpp/CppActionConfigs.java?q=cppactionconfigs&ss=bazel), +and for production toolchains consider adding `no_legacy_features` to make +the toolchain more standalone. + + diff --git a/docs/user-manual.mdx b/docs/user-manual.mdx new file mode 100644 index 0000000..c3d24e9 --- /dev/null +++ b/docs/user-manual.mdx @@ -0,0 +1,2485 @@ +--- +title: 'Commands and Options' +--- + + + +This page covers the options that are available with various Bazel commands, +such as `bazel build`, `bazel run`, and `bazel test`. This page is a companion +to the list of Bazel's commands in [Build with Bazel](/run/build). + +## Target syntax + +Some commands, like `build` or `test`, can operate on a list of targets. They +use a syntax more flexible than labels, which is documented in +[Specifying targets to build](/run/build#specifying-build-targets). + +## Options + +The following sections describe the options available during a +build. When `--long` is used on a help command, the on-line +help messages provide summary information about the meaning, type and +default value for each option. + +Most options can only be specified once. When specified multiple times, the +last instance wins. Options that can be specified multiple times are +identified in the on-line help with the text 'may be used multiple times'. + +### Package location + +#### `--package_path` + +**WARNING:** The `--package_path` option is deprecated. Bazel prefers packages +in the main repository to be under the workspace root. + +This option specifies the set of directories that are searched to +find the BUILD file for a given package. + +Bazel finds its packages by searching the package path. This is a colon +separated ordered list of bazel directories, each being the root of a +partial source tree. + +_To specify a custom package path_ using the `--package_path` option: + +``` + % bazel build --package_path %workspace%:/some/other/root +``` + +Package path elements may be specified in three formats: + +1. If the first character is `/`, the path is absolute. +2. If the path starts with `%workspace%`, the path is taken relative + to the nearest enclosing bazel directory. + For instance, if your working directory + is `/home/bob/clients/bob_client/bazel/foo`, then the + string `%workspace%` in the package-path is expanded + to `/home/bob/clients/bob_client/bazel`. +3. Anything else is taken relative to the working directory. + This is usually not what you mean to do, + and may behave unexpectedly if you use Bazel from directories below the bazel workspace. + For instance, if you use the package-path element `.`, + and then cd into the directory + `/home/bob/clients/bob_client/bazel/foo`, packages + will be resolved from the + `/home/bob/clients/bob_client/bazel/foo` directory. + +If you use a non-default package path, specify it in your +[Bazel configuration file](/run/bazelrc) for convenience. + +_Bazel doesn't require any packages to be in the +current directory_, so you can do a build from an empty bazel +workspace if all the necessary packages can be found somewhere else +on the package path. + +Example: Building from an empty client + +``` + % mkdir -p foo/bazel + % cd foo/bazel + % touch MODULE.bazel + % bazel build --package_path /some/other/path //foo +``` + +#### `--deleted_packages` + +This option specifies a comma-separated list of packages which Bazel +should consider deleted, and not attempt to load from any directory +on the package path. This can be used to simulate the deletion of packages without +actually deleting them. This option can be passed multiple times, in which case +the individual lists are concatenated. + +### Error checking + +These options control Bazel's error-checking and/or warnings. + +#### `--[no]check_visibility` + +If this option is set to false, visibility checks are demoted to warnings. +The default value of this option is true, so that by default, visibility +checking is done. + +#### `--output_filter=\{regex\}` + +The `--output_filter` option will only show build and compilation +warnings for targets that match the regular expression. If a target does not +match the given regular expression and its execution succeeds, its standard +output and standard error are thrown away. + +Here are some typical values for this option: + +| Option | Description | +|--------|-------------| +| `--output_filter='^//(first/project\|second/project):'` | Show the output for the specified packages. | +| `--output_filter='^//((?!(first/bad_project\|second/bad_project):).)*$'` | Don't show output for the specified packages. | +| `--output_filter=` | Show everything. | +| `--output_filter=DONT_MATCH_ANYTHING` | Show nothing. | + +### Tool flags + +These options control which options Bazel will pass to other tools. + +#### `--copt=\{cc-option\}` + +This option takes an argument which is to be passed to the compiler. +The argument will be passed to the compiler whenever it is invoked +for preprocessing, compiling, and/or assembling C, C++, or +assembler code. It will not be passed when linking. + +This option can be used multiple times. For example: + +``` + % bazel build --copt="-g0" --copt="-fpic" //foo +``` + +will compile the `foo` library without debug tables, generating +position-independent code. + +Note: Changing `--copt` settings will force a recompilation +of all affected object files. Also note that copts values listed in specific +cc_library or cc_binary build rules will be placed on the compiler command line +_after_ these options. + +Warning: C++-specific options (such as `-fno-implicit-templates`) +should be specified in `--cxxopt`, not in +`--copt`. Likewise, C-specific options (such as -Wstrict-prototypes) +should be specified in `--conlyopt`, not in `copt`. +Similarly, compiler options that only have an +effect at link time (such as `-l`) should be specified in +`--linkopt`, not in `--copt`. + +#### `--host_copt=\{cc-option\}` + +This option takes an argument which is to be passed to the compiler for source files +that are compiled in the exec configuration. This is analogous to +the [`--copt`](#copt) option, but applies only to the +exec configuration. + +#### `--host_conlyopt=\{cc-option\}` + +This option takes an argument which is to be passed to the compiler for C source files +that are compiled in the exec configuration. This is analogous to +the [`--conlyopt`](#cconlyopt) option, but applies only +to the exec configuration. + +#### `--host_cxxopt=\{cc-option\}` + +This option takes an argument which is to be passed to the compiler for C++ source files +that are compiled in the exec configuration. This is analogous to +the [`--cxxopt`](#cxxopt) option, but applies only to the +exec configuration. + +#### `--host_linkopt=\{linker-option\}` + +This option takes an argument which is to be passed to the linker for source files +that are compiled in the exec configuration. This is analogous to +the [`--linkopt`](#linkopt) option, but applies only to +the exec configuration. + +#### `--conlyopt=\{cc-option\}` + +This option takes an argument which is to be passed to the compiler when compiling C source files. + +This is similar to `--copt`, but only applies to C compilation, +not to C++ compilation or linking. So you can pass C-specific options +(such as `-Wno-pointer-sign`) using `--conlyopt`. + +Note: copts parameters listed in specific cc_library or cc_binary build rules +are placed on the compiler command line _after_ these options. + +#### `--cxxopt=\{cc-option\}` + +This option takes an argument which is to be passed to the compiler when +compiling C++ source files. + +This is similar to `--copt`, but only applies to C++ compilation, +not to C compilation or linking. So you can pass C++-specific options +(such as `-fpermissive` or `-fno-implicit-templates`) using `--cxxopt`. + +For example: + +``` + % bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code +``` + +Note: copts parameters listed in specific cc_library or cc_binary build rules +are placed on the compiler command line _after_ these options. + +#### `--linkopt=\{linker-option\}` + +This option takes an argument which is to be passed to the compiler when linking. + +This is similar to `--copt`, but only applies to linking, +not to compilation. So you can pass compiler options that only make sense +at link time (such as `-lssp` or `-Wl,--wrap,abort`) +using `--linkopt`. For example: + +``` + % bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code +``` + +Build rules can also specify link options in their attributes. This option's +settings always take precedence. Also see +[cc_library.linkopts](/reference/be/c-cpp#cc_library.linkopts). + +#### `--strip (always|never|sometimes)` + +This option determines whether Bazel will strip debugging information from +all binaries and shared libraries, by invoking the linker with the `-Wl,--strip-debug` option. +`--strip=always` means always strip debugging information. +`--strip=never` means never strip debugging information. +The default value of `--strip=sometimes` means strip if the `--compilation_mode` +is `fastbuild`. + +``` + % bazel build --strip=always //foo:bar +``` + +will compile the target while stripping debugging information from all generated +binaries. + +Note: If you want debugging information, it's not enough to disable stripping; +you also need to make sure that the debugging information was generated by the +compiler, which you can do by using either `-c dbg` or `--copt -g`. + +Bazel's `--strip` option corresponds with ld's `--strip-debug` option: +it only strips debugging information. If for some reason you want to strip _all_ symbols, +not just _debug_ symbols, you would need to use ld's `--strip-all` option, +which you can do by passing `--linkopt=-Wl,--strip-all` to Bazel. Also be +aware that setting Bazel's `--strip` flag will override +`--linkopt=-Wl,--strip-all`, so you should only set one or the other. + +If you are only building a single binary and want all symbols stripped, you could also +pass `--stripopt=--strip-all` and explicitly build the +`//foo:bar.stripped` version of the target. As described in the section on +`--stripopt`, this applies a strip action after the final binary is +linked rather than including stripping in all of the build's link actions. + +#### `--stripopt=\{strip-option\}` + +This is an additional option to pass to the `strip` command when generating +a [`*.stripped` binary](/reference/be/c-cpp#cc_binary_implicit_outputs). The default +is `-S -p`. This option can be used multiple times. + +Note: `--stripopt` does not apply to the stripping of the main +binary with `[--strip](#flag--strip)=(always|sometimes)`. + +#### `--fdo_instrument=\{profile-output-dir\}` + +The `--fdo_instrument` option enables the generation of +FDO (feedback directed optimization) profile output when the +built C/C++ binary is executed. For GCC, the argument provided is used as a +directory prefix for a per-object file directory tree of .gcda files +containing profile information for each .o file. + +Once the profile data tree has been generated, the profile tree +should be zipped up, and provided to the +`--fdo_optimize=\{profile-zip\}` +Bazel option to enable the FDO-optimized compilation. + +For the LLVM compiler the argument is also the directory under which the raw LLVM profile +data file(s) is dumped. For example: +`--fdo_instrument={/path/to/rawprof/dir/}`. + +The options `--fdo_instrument` and `--fdo_optimize` cannot be used at the same time. + +#### `--fdo_optimize=\{profile-zip\}` + +The `--fdo_optimize` option enables the use of the +per-object file profile information to perform FDO (feedback +directed optimization) optimizations when compiling. For GCC, the argument +provided is the zip file containing the previously-generated file tree +of .gcda files containing profile information for each .o file. + +Alternatively, the argument provided can point to an auto profile +identified by the extension .afdo. + +Note: This option also accepts labels that resolve to source files. You +may need to add an `exports_files` directive to the corresponding package to +make the file visible to Bazel. + +For the LLVM compiler the argument provided should point to the indexed LLVM +profile output file prepared by the llvm-profdata tool, and should have a .profdata +extension. + +The options `--fdo_instrument` and `--fdo_optimize` cannot be used at the same time. + +#### `--java_language_version=\{version\}` + +This option specifies the version of Java sources. For example: + +``` + % bazel build --java_language_version=8 java/com/example/common/foo:all +``` + +compiles and allows only constructs compatible with Java 8 specification. +Default value is 11. --> +Possible values are: 8, 9, 10, 11, 17, and 21 and may be extended by +registering custom Java toolchains using `default_java_toolchain`. + +#### `--tool_java_language_version=\{version\}` + +The Java language version used to build tools that are executed during a build. +Default value is 11. + +#### `--java_runtime_version=\{version\}` + +This option specifies the version of JVM to use to execute the code and run the tests. For +example: + +``` + % bazel run --java_runtime_version=remotejdk_11 java/com/example/common/foo:java_application +``` + +downloads JDK 11 from a remote repository and run the Java application using it. + +Default value is `local_jdk`. +Possible values are: `local_jdk`, `local_jdk_\{version\}`, +`remotejdk_11`, `remotejdk_17`, and `remotejdk_21`. +You can extend the values by registering custom JVM using either +`local_java_repository` or `remote_java_repository` repository rules. + +#### `--tool_java_runtime_version=\{version\}` + +The version of JVM used to execute tools that are needed during a build. +Default value is `remotejdk_11`. + +#### `--jvmopt=\{jvm-option\}` + +This option allows option arguments to be passed to the Java VM. It can be used +with one big argument, or multiple times with individual arguments. For example: + +``` + % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all +``` + +will use the server VM for launching all Java binaries and set the +startup heap size for the VM to 256 MB. + +#### `--javacopt=\{javac-option\}` + +This option allows option arguments to be passed to javac. It can be used +with one big argument, or multiple times with individual arguments. For example: + +``` + % bazel build --javacopt="-g:source,lines" //myprojects:prog +``` + +will rebuild a java_binary with the javac default debug info +(instead of the bazel default). + +The option is passed to javac after the Bazel built-in default options for +javac and before the per-rule options. The last specification of +any option to javac wins. The default options for javac are: + +``` + -source 8 -target 8 -encoding UTF-8 +``` + +Note: Changing `--javacopt` settings will force a recompilation +of all affected classes. Also note that javacopts parameters listed in +specific java_library or java_binary build rules will be placed on the javac +command line _after_ these options. + +#### `--strict_java_deps (default|strict|off|warn|error)` + +This option controls whether javac checks for missing direct dependencies. +Java targets must explicitly declare all directly used targets as +dependencies. This flag instructs javac to determine the jars actually used +for type checking each java file, and warn/error if they are not the output +of a direct dependency of the current target. + +* `off` means checking is disabled. +* `warn` means javac will generate standard java warnings of + type `[strict]` for each missing direct dependency. +* `default`, `strict` and `error` all + mean javac will generate errors instead of warnings, causing the current + target to fail to build if any missing direct dependencies are found. + This is also the default behavior when the flag is unspecified. + +### Build semantics + +These options affect the build commands and/or the output file contents. + +#### `--compilation_mode (fastbuild|opt|dbg)` (-c) + +The `--compilation_mode` option (often shortened to `-c`, +especially `-c opt`) takes an argument of `fastbuild`, `dbg` +or `opt`, and affects various C/C++ code-generation +options, such as the level of optimization and the completeness of +debug tables. Bazel uses a different output directory for each +different compilation mode, so you can switch between modes without +needing to do a full rebuild _every_ time. + +* `fastbuild` means build as fast as possible: + generate minimal debugging information (`-gmlt + -Wl,-S`), and don't optimize. This is the + default. Note: `-DNDEBUG` will **not** be set. +* `dbg` means build with debugging enabled (`-g`), + so that you can use gdb (or another debugger). +* `opt` means build with optimization enabled and + with `assert()` calls disabled (`-O2 -DNDEBUG`). + Debugging information will not be generated in `opt` mode + unless you also pass `--copt -g`. + +#### `--cpu=\{cpu\}` + +This option specifies the target CPU architecture to be used for +the compilation of binaries during the build. + +Note: A particular combination of crosstool version, compiler version, +and target CPU is allowed only if it has been specified in the currently +used CROSSTOOL file. + +#### `--action_env=\{VAR=VALUE\}` + +Specifies the set of environment variables available during the execution of all actions. +Variables can be either specified by name, in which case the value will be taken from the +invocation environment, or by the `name=value` pair which sets the value independent of the +invocation environment. + +This `--action_env` flag can be specified multiple times. If a value is assigned to the same +variable across multiple `--action_env` flags, the latest assignment wins. + +#### `--experimental_action_listener=\{label\}` + +Warning: Extra actions are deprecated. Use +[aspects](/extending/aspects) +instead. + +The `experimental_action_listener` option instructs Bazel to use +details from the [`action_listener`](/reference/be/extra-actions#action_listener) rule specified by \{label\} to +insert [`extra_actions`](/reference/be/extra-actions#extra_action) into the build graph. + +#### `--[no]experimental_extra_action_top_level_only` + +Warning: Extra actions are deprecated. Use +[aspects](/extending/aspects) instead. + +If this option is set to true, extra actions specified by the +[ `--experimental_action_listener`](#experimental-action-listener) command +line option will only be scheduled for top level targets. + +#### `--experimental_extra_action_filter=\{regex\}` + +Warning: Extra actions are deprecated. Use +[aspects](/extending/aspects) instead. + +The `experimental_extra_action_filter` option instructs Bazel to +filter the set of targets to schedule `extra_actions` for. + +This flag is only applicable in combination with the +[`--experimental_action_listener`](#experimental-action-listener) flag. + +By default all `extra_actions` in the transitive closure of the +requested targets-to-build get scheduled for execution. +`--experimental_extra_action_filter` will restrict scheduling to +`extra_actions` of which the owner's label matches the specified +regular expression. + +The following example will limit scheduling of `extra_actions` +to only apply to actions of which the owner's label contains '/bar/': + +```% bazel build --experimental_action_listener=//test:al //foo/... \ + --experimental_extra_action_filter=.*/bar/.* +``` + +#### `--host_cpu=\{cpu\}` + +This option specifies the name of the CPU architecture that should be +used to build host tools. + +#### `--android_platforms={platform[,platform]*}` + +The platforms to build the transitive `deps` of +`android_binary` rules (specifically for native dependencies like C++). For +example, if a `cc_library` appears in the transitive `deps` of an +`android_binary` rule it is be built once for each platform specified with +`--android_platforms` for the `android_binary` rule, and included in the final +output. + +There is no default value for this flag: a custom Android platform must be +defined and used. + +One `.so` file is created and packaged in the APK for each platform specified +with `--android_platforms`. The `.so` file's name prefixes the name of the +`android_binary` rule with "lib". For example, if the name of the +`android_binary` is "foo", then the file is `libfoo.so`. + +#### `--per_file_copt={[+-]regex[,[+-]regex]...@option[,option]...}` + +When present, any C++ file with a label or an execution path matching one of the inclusion regex +expressions and not matching any of the exclusion expressions will be built +with the given options. The label matching uses the canonical form of the label +(i.e //`package`:`label_name`). + +The execution path is the relative path to your workspace directory including the base name +(including extension) of the C++ file. It also includes any platform dependent prefixes. + +Note: If only one of the label or the execution path matches the options will be used. + +To match the generated files (such as genrule outputs) +Bazel can only use the execution path. In this case the regexp shouldn't start with '//' +since that doesn't match any execution paths. Package names can be used like this: +`--per_file_copt=base/.*\.pb\.cc@-g0`. This will match every +`.pb.cc` file under a directory called `base`. + +This option can be used multiple times. + +The option is applied regardless of the compilation mode used. For example, it is possible +to compile with `--compilation_mode=opt` and selectively compile some +files with stronger optimization turned on, or with optimization disabled. + +**Caveat**: If some files are selectively compiled with debug symbols the symbols +might be stripped during linking. This can be prevented by setting +`--strip=never`. + +**Syntax**: `[+-]regex[,[+-]regex]...@option[,option]...` Where +`regex` stands for a regular expression that can be prefixed with +a `+` to identify include patterns and with `-` to identify +exclude patterns. `option` stands for an arbitrary option that is passed +to the C++ compiler. If an option contains a `,` it has to be quoted like so +`\,`. Options can also contain `@`, since only the first +`@` is used to separate regular expressions from options. + +**Example**: +`--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs` +adds the `-O0` and the `-fprofile-arcs` options to the command +line of the C++ compiler for all `.cc` files in `//foo/` except `file.cc`. + +#### `--dynamic_mode=\{mode\}` + +Determines whether C++ binaries will be linked dynamically, interacting with +the [linkstatic attribute](/reference/be/c-cpp#cc_binary.linkstatic) on build rules. + +Modes: + +* `default`: Allows bazel to choose whether to link dynamically. + See [linkstatic](/reference/be/c-cpp#cc_binary.linkstatic) for more + information. +* `fully`: Links all targets dynamically. This will speed up + linking time, and reduce the size of the resulting binaries. +* `off`: Links all targets in + [mostly static](/reference/be/c-cpp#cc_binary.linkstatic) mode. + If `-static` is set in linkopts, targets will change to fully static. + +#### `--fission (yes|no|[dbg][,opt][,fastbuild])` + +Enables [Fission](https://gcc.gnu.org/wiki/DebugFission), +which writes C++ debug information to dedicated .dwo files instead of .o files, where it would +otherwise go. This substantially reduces the input size to links and can reduce link times. + +When set to `[dbg][,opt][,fastbuild]` (example: +`--fission=dbg,fastbuild`), Fission is enabled +only for the specified set of compilation modes. This is useful for bazelrc +settings. When set to `yes`, Fission is enabled +universally. When set to `no`, Fission is disabled +universally. Default is no. + +#### `--force_ignore_dash_static` + +If this flag is set, any `-static` options in linkopts of +`cc_*` rules BUILD files are ignored. This is only intended as a +workaround for C++ hardening builds. + +#### `--[no]force_pic` + +If enabled, all C++ compilations produce position-independent code ("-fPIC"), +links prefer PIC pre-built libraries over non-PIC libraries, and links produce +position-independent executables ("-pie"). Default is disabled. + +Note: Dynamically linked binaries (for example `--dynamic_mode fully`) +generate PIC code regardless of this flag's setting. So this flag is for cases +where users want PIC code explicitly generated for static links. + +#### `--android_resource_shrinking` + +Selects whether to perform resource shrinking for android_binary rules. Sets the default for the +[shrink_resources attribute](/reference/be/android#android_binary.shrink_resources) on +android_binary rules; see the documentation for that rule for further details. Defaults to off. + +#### `--custom_malloc=\{malloc-library-target\}` + +When specified, always use the given malloc implementation, overriding all +`malloc="target"` attributes, including in those targets that use the +default (by not specifying any `malloc`). + +#### `--crosstool_top=\{label\}` + +This option specifies the location of the crosstool compiler suite +to be used for all C++ compilation during a build. Bazel will look in that +location for a CROSSTOOL file and uses that to automatically determine +settings for `--compiler`. + +#### `--host_crosstool_top=\{label\}` + +If not specified, Bazel uses the value of `--crosstool_top` to compile +code in the exec configuration, such as tools run during the build. The main purpose of this flag +is to enable cross-compilation. + +#### `--apple_crosstool_top=\{label\}` + +The crosstool to use for compiling C/C++ rules in the transitive `deps` of +objc_*, ios__*, and apple_* rules. For those targets, this flag overwrites +`--crosstool_top`. + +#### `--compiler=\{version\}` + +This option specifies the C/C++ compiler version (such as `gcc-4.1.0`) +to be used for the compilation of binaries during the build. If you want to +build with a custom crosstool, you should use a CROSSTOOL file instead of +specifying this flag. + +Note: Only certain combinations of crosstool version, compiler version, +and target CPU are allowed. + +#### `--android_sdk=\{label\}` + +Deprecated. This shouldn't be directly specified. + +This option specifies the Android SDK/platform toolchain +and Android runtime library that will be used to build any Android-related +rule. + +The Android SDK will be automatically selected if an `android_sdk_repository` +rule is defined in the WORKSPACE file. + +#### `--java_toolchain=\{label\}` + +No-op. Kept only for backwards compatibility. + +#### `--host_java_toolchain=\{label\}` + +No-op. Kept only for backwards compatibility. + +#### `--javabase=(\{label\})` + +No-op. Kept only for backwards compatibility. + +#### `--host_javabase=\{label\}` + +No-op. Kept only for backwards compatibility. + +### Execution strategy + +These options affect how Bazel will execute the build. +They should not have any significant effect on the output files +generated by the build. Typically their main effect is on the +speed of the build. + +#### `--spawn_strategy={strategy}` + +This option controls where and how commands are executed. + +* `standalone` causes commands to be executed as local subprocesses. This value is + deprecated. Please use `local` instead. +* `sandboxed` causes commands to be executed inside a sandbox on the local machine. + This requires that all input files, data dependencies and tools are listed as direct + dependencies in the `srcs`, `data` and `tools` attributes. + Bazel enables local sandboxing by default, on systems that support sandboxed execution. +* `local` causes commands to be executed as local subprocesses. +* `worker` causes commands to be executed using a persistent worker, if available. +* `docker` causes commands to be executed inside a docker sandbox on the local machine. + This requires that docker is installed. +* `remote` causes commands to be executed remotely; this is only available if a + remote executor has been configured separately. + +#### `--strategy {mnemonic}={strategy}` + +This option controls where and how commands are executed, overriding the +[--spawn_strategy](#spawn-strategy) (and +[--genrule_strategy](#genrule-strategy) with mnemonic +Genrule) on a per-mnemonic basis. See +[--spawn_strategy](#spawn-strategy) for the supported +strategies and their effects. + +#### `--strategy_regexp={=}` + +This option specifies which strategy should be used to execute commands that have descriptions +matching a certain `regex_filter`. See +[--per_file_copt](#per-file-copt) for details on +regex_filter matching. See +[--spawn_strategy](#spawn-strategy) for the supported +strategies and their effects. + +The last `regex_filter` that matches the description is used. This option overrides +other flags for specifying strategy. + +* Example: `--strategy_regexp=//foo.*\\.cc,-//foo/bar=local` means to run actions using + `local` strategy if their descriptions match //foo.*.cc but not //foo/bar. +* Example: + `--strategy_regexp='Compiling.*/bar=local' --strategy_regexp=Compiling=sandboxed` + runs 'Compiling //foo/bar/baz' with the `sandboxed` strategy, but reversing + the order runs it with `local`. +* Example: `--strategy_regexp='Compiling.*/bar=local,sandboxed'` runs + 'Compiling //foo/bar/baz' with the `local` strategy and falls back to + `sandboxed` if it fails. + +#### `--genrule_strategy={strategy}` + +This is a deprecated short-hand for `--strategy=Genrule={strategy}`. + +#### `--jobs={n}` (-j) + +This option, which takes an integer argument, specifies a limit on +the number of jobs that should be executed concurrently during the +execution phase of the build. + +Note : The number of concurrent jobs that Bazel will run +is determined not only by the `--jobs` setting, but also +by Bazel's scheduler, which tries to avoid running concurrent jobs +that will use up more resources (RAM or CPU) than are available, +based on some (very crude) estimates of the resource consumption +of each job. The behavior of the scheduler can be controlled by +the `--local_ram_resources` option. + +#### `--progress_report_interval={n}` + +Bazel periodically prints a progress report on jobs that are not +finished yet (such as long running tests). This option sets the +reporting frequency, progress will be printed every `n` +seconds. + +The default is 0, that means an incremental algorithm: the first +report will be printed after 10 seconds, then 30 seconds and after +that progress is reported once every minute. + +When bazel is using cursor control, as specified by +[`--curses`](#curses), progress is reported every second. + +#### `--local_{ram,cpu}_resources {resources or resource expression}` + +These options specify the amount of local resources (RAM in MB and number of CPU logical cores) +that Bazel can take into consideration when scheduling build and test activities to run locally. They take +an integer, or a keyword (HOST_RAM or HOST_CPUS) optionally followed by `[-|*`float`]` +(for example, `--local_cpu_resources=2`, `--local_ram_resources=HOST_RAM*.5`, +`--local_cpu_resources=HOST_CPUS-1`). +The flags are independent; one or both may be set. By default, Bazel estimates +the amount of RAM and number of CPU cores directly from the local system's configuration. + +#### `--[no]build_runfile_links` + +This option, which is enabled by default, specifies whether the runfiles +symlinks for tests and binaries should be built in the output directory. +Using `--nobuild_runfile_links` can be useful +to validate if all targets compile without incurring the overhead +for building the runfiles trees. + +When tests (or applications) are executed, their run-time data +dependencies are gathered together in one place. Within Bazel's +output tree, this "runfiles" tree is typically rooted as a sibling of +the corresponding binary or test. +During test execution, runfiles may be accessed using paths of the form +`$TEST_SRCDIR/{canonical_repo_name}/{packagename}/{filename}`. +The runfiles tree ensures that tests have access to all the files +upon which they have a declared dependence, and nothing more. By +default, the runfiles tree is implemented by constructing a set of +symbolic links to the required files. As the set of links grows, so +does the cost of this operation, and for some large builds it can +contribute significantly to overall build time, particularly because +each individual test (or application) requires its own runfiles tree. + +#### `--[no]build_runfile_manifests` + +This option, which is enabled by default, specifies whether runfiles manifests +should be written to the output tree. +Disabling it implies `--nobuild_runfile_links`. + +It can be disabled when executing tests remotely, as runfiles trees will +be created remotely from in-memory manifests. + +#### `--[no]discard_analysis_cache` + +When this option is enabled, Bazel will discard the analysis cache +right before execution starts, thus freeing up additional memory +(around 10%) for the [execution phase](/run/build#execution). +The drawback is that further incremental builds will be slower. See also +[memory-saving mode](/configure/memory). + +#### `--[no]keep_going` (-k) + +As in GNU Make, the execution phase of a build stops when the first +error is encountered. Sometimes it is useful to try to build as +much as possible even in the face of errors. This option enables +that behavior, and when it is specified, the build will attempt to +build every target whose prerequisites were successfully built, but +will ignore errors. + +While this option is usually associated with the execution phase of +a build, it also affects the analysis phase: if several targets are +specified in a build command, but only some of them can be +successfully analyzed, the build will stop with an error +unless `--keep_going` is specified, in which case the +build will proceed to the execution phase, but only for the targets +that were successfully analyzed. + +#### `--[no]use_ijars` + +This option changes the way `java_library` targets are +compiled by Bazel. Instead of using the output of a +`java_library` for compiling dependent +`java_library` targets, Bazel will create interface jars +that contain only the signatures of non-private members (public, +protected, and default (package) access methods and fields) and use +the interface jars to compile the dependent targets. This makes it +possible to avoid recompilation when changes are only made to +method bodies or private members of a class. + +Note: Using `--use_ijars` might give you a different +error message when you are accidentally referring to a non visible +member of another class: Instead of getting an error that the member +is not visible you will get an error that the member does not exist. +Changing the `--use_ijars` setting will force a recompilation of all affected +classes. + +#### `--[no]interface_shared_objects` + +This option enables _interface shared objects_, which makes binaries and +other shared libraries depend on the _interface_ of a shared object, +rather than its implementation. When only the implementation changes, Bazel +can avoid rebuilding targets that depend on the changed shared library +unnecessarily. + +### Output selection + +These options determine what to build or test. + +#### `--[no]build` + +This option causes the execution phase of the build to occur; it is +on by default. When it is switched off, the execution phase is +skipped, and only the first two phases, loading and analysis, occur. + +This option can be useful for validating BUILD files and detecting +errors in the inputs, without actually building anything. + +#### `--[no]build_tests_only` + +If specified, Bazel will build only what is necessary to run the `*_test` +and `test_suite` rules that were not filtered due to their +[size](#test-size-filters), +[timeout](#test-timeout-filters), +[tag](#test-tag-filters), or +[language](#test-lang-filters). +If specified, Bazel will ignore other targets specified on the command line. +By default, this option is disabled and Bazel will build everything +requested, including `*_test` and `test_suite` rules that are filtered out from +testing. This is useful because running +`bazel test --build_tests_only foo/...` may not detect all build +breakages in the `foo` tree. + +#### `--[no]check_up_to_date` + +This option causes Bazel not to perform a build, but merely check +whether all specified targets are up-to-date. If so, the build +completes successfully, as usual. However, if any files are out of +date, instead of being built, an error is reported and the build +fails. This option may be useful to determine whether a build has +been performed more recently than a source edit (for example, for pre-submit +checks) without incurring the cost of a build. + +See also [`--check_tests_up_to_date`](#check-tests-up-to-date). + +#### `--[no]compile_one_dependency` + +Compile a single dependency of the argument files. This is useful for +syntax checking source files in IDEs, for example, by rebuilding a single +target that depends on the source file to detect errors as early as +possible in the edit/build/test cycle. This argument affects the way all +non-flag arguments are interpreted: each argument must be a +file target label or a plain filename relative to the current working +directory, and one rule that depends on each source filename is built. For +C++ and Java +sources, rules in the same language space are preferentially chosen. For +multiple rules with the same preference, the one that appears first in the +BUILD file is chosen. An explicitly named target pattern which does not +reference a source file results in an error. + +#### `--save_temps` + +The `--save_temps` option causes temporary outputs from the compiler to be +saved. These include .s files (assembler code), .i (preprocessed C) and .ii +(preprocessed C++) files. These outputs are often useful for debugging. Temps will only be +generated for the set of targets specified on the command line. + +Note: 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, +you may need to also use `--keep_going` so that Bazel will still try to +produce the preprocessed files after the compilation fails. + +The `--save_temps` flag currently works only for cc_* rules. + +To ensure that Bazel prints the location of the additional output files, check that +your [`--show_result {n}`](#show-result) +setting is high enough. + +#### `--build_tag_filters={tag[,tag]*}` + +If specified, Bazel will build only targets that have at least one required tag +(if any of them are specified) and does not have any excluded tags. Build tag +filter is specified as comma delimited list of tag keywords, optionally +preceded with '-' sign used to denote excluded tags. Required tags may also +have a preceding '+' sign. + +When running tests, Bazel ignores `--build_tag_filters` for test targets, +which are built and run even if they do not match this filter. To avoid building them, filter +test targets using `--test_tag_filters` or by explicitly excluding them. + +#### `--test_size_filters={size[,size]*}` + +If specified, Bazel will test (or build if `--build_tests_only` +is also specified) only test targets with the given size. Test size filter +is specified as comma delimited list of allowed test size values (small, +medium, large or enormous), optionally preceded with '-' sign used to denote +excluded test sizes. For example, + +``` + % bazel test --test_size_filters=small,medium //foo:all +``` + +and + +``` + % bazel test --test_size_filters=-large,-enormous //foo:all +``` + +will test only small and medium tests inside //foo. + +By default, test size filtering is not applied. + +#### `--test_timeout_filters={timeout[,timeout]*}` + +If specified, Bazel will test (or build if `--build_tests_only` +is also specified) only test targets with the given timeout. Test timeout filter +is specified as comma delimited list of allowed test timeout values (short, +moderate, long or eternal), optionally preceded with '-' sign used to denote +excluded test timeouts. See [--test_size_filters](#test-size-filters) +for example syntax. + +By default, test timeout filtering is not applied. + +#### `--test_tag_filters={tag[,tag]*}` + +If specified, Bazel will test (or build if `--build_tests_only` +is also specified) only test targets that have at least one required tag +(if any of them are specified) and does not have any excluded tags. Test tag +filter is specified as comma delimited list of tag keywords, optionally +preceded with '-' sign used to denote excluded tags. Required tags may also +have a preceding '+' sign. + +For example, + +``` + % bazel test --test_tag_filters=performance,stress,-flaky //myproject:all +``` + +will test targets that are tagged with either `performance` or +`stress` tag but are **not** tagged with the `flaky` tag. + +By default, test tag filtering is not applied. Note that you can also filter +on test's `size` and `local` tags in +this manner. + +#### `--test_lang_filters={string[,string]*}` + +Specifies a comma-separated list of strings referring to names of test rule +classes. To refer to the rule class `foo_test`, use the string "foo". Bazel will +test (or build if `--build_tests_only` is also specified) only +targets of the referenced rule classes. To instead exclude those targets, use +the string "-foo". For example, + +``` + % bazel test --test_lang_filters=foo,bar //baz/... +``` +

+ will test only targets that are instances of `foo_test` or `bar_test` in + `//baz/...`, while +

+``` + % bazel test --test_lang_filters=-foo,-bar //baz/... +``` +

+ will test all the targets in `//baz/...` except for the `foo_test` and + `bar_test` instances. +

+ +Tip: You can use `bazel query --output=label_kind "//p:t"` to +learn the rule class name of the target `//p:t`. And you can +look at the pair of instantiation stacks in the output of +`bazel query --output=build "//p:t"` to learn why that target +is an instance of that rule class. + +Warning: The option name "--test_lang_filter" is vestigal and is therefore +unfortunately misleading; don't make assumptions about the semantics based on +the name. + +#### `--test_filter={filter-expression}` + +Specifies a filter that the test runner may use to pick a subset of tests for +running. All targets specified in the invocation are built, but depending on +the expression only some of them may be executed; in some cases, only certain +test methods are run. + +The particular interpretation of {filter-expression} is up to +the test framework responsible for running the test. It may be a glob, +substring, or regexp. `--test_filter` is a convenience +over passing different `--test_arg` filter arguments, +but not all frameworks support it. + +### Verbosity + +These options control the verbosity of Bazel's output, +either to the terminal, or to additional log files. + +#### `--explain={logfile}` + +This option, which requires a filename argument, causes the +dependency checker in `bazel build`'s execution phase to +explain, for each build step, either why it is being executed, or +that it is up-to-date. The explanation is written +to _logfile_. + +If you are encountering unexpected rebuilds, this option can help to +understand the reason. Add it to your `.bazelrc` so that +logging occurs for all subsequent builds, and then inspect the log +when you see an execution step executed unexpectedly. This option +may carry a small performance penalty, so you might want to remove +it when it is no longer needed. + +#### `--verbose_explanations` + +This option increases the verbosity of the explanations generated +when the [--explain](#explain) option is enabled. + +In particular, if verbose explanations are enabled, +and an output file is rebuilt because the command used to +build it has changed, then the output in the explanation file will +include the full details of the new command (at least for most +commands). + +Using this option may significantly increase the length of the +generated explanation file and the performance penalty of using +`--explain`. + +If `--explain` is not enabled, then +`--verbose_explanations` has no effect. + +#### `--profile={file}` + +This option, which takes a filename argument, causes Bazel to write +profiling data into a file. The data then can be analyzed or parsed using the +`bazel analyze-profile` command. The Build profile can be useful in +understanding where Bazel's `build` command is spending its time. + +#### `--[no]show_loading_progress` + +This option causes Bazel to output package-loading progress +messages. If it is disabled, the messages won't be shown. + +#### `--[no]show_progress` + +This option causes progress messages to be displayed; it is on by +default. When disabled, progress messages are suppressed. + +#### `--show_progress_rate_limit={n}` + +This option causes bazel to display at most one progress message per `n` seconds, +where {n} is a real number. +The default value for this option is 0.02, meaning bazel will limit the progress +messages to one per every 0.02 seconds. + +#### `--show_result={n}` + +This option controls the printing of result information at the end +of a `bazel build` command. By default, if a single +build target was specified, Bazel prints a message stating whether +or not the target was successfully brought up-to-date, and if so, +the list of output files that the target created. If multiple +targets were specified, result information is not displayed. + +While the result information may be useful for builds of a single +target or a few targets, for large builds (such as an entire top-level +project tree), this information can be overwhelming and distracting; +this option allows it to be controlled. `--show_result` +takes an integer argument, which is the maximum number of targets +for which full result information should be printed. By default, +the value is 1. Above this threshold, no result information is +shown for individual targets. Thus zero causes the result +information to be suppressed always, and a very large value causes +the result to be printed always. + +Users may wish to choose a value in-between if they regularly +alternate between building a small group of targets (for example, +during the compile-edit-test cycle) and a large group of targets +(for example, when establishing a new workspace or running +regression tests). In the former case, the result information is +very useful whereas in the latter case it is less so. As with all +options, this can be specified implicitly via +the [`.bazelrc`](/run/bazelrc) file. + +The files are printed so as to make it easy to copy and paste the +filename to the shell, to run built executables. The "up-to-date" +or "failed" messages for each target can be easily parsed by scripts +which drive a build. + +#### `--sandbox_debug` + +This option causes Bazel to print extra debugging information when using sandboxing for action +execution. This option also preserves sandbox directories, so that the files visible to actions +during execution can be examined. + +#### `--subcommands` (`-s`) + +This option causes Bazel's execution phase to print the full command line +for each command prior to executing it. + +``` + >>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world'] + (cd /home/johndoe/.cache/bazel/_bazel_johndoe/4c084335afceb392cfbe7c31afee3a9f/bazel && \ + exec env - \ + /usr/bin/gcc -o bazel-out/local-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes -Wl,-S -Wl,@bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world-2.params) +``` + +Where possible, commands are printed in a Bourne shell compatible syntax, +so that they can be easily copied and pasted to a shell command prompt. +(The surrounding parentheses are provided to protect your shell from the +`cd` and `exec` calls; be sure to copy them!) +However some commands are implemented internally within Bazel, such as +creating symlink trees. For these there's no command line to display. + +`--subcommands=pretty_print` may be passed to print +the arguments of the command as a list rather than as a single line. This may +help make long command lines more readable. + +See also [--verbose_failures](#verbose-failures), below. + +For logging subcommands to a file in a tool-friendly format, see +[--execution_log_json_file](/reference/command-line-reference#flag--execution_log_json_file) +and +[--execution_log_binary_file](/reference/command-line-reference#flag--execution_log_binary_file). + +#### `--verbose_failures` + +This option causes Bazel's execution phase to print the full command line +for commands that failed. This can be invaluable for debugging a +failing build. + +Failing commands are printed in a Bourne shell compatible syntax, suitable +for copying and pasting to a shell prompt. + +### Workspace status + +Use these options to "stamp" Bazel-built binaries: to embed additional information into the +binaries, such as the source control revision or other workspace-related information. You can use +this mechanism with rules that support the `stamp` attribute, such as +`genrule`, `cc_binary`, and more. + +#### `--workspace_status_command={program}` + +This flag lets you specify a binary that Bazel runs before each build. The program can report +information about the status of the workspace, such as the current source control revision. + +The flag's value must be a path to a native program. On Linux/macOS this may be any executable. +On Windows this must be a native binary, typically an ".exe", ".bat", or a ".cmd" file. + +The program should print zero or more key/value pairs to standard output, one entry on each line, +then exit with zero (otherwise the build fails). The key names can be anything but they may only +use upper case letters and underscores. The first space after the key name separates it from the +value. The value is the rest of the line (including additional whitespaces). Neither the key nor +the value may span multiple lines. Keys must not be duplicated. + +Bazel partitions the keys into two buckets: "stable" and "volatile". (The names "stable" and +"volatile" are a bit counter-intuitive, so don't think much about them.) + +Bazel then writes the key-value pairs into two files: + +* `bazel-out/stable-status.txt` + contains all keys and values where the key's name starts with `STABLE_` +* `bazel-out/volatile-status.txt` + contains the rest of the keys and their values + +The contract is: + +* "stable" keys' values should change rarely, if possible. If the contents of + `bazel-out/stable-status.txt` + change, Bazel invalidates the actions that depend on them. In + other words, if a stable key's value changes, Bazel will rerun stamped actions. + Therefore the stable status should not contain things like timestamps, because they change all + the time, and would make Bazel rerun stamped actions with each build. + + Bazel always outputs the following stable keys: + * `BUILD_EMBED_LABEL`: value of `--embed_label` + * `BUILD_HOST`: the name of the host machine that Bazel is running on + * `BUILD_USER`: the name of the user that Bazel is running as +* "volatile" keys' values may change often. Bazel expects them to change all the time, like + timestamps do, and duly updates the + `bazel-out/volatile-status.txt` + file. In order to avoid + rerunning stamped actions all the time though, **Bazel pretends that the volatile file never + changes**. In other words, if the volatile status file is the only file whose contents has + changed, Bazel will not invalidate actions that depend on it. If other inputs of the actions + have changed, then Bazel reruns that action, and the action will see the updated volatile + status, but just the volatile status changing alone will not invalidate the action. + + Bazel always outputs the following volatile keys: + * `BUILD_TIMESTAMP`: time of the build in seconds since the Unix Epoch (the value + of `System.currentTimeMillis()` divided by a thousand) + * `FORMATTED_DATE`: time of the build Formatted as + `yyyy MMM d HH mm ss EEE`(for example 2023 Jun 2 01 44 29 Fri) in UTC. + +On Linux/macOS you can pass `--workspace_status_command=/bin/true` to +disable retrieving workspace status, because `true` does nothing, successfully (exits +with zero) and prints no output. On Windows you can pass the path of MSYS's `true.exe` +for the same effect. + +If the workspace status command fails (exits non-zero) for any reason, the build will fail. + +Example program on Linux using Git: + +``` +#!/bin/bash +echo "CURRENT_TIME $(date +%s)" +echo "RANDOM_HASH $(cat /proc/sys/kernel/random/uuid)" +echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)" +echo "STABLE_USER_NAME $USER" +``` + +Pass this program's path with `--workspace_status_command`, and the stable status file +will include the STABLE lines and the volatile status file will include the rest of the lines. + +#### `--[no]stamp` + +This option, in conjunction with the `stamp` rule attribute, controls whether to +embed build information in binaries. + +Stamping can be enabled or disabled explicitly on a per-rule basis using the +`stamp` attribute. Please refer to the Build Encyclopedia for details. When +a rule sets `stamp = -1` (the default for `*_binary` rules), this option +determines whether stamping is enabled. + +Bazel never stamps binaries that are built for the exec configuration, +regardless of this option or the `stamp` attribute. For rules that set `stamp = +0` (the default for `*_test` rules), stamping is disabled regardless of +`--[no]stamp`. Specifying `--stamp` does not force targets to be rebuilt if +their dependencies have not changed. + +Setting `--nostamp` is generally desireable for build performance, as it +reduces input volatility and maximizes build caching. + +### Platform + +Use these options to control the host and target platforms that configure how builds work, and to +control what execution platforms and toolchains are available to Bazel rules. + +Please see background information on [Platforms](/extending/platforms) and [Toolchains](/extending/toolchains). + +#### `--platforms={labels}` + +The labels of the platform rules describing the target platforms for the +current command. + +#### `--host_platform=\{label\}` + +The label of a platform rule that describes the host system. + +#### `--extra_execution_platforms={labels}` + +The platforms that are available as execution platforms to run actions. +Platforms can be specified by exact target, or as a target pattern. These +platforms will be considered before those declared in MODULE.bazel files by +[register_execution_platforms()](/rules/lib/globals/module#register_execution_platforms). +This option accepts a comma-separated list of platforms in order of priority. +If the flag is passed multiple times, the most recent overrides. + +#### `--extra_toolchains={labels}` + +The toolchain rules to be considered during toolchain resolution. Toolchains +can be specified by exact target, or as a target pattern. These toolchains will +be considered before those declared in MODULE.bazel files by +[register_toolchains()](/rules/lib/globals/module#register_toolchains). + +#### `--toolchain_resolution_debug=\{regex\}` + +Print debug information while finding toolchains if the toolchain type matches +the regex. Multiple regexes can be separated by commas. The regex can be +negated by using a `-` at the beginning. This might help developers +of Bazel or Starlark rules with debugging failures due to missing toolchains. + +### Miscellaneous + +#### `--flag_alias={alias_name=target_path}` + +A convenience flag used to bind longer Starlark build settings to a shorter name. For more +details, see the +[Starlark Configurations](/extending/config#using-build-setting-aliases). + +#### `--symlink_prefix={string}` + +Changes the prefix of the generated convenience symlinks. The +default value for the symlink prefix is `bazel-` which +will create the symlinks `bazel-bin`, `bazel-testlogs`, and +`bazel-genfiles`. + +If the symbolic links cannot be created for any reason, a warning is +issued but the build is still considered a success. In particular, +this allows you to build in a read-only directory or one that you have no +permission to write into. Any paths printed in informational +messages at the conclusion of a build will only use the +symlink-relative short form if the symlinks point to the expected +location; in other words, you can rely on the correctness of those +paths, even if you cannot rely on the symlinks being created. + +Some common values of this option: + +* **Suppress symlink creation:** + `--symlink_prefix=/` will cause Bazel to not + create or update any symlinks, including the `bazel-out` and + `bazel-` + symlinks. Use this option to suppress symlink creation entirely. + +* **Reduce clutter:** + `--symlink_prefix=.bazel/` will cause Bazel to create + symlinks called `bin` (etc) inside a hidden directory `.bazel`. + +#### `--platform_suffix={string}` + +Adds a suffix to the configuration short name, which is used to determine the +output directory. Setting this option to different values puts the files into +different directories, for example to improve cache hit rates for builds that +otherwise clobber each others output files, or to keep the output files around +for comparisons. + +#### `--default_visibility={(private|public)}` + +Temporary flag for testing bazel default visibility changes. Not intended for general use +but documented for completeness' sake. + +#### `--starlark_cpu_profile=_file_` + +This flag, whose value is the name of a file, causes Bazel to gather +statistics about CPU usage by all Starlark threads, +and write the profile, in [pprof](https://github.com/google/pprof) format, +to the named file. + +Use this option to help identify Starlark functions that +make loading and analysis slow due to excessive computation. For example: + +``` +$ bazel build --nobuild --starlark_cpu_profile=/tmp/pprof.gz my/project/... +$ pprof /tmp/pprof.gz +(pprof) top +Type: CPU +Time: Feb 6, 2020 at 12:06pm (PST) +Duration: 5.26s, Total samples = 3.34s (63.55%) +Showing nodes accounting for 3.34s, 100% of 3.34s total + flat flat% sum% cum cum% + 1.86s 55.69% 55.69% 1.86s 55.69% sort_source_files + 1.02s 30.54% 86.23% 1.02s 30.54% expand_all_combinations + 0.44s 13.17% 99.40% 0.44s 13.17% range + 0.02s 0.6% 100% 3.34s 100% sorted + 0 0% 100% 1.38s 41.32% my/project/main/BUILD + 0 0% 100% 1.96s 58.68% my/project/library.bzl + 0 0% 100% 3.34s 100% main +``` + +For different views of the same data, try the `pprof` commands `svg`, +`web`, and `list`. + +## Using Bazel for releases + +Bazel is used both by software engineers during the development +cycle, and by release engineers when preparing binaries for deployment +to production. This section provides a list of tips for release +engineers using Bazel. + +### Significant options + +When using Bazel for release builds, the same issues arise as for other scripts +that perform a build. For more details, see +[Call Bazel from scripts](/run/scripts). In particular, the following options +are strongly recommended: + +* [`--bazelrc=/dev/null`](/run/bazelrc) +* [`--nokeep_state_after_build`](/reference/command-line-reference#common_options-flag--keep_state_after_build) + +These options are also important: + +* [`--package_path`](#package-path) +* [`--symlink_prefix`](#symlink-prefix): + for managing builds for multiple configurations, + it may be convenient to distinguish each build + with a distinct identifier, such as "64bit" vs. "32bit". This option + differentiates the `bazel-bin` (etc.) symlinks. + +## Running tests + +To build and run tests with bazel, type `bazel test` followed by +the name of the test targets. + +By default, this command performs simultaneous build and test +activity, building all specified targets (including any non-test +targets specified on the command line) and testing +`*_test` and `test_suite` targets as soon as +their prerequisites are built, meaning that test execution is +interleaved with building. Doing so usually results in significant +speed gains. + +### Options for `bazel test` + +#### `--cache_test_results=(yes|no|auto)` (`-t`) + +If this option is set to 'auto' (the default) then Bazel will only rerun a test if any of the +following conditions applies: + +* Bazel detects changes in the test or its dependencies +* the test is marked as `external` +* multiple test runs were requested with `--runs_per_test` +* the test failed. + +If 'no', all tests will be executed unconditionally. + +If 'yes', the caching behavior will be the same as auto +except that it may cache test failures and test runs with +`--runs_per_test`. + +Note: Test results are _always_ saved in Bazel's output tree, +regardless of whether this option is enabled, so +you needn't have used `--cache_test_results` on the +prior run(s) of `bazel test` in order to get cache hits. +The option only affects whether Bazel will _use_ previously +saved results, not whether it will save results of the current run. + +Users who have enabled this option by default in +their `.bazelrc` file may find the +abbreviations `-t` (on) or `-t-` (off) +convenient for overriding the default on a particular run. + +#### `--check_tests_up_to_date` + +This option tells Bazel not to run the tests, but to merely check and report +the cached test results. If there are any tests which have not been +previously built and run, or whose tests results are out-of-date (for example, because +the source code or the build options have changed), then Bazel will report +an error message ("test result is not up-to-date"), will record the test's +status as "NO STATUS" (in red, if color output is enabled), and will return +a non-zero exit code. + +This option also implies +[`--check_up_to_date`](#check-up-to-date) behavior. + +This option may be useful for pre-submit checks. + +#### `--test_verbose_timeout_warnings` + +This option tells Bazel to explicitly warn the user if a test's timeout is +significantly longer than the test's actual execution time. While a test's +timeout should be set such that it is not flaky, a test that has a highly +over-generous timeout can hide real problems that crop up unexpectedly. + +For instance, a test that normally executes in a minute or two should not have +a timeout of ETERNAL or LONG as these are much, much too generous. + +This option is useful to help users decide on a good timeout value or +sanity check existing timeout values. + +Note: Each test shard is allotted the timeout of the entire +`XX_test` target. Using this option does not affect a test's timeout +value, merely warns if Bazel thinks the timeout could be restricted further. + +#### `--[no]test_keep_going` + +By default, all tests are run to completion. If this flag is disabled, +however, the build is aborted on any non-passing test. Subsequent build steps +and test invocations are not run, and in-flight invocations are canceled. +Do not specify both `--notest_keep_going` and `--keep_going`. + +#### `--flaky_test_attempts={attempts}` + +This option specifies the maximum number of times a test should be attempted +if it fails for any reason. A test that initially fails but eventually +succeeds is reported as `FLAKY` on the test summary. It is, +however, considered to be passed when it comes to identifying Bazel exit code +or total number of passed tests. Tests that fail all allowed attempts are +considered to be failed. + +By default (when this option is not specified, or when it is set to +default), only a single attempt is allowed for regular tests, and +3 for test rules with the `flaky` attribute set. You can specify +an integer value to override the maximum limit of test attempts. Bazel allows +a maximum of 10 test attempts in order to prevent abuse of the system. + +#### `--runs_per_test={[regex@]number}` + +This option specifies the number of times each test should be executed. All +test executions are treated as separate tests (fallback functionality +will apply to each of them independently). + +The status of a target with failing runs depends on the value of the +`--runs_per_test_detects_flakes` flag: + +* If absent, any failing run causes the entire test to fail. +* If present and two runs from the same shard return PASS and FAIL, the test + will receive a status of flaky (unless other failing runs cause it to + fail). + +If a single number is specified, all tests will run that many times. +Alternatively, a regular expression may be specified using the syntax +regex@number. This constrains the effect of `--runs_per_test` to targets +which match the regex (`--runs_per_test=^//pizza:.*@4` runs all tests +under `//pizza/` 4 times). +This form of `--runs_per_test` may be specified more than once. + +#### `--[no]runs_per_test_detects_flakes` + +If this option is specified (by default it is not), Bazel will detect flaky +test shards through `--runs_per_test`. If one or more runs for a single shard +fail and one or more runs for the same shard pass, the target will be +considered flaky with the flag. If unspecified, the target will report a +failing status. + +#### `--test_summary={output_style}` + +Specifies how the test result summary should be displayed. + +* `short` prints the results of each test along with the name of + the file containing the test output if the test failed. This is the default + value. +* `terse` like `short`, but even shorter: only print + information about tests which did not pass. +* `detailed` prints each individual test case that failed, not + only each test. The names of test output files are omitted. +* `none` does not print test summary. + +#### `--test_output={output_style}` + +Specifies how test output should be displayed: + +* `summary` shows a summary of whether each test passed or + failed. Also shows the output log file name for failed tests. The summary + will be printed at the end of the build (during the build, one would see + just simple progress messages when tests start, pass or fail). + This is the default behavior. +* `errors` sends combined stdout/stderr output from failed tests + only into the stdout immediately after test is completed, ensuring that + test output from simultaneous tests is not interleaved with each other. + Prints a summary at the build as per summary output above. +* `all` is similar to `errors` but prints output for + all tests, including those which passed. +* `streamed` streams stdout/stderr output from each test in + real-time. + +#### `--java_debug` + +This option causes the Java virtual machine of a java test to wait for a connection from a +JDWP-compliant debugger before starting the test. This option implies `--test_output=streamed`. + +#### `--[no]verbose_test_summary` + +By default this option is enabled, causing test times and other additional +information (such as test attempts) to be printed to the test summary. If +`--noverbose_test_summary` is specified, test summary will +include only test name, test status and cached test indicator and will +be formatted to stay within 80 characters when possible. + +#### `--test_tmpdir={path}` + +Specifies temporary directory for tests executed locally. Each test will be +executed in a separate subdirectory inside this directory. The directory will +be cleaned at the beginning of the each `bazel test` command. +By default, bazel will place this directory under Bazel output base directory. + +Note: This is a directory for running tests, not storing test results +(those are always stored under the `bazel-out` directory). + +#### `--test_timeout={seconds}` OR `--test_timeout={seconds},{seconds},{seconds},{seconds}` + +Overrides the timeout value for all tests by using specified number of +seconds as a new timeout value. If only one value is provided, then it will +be used for all test timeout categories. + +Alternatively, four comma-separated values may be provided, specifying +individual timeouts for short, moderate, long and eternal tests (in that +order). +In either form, zero or a negative value for any of the test sizes will +be substituted by the default timeout for the given timeout categories as +defined by the page [Writing Tests](/reference/test-encyclopedia). +By default, Bazel will use these timeouts for all tests by +inferring the timeout limit from the test's size whether the size is +implicitly or explicitly set. + +Tests which explicitly state their timeout category as distinct from their +size will receive the same value as if that timeout had been implicitly set by +the size tag. So a test of size 'small' which declares a 'long' timeout will +have the same effective timeout that a 'large' tests has with no explicit +timeout. + +#### `--test_arg={arg}` + +Passes command-line options/flags/arguments to each test process. This +option can be used multiple times to pass several arguments. For example, +`--test_arg=--logtostderr --test_arg=--v=3`. + +Note that, unlike the `bazel run` command, you can't pass test arguments +directly as in `bazel test -- target --logtostderr --v=3`. That's because +extraneous arguments passed to `bazel test` are interpreted as additional test +targets. That is, `--logtostderr` and `--v=3` would each be interpreted as a +test target. This ambiguity doesn't exist for a `bazel run` command, which only +accepts one target. + +`--test_arg` can be passed to a `bazel run` command, but it's ignored unless the +target being run is a test target. (As with any other flag, if it's passed in a +`bazel run` command after a `--` token, it's not processed by Bazel but +forwarded verbatim to the executed target.) + +#### `--test_env={variable}=_value_` OR `--test_env={variable}` + +Specifies additional variables that must be injected into the test +environment for each test. If {value} is not specified it will be +inherited from the shell environment used to start the `bazel test` +command. + +The environment can be accessed from within a test by using +`System.getenv("var")` (Java), `getenv("var")` (C or C++), + +#### `--run_under={command-prefix}` + +This specifies a prefix that the test runner will insert in front +of the test command before running it. The +{command-prefix} is split into words using Bourne shell +tokenization rules, and then the list of words is prepended to the +command that will be executed. + +If the first word is a fully-qualified label (starts with +`//`) it is built. Then the label is substituted by the +corresponding executable location that is prepended to the command +that will be executed along with the other words. + +Some caveats apply: + +* The PATH used for running tests may be different than the PATH in your environment, + so you may need to use an **absolute path** for the `--run_under` + command (the first word in {command-prefix}). +* **`stdin` is not connected**, so `--run_under` + can't be used for interactive commands. + +Examples: + +``` + --run_under=/usr/bin/strace + --run_under='/usr/bin/strace -c' + --run_under=/usr/bin/valgrind + --run_under='/usr/bin/valgrind --quiet --num-callers=20' +``` + +#### Test selection + +As documented under [Output selection options](#output-selection), +you can filter tests by [size](#test-size-filters), +[timeout](#test-timeout-filters), +[tag](#test-tag-filters), or +[language](#test-lang-filters). A convenience +[general name filter](#test-filter) can forward particular +filter args to the test runner. + +#### Other options for `bazel test` + +The syntax and the remaining options are exactly like +[`bazel build`](/run/build). + +## Running executables + +The `bazel run` command is similar to `bazel build`, except +it is used to build _and run_ a single target. Here is a typical session +(`//java/myapp:myapp` says hello and prints out its args): + +``` + % bazel run java/myapp:myapp -- --arg1 --arg2 + INFO: Analyzed target //java/myapp:myapp (13 packages loaded, 27 targets configured). + INFO: Found 1 target... + Target //java/myapp:myapp up-to-date: + bazel-bin/java/myapp/myapp + INFO: Elapsed time: 14.290s, Critical Path: 5.54s, ... + INFO: Build completed successfully, 4 total actions + INFO: Running command line: bazel-bin/java/myapp/myapp <args omitted> + Hello there + $EXEC_ROOT/java/myapp/myapp + --arg1 + --arg2 +``` + +Note: `--` is needed so that Bazel +does not interpret `--arg1` and `--arg2` as +Bazel options, but rather as part of the command line for running the binary. +Additionally, Bazel will avoid logging these arguments to the console in case +they contain sensitive information. + +`bazel run` is similar, but not identical, to directly invoking +the binary built by Bazel and its behavior is different depending on whether the +binary to be invoked is a test or not. + +When the binary is not a test, the current working directory will be the +runfiles tree of the binary. + +When the binary is a test, the current working directory will be the exec root +and a good-faith attempt is made to replicate the environment tests are usually +run in. The emulation is not perfect, though, and tests that have multiple +shards cannot be run this way (the +`--test_sharding_strategy=disabled` command line option can be used +to work around this) + +The following extra environment variables are also available to the binary: + +* `BUILD_WORKSPACE_DIRECTORY`: the root of the workspace where the + build was run. +* `BUILD_WORKING_DIRECTORY`: the current working directory where + Bazel was run from. +* `BUILD_ID`: the build ID of the `bazel run` invocation. This is usually + unique, except if Bazel was run with `--script_path` and the resulting + script is re-used. +* `BUILD_EXECROOT`: the execution root of the `bazel run` invocation. + +These can be used, for example, to interpret file names on the command line in +a user-friendly way. + +### Options for `bazel run` + +#### `--run_under={command-prefix}` + +This has the same effect as the `--run_under` option for +`bazel test` ([see above](#test-run-under)), +except that it applies to the command being run by `bazel +run` rather than to the tests being run by `bazel test` +and cannot run under label. + +#### Filtering logging outputs from Bazel + +When invoking a binary with `bazel run`, Bazel prints logging output from Bazel +itself and the binary under invocation. To make the logs less noisy, you can +suppress the outputs from Bazel itself with the `--ui_event_filters` and +`--noshow_progress` flags. + +For example: +`bazel run --ui_event_filters=-info,-stdout,-stderr --noshow_progress //java/myapp:myapp` + +### Executing tests + +`bazel run` can also execute test binaries, which has the effect of +running the test in a close approximation of the environment described at +[Writing Tests](/reference/test-encyclopedia). Note that none of the +`--test_*` arguments have an effect when running a test in this manner except +`--test_arg` . + +## Cleaning build outputs + +### The `clean` command + +Bazel has a `clean` command, analogous to that of Make. +It deletes the output directories for all build configurations performed +by this Bazel instance, or the entire working tree created by this +Bazel instance, and resets internal caches. If executed without any +command-line options, then the output directory for all configurations +will be cleaned. + +Recall that each Bazel instance is associated with a single workspace, thus the +`clean` command will delete all outputs from all builds you've done +with that Bazel instance in that workspace. + +To completely remove the entire working tree created by a Bazel +instance, you can specify the `--expunge` option. When +executed with `--expunge`, the clean command simply +removes the entire output base tree which, in addition to the build +output, contains all temp files created by Bazel. It also +stops the Bazel server after the clean, equivalent to the [`shutdown`](#shutdown) command. For example, to +clean up all disk and memory traces of a Bazel instance, you could +specify: + +``` + % bazel clean --expunge +``` + +Alternatively, you can expunge in the background by using +`--expunge_async`. It is safe to invoke a Bazel command +in the same client while the asynchronous expunge continues to run. + +Note: This may introduce IO contention. + +The `clean` command is provided primarily as a means of +reclaiming disk space for workspaces that are no longer needed. +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 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`. + +## Querying the dependency graph + +Bazel includes a query language for asking questions about the +dependency graph used during the build. The query language is used +by two commands: query and cquery. The major difference between the +two commands is that query runs after the [loading phase](/run/build#loading) +and cquery runs after the [analysis phase](/run/build#analysis). These tools are an +invaluable aid to many software engineering tasks. + +The query language is based on the idea of +algebraic operations over graphs; it is documented in detail in + +[Bazel Query Reference](/query/language). +Please refer to that document for reference, for +examples, and for query-specific command-line options. + +The query tool accepts several command-line +option. `--output` selects the output format. +`--[no]keep_going` (disabled by default) causes the query +tool to continue to make progress upon errors; this behavior may be +disabled if an incomplete result is not acceptable in case of errors. + +The `--[no]tool_deps` option, +enabled by default, causes dependencies in non-target configurations to be included in the +dependency graph over which the query operates. + +The `--[no]implicit_deps` option, enabled by default, causes +implicit dependencies to be included in the dependency graph over which the query operates. An +implicit dependency is one that is not explicitly specified in the BUILD file +but added by bazel. + +Example: "Show the locations of the definitions (in BUILD files) of +all genrules required to build all the tests in the PEBL tree." + +``` + bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))' +``` + +## Querying the action graph + +Caution: The aquery command is still experimental and its API will change. + +The `aquery` command allows you to query for actions in your build graph. +It operates on the post-analysis configured target graph and exposes +information about actions, artifacts and their relationships. + +The tool accepts several command-line options. +`--output` selects the output format. The default output format +(`text`) is human-readable, use `proto` or `textproto` for +machine-readable format. +Notably, the aquery command runs on top of a regular Bazel build and inherits +the set of options available during a build. + +It supports the same set of functions that is also available to traditional +`query` but `siblings`, `buildfiles` and +`tests`. + +For more details, see [Action Graph Query](/query/aquery). + +## Miscellaneous commands and options + +### `help` + +The `help` command provides on-line help. By default, it +shows a summary of available commands and help topics, as shown in +[Building with Bazel](/run/build#quickstart). +Specifying an argument displays detailed help for a particular +topic. Most topics are Bazel commands, such as `build` +or `query`, but there are some additional help topics +that do not correspond to commands. + +#### `--[no]long` (`-l`) + +By default, `bazel help [{topic}]` prints only a +summary of the relevant options for a topic. If +the `--long` option is specified, the type, default value +and full description of each option is also printed. + +### `shutdown` + +Bazel server processes may be stopped by using the `shutdown` +command. This command causes the Bazel server to exit as soon as it +becomes idle (for example, after the completion of any builds or other +commands that are currently in progress). For more details, see +[Client/server implementation](/run/client-server). + +Bazel servers stop themselves after an idle timeout, so this command +is rarely necessary; however, it can be useful in scripts when it is +known that no further builds will occur in a given workspace. + +`shutdown` accepts one +option, `--iff_heap_size_greater_than _n_`, which +requires an integer argument (in MB). If specified, this makes the shutdown +conditional on the amount of memory already consumed. This is +useful for scripts that initiate a lot of builds, as any memory +leaks in the Bazel server could cause it to crash spuriously on +occasion; performing a conditional restart preempts this condition. + +### `info` + +The `info` command prints various values associated with +the Bazel server instance, or with a specific build configuration. +(These may be used by scripts that drive a build.) + +The `info` command also permits a single (optional) +argument, which is the name of one of the keys in the list below. +In this case, `bazel info {key}` will print only +the value for that one key. (This is especially convenient when +scripting Bazel, as it avoids the need to pipe the result +through `sed -ne /key:/s/key://p`: + +#### Configuration-independent data + +* `release`: the release label for this Bazel + instance, or "development version" if this is not a released + binary. +* `workspace` the absolute path to the base workspace + directory. +* `install_base`: the absolute path to the installation + directory used by this Bazel instance for the current user. Bazel + installs its internally required executables below this directory. + +* `output_base`: the absolute path to the base output + directory used by this Bazel instance for the current user and + workspace combination. Bazel puts all of its scratch and build + output below this directory. +* `execution_root`: the absolute path to the execution + root directory under output_base. This directory is the root for all files + accessible to commands executed during the build, and is the working + directory for those commands. If the workspace directory is writable, a + symlink named `bazel-` + is placed there pointing to this directory. +* `output_path`: the absolute path to the output + directory beneath the execution root used for all files actually + generated as a result of build commands. If the workspace directory is + writable, a symlink named `bazel-out` is placed there pointing + to this directory. +* `server_pid`: the process ID of the Bazel server + process. +* `server_log`: the absolute path to the Bazel server's debug log file. + This file contains debugging information for all commands over the lifetime of the + Bazel server, and is intended for human consumption by Bazel developers and power users. +* `command_log`: the absolute path to the command log file; + this contains the interleaved stdout and stderr streams of the most recent + Bazel command. Note that running `bazel info` will overwrite the + contents of this file, since it then becomes the most recent Bazel command. + However, the location of the command log file will not change unless you + change the setting of the `--output_base` or + `--output_user_root` options. +* `used-heap-size`, + `committed-heap-size`, + `max-heap-size`: reports various JVM heap size + parameters. Respectively: memory currently used, memory currently + guaranteed to be available to the JVM from the system, maximum + possible allocation. +* `gc-count`, `gc-time`: The cumulative count of + garbage collections since the start of this Bazel server and the time spent + to perform them. Note that these values are not reset at the start of every + build. +* `package_path`: A colon-separated list of paths which would be + searched for packages by bazel. Has the same format as the + `--package_path` build command line argument. + +Example: the process ID of the Bazel server. + +```% bazel info server_pid +1285 +``` + +#### Configuration-specific data + +These data may be affected by the configuration options passed +to `bazel info`, for +example `--cpu`, `--compilation_mode`, +etc. The `info` command accepts all +the options that control dependency +analysis, since some of these determine the location of the +output directory of a build, the choice of compiler, etc. + +* `bazel-bin`, `bazel-testlogs`, + `bazel-genfiles`: reports the absolute path to + the `bazel-*` directories in which programs generated by the + build are located. This is usually, though not always, the same as + the `bazel-*` symlinks created in the base workspace directory after a + successful build. However, if the workspace directory is read-only, + no `bazel-*` symlinks can be created. Scripts that use + the value reported by `bazel info`, instead of assuming the + existence of the symlink, will be more robust. +* The complete + ["Make" environment](/reference/be/make-variables). If the `--show_make_env` flag is + specified, all variables in the current configuration's "Make" environment + are also displayed (such as `CC`, `GLIBC_VERSION`, etc). + These are the variables accessed using the `$(CC)` + or `varref("CC")` syntax inside BUILD files. + +Example: the C++ compiler for the current configuration. +This is the `$(CC)` variable in the "Make" environment, +so the `--show_make_env` flag is needed. + +``` + % bazel info --show_make_env -c opt COMPILATION_MODE + opt +``` + +Example: the `bazel-bin` output directory for the current +configuration. This is guaranteed to be correct even in cases where +the `bazel-bin` symlink cannot be created for some reason +(such as if you are building from a read-only directory). + +```% bazel info --cpu=piii bazel-bin +/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin +% bazel info --cpu=k8 bazel-bin +/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin +``` + +### `version` and `--version` + +The version command prints version details about the built Bazel +binary, including the changelist at which it was built and the date. +These are particularly useful in determining if you have the latest +Bazel, or if you are reporting bugs. Some of the interesting values +are: + +* `changelist`: the changelist at which this version of + Bazel was released. +* `label`: the release label for this Bazel + instance, or "development version" if this is not a released + binary. Very useful when reporting bugs. + +`bazel --version`, with no other args, will emit the same output as +`bazel version --gnu_format`, except without the side-effect of potentially starting +a Bazel server or unpacking the server archive. `bazel --version` can be run from +anywhere - it does not require a workspace directory. + +### `mobile-install` + +The `mobile-install` command installs apps to mobile devices. +Currently only Android devices running ART are supported. + +See [bazel mobile-install](/docs/mobile-install) for more information. + +Note: This command does not install the same thing that +`bazel build` produces: Bazel tweaks the app so that it can be +built, installed and re-installed quickly. This should, however, be mostly +transparent to the app. + +The following options are supported: + +#### `--incremental` + +If set, Bazel tries to install the app incrementally, that is, only those +parts that have changed since the last build. This cannot update resources +referenced from `AndroidManifest.xml`, native code or Java +resources (such as those referenced by `Class.getResource()`). If these +things change, this option must be omitted. Contrary to the spirit of Bazel +and due to limitations of the Android platform, it is the +**responsibility of the user** to know when this command is good enough and +when a full install is needed. + +If you are using a device with Marshmallow or later, consider the +[`--split_apks`](#split-apks) flag. + +#### `--split_apks` + +Whether to use split apks to install and update the application on the device. +Works only with devices with Marshmallow or later. Note that the +[`--incremental`](#incremental) flag +is not necessary when using `--split_apks`. + +#### `--start_app` + +Starts the app in a clean state after installing. Equivalent to `--start=COLD`. + +#### `--debug_app` + +Waits for debugger to be attached before starting the app in a clean state after installing. +Equivalent to `--start=DEBUG`. + +#### `--start=_start_type_` + +How the app should be started after installing it. Supported _start_type_s are: + +* `NO` Does not start the app. This is the default. +* `COLD` Starts the app from a clean state after install. +* `WARM` Preserves and restores the application state on incremental installs. +* `DEBUG` Waits for the debugger before starting the app in a clean state after + install. + +Note: If more than one of `--start=_start_type_`, `--start_app` or +`--debug_app` is set, the last value is used. + +#### `--adb={path}` + +Indicates the `adb` binary to be used. + +The default is to use the adb in the Android SDK specified by +[`--android_sdk`](#android-sdk). + +#### `--adb_arg={serial}` + +Extra arguments to `adb`. These come before the subcommand in the +command line and are typically used to specify which device to install to. +For example, to select the Android device or emulator to use: + +```% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef +``` + +invokes `adb` as + +``` +adb -s deadbeef install ... +``` + +#### `--incremental_install_verbosity={number}` + +The verbosity for incremental install. Set to 1 for debug logging to be +printed to the console. + +### `dump` + +The `dump` command prints to stdout a dump of the +internal state of the Bazel server. This command is intended +primarily for use by Bazel developers, so the output of this command +is not specified, and is subject to change. + +By default, command will just print help message outlining possible +options to dump specific areas of the Bazel state. In order to dump +internal state, at least one of the options must be specified. + +Following options are supported: + +* `--action_cache` dumps action cache content. +* `--packages` dumps package cache content. +* `--skyframe` dumps state of internal Bazel dependency graph. +* `--rules` dumps rule summary for each rule and aspect class, + including counts and action counts. This includes both native and Starlark rules. + If memory tracking is enabled, then the rules' memory consumption is also printed. +* `--skylark_memory` dumps a + [pprof](https://github.com/google/pprof) compatible .gz file to the specified path. + You must enable memory tracking for this to work. + +#### Memory tracking + +Some `dump` commands require memory tracking. To turn this on, you have to pass +startup flags to Bazel: + +* `--host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.jar` +* `--host_jvm_args=-DRULE_MEMORY_TRACKER=1` + +The java-agent is checked into Bazel at +`third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.jar`, so +make sure you adjust `$BAZEL` for where you keep your Bazel repository. + +Do not forget to keep passing these options to Bazel for every command or the server will +restart. + +Example: + +``` + % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.jar \ + --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ + build --nobuild <targets> + + # Dump rules + % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.jar \ + --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ + dump --rules + + # Dump Starlark heap and analyze it with pprof + % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.jar \ + --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ + dump --skylark_memory=$HOME/prof.gz + % pprof -flame $HOME/prof.gz +``` + +### `analyze-profile` + +The `analyze-profile` command analyzes a +[JSON trace profile](/advanced/performance/json-trace-profile) previously +gathered during a Bazel invocation. + +### `canonicalize-flags` + +The [`canonicalize-flags`](/reference/command-line-reference#canonicalize-flags-options) +command, which takes a list of options for a Bazel command and returns a list of +options that has the same effect. The new list of options is canonical. For example, +two lists of options with the same effect are canonicalized to the same new list. + +The `--for_command` option can be used to select between different +commands. At this time, only `build` and `test` are +supported. Options that the given command does not support cause an error. + +Note: A small number of options cannot be reordered, because Bazel cannot +ensure that the effect is identical. Also note that this command +_does not_ expand flags from `--config`. + +As an example: + +``` + % bazel canonicalize-flags -- --config=any_name --test_tag_filters="-lint" + --config=any_name + --test_tag_filters=-lint +``` + +### Startup options + +The options described in this section affect the startup of the Java +virtual machine used by Bazel server process, and they apply to all +subsequent commands handled by that server. If there is an already +running Bazel server and the startup options do not match, it will +be restarted. + +All of the options described in this section must be specified using the +`--key=value` or `--key value` +syntax. Also, these options must appear _before_ the name of the Bazel +command. Use `startup --key=value` to list these in a `.bazelrc` file. + +#### `--output_base={dir}` + +This option requires a path argument, which must specify a +writable directory. Bazel will use this location to write all its +output. The output base is also the key by which the client locates +the Bazel server. By changing the output base, you change the server +which will handle the command. + +By default, the output base is derived from the user's login name, +and the name of the workspace directory (actually, its MD5 digest), +so a typical value looks like: +`/var/tmp/google/_bazel_johndoe/d41d8cd98f00b204e9800998ecf8427e`. + +Note: The client uses the output base to find the Bazel server +instance, so if you specify a different output base in a Bazel +command, a different server will be found (or started) to handle the +request. It's possible to perform two concurrent builds in the same +workspace directory by varying the output base. + +For example: + +``` + OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base +% bazel --output_base ${OUTPUT_BASE}1 build //foo & bazel --output_base ${OUTPUT_BASE}2 build //bar +``` + +In this command, the two Bazel commands run concurrently (because of +the shell `&` operator), each using a different Bazel +server instance (because of the different output bases). +In contrast, if the default output base was used in both commands, +then both requests would be sent to the same server, which would +handle them sequentially: building `//foo` first, followed +by an incremental build of `//bar`. + +Note: We recommend you do not use an NFS or similar networked file system for the root +directory, as the higher access latency will cause noticeably slower builds. + +#### `--output_user_root={dir}` + +Points to the root directory where output and install bases are created. 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. This may be allowed once +[issue #11100](https://github.com/bazelbuild/bazel/issues/11100) is addressed. + +If the `--output_base` option is specified, it overrides +using `--output_user_root` to calculate the output base. + +The install base location is calculated based on +`--output_user_root`, plus the MD5 identity of the Bazel embedded +binaries. + +You can use the `--output_user_root` option to choose an +alternate base location for all of Bazel's output (install base and output +base) if there is a better location in your filesystem layout. + +Note: We recommend you do not use an NFS or similar networked file system for the root +directory, as the higher access latency will cause noticeably slower builds. + +#### `--server_javabase={dir}` + +Specifies the Java virtual machine in which _Bazel itself_ runs. The value must be a path to +the directory containing a JDK or JRE. It should not be a label. +This option should appear before any Bazel command, for example: + +``` + % bazel --server_javabase=/usr/local/buildtools/java/jdk build //foo +``` + +This flag does _not_ affect the JVMs used by Bazel subprocesses such as applications, tests, +tools, and so on. Use build options [--javabase](#javabase) or +[--host_javabase](#host-javabase) instead. + +This flag was previously named `--host_javabase` (sometimes referred to as the +'left-hand side' `--host_javabase`), but was renamed to avoid confusion with the +build flag [--host_javabase](#host-javabase) (sometimes referred to as the +'right-hand side' `--host_javabase`). + +#### `--host_jvm_args={string}` + +Specifies a startup option to be passed to the Java virtual machine in which _Bazel itself_ +runs. This can be used to set the stack size, for example: + +``` + % bazel --host_jvm_args="-Xss256K" build //foo +``` + +This option can be used multiple times with individual arguments. Note that +setting this flag should rarely be needed. You can also pass a space-separated list of strings, +each of which will be interpreted as a separate JVM argument, but this feature will soon be +deprecated. + +That this does _not_ affect any JVMs used by +subprocesses of Bazel: applications, tests, tools, and so on. To pass +JVM options to executable Java programs, whether run by `bazel +run` or on the command-line, you should use +the `--jvm_flags` argument which +all `java_binary` and `java_test` programs +support. Alternatively for tests, use `bazel test --test_arg=--jvm_flags=foo ...`. + +#### `--host_jvm_debug` + +This option causes the Java virtual machine to wait for a connection +from a JDWP-compliant debugger before +calling the main method of _Bazel itself_. This is primarily +intended for use by Bazel developers. + +Note: This does _not_ affect any JVMs used by subprocesses of Bazel: +applications, tests, tools, etc. + +#### `--autodetect_server_javabase` + +This option causes Bazel to automatically search for an installed JDK on startup, +and to fall back to the installed JRE if the embedded JRE isn't available. +`--explicit_server_javabase` can be used to pick an explicit JRE to +run Bazel with. + +#### `--batch` + +Batch mode causes Bazel to not use the +[standard client/server mode](/run/client-server), but instead runs a bazel +java process for a single command, which has been used for more predictable +semantics with respect to signal handling, job control, and environment +variable inheritance, and is necessary for running bazel in a chroot jail. + +Batch mode retains proper queueing semantics within the same output_base. +That is, simultaneous invocations will be processed in order, without overlap. +If a batch mode Bazel is run on a client with a running server, it first +kills the server before processing the command. + +Bazel will run slower in batch mode, or with the alternatives described above. +This is because, among other things, the build file cache is memory-resident, so it is not +preserved between sequential batch invocations. +Therefore, using batch mode often makes more sense in cases where performance +is less critical, such as continuous builds. + +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, 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. + +#### `--max_idle_secs={n}` + +This option specifies how long, in seconds, the Bazel server process +should wait after the last client request, before it exits. The +default value is 10800 (3 hours). `--max_idle_secs=0` will cause the +Bazel server process to persist indefinitely. + +Note: this flag is only read if Bazel needs +to start a new server. Changing this option will not cause the server to restart. + +Note: system sleep time where a build is not running is counted as idle time. + +This option may be used by scripts that invoke Bazel to ensure that +they do not leave Bazel server processes on a user's machine when they +would not be running otherwise. +For example, a presubmit script might wish to +invoke `bazel query` to ensure that a user's pending +change does not introduce unwanted dependencies. However, if the +user has not done a recent build in that workspace, it would be +undesirable for the presubmit script to start a Bazel server just +for it to remain idle for the rest of the day. +By specifying a small value of `--max_idle_secs` in the +query request, the script can ensure that _if_ it caused a new +server to start, that server will exit promptly, but if instead +there was already a server running, that server will continue to run +until it has been idle for the usual time. Of course, the existing +server's idle timer will be reset. + +#### `--[no]shutdown_on_low_sys_mem` + +If enabled and `--max_idle_secs` is set to a positive duration, +after the build server has been idle for a while, shut down the server when the system is +low on memory. Linux only. + +In addition to running an idle check corresponding to max_idle_secs, the build server will +starts monitoring available system memory after the server has been idle for some time. +If the available system memory becomes critically low, the server will exit. + +#### `--[no]block_for_lock` + +If enabled, Bazel will wait for other Bazel commands holding the +server lock to complete before progressing. If disabled, Bazel will +exit in error if it cannot immediately acquire the lock and +proceed. + +Developers might use this in presubmit checks to avoid long waits caused +by another Bazel command in the same client. + +#### `--io_nice_level={n}` + +Sets a level from 0-7 for best-effort IO scheduling. 0 is highest priority, +7 is lowest. The anticipatory scheduler may only honor up to priority 4. +Negative values are ignored. + +#### `--batch_cpu_scheduling` + +Use `batch` CPU scheduling for Bazel. This policy is useful for +workloads that are non-interactive, but do not want to lower their nice value. +See 'man 2 sched_setscheduler'. This policy may provide for better system +interactivity at the expense of Bazel throughput. + +### Miscellaneous options + +#### `--[no]announce_rc` + +Controls whether Bazel announces startup options and command options read from +the bazelrc files when starting up. + +#### `--color (yes|no|auto)` + +This option determines whether Bazel will use colors to highlight +its output on the screen. + +If this option is set to `yes`, color output is enabled. +If this option is set to `auto`, Bazel will use color output only if +the output is being sent to a terminal and the TERM environment variable +is set to a value other than `dumb`, `emacs`, or `xterm-mono`. +If this option is set to `no`, color output is disabled, +regardless of whether the output is going to a terminal and regardless +of the setting of the TERM environment variable. + +#### `--config={name}` + +Selects additional config section from +[the rc files](/run/bazelrc#bazelrc-file-locations); for the current `command`, +it also pulls in the options from `command:name` if such a section exists. Can be +specified multiple times to add flags from several config sections. Expansions can refer to other +definitions (for example, expansions can be chained). + +#### `--curses (yes|no|auto)` + +This option determines whether Bazel will use cursor controls +in its screen output. This results in less scrolling data, and a more +compact, easy-to-read stream of output from Bazel. This works well with +`--color`. + +If this option is set to `yes`, use of cursor controls is enabled. +If this option is set to `no`, use of cursor controls is disabled. +If this option is set to `auto`, use of cursor controls will be +enabled under the same conditions as for `--color=auto`. + +#### `--[no]show_timestamps` + +If specified, a timestamp is added to each message generated by +Bazel specifying the time at which the message was displayed. + diff --git a/query/quickstart.mdx b/query/quickstart.mdx new file mode 100644 index 0000000..4c6021f --- /dev/null +++ b/query/quickstart.mdx @@ -0,0 +1,517 @@ +--- +title: 'Query quickstart' +--- + + + +This tutorial covers how to work with Bazel to trace dependencies in your code using a premade Bazel project. + +For language and `--output` flag details, see the [Bazel query reference](/query/language) and [Bazel cquery reference](/query/cquery) manuals. Get help in your IDE by typing `bazel help query` or `bazel help cquery` on the command line. + +## Objective + +This guide runs you through a set of basic queries you can use to learn more about your project's file dependencies. It is intended for new Bazel developers with a basic knowledge of how Bazel and `BUILD` files work. + + +## Prerequisites + +Start by installing [Bazel](https://bazel.build/install), if you haven’t already. This tutorial uses Git for source control, so for best results, install [Git](https://github.com/git-guides/install-git) as well. + +To visualize dependency graphs, the tool called Graphviz is used, which you can [download](https://graphviz.org/download/) in order to follow along. + +### Get the sample project + +Next, retrieve the sample app from [Bazel's Examples repository](https://github.com/bazelbuild/examples) by running the following in your command-line tool of choice: + +```posix-terminal +git clone https://github.com/bazelbuild/examples.git +``` + +The sample project for this tutorial is in the `examples/query-quickstart` directory. + +## Getting started + +### What are Bazel queries? + +Queries help you to learn about a Bazel codebase by analyzing the relationships between `BUILD` files and examining the resulting output for useful information. This guide previews some basic query functions, but for more options see the [query guide](https://bazel.build/query/guide). Queries help you learn about dependencies in large scale projects without manually navigating through `BUILD` files. + +To run a query, open your command line terminal and enter: + +```posix-terminal +bazel query 'query_function' +``` + +### Scenario + +Imagine a scenario that delves into the relationship between Cafe Bazel and its respective chef. This Cafe exclusively sells pizza and mac & cheese. Take a look below at how the project is structured: + +``` +bazelqueryguide +├── BUILD +├── src +│ └── main +│ └── java +│ └── com +│ └── example +│ ├── customers +│ │ ├── Jenny.java +│ │ ├── Amir.java +│ │ └── BUILD +│ ├── dishes +│ │ ├── Pizza.java +│ │ ├── MacAndCheese.java +│ │ └── BUILD +│ ├── ingredients +│ │ ├── Cheese.java +│ │ ├── Tomatoes.java +│ │ ├── Dough.java +│ │ ├── Macaroni.java +│ │ └── BUILD +│ ├── restaurant +│ │ ├── Cafe.java +│ │ ├── Chef.java +│ │ └── BUILD +│ ├── reviews +│ │ ├── Review.java +│ │ └── BUILD +│ └── Runner.java +└── MODULE.bazel +``` + +Throughout this tutorial, unless directed otherwise, try not to look in the `BUILD` files to find the information you need and instead solely use the query function. + +A project consists of different packages that make up a Cafe. They are separated into: `restaurant`, `ingredients`, `dishes`, `customers`, and `reviews`. Rules within these packages define different components of the Cafe with various tags and dependencies. + +### Running a build + +This project contains a main method inside of `Runner.java` that you can execute +to print out a menu of the Cafe. Build the project using Bazel with the command +`bazel build` and use `:` to signal that the target is named `runner`. See +[target names](https://bazel.build/concepts/labels#target-names) to learn how to +reference targets. + +To build this project, paste this command into a terminal: + +```posix-terminal +bazel build :runner +``` + +Your output should look something like this if the build is successful. + +```bash +INFO: Analyzed target //:runner (49 packages loaded, 784 targets configured). +INFO: Found 1 target... +Target //:runner up-to-date: + bazel-bin/runner.jar + bazel-bin/runner +INFO: Elapsed time: 16.593s, Critical Path: 4.32s +INFO: 23 processes: 4 internal, 10 darwin-sandbox, 9 worker. +INFO: Build completed successfully, 23 total actions +``` + +After it has built successfully, run the application by pasting this command: + +```posix-terminal +bazel-bin/runner +``` + +```bash +--------------------- MENU ------------------------- + +Pizza - Cheesy Delicious Goodness +Macaroni & Cheese - Kid-approved Dinner + +---------------------------------------------------- +``` +This leaves you with a list of the menu items given along with a short description. + +## Exploring targets + +The project lists ingredients and dishes in their own packages. To use a query to view the rules of a package, run the command bazel query package/… + +In this case, you can use this to look through the ingredients and dishes that this Cafe has by running: + +```posix-terminal +bazel query //src/main/java/com/example/dishes/... +``` + +```posix-terminal +bazel query //src/main/java/com/example/ingredients/... +``` + +If you query for the targets of the ingredients package, the output should look like: + +```bash +//src/main/java/com/example/ingredients:cheese +//src/main/java/com/example/ingredients:dough +//src/main/java/com/example/ingredients:macaroni +//src/main/java/com/example/ingredients:tomato +``` + +## Finding dependencies + +What targets does your runner rely on to run? + +Say you want to dive deeper into the structure of your project without prodding into the filesystem (which may be untenable for large projects). What rules does Cafe Bazel use? + +If, like in this example, the target for your runner is `runner`, discover the underlying dependencies of the target by running the command: + +```posix-terminal +bazel query --noimplicit_deps "deps(target)" +``` + +```posix-terminal +bazel query --noimplicit_deps "deps(:runner)" +``` + +```bash +//:runner +//:src/main/java/com/example/Runner.java +//src/main/java/com/example/dishes:MacAndCheese.java +//src/main/java/com/example/dishes:Pizza.java +//src/main/java/com/example/dishes:macAndCheese +//src/main/java/com/example/dishes:pizza +//src/main/java/com/example/ingredients:Cheese.java +//src/main/java/com/example/ingredients:Dough.java +//src/main/java/com/example/ingredients:Macaroni.java +//src/main/java/com/example/ingredients:Tomato.java +//src/main/java/com/example/ingredients:cheese +//src/main/java/com/example/ingredients:dough +//src/main/java/com/example/ingredients:macaroni +//src/main/java/com/example/ingredients:tomato +//src/main/java/com/example/restaurant:Cafe.java +//src/main/java/com/example/restaurant:Chef.java +//src/main/java/com/example/restaurant:cafe +//src/main/java/com/example/restaurant:chef +``` +Note: Adding the flag `--noimplicit_deps` removes configurations and potential toolchains to simplify the list. When you omit this flag, Bazel returns implicit dependencies not specified in the `BUILD` file and clutters the output. + +In most cases, use the query function `deps()` to see individual output dependencies of a specific target. + +## Visualizing the dependency graph (optional) + +Note: This section uses Graphviz, so make sure to [download Graphviz](https://graphviz.org/download/) to follow along. + +The section describes how you can visualize the dependency paths for a specific query. [Graphviz](https://graphviz.org/) helps to see the path as a directed acyclic graph image as opposed to a flattened list. You can alter the display of the Bazel query graph by using various `--output` command line options. See [Output Formats](https://bazel.build/query/language#output-formats) for options. + +Start by running your desired query and add the flag `--noimplicit_deps` to remove excessive tool dependencies. Then, follow the query with the output flag and store the graph into a file called `graph.in` to create a text representation of the graph. + +To search for all dependencies of the target `:runner` and format the output as a graph: + +```posix-terminal +bazel query --noimplicit_deps 'deps(:runner)' --output graph > graph.in +``` +This creates a file called `graph.in`, which is a text representation of the build graph. Graphviz uses [dot](https://graphviz.org/docs/layouts/dot/) – a tool that processes text into a visualization — to create a png: + +```posix-terminal +dot -Tpng < graph.in > graph.png +``` +If you open up `graph.png`, you should see something like this. The graph below has been simplified to make the essential path details clearer in this guide. + +![Diagram showing a relationship from cafe to chef to the dishes: pizza and mac and cheese which diverges into the separate ingredients: cheese, tomatoes, dough, and macaroni.](images/query_graph1.png "Dependency graph") + +This helps when you want to see the outputs of the different query functions throughout this guide. + +## Finding reverse dependencies + +If instead you have a target you’d like to analyze what other targets use it, you can use a query to examine what targets depend on a certain rule. This is called a “reverse dependency”. Using `rdeps()` can be useful when editing a file in a codebase that you’re unfamiliar with, and can save you from unknowingly breaking other files which depended on it. + +For instance, you want to make some edits to the ingredient `cheese`. To avoid causing an issue for Cafe Bazel, you need to check what dishes rely on `cheese`. + +Caution: Since `ingredients` is its own package, you must use a different naming convention for the target `cheese` in the form of `//package:target`. Read more about referencing targets, or [Labels](https://bazel.build/concepts/labels). + +To see what targets depend on a particular target/package, you can use `rdeps(universe_scope, target)`. The `rdeps()` query function takes in at least two arguments: a `universe_scope` — the relevant directory — and a `target`. Bazel searches for the target’s reverse dependencies within the `universe_scope` provided. The `rdeps()` operator accepts an optional third argument: an integer literal specifying the upper bound on the depth of the search. + +Tip: To search within the whole scope of the project, set the `universe_scope` to `//...` + +To look for reverse dependencies of the target `cheese` within the scope of the entire project ‘//…’ run the command: + +```posix-terminal +bazel query "rdeps(universe_scope, target)" +``` +``` +ex) bazel query "rdeps(//... , //src/main/java/com/example/ingredients:cheese)" +``` +```bash +//:runner +//src/main/java/com/example/dishes:macAndCheese +//src/main/java/com/example/dishes:pizza +//src/main/java/com/example/ingredients:cheese +//src/main/java/com/example/restaurant:cafe +//src/main/java/com/example/restaurant:chef +``` +The query return shows that cheese is relied on by both pizza and macAndCheese. What a surprise! + +## Finding targets based on tags + +Two customers walk into Bazel Cafe: Amir and Jenny. There is nothing known about them except for their names. Luckily, they have their orders tagged in the 'customers' `BUILD` file. How can you access this tag? + +Developers can tag Bazel targets with different identifiers, often for testing purposes. For instance, tags on tests can annotate a test's role in your debug and release process, especially for C++ and Python tests, which lack any runtime annotation ability. Using tags and size elements gives flexibility in assembling suites of tests based around a codebase’s check-in policy. + +In this example, the tags are either one of `pizza` or `macAndCheese` to represent the menu items. This command queries for targets that have tags matching your identifier within a certain package. + +``` +bazel query 'attr(tags, "pizza", //src/main/java/com/example/customers/...)' +``` +This query returns all of the targets in the 'customers' package that have a tag of "pizza". + +### Test yourself + +Use this query to learn what Jenny wants to order. + +
+ +

Answer

+

Mac and Cheese

+ +
+ + +## Adding a new dependency + +Cafe Bazel has expanded its menu — customers can now order a Smoothie! This specific smoothie consists of the ingredients `Strawberry` and `Banana`. + +First, add the ingredients that the smoothie depends on: `Strawberry.java` and `Banana.java`. Add the empty Java classes. + +**`src/main/java/com/example/ingredients/Strawberry.java`** + +```java +package com.example.ingredients; + +public class Strawberry { + +} +``` + +**`src/main/java/com/example/ingredients/Banana.java`** + +```java +package com.example.ingredients; + +public class Banana { + +} +``` + +Next, add `Smoothie.java` to the appropriate directory: `dishes`. + +**`src/main/java/com/example/dishes/Smoothie.java`** + +```java +package com.example.dishes; + +public class Smoothie { + public static final String DISH_NAME = "Smoothie"; + public static final String DESCRIPTION = "Yummy and Refreshing"; +} +``` + + +Lastly, add these files as rules in the appropriate `BUILD` files. Create a new java library for each new ingredient, including its name, public visibility, and its newly created 'src' file. You should wind up with this updated `BUILD` file: + +**`src/main/java/com/example/ingredients/BUILD`** + +``` +java_library( + name = "cheese", + visibility = ["//visibility:public"], + srcs = ["Cheese.java"], +) + +java_library( + name = "dough", + visibility = ["//visibility:public"], + srcs = ["Dough.java"], +) + +java_library( + name = "macaroni", + visibility = ["//visibility:public"], + srcs = ["Macaroni.java"], +) + +java_library( + name = "tomato", + visibility = ["//visibility:public"], + srcs = ["Tomato.java"], +) + +java_library( + name = "strawberry", + visibility = ["//visibility:public"], + srcs = ["Strawberry.java"], +) + +java_library( + name = "banana", + visibility = ["//visibility:public"], + srcs = ["Banana.java"], +) +``` + +In the `BUILD` file for dishes, you want to add a new rule for `Smoothie`. Doing so includes the Java file created for `Smoothie` as a 'src' file, and the new rules you made for each ingredient of the smoothie. + +**`src/main/java/com/example/dishes/BUILD`** + +``` +java_library( + name = "macAndCheese", + visibility = ["//visibility:public"], + srcs = ["MacAndCheese.java"], + deps = [ + "//src/main/java/com/example/ingredients:cheese", + "//src/main/java/com/example/ingredients:macaroni", + ], +) + +java_library( + name = "pizza", + visibility = ["//visibility:public"], + srcs = ["Pizza.java"], + deps = [ + "//src/main/java/com/example/ingredients:cheese", + "//src/main/java/com/example/ingredients:dough", + "//src/main/java/com/example/ingredients:tomato", + ], +) + +java_library( + name = "smoothie", + visibility = ["//visibility:public"], + srcs = ["Smoothie.java"], + deps = [ + "//src/main/java/com/example/ingredients:strawberry", + "//src/main/java/com/example/ingredients:banana", + ], +) +``` + +Lastly, you want to include the smoothie as a dependency in the Chef’s `BUILD` file. + +**`src/main/java/com/example/restaurant/BUILD`** + +``` +java_library( + name = "chef", + visibility = ["//visibility:public"], + srcs = [ + "Chef.java", + ], + + deps = [ + "//src/main/java/com/example/dishes:macAndCheese", + "//src/main/java/com/example/dishes:pizza", + "//src/main/java/com/example/dishes:smoothie", + ], +) + +java_library( + name = "cafe", + visibility = ["//visibility:public"], + srcs = [ + "Cafe.java", + ], + deps = [ + ":chef", + ], +) +``` + +Build `cafe` again to confirm that there are no errors. If it builds successfully, congratulations! You’ve added a new dependency for the 'Cafe'. If not, look out for spelling mistakes and package naming. For more information about writing `BUILD` files see [BUILD Style Guide](https://bazel.build/build/style-guide). + +Now, visualize the new dependency graph with the addition of the `Smoothie` to compare with the previous one. For clarity, name the graph input as `graph2.in` and `graph2.png`. + + +```posix-terminal +bazel query --noimplicit_deps 'deps(:runner)' --output graph > graph2.in +``` + +```posix-terminal +dot -Tpng < graph2.in > graph2.png +``` + +[![The same graph as the first one except now there is a spoke stemming from the chef target with smoothie which leads to banana and strawberry](images/query_graph2.png "Updated dependency graph")](images/query_graph2.png) + +Looking at `graph2.png`, you can see that `Smoothie` has no shared dependencies with other dishes but is just another target that the `Chef` relies on. + +## somepath() and allpaths() + +What if you want to query why one package depends on another package? Displaying a dependency path between the two provides the answer. + +Two functions can help you find dependency paths: `somepath()` and `allpaths()`. Given a starting target S and an end point E, find a path between S and E by using `somepath(S,E)`. + +Explore the differences between these two functions by looking at the relationships between the 'Chef' and 'Cheese' targets. There are different possible paths to get from one target to the other: + +* Chef → MacAndCheese → Cheese +* Chef → Pizza → Cheese + +`somepath()` gives you a single path out of the two options, whereas 'allpaths()' outputs every possible path. + +Using Cafe Bazel as an example, run the following: + +```posix-terminal +bazel query "somepath(//src/main/java/com/example/restaurant/..., //src/main/java/com/example/ingredients:cheese)" +``` + +```bash +//src/main/java/com/example/restaurant:cafe +//src/main/java/com/example/restaurant:chef +//src/main/java/com/example/dishes:macAndCheese +//src/main/java/com/example/ingredients:cheese +``` + +The output follows the first path of Cafe → Chef → MacAndCheese → Cheese. If instead you use `allpaths()`, you get: + +```posix-terminal +bazel query "allpaths(//src/main/java/com/example/restaurant/..., //src/main/java/com/example/ingredients:cheese)" +``` + +```bash +//src/main/java/com/example/dishes:macAndCheese +//src/main/java/com/example/dishes:pizza +//src/main/java/com/example/ingredients:cheese +//src/main/java/com/example/restaurant:cafe +//src/main/java/com/example/restaurant:chef +``` + +![Output path of cafe to chef to pizza,mac and cheese to cheese](images/query_graph3.png "Output path for dependency") + +The output of `allpaths()` is a little harder to read as it is a flattened list of the dependencies. Visualizing this graph using Graphviz makes the relationship clearer to understand. + +## Test yourself + +One of Cafe Bazel’s customers gave the restaurant's first review! Unfortunately, the review is missing some details such as the identity of the reviewer and what dish it’s referencing. Luckily, you can access this information with Bazel. The `reviews` package contains a program that prints a review from a mystery customer. Build and run it with: + +```posix-terminal +bazel build //src/main/java/com/example/reviews:review +``` + +```posix-terminal +bazel-bin/src/main/java/com/example/reviews/review +``` + +Going off Bazel queries only, try to find out who wrote the review, and what dish they were describing. + +
+ +

Hint

+

Check the tags and dependencies for useful information.

+ +
+ +
+ +

Answer

+

This review was describing the Pizza and Amir was the reviewer. If you look at what dependencies that this rule had using + bazel query --noimplicit\_deps 'deps(//src/main/java/com/example/reviews:review)' + The result of this command reveals that Amir is the reviewer! + Next, since you know the reviewer is Amir, you can use the query function to seek which tag Amir has in the `BUILD` file to see what dish is there. + The command bazel query 'attr(tags, "pizza", //src/main/java/com/example/customers/...)' output that Amir is the only customer that ordered a pizza and is the reviewer which gives us the answer. +

+ +
+ +## Wrapping up + +Congratulations! You have now run several basic queries, which you can try out on own projects. To learn more about the query language syntax, refer to the [Query reference page](https://bazel.build/query/language). Want more advanced queries? The [Query guide](https://bazel.build/query/guide) showcases an in-depth list of more use cases than are covered in this guide. + diff --git a/reference/flag-cheatsheet.mdx b/reference/flag-cheatsheet.mdx new file mode 100644 index 0000000..ae185a6 --- /dev/null +++ b/reference/flag-cheatsheet.mdx @@ -0,0 +1,204 @@ +--- +title: 'Bazel flag cheat sheet' +--- + +Navigating Bazel's extensive list of command line flags can be a challenge. +This page focuses on the most crucial flags you'll need to know. + + +Select the flag name in table to navigate to its entry in the command line reference. + + +## Useful general options + +The following flags are meant to be set explicitly on the command line. + +### [`--config`](https://bazel.build/reference/command-line-reference#flag--config) + +You can organize flags in a `.bazelrc` file into configurations, like ones for debugging or release builds. Additional configuration groups can be selected with `--config=`. + +### [`--keep_going`](https://bazel.build/reference/command-line-reference#flag--keep_going) + +Bazel should try as much as possible to continue with build and test execution. By default, Bazel fails eagerly. + +### [`--remote_download_outputs`](https://bazel.build/reference/command-line-reference#flag--remote_download_outputs) + +When using remote execution or caching (both disk and remote), you can signal to Bazel that you want to download **all** (intermediate) build artifacts as follows: + +```sh +--remote_download_outputs=all +``` + +By default, Bazel only downloads top-level artifacts, such as the final binary, and intermediate artifacts that are necessary for local actions. + +### [`--stamp`](https://bazel.build/reference/command-line-reference#flag--stamp) + +Adds build info (user, timestamp) to binaries. + + +Because this increases build time, it's only intended for release builds. + + +## Uncover Build & Test Issues + +The following flags can help you better understand Bazel build or test errors. + +### [`--announce_rc`](https://bazel.build/reference/command-line-reference#flag--announce_rc) + +Shows which flags are implicitly set through user-defined, machine-defined, or project-defined `.bazelrc` files. + +### [`--auto_output_filter`](https://bazel.build/reference/command-line-reference#flag--auto_output_filter) + +By default, Bazel tries to prevent log spam and does only print compiler warnings and Starlark debug output for packages and subpackages requested on the command line. To disable all filtering, set `--auto_output_filter=none`. + +### [`--sandbox_debug`](https://bazel.build/reference/command-line-reference#flag--sandbox_debug) + +Lets you drill into sandboxing errors. For details on why Bazel sandboxes builds by default and what gets sandboxed, see our [sandboxing documentation](https://bazel.build/docs/sandboxing). + + +If you think the error might be caused by sandboxing, try turning sandboxing off temporarily. + +To do this, add `--spawn_strategy=local` to your command. + + +### [`--subcommands (-s)`](https://bazel.build/reference/command-line-reference#flag--subcommands) + +Displays a comprehensive list of every command that Bazel runs during a build, regardless of whether it succeeds or fails. + +## Startup + + +Startup flags need to be passed before the command and cause a server restart. Toggle these flags with caution. + + +### [`--bazelrc`](https://bazel.build/reference/command-line-reference#flag--bazelrc) + +You can specify default Bazel options in `.bazelrc` files. If multiple `.bazelrc` files exist, you can select which `.bazelrc` file is used by adding `--bazelrc=`. + + +`--bazelrc=dev/null` disables the search for `.bazelrc` files. + +This is ideal for scenarios where you want to ensure a clean build environment, such as release builds, and prevent any unintended configuration changes from `.bazelrc` files. + + +### [`--host_jvm_args`](https://bazel.build/docs/user-manual#host-jvm-args) + +Limits the amount of RAM the Bazel server uses. + +For example, the following limits the Bazel heap size to **3**GB: + +```sh +--host_jvm_args=-Xmx3g +``` + + +`-Xmx` is used to set the maximum heap size for the Java Virtual Machine (JVM). The heap is the area of memory where objects are allocated. The correct format for this option is `-Xmx`, where `` is the maximum heap size, specified with a unit such as: + +- m for megabytes +- g for gigabytes +- k for kilobytes + + +### [`--output_base`](https://bazel.build/reference/command-line-reference#flag--output_base) + +Controls Bazel's output tree. Bazel doesn't store build outputs, including logs, within the source tree itself. Instead, it uses a distinct output tree for this purpose. + + +Using multiple output bases in one Bazel workspace lets you run multiple Bazel servers concurrently. This can be useful when trying to avoid analysis thrashing. For more information, see [Choosing the output base](https://bazel.build/run/scripts#output-base-option). + + +## Bazel tests + +The following flags are related to Bazel test. + +### [`--java_debug`](https://bazel.build/reference/command-line-reference#flag--java_debug) + +Causes Java tests to wait for a debugger connection before being executed. + +### [`--runs_per_test`](https://bazel.build/reference/command-line-reference#flag--runs_per_test) + +The number of times to run tests. For example, to run tests N times, add `--runs_per_test=N`. This can be useful to debug flaky tests and see whether a fix causes a test to pass consistently. + +### [`--test_filter`](https://bazel.build/reference/command-line-reference#flag--test_filter) + +This flag is particularly useful when iterating on a single test method, such as when a change you made breaks a test. Instead of re-running all the test methods in the test suite, you can focus solely on the specific test(s) that failed. This allows for faster feedback and more efficient debugging. This flag is often used in conjunction with `--test_output=streamed` for real-time test output. + +### [`--test_output`](https://bazel.build/reference/command-line-reference#flag--test_output) + +Specifies the output mode. By default, Bazel captures test output in local log files. When iterating on a broken test, you typically want to use `--test_output=streamed` to see the test output in real time. + +## Bazel run + +The following flags are related to Bazel run. + +### [`--run_under`](https://bazel.build/reference/command-line-reference#flag--run_under) + +Changes how executables are invoked. For example `--run_under="strace -c"` is commonly used for debugging. + +## User-specific bazelrc options + +The following flags are related to user-specific `.bazelrc` options. + +### [`--disk_cache`](https://bazel.build/reference/command-line-reference#flag--disk_cache) + +A path to a directory where Bazel can read and write actions and action outputs. If the directory doesn't exist, it will be created. + +You can share build artifacts between multiple branches or workspaces and speed up Bazel builds by adding `--disk_cache=` to your command. + +### [`--jobs`](https://bazel.build/reference/command-line-reference#flag--jobs) + +The number of concurrent jobs to run. + +This is typically only required when using remote execution where a remote build cluster executes more jobs than you have cores locally. + +### [`--local_resources`](https://bazel.build/reference/command-line-reference#flag--local_resources) + +Limits how much CPU or RAM is consumed by locally running actions. + + +This has no impact on the amount of CPU or RAM that the Bazel server itself consumes for tasks like analysis and build orchestration. + + +### [`--sandbox_base`](https://bazel.build/reference/command-line-reference#flag--sandbox_base) + +Lets the sandbox create its sandbox directories underneath this path. By default, Bazel executes local actions sandboxed which adds some overhead to the build. + + +Specify a path on tmpfs, for example `/run/shm`, to possibly improve performance a lot when your build or tests have many input files. + + +## Project-specific bazelrc options + +The following flags are related to project-specific `.bazelrc` options. + +### [`--flaky_test_attempts`](https://bazel.build/reference/command-line-reference#flag--flaky_test_attempts) + +Retry each test up to the specified number of times in case of any test failure. This is especially useful on Continuous Integration. Tests that require more than one attempt to pass are marked as **FLAKY** in the test summary. + +### [`--remote_cache`](https://bazel.build/reference/command-line-reference#flag--remote_cache) + +A URI of a caching endpoint. Setting up remote caching can be a great way to speed up Bazel builds. It can be combined with a local disk cache. + +### [`--remote_download_regex`](https://bazel.build/reference/command-line-reference#flag--remote_download_regex) + +Force remote build outputs whose path matches this pattern to be downloaded, irrespective of the `--remote_download_outputs` setting. Multiple patterns may be specified by repeating this flag. + +### [`--remote_executor`](https://bazel.build/reference/command-line-reference#flag--remote_executor) + +`HOST` or `HOST:PORT` of a remote execution endpoint. Pass this if you are using a remote execution service. You'll often need to Add `--remote_instance_name=`. + +### [`--remote_instance_name`](https://bazel.build/reference/command-line-reference#flag--remote_instance_name) + +The value to pass as `instance_name` in the remote execution API. + +### [`--show_timestamps`](https://bazel.build/docs/user-manual#show-timestamps) + +If specified, a timestamp is added to each message generated by Bazel specifying the time at which the message was displayed. This is useful on CI systems to quickly understand what step took how long. + +### [`--spawn_strategy`](https://bazel.build/reference/command-line-reference#flag--spawn_strategy) + +Even with remote execution, running some build actions locally might be faster. This depends on factors like your build cluster's capacity, network speed, and network delays. + + +To run actions both locally and remotely and accept the faster result add `--spawn_strategy=dynamic` to your build command. + diff --git a/reference/test-encyclopedia.mdx b/reference/test-encyclopedia.mdx new file mode 100644 index 0000000..2c74dc9 --- /dev/null +++ b/reference/test-encyclopedia.mdx @@ -0,0 +1,758 @@ +--- +title: 'Test encyclopedia' +--- + + + +An exhaustive specification of the test execution environment. + +## Background + +The Bazel BUILD language includes rules which can be used to define automated +test programs in many languages. + +Tests are run using [`bazel test`](/docs/user-manual#test). + +Users may also execute test binaries directly. This is allowed but not endorsed, +as such an invocation will not adhere to the mandates described below. + +Tests should be *hermetic*: that is, they ought to access only those resources +on which they have a declared dependency. If tests are not properly hermetic +then they do not give historically reproducible results. This could be a +significant problem for culprit finding (determining which change broke a test), +release engineering auditability, and resource isolation of tests (automated +testing frameworks ought not DDOS a server because some tests happen to talk to +it). + +## Objective + +The goal of this page is to formally establish the runtime environment for and +expected behavior of Bazel tests. It will also impose requirements on the test +runner and the build system. + +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 this +specification and the implemented behavior of test runner disagree, the +specification takes precedence. + +## Proposed Specification + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as +described in IETF RFC 2119. + +## Purpose of tests + +The purpose of Bazel tests is to confirm some property of the source files +checked into the repository. (On this page, "source files" includes test data, +golden outputs, and anything else kept under version control.) One user writes a +test to assert an invariant which they expect to be maintained. Other users +execute the test later to check whether the invariant has been broken. If the +test depends on any variables other than source files (non-hermetic), its value +is diminished, because the later users cannot be sure their changes are at fault +when the test stops passing. + +Therefore the outcome of a test must depend only on: + +* source files on which the test has a declared dependency +* products of the build system on which the test has a declared dependency +* resources whose behavior is guaranteed by the test runner to remain constant + +Currently, such behavior is not enforced. However, test runners reserve the +right to add such enforcement in the future. + +## Role of the build system + +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 a +language-specific harness with the test code. Test rules must produce other +outputs as well. In addition to the primary test executable, the test runner +will need a manifest of **runfiles**, input files which should be made available +to the test at runtime, and it may need information about the type, size, and +tags of a test. + +The build system may use the runfiles to deliver code as well as data. (This +might be used as an optimization to make each test binary smaller by sharing +files across tests, such as through the use of dynamic linking.) The build system +should ensure that the generated executable loads these files via the runfiles +image provided by the test runner, rather than hardcoded references to absolute +locations in the source or output tree. + +## Role of the test runner + +From the point of view of the test runner, each test is a program which can be +invoked with `execve()`. There may be other ways to execute tests; for example, +an IDE might allow the execution of Java tests in-process. However, the result +of running the test as a standalone process must be considered authoritative. If +a test process runs to completion and terminates normally with an exit code of +zero, the test has passed. Any other result is considered a test failure. In +particular, writing any of the strings `PASS` or `FAIL` to stdout has no +significance to the test runner. + +If a test takes too long to execute, exceeds some resource limit, or the test +runner otherwise detects prohibited behavior, it may choose to kill the test and +treat the run as a failure. The runner must not report the test as passing after +sending a signal to the test process or any children thereof. + +The whole test target (not individual methods or tests) is given a limited +amount of time to run to completion. The time limit for a test is based on its +[`timeout`](/reference/be/common-definitions#test.timeout) attribute according +to the following table: + +| timeout | Time Limit (sec.) | +|---------|-------------------| +| short | 60 | +| moderate | 300 | +| long | 900 | +| eternal | 3600 | + +Tests which do not explicitly specify a timeout have one implied based on the +test's [`size`](/reference/be/common-definitions#test.size) as follows: + +| size | Implied timeout label | +|------|-----------------------| +| small | short | +| medium | moderate | +| large | long | +| enormous | eternal | + +A "large" test with no explicit timeout setting will be allotted 900 +seconds to run. A "medium" test with a timeout of "short" will be allotted 60 +seconds. + +Unlike `timeout`, the `size` additionally determines the assumed peak usage of +other resources (like RAM) when running the test locally, as described in +[Common definitions](/reference/be/common-definitions#common-attributes-tests). + +All combinations of `size` and `timeout` labels are legal, so an "enormous" test +may be declared to have a timeout of "short". Presumably it would do some really +horrible things very quickly. + +Tests may return arbitrarily fast regardless of timeout. A test is not penalized +for an overgenerous timeout, although a warning may be issued: you should +generally set your timeout as tight as you can without incurring any flakiness. + +The test timeout can be overridden with the `--test_timeout` bazel flag when +manually running under conditions that are known to be slow. The +`--test_timeout` values are in seconds. For example, `--test_timeout=120` +sets the test timeout to two minutes. + +There is also a recommended lower bound for test timeouts as follows: + +| timeout | Time minimum (sec.) | +|---------|---------------------| +| short | 0 | +| moderate | 30 | +| long | 300 | +| eternal | 900 | + +For example, if a "moderate" test completes in 5.5s, consider setting `timeout = +"short"` or `size = "small"`. Using the bazel `--test_verbose_timeout_warnings` +command line option will show the tests whose specified size is too big. + +Test sizes and timeouts are specified in the BUILD file according to the +specification [here](/reference/be/common-definitions#common-attributes-tests). If +unspecified, a test's size will default to "medium". + +If the main process of a test exits, but some of its children are still running, +the test runner should consider the run complete and count it as a success or +failure based on the exit code observed from the main process. The test runner +may kill any stray processes. Tests should not leak processes in this fashion. + +## Test sharding + +Tests can be parallelized via test sharding. See +[`--test_sharding_strategy`](/reference/command-line-reference#flag--test_sharding_strategy) +and [`shard_count`](/reference/be/common-definitions#common-attributes-tests) to +enable test sharding. When sharding is enabled, the test runner is launched once +per shard. The environment variable [`TEST_TOTAL_SHARDS`](#initial-conditions) +is the number of shards, and [`TEST_SHARD_INDEX`](#initial-conditions) is the +shard index, beginning at 0. Runners use this information to select which tests +to run - for example, using a round-robin strategy. Not all test runners support +sharding. If a runner supports sharding, it must create or update the last +modified date of the file specified by +[`TEST_SHARD_STATUS_FILE`](#initial-conditions). Otherwise, if +[`--incompatible_check_sharding_support`](/reference/command-line-reference#flag--incompatible_check_sharding_support) +is enabled, Bazel will fail the test if it is sharded. + +## Initial conditions + +When executing a test, the test runner must establish certain initial +conditions. + +The test runner must invoke each test with the path to the test executable in +`argv[0]`. This path must be relative and beneath the test's current directory +(which is in the runfiles tree, see below). The test runner should not pass any +other arguments to a test unless the user explicitly requests it. + +The initial environment block shall be composed as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableValueStatus
HOMEvalue of $TEST_TMPDIRrecommended
LANGunsetrequired
LANGUAGEunsetrequired
LC_ALLunsetrequired
LC_COLLATEunsetrequired
LC_CTYPEunsetrequired
LC_MESSAGESunsetrequired
LC_MONETARYunsetrequired
LC_NUMERICunsetrequired
LC_TIMEunsetrequired
LD_LIBRARY_PATHcolon-separated list of directories containing shared librariesoptional
JAVA_RUNFILESvalue of $TEST_SRCDIRdeprecated
LOGNAMEvalue of $USERrequired
PATH/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin:.recommended
PWD$TEST_SRCDIR/workspace-namerecommended
SHLVL2recommended
TEST_INFRASTRUCTURE_FAILURE_FILEabsolute path to a private file in a writable directory (This file + should only be used to report failures originating from the testing + infrastructure, not as a general mechanism for reporting flaky failures + of tests. In this context, testing infrastructure is defined as systems + or libraries that are not test-specific, but can cause test failures by + malfunctioning. The first line is the name of the testing infrastructure + component that caused the failure, the second one a human-readable + description of the failure. Additional lines are ignored.)optional
TEST_LOGSPLITTER_OUTPUT_FILEabsolute path to a private file in a writable directory (used to write + Logsplitter protobuffer log)optional
TEST_PREMATURE_EXIT_FILEabsolute path to a private file in a writable directory (used for + catching calls to exit())optional
TEST_RANDOM_SEEDIf the --runs_per_test option is used, + TEST_RANDOM_SEED is set to the run number + (starting with 1) for each individual test run.optional
TEST_RUN_NUMBERIf the --runs_per_test option is used, + TEST_RUN_NUMBER is set to the run number + (starting with 1) for each individual test run.optional
TEST_TARGETThe name of the target being testedoptional
TEST_SIZEThe test sizeoptional
TEST_TIMEOUTThe test timeout in secondsoptional
TEST_SHARD_INDEXshard index, if sharding is usedoptional
TEST_SHARD_STATUS_FILEpath to file to touch to indicate support for shardingoptional
TEST_SRCDIRabsolute path to the base of the runfiles treerequired
TEST_TOTAL_SHARDStotal + shard count, + if sharding is usedoptional
TEST_TMPDIRabsolute path to a private writable directoryrequired
TEST_WORKSPACEthe local repository's workspace nameoptional
TEST_UNDECLARED_OUTPUTS_DIRabsolute path to a private writable directory (used to write undeclared + test outputs). Any files written to the + TEST_UNDECLARED_OUTPUTS_DIR directory will be zipped up and + added to an outputs.zip file under + bazel-testlogs.optional
TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIRabsolute path to a private writable directory (used to write undeclared + test output annotation .part and .pb files).optional
TEST_WARNINGS_OUTPUT_FILEabsolute path to a private file in a writable directory (used to write + test target warnings)optional
TESTBRIDGE_TEST_ONLYvalue of + --test_filter, + if specifiedoptional
TZUTCrequired
USERvalue of getpwuid(getuid())->pw_namerequired
XML_OUTPUT_FILELocation to which test actions should write a test result XML output file. Otherwise, Bazel generates a default XML output file wrapping the test log as part of the test action. The XML schema is based on the JUnit test result schema.optional
BAZEL_TESTSignifies test executable is being driven by bazel testrequired
+ +The environment may contain additional entries. Tests should not depend on the +presence, absence, or value of any environment variable not listed above. + +The initial working directory shall be `$TEST_SRCDIR/$TEST_WORKSPACE`. + +The current process id, process group id, session id, and parent process id are +unspecified. The process may or may not be a process group leader or a session +leader. The process may or may not have a controlling terminal. The process may +have zero or more running or unreaped child processes. The process should not +have multiple threads when the test code gains control. + +File descriptor 0 (`stdin`) shall be open for reading, but what it is attached to +is unspecified. Tests must not read from it. File descriptors 1 (`stdout`) and 2 +(`stderr`) shall be open for writing, but what they are attached to is +unspecified. It could be a terminal, a pipe, a regular file, or anything else to +which characters can be written. They may share an entry in the open file table +(meaning that they cannot seek independently). Tests should not inherit any +other open file descriptors. + +The initial umask shall be `022` or `027`. + +No alarm or interval timer shall be pending. + +The initial mask of blocked signals shall be empty. All signals shall be set to +their default action. + +The initial resource limits, both soft and hard, should be set as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ResourceLimit
RLIMIT_ASunlimited
RLIMIT_COREunspecified
RLIMIT_CPUunlimited
RLIMIT_DATAunlimited
RLIMIT_FSIZEunlimited
RLIMIT_LOCKSunlimited
RLIMIT_MEMLOCKunlimited
RLIMIT_MSGQUEUEunspecified
RLIMIT_NICEunspecified
RLIMIT_NOFILEat least 1024
RLIMIT_NPROCunspecified
RLIMIT_RSSunlimited
RLIMIT_RTPRIOunspecified
RLIMIT_SIGPENDINGunspecified
RLIMIT_STACKunlimited, or 2044KB <= rlim <= 8192KB
+ +The initial process times (as returned by `times()`) and resource utilization +(as returned by `getrusage()`) are unspecified. + +The initial scheduling policy and priority are unspecified. + +## Role of the host system + +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 +properties for a test run to be valid. + +#### Filesystem + +The root directory observed by a test may or may not be the real root directory. + +`/proc` shall be mounted. + +All build tools shall be present at the absolute paths under `/usr` used by a +local installation. + +Paths starting with `/home` may not be available. Tests should not access any +such paths. + +`/tmp` shall be writable, but tests should avoid using these paths. + +Tests must not assume that any constant path is available for their exclusive +use. + +Tests must not assume that atimes are enabled for any mounted filesystem. + +#### Users and groups + +The users root, nobody, and unittest must exist. The groups root, nobody, and +eng must exist. + +Tests must be executed as a non-root user. The real and effective user ids must +be equal; likewise for group ids. Beyond this, the current user id, group id, +user name, and group name are unspecified. The set of supplementary group ids is +unspecified. + +The current user id and group id must have corresponding names which can be +retrieved with `getpwuid()` and `getgrgid()`. The same may not be true for +supplementary group ids. + +The current user must have a home directory. It may not be writable. Tests must +not attempt to write to it. + +#### Networking + +The hostname is unspecified. It may or may not contain a dot. Resolving the +hostname must give an IP address of the current host. Resolving the hostname cut +after the first dot must also work. The hostname localhost must resolve. + +#### Other resources + +Tests are granted at least one CPU core. Others may be available but this is not +guaranteed. Other performance aspects of this core are not specified. You can +increase the reservation to a higher number of CPU cores by adding the tag +"cpu:n" (where n is a positive number) to a test rule. If a machine has less +total CPU cores than requested, Bazel will still run the test. If a test uses +[sharding](#test-sharding), each individual shard will reserve the number of CPU +cores specified here. + +Tests may create subprocesses, but not process groups or sessions. + +There is a limit on the number of input files a test may consume. This limit is +subject to change, but is currently in the range of tens of thousands of inputs. + +#### Time and date + +The current time and date are unspecified. The system timezone is unspecified. + +X Windows may or may not be available. Tests that need an X server should start +Xvfb. + +## Test interaction with the filesystem + +All file paths specified in test environment variables point to somewhere on the +local filesystem, unless otherwise specified. + +Tests should create files only within the directories specified by +`$TEST_TMPDIR` and `$TEST_UNDECLARED_OUTPUTS_DIR` (if set). + +These directories will be initially empty. + +Tests must not attempt to remove, chmod, or otherwise alter these directories. + +These directories may be a symbolic links. + +The filesystem type of `$TEST_TMPDIR/.` remains unspecified. + +Tests may also write .part files to the +`$TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR` to annotate undeclared output files. + +In rare cases, a test may be forced to create files in `/tmp`. For example, +[path length limits for Unix domain sockets](https://serverfault.com/questions/641347) +typically require creating the socket under `/tmp`. Bazel will be unable to +track such files; the test itself must take care to be hermetic, to use unique +paths to avoid colliding with other, simultaneously running tests and non-test +processes, and to clean up the files it creates in `/tmp`. + +Some popular testing frameworks, such as +[JUnit4 `TemporaryFolder`](https://junit.org/junit4/javadoc/latest/org/junit/rules/TemporaryFolder.html) +or [Go `TempDir`](https://golang.org/pkg/testing/#T.TempDir), have +their own ways to create a temporary directory under `/tmp`. These testing +frameworks include functionality that cleans up files in `/tmp`, so you may use +them even though they create files outside of `TEST_TMPDIR`. + +Tests must access inputs through the **runfiles** mechanism, or other parts of +the execution environment which are specifically intended to make input files +available. + +Tests must not access other outputs of the build system at paths inferred from +the location of their own executable. + +It is unspecified whether the runfiles tree contains regular files, symbolic +links, or a mixture. The runfiles tree may contain symlinks to directories. +Tests should avoid using paths containing `..` components within the runfiles +tree. + +No directory, file, or symlink within the runfiles tree (including paths which +traverse symlinks) should be writable. (It follows that the initial working +directory should not be writable.) Tests must not assume that any part of the +runfiles is writable, or owned by the current user (for example, `chmod` and `chgrp` may +fail). + +The runfiles tree (including paths which traverse symlinks) must not change +during test execution. Parent directories and filesystem mounts must not change +in any way which affects the result of resolving a path within the runfiles +tree. + +In order to catch early exit, a test may create a file at the path specified by +`TEST_PREMATURE_EXIT_FILE` upon start and remove it upon exit. If Bazel sees the +file when the test finishes, it will assume that the test exited prematurely and +mark it as having failed. + +## Execution platform + +The [execution platform](/extending/platforms) for a test action is determined +via [toolchain resolution](/extending/toolchains#toolchain-resolution), just +like for any other action. Each test rule has an implicitly defined [ +`test` exec group](/extending/exec-groups#exec-groups-for-native-rules) that, +unless overridden, has a mandatory toolchain requirement on +`@bazel_tools//tools/test:default_test_toolchain_type`. Toolchains of this type +do not carry any data in the form of providers, but can be used to influence the +execution platform of the test action. By default, Bazel registers two such +toolchains: + +* If `--@bazel_tools//tools/test:incompatible_use_default_test_toolchain` is + disabled (the current default), the active test toolchain is + `@bazel_tools//tools/test:legacy_test_toolchain`. This toolchain does not + impose any constraints and thus test actions without manually specified exec + constraints are configured for the first registered execution platform. This + is often not the intended behavior in multi-platform builds as it can result + in e.g. a test binary built for Linux on a Windows machine to be executed on + Windows. +* If `--@bazel_tools//tools/test:incompatible_use_default_test_toolchain` is + enabled, the active test toolchain is + `@bazel_tools//tools/test:default_test_toolchain`. This toolchain requires an + execution platform to match all the constraints of the test rule's target + platform. In particular, the target platform is compatible with this toolchain + if it is also registered as an execution platform. If no such platform is + found, the test rule fails with a toolchain resolution error. + +Users can register additional toolchains for this type to influence this +behavior and their toolchains will take precedence over the default ones. +Test rule authors can define their own test toolchain type and also register +a default toolchain for it. + +## Tag conventions + +Some tags in the test rules have a special meaning. See also the +[Bazel Build Encyclopedia on the `tags` attribute](/reference/be/common-definitions#common.tags). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TagMeaning
exclusiverun no other test at the same time
externaltest has an external dependency; disable test caching
largetest_suite convention; suite of large tests
`manual *`don't include test target in wildcard target patterns like + :..., :*, or :all
mediumtest_suite convention; suite of medium tests
smalltest_suite convention; suite of small tests
smoketest_suite convention; means it should be run before + committing code changes into the version control system
+ +Note: bazel `query` does not respect the manual tag. + +## Runfiles + +In the following, assume there is a *_binary() rule labeled +`//foo/bar:unittest`, with a run-time dependency on the rule labeled +`//deps/server:server`. + +#### Location + +The runfiles directory for a target `//foo/bar:unittest` is the directory +`$(WORKSPACE)/$(BINDIR)/foo/bar/unittest.runfiles`. This path is referred to as +the `runfiles_dir`. + +#### Dependencies + +The runfiles directory is declared as a compile-time dependency of the +`*_binary()` rule. The runfiles directory itself depends on the set of BUILD +files that affect the `*_binary()` rule or any of its compile-time or run-time +dependencies. Modifying source files does not affect the structure of the +runfiles directory, and thus does not trigger any rebuilding. + +#### Contents + +The runfiles directory contains the following: + +* **Symlinks to run-time dependencies**: each OutputFile and CommandRule that + is a run-time dependency of the `*_binary()` rule is represented by one + symlink in the runfiles directory. The name of the symlink is + `$(WORKSPACE)/package_name/rule_name`. For example, the symlink for server + would be named `$(WORKSPACE)/deps/server/server`, and the full path would be + `$(WORKSPACE)/foo/bar/unittest.runfiles/$(WORKSPACE)/deps/server/server`. + The destination of the symlink is the OutputFileName() of the OutputFile or + CommandRule, expressed as an absolute path. Thus, the destination of the + symlink might be `$(WORKSPACE)/linux-dbg/deps/server/42/server`. + diff --git a/run/build.mdx b/run/build.mdx new file mode 100644 index 0000000..8d181e1 --- /dev/null +++ b/run/build.mdx @@ -0,0 +1,650 @@ +--- +title: 'Build programs with Bazel' +--- + + + +This page covers how to build a program with Bazel, build command syntax, and +target pattern syntax. + +## Quickstart + +To run Bazel, go to your base [workspace](/concepts/build-ref#workspace) directory +or any of its subdirectories and type `bazel`. See [build](#bazel-build) if you +need to make a new workspace. + +```posix-terminal +bazel help + [Bazel release bazel {{ "" }}version{{ "" }}] +Usage: bazel {{ "" }}command{{ "" }} {{ "" }}options{{ "" }} ... +``` + +### Available commands + +* [`analyze-profile`](/docs/user-manual#analyze-profile): Analyzes build profile data. +* [`aquery`](/docs/user-manual#aquery): Executes a query on the [post-analysis](#analysis) action graph. +* [`build`](#bazel-build): Builds the specified targets. +* [`canonicalize-flags`](/docs/user-manual#canonicalize-flags): Canonicalize Bazel flags. +* [`clean`](/docs/user-manual#clean): Removes output files and optionally stops the server. +* [`cquery`](/query/cquery): Executes a [post-analysis](#analysis) dependency graph query. +* [`dump`](/docs/user-manual#dump): Dumps the internal state of the Bazel server process. +* [`help`](/docs/user-manual#help): Prints help for commands, or the index. +* [`info`](/docs/user-manual#info): Displays runtime info about the bazel server. +* [`fetch`](#fetching-external-dependencies): Fetches all external dependencies of a target. +* [`mobile-install`](/docs/user-manual#mobile-install): Installs apps on mobile devices. +* [`query`](/query/guide): Executes a dependency graph query. +* [`run`](/docs/user-manual#running-executables): Runs the specified target. +* [`shutdown`](/docs/user-manual#shutdown): Stops the Bazel server. +* [`test`](/docs/user-manual#running-tests): Builds and runs the specified test targets. +* [`version`](/docs/user-manual#version): Prints version information for Bazel. + +### Getting help + +* `bazel help {{ '' }}command{{ '' }}`: Prints help and options for + `{{ '' }}command{{ '' }}`. +* `bazel help `[`startup_options`](/docs/user-manual#startup-options): Options for the JVM hosting Bazel. +* `bazel help `[`target-syntax`](#specifying-build-targets): Explains the syntax for specifying targets. +* `bazel help info-keys`: Displays a list of keys used by the info command. + +The `bazel` tool performs many functions, called commands. The most commonly +used ones are `bazel build` and `bazel test`. You can browse the online help +messages using `bazel help`. + + +### Building one target + +Before you can start a build, you need a _workspace_. A workspace is a +directory tree that contains all the source files needed to build your +application. Bazel allows you to perform a build from a completely read-only +volume. + +To build a program with Bazel, type `bazel build` followed by the +[target](#specifying-build-targets) you want to build. + +```posix-terminal +bazel build //foo +``` + +After issuing the command to build `//foo`, you'll see output similar to this: + +``` +INFO: Analyzed target //foo:foo (14 packages loaded, 48 targets configured). +INFO: Found 1 target... +Target //foo:foo up-to-date: + bazel-bin/foo/foo +INFO: Elapsed time: 9.905s, Critical Path: 3.25s +INFO: Build completed successfully, 6 total actions +``` + + +First, Bazel **loads** all packages in your target's dependency graph. This +includes _declared dependencies_, files listed directly in the target's `BUILD` +file, and _transitive dependencies_, files listed in the `BUILD` files of your +target's dependencies. After identifying all dependencies, Bazel **analyzes** +them for correctness and creates the _build actions_. Last, Bazel **executes** +the compilers and other tools of the build. + +During the build's execution phase, Bazel prints progress messages. The progress +messages include the current build step (such as, compiler or linker) as it +starts, and the number completed over the total number of build actions. As the +build starts, the number of total actions often increases as Bazel discovers +the entire action graph, but the number stabilizes within a few seconds. + +At the end of the build, Bazel prints which targets were requested, whether or +not they were successfully built, and if so, where the output files can be +found. Scripts that run builds can reliably parse this output; see +[`--show_result`](/docs/user-manual#show-result) for more details. + +If you type the same command again, the build finishes much faster. + +```posix-terminal +bazel build //foo +INFO: Analyzed target //foo:foo (0 packages loaded, 0 targets configured). +INFO: Found 1 target... +Target //foo:foo up-to-date: + bazel-bin/foo/foo +INFO: Elapsed time: 0.144s, Critical Path: 0.00s +INFO: Build completed successfully, 1 total action +``` + +This is a _null build_. Because nothing changed, there are no packages to reload +and no build steps to execute. If something changed in 'foo' or its +dependencies, Bazel would re-execute some build actions, or complete an +_incremental build_. + +### Building multiple targets + +Bazel allows a number of ways to specify the targets to be built. Collectively, +these are known as _target patterns_. This syntax is used in commands like +`build`, `test`, or `query`. + +Whereas [labels](/concepts/labels) are used to specify individual +targets, such as for declaring dependencies in `BUILD` files, Bazel's target +patterns specify multiple targets. Target patterns are a generalization of the +label syntax for _sets_ of targets, using wildcards. In the simplest case, any +valid label is also a valid target pattern, identifying a set of exactly one +target. + +All target patterns starting with `//` are resolved relative to the current +workspace. + + All rule targets in packages in the main repository. Does not include targets + from external repositories. + All rule targets in the top-level package, if there is a `BUILD` file at the + root of the workspace. +| Pattern | Description | +|---------|-------------| +| | Just the single target //foo/bar:wiz. | +| | Equivalent to //foo/bar:bar. | +| | All rule targets in the package foo/bar. | +| | All rule targets in all packages beneath the directory foo. | +| | All rule targets in all packages beneath the directory foo. | +| | All targets (rules and files) in all packages beneath the directory foo. | +| | All targets (rules and files) in all packages beneath the directory foo. | + + +Target patterns that do not begin with `//` are resolved relative to the +current _working directory_. These examples assume a working directory of `foo`: + +| Pattern | Description | +|---------|-------------| +| | Equivalent to //foo:foo. | +| | Equivalent to //foo/bar:wiz. | +| | Equivalent to: if foo/bar/wiz is a package; if foo/bar is a package; otherwise | +| | Equivalent to //foo/bar:all. | +| | Equivalent to //foo:all. | +| | Equivalent to //foo/...:all. | +| | Equivalent to //foo/...:all. | +| | Equivalent to //foo/bar/...:all. | + + +By default, directory symlinks are followed for recursive target patterns, +except those that point to under the output base, such as the convenience +symlinks that are created in the root directory of the workspace. + +In addition, Bazel does not follow symlinks when evaluating recursive target +patterns in any directory that contains a file named as follows: +`DONT_FOLLOW_SYMLINKS_WHEN_TRAVERSING_THIS_DIRECTORY_VIA_A_RECURSIVE_TARGET_PATTERN` + +`foo/...` is a wildcard over _packages_, indicating all packages recursively +beneath directory `foo` (for all roots of the package path). `:all` is a +wildcard over _targets_, matching all rules within a package. These two may be +combined, as in `foo/...:all`, and when both wildcards are used, this may be +abbreviated to `foo/...`. + +In addition, `:*` (or `:all-targets`) is a wildcard that matches _every target_ +in the matched packages, including files that aren't normally built by any rule, +such as `_deploy.jar` files associated with `java_binary` rules. + +This implies that `:*` denotes a _superset_ of `:all`; while potentially +confusing, this syntax does allow the familiar `:all` wildcard to be used for +typical builds, where building targets like the `_deploy.jar` is not desired. + +In addition, Bazel allows a slash to be used instead of the colon required by +the label syntax; this is often convenient when using Bash filename expansion. +For example, `foo/bar/wiz` is equivalent to `//foo/bar:wiz` (if there is a +package `foo/bar`) or to `//foo:bar/wiz` (if there is a package `foo`). + +Many Bazel commands accept a list of target patterns as arguments, and they all +honor the prefix negation operator `-`. This can be used to subtract a set of +targets from the set specified by the preceding arguments. Note that this means +order matters. For example, + +```posix-terminal +bazel build foo/... bar/... +``` + +means "build all targets beneath `foo` _and_ all targets beneath `bar`", whereas + +```posix-terminal +bazel build -- foo/... -foo/bar/... +``` + +means "build all targets beneath `foo` _except_ those beneath `foo/bar`". (The +`--` argument is required to prevent the subsequent arguments starting with `-` +from being interpreted as additional options.) + +It's important to point out though that subtracting targets this way will not +guarantee that they are not built, since they may be dependencies of targets +that weren't subtracted. For example, if there were a target `//foo:all-apis` +that among others depended on `//foo/bar:api`, then the latter would be built as +part of building the former. + +Targets with `tags = ["manual"]` are not included in wildcard target patterns +(`...`, `:*`, `:all`, etc.) when specified in commands like +`bazel build` and `bazel test` (but they are included in +negative wildcard target patterns, that is they will be subtracted). You should +specify such test targets with explicit target patterns on the command line if +you want Bazel to build/test them. In contrast, `bazel query` doesn't perform +any such filtering automatically (that would defeat the purpose of +`bazel query`). + +### Fetching external dependencies + +By default, Bazel will download and symlink external dependencies during the +build. However, this can be undesirable, either because you'd like to know +when new external dependencies are added or because you'd like to +"prefetch" dependencies (say, before a flight where you'll be offline). If you +would like to prevent new dependencies from being added during builds, you +can specify the `--fetch=false` flag. Note that this flag only +applies to repository rules that do not point to a directory in the local +file system. Changes, for example, to `local_repository`, +`new_local_repository` and Android SDK and NDK repository rules +will always take effect regardless of the value `--fetch` . + +If you disallow fetching during builds and Bazel finds new external +dependencies, your build will fail. + +You can manually fetch dependencies by running `bazel fetch`. If +you disallow during-build fetching, you'll need to run `bazel fetch`: + +- Before you build for the first time. +- After you add a new external dependency. + +Once it has been run, you should not need to run it again until the MODULE.bazel +file changes. + +`fetch` takes a list of targets to fetch dependencies for. For +example, this would fetch dependencies needed to build `//foo:bar` +and `//bar:baz`: + +```posix-terminal +bazel fetch //foo:bar //bar:baz +``` + +To fetch all external dependencies for a workspace, run: + +```posix-terminal +bazel fetch //... +``` + +With Bazel 7 or later, if you have Bzlmod enabled, you can also fetch all +external dependencies by running + +```posix-terminal +bazel fetch +``` + +You do not need to run bazel fetch at all if you have all of the tools you are +using (from library jars to the JDK itself) under your workspace root. +However, if you're using anything outside of the workspace directory then Bazel +will automatically run `bazel fetch` before running +`bazel build`. + +#### The repository cache + +Bazel tries to avoid fetching the same file several times, even if the same +file is needed in different workspaces, or if the definition of an external +repository changed but it still needs the same file to download. To do so, +bazel caches all files downloaded in the repository cache which, by default, +is located at `~/.cache/bazel/_bazel_$USER/cache/repos/v1/`. The +location can be changed by the `--repository_cache` option. The +cache is shared between all workspaces and installed versions of bazel. +An entry is taken from the cache if +Bazel knows for sure that it has a copy of the correct file, that is, if the +download request has a SHA256 sum of the file specified and a file with that +hash is in the cache. So specifying a hash for each external file is +not only a good idea from a security perspective; it also helps avoiding +unnecessary downloads. + +Upon each cache hit, the modification time of the file in the cache is +updated. In this way, the last use of a file in the cache directory can easily +be determined, for example to manually clean up the cache. The cache is never +cleaned up automatically, as it might contain a copy of a file that is no +longer available upstream. + +#### [Deprecated] Distribution files directories + +**Deprecated**: *Using repository cache is preferred to achieve offline build.* + +The distribution directory is another Bazel mechanism to avoid unnecessary +downloads. Bazel searches distribution directories before the repository cache. +The primary difference is that the distribution directory requires manual +preparation. + +Using the +[`--distdir=/path/to-directory`](/reference/command-line-reference#flag--distdir) +option, you can specify additional read-only directories to look for files +instead of fetching them. A file is taken from such a directory if the file name +is equal to the base name of the URL and additionally the hash of the file is +equal to the one specified in the download request. This only works if the +file hash is specified in the repo rule declaration. + +While the condition on the file name is not necessary for correctness, it +reduces the number of candidate files to one per specified directory. In this +way, specifying distribution files directories remains efficient, even if the +number of files in such a directory grows large. + +#### Running Bazel in an airgapped environment + +To keep Bazel's binary size small, Bazel's implicit dependencies are fetched +over the network while running for the first time. These implicit dependencies +contain toolchains and rules that may not be necessary for everyone. For +example, Android tools are unbundled and fetched only when building Android +projects. + +However, these implicit dependencies may cause problems when running Bazel in an +airgapped environment, even if you have vendored all of your external +dependencies. To solve that, you can prepare a repository cache (with Bazel 7 or +later) or distribution directory (with Bazel prior to 7) containing these +dependencies on a machine with network access, and then transfer them to the +airgapped environment with an offline approach. + +##### Repository cache (with Bazel 7 or later) + +To prepare the [repository cache](#repository-cache), use the +[`--repository_cache`](/reference/command-line-reference#flag--repository_cache) +flag. You will need to do this once for every new Bazel binary version, since +the implicit dependencies can be different for every release. + +To fetch those dependencies outside of your airgapped environment, first create +an empty workspace: + +```posix-terminal +mkdir empty_workspace && cd empty_workspace + +touch MODULE.bazel +``` + +To fetch built-in Bzlmod dependencies, run + +```posix-terminal +bazel fetch --repository_cache="path/to/repository/cache" +``` + +If you still rely on the legacy WORKSPACE file, to fetch built-in WORKSPACE +dependencies, run + +```posix-terminal +bazel sync --repository_cache="path/to/repository/cache" +``` + +Finally, when you use Bazel in your airgapped environment, pass the same +`--repository_cache` flag. For convenience, you can add it as an `.bazelrc` +entry: + +```python +common --repository_cache="path/to/repository/cache" +``` + +In addition, you may also need to clone the +[BCR](https://github.com/bazelbuild/bazel-central-registry) locally and use +`--registry` flag to point your local copy to prevent Bazel from accessing the +BCR through internet. Add the following line to your `.bazelrc`: + +```python +common --registry="path/to/local/bcr/registry" +``` + +##### Distribution directory (with Bazel prior to 7) + +To prepare the [distribution directory](#distribution-directory), use the +[`--distdir`](/reference/command-line-reference#flag--distdir) +flag. You will need to do this once for every new Bazel binary version, since +the implicit dependencies can be different for every release. + +To build these dependencies outside of your airgapped environment, first +checkout the Bazel source tree at the right version: + +```posix-terminal +git clone https://github.com/bazelbuild/bazel "$BAZEL_DIR" + +cd "$BAZEL_DIR" + +git checkout "$BAZEL_VERSION" +``` + +Then, build the tarball containing the implicit runtime dependencies for that +specific Bazel version: + +```posix-terminal +bazel build @additional_distfiles//:archives.tar +``` + +Export this tarball to a directory that can be copied into your airgapped +environment. Note the `--strip-components` flag, because `--distdir` can be +quite finicky with the directory nesting level: + +```posix-terminal +tar xvf bazel-bin/external/additional_distfiles/archives.tar \ + -C "$NEW_DIRECTORY" --strip-components=3 +``` + +Finally, when you use Bazel in your airgapped environment, pass the `--distdir` +flag pointing to the directory. For convenience, you can add it as an `.bazelrc` +entry: + +```posix-terminal +build --distdir={{ '' }}path{{ '' }}/to/{{ '' }}directory{{ '' }} +``` + +### Build configurations and cross-compilation + +All the inputs that specify the behavior and result of a given build can be +divided into two distinct categories. The first kind is the intrinsic +information stored in the `BUILD` files of your project: the build rule, the +values of its attributes, and the complete set of its transitive dependencies. +The second kind is the external or environmental data, supplied by the user or +by the build tool: the choice of target architecture, compilation and linking +options, and other toolchain configuration options. We refer to a complete set +of environmental data as a **configuration**. + +In any given build, there may be more than one configuration. Consider a +cross-compile, in which you build a `//foo:bin` executable for a 64-bit +architecture, but your workstation is a 32-bit machine. Clearly, the build will +require building `//foo:bin` using a toolchain capable of creating 64-bit +executables, but the build system must also build various tools used during the +build itself—for example tools that are built from source, then subsequently +used in, say, a genrule—and these must be built to run on your workstation. Thus +we can identify two configurations: the **exec configuration**, which is used +for building tools that run during the build, and the **target configuration** +(or _request configuration_, but we say "target configuration" more often even +though that word already has many meanings), which is used for building the +binary you ultimately requested. + +Typically, there are many libraries that are prerequisites of both the requested +build target (`//foo:bin`) and one or more of the exec tools, for example some +base libraries. Such libraries must be built twice, once for the exec +configuration, and once for the target configuration. Bazel takes care of +ensuring that both variants are built, and that the derived files are kept +separate to avoid interference; usually such targets can be built concurrently, +since they are independent of each other. If you see progress messages +indicating that a given target is being built twice, this is most likely the +explanation. + +The exec configuration is derived from the target configuration as follows: + +- Use the same version of Crosstool (`--crosstool_top`) as specified in the + request configuration, unless `--host_crosstool_top` is specified. +- Use the value of `--host_cpu` for `--cpu` (default: `k8`). +- Use the same values of these options as specified in the request + configuration: `--compiler`, `--use_ijars`, and if `--host_crosstool_top` is + used, then the value of `--host_cpu` is used to look up a + `default_toolchain` in the Crosstool (ignoring `--compiler`) for the exec + configuration. +- Use the value of `--host_javabase` for `--javabase` +- Use the value of `--host_java_toolchain` for `--java_toolchain` +- Use optimized builds for C++ code (`-c opt`). +- Generate no debugging information (`--copt=-g0`). +- Strip debug information from executables and shared libraries + (`--strip=always`). +- Place all derived files in a special location, distinct from that used by + any possible request configuration. +- Suppress stamping of binaries with build data (see `--embed_*` options). +- All other values remain at their defaults. + +There are many reasons why it might be preferable to select a distinct exec +configuration from the request configuration. Most importantly: + +Firstly, by using stripped, optimized binaries, you reduce the time spent +linking and executing the tools, the disk space occupied by the tools, and the +network I/O time in distributed builds. + +Secondly, by decoupling the exec and request configurations in all builds, you +avoid very expensive rebuilds that would result from minor changes to the +request configuration (such as changing a linker options does), as described +earlier. + +### Correct incremental rebuilds + +One of the primary goals of the Bazel project is to ensure correct incremental +rebuilds. Previous build tools, especially those based on Make, make several +unsound assumptions in their implementation of incremental builds. + +Firstly, that timestamps of files increase monotonically. While this is the +typical case, it is very easy to fall afoul of this assumption; syncing to an +earlier revision of a file causes that file's modification time to decrease; +Make-based systems will not rebuild. + +More generally, while Make detects changes to files, it does not detect changes +to commands. If you alter the options passed to the compiler in a given build +step, Make will not re-run the compiler, and it is necessary to manually discard +the invalid outputs of the previous build using `make clean`. + +Also, Make is not robust against the unsuccessful termination of one of its +subprocesses after that subprocess has started writing to its output file. While +the current execution of Make will fail, the subsequent invocation of Make will +blindly assume that the truncated output file is valid (because it is newer than +its inputs), and it will not be rebuilt. Similarly, if the Make process is +killed, a similar situation can occur. + +Bazel avoids these assumptions, and others. Bazel maintains a database of all +work previously done, and will only omit a build step if it finds that the set +of input files (and their timestamps) to that build step, and the compilation +command for that build step, exactly match one in the database, and, that the +set of output files (and their timestamps) for the database entry exactly match +the timestamps of the files on disk. Any change to the input files or output +files, or to the command itself, will cause re-execution of the build step. + +The benefit to users of correct incremental builds is: less time wasted due to +confusion. (Also, less time spent waiting for rebuilds caused by use of `make +clean`, whether necessary or pre-emptive.) + +#### Build consistency and incremental builds + +Formally, we define the state of a build as _consistent_ when all the expected +output files exist, and their contents are correct, as specified by the steps or +rules required to create them. When you edit a source file, the state of the +build is said to be _inconsistent_, and remains inconsistent until you next run +the build tool to successful completion. We describe this situation as _unstable +inconsistency_, because it is only temporary, and consistency is restored by +running the build tool. + +There is another kind of inconsistency that is pernicious: _stable +inconsistency_. If the build reaches a stable inconsistent state, then repeated +successful invocation of the build tool does not restore consistency: the build +has gotten "stuck", and the outputs remain incorrect. Stable inconsistent states +are the main reason why users of Make (and other build tools) type `make clean`. +Discovering that the build tool has failed in this manner (and then recovering +from it) can be time consuming and very frustrating. + +Conceptually, the simplest way to achieve a consistent build is to throw away +all the previous build outputs and start again: make every build a clean build. +This approach is obviously too time-consuming to be practical (except perhaps +for release engineers), and therefore to be useful, the build tool must be able +to perform incremental builds without compromising consistency. + +Correct incremental dependency analysis is hard, and as described above, many +other build tools do a poor job of avoiding stable inconsistent states during +incremental builds. In contrast, Bazel offers the following guarantee: after a +successful invocation of the build tool during which you made no edits, the +build will be in a consistent state. (If you edit your source files during a +build, Bazel makes no guarantee about the consistency of the result of the +current build. But it does guarantee that the results of the _next_ build will +restore consistency.) + +As with all guarantees, there comes some fine print: there are some known ways +of getting into a stable inconsistent state with Bazel. We won't guarantee to +investigate such problems arising from deliberate attempts to find bugs in the +incremental dependency analysis, but we will investigate and do our best to fix +all stable inconsistent states arising from normal or "reasonable" use of the +build tool. + +If you ever detect a stable inconsistent state with Bazel, please report a bug. + +#### Sandboxed execution + +Note: Sandboxing is enabled by default for local execution. + +Bazel uses sandboxes to guarantee that actions run hermetically and +correctly. Bazel runs _spawns_ (loosely speaking: actions) in sandboxes that +only contain the minimal set of files the tool requires to do its job. Currently +sandboxing works on Linux 3.12 or newer with the `CONFIG_USER_NS` option +enabled, and also on macOS 10.11 or newer. + +Bazel will print a warning if your system does not support sandboxing to alert +you to the fact that builds are not guaranteed to be hermetic and might affect +the host system in unknown ways. To disable this warning you can pass the +`--ignore_unsupported_sandboxing` flag to Bazel. + +Note: Hermeticity means that the action only uses its declared input +files and no other files in the filesystem, and it only produces its declared +output files. See [Hermeticity](/basics/hermeticity) for more details. + +On some platforms such as [Google Kubernetes +Engine](https://cloud.google.com/kubernetes-engine/) cluster nodes or Debian, +user namespaces are deactivated by default due to security +concerns. This can be checked by looking at the file +`/proc/sys/kernel/unprivileged_userns_clone`: if it exists and contains a 0, +then user namespaces can be activated with +`sudo sysctl kernel.unprivileged_userns_clone=1`. + +In some cases, the Bazel sandbox fails to execute rules because of the system +setup. The symptom is generally a failure that output a message similar to +`namespace-sandbox.c:633: execvp(argv[0], argv): No such file or directory`. +In that case, try to deactivate the sandbox for genrules with +`--strategy=Genrule=standalone` and for other rules with +`--spawn_strategy=standalone`. Also please report a bug on our +issue tracker and mention which Linux distribution you're using so that we can +investigate and provide a fix in a subsequent release. + +### Phases of a build + +In Bazel, a build occurs in three distinct phases; as a user, understanding the +difference between them provides insight into the options which control a build +(see below). + +#### Loading phase + +The first is **loading** during which all the necessary BUILD files for the +initial targets, and their transitive closure of dependencies, are loaded, +parsed, evaluated and cached. + +For the first build after a Bazel server is started, the loading phase typically +takes many seconds as many BUILD files are loaded from the file system. In +subsequent builds, especially if no BUILD files have changed, loading occurs +very quickly. + +Errors reported during this phase include: package not found, target not found, +lexical and grammatical errors in a BUILD file, and evaluation errors. + +#### Analysis phase + +The second phase, **analysis**, involves the semantic analysis and validation of +each build rule, the construction of a build dependency graph, and the +determination of exactly what work is to be done in each step of the build. + +Like loading, analysis also takes several seconds when computed in its entirety. +However, Bazel caches the dependency graph from one build to the next and only +reanalyzes what it has to, which can make incremental builds extremely fast in +the case where the packages haven't changed since the previous build. + +Errors reported at this stage include: inappropriate dependencies, invalid +inputs to a rule, and all rule-specific error messages. + +The loading and analysis phases are fast because Bazel avoids unnecessary file +I/O at this stage, reading only BUILD files in order to determine the work to be +done. This is by design, and makes Bazel a good foundation for analysis tools, +such as Bazel's [query](/query/guide) command, which is implemented atop the loading +phase. + +#### Execution phase + +The third and final phase of the build is **execution**. This phase ensures that +the outputs of each step in the build are consistent with its inputs, re-running +compilation/linking/etc. tools as necessary. This step is where the build spends +the majority of its time, ranging from a few seconds to over an hour for a large +build. Errors reported during this phase include: missing source files, errors +in a tool executed by some build action, or failure of a tool to produce the +expected set of outputs. +