diff --git a/community/images/Bitrise.png b/community/images/Bitrise.png index 07f85f1ec..e69de29bb 100644 Binary files a/community/images/Bitrise.png and b/community/images/Bitrise.png differ diff --git a/community/images/Gradle.png b/community/images/Gradle.png index 1e5f5eb01..e69de29bb 100644 Binary files a/community/images/Gradle.png and b/community/images/Gradle.png differ diff --git a/community/images/JetBrains.png b/community/images/JetBrains.png index 0f22176d9..e69de29bb 100644 Binary files a/community/images/JetBrains.png and b/community/images/JetBrains.png differ diff --git a/community/images/Linkedin-Logo.png b/community/images/Linkedin-Logo.png index 9dd8715c1..e69de29bb 100644 Binary files a/community/images/Linkedin-Logo.png and b/community/images/Linkedin-Logo.png differ diff --git a/community/images/aspect-logo-2.png b/community/images/aspect-logo-2.png index dfebc4cb6..e69de29bb 100644 Binary files a/community/images/aspect-logo-2.png and b/community/images/aspect-logo-2.png differ diff --git a/community/images/bitrise-logo.png b/community/images/bitrise-logo.png index 27037ce62..e69de29bb 100644 Binary files a/community/images/bitrise-logo.png and b/community/images/bitrise-logo.png differ diff --git a/community/images/develocity.png b/community/images/develocity.png index eb3eb65a7..e69de29bb 100644 Binary files a/community/images/develocity.png and b/community/images/develocity.png differ diff --git a/community/images/dropbox.png b/community/images/dropbox.png index 125476a66..e69de29bb 100644 Binary files a/community/images/dropbox.png and b/community/images/dropbox.png differ diff --git a/community/images/epam-logo.png b/community/images/epam-logo.png index e6a5674cf..e69de29bb 100644 Binary files a/community/images/epam-logo.png and b/community/images/epam-logo.png differ diff --git a/community/images/flare-logo.png b/community/images/flare-logo.png index 84cb0e5b8..e69de29bb 100644 Binary files a/community/images/flare-logo.png and b/community/images/flare-logo.png differ diff --git a/community/images/liulishuo.png b/community/images/liulishuo.png index a6758e5ca..e69de29bb 100644 Binary files a/community/images/liulishuo.png and b/community/images/liulishuo.png differ diff --git a/community/images/oasis-logo.png b/community/images/oasis-logo.png index 846a9cd56..e69de29bb 100644 Binary files a/community/images/oasis-logo.png and b/community/images/oasis-logo.png differ diff --git a/community/images/sumglobal-logo.png b/community/images/sumglobal-logo.png index 6736328dc..e69de29bb 100644 Binary files a/community/images/sumglobal-logo.png and b/community/images/sumglobal-logo.png differ diff --git a/community/images/tweag-logo.png b/community/images/tweag-logo.png index 20210ed75..e69de29bb 100644 Binary files a/community/images/tweag-logo.png and b/community/images/tweag-logo.png differ diff --git a/community/images/typedb.png b/community/images/typedb.png index 48ce1056b..e69de29bb 100644 Binary files a/community/images/typedb.png and b/community/images/typedb.png differ diff --git a/community/partners.mdx b/community/partners.mdx index e27198dc7..44b8724a0 100644 --- a/community/partners.mdx +++ b/community/partners.mdx @@ -34,28 +34,24 @@ EngFlow is the build and test acceleration company created by core Bazel enginee Develocity is a multi-build-system platform for improving developer productivity and happiness. It does this by providing a comprehensive and end-to-end solution for build & test observability, acceleration, and failure analytics, and currently supports the Bazel, Apache Maven, Gradle, and SBT build systems. Specifically, Develocity for Bazel supports Build Cache to speed up build and test feedback cycles; Build Scan® that is like an X-ray for your build to make troubleshooting more efficient; and Failure Analytics to improve toolchain reliability. - -JetBrains is a leading provider of IDEs and developer tools. Since 2022, we’ve been active in the Bazel community, delivering robust polyglot support through plugins for CLion, GoLand, PyCharm, and IntelliJ IDEA. These plugins provide deep Bazel integration for large projects, enabling editing, navigation, testing, and debugging across multiple languages, including C++, Go, Python, Java, Kotlin, Scala, as well as Starlark and other configuration files. + +Tweag is one of Bazel's earliest adopters, an active contributor of new features and new open source extensions since early 2018. We have been helping companies and teams achieve near byte-for-byte reproducibility, fully traceable all the way to production and conveniently auditable builds that can be cached correctly and run fast. Besides our consulting work, we also have an array of tools and extensions. Skyscope to visualize and explore complex Bazel build graphs with hundreds of thousands of nodes in your web browser. Open source Bazel extensions to achieve fully reproducible builds with the power of Nix, manage shell tools in a principled way, and build Haskell projects with Bazel. Finally, our open source Gazelle extensions to automate your Bazel migration and build maintenance. - -Tweag is one of Bazel's earliest adopters, an active contributor of new features and new open source extensions since early 2018. We have been helping companies and teams achieve near byte-for-byte reproducibility, fully traceable all the way to production and conveniently auditable builds that can be cached correctly and run fast. Besides our consulting work, we also have an array of tools and extensions. Skyscope to visualize and explore complex Bazel build graphs with hundreds of thousands of nodes in your web browser. Open source Bazel extensions to achieve fully reproducible builds with the power of Nix, manage shell tools in a principled way, and build Haskell projects with Bazel. Finally, our open source Gazelle extensions to automate your Bazel migration and build maintenance. - - NativeLink is the 100% free, open source, and permissively licensed build and test acceleration project written in Rust. It is created by a team of open source maintainers and the company is funded by Wellington Management, an asset manager with over one trillion dollars under management. Whether deployed on your infrastructure or on NativeLink’s cloud, our global Bazel, Reclient, and compiler experts provide 24x7 coverage, support small and large teams, and SSO included. - - - VirtusLab specializes in managing monorepos and migrating codebases to Bazel. We offer a smooth transition that enhances your software’s creation, testing, and release processes. Our engineers will assist you in adopting industry-standard tooling and practices, including top-tier security measures. We believe that a seamless Developer Experience requires great tooling. By partnering with us, you will optimize build times, reduce costs, and empower your development teams to reach their peak performance. + + + Based in San Francisco and Sydney, Buildkite is a fast-growing software delivery provider that offers the industry’s first and only Scale-Out Delivery Platform. Buildkite's Scale-Out Delivery platform is the only solution that provides the flexibility and scale required by the world's most demanding companies for delivering software across a broad range of use cases, including AI/ML workloads and mobile application development. Global innovation leaders including Airbnb, Block, Canva, Cruise, Culture Amp, Elastic, Lyft, PagerDuty, Pinterest, PlanetScale, Rippling, Shopify, Slack, Tinder, Twilio, Uber, and Wayfair have standardized on Buildkite for software delivery. Buildkite delivers seamless Bazel integration, enabling teams to scale CI/CD for complex monorepos. Buildkite sponsors CI for the Bazel project as part of its commitment to developers, driving faster builds and broader adoption. diff --git a/community/users.mdx b/community/users.mdx index c90fefb27..ce0df6454 100644 --- a/community/users.mdx +++ b/community/users.mdx @@ -51,7 +51,7 @@ ASML is an innovation leader in the semiconductor industry. We provide chipmaker with everything they need – hardware, software and services – to mass produce patterns on silicon through lithography. -### [Augment Code](https://augmentcode.com) +### [Augment Code](https://augmentcode.com){: .external} Augment Code is the first Developer AI for teams. Every Augment feature is context aware. Every suggestion, completion, and @@ -223,6 +223,11 @@ creating huge simulations inhabited by millions of complex entities. InteraXon is a thought-controlled computing firm that creates hardware and software platforms to convert brainwaves into digital signals. +## [JetBrains](https://www.jetbrains.com/) + + +JetBrains is a leading provider of IDEs and developer tools. Since 2022, we’ve been active in the Bazel community, delivering robust polyglot support through plugins for CLion, GoLang, PyCharm, and IntelliJ IDEA. We also use Bazel internally to build these products from our own large-scale monorepo. + ### [Jupiter](https://jupiter.co/) Jupiter is a company that provides delivery of groceries and household @@ -747,4 +752,4 @@ architecture. ### [ZhihuDailyPurify](https://github.com/izzyleung/ZhihuDailyPurify) ZhihuDailyPurify is a light weight version of Zhihu Daily, a Chinese -question-and-answer webs. +question-and-answer webs. \ No newline at end of file diff --git a/concepts/build-files.mdx b/concepts/build-files.mdx new file mode 100644 index 000000000..33087dc45 --- /dev/null +++ b/concepts/build-files.mdx @@ -0,0 +1,152 @@ +--- +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/){: .external}. + +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. + + + + + + +
+ Labels + + 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 000000000..d3fcb71e6 --- /dev/null +++ b/concepts/dependencies.mdx @@ -0,0 +1,375 @@ +--- +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`. + + + + + + + + + + + + + + + + + + + + + + +
a/BUILDb/BUILD
+ 
rule(
+    name = "a",
+    srcs = "a.in",
+    deps = "//b:b",
+)
+
+ 		+ 
+rule(
+    name = "b",
+    srcs = "b.in",
+    deps = "//c:c",
+)
+
+
a / a.inb / b.in
+import b;
+b.foo();
+
+ 		+ 
+import c;
+function foo() {
+  c.bar();
+}
+
+
+
+ Declared dependency graph with arrows connecting a, b, and c +
Declared dependency graph
+
+ 		+
+ Actual dependency graph that matches the declared dependency + graph with arrows connecting a, b, and c +
Actual dependency graph
+
+
+ +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`. + + + + + + + + + + + + + + +
a / a.in 
+ 
+        import b;
+        import c;
+        b.foo();
+        c.garply();
+
+ 		 
+
+ Declared dependency graph with arrows connecting a, b, and c +
Declared dependency graph
+
+ 		+
+ 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 +
Actual dependency graph
+
+
+ +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. + + + + + + + + + + + + + + + + + + + + + + +
 b/BUILD
  + 
rule(
+    name = "b",
+    srcs = "b.in",
+    deps = "//d:d",
+)
+
+
 b / b.in
  + 
+      import d;
+      function foo() {
+        d.baz();
+      }
+
+
+
+ Declared dependency graph with arrows connecting a and b. + b no longer connects to c, which breaks a's connection to c +
Declared dependency graph
+
+ 		+
+ Actual dependency graph that shows a connecting to b and c, + but b no longer connects to c +
Actual dependency graph
+
+
+ +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. + + + + + + +
+ BUILD files + + Visibility +
+ diff --git a/concepts/labels.mdx b/concepts/labels.mdx new file mode 100644 index 000000000..caf82faf7 --- /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. + + + + + + +
+ Targets + + BUILD files +
diff --git a/concepts/runfiles.mdx b/concepts/runfiles.mdx index 9d5449b41..298e4b172 100644 --- a/concepts/runfiles.mdx +++ b/concepts/runfiles.mdx @@ -2,15 +2,9 @@ title: 'Runfiles' --- +[Runfiles are a set of files used by a target at runtime (as opposed to build time)](/extending/rules#runfiles). - -[Runfiles are a set of files used by a target at runtime (as opposed to build -time)](/extending/rules#runfiles). - -Do not hardcode runfiles paths. Those contain the -[canonical repository name](/external/overview#canonical-repo-name), but -[the canonical repository name format is an implementation detail that may -change at any time](/external/module#repository_names_and_strict_deps). +Do not hardcode runfiles paths. Those contain the [canonical repository name](/external/overview#canonical-repo-name), but [the canonical repository name format is an implementation detail that may change at any time](/external/module#repository_names_and_strict_deps). Use one of the language-specific runfiles libraries to access them: @@ -19,24 +13,17 @@ Use one of the language-specific runfiles libraries to access them: - [rules_python](https://github.com/bazel-contrib/rules_python/blob/main/python/runfiles/runfiles.py) - [rules_shell](https://github.com/bazelbuild/rules_shell/blob/main/shell/runfiles/runfiles.bash) -Runfiles are generally referenced by an `rlocationpath` in the form of -`$REPO/package/file` where `$REPO` should be the -[apparent repository name](/external/overview#apparent-repo-name). -Most runfiles libraries (see below) support functionality to determine the -repository of the currently executed target which is useful to refer to other -files in the same repository. Many Bazel rules support -[Make Variables](/reference/be/make-variables#predefined_label_variables) -to translate from a target to an rlocationpath by using the -`$(rlocationpath //package:target)` notation. +Runfiles are generally referenced by an `rlocationpath` in the form of `$REPO/package/file` where `$REPO` should be the [apparent repository name](/external/overview#apparent-repo-name). +Most runfiles libraries (see below) support functionality to determine the repository of the currently executed target which is useful to refer to other files in the same repository. +Many Bazel rules support [Make Variables](/reference/be/make-variables#predefined_label_variables) to translate from a target to an rlocationpath by using the `$(rlocationpath //package:target)` notation. Examples: -
- -
-

C++

+ - ``` + + +```python load("@rules_cc//cc:cc_binary.bzl", "cc_binary") cc_binary( @@ -47,11 +34,11 @@ cc_binary( ) ``` - ``` -#include <filesystem> -#include <fstream> -#include <iostream> -#include <string> +```cpp +#include +#include +#include +#include #include "rules_cc/cc/runfiles/runfiles.h" @@ -82,12 +69,11 @@ int main(int argc, char **argv) { return 0; } - ``` -
-
-

Golang

+``` + + - ``` +```python load("@rules_go//go:def.bzl", "go_binary") go_binary( @@ -98,7 +84,7 @@ go_binary( ) ``` - ``` + ```go package main import ( @@ -138,12 +124,10 @@ func main() { fmt.Print(string(data)) } ``` + + -
-
-

Python

- - ``` + ```python load("@rules_python//python:defs.bzl", "py_binary") py_binary( @@ -152,9 +136,9 @@ py_binary( data = ["//examples:runfile.txt"], deps = ["@rules_python//python/runfiles"], ) - ``` +``` - ``` +```python import pathlib from python.runfiles import runfiles @@ -171,12 +155,10 @@ print("The content of the runfile is:") with open(realPathToSomeFile, 'r') as f: print(f.read()) ``` + + -
-
-

Shell

- - ``` +```python load("@rules_shell//shell:sh_binary.bzl", "sh_binary") sh_binary( @@ -185,9 +167,9 @@ sh_binary( data = ["//examples:runfile.txt"], use_bash_launcher = True, ) - ``` + ``` - ``` +```bash #!/bin/bash SOME_FILE='examples/runfile.txt' @@ -200,8 +182,7 @@ real_path_to_some_file="$(rlocation "${root}/${SOME_FILE}")" echo "The content of the runfile is:" cat "${real_path_to_some_file}" - ``` + ``` + -
- -
+ diff --git a/concepts/visibility.mdx b/concepts/visibility.mdx index 2f3980366..a4bc6c549 100644 --- a/concepts/visibility.mdx +++ b/concepts/visibility.mdx @@ -5,9 +5,8 @@ title: 'Visibility' This page covers Bazel's three visibility systems: -[target visibility](#target-visibility), -[transitive visibility](#transitive-visibility) and -[load visibility](#load-visibility). +[target visibility](#target-visibility),[transitive visibility](#transitive-visibility) +and [load visibility](#load-visibility). These types of visibility help other developers distinguish between your library's public API and its implementation details, and help enforce structure @@ -400,7 +399,7 @@ finalizer, the finalizer cannot see such a target. Note, however, that a `native.existing_rules()`-based legacy macro will also be unable to see such a target. -## Transitive visibility +## Transitive visibility {#transitive-visibility} **Transitive visibility** is a way of restricting who may depend on a target, including when the dependency is only indirect. It applies separately from the diff --git a/configure/coverage.mdx b/configure/coverage.mdx index 541e4b6fd..f8e3e7b6a 100644 --- a/configure/coverage.mdx +++ b/configure/coverage.mdx @@ -38,12 +38,10 @@ however the latter can be more difficult for complex projects. "Instrumentation" in this case refers to the coverage tools that are used for a specific target. Bazel allows turning this on for a specific subset of files using the -[`--instrumentation_filter`] -(/reference/command-line-reference#flag--instrumentation_filter) +[`--instrumentation_filter`](/reference/command-line-reference#flag--instrumentation_filter) flag, which specifies a filter for targets that are tested with the instrumentation enabled. To enable instrumentation for tests, the -[`--instrument_test_targets`] -(/reference/command-line-reference#flag--instrument_test_targets) +[`--instrument_test_targets`](/reference/command-line-reference#flag--instrument_test_targets) flag is required. By default, bazel tries to match the target package(s), and prints the @@ -81,7 +79,7 @@ Note that `genhtml` reads the source code as well, to annotate missing coverage in these files. For this to work, it is expected that `genhtml` is executed in the root of the bazel project. -To view the result, open the `index.html` file produced in the +To view the result, simply open the `index.html` file produced in the `genhtml` directory in any web browser. For further help and information around the `genhtml` tool, or the @@ -89,11 +87,11 @@ For further help and information around the `genhtml` tool, or the ## Remote execution -Running with remote test execution has a few caveats: +Running with remote test execution currently has a few caveats: - The report combination action cannot yet run remotely. This is because Bazel does not consider the coverage output files as part of - its graph (see [Bazel issue #4685][remote_report_issue]), and can therefore + its graph (see [this issue][remote_report_issue]), and can therefore not correctly treat them as inputs to the combination action. To work around this, use `--strategy=CoverageReport=local`. - Note: It may be necessary to specify something like @@ -101,7 +99,7 @@ Running with remote test execution has a few caveats: up to try `local,remote`, due to how Bazel resolves strategies. - `--remote_download_minimal` and similar flags can also not be used as a consequence of the former. -- Bazel will fail to create coverage information if tests +- Bazel will currently fail to create coverage information if tests have been cached previously. To work around this, `--nocache_test_results` can be set specifically for coverage runs, although this of course incurs a heavy cost in terms of test times. @@ -110,21 +108,18 @@ Running with remote test execution has a few caveats: - Usually coverage is run as part of the test action, and so by default, we don't get all coverage back as outputs of the remote execution by default. These flags override the default and obtain - the coverage data. See [Bazel issue #4685][split_coverage_issue] for more + the coverage data. See [this issue][split_coverage_issue] for more details. ## Language-specific configuration -The following sections detail language-specific considerations for setting up -code coverage with Bazel. - ### C++ #### Linux C++ coverage should work out-of-the-box with the default configuration. -#### macOS +#### MacOS The default value of `GCOV_PREFIX_STRIP` is almost certainly incorrect and needs adjusting manually because the correct value depends on your setup. diff --git a/configure/integrate-cpp.mdx b/configure/integrate-cpp.mdx index e285fa439..107ab8102 100644 --- a/configure/integrate-cpp.mdx +++ b/configure/integrate-cpp.mdx @@ -2,8 +2,6 @@ title: 'Integrating with C++ Rules' --- - - This page describes how to integrate with C++ rules on various levels. ## Accessing the C++ toolchain @@ -17,8 +15,7 @@ To depend on a C++ toolchain in your rule, set the `toolchains` parameter to `find_cpp_toolchain(ctx)` to get the [`CcToolchainInfo`](/rules/lib/providers/CcToolchainInfo). A complete working example can be found [in the rules_cc -examples](https://github.com/bazelbuild/rules_cc/blob/main/examples/write_cc_toolchain_cpu/write_cc_toolchain_cpu.bzl){: -.external}. +examples](https://github.com/bazelbuild/rules_cc/blob/main/examples/write_cc_toolchain_cpu/write_cc_toolchain_cpu.bzl). ## Generating command lines and environment variables using the C++ toolchain @@ -70,7 +67,6 @@ it should wrap it in, for example, `JavaCcInfo`. A complete working example can be found [in the rules_cc examples](https://github.com/bazelbuild/rules_cc/blob/main/examples/my_c_archive/my_c_archive.bzl). - ## Reusing logic and actions of C++ rules _Not stable yet; This section will be updated once the API stabilizes. Follow diff --git a/configure/windows.mdx b/configure/windows.mdx index b42458b3b..67a36c832 100644 --- a/configure/windows.mdx +++ b/configure/windows.mdx @@ -369,6 +369,7 @@ necessary for consistent behavior between WORKSPACE and Bzlmod setups in Bazel * Clang is not supported. + ### Build Java To build Java targets, you need: diff --git a/contribute/codebase.mdx b/contribute/codebase.mdx index 44e0150d3..98935ab8f 100644 --- a/contribute/codebase.mdx +++ b/contribute/codebase.mdx @@ -165,23 +165,32 @@ execute, the following sequence of events happens: ## Command line options -The command line options for a Bazel invocation are described in an -`OptionsParsingResult` object, which in turn contains a map from "option -classes" to the values of the options. An "option class" is a subclass of -`OptionsBase` and groups command line options together that are related to each -other. For example: - -1. Options related to a programming language (`CppOptions` or `JavaOptions`). - These should be a subclass of `FragmentOptions` and are eventually wrapped - into a `BuildOptions` object. -2. Options related to the way Bazel executes actions (`ExecutionOptions`) - -These options are designed to be consumed in the analysis phase and (either -through `RuleContext.getFragment()` in Java or `ctx.fragments` in Starlark). -Some of them (for example, whether to do C++ include scanning or not) are read -in the execution phase, but that always requires explicit plumbing since -`BuildConfiguration` is not available then. For more information, see the -section "Configurations". +The command line options for a Bazel invocation are parsed into an +`OptionsParsingResult` object, which holds instances of `OptionsBase` +subclasses populated with the parsed values. An "option class" is a subclass +of `OptionsBase` and groups related command line options together. + +There are two main kinds of option classes: + +1. **Configuration options:** These options affect how targets are built, + for example, defining the target platform or compilation mode. They are + defined in subclasses of `FragmentOptions` (e.g., `CppOptions`, + `JavaOptions`), which is itself a subclass of `OptionsBase`. + `FragmentOptions` instances are collected into a `BuildOptions` object, + which is used to create the `BuildConfiguration` for a configured target. + These options are available during the analysis phase via + `RuleContext.getFragment()` in Java or `ctx.fragments` in Starlark. +2. **Other command options:** These options affect other aspects of Bazel's + behavior. They are defined in classes that extend `OptionsBase` directly, + but are not `FragmentOptions`. Examples include `ExecutionOptions`, which + influences how actions are executed, and `CommonCommandOptions`, which + contains options applicable to many commands. These are not part of + `BuildOptions`. + +Some configuration options (for example, whether to do C++ include scanning with +`--cc_include_scanning`) are read in the execution phase. But that always +requires explicit plumbing since `BuildConfiguration` is not available then. For +more information, see the section "Configurations". **WARNING:** We like to pretend that `OptionsBase` instances are immutable and use them that way (such as a part of `SkyKeys`). This is not the case and @@ -193,15 +202,16 @@ called on it is okay.) Bazel learns about option classes in the following ways: -1. Some are hard-wired into Bazel (`CommonCommandOptions`) -2. From the `@Command` annotation on each Bazel command -3. From `ConfiguredRuleClassProvider` (these are command line options related - to individual programming languages) -4. Starlark rules can also define their own options (see - [here](/extending/config)) +1. Some are hard-wired into Bazel (`CommonCommandOptions`). +2. From the `@Command` annotation on each Bazel command, which + lists option classes applicable to that command. +3. From `ConfiguredRuleClassProvider` (these are `FragmentOptions` for + individual programming languages that become part of `BuildOptions`). +4. Starlark rules can also define their own options, known as build settings + (see [here](/extending/config)). -Each option (excluding Starlark-defined options) is a member variable of a -`FragmentOptions` subclass that has the `@Option` annotation, which specifies +Each option (excluding Starlark-defined options) is a member variable of an +`OptionsBase` subclass that has the `@Option` annotation, which specifies the name and the type of the command line option along with some help text. The Java type of the value of a command line option is usually something simple diff --git a/contribute/docs-style-guide.mdx b/contribute/docs-style-guide.mdx new file mode 100644 index 000000000..f50c9eb67 --- /dev/null +++ b/contribute/docs-style-guide.mdx @@ -0,0 +1,217 @@ +--- +title: 'Bazel docs style guide' +--- + + + +Thank you for contributing to Bazel's documentation. This serves as a quick +documentation style guide to get you started. For any style questions not +answered by this guide, follow the +[Google developer documentation style guide](https://developers.google.com/style). + +## Defining principles + +Bazel docs should uphold these principles: + +- **Concise.** Use as few words as possible. +- **Clear.** Use plain language. Write without jargon for a fifth-grade + reading level. +- **Consistent.** Use the same words or phrases for repeated concepts + throughout the docs. +- **Correct.** Write in a way where the content stays correct for as long as + possible by avoiding time-based information and promises for the future. + +## Writing + +This section contains basic writing tips. + +### Headings + +- Page-level headings start at H2. (H1 headings are used as page titles.) +- Make headers as short as is sensible. This way, they fit in the TOC + without wrapping. + + - Yes: Permissions + - No: A brief note on permissions + +- Use sentence case for headings + + - Yes: Set up your workspace + - No: Set Up Your Workspace + +- Try to make headings task-based or actionable. If headings are conceptual, + it may be based around understanding, but write to what the user does. + + - Yes: Preserving graph order + - No: On the preservation of graph order + +### Names + +- Capitalize proper nouns, such as Bazel and Starlark. + + - Yes: At the end of the build, Bazel prints the requested targets. + - No: At the end of the build, bazel prints the requested targets. + +- Keep it consistent. Don't introduce new names for existing concepts. Where + applicable, use the term defined in the + [Glossary](/reference/glossary). + + - For example, if you're writing about issuing commands on a + terminal, don't use both terminal and command line on the page. + +### Page scope + +- Each page should have one purpose and that should be defined at the + beginning. This helps readers find what they need quicker. + + - Yes: This page covers how to install Bazel on Windows. + - No: (No introductory sentence.) + +- At the end of the page, tell the reader what to do next. For pages where + there is no clear action, you can include links to similar concepts, + examples, or other avenues for exploration. + +### Subject + +In Bazel documentation, the audience should primarily be users—the people using +Bazel to build their software. + +- Address your reader as "you". (If for some reason you can't use "you", + use gender-neutral language, such as they.) + - Yes: To build Java code using Bazel, + you must install a JDK. + - **MAYBE:** For users to build Java code with Bazel, they must install a JDK. + - No: For a user to build Java code with + Bazel, he or she must install a JDK. + +- If your audience is NOT general Bazel users, define the audience at the + beginning of the page or in the section. Other audiences can include + maintainers, contributors, migrators, or other roles. +- Avoid "we". In user docs, there is no author; just tell people what's + possible. + - Yes: As Bazel evolves, you should update your code base to maintain + compatibility. + - No: Bazel is evolving, and we will make changes to Bazel that at + times will be incompatible and require some changes from Bazel users. + +### Temporal + +Where possible, avoid terms that orient things in time, such as referencing +specific dates (Q2 2022) or saying "now", "currently", or "soon." These go +stale quickly and could be incorrect if it's a future projection. Instead, +specify a version level instead, such as "Bazel X.x and higher supports +\ or a GitHub issue link. + +- Yes: Bazel 0.10.0 or later supports + remote caching. +- No: Bazel will soon support remote + caching, likely in October 2017. + +### Tense + +- Use present tense. Avoid past or future tense unless absolutely necessary + for clarity. + - Yes: Bazel issues an error when it + finds dependencies that don't conform to this rule. + - No: If Bazel finds a dependency that + does not conform to this rule, Bazel will issue an error. + +- Where possible, use active voice (where a subject acts upon an object) not + passive voice (where an object is acted upon by a subject). Generally, + active voice makes sentences clearer because it shows who is responsible. If + using active voice detracts from clarity, use passive voice. + - Yes: Bazel initiates X and uses the + output to build Y. + - No: X is initiated by Bazel and then + afterward Y will be built with the output. + +### Tone + +Write with a business friendly tone. + +- Avoid colloquial language. It's harder to translate phrases that are + specific to English. + - Yes: Good rulesets + - No: So what is a good ruleset? + +- Avoid overly formal language. Write as though you're explaining the + concept to someone who is curious about tech, but doesn't know the details. + +## Formatting + +### File type + +For readability, wrap lines at 80 characters. Long links or code snippets +may be longer, but should start on a new line. For example: + +Note: Where possible, use Markdown instead of HTML in your files. Follow the +[GitHub Markdown Syntax Guide](https://guides.github.com/features/mastering-markdown/#syntax) +for recommended Markdown style. + +### Links + +- Use descriptive link text instead of "here" or "below". This practice + makes it easier to scan a doc and is better for screen readers. + - Yes: For more details, see [Installing Bazel]. + - No: For more details, see [here]. + +- End the sentence with the link, if possible. + - Yes: For more details, see [link]. + - No: See [link] for more information. + +### Lists + +- Use an ordered list to describe how to accomplish a task with steps +- Use an unordered list to list things that aren't task based. (There should + still be an order of sorts, such as alphabetical, importance, etc.) +- Write with parallel structure. For example: + 1. Make all the list items sentences. + 1. Start with verbs that are the same tense. + 1. Use an ordered list if there are steps to follow. + +### Placeholders + +- Use angle brackets to denote a variable that users should change. + In Markdown, escape the angle brackets with a back slash: `\`. + - Yes: `bazel help `: Prints + help and options for `` + - No: bazel help _command_: Prints help + and options for "command" + +- Especially for complicated code samples, use placeholders that make sense + in context. + +### Table of contents + +Use the auto-generated TOC supported by the site. Don't add a manual TOC. + +## Code + +Code samples are developers' best friends. You probably know how to write these +already, but here are a few tips. + +If you're referencing a small snippet of code, you can embed it in a sentence. +If you want the reader to use the code, such as copying a command, use a code +block. + +### Code blocks + +- Keep it short. Eliminate all redundant or unnecessary text from a code + sample. +- In Markdown, specify the type of code block by adding the sample's language. + +``` +```shell +... +``` + +- Separate commands and output into different code blocks. + +### Inline code formatting + +- Use code style for filenames, directories, paths, and small bits of code. +- Use inline code styling instead of _italics_, "quotes," or **bolding**. + - Yes: `bazel help `: Prints + help and options for `` + - No: bazel help _command_: Prints help + and options for "command" diff --git a/contribute/search.mdx b/contribute/search.mdx new file mode 100644 index 000000000..c5b8cb844 --- /dev/null +++ b/contribute/search.mdx @@ -0,0 +1,276 @@ +--- +title: 'Searching the codebase' +--- + +## Product overview {:#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 {:#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 {:#working-with-repositories} + +### Opening a repository {:#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 {:#switch-repositories} + +To switch to a different repository, select the repository from the Breadcrumb toolbar. + +### View a repository at a specific commit {:#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 {:#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 {:#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 {:#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 {:#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 {:#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 {:#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 {:#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 {:#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 {:#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 {:#search} + +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){: .external} +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 {:#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/docs.json b/docs.json index 29101e430..ef2feea3a 100644 --- a/docs.json +++ b/docs.json @@ -170,7 +170,9 @@ }, { "group": "Query Language", - "pages": [] + "pages": [ + "query/quickstart" + ] }, { "group": "Glossary", diff --git a/docs/cc-toolchain-config-reference.mdx b/docs/cc-toolchain-config-reference.mdx new file mode 100644 index 000000000..8b6c26901 --- /dev/null +++ b/docs/cc-toolchain-config-reference.mdx @@ -0,0 +1,1150 @@ +--- +title: 'C++ Toolchain Configuration' +--- + +## Overview {:#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){: .external}. + +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 {:#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 {:#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 {:#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} + +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 {:#assembler-actions} + + + + + + + + + + + + + + + + +
Action + Description +
preprocess-assemble + Assemble with preprocessing. Typically for .S files. +
assemble + Assemble without preprocessing. Typically for .s files. +
+ +### Compiler actions {:#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 {:#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} + +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 {:#lto-actions} + + + + + + + + + + + + + + + + +
Action + Description +
lto-backend + ThinLTO action compiling bitcodes into native objects. +
lto-index + ThinLTO action generating global index. +
+ +## Using action_config {:#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 {:#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 {:#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 {:#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= -isystem= -iprefix= -isystem= + +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 {:#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 {:#cctoolchainconfiginfo-reference} + +This section provides a reference of build variables, features, and other +information required to successfully configure C++ rules. + +### CcToolchainConfigInfo build variables {:#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 {:#wellknown-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 {:#legacy-features-patching-logic} + +

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

    +
  • Moves legacy_compile_flags feature to the top of the toolchain
    • +
  • Moves default_compile_flags feature to the top of the toolchain
    • +
  • Adds dependency_file (if not present) feature to the top of the toolchain
    • +
  • Adds pic (if not present) feature to the top of the toolchain
    • +
  • Adds per_object_debug_info (if not present) feature to the top of the toolchain
    • +
  • Adds preprocessor_defines (if not present) feature to the top of the toolchain
    • +
  • Adds includes (if not present) feature to the top of the toolchain
    • +
  • Adds include_paths (if not present) feature to the top of the toolchain
    • +
  • Adds fdo_instrument (if not present) feature to the top of the toolchain
    • +
  • Adds fdo_optimize (if not present) feature to the top of the toolchain
    • +
  • Adds cs_fdo_instrument (if not present) feature to the top of the toolchain
    • +
  • Adds cs_fdo_optimize (if not present) feature to the top of the toolchain
    • +
  • Adds fdo_prefetch_hints (if not present) feature to the top of the toolchain
    • +
  • Adds autofdo (if not present) feature to the top of the toolchain
    • +
  • Adds build_interface_libraries (if not present) feature to the top of the toolchain
    • +
  • Adds dynamic_library_linker_tool (if not present) feature to the top of the toolchain
    • +
  • Adds shared_flag (if not present) feature to the top of the toolchain
    • +
  • Adds linkstamps (if not present) feature to the top of the toolchain
    • +
  • Adds output_execpath_flags (if not present) feature to the top of the toolchain
    • +
  • Adds runtime_library_search_directories (if not present) feature to the top of the toolchain
    • +
  • Adds library_search_directories (if not present) feature to the top of the toolchain
    • +
  • Adds archiver_flags (if not present) feature to the top of the toolchain
    • +
  • Adds libraries_to_link (if not present) feature to the top of the toolchain
    • +
  • Adds force_pic_flags (if not present) feature to the top of the toolchain
    • +
  • Adds user_link_flags (if not present) feature to the top of the toolchain
    • +
  • Adds legacy_link_flags (if not present) feature to the top of the toolchain
    • +
  • Adds static_libgcc (if not present) feature to the top of the toolchain
    • +
  • Adds fission_support (if not present) feature to the top of the toolchain
    • +
  • Adds strip_debug_symbols (if not present) feature to the top of the toolchain
    • +
  • Adds coverage (if not present) feature to the top of the toolchain
    • +
  • Adds llvm_coverage_map_format (if not present) feature to the top of the toolchain
    • +
  • Adds gcc_coverage_map_format (if not present) feature to the top of the toolchain
    • +
  • Adds fully_static_link (if not present) feature to the bottom of the toolchain
    • +
  • Adds user_compile_flags (if not present) feature to the bottom of the toolchain
    • +
  • Adds sysroot (if not present) feature to the bottom of the toolchain
    • +
  • Adds unfiltered_compile_flags (if not present) feature to the bottom of the toolchain
    • +
  • Adds linker_param_file (if not present) feature to the bottom of the toolchain
    • +
  • Adds compiler_input_flags (if not present) feature to the bottom of the toolchain
    • +
  • Adds compiler_output_flags (if not present) feature to the bottom of the toolchain
    • +
+

+ +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){: .external} 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 000000000..057991ac8 --- /dev/null +++ b/docs/user-manual.mdx @@ -0,0 +1,2497 @@ +--- +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 {:#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 {:#build-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-location} + +#### `--package_path` {:#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` {:flag--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 {:#error-checking} + +These options control Bazel's error-checking and/or warnings. + +#### `--[no]check_visibility` {:#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{{ "" }}` {:#output-filter} + +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: + + + + + + + + + + + + + + + + + + +
`--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 {:#tool-flags} + +These options control which options Bazel will pass to other tools. + +#### `--copt={{ "" }}cc-option{{ "" }}` {:#copt} + +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{{ "" }}` {:#host-copt} + +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{{ "" }}` {:#host-conlyopt} + +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{{ "" }}` {:#host-cxxopt} + +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{{ "" }}` {:#host-linkopt} + +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{{ "" }}` {:#cconlyopt} + +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{{ "" }}` {:#cxxopt} + +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{{ "" }}` {:#linkopt} + +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)` {:#strip} + +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{{ "" }}` {:#stripopt} + +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{{ "" }}` {:#fdo-instrument} + +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{{ "" }}` {:#fdo-optimize} + +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{{ "" }}` {:#java-language-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{{ "" }}` {:#tool-java-language-version} + +The Java language version used to build tools that are executed during a build. +Default value is 11. + +#### `--java_runtime_version={{ "" }}version{{ "" }}` {:#java-runtime-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{{ "" }}` {:#tool-java-runtime-version} + +The version of JVM used to execute tools that are needed during a build. +Default value is `remotejdk_11`. + +#### `--jvmopt={{ "" }}jvm-option{{ "" }}` {:#jvmopt} + +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{{ "" }}` {:#javacopt} + +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)` {:#strict-java-deps} + +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 {:#build-semantics} + +These options affect the build commands and/or the output file contents. + +#### `--compilation_mode (fastbuild|opt|dbg)` (-c) {:#compilation-mode} + +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{{ "" }}` {:#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{{ "" }}` {:#action-env} + +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{{ "" }}` {:#experimental-action-listener} + +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` {: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{{ "" }}` {:#experimental-extra-action-filter} + +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{{ "" }}` {:#host-cpu} + +This option specifies the name of the CPU architecture that should be +used to build host tools. + +#### `--android_platforms={{ "" }}platform[,platform]*{{ "" }}` {:#android-platforms} + +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]...{{ "" }}` {:#per-file-copt} + +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{{ "" }}` {:#dynamic-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])` {:#fission} + +Enables [Fission](https://gcc.gnu.org/wiki/DebugFission){: .external}, +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` {:#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` {:#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` {:#flag--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{{ "" }}` {:#custom-malloc} + +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{{ "" }}` {:#crosstool-top} + +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{{ "" }}` {:#host-crosstool-top} + +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{{ "" }}` {:#apple-crosstool-top} + +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{{ "" }}` {:#compiler} + +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{{ "" }}` {:#android-sdk} + +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{{ "" }}` {:#java-toolchain} + +No-op. Kept only for backwards compatibility. + +#### `--host_java_toolchain={{ "" }}label{{ "" }}` {:#host-java-toolchain} + +No-op. Kept only for backwards compatibility. + +#### `--javabase=({{ "" }}label{{ "" }})` {:#javabase} + +No-op. Kept only for backwards compatibility. + +#### `--host_javabase={{ "" }}label{{ "" }}` {:#host-javabase} + +No-op. Kept only for backwards compatibility. + +### Execution strategy {:#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{{ "" }}` {:#spawn-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{{ "" }}` {:#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={{ "" }}={{ "" }}` {:#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{{ "" }}` {:#genrule-strategy} + +This is a deprecated short-hand for `--strategy=Genrule={{ "" }}strategy{{ "" }}`. + +#### `--jobs={{ "" }}n{{ "" }}` (-j) {:#jobs} + +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_resources` option. + +#### `--progress_report_interval={{ "" }}n{{ "" }}` {:progress-report-interval} + +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_resources {{ "" }}resources or resource expression{{ "" }}` {:#local-resources} + +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 float, or a keyword (HOST_RAM or HOST_CPUS) optionally followed by `[-|*`float`]` +(for example, `--local_resources=cpu=2`, `--local_resources=memory=HOST_RAM*.5`, +`--local_resources=cpu=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` {:#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` {:#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` {:#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) {:#keep-going} + +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` {:#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` {:#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 {:#output-selection} + +These options determine what to build or test. + +#### `--[no]build` {:#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` {:#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` {:#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-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` {:#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]*{{ "" }}` {:#build-tag-filters} + +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]*{{ "" }}` {:#test-size-filters} + +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]*{{ "" }}` {:#test-timeout-filters} + +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]*{{ "" }}` {:#test-tag-filters} + +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]*{{ "" }}` {:#test-lang-filters} + +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{{ "" }}` {:#test-filter} + +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 {:#verbosity} + +These options control the verbosity of Bazel's output, +either to the terminal, or to additional log files. + +#### `--explain={{ "" }}logfile{{ "" }}` {:#explain} + +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` {:#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{{ "" }}` {:#profile} + +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` {:#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` {:#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{{ "" }}` {:#show-progress-rate} + +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{{ "" }}` {:#show-result} + +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` {:#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`) {:#subcommands} + +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` {:#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 {:#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{{ "" }}` {:#workspace-status-command} + +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` {:#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 {:#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{{ "" }}` {:#platforms} + +The labels of the platform rules describing the target platforms for the +current command. + +#### `--host_platform={{ "" }}label{{ "" }}` {:#host-platform} + +The label of a platform rule that describes the host system. + +#### `--extra_execution_platforms={{ "" }}labels{{ "" }}` {:#extra-execution-platforms} + +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{{ "" }}` {:#extra-toolchains} + +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{{ "" }}` {:#toolchain-resolution-debug} + +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 {:#miscellaneous} + +#### `--flag_alias={{ "" }}alias_name=target_path{{ "" }}` {:#flag-alias} + +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{{ "" }}` {:#symlink-prefix} + +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{{ "" }}` {:#platform-suffix} + +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){{ "" }}` {:#default-visibility} + +Temporary flag for testing bazel default visibility changes. Not intended for general use +but documented for completeness' sake. + +#### `--starlark_cpu_profile=_file_` {:#starlark-cpu-profile} + +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){: .external} 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-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 {:#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 {:#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` {:#bazel-test-options} + +#### `--cache_test_results=(yes|no|auto)` (`-t`) {:#cache-test-results} + +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` {:#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` {:#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` {:#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{{ "" }}` {:#flaky-test-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{{ "" }}` {:#runs-per-test} + +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` {:#run-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{{ "" }}` {:#test-summary} + +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{{ "" }}` {:#test-output} + +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` {:#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` {:#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{{ "" }}` {:#test-tmpdir} + +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{{ "" }}` {:#test-timeout} + +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{{ "" }}` {:#test-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{{ "" }}` {:#test-env} + +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{{ "" }}` {:#test-run-under} + +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 {:#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` {:#bazel-test-other-options} + +The syntax and the remaining options are exactly like +[`bazel build`](/run/build). + +## Running executables {:#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` {:#bazel-run-options} + +#### `--run_under={{ "" }}command-prefix{{ "" }}` {:#run-run-under} + +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 {:#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 {:#cleaning-build-outputs} + +### The `clean` command {:#clean} + +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 {:#querying-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 {:#aquery} + +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 {:#misc-commands-options} + +### `help` {:#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`) {:#long} + +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` {:#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` {:#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 {:#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 {:#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` {:#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` {:#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` {:#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` {:#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` {:#start-app} + +Starts the app in a clean state after installing. Equivalent to `--start=COLD`. + +#### `--debug_app` {:#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_` {:#start} + +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{{ "" }}` {:#adb} + +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{{ "" }}` {:#adb-arg} + +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{{ "" }}` {:#incremental-install-verbosity} + +The verbosity for incremental install. Set to 1 for debug logging to be +printed to the console. + +### `dump` {:#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 {:#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` {:#analyze-profile} + +The `analyze-profile` command analyzes a +[JSON trace profile](/advanced/performance/json-trace-profile) previously +gathered during a Bazel invocation. + +### `canonicalize-flags` {:#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 {:#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{{ "" }}` {:#output-base} + +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{{ "" }}` {:#output-user-root} + +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){: .external} 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{{ "" }}` {:#server-javabase} + +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{{ "" }}` {:#host-jvm-args} + +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` {:#host-java-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` {:#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} + +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{{ "" }}` {:#max-idle-secs} + +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` {:#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` {:#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{{ "" }}` {:#io-nice-level} + +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` {:#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 {:#misc-options} + +#### `--[no]announce_rc` {:#announce-rc} + +Controls whether Bazel announces startup options and command options read from +the bazelrc files when starting up. + +#### `--color (yes|no|auto)` {:#color} + +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{{ "" }}` {:#config} + +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)` {:#curses} + +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` {:#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/extending/config.mdx b/extending/config.mdx new file mode 100644 index 000000000..0e44c3448 --- /dev/null +++ b/extending/config.mdx @@ -0,0 +1,789 @@ +--- +title: 'Configurations' +--- + + + +This page covers the benefits and basic usage of Starlark configurations, +Bazel's API for customizing how your project builds. It includes how to define +build settings and provides examples. + +This makes it possible to: + +* define custom flags for your project, obsoleting the need for + [`--define`](/docs/configurable-attributes#custom-keys) +* write + [transitions](/rules/lib/builtins/transition#transition) to configure deps in + different configurations than their parents + (such as `--compilation_mode=opt` or `--cpu=arm`) +* bake better defaults into rules (such as automatically build `//my:android_app` + with a specified SDK) + +and more, all completely from .bzl files (no Bazel release required). See the +`bazelbuild/examples` repo for +[examples](https://github.com/bazelbuild/examples/tree/HEAD/configurations){: .external}. + +## User-defined build settings {:#user-defined-build-settings} + +A build setting is a single piece of +[configuration](/extending/rules#configurations) +information. Think of a configuration as a key/value map. Setting `--cpu=ppc` +and `--copt="-DFoo"` produces a configuration that looks like +`{cpu: ppc, copt: "-DFoo"}`. Each entry is a build setting. + +Traditional flags like `cpu` and `copt` are native settings — +their keys are defined and their values are set inside native bazel java code. +Bazel users can only read and write them via the command line +and other APIs maintained natively. Changing native flags, and the APIs +that expose them, requires a bazel release. User-defined build +settings are defined in `.bzl` files (and thus, don't need a bazel release to +register changes). They also can be set via the command line +(if they're designated as `flags`, see more below), but can also be +set via [user-defined transitions](#user-defined-transitions). + +### Defining build settings {:#defining-build-settings} + +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/basic_build_setting){: .external} + +#### The `build_setting` `rule()` parameter {:#rule-parameter} + +Build settings are rules like any other rule and are differentiated using the +Starlark `rule()` function's `build_setting` +[attribute](/rules/lib/globals/bzl#rule.build_setting). + +```python +# example/buildsettings/build_settings.bzl +string_flag = rule( + implementation = _impl, + build_setting = config.string(flag = True) +) +``` + +The `build_setting` attribute takes a function that designates the type of the +build setting. The type is limited to a set of basic Starlark types like +`bool` and `string`. See the `config` module +[documentation](/rules/lib/toplevel/config) for details. More complicated typing can be +done in the rule's implementation function. More on this below. + +The `config` module's functions takes an optional boolean parameter, `flag`, +which is set to false by default. if `flag` is set to true, the build setting +can be set on the command line by users as well as internally by rule writers +via default values and [transitions](/rules/lib/builtins/transition#transition). +Not all settings should be settable by users. For example, if you as a rule +writer have some debug mode that you'd like to turn on inside test rules, +you don't want to give users the ability to indiscriminately turn on that +feature inside other non-test rules. + +#### Using ctx.build_setting_value {:#ctx-build-setting-value} + +Like all rules, build setting rules have [implementation functions](/extending/rules#implementation-function). +The basic Starlark-type value of the build settings can be accessed via the +`ctx.build_setting_value` method. This method is only available to +[`ctx`](/rules/lib/builtins/ctx) objects of build setting rules. These implementation +methods can directly forward the build settings value or do additional work on +it, like type checking or more complex struct creation. Here's how you would +implement an `enum`-typed build setting: + +```python +# example/buildsettings/build_settings.bzl +TemperatureProvider = provider(fields = ['type']) + +temperatures = ["HOT", "LUKEWARM", "ICED"] + +def _impl(ctx): + raw_temperature = ctx.build_setting_value + if raw_temperature not in temperatures: + fail(str(ctx.label) + " build setting allowed to take values {" + + ", ".join(temperatures) + "} but was set to unallowed value " + + raw_temperature) + return TemperatureProvider(type = raw_temperature) + +temperature = rule( + implementation = _impl, + build_setting = config.string(flag = True) +) +``` + +Note: if a rule depends on a build setting, it will receive whatever providers +the build setting implementation function returns, like any other dependency. +But all other references to the value of the build setting (such as in transitions) +will see its basic Starlark-typed value, not this post implementation function +value. + +#### Defining multi-set string flags {:#multi-set-string-flags} + +String settings have an additional `allow_multiple` parameter which allows the +flag to be set multiple times on the command line or in bazelrcs. Their default +value is still set with a string-typed attribute: + +```python +# example/buildsettings/build_settings.bzl +allow_multiple_flag = rule( + implementation = _impl, + build_setting = config.string(flag = True, allow_multiple = True) +) +``` + +```python +# example/BUILD +load("//example/buildsettings:build_settings.bzl", "allow_multiple_flag") +allow_multiple_flag( + name = "roasts", + build_setting_default = "medium" +) +``` + +Each setting of the flag is treated as a single value: + +```shell +$ bazel build //my/target --//example:roasts=blonde \ + --//example:roasts=medium,dark +``` + +The above is parsed to `{"//example:roasts": ["blonde", "medium,dark"]}` and +`ctx.build_setting_value` returns the list `["blonde", "medium,dark"]`. + +#### Instantiating build settings {:#instantiating-build-settings} + +Rules defined with the `build_setting` parameter have an implicit mandatory +`build_setting_default` attribute. This attribute takes on the same type as +declared by the `build_setting` param. + +```python +# example/buildsettings/build_settings.bzl +FlavorProvider = provider(fields = ['type']) + +def _impl(ctx): + return FlavorProvider(type = ctx.build_setting_value) + +flavor = rule( + implementation = _impl, + build_setting = config.string(flag = True) +) +``` + +```python +# example/BUILD +load("//example/buildsettings:build_settings.bzl", "flavor") +flavor( + name = "favorite_flavor", + build_setting_default = "APPLE" +) +``` + +### Predefined settings {:#predefined-settings} + +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/use_skylib_build_setting){: .external} + +The +[Skylib](https://github.com/bazelbuild/bazel-skylib){: .external} +library includes a set of predefined settings you can instantiate without having +to write custom Starlark. + +For example, to define a setting that accepts a limited set of string values: + +```python +# example/BUILD +load("@bazel_skylib//rules:common_settings.bzl", "string_flag") +string_flag( + name = "myflag", + values = ["a", "b", "c"], + build_setting_default = "a", +) +``` + +For a complete list, see +[Common build setting rules](https://github.com/bazelbuild/bazel-skylib/blob/main/rules/common_settings.bzl){: .external}. + +### Using build settings {:#using-build-settings} + +#### Depending on build settings {:#depending-on-build-settings} + +If a target would like to read a piece of configuration information, it can +directly depend on the build setting via a regular attribute dependency. + +```python +# example/rules.bzl +load("//example/buildsettings:build_settings.bzl", "FlavorProvider") +def _rule_impl(ctx): + if ctx.attr.flavor[FlavorProvider].type == "ORANGE": + ... + +drink_rule = rule( + implementation = _rule_impl, + attrs = { + "flavor": attr.label() + } +) +``` + +```python +# example/BUILD +load("//example:rules.bzl", "drink_rule") +load("//example/buildsettings:build_settings.bzl", "flavor") +flavor( + name = "favorite_flavor", + build_setting_default = "APPLE" +) +drink_rule( + name = "my_drink", + flavor = ":favorite_flavor", +) +``` + +Languages may wish to create a canonical set of build settings which all rules +for that language depend on. Though the native concept of `fragments` no longer +exists as a hardcoded object in Starlark configuration world, one way to +translate this concept would be to use sets of common implicit attributes. For +example: + +```python +# kotlin/rules.bzl +_KOTLIN_CONFIG = { + "_compiler": attr.label(default = "//kotlin/config:compiler-flag"), + "_mode": attr.label(default = "//kotlin/config:mode-flag"), + ... +} + +... + +kotlin_library = rule( + implementation = _rule_impl, + attrs = dicts.add({ + "library-attr": attr.string() + }, _KOTLIN_CONFIG) +) + +kotlin_binary = rule( + implementation = _binary_impl, + attrs = dicts.add({ + "binary-attr": attr.label() + }, _KOTLIN_CONFIG) + +``` + +#### Using build settings on the command line {:#build-settings-command-line} + +Similar to most native flags, you can use the command line to set build settings +[that are marked as flags](#rule-parameter). The build +setting's name is its full target path using `name=value` syntax: + +```shell +$ bazel build //my/target --//example:string_flag=some-value # allowed +$ bazel build //my/target --//example:string_flag some-value # not allowed +``` + +Special boolean syntax is supported: + +```shell +$ bazel build //my/target --//example:boolean_flag +$ bazel build //my/target --no//example:boolean_flag +``` + +#### Using build setting aliases {:#using-build-setting-aliases} + +You can set an alias for your build setting target path to make it easier to read +on the command line. Aliases function similarly to native flags and also make use +of the double-dash option syntax. + +Set an alias by adding `--flag_alias=ALIAS_NAME=TARGET_PATH` +to your `.bazelrc` . For example, to set an alias to `coffee`: + +```shell +# .bazelrc +build --flag_alias=coffee=//experimental/user/starlark_configurations/basic_build_setting:coffee-temp +``` + +Best Practice: Setting an alias multiple times results in the most recent +one taking precedence. Use unique alias names to avoid unintended parsing results. + +To make use of the alias, type it in place of the build setting target path. +With the above example of `coffee` set in the user's `.bazelrc`: + +```shell +$ bazel build //my/target --coffee=ICED +``` + +instead of + +```shell +$ bazel build //my/target --//experimental/user/starlark_configurations/basic_build_setting:coffee-temp=ICED +``` +Best Practice: While it possible to set aliases on the command line, leaving them +in a `.bazelrc` reduces command line clutter. + +### Label-typed build settings {:#label-typed-build-settings} + +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/label_typed_build_setting){: .external} + +Unlike other build settings, label-typed settings cannot be defined using the +`build_setting` rule parameter. Instead, bazel has two built-in rules: +`label_flag` and `label_setting`. These rules forward the providers of the +actual target to which the build setting is set. `label_flag` and +`label_setting` can be read/written by transitions and `label_flag` can be set +by the user like other `build_setting` rules can. Their only difference is they +can't customely defined. + +Label-typed settings will eventually replace the functionality of late-bound +defaults. Late-bound default attributes are Label-typed attributes whose +final values can be affected by configuration. In Starlark, this will replace +the [`configuration_field`](/rules/lib/globals/bzl#configuration_field) + API. + +```python +# example/rules.bzl +MyProvider = provider(fields = ["my_field"]) + +def _dep_impl(ctx): + return MyProvider(my_field = "yeehaw") + +dep_rule = rule( + implementation = _dep_impl +) + +def _parent_impl(ctx): + if ctx.attr.my_field_provider[MyProvider].my_field == "cowabunga": + ... + +parent_rule = rule( + implementation = _parent_impl, + attrs = { "my_field_provider": attr.label() } +) + +``` + +```python +# example/BUILD +load("//example:rules.bzl", "dep_rule", "parent_rule") + +dep_rule(name = "dep") + +parent_rule(name = "parent", my_field_provider = ":my_field_provider") + +label_flag( + name = "my_field_provider", + build_setting_default = ":dep" +) +``` + +### Build settings and select() {:#build-settings-and-select} + +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/select_on_build_setting){: .external} + +Users can configure attributes on build settings by using + [`select()`](/reference/be/functions#select). Build setting targets can be passed to the `flag_values` attribute of +`config_setting`. The value to match to the configuration is passed as a +`String` then parsed to the type of the build setting for matching. + +```python +config_setting( + name = "my_config", + flag_values = { + "//example:favorite_flavor": "MANGO" + } +) +``` + +## User-defined transitions {:#user-defined-transitions} + +A configuration +[transition](/rules/lib/builtins/transition#transition) +maps the transformation from one configured target to another within the +build graph. + +Important: Transitions have [memory and performance impact](#memory-performance-considerations). + +### Defining {:#defining} + +Transitions define configuration changes between rules. For example, a request +like "compile my dependency for a different CPU than its parent" is handled by a +transition. + +Formally, a transition is a function from an input configuration to one or more +output configurations. Most transitions are 1:1 such as "override the input +configuration with `--cpu=ppc`". 1:2+ transitions can also exist but come +with special restrictions. + +In Starlark, transitions are defined much like rules, with a defining +`transition()` +[function](/rules/lib/builtins/transition#transition) +and an implementation function. + +```python +# example/transitions/transitions.bzl +def _impl(settings, attr): + _ignore = (settings, attr) + return {"//example:favorite_flavor" : "MINT"} + +hot_chocolate_transition = transition( + implementation = _impl, + inputs = [], + outputs = ["//example:favorite_flavor"] +) +``` +The `transition()` function takes in an implementation function, a set of +build settings to read(`inputs`), and a set of build settings to write +(`outputs`). The implementation function has two parameters, `settings` and +`attr`. `settings` is a dictionary {`String`:`Object`} of all settings declared +in the `inputs` parameter to `transition()`. + +`attr` is a dictionary of attributes and values of the rule to which the +transition is attached. When attached as an +[outgoing edge transition](#outgoing-edge-transitions), the values of these +attributes are all configured post-select() resolution. When attached as +an [incoming edge transition](#incoming-edge-transitions), `attr` does not +include any attributes that use a selector to resolve their value. If an +incoming edge transition on `--foo` reads attribute `bar` and then also +selects on `--foo` to set attribute `bar`, then there's a chance for the +incoming edge transition to read the wrong value of `bar` in the transition. + +Note: Since transitions are attached to rule definitions and `select()`s are +attached to rule instantiations (such as targets), errors related to `select()`s on +read attributes will pop up when users create targets rather than when rules are +written. It may be worth taking extra care to communicate to rule users which +attributes they should be wary of selecting on or taking other precautions. + +The implementation function must return a dictionary (or list of +dictionaries, in the case of +transitions with multiple output configurations) +of new build settings values to apply. The returned dictionary keyset(s) must +contain exactly the set of build settings passed to the `outputs` +parameter of the transition function. This is true even if a build setting is +not actually changed over the course of the transition - its original value must +be explicitly passed through in the returned dictionary. + +### Defining 1:2+ transitions {:#defining-1-2-transitions} + +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/multi_arch_binary){: .external} + +[Outgoing edge transition](#outgoing-edge-transitions) can map a single input +configuration to two or more output configurations. This is useful for defining +rules that bundle multi-architecture code. + +1:2+ transitions are defined by returning a list of dictionaries in the +transition implementation function. + +```python +# example/transitions/transitions.bzl +def _impl(settings, attr): + _ignore = (settings, attr) + return [ + {"//example:favorite_flavor" : "LATTE"}, + {"//example:favorite_flavor" : "MOCHA"}, + ] + +coffee_transition = transition( + implementation = _impl, + inputs = [], + outputs = ["//example:favorite_flavor"] +) +``` +They can also set custom keys that the rule implementation function can use to +read individual dependencies: + +```python +# example/transitions/transitions.bzl +def _impl(settings, attr): + _ignore = (settings, attr) + return { + "Apple deps": {"//command_line_option:cpu": "ppc"}, + "Linux deps": {"//command_line_option:cpu": "x86"}, + } + +multi_arch_transition = transition( + implementation = _impl, + inputs = [], + outputs = ["//command_line_option:cpu"] +) +``` + +### Attaching transitions {:#attaching-transitions} + +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/attaching_transitions_to_rules){: .external} + +Transitions can be attached in two places: incoming edges and outgoing edges. +Effectively this means rules can transition their own configuration (incoming +edge transition) and transition their dependencies' configurations (outgoing +edge transition). + +NOTE: There is currently no way to attach Starlark transitions to native rules. +If you need to do this, contact +bazel-discuss@googlegroups.com +for help with figuring out workarounds. + +### Incoming edge transitions {:#incoming-edge-transitions} + +Incoming edge transitions are activated by attaching a `transition` object +(created by `transition()`) to `rule()`'s `cfg` parameter: + +```python +# example/rules.bzl +load("example/transitions:transitions.bzl", "hot_chocolate_transition") +drink_rule = rule( + implementation = _impl, + cfg = hot_chocolate_transition, + ... +``` + +Incoming edge transitions must be 1:1 transitions. + +### Outgoing edge transitions {:#outgoing-edge-transitions} + +Outgoing edge transitions are activated by attaching a `transition` object +(created by `transition()`) to an attribute's `cfg` parameter: + +```python +# example/rules.bzl +load("example/transitions:transitions.bzl", "coffee_transition") +drink_rule = rule( + implementation = _impl, + attrs = { "dep": attr.label(cfg = coffee_transition)} + ... +``` +Outgoing edge transitions can be 1:1 or 1:2+. + +See [Accessing attributes with transitions](#accessing-attributes-with-transitions) +for how to read these keys. + +### Transitions on native options {:#transitions-native-options} + +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/transition_on_native_flag){: .external} + +Starlark transitions can also declare reads and writes on native build +configuration options via a special prefix to the option name. + +```python +# example/transitions/transitions.bzl +def _impl(settings, attr): + _ignore = (settings, attr) + return {"//command_line_option:cpu": "k8"} + +cpu_transition = transition( + implementation = _impl, + inputs = [], + outputs = ["//command_line_option:cpu"] +``` + +#### Unsupported native options {:#unsupported-native-options} + +Bazel doesn't support transitioning on `--define` with +`"//command_line_option:define"`. Instead, use a custom +[build setting](#user-defined-build-settings). In general, new usages of +`--define` are discouraged in favor of build settings. + +Bazel doesn't support transitioning on `--config`. This is because `--config` is +an "expansion" flag that expands to other flags. + +Crucially, `--config` may include flags that don't affect build configuration, +such as +[`--spawn_strategy`](/docs/user-manual#spawn-strategy) +. Bazel, by design, can't bind such flags to individual targets. This means +there's no coherent way to apply them in transitions. + +As a workaround, you can explicitly itemize the flags that *are* part of +the configuration in your transition. This requires maintaining the `--config`'s +expansion in two places, which is a known UI blemish. + +### Transitions on allow multiple build settings {:#transitions-multiple-build-settings} + +When setting build settings that +[allow multiple values](#defining-multi-set-string-flags), the value of the +setting must be set with a list. + +```python +# example/buildsettings/build_settings.bzl +string_flag = rule( + implementation = _impl, + build_setting = config.string(flag = True, allow_multiple = True) +) +``` + +```python +# example/BUILD +load("//example/buildsettings:build_settings.bzl", "string_flag") +string_flag(name = "roasts", build_setting_default = "medium") +``` + +```python +# example/transitions/rules.bzl +def _transition_impl(settings, attr): + # Using a value of just "dark" here will throw an error + return {"//example:roasts" : ["dark"]}, + +coffee_transition = transition( + implementation = _transition_impl, + inputs = [], + outputs = ["//example:roasts"] +) +``` + +### No-op transitions {:#no-op-transitions} + +If a transition returns `{}`, `[]`, or `None`, this is shorthand for keeping all +settings at their original values. This can be more convenient than explicitly +setting each output to itself. + +```python +# example/transitions/transitions.bzl +def _impl(settings, attr): + _ignore = (attr) + if settings["//example:already_chosen"] is True: + return {} + return { + "//example:favorite_flavor": "dark chocolate", + "//example:include_marshmallows": "yes", + "//example:desired_temperature": "38C", + } + +hot_chocolate_transition = transition( + implementation = _impl, + inputs = ["//example:already_chosen"], + outputs = [ + "//example:favorite_flavor", + "//example:include_marshmallows", + "//example:desired_temperature", + ] +) +``` + +### Accessing attributes with transitions {:#accessing-attributes-with-transitions} + +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/read_attr_in_transition){: .external} + +When [attaching a transition to an outgoing edge](#outgoing-edge-transitions) +(regardless of whether the transition is a 1:1 or 1:2+ transition), `ctx.attr` is forced to be a list +if it isn't already. The order of elements in this list is unspecified. + +```python +# example/transitions/rules.bzl +def _transition_impl(settings, attr): + return {"//example:favorite_flavor" : "LATTE"}, + +coffee_transition = transition( + implementation = _transition_impl, + inputs = [], + outputs = ["//example:favorite_flavor"] +) + +def _rule_impl(ctx): + # Note: List access even though "dep" is not declared as list + transitioned_dep = ctx.attr.dep[0] + + # Note: Access doesn't change, other_deps was already a list + for other_dep in ctx.attr.other_deps: + # ... + +coffee_rule = rule( + implementation = _rule_impl, + attrs = { + "dep": attr.label(cfg = coffee_transition) + "other_deps": attr.label_list(cfg = coffee_transition) + }) +``` + +If the transition is `1:2+` and sets custom keys, `ctx.split_attr` can be used +to read individual deps for each key: + +```python +# example/transitions/rules.bzl +def _impl(settings, attr): + _ignore = (settings, attr) + return { + "Apple deps": {"//command_line_option:cpu": "ppc"}, + "Linux deps": {"//command_line_option:cpu": "x86"}, + } + +multi_arch_transition = transition( + implementation = _impl, + inputs = [], + outputs = ["//command_line_option:cpu"] +) + +def _rule_impl(ctx): + apple_dep = ctx.split_attr.dep["Apple deps"] + linux_dep = ctx.split_attr.dep["Linux deps"] + # ctx.attr has a list of all deps for all keys. Order is not guaranteed. + all_deps = ctx.attr.dep + +multi_arch_rule = rule( + implementation = _rule_impl, + attrs = { + "dep": attr.label(cfg = multi_arch_transition) + }) +``` + +See [complete example](https://github.com/bazelbuild/examples/tree/main/configurations/multi_arch_binary) +here. + +## Integration with platforms and toolchains {:#integration-platforms-toolchains} + +Many native flags today, like `--cpu` and `--crosstool_top` are related to +toolchain resolution. In the future, explicit transitions on these types of +flags will likely be replaced by transitioning on the +[target platform](/extending/platforms). + +## Memory and performance considerations {:#memory-performance-considerations} + +Adding transitions, and therefore new configurations, to your build comes at a +cost: larger build graphs, less comprehensible build graphs, and slower +builds. It's worth considering these costs when considering +using transitions in your build rules. Below is an example of how a transition +might create exponential growth of your build graph. + +### Badly behaved builds: a case study {:#badly-behaved-builds} + +![Scalability graph](/rules/scalability-graph.png "Scalability graph") + +**Figure 1.** Scalability graph showing a top level target and its dependencies. + +This graph shows a top level target, `//pkg:app`, which depends on two targets, a +`//pkg:1_0` and `//pkg:1_1`. Both these targets depend on two targets, `//pkg:2_0` and +`//pkg:2_1`. Both these targets depend on two targets, `//pkg:3_0` and `//pkg:3_1`. +This continues on until `//pkg:n_0` and `//pkg:n_1`, which both depend on a single +target, `//pkg:dep`. + +Building `//pkg:app` requires \\(2n+2\\) targets: + +* `//pkg:app` +* `//pkg:dep` +* `//pkg:i_0` and `//pkg:i_1` for \\(i\\) in \\([1..n]\\) + +Imagine you [implement](#user-defined-build-settings) a flag +`--//foo:owner=` and `//pkg:i_b` applies + + depConfig = myConfig + depConfig.owner="$(myConfig.owner)$(b)" + +In other words, `//pkg:i_b` appends `b` to the old value of `--owner` for all +its deps. + +This produces the following [configured targets](/reference/glossary#configured-target): + +``` +//pkg:app //foo:owner="" +//pkg:1_0 //foo:owner="" +//pkg:1_1 //foo:owner="" +//pkg:2_0 (via //pkg:1_0) //foo:owner="0" +//pkg:2_0 (via //pkg:1_1) //foo:owner="1" +//pkg:2_1 (via //pkg:1_0) //foo:owner="0" +//pkg:2_1 (via //pkg:1_1) //foo:owner="1" +//pkg:3_0 (via //pkg:1_0 → //pkg:2_0) //foo:owner="00" +//pkg:3_0 (via //pkg:1_0 → //pkg:2_1) //foo:owner="01" +//pkg:3_0 (via //pkg:1_1 → //pkg:2_0) //foo:owner="10" +//pkg:3_0 (via //pkg:1_1 → //pkg:2_1) //foo:owner="11" +... +``` + +`//pkg:dep` produces \\(2^n\\) configured targets: `config.owner=` +"\\(b_0b_1...b_n\\)" for all \\(b_i\\) in \\(\{0,1\}\\). + +This makes the build graph exponentially larger than the target graph, with +corresponding memory and performance consequences. + +TODO: Add strategies for measurement and mitigation of these issues. + +## Further reading {:#further-reading} + +For more details on modifying build configurations, see: + + * [Starlark Build Configuration](https://docs.google.com/document/d/1vc8v-kXjvgZOdQdnxPTaV0rrLxtP2XwnD2tAZlYJOqw/edit?usp=sharing){: .external} + * Full [set](https://github.com/bazelbuild/examples/tree/HEAD/configurations){: .external} of end to end examples diff --git a/extending/exec-groups.mdx b/extending/exec-groups.mdx index f785db8cf..aa70cb1ec 100644 --- a/extending/exec-groups.mdx +++ b/extending/exec-groups.mdx @@ -111,7 +111,7 @@ problem. The following execution groups are predefined: * `test`: Test runner actions (for more details, see - the [execution platform section of the Test Encyclopedia](/reference/test-encyclopedia#execution-platform)). + the [execution platform section of the Test Encyclopedia](/reference/test-encyclopedia#execution-platform)). * `cpp_link`: C++ linking actions. ## Using execution groups to set execution properties diff --git a/extending/platforms.mdx b/extending/platforms.mdx index 9304d80bc..920328e71 100644 --- a/extending/platforms.mdx +++ b/extending/platforms.mdx @@ -72,18 +72,18 @@ builds target the same machine Bazel runs on. Build rules can [@platforms/cpu](https://github.com/bazelbuild/platforms/blob/main/cpu/BUILD) constraints. -## Generally useful constraints and platforms +## Generally useful constraints and platforms {:#useful-constraints-platforms} To keep the ecosystem consistent, Bazel team maintains a repository with constraint definitions for the most popular CPU architectures and operating systems. These are all defined in -[https://github.com/bazelbuild/platforms](https://github.com/bazelbuild/platforms). +[https://github.com/bazelbuild/platforms](https://github.com/bazelbuild/platforms){: .external}. Bazel ships with the following special platform definition: `@platforms//host` (aliased as `@bazel_tools//tools:host_platform`). This auto-detects the OS and CPU properties of the machine Bazel runs on. -## Defining constraints +## Defining constraints {:#constraints} Constraints are modeled with the [`constraint_setting`][constraint_setting] and [`constraint_value`][constraint_value] build rules. @@ -113,7 +113,7 @@ the `x86` constraint as `//cpus:x86`. If visibility allows, you can extend an existing `constraint_setting` by defining your own value for it. -## Defining platforms +## Defining platforms {:#platforms} The [`platform`](/reference/be/platforms-and-toolchains#platform) build rule defines a platform as a collection of `constraint_value`s: @@ -135,7 +135,7 @@ Platforms may only have one `constraint_value` for a given `constraint_setting`. This means, for example, a platform can't have two CPUs unless you create another `constraint_setting` type to model the second value. -## Skipping incompatible targets +## Skipping incompatible targets {:#skipping-incompatible-targets} When building for a specific target platform it is often desirable to skip targets that will never work on that platform. For example, your Windows device @@ -165,7 +165,7 @@ incompatible with all else. Incompatibility is transitive. Any targets that transitively depend on an incompatible target are themselves considered incompatible. -### When are targets skipped? +### When are targets skipped? {:#when-targets-skipped} Targets are skipped when they are considered incompatible and included in the build as part of a target pattern expansion. For example, the following two @@ -200,7 +200,7 @@ FAILED: Build did NOT complete successfully Incompatible explicit targets are silently skipped if `--skip_incompatible_explicit_targets` is enabled. -### More expressive constraints +### More expressive constraints {:#expressive-constraints} For more flexibility in expressing constraints, use the `@platforms//:incompatible` @@ -235,8 +235,8 @@ The above can be interpreted as follows: deemed incompatible. To make your constraints more readable, use -[skylib](https://github.com/bazelbuild/bazel-skylib)'s -[`selects.with_or()`](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/selects_doc.md#selectswith_or). +[skylib](https://github.com/bazelbuild/bazel-skylib){: .external}'s +[`selects.with_or()`](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/selects_doc.md#selectswith_or){: .external}. You can express inverse compatibility in a similar way. The following example describes a library that is compatible with everything _except_ for ARM. @@ -252,7 +252,7 @@ cc_library( ) ``` -### Detecting incompatible targets using `bazel cquery` +### Detecting incompatible targets using `bazel cquery` {:#cquery-incompatible-target-detection} You can use the [`IncompatiblePlatformProvider`](/rules/lib/providers/IncompatiblePlatformProvider) diff --git a/extending/toolchains.mdx b/extending/toolchains.mdx index 0d92d6e18..249eaf06c 100644 --- a/extending/toolchains.mdx +++ b/extending/toolchains.mdx @@ -409,21 +409,79 @@ bar_toolchain = rule( The use of [`attr.label`](/rules/lib/toplevel/attr#label) is the same as for a standard rule, but the meaning of the `cfg` parameter is slightly different. -The dependency from a target (called the "parent") to a toolchain via toolchain -resolution uses a special configuration transition called the "toolchain -transition". The toolchain transition keeps the configuration the same, except -that it forces the execution platform to be the same for the toolchain as for -the parent (otherwise, toolchain resolution for the toolchain could pick any -execution platform, and wouldn't necessarily be the same as for parent). This -allows any `exec` dependencies of the toolchain to also be executable for the -parent's build actions. Any of the toolchain's dependencies which use `cfg = -"target"` (or which don't specify `cfg`, since "target" is the default) are -built for the same target platform as the parent. This allows toolchain rules to -contribute both libraries (the `system_lib` attribute above) and tools (the -`compiler` attribute) to the build rules which need them. The system libraries -are linked into the final artifact, and so need to be built for the same -platform, whereas the compiler is a tool invoked during the build, and needs to -be able to run on the execution platform. +When a target (the "parent") depends on a toolchain via toolchain resolution, +Bazel applies a special configuration transition called the "toolchain transition". + +In this transition Bazel keeps the overall configuration identical, but forces +the toolchain to use the same execution platform as the parent. Without this, +toolchain resolution could pick a different execution platform for the +toolchain, and the tools it provides might not be runnable for the parent's +actions. + +This alignment of execution platforms guarantees that any dependencies of the +toolchain declared with `cfg = "exec"` are built so they can run where the +parent's actions run. + +Dependencies declared with `cfg = "target"` (or which omit `cfg`, since +"target" is the default) are built for the parent's target platform. This lets +the toolchain contribute both runtime libraries and build-time tools. + +In practice: + +- `cfg = "exec"`: build artifacts intended to run during the build (e.g. + the `compiler` tool) and therefore for the execution platform. +- `cfg = "target"`: build artifacts intended to be linked into or shipped with + the final output (e.g. the `system_lib`) and therefore for the target + platform. + +The system libraries must be built for the same target platform as the final +artifact, while the compiler must be runnable on the execution platform. + +### Selecting `exec` dependencies + +For toolchain config rules, adding a `select()` to an attribute with `cfg = "exec"` +does **not** make the `select()` use the exec configuration. +It will still be resolved under the **target** configuration. + +Assuming the target platform is not matching any of these constraints, the select for the compiler +will fail to analyze. + +```python +bar_toolchain( + name = "barc_omni", + compiler = select({ + "@platforms//os:linux": Label(":linux_compiler"), + "@platforms//os:windows": Label(":windows_compiler"), + "//some/exec:platform": Label(":special_compiler"), + }, + no_match_error = "No compiler for this execution platform", + }), + # <...> +) +``` + +A known workaround for this is to defer the evaluation behind another target, +e.g. [`alias()`](/reference/be/general#alias). +This analyzes the `select` inside the alias under the exec configuration. + +```python +alias( + name = "host_specific_compiler", + actual = select({ + "@platforms//os:linux": Label(":linux_compiler"), + "@platforms//os:windows": Label(":windows_compiler"), + "//some/exec:platform": Label(":special_compiler"), + }, + no_match_error = "No compiler for this execution platform", + ), +) + +bar_toolchain( + name = "barc_omni", + compiler = ":host_specific_compiler", + # <...> +) +``` ## Registering and building with toolchains @@ -568,6 +626,12 @@ If the rule uses [execution groups](/extending/exec-groups), each execution group performs toolchain resolution separately, and each has its own execution platform and toolchains. +**TIP:** For a toolchain to match a platform, the platform must define *all* of +the toolchain's constraints. But the reverse isn't true: the platform may define +additional constraints not specified by the toolchain. This lets developers +define arbitrarily precise platforms that don't lose toolchain compatibility +because of unrelated hardware variants. + ## Debugging toolchains If you are adding toolchain support to an existing rule, use the diff --git a/external/faq.mdx b/external/faq.mdx index 0d358f08b..480658fbc 100644 --- a/external/faq.mdx +++ b/external/faq.mdx @@ -365,3 +365,4 @@ fetched](https://github.com/bazelbuild/bazel/discussions/20464). [go_deps]: https://github.com/bazel-contrib/rules_go/blob/master/docs/go/core/bzlmod.md#specifying-external-dependencies [bazelisk-config]: https://github.com/bazelbuild/bazelisk?tab=readme-ov-file#where-does-bazelisk-get-bazel-from [bcr-disclaimer]: https://github.com/bazelbuild/bazel-central-registry?tab=readme-ov-file#disclaimer + diff --git a/external/migration_tool.mdx b/external/migration_tool.mdx new file mode 100644 index 000000000..522e9ee8f --- /dev/null +++ b/external/migration_tool.mdx @@ -0,0 +1,728 @@ +keywords: bzlmod + +{# disableFinding(LINE_OVER_80_LINK) #} +{# disableFinding(SNIPPET_NO_LANG) #} +{# disableFinding(LINK_MISSING_ID) #} +{# disableFinding("repo") #} + +--- +title: 'Bzlmod Migration Tool' +--- + +[migration_script]: https://github.com/bazelbuild/bazel-central-registry/blob/main/tools/migrate_to_bzlmod.py +[gemini_cli_setup]: https://github.com/bazelbuild/bazel-central-registry/tree/main/tools/code-agent + +To simplify the often complex process of moving from `WORKSPACE` to Bzlmod, it's +highly recommended to use the [migration script][migration_script]. This helper +tool automates many of the steps involved in migrating your external dependency +management system. + +**Note**: If you want to try out the AI driven Bzlmod migration, check [Bzlmod Migration Agent Setup][gemini_cli_setup]. + +## Core Functionality {:#migration-tool-core-functionality} + +The script's primary functions are: + +* **Collecting dependency information:** Analyzing your project's `WORKSPACE` + file to identify external repositories used by specified build targets, + using Bazel's + [experimental_repository_resolved_file](https://bazel.build/versions/8.2.0/reference/command-line-reference#flag--experimental_repository_resolved_file) + flag to generate a resolved dependencies file containing this information. +* **Identifying direct dependencies:** Using `bazel query` to determine which + repositories are direct dependencies for the specified targets. +* **Migrating to Bzlmod:** Translating relevant `WORKSPACE` dependencies into + their Bzlmod equivalents. This is a two-step process: + 1. Introduce all identified direct dependencies to the + `MODULE.bazel` file. + 2. Build specified targets with Bzlmod enabled, then + iteratively identify and fix recognizable errors. This step is + needed since some dependencies might be missing in the first step. +* **Generating a migration report:** Creating a `migration_info.md` file that + documents the migration process. This report includes a list of direct + dependencies, the generated Bzlmod declarations, and any manual steps that + may be required to complete the migration. + +The migration tool supports: + +* Dependencies available in the Bazel Central Registry +* User-defined custom repository rules +* Package manager dependencies + * Maven + * Go + * Python + +**Important Notes**: + +* The migration tool is a best-effort utility. Always double-check its +recommendations for correctness. +* Use the migration tool with Bazel 7 (not supported with Bazel 8). + +## How to Use the Migration Tool {:#migration-tool-how-to-use} + +Before you begin: + +* Upgrade to the latest Bazel 7 release, which provides robust support for + both WORKSPACE and Bzlmod. +* Verify the following command runs successfully for your project's main build + targets: + + ```shell + bazel build --nobuild --enable_workspace --noenable_bzlmod + ``` + +### Command for running the script {:#migration-script-command} + +Once the prerequisites are met, run the following commands to use the migration +tool: + +
+# Clone the Bazel Central Registry repository
+git clone https://github.com/bazelbuild/bazel-central-registry.git
+cd bazel-central-registry
+
+# Build the migration tool
+bazel build //tools:migrate_to_bzlmod
+
+# Create a convenient alias for the tool
+alias migrate2bzlmod=$(realpath ./bazel-bin/tools/migrate_to_bzlmod)
+
+# Navigate to your project's root directory and run the tool
+cd <your project root>
+migrate2bzlmod -t <targets>
+
+ +### Files generated by this script {:#migration-script-files} + +* `MODULE.bazel` - The central manifest file for Bzlmod, which declares the + project's metadata and its direct dependencies on other Bazel modules. +* `migration_info.md` - A file providing step-by-step instructions on how the + migration tool was executed, designed to assist in the manual completion of + the migration process, if necessary. +* `resolved_deps.py` - Contains a comprehensive list of the project's external + dependencies, generated by analyzing the project's `WORKSPACE` file, serving + as a reference during the transition. +* `query_direct_deps` - Contains migration-relevant information regarding the + utilized targets, obtained by invoking Bazel with `--output=build` on the + project's `WORKSPACE` file. This file is primarily consumed by the migration + script. +* `extension_for_XXX` - A file containing a module extension + definition. The migration tool generates these files for dependencies that + are not standard Bazel modules but can be managed using Bzlmod's [module + extensions](/external/extension). + +### Flags {:#migration-script-flags} + +Flags available in this migration scripts are: + +* `--t`/`--target`: Targets to migrate. This flag is repeatable, and the + targets are accumulated. +* `--i`/`--initial`: Deletes `MODULE.bazel`, `resolved_deps.py`, + `migration_info.md` files and starts from scratch - Detect direct + dependencies, introduce them in MODULE.bazel and rerun generation of + resolved dependencies. + +### Post-migration cleanup {:#post-migration-cleanup} + +* Delete `migration_info.md`, `resolved_deps.py` and `query_direct_deps`. +* Clean up comments from `MODULE.bazel` file which were used for the + migration, such as `# -- bazel_dep definitions -- #`. + +## Migration Example {:#migration-tool-example} + +To see the migration script in action, consider the following scenario when +Python, Maven and Go dependencies are declared in `WORKSPACE` file. + +
+ +Click here to see `WORKSPACE` file + + +```python +workspace(name="example") + +load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") +load(":my_custom_macro.bzl", "my_custom_macro") + +http_archive( + name = "rules_cc", + sha256 = "b8b918a85f9144c01f6cfe0f45e4f2838c7413961a8ff23bc0c6cdf8bb07a3b6", + strip_prefix = "rules_cc-0.1.5", + urls = ["https://github.com/bazelbuild/rules_cc/releases/download/0.1.5/rules_cc-0.1.5.tar.gz"], +) + +# Module dependency +# ------------------- +http_archive( + name = "rules_shell", + sha256 = "3e114424a5c7e4fd43e0133cc6ecdfe54e45ae8affa14fadd839f29901424043", + strip_prefix = "rules_shell-0.4.0", + url = "https://github.com/bazelbuild/rules_shell/releases/download/v0.4.0/rules_shell-v0.4.0.tar.gz", +) + +# Repo rule +# ------------------- +http_archive( + name = "com_github_cockroachdb_cockroach", + sha256 = "6c3568ef244ce6b874694eeeecb83ed4f5d5dff6cf037c952ecde76828a6c502", + strip_prefix = "cockroach-22.1.6", + url = "https://github.com/cockroachdb/cockroach/archive/v22.1.6.tar.gz", +) + +# Module extension +# ------------------- +# Macro which invokes repository_rule +my_custom_macro( + name = "my_custom_repo", +) + +# Go dependencies +# ------------------- +http_archive( + name = "io_bazel_rules_go", + integrity = "sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=", + urls = [ + "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip", + "https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip", + ], +) + +http_archive( + name = "bazel_gazelle", + integrity = "sha256-12v3pg/YsFBEQJDfooN6Tq+YKeEWVhjuNdzspcvfWNU=", + urls = [ + "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz", + "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz", + ], +) + +load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies") +load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository") + +go_rules_dependencies() +go_register_toolchains(version = "1.23.1") +gazelle_dependencies() + +go_repository( + name = "org_golang_x_net", + importpath = "golang.org/x/net", + sum = "h1:oWX7TPOiFAMXLq8o0ikBYfCJVlRHBcsciT5bXOrH628=", + version = "v0.0.0-20190311183353-d8887717615a", + build_file_proto_mode = "disable", + build_naming_convention = "import", +) + +# Python dependencies +# ------------------- +http_archive( + name = "rules_python", + integrity = "sha256-qDdnnxOC8mlowe5vg5x9r5B5qlMSgGmh8oFd7KpjcwQ=", + strip_prefix = "rules_python-1.4.0", + url = "https://github.com/bazelbuild/rules_python/releases/download/1.4.0/rules_python-1.4.0.tar.gz", +) + +load("@rules_python//python:repositories.bzl", "py_repositories") +py_repositories() + +load("@rules_python//python:pip.bzl", "pip_parse") +pip_parse( + name = "my_python_deps", + requirements_lock = "@example//:requirements_lock.txt", +) + +load("@my_python_deps//:requirements.bzl", "install_deps") +install_deps() + +load("@rules_python//python:repositories.bzl", "python_register_toolchains") +python_register_toolchains( + name = "python_3_11", + python_version = "3.11", +) + +# Maven dependencies +# __________________ + +RULES_JVM_EXTERNAL_TAG = "4.5" +RULES_JVM_EXTERNAL_SHA = "b17d7388feb9bfa7f2fa09031b32707df529f26c91ab9e5d909eb1676badd9a6" + +http_archive( + name = "rules_jvm_external", + strip_prefix = "rules_jvm_external-%s" % RULES_JVM_EXTERNAL_TAG, + sha256 = RULES_JVM_EXTERNAL_SHA, + url = "https://github.com/bazelbuild/rules_jvm_external/archive/%s.zip" % RULES_JVM_EXTERNAL_TAG, +) + +load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps") +rules_jvm_external_deps() +load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup") +rules_jvm_external_setup() + +load("@rules_jvm_external//:defs.bzl", "maven_install") +maven_install( + name = "px_deps", + artifacts = [ + "org.antlr:antlr4:4.11.1", + ], + repositories = [ + "https://repo1.maven.org/maven2", + ], +) +``` +
+ +Moreover, to demonstrate usage of module extension, custom macro is invoked from +`WORKSPACE` and it is defined in `my_custom_macro.bzl`. + +
+ +Click here to see `my_custom_macro.bzl` file + + +```python +"""Repo rule and macro used for testing""" + +def _test_repo_rule_impl(repository_ctx): + repository_ctx.file( + "BUILD", + content = """ +genrule( + name = "foo", + outs = ["rule_name.out"], + cmd = "touch $@", + visibility = ["//visibility:public"], +) +""" + ) + +_test_repo_rule = repository_rule( + implementation = _test_repo_rule_impl, +) + +def my_custom_macro(name): + _test_repo_rule(name = name) +``` +
+ +The end goal is to have `MODULE.bazel` file and delete the `WORKSPACE` file, +without impacting the user experience. + +The first step is to follow [How to Use the Migration +Tool](#migration-tool-how-to-use), which mostly is checking the bazel version +(it must be Bazel 7) and adding an alias to the migration script. + +Then, running `migrate2bzlmod -t=//...` outputs: + +
+  bazel 7.6.1
+
+  Generating ./resolved_deps.py file - It might take a while...
+
+  RESOLVED: rules_java has been introduced as a Bazel module.
+  RESOLVED: bazel_gazelle has been introduced as a Bazel module.
+  RESOLVED: io_bazel_rules_go has been introduced as a Bazel module.
+  RESOLVED: rules_python has been introduced as a Bazel module.
+  IMPORTANT: 3.11 is used as a default python version. If you need a different version, please change it manually and then rerun the migration tool.
+  RESOLVED: my_python_deps has been introduced as python extension.
+  RESOLVED: org_golang_x_net has been introduced as go extension.
+  RESOLVED: rules_jvm_external has been introduced as a Bazel module.
+  RESOLVED: org.antlr has been introduced as maven extension.
+  RESOLVED: rules_shell has been introduced as a Bazel module.
+
+  Congratulations! All external repositories needed for building //... are available with Bzlmod!
+  IMPORTANT: Fix potential build time issues by running the following command:
+      bazel build --enable_bzlmod --noenable_workspace //...
+
+  IMPORTANT: For details about the migration process, check `migration_info.md` file.
+
+ +which gives the following important information: + +* Generates `./resolved_deps.py` file, which contains info about all external + repositories declared and loaded using your `WORKSPACE` file. +* `RESOLVED` keyword describes all dependencies which are resolved by the tool + and added to the `MODULE.bazel` file. +* `IMPORTANT` keyword describes significant information worth investing time. +* All dependencies have been resolved in this example, at least with + `--nobuild` flag. +* It is important to run the full build (command specified) and manually fix + potential errors (e.g. toolchain not registered correctly). +* `migration_info.md` file contains details about the migration. Check details + [at this section](#migration-tool-report-generation). + +### Transformations {:#migration-tool-transformations} + +This section illustrates the migration of code from the `WORKSPACE` file to +`MODULE.bazel`. + +
+
+

WORKSPACE - Bazel Module

+ 
+http_archive(
+    name = "rules_shell",
+    sha256 = "3e114424a5c7e4fd43e0133cc6ecdfe54e45ae8affa14fadd839f29901424043",
+    strip_prefix = "rules_shell-0.4.0",
+    url = "https://github.com/bazelbuild/rules_shell/releases/download/v0.4.0/rules_shell-v0.4.0.tar.gz",
+)
+
+
+
+

MODULE.bazel - Bazel Module

+ 
+bazel_dep(name = "rules_shell", version = "0.6.1")
+
+
+
+ +
+ +
+
+

WORKSPACE - Go Extension

+ 
+http_archive(
+    name = "io_bazel_rules_go",
+    integrity = "sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
+        "https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
+    ],
+)
+http_archive(
+    name = "bazel_gazelle",
+    integrity = "sha256-12v3pg/YsFBEQJDfooN6Tq+YKeEWVhjuNdzspcvfWNU=",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
+        "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
+    ],
+)
+
+load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
+load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository")
+
+go_rules_dependencies()
+go_register_toolchains(version = "1.23.1")
+gazelle_dependencies()
+
+go_repository(
+    name = "org_golang_x_net",
+    importpath = "golang.org/x/net",
+    sum = "h1:oWX7TPOiFAMXLq8o0ikBYfCJVlRHBcsciT5bXOrH628=",
+    version = "v0.0.0-20190311183353-d8887717615a",
+    build_file_proto_mode = "disable",
+    build_naming_convention = "import",
+)
+
+
+
+

MODULE.bazel - Go Extension

+ 
+go_deps = use_extension("@bazel_gazelle//:extensions.bzl", "go_deps")
+go_sdk = use_extension("@io_bazel_rules_go//go:extensions.bzl", "go_sdk")
+
+go_deps.from_file(go_mod = "//:go.mod")
+use_repo(go_deps, "org_golang_x_net")
+go_sdk.from_file(go_mod = "//:go.mod")
+
+go_deps.gazelle_override(
+    path = "golang.org/x/net",
+    directives = [
+        "gazelle:proto disable",
+         "gazelle:go_naming_convention import",
+    ],
+)
+
+
+
+ +
+ +
+
+

WORKSPACE - Python Extension

+ 
+http_archive(
+    name = "rules_python",
+    integrity = "sha256-qDdnnxOC8mlowe5vg5x9r5B5qlMSgGmh8oFd7KpjcwQ=",
+    strip_prefix = "rules_python-1.4.0",
+    url = "https://github.com/bazelbuild/rules_python/releases/download/1.4.0/rules_python-1.4.0.tar.gz",
+)
+
+load("@rules_python//python:repositories.bzl", "py_repositories")
+py_repositories()
+
+load("@rules_python//python:pip.bzl", "pip_parse")
+pip_parse(
+   name = "my_python_deps",
+   requirements_lock = "@example//:requirements_lock.txt",
+)
+
+load("@my_python_deps//:requirements.bzl", "install_deps")
+install_deps()
+
+load("@rules_python//python:repositories.bzl", "python_register_toolchains")
+python_register_toolchains(
+    name = "python_3_11",
+    python_version = "3.11",
+)
+
+
+
+

MODULE.bazel - Python Extension

+ 
+pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
+pip.parse(
+    hub_name = "my_python_deps",
+    python_version = "3.11",
+    requirements_lock = "//:requirements_lock.txt",
+)
+use_repo(pip, "my_python_deps")
+
+python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.defaults(python_version = "3.11")
+python.toolchain(python_version = "3.11")
+
+
+
+ +
+ +
+
+

WORKSPACE - Maven Extension

+ 
+
+RULES_JVM_EXTERNAL_TAG = "4.5"
+RULES_JVM_EXTERNAL_SHA = "b17d7388feb9bfa7f2fa09031b32707df529f26c91ab9e5d909eb1676badd9a6"
+
+http_archive(
+    name = "rules_jvm_external",
+    strip_prefix = "rules_jvm_external-%s" % RULES_JVM_EXTERNAL_TAG,
+    sha256 = RULES_JVM_EXTERNAL_SHA,
+    url = "https://github.com/bazelbuild/rules_jvm_external/archive/%s.zip" % RULES_JVM_EXTERNAL_TAG,
+)
+
+load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")
+rules_jvm_external_deps()
+load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")
+rules_jvm_external_setup()
+
+load("@rules_jvm_external//:defs.bzl", "maven_install")
+maven_install(
+    name = "px_deps",
+    artifacts = [
+        "org.antlr:antlr4:4.11.1",
+    ],
+    repositories = [
+        "https://repo1.maven.org/maven2",
+    ],
+)
+
+
+
+

MODULE.bazel - Maven Extension

+ 
+bazel_dep(name = "rules_jvm_external", version = "6.8")
+
+maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
+use_repo(maven, "px_deps")
+
+maven.artifact(
+    name = "px_deps",
+    group = "org.antlr",
+    artifact = "antlr4",
+    version = "4.11.1"
+)
+
+
+
+ +
+ +
+
+

WORKSPACE - Repo rule

+ 
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "com_github_cockroachdb_cockroach",
+    sha256 = "6c3568ef244ce6b874694eeeecb83ed4f5d5dff6cf037c952ecde76828a6c502",
+    strip_prefix = "cockroach-22.1.6",
+    url = "https://github.com/cockroachdb/cockroach/archive/v22.1.6.tar.gz",
+)
+
+
+
+

MODULE.bazel - Repo rule

+ 
+http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+  name = "com_github_cockroachdb_cockroach",
+  url = "https://github.com/cockroachdb/cockroach/archive/v22.1.6.tar.gz",
+  sha256 = "6c3568ef244ce6b874694eeeecb83ed4f5d5dff6cf037c952ecde76828a6c502",
+  strip_prefix = "cockroach-22.1.6",
+)
+
+
+
+ +
+ +
+
+

WORKSPACE - Module extension

+ 
+load(":my_custom_macro.bzl", "my_custom_macro")
+
+my_custom_macro(
+    name = "my_custom_repo",
+)
+
+
+
+

MODULE.bazel - Module extension

+ 
+extension_for_my_custom_macro = use_extension("//:extension_for_my_custom_macro.bzl", "extension_for_my_custom_macro")
+use_repo(extension_for_my_custom_macro, "my_custom_repo")
+
+

extension_for_my_custom_macro.bzl

+ 
+load("//:my_custom_macro.bzl", "my_custom_macro")
+
+def _extension_for_my_custom_macro_impl(ctx):
+  my_custom_macro(
+    name = "my_custom_repo",
+  )
+
+extension_for_my_custom_macro = module_extension(implementation = _extension_for_my_custom_macro_impl)
+
+
+
+ +
+ +## Tips with debugging {:#migration-tool-tips} + +This section provides useful commands and information to help debug issues that +may arise during the Bzlmod migration. + +### Useful tips {:#debugging-useful-tips} + +* Override version - Not rarely it happens that upgrading the version of a + dependency causes troubles. Bzlmod could change the version of the + dependency due to the [MVS algorithm](/external/module#version-selection). + In order to use the same or similar version as it was in the WORKSPACE, + override it with + [single_version_override](/rules/lib/globals/module#single_version_override). + Note that this is useful for debugging differences between WORKSPACE and + Bzlmod, but you shouldn't rely on this feature in the long term. + + `single_version_override(module_name = "{dep_name}", version = "{version}")` + +* Use [bazel mod](/external/mod-command#syntax) command. + * Check the version of a specified repo with `show_repo` + command. For example: + + `bazel mod show_repo @rules_python` + + * Check information about a module extension with the `show_extension` + command. For example: + + `bazel mod show_extension @rules_python//python/extensions:pip.bzl%pip` + +* Use [vendor mode](/external/vendor) to create a local copy of a repo when + you want to monitor or control the source of the repo. For example: + + `bazel vendor --enable_bzlmod --vendor_dir=vendor_src --repo=@protobuf` + +### Migration Report Generation {:#migration-tool-report-generation} + +This file is updated with each run of the migration script or it's generated +from scratch if it's the first run or if the [`--i` +flag](#migration-script-flags) is used. The report contains: + +* Command for local testing. +* List of direct dependencies (at least the ones which are directly used in + the project). +* For each dependency, a drop-down menu for checking where the repository was + declared in the `WORKSPACE` file, which is particularly useful for the + debugging. You can see it as: + + 
+    > Click here to see where and how the repo was declared in the WORKSPACE
+    file
+
+ +* For each dependency, how it was implemented in `MODULE.bazel` file. From the + earlier [Migration Example](#migration-tool-example), that would look as: + 1. Bazel module Dependency - `Migration of rules_python` + + 
+        Found perfect name match in BCR: rules_python
+        Found partially name matches in BCR: rules_python_gazelle_plugin
+
+        It has been introduced as a Bazel module:
+            `bazel_dep(name = "rules_python", version = "1.6.1")`
+
+ + * The script will automatically use the `perfect name match` if it finds + it. In case of an error, you can double check if the name was correctly + added. + 2. Python extension - `Migration of my_python_deps` + + 
+        pip.parse(
+            hub_name = "my_python_deps",
+            requirements_lock = "//:requirements_lock.txt",
+            python_version = "3.11",
+        )
+        use_repo(pip, "my_python_deps")
+
+ + 3. Maven extension - `Migration of org.antlr (px_deps):` + + 
+        maven.artifact(
+            name = "px_deps",
+            group = "org.antlr",
+            artifact = "antlr4",
+            version = "4.11.1"
+        )
+
+ + 4. Go extension - `Migration of org_golang_x_net` + + 
+        go_deps.from_file(go_mod = "//:go.mod")
+        go_sdk.from_file(go_mod = "//:go.mod")
+
+        go_deps.gazelle_override(
+            path = "golang.org/x/net",
+            directives = [
+                "gazelle:proto disable",
+                "gazelle:go_naming_convention import",
+            ],
+        )
+
+ + * It has been introduced as a go module with the help of `go.mod`. If + `go.mod` and `go.sum` are not available, go module is added directly + to the `MODULE.bazel` file. + * `gazelle_override` is used for adding specific directives. + +## Useful links {:#useful-links} + +* Official pages for the external extensions + * [rules_jvm_external](https://github.com/bazelbuild/rules_jvm_external/blob/master/docs/bzlmod.md) + * [rules_go](https://github.com/bazelbuild/rules_go/blob/master/docs/go/core/bzlmod.md) + * [rules_python](https://rules-python.readthedocs.io/en/latest/pypi/download.html) +* Community posts and videos + * [Migrating to Bazel Modules](https://blog.engflow.com/2025/01/16/migrating-to-bazel-modules-aka-bzlmod---module-extensions/index.html#migrating-to-bazel-modules-aka-bzlmod-module-extensions). + * [Moving to Bzlmod](https://www.youtube.com/watch?v=W9uXRYLVHUk). + * [How Uber Manages Go Dependencies with Bzlmod](https://www.youtube.com/watch?v=hIqzkUE_pSY). + +## Feedback {:#feedback} + +If you would like to contribute, do so by creating an Issue or PR at +[bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry). diff --git a/external/mod-command.mdx b/external/mod-command.mdx new file mode 100644 index 000000000..0bf1a564f --- /dev/null +++ b/external/mod-command.mdx @@ -0,0 +1,583 @@ +keywords: Bzlmod + +--- +title: '`mod` Command' +--- + +The `mod` command provides a range of tools to help the user understand their +external dependency graph. It lets you visualize the dependency graph, find out +why a certain module or a version of a module is present in the graph, view the +repo definitions backing modules, inspect usages of module extensions and repos +they generate, among other functions. + +## Syntax {:#syntax} + +```sh +bazel mod [] [ [...]] +``` + +The available subcommands and their respective required arguments are: + +* `graph`: Displays the full dependency graph of the project, starting from + the root module. If one or more modules are specified in `--from`, these + modules are shown directly under the root, and the graph is only expanded + starting from them (see [example](#mod-example1)). + +* `deps ...`: Displays the resolved direct dependencies of each of the + specified modules, similarly to `graph`. + +* `all_paths ...`: Displays all dependency paths from the --from modules + to the target modules. To simplify the output, only the first shortest path + is shown when multiple paths share the same suffix. For example, A -> B -> X + would be shown, but the longer A -> C -> B -> X would be omitted. In other + words, for every module Y that directly depends on the target module X, the + output contains only the shortest path going through Y to reach X. + +* `path ...`: Has the same semantics as `all_paths`, but only display a + single path from one of the `--from` modules to one of the argument modules. + +* `explain ...`: Shows all the places where the specified modules appear + in the dependency graph, along with the modules that directly depend on + them. The output of the `explain` command is essentially a pruned version of + the `all_paths` command, containing 1) the root module; 2) the root module's + direct dependencies that lead to the argument modules; 3) the argument + modules' direct dependents; and + 4) the argument modules themselves (see [example](#mod-example5)). + +* `show_repo ...`: Displays the definition of the specified repos (see + [example](#mod-example6)). Use `--all_repos` to show definitions of all + repos in the entire dependency graph, or `--all_visible_repos` to show + definitions of all repos visible from the `--base_module`. + +* `show_extension ...`: Displays information about each of the + specified extensions: a list of the generated repos along with the modules + that import them using `use_repo`, and a list of the usages of that + extension in each of the modules where it is used, containing the specified + tags and the `use_repo` calls (see [example](#mod-example8)). + +`` refers to one or more modules or repos. It can be one of: + +* The literal string ``: The root module representing your current + project. + +* `@`: The module `` at version ``. For a module + with a non-registry override, use an underscore (`_`) as the ``. + +* ``: All present versions of the module ``. + +* `@`: The repo with the given [apparent + name](overview#apparent-repo-name) in the context of the `--base_module`. + +* `@@`: The repo with the given [canonical + name](overview#canonical-repo-name). + +In a context requiring specifying modules, ``s referring to repos that +correspond to modules (as opposed to extension-generated repos) can also be +used. Conversely, in a context requiring specifying repos, ``s referring to +modules can stand in for the corresponding repos. + +`` must be of the form `%`. +The `` part must be a repo-relative label (for example, +`//pkg/path:file.bzl`). + +### Graph command options + +The following options only affect the subcommands that print graphs (`graph`, +`deps`, `all_paths`, `path`, and `explain`): + +* `--from [,[,...]]` *default: ``*: The module(s) from which + the graph is expanded in `graph`, `all_paths`, `path`, and `explain`. Check + the subcommands' descriptions for more details. + +* `--verbose` *default: "false"*: Include in the output graph extra + information about the version resolution of each module. If the module + version changed during resolution, show either which version replaced it or + what was the original version, the reason it was replaced, and which modules + requested the new version if the reason was [Minimal Version + Selection](module#version-selection). + +* `--include_unused` *default: "false"*: Include in the output graph the + modules which were originally present in the dependency graph, but became + unused after module resolution. + +* `--extension_info `: Include information about the module extension + usages as part of the output graph (see [example](#mod-example7)). `` + can be one of: + + * `hidden` *(default)*: Don't show anything about extensions. + + * `usages`: Show extensions under each module where they are used. They + are printed in the form of `$`. + + * `repos`: In addition to `usages`, show the repo imported using + `use_repo` under each extension usage. + + * `all`: In addition to `usages` and `repos`, also show + extension-generated repos that are not imported by any module. These + extra repos are shown under the first occurrence of their generating + extension in the output, and are connected with a dotted edge. + +* `--extension_filter [,[,...]]`: If specified, the + output graph only includes modules that use the specified extensions, and + the paths that lead to those modules. Specifying an empty extension list (as + in `--extension_filter=`) is equivalent to specifying _all_ extensions used + by any module in the dependency graph. + +* `--depth `: The depth of the output graph. A depth of 1 only displays the + root and its direct dependencies. Defaults to 1 for `explain`, 2 for `deps` + and infinity for the others. + +* `--cycles` *default: "false"*: Include cycle edges in the output graph. + +* `--include_builtin` *default: "false"*: Include built-in modules (such as + `@bazel_tools`) in the output graph. This flag is disabled by default, as + built-in modules are implicitly depended on by every other module, which + greatly clutters the output. + +* `--charset ` *default: utf8*: Specify the charset to use for text + output. Valid values are `"utf8"` and `"ascii"`. The only significant + difference is in the special characters used to draw the graph in the + `"text"` output format, which don't exist in the `"ascii"` charset. + Therefore, the `"ascii"` charset is present to also support the usage on + legacy platforms which cannot use Unicode. + +* `--output `: Include information about the module extension usages as + part of the output graph. `' can be one of: + + * `text` *(default)*: A human-readable representation of the output graph + (flattened as a tree). + + * `json`: Outputs the graph in the form of a JSON object (flattened as a + tree). + + * `graph`: Outputs the graph in the Graphviz *dot* representation. + + Tip: Use the following command to pipe the output through the *dot* engine + and export the graph representation as an SVG image. + + ```sh + bazel mod graph --output graph | dot -Tsvg > /tmp/graph.svg + ``` + + ### show_repo options +`show_repo` supports a different set of output formats: +* `--output `: Change how repository definitions are displayed. + `` can be one of: + * `text` *(default)*: Display repo definitions in Starlark. + * `streamed_proto`: Prints a + [length-delimited](https://protobuf.dev/programming-guides/encoding/#size-limit) + stream of + [`Repository`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) + protocol buffers. + * `streamed_jsonproto`: Similar to `--output streamed_proto`, prints a + stream of [`Repository`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) + protocol buffers but in [NDJSON](https://github.com/ndjson/ndjson-spec) format. + + ### Other options + +Other options include: + +* `--base_module ` *default: ``*: Specify a module relative to + which apparent repo names in arguments are interpreted. Note that this + argument itself can be in the form of `@`; this is always + interpreted relative to the root module. + +* `--extension_usages [,[,...]]`: Filters `show_extension` to only + display extension usages from the specified modules. + +## Examples {:#examples} + +Some possible usages of the `mod` command on a real Bazel project are showcased +below to give you a general idea on how you can use it to inspect your project's +external dependencies. + +`MODULE.bazel` file: + +```python +module( + name = "my_project", + version = "1.0", +) + +bazel_dep(name = "bazel_skylib", version = "1.1.1", repo_name = "skylib1") +bazel_dep(name = "bazel_skylib", version = "1.2.0", repo_name = "skylib2") +multiple_version_override(module_name = "bazel_skylib", versions = ["1.1.1", "1.2.0"]) + +bazel_dep(name = "stardoc", version = "0.5.0") +bazel_dep(name = "rules_java", version = "5.0.0") + +toolchains = use_extension("@rules_java//java:extensions.bzl", "toolchains") +use_repo(toolchains, my_jdk="remotejdk17_linux") +``` + + + + + + +
+
+ Graph Before Resolution +
Graph Before Resolution
+
+ + 		+
+ Graph After Resolution +
Graph After Resolution
+
+ +
+ +1. Display the whole dependency graph of your + project. + + ```sh + bazel mod graph + ``` + + ```none + (my_project@1.0) + ├───bazel_skylib@1.1.1 + │ └───platforms@0.0.4 + ├───bazel_skylib@1.2.0 + │ └───platforms@0.0.4 ... + ├───rules_java@5.0.0 + │ ├───platforms@0.0.4 ... + │ ├───rules_cc@0.0.1 + │ │ ├───bazel_skylib@1.1.1 ... + │ │ └───platforms@0.0.4 ... + │ └───rules_proto@4.0.0 + │ ├───bazel_skylib@1.1.1 ... + │ └───rules_cc@0.0.1 ... + └───stardoc@0.5.0 + ├───bazel_skylib@1.1.1 ... + └───rules_java@5.0.0 ... + ``` + + Note: The `...` symbol indicates that the node has already been expanded + somewhere else and was not expanded again to reduce noise. + +2. Display the whole dependency graph (including + unused modules and with extra information about version resolution). + + ```sh + bazel mod graph --include_unused --verbose + ``` + + ```none + (my_project@1.0) + ├───bazel_skylib@1.1.1 + │ └───platforms@0.0.4 + ├───bazel_skylib@1.2.0 + │ └───platforms@0.0.4 ... + ├───rules_java@5.0.0 + │ ├───platforms@0.0.4 ... + │ ├───rules_cc@0.0.1 + │ │ ├───bazel_skylib@1.0.3 ... (to 1.1.1, cause multiple_version_override) + │ │ ├───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override) + │ │ └───platforms@0.0.4 ... + │ └───rules_proto@4.0.0 + │ ├───bazel_skylib@1.0.3 ... (to 1.1.1, cause multiple_version_override) + │ ├───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override) + │ └───rules_cc@0.0.1 ... + └───stardoc@0.5.0 + ├───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override) + ├───rules_java@5.0.0 ... (was 4.0.0, cause , bazel_tools@_) + ├───bazel_skylib@1.0.3 (to 1.1.1, cause multiple_version_override) + │ └───platforms@0.0.4 ... + └───rules_java@4.0.0 (to 5.0.0, cause , bazel_tools@_) + ├───bazel_skylib@1.0.3 ... (to 1.1.1, cause multiple_version_override) + └───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override) + ``` + +3. Display the dependency graph expanded from + some specific modules. + + ```sh + bazel mod graph --from rules_java --include_unused + ``` + + ```none + (my_project@1.0) + ├───rules_java@5.0.0 + │ ├───platforms@0.0.4 + │ ├───rules_cc@0.0.1 + │ │ ├───bazel_skylib@1.0.3 ... (unused) + │ │ ├───bazel_skylib@1.1.1 ... + │ │ └───platforms@0.0.4 ... + │ └───rules_proto@4.0.0 + │ ├───bazel_skylib@1.0.3 ... (unused) + │ ├───bazel_skylib@1.1.1 ... + │ └───rules_cc@0.0.1 ... + └╌╌rules_java@4.0.0 (unused) + ├───bazel_skylib@1.0.3 (unused) + │ └───platforms@0.0.4 ... + └───bazel_skylib@1.1.1 + └───platforms@0.0.4 ... + ``` + + Note: The dotted line is used to indicate an *indirect* (transitive) + dependency edge between two nodes. + +4. Display all paths between two of your + modules. + + ```sh + bazel mod all_paths bazel_skylib@1.1.1 --from rules_proto + ``` + + ```none + (my_project@1.0) + └╌╌rules_proto@4.0.0 + ├───bazel_skylib@1.1.1 + └───rules_cc@0.0.1 + └───bazel_skylib@1.1.1 ... + ``` + +5. See why and how your project depends on some + module(s). + + ```sh + bazel mod explain @skylib1 --verbose --include_unused + ``` + + ```none + (my_project@1.0) + ├───bazel_skylib@1.1.1 + ├───rules_java@5.0.0 + │ ├───rules_cc@0.0.1 + │ │ └───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override) + │ └───rules_proto@4.0.0 + │ ├───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override) + │ └───rules_cc@0.0.1 ... + └───stardoc@0.5.0 + ├───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override) + ├╌╌rules_cc@0.0.1 + │ └───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override) + └╌╌rules_proto@4.0.0 + ├───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override) + └───rules_cc@0.0.1 ... + ``` + +6. See the underlying rule of some your modules' + repos. + + ```sh + bazel mod show_repo rules_cc stardoc + ``` + + `bazel mod show_repo` also works with repos imported by `use_repo` and repos + created with `use_repo_rule`. If `show_repo` is invoked with an apparent + repository name or `--all_visible_repos`, then the apparent repository name + is shown on a line prefixed with `##`. + + ```sh + bazel mod show_repo @jq_linux_arm64 + bazel mod show_repo --all_visible_repos + ``` + + ```none + ## rules_cc@0.0.1: + # + http_archive( + name = "rules_cc+", + urls = ["https://bcr.bazel.build/test-mirror/github.com/bazelbuild/rules_cc/releases/download/0.0.1/rules_cc-0.0.1.tar.gz", "https://github.com/bazelbuild/rules_cc/releases/download/0.0.1/rules_cc-0.0.1.tar.gz"], + integrity = "sha256-Tcy/0iwN7xZMj0dFi9UODHFI89kgAs20WcKpamhJgkE=", + strip_prefix = "", + remote_patches = {"https://bcr.bazel.build/modules/rules_cc/0.0.1/patches/add_module_extension.patch": "sha256-g3+zmGs0YT2HKOVevZpN0Jet89Ylw90Cp9XsIAY8QqU="}, + remote_patch_strip = 1, + ) + # Rule http_archive defined at (most recent call last): + # /home/user/.cache/bazel/_bazel_user/6e893e0f5a92cc4cf5909a6e4b2770f9/external/bazel_tools/tools/build_defs/repo/http.bzl:355:31 in + + ## stardoc: + # + http_archive( + name = "stardoc+", + urls = ["https://bcr.bazel.build/test-mirror/github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz", "https://github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz"], + integrity = "sha256-yXlNzIAmow/2fPfPkeviRcopSyCwcYRdEsGSr+JDrXI=", + strip_prefix = "", + remote_patches = {}, + remote_patch_strip = 0, + ) + # Rule http_archive defined at (most recent call last): + # /home/user/.cache/bazel/_bazel_user/6e893e0f5a92cc4cf5909a6e4b2770f9/external/bazel_tools/tools/build_defs/repo/http.bzl:355:31 in + ``` + + ```none + ## @jq_linux_arm64: + load("@@bazel_tools//tools/build_defs/repo:http.bzl", "http_file") + http_file( + name = "+http_file+jq_linux_arm64", + executable = True, + integrity = "sha256-TdLYoGYd8LIvG7mh+YMPBrbzuPfZEhGh7118TwaotKU=", + urls = ["https://github.com/jqlang/jq/releases/download/jq-1.7.1/jq-linux-arm64"], + ) + ``` + + ```sh + bazel mod graph --extension_info=usages + ``` + + ```none + (my_project@1.0) + ├───$@@rules_java.5.0.0//java:extensions.bzl%toolchains + ├───rules_java@5.0.0 # + │ ├───$@@rules_java.5.0.0//java:extensions.bzl%toolchains + │ ├───rules_cc@0.0.1 # + │ │ └───$@@rules_cc.0.0.1//bzlmod:extensions.bzl%cc_configure + │ └───rules_proto@4.0.0 + │ └───rules_cc@0.0.1 ... + └───stardoc@0.5.0 + └───rules_java@5.0.0 ... + ``` + +8. See what repositories are generated and + imported from some specific extension as part of the dependency graph. + + ```sh + bazel mod show_extension @@rules_java+5.0.0//java:extensions.bzl%toolchains + ``` + + ```none + (my_project@1.0) + ├───$@@rules_java.5.0.0//java:extensions.bzl%toolchains + │ ├───remotejdk17_linux + │ ├╌╌remotejdk11_linux + │ ├╌╌remotejdk11_linux_aarch64 + │ ├╌╌remotejdk11_linux_ppc64le + │ ├╌╌remotejdk11_linux_s390x + ...(some lines omitted)... + ├───rules_java@5.0.0 # + │ └───$@@rules_java.5.0.0//java:extensions.bzl%toolchains ... + │ ├───local_jdk + │ ├───remote_java_tools + │ ├───remote_java_tools_darwin + │ ├───remote_java_tools_linux + │ ├───remote_java_tools_windows + │ ├───remotejdk11_linux_aarch64_toolchain_config_repo + │ ├───remotejdk11_linux_ppc64le_toolchain_config_repo + ...(some lines omitted)... + └───stardoc@0.5.0 + └───rules_java@5.0.0 ... + ``` + +9. See the list of generated repositories of an + extension and how that extension is used in each module. + + ```sh + bazel mod graph --extension_info=all --extension_filter=@rules_java//java:extensions.bzl%toolchains + ``` + + ```none + ## @@rules_java.5.0.0//java:extensions.bzl%toolchains: + + Fetched repositories: + - local_jdk (imported by bazel_tools@_, rules_java@5.0.0) + - remote_java_tools (imported by bazel_tools@_, rules_java@5.0.0) + - remote_java_tools_darwin (imported by bazel_tools@_, rules_java@5.0.0) + - remote_java_tools_linux (imported by bazel_tools@_, rules_java@5.0.0) + - remote_java_tools_windows (imported by bazel_tools@_, rules_java@5.0.0) + - remotejdk11_linux_aarch64_toolchain_config_repo (imported by rules_java@5.0.0) + - remotejdk11_linux_ppc64le_toolchain_config_repo (imported by rules_java@5.0.0) + ...(some lines omitted)... + - remotejdk17_linux (imported by ) + - remotejdk11_linux + - remotejdk11_linux_aarch64 + - remotejdk11_linux_ppc64le + - remotejdk11_linux_s390x + - remotejdk11_macos + ...(some lines omitted)... + + # Usage in at /MODULE.bazel:14:27 with the specified attributes: + use_repo( + toolchains, + my_jdk="remotejdk17_linux", + ) + + # Usage in bazel_tools@_ at bazel_tools@_/MODULE.bazel:23:32 with the specified attributes: + use_repo( + toolchains, + "local_jdk", + "remote_java_tools", + "remote_java_tools_linux", + "remote_java_tools_windows", + "remote_java_tools_darwin", + ) + + # Usage in rules_java@5.0.0 at rules_java@5.0.0/MODULE.bazel:30:27 with the specified attributes: + use_repo( + toolchains, + "remote_java_tools", + "remote_java_tools_linux", + "remote_java_tools_windows", + "remote_java_tools_darwin", + "local_jdk", + "remotejdk11_linux_toolchain_config_repo", + "remotejdk11_macos_toolchain_config_repo", + "remotejdk11_macos_aarch64_toolchain_config_repo", + ...(some lines omitted)... + ) + ``` + +10. See the underlying rule of some + extension-generated repositories. + + ```sh + bazel mod show_repo --base_module=rules_java @remote_java_tools + ``` + + ```none + ## @remote_java_tools: + # + http_archive( + name = "rules_java++toolchains+remote_java_tools", + urls = ["https://mirror.bazel.build/bazel_java_tools/releases/java/v11.5/java_tools-v11.5.zip", "https://github.com/bazelbuild/java_tools/releases/download/java_v11.5/java_tools-v11.5.zip"], + sha256 = "b763ee80e5754e593fd6d5be6d7343f905bc8b73d661d36d842b024ca11b6793", + ) + # Rule http_archive defined at (most recent call last): + # /home/user/.cache/bazel/_bazel_user/6e893e0f5a92cc4cf5909a6e4b2770f9/external/bazel_tools/tools/build_defs/repo/http.bzl:355:31 in + ``` \ No newline at end of file diff --git a/external/registry.mdx b/external/registry.mdx new file mode 100644 index 000000000..2e9e26b76 --- /dev/null +++ b/external/registry.mdx @@ -0,0 +1,172 @@ +--- +title: 'Bazel registries' +--- + +Bazel discovers dependencies by requesting their information from Bazel +*registries*: databases of Bazel modules. Bazel only supports one type of +registries — [*index registries*](#index_registry) — local directories or static +HTTP servers following a specific format. + +## Index registry + +An index registry is a local directory or a static HTTP server containing +information about a list of modules — including their homepage, maintainers, the +`MODULE.bazel` file of each version, and how to fetch the source of each +version. Notably, it does *not* need to serve the source archives itself. + +An index registry must have the following format: + +* [`/bazel_registry.json`](#bazel-registry-json): An optional JSON file + containing metadata for the registry. +* `/modules`: A directory containing a subdirectory for each module in this + registry +* `/modules/$MODULE`: A directory containing a subdirectory for each version + of the module named `$MODULE`, as well as the [`metadata.json` + file](#metadata-json) containing metadata for this module. +* `/modules/$MODULE/$VERSION`: A directory containing the following files: + * `MODULE.bazel`: The `MODULE.bazel` file of this module version. Note + that this is the `MODULE.bazel` file read during Bazel's external + dependency resolution, _not_ the one from the source archive (unless + there's a [non-registry + override](/external/module#non-registry_overrides)). Also note that it's + best to use this file to set the version of a release and avoid doing so + in the source archive `MODULE.bazel` file. To learn more about module + versioning, [see the FAQ](faq.md#module-versioning-best-practices). + * [`source.json`](#source-json): A JSON file containing information on how + to fetch the source of this module version + * `patches/`: An optional directory containing patch files, only used when + `source.json` has "archive" type + * `overlay/`: An optional directory containing overlay files, only used + when `source.json` has "archive" type + +### `bazel_registry.json` {:#bazel-registry-json} + +`bazel_registry.json` is an optional file that specifies metadata applying to +the entire registry. It can contain the following fields: + +* `mirrors`: an array of strings, specifying the list of mirrors to use for + source archives. + * The mirrored URL is a concatenation of the mirror itself, and the + source URL of the module specified by its `source.json` file sans the + protocol. For example, if a module's source URL is + `https://foo.com/bar/baz`, and `mirrors` contains + `["https://mirror1.com/", "https://example.com/mirror2/"]`, then the + URLs Bazel will try in order are `https://mirror1.com/foo.com/bar/baz`, + `https://example.com/mirror2/foo.com/bar/baz`, and finally the original + source URL itself `https://foo.com/bar/baz`. +* `module_base_path`: a string, specifying the base path for modules with + `local_path` type in the `source.json` file + +### `metadata.json` {:#metadata-json} + +`metadata.json` is an optional JSON file containing information about the +module, with the following fields: + +* `versions`: An array of strings, each denoting a version of the module + available in this registry. This array should match the children of the + module directory. +* `yanked_versions`: A JSON object specifying the [*yanked* + versions](/external/module#yanked_versions) of this module. The keys + should be versions to yank, and the values should be descriptions of + why the version is yanked, ideally containing a link to more + information. + +Note that the BCR requires more information in the `metadata.json` file. + +### `source.json` {:#source-json} + +`source.json` is a required JSON file containing information about how to fetch +a specific version of a module. The schema of this file depends on its `type` +field, which defaults to `archive`. + +* If `type` is `archive` (the default), this module version is backed by an + [`http_archive`](/rules/lib/repo/http#http_archive) repo rule; it's fetched + by downloading an archive from a given URL and extracting its contents. It + supports the following fields: + * `url`: A string, the URL of the source archive + * `mirror_urls`: A list of string, the mirror URLs of the source archive. + The URLs are tried in order after `url` as backups. + * `integrity`: A string, the [Subresource + Integrity][subresource-integrity] checksum of the archive + * `strip_prefix`: A string, the directory prefix to strip when extracting + the source archive + * `overlay`: A JSON object containing overlay files to layer on top of the + extracted archive. The patch files are located under the + `/modules/$MODULE/$VERSION/overlay` directory. The keys are the + overlay file names, and the values are the integrity checksum of + the overlay files. The overlays are applied before the patch files. + * `patches`: A JSON object containing patch files to apply to the + extracted archive. The patch files are located under the + `/modules/$MODULE/$VERSION/patches` directory. The keys are the + patch file names, and the values are the integrity checksum of + the patch files. The patches are applied after the overlay files and in + the order they appear in `patches`. + * `patch_strip`: A number; the same as the `--strip` argument of Unix + `patch`. + * `archive_type`: A string, the archive type of the downloaded file (Same + as [`type` on `http_archive`](/rules/lib/repo/http#http_archive-type)). +* If `type` is `git_repository`, this module version is backed by a + [`git_repository`](/rules/lib/repo/git#git_repository) repo rule; it's + fetched by cloning a Git repository. + * The following fields are supported, and are directly forwarded to the + underlying `git_repository` repo rule: `remote`, `commit`, + `shallow_since`, `tag`, `init_submodules`, `verbose`, and + `strip_prefix`, `patch_strip`. + * `patches`: A JSON object containing patch files to apply to the + cloned repository. The patch files are located under the + `/modules/$MODULE/$VERSION/patches` directory. The keys are the + patch file names, and the values are the integrity checksum of + the patch files. The patches are applied in the order they appear in + `patches`. +* If `type` is `local_path`, this module version is backed by a + [`local_repository`](/rules/lib/repo/local#local_repository) repo rule; + it's symlinked to a directory on local disk. It supports the following + field: + * `path`: The local path to the repo, calculated as following: + * If `path` is an absolute path, it stays as it is + * If `path` is a relative path and `module_base_path` is an + absolute path, it resolves to `/` + * If `path` and `module_base_path` are both relative paths, it + resolves to `//`. + Registry must be hosted locally and used by + `--registry=file://`. Otherwise, Bazel will + throw an error + +## Bazel Central Registry {:#bazel-central-registry} + +The Bazel Central Registry (BCR) at is an index +registry with contents backed by the GitHub repo +[`bazelbuild/bazel-central-registry`][bcr-repo]. You can browse its contents +using the web frontend at . + +The Bazel community maintains the BCR, and contributors are welcome to submit +pull requests. See the [BCR contribution +guidelines][bcr-contribution-guidelines]. + +In addition to following the format of a normal index registry, the BCR requires +a `presubmit.yml` file for each module version +(`/modules/$MODULE/$VERSION/presubmit.yml`). This file specifies a few essential +build and test targets that you can use to check the validity of this module +version. The BCR's CI pipelines also uses this to ensure interoperability +between modules. + +## Selecting registries + +The repeatable Bazel flag `--registry` can be used to specify the list of +registries to request modules from, so you can set up your project to fetch +dependencies from a third-party or internal registry. Earlier registries take +precedence. For convenience, you can put a list of `--registry` flags in the +`.bazelrc` file of your project. + +If your registry is hosted on GitHub (for example, as a fork of +`bazelbuild/bazel-central-registry`) then your `--registry` value needs a raw +GitHub address under `raw.githubusercontent.com`. For example, on the `main` +branch of the `my-org` fork, you would set +`--registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/`. + +Using the `--registry` flag stops the Bazel Central Registry from being used by +default, but you can add it back by adding `--registry=https://bcr.bazel.build`. + +[bcr-contribution-guidelines]: https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/README.md +[bcr-repo]: https://github.com/bazelbuild/bazel-central-registry +[subresource-integrity]: https://w3c.github.io/webappsec-subresource-integrity/#integrity-metadata-description diff --git a/help.mdx b/help.mdx index 1878c6c72..9956d9287 100644 --- a/help.mdx +++ b/help.mdx @@ -24,13 +24,13 @@ There are recordings of Bazel talks at various conferences, such as: * Bazel’s annual conference, BazelCon: * [BazelCon 2025](https://www.youtube.com/playlist?list=PLak8-7eFSpowmNiR2lhvJEomLA140yban) * [BazelCon 2024](https://www.youtube.com/playlist?list=PLbzoR-pLrL6ptKfAQNZ5RS4HMdmeilBcw) - * [BazelCon 2023](https://www.youtube.com/playlist?list=PLbzoR-pLrL6rUiqylH-kumoZCWntG1vjp) - * [BazelCon 2022](https://www.youtube.com/playlist?list=PLbzoR-pLrL6rABfcAJO1VWeOUYL1kIn-p) - * [BazelCon 2021](https://www.youtube.com/playlist?list=PLbzoR-pLrL6pO6BaaQ1Ndos53gfRVLEoU) - * [BazelCon 2020](https://www.youtube.com/playlist?list=PLbzoR-pLrL6qZ5JRMtn20_s2uPz9vFYgU) - * [BazelCon 2019](https://www.youtube.com/playlist?list=PLbzoR-pLrL6ogKgytQXqUxJQ6nZlIWoTH) - * [BazelCon 2018](https://www.youtube.com/playlist?list=PLbzoR-pLrL6rBDwC0NMRPS8EJ0VRAW0QR) - * [BazelCon 2017](https://www.youtube.com/playlist?list=PLbzoR-pLrL6qvwchdtlSopLgUrz4J4zKP) + * [BazelCon 2023](https://www.youtube.com/playlist?list=PLxNYxgaZ8Rsefrwb_ySGRi_bvQejpO_Tj) + * [BazelCon 2022](https://youtube.com/playlist?list=PLxNYxgaZ8RsdH4GCIZ69dzxQCOPyuNlpF) + * [BazelCon 2021](https://www.youtube.com/playlist?list=PLxNYxgaZ8Rsc3auKhtfIB4qXAYf7whEux) + * [BazelCon 2020](https://www.youtube.com/playlist?list=PLxNYxgaZ8RseRybXNbopHRv6-wGmFr04n) + * [BazelCon 2019](https://youtu.be/eymphDN7No4?t=PLxNYxgaZ8Rsf-7g43Z8LyXct9ax6egdSj) + * [BazelCon 2018](https://youtu.be/DVYRg6b2UBo?t=PLxNYxgaZ8Rsd3Nmvl1W1B4I6nK1674ezp) + * [BazelCon 2017](https://youtu.be/3eFllvz8_0k?t=PLxNYxgaZ8RseY0KmkXQSt0StE71E7yizG) * Bazel day on [Google Open Source Live](https://opensourcelive.withgoogle.com/events/bazel) diff --git a/install/compile-source.mdx b/install/compile-source.mdx index 9f5905a47..7a05ce47c 100644 --- a/install/compile-source.mdx +++ b/install/compile-source.mdx @@ -34,7 +34,7 @@ To build Bazel from source, you can do one of the following: `bazel build //src:bazel-dev` (or `bazel build //src:bazel-dev.exe` on Windows). - **Note:** Many rulesets rely on the Bazel version for feature detection. + **Note:** Many rulesets rely on the Bazel version for feature detection. For this to work correctly, the version must be embedded in the binary. Build `bazel-dev` with: diff --git a/install/ide.mdx b/install/ide.mdx index aa6210b3a..abe1f8955 100644 --- a/install/ide.mdx +++ b/install/ide.mdx @@ -20,10 +20,14 @@ a discussion on [GitHub](https://github.com/bazelbuild/bazel/discussions). ### IntelliJ, Android Studio, and CLion -[Official plugin](http://ij.bazel.build) for IntelliJ, Android Studio, and -CLion. The plugin is [open source](https://github.com/bazelbuild/intellij). +Official Bazel plugins exist for many of the JetBrains-associated IDEs. +Full documentation is linked from the listings on the JetBrains Marketplace: -This is the open source version of the plugin used internally at Google. +* [IntelliJ + plugin](https://plugins.jetbrains.com/plugin/22977-bazel) +* [Android Studio + plugin](https://plugins.jetbrains.com/plugin/9185-android-studio-with-bazel) +* [CLion plugin](https://plugins.jetbrains.com/plugin/9554-clion-with-bazel) Features: @@ -37,14 +41,9 @@ Features: To install, go to the IDE's plugin browser and search for `Bazel`. -To manually install older versions, download the zip files from JetBrains' -Plugin Repository and install the zip file from the IDE's plugin browser: - -* [Android Studio - plugin](https://plugins.jetbrains.com/plugin/9185-android-studio-with-bazel) -* [IntelliJ - plugin](https://plugins.jetbrains.com/plugin/8609-intellij-with-bazel) -* [CLion plugin](https://plugins.jetbrains.com/plugin/9554-clion-with-bazel) +To manually install older versions, download the zip files from the JetBrains +Marketplace or from [GitHub Releases](https://github.com/bazelbuild/intellij/releases) +and install the zip file from the IDE's plugin browser. ### Xcode diff --git a/install/index.mdx b/install/index.mdx index 29b469728..84d9b1468 100644 --- a/install/index.mdx +++ b/install/index.mdx @@ -22,6 +22,7 @@ officially support them. Contact the package maintainers for support. * [Fedora](https://copr.fedorainfracloud.org/coprs/lihaohong/bazel) * [FreeBSD](https://www.freshports.org/devel/bazel) * [Homebrew](https://formulae.brew.sh/formula/bazel) +* [mise](install/mise) * [Nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/tools/build-managers/bazel) * [openSUSE](/install/suse) * [Scoop](https://github.com/scoopinstaller/scoop-main/blob/master/bucket/bazel.json) diff --git a/install/mise.mdx b/install/mise.mdx new file mode 100644 index 000000000..24aa517c6 --- /dev/null +++ b/install/mise.mdx @@ -0,0 +1,10 @@ +--- +title: 'Installing Bazel with mise' +--- + + +This page describes how to install Bazel using [mise](https://github.com/jdx/mise) the polyglot tools version manager. + +```shell +mise use -g bazel@latest +``` diff --git a/migrate/index.mdx b/migrate/index.mdx index 2a5740671..601d61031 100644 --- a/migrate/index.mdx +++ b/migrate/index.mdx @@ -2,8 +2,6 @@ title: 'Migrating to Bazel' --- - - This page links to migration guides for Bazel. * [Maven](/migrate/maven) diff --git a/migrate/maven.mdx b/migrate/maven.mdx index 38aaffc00..960867fde 100644 --- a/migrate/maven.mdx +++ b/migrate/maven.mdx @@ -2,8 +2,6 @@ title: 'Migrating from Maven to Bazel' --- - - This page describes how to migrate from Maven to Bazel, including the prerequisites and installation steps. It describes the differences between Maven and Bazel, and provides a migration example using the Guava project. @@ -14,18 +12,18 @@ system, and any other relevant systems. You can run Maven and Bazel in the same repository. Note: While Bazel supports downloading and publishing Maven artifacts with -[rules_jvm_external](https://github.com/bazelbuild/rules_jvm_external) +[rules_jvm_external](https://github.com/bazelbuild/rules_jvm_external){: .external} , it does not directly support Maven-based plugins. Maven plugins can't be directly run by Bazel since there's no Maven compatibility layer. -## Before you begin +## Before you begin {:#before-you-begin} * [Install Bazel](/install) if it's not yet installed. * If you're new to Bazel, go through the tutorial [Introduction to Bazel: Build Java](/start/java) before you start migrating. The tutorial explains Bazel's concepts, structure, and label syntax. -## Differences between Maven and Bazel +## Differences between Maven and Bazel {:#dif-maven-bazel} * Maven uses top-level `pom.xml` file(s). Bazel supports multiple build files and multiple targets per `BUILD` file, allowing for builds that are more @@ -37,7 +35,7 @@ directly run by Bazel since there's no Maven compatibility layer. `BUILD` files. Best practice is to add a `BUILD` file to each new Java package. -## Migrate from Maven to Bazel +## Migrate from Maven to Bazel {:#migrate-maven-bazel} The steps below describe how to migrate your project to Bazel: @@ -47,7 +45,7 @@ The steps below describe how to migrate your project to Bazel: 4. [Build using Bazel](#4-build) Examples below come from a migration of the [Guava -project](https://github.com/google/guava) from Maven to Bazel. The +project](https://github.com/google/guava){: .external} from Maven to Bazel. The Guava project used is release `v31.1`. The examples using Guava do not walk through each step in the migration, but they do show the files and contents that are generated or added manually for the migration. @@ -57,7 +55,7 @@ $ git clone https://github.com/google/guava.git && cd guava $ git checkout v31.1 ``` -### 1. Create the MODULE.bazel file +### 1. Create the MODULE.bazel file {:#1-build} Create a file named `MODULE.bazel` at the root of your project. If your project has no external dependencies, this file can be empty. @@ -66,14 +64,14 @@ If your project depends on files or packages that are not in one of the project's directories, specify these external dependencies in the MODULE.bazel file. You can use `rules_jvm_external` to manage dependencies from Maven. For instructions about using this ruleset, see [the -README](https://github.com/bazelbuild/rules_jvm_external/#rules_jvm_external) +README](https://github.com/bazelbuild/rules_jvm_external/#rules_jvm_external){: .external} . -#### Guava project example: external dependencies +#### Guava project example: external dependencies {:#guava-1} You can list the external dependencies of the [Guava -project](https://github.com/google/guava) with the -[`rules_jvm_external`](https://github.com/bazelbuild/rules_jvm_external) +project](https://github.com/google/guava){: .external} with the +[`rules_jvm_external`](https://github.com/bazelbuild/rules_jvm_external){: .external} ruleset. Add the following snippet to the `MODULE.bazel` file: @@ -96,7 +94,7 @@ maven.install( use_repo(maven, "maven") ``` -### 2. Create one BUILD file +### 2. Create one BUILD file {:#2-build} Now that you have your workspace defined and external dependencies (if applicable) listed, you need to create `BUILD` files to describe how your @@ -176,7 +174,7 @@ your build by adding more `BUILD` files with more granular targets. The project has now been successfully built with Bazel. You will need to add more `BUILD` files to allow incremental builds of the project. -#### Guava project example: start with one BUILD file +#### Guava project example: start with one BUILD file {:#guava-2} When migrating the Guava project to Bazel, initially one `BUILD` file is used to build the entire project. Here are the contents of this initial `BUILD` file in @@ -200,7 +198,7 @@ java_library( ) ``` -### 3. Create more BUILD files (optional) +### 3. Create more BUILD files (optional) {:#3-build} Bazel does work with just one `BUILD file`, as you saw after completing your first build. You should still consider breaking the build into smaller chunks by @@ -232,10 +230,10 @@ Tips for adding more `BUILD` files: that the project continues to build with Bazel as you add each build file. Run `bazel build //...` to ensure all of your targets still build. -### 4. Build using Bazel +### 4. Build using Bazel {:#4-build} You've been building using Bazel as you add `BUILD` files to validate the setup of the build. When you have `BUILD` files at the desired granularity, you can use Bazel to -produce all of your builds. +produce all of your builds. \ No newline at end of file diff --git a/migrate/xcode.mdx b/migrate/xcode.mdx index 986cd1158..a01a2c9f5 100644 --- a/migrate/xcode.mdx +++ b/migrate/xcode.mdx @@ -2,14 +2,12 @@ title: 'Migrating from Xcode to Bazel' --- - - This page describes how to build or test an Xcode project with Bazel. It describes the differences between Xcode and Bazel, and provides the steps for converting an Xcode project to a Bazel project. It also provides troubleshooting solutions to address common errors. -## Differences between Xcode and Bazel +## Differences between Xcode and Bazel {:#dif-xcode-bazel} * Bazel requires you to explicitly specify every build target and its dependencies, plus the corresponding build settings via build rules. @@ -21,14 +19,14 @@ solutions to address common errors. * When building Xcode projects with Bazel, the `BUILD` file(s) become the source of truth. If you work on the project in Xcode, you must generate a new version of the Xcode project that matches the `BUILD` files using - [rules_xcodeproj](https://github.com/buildbuddy-io/rules_xcodeproj/) + [rules_xcodeproj](https://github.com/buildbuddy-io/rules_xcodeproj/){: .external} whenever you update the `BUILD` files. Certain changes to the `BUILD` files such as adding dependencies to a target don't require regenerating the project which can speed up development. If you're not using Xcode, the `bazel build` and `bazel test` commands provide build and test capabilities with certain limitations described later in this guide. -## Before you begin +## Before you begin {:#before-you-begin} Before you begin, do the following: @@ -41,7 +39,7 @@ Before you begin, do the following: 3. Analyze and understand the project's dependencies. -### Analyze project dependencies +### Analyze project dependencies {:#analyze-project-dependencies} Unlike Xcode, Bazel requires you to explicitly declare all dependencies for every target in the `BUILD` file. @@ -49,7 +47,7 @@ every target in the `BUILD` file. For more information on external dependencies, see [Working with external dependencies](/docs/external). -## Build or test an Xcode project with Bazel +## Build or test an Xcode project with Bazel {:#build-xcode-project} To build or test an Xcode project with Bazel, do the following: @@ -71,7 +69,7 @@ To build or test an Xcode project with Bazel, do the following: 6. [Generate the Xcode project with rules_xcodeproj](#generate-the-xcode-project-with-rules_xcodeproj) -### Step 1: Create the `MODULE.bazel` file +### Step 1: Create the `MODULE.bazel` file {:#create-workspace} Create a `MODULE.bazel` file in a new directory. This directory becomes the Bazel workspace root. If the project uses no external dependencies, this file @@ -82,19 +80,19 @@ the project's directories, specify these external dependencies in the Note: Place the project source code within the directory tree containing the `MODULE.bazel` file. -### Step 2: (Experimental) Integrate SwiftPM dependencies +### Step 2: (Experimental) Integrate SwiftPM dependencies {:#integrate-swiftpm} To integrate SwiftPM dependencies into the Bazel workspace with -[swift_bazel](https://github.com/cgrindel/swift_bazel), you must +[swift_bazel](https://github.com/cgrindel/swift_bazel){: .external}, you must convert them into Bazel packages as described in the [following -tutorial](https://chuckgrindel.com/swift-packages-in-bazel-using-swift_bazel/) +tutorial](https://chuckgrindel.com/swift-packages-in-bazel-using-swift_bazel/){: .external} . Note: SwiftPM support is a manual process with many variables. SwiftPM integration with Bazel has not been fully verified and is not officially supported. -### Step 3: Create a `BUILD` file +### Step 3: Create a `BUILD` file {:#create-build-file} Once you have defined the workspace and external dependencies, you need to create a `BUILD` file that tells Bazel how the project is structured. Create the @@ -108,12 +106,12 @@ initial build of the project as follows: **Tip:** To learn more about packages and other Bazel concepts, see [Workspaces, packages, and targets](/concepts/build-ref). -#### Step 3a: Add the application target +#### Step 3a: Add the application target {:#add-app-target} Add a -[`macos_application`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-macos.md#macos_application) +[`macos_application`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-macos.md#macos_application){: .external} or an -[`ios_application`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_application) +[`ios_application`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_application){: .external} rule target. This target builds a macOS or iOS application bundle, respectively. In the target, specify the following at the minimum: @@ -132,26 +130,26 @@ In the target, specify the following at the minimum: application supports. This ensures Bazel builds the application with the correct API levels. -#### Step 3b: (Optional) Add the test target(s) +#### Step 3b: (Optional) Add the test target(s) {:#add-test-target} Bazel's [Apple build -rules](https://github.com/bazelbuild/rules_apple) support running +rules](https://github.com/bazelbuild/rules_apple){: .external} support running unit and UI tests on all Apple platforms. Add test targets as follows: -* [`macos_unit_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-macos.md#macos_unit_test) +* [`macos_unit_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-macos.md#macos_unit_test){: .external} to run library-based and application-based unit tests on a macOS. -* [`ios_unit_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_unit_test) +* [`ios_unit_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_unit_test){: .external} to build and run library-based unit tests on iOS. -* [`ios_ui_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_ui_test) +* [`ios_ui_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_ui_test){: .external} to build and run user interface tests in the iOS simulator. * Similar test rules exist for - [tvOS](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-tvos.md), - [watchOS](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-watchos.md) + [tvOS](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-tvos.md){: .external}, + [watchOS](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-watchos.md){: .external} and - [visionOS](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-visionos.md). + [visionOS](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-visionos.md){: .external}. At the minimum, specify a value for the `minimum_os_version` attribute. While other packaging attributes, such as `bundle_identifier` and `infoplists`, @@ -160,11 +158,11 @@ with the project and adjust them as necessary. For tests that require the iOS simulator, also specify the `ios_application` target name as the value of the `test_host` attribute. -#### Step 3c: Add the library target(s) +#### Step 3c: Add the library target(s) {:#add-library-target} Add an [`objc_library`](/reference/be/objective-c#objc_library) target for each Objective-C library and a -[`swift_library`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_library) +[`swift_library`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_library){: .external} target for each Swift library on which the application and/or tests depend. Add the library targets as follows: @@ -187,20 +185,20 @@ the [rules_apple examples directory](https://github.com/bazelbuild/rules_apple/tree/master/examples/). For example: -* [macOS application targets](https://github.com/bazelbuild/rules_apple/tree/master/examples/macos) +* [macOS application targets](https://github.com/bazelbuild/rules_apple/tree/master/examples/macos){: .external} -* [iOS applications targets](https://github.com/bazelbuild/rules_apple/tree/master/examples/ios) +* [iOS applications targets](https://github.com/bazelbuild/rules_apple/tree/master/examples/ios){: .external} -* [Multi platform applications (macOS, iOS, watchOS, tvOS)](https://github.com/bazelbuild/rules_apple/tree/master/examples/multi_platform) +* [Multi platform applications (macOS, iOS, watchOS, tvOS)](https://github.com/bazelbuild/rules_apple/tree/master/examples/multi_platform){: .external} For more information on build rules, see [Apple Rules for -Bazel](https://github.com/bazelbuild/rules_apple). +Bazel](https://github.com/bazelbuild/rules_apple){: .external}. At this point, it is a good idea to test the build: `bazel build //:` -### Step 4: (Optional) Granularize the build +### Step 4: (Optional) Granularize the build {:#granularize-build} If the project is large, or as it grows, consider chunking it into multiple Bazel packages. This increased granularity provides: @@ -234,7 +232,7 @@ Tips for granularizing the project: * Build the project after each major change to the `BUILD` files and fix build errors as you encounter them. -### Step 5: Run the build +### Step 5: Run the build {:#run-build} Run the fully migrated build to ensure it completes with no errors or warnings. Run every application and test target individually to more easily find sources @@ -246,15 +244,15 @@ For example: bazel build //:my-target ``` -### Step 6: Generate the Xcode project with rules_xcodeproj +### Step 6: Generate the Xcode project with rules_xcodeproj {:#generate-the-xcode-project-with-rules_xcodeproj} When building with Bazel, the `MODULE.bazel` and `BUILD` files become the source of truth about the build. To make Xcode aware of this, you must generate a Bazel-compatible Xcode project using -[rules_xcodeproj](https://github.com/buildbuddy-io/rules_xcodeproj#features) +[rules_xcodeproj](https://github.com/buildbuddy-io/rules_xcodeproj#features){: .external} . -### Troubleshooting +### Troubleshooting {:#troubleshooting} Bazel errors can arise when it gets out of sync with the selected Xcode version, like when you apply an update. Here are some things to try if you're @@ -277,4 +275,4 @@ use an Apple CROSSTOOL". * If this does not work, you may also try running `bazel clean --expunge`. Note: If you've saved your Xcode to a different path, you can use `xcode-select --s` to point to that path. +-s` to point to that path. \ No newline at end of file diff --git a/query/cquery.mdx b/query/cquery.mdx index dc46c97dd..d35ea8298 100644 --- a/query/cquery.mdx +++ b/query/cquery.mdx @@ -164,14 +164,9 @@ The `config` operator attempts to find the configured target for the label denoted by the first argument and configuration specified by the second argument. -Valid values for the second argument are: - -* 'target': The 'top-level' configuration for a cquery -* 'anyexec': Identify any 'exec' configuration (always return first exec config, - in alphanumeric sorting of config hash. -* `null` used for source files while have no configuration. -* [custom configuration hash](#configurations). Hashes can be retrieved from - `$ blaze config` or a prevous `cquery`'s output. +Valid values for the second argument are `null` or a +[custom configuration hash](#configurations). Hashes can be retrieved from `$ +bazel config` or a previous `cquery`'s output. Examples: diff --git a/query/language.mdx b/query/language.mdx new file mode 100644 index 000000000..20a8f78a8 --- /dev/null +++ b/query/language.mdx @@ -0,0 +1,1551 @@ +--- +title: 'The Bazel Query Reference' +--- + +This page is the reference manual for the _Bazel Query Language_ used +when you use `bazel query` to analyze build dependencies. It also +describes the output formats `bazel query` supports. + +For practical use cases, see the [Bazel Query How-To](/query/guide). + +## Additional query reference + +In addition to `query`, which runs on the post-loading phase target graph, +Bazel includes *action graph query* and *configurable query*. + +### Action graph query {:#aquery} + +The action graph query (`aquery`) operates on the post-analysis Configured +Target Graph and exposes information about **Actions**, **Artifacts**, and +their relationships. `aquery` is useful when you are interested in the +properties of the Actions/Artifacts generated from the Configured Target Graph. +For example, the actual commands run and their inputs, outputs, and mnemonics. + +For more details, see the [aquery reference](/query/aquery). + +### Configurable query {:#cquery} + +Traditional Bazel query runs on the post-loading phase target graph and +therefore has no concept of configurations and their related concepts. Notably, +it doesn't correctly resolve [select statements](/reference/be/functions#select) +and instead returns all possible resolutions of selects. However, the +configurable query environment, `cquery`, properly handles configurations but +doesn't provide all of the functionality of this original query. + +For more details, see the [cquery reference](/query/cquery). + +## Examples {:#examples} + +How do people use `bazel query`? Here are typical examples: + +Why does the `//foo` tree depend on `//bar/baz`? +Show a path: + +``` +somepath(foo/..., //bar/baz:all) +``` + +What C++ libraries do all the `foo` tests depend on that +the `foo_bin` target does not? + +``` +kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin)) +``` + +## Tokens: The lexical syntax {:#tokens} + +Expressions in the query language are composed of the following +tokens: + +* **Keywords**, such as `let`. Keywords are the reserved words of the + language, and each of them is described below. The complete set + of keywords is: + + * [`except`](#set-operations) + + * [`in`](#variables) + + * [`intersect`](#set-operations) + + * [`let`](#variables) + + * [`set`](#set) + + * [`union`](#set-operations) + +* **Words**, such as "`foo/...`" or "`.*test rule`" or "`//bar/baz:all`". If a + character sequence is "quoted" (begins and ends with a single-quote ' or + begins and ends with a double-quote "), it is a word. If a character sequence + is not quoted, it may still be parsed as a word. Unquoted words are sequences + of characters drawn from the alphabet characters A-Za-z, the numerals 0-9, + and the special characters `*/@.-_:$~[]` (asterisk, forward slash, at, period, + hyphen, underscore, colon, dollar sign, tilde, left square brace, right square + brace). However, unquoted words may not start with a hyphen `-` or asterisk `*` + even though relative [target names](/concepts/labels#target-names) may start + with those characters. As a special rule meant to simplify the handling of + labels referring to external repositories, unquoted words that start with + `@@` may contain `+` characters. + + Unquoted words also may not include the characters plus sign `+` or equals + sign `=`, even though those characters are permitted in target names. When + writing code that generates query expressions, target names should be quoted. + + Quoting _is_ necessary when writing scripts that construct Bazel query + expressions from user-supplied values. + + ``` + //foo:bar+wiz # WRONG: scanned as //foo:bar + wiz. + //foo:bar=wiz # WRONG: scanned as //foo:bar = wiz. + "//foo:bar+wiz" # OK. + "//foo:bar=wiz" # OK. + ``` + + Note that this quoting is in addition to any quoting that may be required by + your shell, such as: + + ```posix-terminal + bazel query ' "//foo:bar=wiz" ' # single-quotes for shell, double-quotes for Bazel. + ``` + + Keywords and operators, when quoted, are treated as ordinary words. For example, `some` is a + keyword but "some" is a word. Both `foo` and "foo" are words. + + However, be careful when using single or double quotes in target names. When + quoting one or more target names, use only one type of quotes (either all + single or all double quotes). + + The following are examples of what the Java query string will be: + + ``` + 'a"'a' # WRONG: Error message: unclosed quotation. + "a'"a" # WRONG: Error message: unclosed quotation. + '"a" + 'a'' # WRONG: Error message: unexpected token 'a' after query expression '"a" + ' + "'a' + "a"" # WRONG: Error message: unexpected token 'a' after query expression ''a' + ' + "a'a" # OK. + 'a"a' # OK. + '"a" + "a"' # OK + "'a' + 'a'" # OK + ``` + + We chose this syntax so that quote marks aren't needed in most cases. The + (unusual) `".*test rule"` example needs quotes: it starts with a period and + contains a space. Quoting `"cc_library"` is unnecessary but harmless. + +* **Punctuation**, such as parens `()`, period `.` and comma `,`. Words + containing punctuation (other than the exceptions listed above) must be quoted. + +Whitespace characters outside of a quoted word are ignored. + +## Bazel query language concepts {:#language-concepts} + +The Bazel query language is a language of expressions. Every +expression evaluates to a **partially-ordered set** of targets, +or equivalently, a **graph** (DAG) of targets. This is the only +datatype. + +Set and graph refer to the same datatype, but emphasize different +aspects of it, for example: + +* **Set:** The partial order of the targets is not interesting. +* **Graph:** The partial order of targets is significant. + +### Cycles in the dependency graph {:#dependency-graph-cycles} + +Build dependency graphs should be acyclic. + +The algorithms used by the query language are robust against cycles, and will +not report cycles as errors. + +Note that the post-loading phase unconfigured target graph that `bazel query` +operates over may contain cycles that do not exist in the configured target +graph. Cycles in the configured target graph are detected and reported as errors +by [`bazel cquery`](/query/cquery) and [`bazel aquery`](/query/aquery). + +### Implicit dependencies {:#implicit-dependencies} + +In addition to build dependencies that are defined explicitly in `BUILD` files, +Bazel adds additional _implicit_ dependencies to rules. Implicit dependencies +may be defined by: + +- [Private attributes](/extending/rules#private_attributes_and_implicit_dependencies) +- [Toolchain requirements](/extending/toolchains#writing-rules-toolchains) + +By default, `bazel query` takes implicit dependencies into account +when computing the query result. This behavior can be changed with +the `--[no]implicit_deps` option. + +Note that, as query does not consider configurations, potential toolchain +**implementations** are not considered dependencies, only the +required toolchain types. See +[toolchain documentation](/extending/toolchains#writing-rules-toolchains). + +### Soundness {:#soundness} + +Bazel query language expressions operate over the build +dependency graph, which is the graph implicitly defined by all +rule declarations in all `BUILD` files. It is important to understand +that this graph is somewhat abstract, and does not constitute a +complete description of how to perform all the steps of a build. In +order to perform a build, a _configuration_ is required too; +see the [configurations](/docs/user-manual#configurations) +section of the User's Guide for more detail. + +The result of evaluating an expression in the Bazel query language +is true _for all configurations_, which means that it may be +a conservative over-approximation, and not exactly precise. If you +use the query tool to compute the set of all source files needed +during a build, it may report more than are actually necessary +because, for example, the query tool will include all the files +needed to support message translation, even though you don't intend +to use that feature in your build. + +### On the preservation of graph order {:#graph-order} + +Operations preserve any ordering +constraints inherited from their subexpressions. You can think of +this as "the law of conservation of partial order". Consider an +example: if you issue a query to determine the transitive closure of +dependencies of a particular target, the resulting set is ordered +according to the dependency graph. If you filter that set to +include only the targets of `file` kind, the same +_transitive_ partial ordering relation holds between every +pair of targets in the resulting subset - even though none of +these pairs is actually directly connected in the original graph. +(There are no file-file edges in the build dependency graph). + +However, while all operators _preserve_ order, some +operations, such as the [set operations](#set-operations) +don't _introduce_ any ordering constraints of their own. +Consider this expression: + +``` +deps(x) union y +``` + +The order of the final result set is guaranteed to preserve all the +ordering constraints of its subexpressions, namely, that all the +transitive dependencies of `x` are correctly ordered with +respect to each other. However, the query guarantees nothing about +the ordering of the targets in `y`, nor about the +ordering of the targets in `deps(x)` relative to those in +`y` (except for those targets in +`y` that also happen to be in `deps(x)`). + +Operators that introduce ordering constraints include: +`allpaths`, `deps`, `rdeps`, `somepath`, and the target pattern wildcards +`package:*`, `dir/...`, etc. + +### Sky query {:#sky-query} + +_Sky Query_ is a mode of query that operates over a specified _universe scope_. + +#### Special functions available only in SkyQuery + +Sky Query mode has the additional query functions `allrdeps` and +`rbuildfiles`. These functions operate over the entire +universe scope (which is why they don't make sense for normal Query). + +#### Specifying a universe scope + +Sky Query mode is activated by passing the following two flags: +(`--universe_scope` or `--infer_universe_scope`) and +`--order_output=no`. +`--universe_scope=,...,` tells query to +preload the transitive closure of the target pattern specified by the target patterns, which can +be both additive and subtractive. All queries are then evaluated in this "scope". In particular, +the [`allrdeps`](#allrdeps) and +[`rbuildfiles`](#rbuildfiles) operators only return results from this scope. +`--infer_universe_scope` tells Bazel to infer a value for `--universe_scope` +from the query expression. This inferred value is the list of unique target patterns in the +query expression, but this might not be what you want. For example: + +```posix-terminal +bazel query --infer_universe_scope --order_output=no "allrdeps(//my:target)" +``` + +The list of unique target patterns in this query expression is `["//my:target"]`, so +Bazel treats this the same as the invocation: + +```posix-terminal +bazel query --universe_scope=//my:target --order_output=no "allrdeps(//my:target)" +``` + +But the result of that query with `--universe_scope` is only `//my:target`; +none of the reverse dependencies of `//my:target` are in the universe, by +construction! On the other hand, consider: + +```posix-terminal +bazel query --infer_universe_scope --order_output=no "tests(//a/... + b/...) intersect allrdeps(siblings(rbuildfiles(my/starlark/file.bzl)))" +``` + +This is a meaningful query invocation that is trying to compute the test targets in the +[`tests`](#tests) expansion of the targets under some directories that +transitively depend on targets whose definition uses a certain `.bzl` file. Here, +`--infer_universe_scope` is a convenience, especially in the case where the choice of +`--universe_scope` would otherwise require you to parse the query expression yourself. + +So, for query expressions that use universe-scoped operators like +[`allrdeps`](#allrdeps) and +[`rbuildfiles`](#rbuildfiles) be sure to use +`--infer_universe_scope` only if its behavior is what you want. + +Sky Query has some advantages and disadvantages compared to the default query. The main +disadvantage is that it cannot order its output according to graph order, and thus certain +[output formats](#output-formats) are forbidden. Its advantages are that it provides +two operators ([`allrdeps`](#allrdeps) and +[`rbuildfiles`](#rbuildfiles)) that are not available in the default query. +As well, Sky Query does its work by introspecting the +[Skyframe](/reference/skyframe) graph, rather than creating a new +graph, which is what the default implementation does. Thus, there are some circumstances in which +it is faster and uses less memory. + +## Expressions: Syntax and semantics of the grammar {:#expressions} + +This is the grammar of the Bazel query language, expressed in EBNF notation: + +```none {:.devsite-disable-click-to-copy} +expr ::= {{ '' }}word{{ '' }} + | let {{ '' }}name{{ '' }} = {{ '' }}expr{{ '' }} in {{ '' }}expr{{ '' }} + | ({{ '' }}expr{{ '' }}) + | {{ '' }}expr{{ '' }} intersect {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} ^ {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} union {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} + {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} except {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} - {{ '' }}expr{{ '' }} + | set({{ '' }}word{{ '' }} *) + | {{ '' }}word{{ '' }} '(' {{ '' }}int{{ '' }} | {{ '' }}word{{ '' }} | {{ '' }}expr{{ '' }} ... ')' +``` + +The following sections describe each of the productions of this grammar in order. + +### Target patterns {:#target-patterns} + +``` +expr ::= {{ '' }}word{{ '' }} +``` + +Syntactically, a _target pattern_ is just a word. It's interpreted as an +(unordered) set of targets. The simplest target pattern is a label, which +identifies a single target (file or rule). For example, the target pattern +`//foo:bar` evaluates to a set containing one element, the target, the `bar` +rule. + +Target patterns generalize labels to include wildcards over packages and +targets. For example, `foo/...:all` (or just `foo/...`) is a target pattern +that evaluates to a set containing all _rules_ in every package recursively +beneath the `foo` directory; `bar/baz:all` is a target pattern that evaluates +to a set containing all the rules in the `bar/baz` package, but not its +subpackages. + +Similarly, `foo/...:*` is a target pattern that evaluates to a set containing +all _targets_ (rules _and_ files) in every package recursively beneath the +`foo` directory; `bar/baz:*` evaluates to a set containing all the targets in +the `bar/baz` package, but not its subpackages. + +Because the `:*` wildcard matches files as well as rules, it's often more +useful than `:all` for queries. Conversely, the `:all` wildcard (implicit in +target patterns like `foo/...`) is typically more useful for builds. + +`bazel query` target patterns work the same as `bazel build` build targets do. +For more details, see [Target Patterns](/docs/user-manual#target-patterns), or +type `bazel help target-syntax`. + +Target patterns may evaluate to a singleton set (in the case of a label), to a +set containing many elements (as in the case of `foo/...`, which has thousands +of elements) or to the empty set, if the target pattern matches no targets. + +All nodes in the result of a target pattern expression are correctly ordered +relative to each other according to the dependency relation. So, the result of +`foo:*` is not just the set of targets in package `foo`, it is also the +_graph_ over those targets. (No guarantees are made about the relative ordering +of the result nodes against other nodes.) For more details, see the +[graph order](#graph-order) section. + +### Variables {:#variables} + +```none {:.devsite-disable-click-to-copy} +expr ::= let {{ '' }}name{{ '' }} = {{ '' }}expr{{ '' }}{{ '' }}1{{ '' }} in {{ '' }}expr{{ '' }}{{ '' }}2{{ '' }} + | {{ '' }}$name{{ '' }} +``` + +The Bazel query language allows definitions of and references to +variables. The result of evaluation of a `let` expression is the same as +that of {{ '' }}expr{{ '' }}2, with all free occurrences +of variable {{ '' }}name{{ '' }} replaced by the value of +{{ '' }}expr{{ '' }}1. + +For example, `let v = foo/... in allpaths($v, //common) intersect $v` is +equivalent to the `allpaths(foo/...,//common) intersect foo/...`. + +An occurrence of a variable reference `name` other than in +an enclosing `let {{ '' }}name{{ '' }} = ...` expression is an +error. In other words, top-level query expressions cannot have free +variables. + +In the above grammar productions, `name` is like _word_, but with the +additional constraint that it be a legal identifier in the C programming +language. References to the variable must be prepended with the "$" character. + +Each `let` expression defines only a single variable, but you can nest them. + +Both [target patterns](#target-patterns) and variable references consist of +just a single token, a word, creating a syntactic ambiguity. However, there is +no semantic ambiguity, because the subset of words that are legal variable +names is disjoint from the subset of words that are legal target patterns. + +Technically speaking, `let` expressions do not increase +the expressiveness of the query language: any query expressible in +the language can also be expressed without them. However, they +improve the conciseness of many queries, and may also lead to more +efficient query evaluation. + +### Parenthesized expressions {:#parenthesized-expressions} + +```none {:.devsite-disable-click-to-copy} +expr ::= ({{ '' }}expr{{ '' }}) +``` + +Parentheses associate subexpressions to force an order of evaluation. +A parenthesized expression evaluates to the value of its argument. + +### Algebraic set operations: intersection, union, set difference {:#algebraic-set-operations} + +```none {:.devsite-disable-click-to-copy} +expr ::= {{ '' }}expr{{ '' }} intersect {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} ^ {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} union {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} + {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} except {{ '' }}expr{{ '' }} + | {{ '' }}expr{{ '' }} - {{ '' }}expr{{ '' }} +``` + +These three operators compute the usual set operations over their arguments. +Each operator has two forms, a nominal form, such as `intersect`, and a +symbolic form, such as `^`. Both forms are equivalent; the symbolic forms are +quicker to type. (For clarity, the rest of this page uses the nominal forms.) + +For example, + +``` +foo/... except foo/bar/... +``` + +evaluates to the set of targets that match `foo/...` but not `foo/bar/...`. + +You can write the same query as: + +``` +foo/... - foo/bar/... +``` + +The `intersect` (`^`) and `union` (`+`) operations are commutative (symmetric); +`except` (`-`) is asymmetric. The parser treats all three operators as +left-associative and of equal precedence, so you might want parentheses. For +example, the first two of these expressions are equivalent, but the third is not: + +``` +x intersect y union z +(x intersect y) union z +x intersect (y union z) +``` + +Important: Use parentheses where there is any danger of ambiguity in reading a +query expression. + +### Read targets from an external source: set {:#set} + +```none {:.devsite-disable-click-to-copy} +expr ::= set({{ '' }}word{{ '' }} *) +``` + +The `set({{ '' }}a{{ '' }} {{ '' }}b{{ '' }} {{ '' }}c{{ '' }} ...)` +operator computes the union of a set of zero or more +[target patterns](#target-patterns), separated by whitespace (no commas). + +In conjunction with the Bourne shell's `$(...)` feature, `set()` provides a +means of saving the results of one query in a regular text file, manipulating +that text file using other programs (such as standard UNIX shell tools), and then +introducing the result back into the query tool as a value for further +processing. For example: + +```posix-terminal +bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo + +bazel query "kind(cc_binary, set($( foo + +bazel query "kind(cc_library, set($(' }}word{{ '' }} '(' {{ '' }}int{{ '' }} | {{ '' }}word{{ '' }} | {{ '' }}expr{{ '' }} ... ')' +``` + +The query language defines several functions. The name of the function +determines the number and type of arguments it requires. The following +functions are available: + +* [`allpaths`](#somepath-allpaths) +* [`attr`](#attr) +* [`buildfiles`](#buildfiles) +* [`rbuildfiles`](#rbuildfiles) +* [`deps`](#deps) +* [`executables`](#executables) +* [`filter`](#filter) +* [`kind`](#kind) +* [`labels`](#labels) +* [`loadfiles`](#loadfiles) +* [`rdeps`](#rdeps) +* [`allrdeps`](#allrdeps) +* [`same_pkg_direct_rdeps`](#same_pkg_direct_rdeps) +* [`siblings`](#siblings) +* [`some`](#some) +* [`somepath`](#somepath-allpaths) +* [`tests`](#tests) +* [`visible`](#visible) + + +### Transitive closure of dependencies: deps {:#deps} + +```none {:.devsite-disable-click-to-copy} +expr ::= deps({{ '' }}expr{{ '' }}) + | deps({{ '' }}expr{{ '' }}, {{ '' }}depth{{ '' }}) +``` + +The `deps({{ '' }}x{{ '' }})` operator evaluates to the graph formed +by the transitive closure of dependencies of its argument set +{{ '' }}x{{ '' }}. For example, the value of `deps(//foo)` is the +dependency graph rooted at the single node `foo`, including all its +dependencies. The value of `deps(foo/...)` is the dependency graphs whose roots +are all rules in every package beneath the `foo` directory. In this context, +'dependencies' means only rule and file targets, therefore the `BUILD` and +Starlark files needed to create these targets are not included here. For that +you should use the [`buildfiles`](#buildfiles) operator. + +The resulting graph is ordered according to the dependency relation. For more +details, see the section on [graph order](#graph-order). + +The `deps` operator accepts an optional second argument, which is an integer +literal specifying an upper bound on the depth of the search. So +`deps(foo:*, 0)` returns all targets in the `foo` package, while +`deps(foo:*, 1)` further includes the direct prerequisites of any target in the +`foo` package, and `deps(foo:*, 2)` further includes the nodes directly +reachable from the nodes in `deps(foo:*, 1)`, and so on. (These numbers +correspond to the ranks shown in the [`minrank`](#output-ranked) output format.) +If the {{ '' }}depth{{ '' }} parameter is omitted, the search is +unbounded: it computes the reflexive transitive closure of prerequisites. + +### Transitive closure of reverse dependencies: rdeps {:#rdeps} + +```none {:.devsite-disable-click-to-copy} +expr ::= rdeps({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}) + | rdeps({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}, {{ '' }}depth{{ '' }}) +``` + +The `rdeps({{ '' }}u{{ '' }}, {{ '' }}x{{ '' }})` +operator evaluates to the reverse dependencies of the argument set +{{ '' }}x{{ '' }} within the transitive closure of the universe set +{{ '' }}u{{ '' }}. + +The resulting graph is ordered according to the dependency relation. See the +section on [graph order](#graph-order) for more details. + +The `rdeps` operator accepts an optional third argument, which is an integer +literal specifying an upper bound on the depth of the search. The resulting +graph only includes nodes within a distance of the specified depth from any +node in the argument set. So `rdeps(//foo, //common, 1)` evaluates to all nodes +in the transitive closure of `//foo` that directly depend on `//common`. (These +numbers correspond to the ranks shown in the [`minrank`](#output-ranked) output +format.) If the {{ '' }}depth{{ '' }} parameter is omitted, the +search is unbounded. + +### Transitive closure of all reverse dependencies: allrdeps {:#allrdeps} + +``` +expr ::= allrdeps({{ '' }}expr{{ '' }}) + | allrdeps({{ '' }}expr{{ '' }}, {{ '' }}depth{{ '' }}) +``` + +Note: Only available with [Sky Query](#sky-query) + +The `allrdeps` operator behaves just like the [`rdeps`](#rdeps) +operator, except that the "universe set" is whatever the `--universe_scope` flag +evaluated to, instead of being separately specified. Thus, if +`--universe_scope=//foo/...` was passed, then `allrdeps(//bar)` is +equivalent to `rdeps(//foo/..., //bar)`. + +### Direct reverse dependencies in the same package: same_pkg_direct_rdeps {:#same_pkg_direct_rdeps} + +``` +expr ::= same_pkg_direct_rdeps({{ '' }}expr{{ '' }}) +``` + +The `same_pkg_direct_rdeps({{ '' }}x{{ '' }})` operator evaluates to the full set of targets +that are in the same package as a target in the argument set, and which directly depend on it. + +### Dealing with a target's package: siblings {:#siblings} + +``` +expr ::= siblings({{ '' }}expr{{ '' }}) +``` + +The `siblings({{ '' }}x{{ '' }})` operator evaluates to the full set of targets that are in +the same package as a target in the argument set. + +### Arbitrary choice: some {:#some} + +``` +expr ::= some({{ '' }}expr{{ '' }}) + | some({{ '' }}expr{{ '' }}, {{ '' }}count{{ ' '}}) +``` + +The `some({{ '' }}x{{ '' }}, {{ '' }}k{{ '' }})` operator +selects at most {{ '' }}k{{ '' }} targets arbitrarily from its +argument set {{ '' }}x{{ '' }}, and evaluates to a set containing +only those targets. Parameter {{ '' }}k{{ '' }} is optional; if +missing, the result will be a singleton set containing only one target +arbitrarily selected. If the size of argument set {{ '' }}x{{ '' }} is +smaller than {{ '' }}k{{ '' }}, the whole argument set +{{ '' }}x{{ '' }} will be returned. + +For example, the expression `some(//foo:main union //bar:baz)` evaluates to a +singleton set containing either `//foo:main` or `//bar:baz`—though which +one is not defined. The expression `some(//foo:main union //bar:baz, 2)` or +`some(//foo:main union //bar:baz, 3)` returns both `//foo:main` and +`//bar:baz`. + +If the argument is a singleton, then `some` +computes the identity function: `some(//foo:main)` is +equivalent to `//foo:main`. + +It is an error if the specified argument set is empty, as in the +expression `some(//foo:main intersect //bar:baz)`. + +### Path operators: somepath, allpaths {:#somepath-allpaths} + +``` +expr ::= somepath({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}) + | allpaths({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}) +``` + +The `somepath({{ '' }}S{{ '' }}, {{ '' }}E{{ '' }})` and +`allpaths({{ '' }}S{{ '' }}, {{ '' }}E{{ '' }})` operators compute +paths between two sets of targets. Both queries accept two +arguments, a set {{ '' }}S{{ '' }} of starting points and a set +{{ '' }}E{{ '' }} of ending points. `somepath` returns the +graph of nodes on _some_ arbitrary path from a target in +{{ '' }}S{{ '' }} to a target in {{ '' }}E{{ '' }}; `allpaths` +returns the graph of nodes on _all_ paths from any target in +{{ '' }}S{{ '' }} to any target in {{ '' }}E{{ '' }}. + +The resulting graphs are ordered according to the dependency relation. +See the section on [graph order](#graph-order) for more details. + + + + + + + +
+
+ Somepath +
somepath(S1 + S2, E), one possible result.
+
+ + 		+
+ Somepath +
somepath(S1 + S2, E), another possible result.
+
+ + 		+
+ Allpaths +
allpaths(S1 + S2, E)
+
+ +
+ +### Target kind filtering: kind {:#kind} + +``` +expr ::= kind({{ '' }}word{{ '' }}, {{ '' }}expr{{ '' }}) +``` + +The `kind({{ '' }}pattern{{ '' }}, {{ '' }}input{{ '' }})` +operator applies a filter to a set of targets, and discards those targets +that are not of the expected kind. The {{ '' }}pattern{{ '' }} +parameter specifies what kind of target to match. + +For example, the kinds for the four targets defined by the `BUILD` file +(for package `p`) shown below are illustrated in the table: + + + + + + + + + + + + + + + + + + + + + + + + +
CodeTargetKind
+ 
+        genrule(
+            name = "a",
+            srcs = ["a.in"],
+            outs = ["a.out"],
+            cmd = "...",
+        )
+
+ 		//p:agenrule rule
//p:a.insource file
//p:a.outgenerated file
//p:BUILDsource file
+ +Thus, `kind("cc_.* rule", foo/...)` evaluates to the set +of all `cc_library`, `cc_binary`, etc, +rule targets beneath `foo`, and `kind("source file", deps(//foo))` +evaluates to the set of all source files in the transitive closure +of dependencies of the `//foo` target. + +Quotation of the {{ '' }}pattern{{ '' }} argument is often required +because without it, many [regular expressions](#regex), such as `source +file` and `.*_test`, are not considered words by the parser. + +When matching for `package group`, targets ending in +`:all` may not yield any results. Use `:all-targets` instead. + +### Target name filtering: filter {:#filter} + +``` +expr ::= filter({{ '' }}word{{ '' }}, {{ '' }}expr{{ '' }}) +``` + +The `filter({{ '' }}pattern{{ '' }}, {{ '' }}input{{ '' }})` +operator applies a filter to a set of targets, and discards targets whose +labels (in absolute form) do not match the pattern; it +evaluates to a subset of its input. + +The first argument, {{ '' }}pattern{{ '' }} is a word containing a +[regular expression](#regex) over target names. A `filter` expression +evaluates to the set containing all targets {{ '' }}x{{ '' }} such that +{{ '' }}x{{ '' }} is a member of the set {{ '' }}input{{ '' }} and the +label (in absolute form, such as `//foo:bar`) +of {{ '' }}x{{ '' }} contains an (unanchored) match +for the regular expression {{ '' }}pattern{{ '' }}. Since all +target names start with `//`, it may be used as an alternative +to the `^` regular expression anchor. + +This operator often provides a much faster and more robust alternative to the +`intersect` operator. For example, in order to see all +`bar` dependencies of the `//foo:foo` target, one could +evaluate + +``` +deps(//foo) intersect //bar/... +``` + +This statement, however, will require parsing of all `BUILD` files in the +`bar` tree, which will be slow and prone to errors in +irrelevant `BUILD` files. An alternative would be: + +``` +filter(//bar, deps(//foo)) +``` + +which would first calculate the set of `//foo` dependencies and +then would filter only targets matching the provided pattern—in other +words, targets with names containing `//bar` as a substring. + +Another common use of the `filter({{ '' }}pattern{{ '' }}, +{{ '' }}expr{{ '' }})` operator is to filter specific files by their +name or extension. For example, + +``` +filter("\.cc$", deps(//foo)) +``` + +will provide a list of all `.cc` files used to build `//foo`. + +### Rule attribute filtering: attr {:#attr} + +``` +expr ::= attr({{ '' }}word{{ '' }}, {{ '' }}word{{ '' }}, {{ '' }}expr{{ '' }}) +``` + +The +`attr({{ '' }}name{{ '' }}, {{ '' }}pattern{{ '' }}, {{ '' }}input{{ '' }})` +operator applies a filter to a set of targets, and discards targets that aren't +rules, rule targets that do not have attribute {{ '' }}name{{ '' }} +defined or rule targets where the attribute value does not match the provided +[regular expression](#regex) {{ '' }}pattern{{ '' }}; it evaluates +to a subset of its input. + +The first argument, {{ '' }}name{{ '' }} is the name of the rule +attribute that should be matched against the provided +[regular expression](#regex) pattern. The second argument, +{{ '' }}pattern{{ '' }} is a regular expression over the attribute +values. An `attr` expression evaluates to the set containing all targets +{{ '' }}x{{ '' }} such that {{ '' }}x{{ '' }} is a +member of the set {{ '' }}input{{ '' }}, is a rule with the defined +attribute {{ '' }}name{{ '' }} and the attribute value contains an +(unanchored) match for the regular expression +{{ '' }}pattern{{ '' }}. If {{ '' }}name{{ '' }} is an +optional attribute and rule does not specify it explicitly then default +attribute value will be used for comparison. For example, + +``` +attr(linkshared, 0, deps(//foo)) +``` + +will select all `//foo` dependencies that are allowed to have a +linkshared attribute (such as, `cc_binary` rule) and have it either +explicitly set to 0 or do not set it at all but default value is 0 (such as for +`cc_binary` rules). + +List-type attributes (such as `srcs`, `data`, etc) are +converted to strings of the form `[value1, ..., valuen]`, +starting with a `[` bracket, ending with a `]` bracket +and using "`, `" (comma, space) to delimit multiple values. +Labels are converted to strings by using the absolute form of the +label. For example, an attribute `deps=[":foo", +"//otherpkg:bar", "wiz"]` would be converted to the +string `[//thispkg:foo, //otherpkg:bar, //thispkg:wiz]`. +Brackets are always present, so the empty list would use string value `[]` +for matching purposes. For example, + +``` +attr("srcs", "\[\]", deps(//foo)) +``` + +will select all rules among `//foo` dependencies that have an +empty `srcs` attribute, while + +``` +attr("data", ".{3,}", deps(//foo)) +``` + +will select all rules among `//foo` dependencies that specify at +least one value in the `data` attribute (every label is at least +3 characters long due to the `//` and `:`). + +To select all rules among `//foo` dependencies with a particular `value` in a +list-type attribute, use + +``` +attr("tags", "[\[ ]value[,\]]", deps(//foo)) +``` + +This works because the character before `value` will be `[` or a space and the +character after `value` will be a comma or `]`. + +To select all rules among `//foo` dependencies with a particular `key` and +`value` in a dict-type attribute, use + +``` +attr("some_dict_attribute", "[\{ ]key=value[,\}]", deps(//foo)) +``` + +This would select `//foo` if `//foo` is defined as + +``` +some_rule( + name = "foo", + some_dict_attribute = { + "key": "value", + }, +) +``` + +This works because the character before `key=value` will be `{` or a space and +the character after `key=value` will be a comma or `}`. + +### Rule visibility filtering: visible {:#visible} + +``` +expr ::= visible({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}) +``` + +The `visible({{ '' }}predicate{{ '' }}, {{ '' }}input{{ '' }})` operator +applies a filter to a set of targets, and discards targets without the +required visibility. + +The first argument, {{ '' }}predicate{{ '' }}, is a set of targets that all targets +in the output must be visible to. A {{ '' }}visible{{ '' }} expression +evaluates to the set containing all targets {{ '' }}x{{ '' }} such that {{ '' }}x{{ '' }} +is a member of the set {{ '' }}input{{ '' }}, and for all targets {{ '' }}y{{ '' }} in +{{ '' }}predicate{{ '' }} {{ '' }}x{{ '' }} is visible to {{ '' }}y{{ '' }}. For example: + +``` +visible(//foo, //bar:*) +``` + +will select all targets in the package `//bar` that `//foo` +can depend on without violating visibility restrictions. + +### Evaluation of rule attributes of type label: labels {:#labels} + +``` +expr ::= labels({{ '' }}word{{ '' }}, {{ '' }}expr{{ '' }}) +``` + +The `labels({{ '' }}attr_name{{ '' }}, {{ '' }}inputs{{ '' }})` +operator returns the set of targets specified in the +attribute {{ '' }}attr_name{{ '' }} of type "label" or "list of label" in +some rule in set {{ '' }}inputs{{ '' }}. + +For example, `labels(srcs, //foo)` returns the set of +targets appearing in the `srcs` attribute of +the `//foo` rule. If there are multiple rules +with `srcs` attributes in the {{ '' }}inputs{{ '' }} set, the +union of their `srcs` is returned. + +### Expand and filter test_suites: tests {:#tests} + +``` +expr ::= tests({{ '' }}expr{{ '' }}) +``` + +The `tests({{ '' }}x{{ '' }})` operator returns the set of all test +rules in set {{ '' }}x{{ '' }}, expanding any `test_suite` rules into +the set of individual tests that they refer to, and applying filtering by +`tag` and `size`. + +By default, query evaluation +ignores any non-test targets in all `test_suite` rules. This can be +changed to errors with the `--strict_test_suite` option. + +For example, the query `kind(test, foo:*)` lists all +the `*_test` and `test_suite` rules +in the `foo` package. All the results are (by +definition) members of the `foo` package. In contrast, +the query `tests(foo:*)` will return all of the +individual tests that would be executed by `bazel test +foo:*`: this may include tests belonging to other packages, +that are referenced directly or indirectly +via `test_suite` rules. + +### Executable targets: executables {:#executables} + +``` +expr ::= executables({{ '' }}expr{{ '' }}) +``` + +The `executables({{ '' }}x{{ '' }})` operator returns the set of all +executable targets in set {{ '' }}x{{ '' }}. These targets +are of rule types that can be run with `bazel run`, such as `cc_binary`, +or any other rule that sets `executable = True` in its definition. + +This doesn't include test targets, which can be added to the result with +the [`tests`](#tests) operator. + +### Package definition files: buildfiles {:#buildfiles} + +``` +expr ::= buildfiles({{ '' }}expr{{ '' }}) +``` + +The `buildfiles({{ '' }}x{{ '' }})` operator returns the set +of files that define the packages of each target in +set {{ '' }}x{{ '' }}; in other words, for each package, its `BUILD` file, +plus any .bzl files it references via `load`. Note that this +also returns the `BUILD` files of the packages containing these +`load`ed files. + +This operator is typically used when determining what files or +packages are required to build a specified target, often in conjunction with +the [`--output package`](#output-package) option, below). For example, + +```posix-terminal +bazel query 'buildfiles(deps(//foo))' --output package +``` + +returns the set of all packages on which `//foo` transitively depends. + +Note: A naive attempt at the above query would omit +the `buildfiles` operator and use only `deps`, +but this yields an incorrect result: while the result contains the +majority of needed packages, those packages that contain only files +that are `load()`'ed will be missing. + +Warning: Bazel pretends each `.bzl` file produced by +`buildfiles` has a corresponding target (for example, file `a/b.bzl` => +target `//a:b.bzl`), but this isn't necessarily the case. Therefore, +`buildfiles` doesn't compose well with other query operators and its results can be +misleading when formatted in a structured way, such as +[`--output=xml`](#xml). + +### Package definition files: rbuildfiles {:#rbuildfiles} + +``` +expr ::= rbuildfiles({{ '' }}word{{ '' }}, ...) +``` + +Note: Only available with [Sky Query](#sky-query). + +The `rbuildfiles` operator takes a comma-separated list of path fragments and returns +the set of `BUILD` files that transitively depend on these path fragments. For instance, if +`//foo` is a package, then `rbuildfiles(foo/BUILD)` will return the +`//foo:BUILD` target. If the `foo/BUILD` file has +`load('//bar:file.bzl'...` in it, then `rbuildfiles(bar/file.bzl)` will +return the `//foo:BUILD` target, as well as the targets for any other `BUILD` files that +load `//bar:file.bzl` + +The scope of the rbuildfiles operator is the universe specified by the +`--universe_scope` flag. Files that do not correspond directly to `BUILD` files and `.bzl` +files do not affect the results. For instance, source files (like `foo.cc`) are ignored, +even if they are explicitly mentioned in the `BUILD` file. Symlinks, however, are respected, so that +if `foo/BUILD` is a symlink to `bar/BUILD`, then +`rbuildfiles(bar/BUILD)` will include `//foo:BUILD` in its results. + +The `rbuildfiles` operator is almost morally the inverse of the +[`buildfiles`](#buildfiles) operator. However, this moral inversion +holds more strongly in one direction: the outputs of `rbuildfiles` are just like the +inputs of `buildfiles`; the former will only contain `BUILD` file targets in packages, +and the latter may contain such targets. In the other direction, the correspondence is weaker. The +outputs of the `buildfiles` operator are targets corresponding to all packages and .`bzl` +files needed by a given input. However, the inputs of the `rbuildfiles` operator are +not those targets, but rather the path fragments that correspond to those targets. + +### Package definition files: loadfiles {:#loadfiles} + +``` +expr ::= loadfiles({{ '' }}expr{{ '' }}) +``` + +The `loadfiles({{ '' }}x{{ '' }})` operator returns the set of +Starlark files that are needed to load the packages of each target in +set {{ '' }}x{{ '' }}. In other words, for each package, it returns the +.bzl files that are referenced from its `BUILD` files. + +Warning: Bazel pretends each of these .bzl files has a corresponding target +(for example, file `a/b.bzl` => target `//a:b.bzl`), but this isn't +necessarily the case. Therefore, `loadfiles` doesn't compose well with other query +operators and its results can be misleading when formatted in a structured way, such as +[`--output=xml`](#xml). + +## Output formats {:#output-formats} + +`bazel query` generates a graph. +You specify the content, format, and ordering by which +`bazel query` presents this graph +by means of the `--output` command-line option. + +When running with [Sky Query](#sky-query), only output formats that are compatible with +unordered output are allowed. Specifically, `graph`, `minrank`, and +`maxrank` output formats are forbidden. + +Some of the output formats accept additional options. The name of +each output option is prefixed with the output format to which it +applies, so `--graph:factored` applies only +when `--output=graph` is being used; it has no effect if +an output format other than `graph` is used. Similarly, +`--xml:line_numbers` applies only when `--output=xml` +is being used. + +### On the ordering of results {:#results-ordering} + +Although query expressions always follow the "[law of +conservation of graph order](#graph-order)", _presenting_ the results may be done +in either a dependency-ordered or unordered manner. This does **not** +influence the targets in the result set or how the query is computed. It only +affects how the results are printed to stdout. Moreover, nodes that are +equivalent in the dependency order may or may not be ordered alphabetically. +The `--order_output` flag can be used to control this behavior. +(The `--[no]order_results` flag has a subset of the functionality +of the `--order_output` flag and is deprecated.) + +The default value of this flag is `auto`, which prints results in **lexicographical +order**. However, when `somepath(a,b)` is used, the results will be printed in +`deps` order instead. + +When this flag is `no` and `--output` is one of +`build`, `label`, `label_kind`, `location`, `package`, `proto`, or +`xml`, the outputs will be printed in arbitrary order. **This is +generally the fastest option**. It is not supported though when +`--output` is one of `graph`, `minrank` or +`maxrank`: with these formats, Bazel always prints results +ordered by the dependency order or rank. + +When this flag is `deps`, Bazel prints results in some topological order—that is, +dependents first and dependencies after. However, nodes that are unordered by the +dependency order (because there is no path from either one to the other) may be +printed in any order. + +When this flag is `full`, Bazel prints nodes in a fully deterministic (total) order. +First, all nodes are sorted alphabetically. Then, each node in the list is used as the start of a +post-order depth-first search in which outgoing edges to unvisited nodes are traversed in +alphabetical order of the successor nodes. Finally, nodes are printed in the reverse of the order +in which they were visited. + +Printing nodes in this order may be slower, so it should be used only when determinism is +important. + +### Print the source form of targets as they would appear in BUILD {:#target-source-form} + +``` +--output build +``` + +With this option, the representation of each target is as if it were +hand-written in the BUILD language. All variables and function calls +(such as glob, macros) are expanded, which is useful for seeing the effect +of Starlark macros. Additionally, each effective rule reports a +`generator_name` and/or `generator_function`) value, +giving the name of the macro that was evaluated to produce the effective rule. + +Although the output uses the same syntax as `BUILD` files, it is not +guaranteed to produce a valid `BUILD` file. + +### Print the label of each target {:#print-label-target} + +``` +--output label +``` + +With this option, the set of names (or _labels_) of each target +in the resulting graph is printed, one label per line, in +topological order (unless `--noorder_results` is specified, see +[notes on the ordering of results](#result-order)). +(A topological ordering is one in which a graph +node appears earlier than all of its successors.) Of course there +are many possible topological orderings of a graph (_reverse +postorder_ is just one); which one is chosen is not specified. + +When printing the output of a `somepath` query, the order +in which the nodes are printed is the order of the path. + +Caveat: in some corner cases, there may be two distinct targets with +the same label; for example, a `sh_binary` rule and its +sole (implicit) `srcs` file may both be called +`foo.sh`. If the result of a query contains both of +these targets, the output (in `label` format) will appear +to contain a duplicate. When using the `label_kind` (see +below) format, the distinction becomes clear: the two targets have +the same name, but one has kind `sh_binary rule` and the +other kind `source file`. + +### Print the label and kind of each target {:#print-target-label} + +``` +--output label_kind +``` + +Like `label`, this output format prints the labels of +each target in the resulting graph, in topological order, but it +additionally precedes the label by the [_kind_](#kind) of the target. + +### Print targets in protocol buffer format {:#print-target-proto} + +``` +--output proto +``` + +Prints the query output as a +[`QueryResult`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) +protocol buffer. + +### Print targets in length-delimited protocol buffer format {:#print-target-length-delimited-proto} + +``` +--output streamed_proto +``` + +Prints a +[length-delimited](https://protobuf.dev/programming-guides/encoding/#size-limit) +stream of +[`Target`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) +protocol buffers. This is useful to _(i)_ get around +[size limitations](https://protobuf.dev/programming-guides/encoding/#size-limit) +of protocol buffers when there are too many targets to fit in a single +`QueryResult` or _(ii)_ to start processing while Bazel is still outputting. + +### Print targets in text proto format {:#print-target-textproto} + +``` +--output textproto +``` + +Similar to `--output proto`, prints the +[`QueryResult`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) +protocol buffer but in +[text format](https://protobuf.dev/reference/protobuf/textformat-spec/). + +### Print targets in ndjson format {:#print-target-streamed-jsonproto} + +``` +--output streamed_jsonproto +``` + +Similar to `--output streamed_proto`, prints a stream of +[`Target`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) +protocol buffers but in [ndjson](https://github.com/ndjson/ndjson-spec) format. + +### Print the label of each target, in rank order {:#print-target-label-rank-order} + +``` +--output minrank --output maxrank +``` + +Like `label`, the `minrank` +and `maxrank` output formats print the labels of each +target in the resulting graph, but instead of appearing in +topological order, they appear in rank order, preceded by their +rank number. These are unaffected by the result ordering +`--[no]order_results` flag (see [notes on +the ordering of results](#result-order)). + +There are two variants of this format: `minrank` ranks +each node by the length of the shortest path from a root node to it. +"Root" nodes (those which have no incoming edges) are of rank 0, +their successors are of rank 1, etc. (As always, edges point from a +target to its prerequisites: the targets it depends upon.) + +`maxrank` ranks each node by the length of the longest +path from a root node to it. Again, "roots" have rank 0, all other +nodes have a rank which is one greater than the maximum rank of all +their predecessors. + +All nodes in a cycle are considered of equal rank. (Most graphs are +acyclic, but cycles do occur +simply because `BUILD` files contain erroneous cycles.) + +These output formats are useful for discovering how deep a graph is. +If used for the result of a `deps(x)`, `rdeps(x)`, +or `allpaths` query, then the rank number is equal to the +length of the shortest (with `minrank`) or longest +(with `maxrank`) path from `x` to a node in +that rank. `maxrank` can be used to determine the +longest sequence of build steps required to build a target. + +Note: The ranked output of a `somepath` query is +basically meaningless because `somepath` doesn't +guarantee to return either a shortest or a longest path, and it may +include "transitive" edges from one path node to another that are +not direct edges in original graph. + +For example, the graph on the left yields the outputs on the right +when `--output minrank` and `--output maxrank` +are specified, respectively. + + + + + + + +
Out ranked + + 
+      minrank
+
+      0 //c:c
+      1 //b:b
+      1 //a:a
+      2 //b:b.cc
+      2 //a:a.cc
+
+ 		+ 
+      maxrank
+
+      0 //c:c
+      1 //b:b
+      2 //a:a
+      2 //b:b.cc
+      3 //a:a.cc
+
+
+ +### Print the location of each target {:#print-target-location} + +``` +--output location +``` + +Like `label_kind`, this option prints out, for each +target in the result, the target's kind and label, but it is +prefixed by a string describing the location of that target, as a +filename and line number. The format resembles the output of +`grep`. Thus, tools that can parse the latter (such as Emacs +or vi) can also use the query output to step through a series of +matches, allowing the Bazel query tool to be used as a +dependency-graph-aware "grep for BUILD files". + +The location information varies by target kind (see the [kind](#kind) operator). For rules, the +location of the rule's declaration within the `BUILD` file is printed. +For source files, the location of line 1 of the actual file is +printed. For a generated file, the location of the rule that +generates it is printed. (The query tool does not have sufficient +information to find the actual location of the generated file, and +in any case, it might not exist if a build has not yet been performed.) + +### Print the set of packages {:#print-package-set} + +```--output package``` + +This option prints the name of all packages to which +some target in the result set belongs. The names are printed in +lexicographical order; duplicates are excluded. Formally, this +is a _projection_ from the set of labels (package, target) onto +packages. + +Packages in external repositories are formatted as +`@repo//foo/bar` while packages in the main repository are +formatted as `foo/bar`. + +In conjunction with the `deps(...)` query, this output +option can be used to find the set of packages that must be checked +out in order to build a given set of targets. + +### Display a graph of the result {:#display-result-graph} + +```--output graph``` + +This option causes the query result to be printed as a directed +graph in the popular AT&T GraphViz format. Typically the +result is saved to a file, such as `.png` or `.svg`. +(If the `dot` program is not installed on your workstation, you +can install it using the command `sudo apt-get install graphviz`.) +See the example section below for a sample invocation. + +This output format is particularly useful for `allpaths`, +`deps`, or `rdeps` queries, where the result +includes a _set of paths_ that cannot be easily visualized when +rendered in a linear form, such as with `--output label`. + +By default, the graph is rendered in a _factored_ form. That is, +topologically-equivalent nodes are merged together into a single +node with multiple labels. This makes the graph more compact +and readable, because typical result graphs contain highly +repetitive patterns. For example, a `java_library` rule +may depend on hundreds of Java source files all generated by the +same `genrule`; in the factored graph, all these files +are represented by a single node. This behavior may be disabled +with the `--nograph:factored` option. + +#### `--graph:node_limit {{ '' }}n{{ '' }}` {:#graph-nodelimit} + +The option specifies the maximum length of the label string for a +graph node in the output. Longer labels will be truncated; -1 +disables truncation. Due to the factored form in which graphs are +usually printed, the node labels may be very long. GraphViz cannot +handle labels exceeding 1024 characters, which is the default value +of this option. This option has no effect unless +`--output=graph` is being used. + +#### `--[no]graph:factored` {:#graph-factored} + +By default, graphs are displayed in factored form, as explained +[above](#output-graph). +When `--nograph:factored` is specified, graphs are +printed without factoring. This makes visualization using GraphViz +impractical, but the simpler format may ease processing by other +tools (such as grep). This option has no effect +unless `--output=graph` is being used. + +### XML {:#xml} + +```--output xml``` + +This option causes the resulting targets to be printed in an XML +form. The output starts with an XML header such as this + +``` + + +``` + + + +and then continues with an XML element for each target +in the result graph, in topological order (unless +[unordered results](#result-order) are requested), +and then finishes with a terminating + +``` + +``` + +Simple entries are emitted for targets of `file` kind: + +``` + + +``` + +But for rules, the XML is structured and contains definitions of all +the attributes of the rule, including those whose value was not +explicitly specified in the rule's `BUILD` file. + +Additionally, the result includes `rule-input` and +`rule-output` elements so that the topology of the +dependency graph can be reconstructed without having to know that, +for example, the elements of the `srcs` attribute are +forward dependencies (prerequisites) and the contents of the +`outs` attribute are backward dependencies (consumers). + +`rule-input` elements for [implicit dependencies](#implicit_deps) are suppressed if +`--noimplicit_deps` is specified. + +``` + + + + + + + ... + + + + + + + + + + + + ... + +``` + +Every XML element for a target contains a `name` +attribute, whose value is the target's label, and +a `location` attribute, whose value is the target's +location as printed by the [`--output location`](#print-target-location). + +#### `--[no]xml:line_numbers` {:#xml-linenumbers} + +By default, the locations displayed in the XML output contain line numbers. +When `--noxml:line_numbers` is specified, line numbers are not printed. + +#### `--[no]xml:default_values` {:#xml-defaultvalues} + +By default, XML output does not include rule attribute whose value +is the default value for that kind of attribute (for example, if it +were not specified in the `BUILD` file, or the default value was +provided explicitly). This option causes such attribute values to +be included in the XML output. + +### Regular expressions {:#regular-expressions} + +Regular expressions in the query language use the Java regex library, so you can use the +full syntax for +[`java.util.regex.Pattern`](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html){: .external}. + +### Querying with external repositories {:#querying-external-repositories} + +If the build depends on rules from [external repositories](/external/overview) +then query results will include these dependencies. For +example, if `//foo:bar` depends on `@other-repo//baz:lib`, then +`bazel query 'deps(//foo:bar)'` will list `@other-repo//baz:lib` as a +dependency. diff --git a/query/quickstart.mdx b/query/quickstart.mdx index 2e95dc941..eebcec986 100644 --- a/query/quickstart.mdx +++ b/query/quickstart.mdx @@ -2,8 +2,6 @@ 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. @@ -12,7 +10,6 @@ For language and `--output` flag details, see the [Bazel query reference](/query 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. @@ -259,13 +256,9 @@ This query returns all of the targets in the 'customers' package that have a tag Use this query to learn what Jenny wants to order. -
- -

Answer

-

Mac and Cheese

- -
- + + Mac and Cheese + ## Adding a new dependency @@ -306,7 +299,6 @@ public class Smoothie { } ``` - 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`** @@ -421,7 +413,6 @@ Build `cafe` again to confirm that there are no errors. If it builds successfull 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 ``` @@ -492,24 +483,17 @@ 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)' + + Check the tags and dependencies for useful information. + + + + 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 diff --git a/reference/be/be-nav.mdx b/reference/be/be-nav.mdx index fbf211d1d..cdf688c19 100644 --- a/reference/be/be-nav.mdx +++ b/reference/be/be-nav.mdx @@ -1,27 +1,30 @@ \*\*Build Encyclopedia\*\* -- [Overview](/reference/be/overview.html) -- [Concepts](#be-menu) - [Common Definitions](/reference/be/common-definitions.html) - - ["Make" variables](/reference/be/make-variables.html) -- [Rules](#be-rules) - [Functions](/reference/be/functions.html) - - [C / C++](/reference/be/c-cpp.html) - - [Java](/reference/be/java.html) - - [Objective-C](/reference/be/objective-c.html) - - [Protocol Buffer](/reference/be/protocol-buffer.html) - - [Python](/reference/be/python.html) - - [Shell](/reference/be/shell.html) - - [Extra Actions](/reference/be/extra-actions.html) - - [General](/reference/be/general.html) - - [Platforms and Toolchains](/reference/be/platforms-and-toolchains.html) - - [AppEngine](https://github.com/bazelbuild/rules_appengine) - - [Apple (Swift, iOS, macOS, tvOS, visionOS, watchOS)](https://github.com/bazelbuild/rules_apple) - - [C#](https://github.com/bazelbuild/rules_dotnet) - - [D](https://github.com/bazelbuild/rules_d) - - [Docker](https://github.com/bazelbuild/rules_docker) - - [Groovy](https://github.com/bazelbuild/rules_groovy) - - [Go](https://github.com/bazelbuild/rules_go) - - [JavaScript (Closure)](https://github.com/bazelbuild/rules_closure) - - [Jsonnet](https://github.com/bazelbuild/rules_jsonnet) - - [Packaging](/reference/be/pkg.html) - - [Rust](https://github.com/bazelbuild/rules_rust) - - [Sass](https://github.com/bazelbuild/rules_sass) - - [Scala](https://github.com/bazelbuild/rules_scala) + +* [Overview](/reference/be/overview) +* [Concepts](#be-menu) + + [Common Definitions](/reference/be/common-definitions) + + ["Make" variables](/reference/be/make-variables) +* [Rules](#be-rules) + + [Functions](/reference/be/functions) + + [C / C++](/reference/be/c-cpp) + + [Java](/reference/be/java) + + [Objective-C](/reference/be/objective-c) + + [Protocol Buffer](/reference/be/protocol-buffer) + + [Python](/reference/be/python) + + [Shell](/reference/be/shell) + + [Extra Actions](/reference/be/extra-actions) + + [General](/reference/be/general) + + [Platforms and Toolchains](/reference/be/platforms-and-toolchains) + + [AppEngine](https://github.com/bazelbuild/rules_appengine) + + [Apple (Swift, iOS, macOS, tvOS, visionOS, watchOS)](https://github.com/bazelbuild/rules_apple) + + [C#](https://github.com/bazelbuild/rules_dotnet) + + [D](https://github.com/bazelbuild/rules_d) + + [Docker](https://github.com/bazelbuild/rules_docker) + + [Groovy](https://github.com/bazelbuild/rules_groovy) + + [Go](https://github.com/bazelbuild/rules_go) + + [JavaScript (Closure)](https://github.com/bazelbuild/rules_closure) + + [Jsonnet](https://github.com/bazelbuild/rules_jsonnet) + + [Packaging](/reference/be/pkg) + + [Rust](https://github.com/bazelbuild/rules_rust) + + [Sass](https://github.com/bazelbuild/rules_sass) + + [Scala](https://github.com/bazelbuild/rules_scala) \ No newline at end of file diff --git a/reference/be/c-cpp.mdx b/reference/be/c-cpp.mdx index a6e8453d5..214f06b41 100644 --- a/reference/be/c-cpp.mdx +++ b/reference/be/c-cpp.mdx @@ -2,21 +2,19 @@ title: 'C / C++ Rules' --- - - ## Rules -- [cc\_binary](#cc_binary) -- [cc\_import](#cc_import) -- [cc\_library](#cc_library) -- [cc\_shared\_library](#cc_shared_library) -- [cc\_static\_library](#cc_static_library) -- [cc\_test](#cc_test) -- [cc\_toolchain](#cc_toolchain) -- [fdo\_prefetch\_hints](#fdo_prefetch_hints) -- [fdo\_profile](#fdo_profile) -- [memprof\_profile](#memprof_profile) -- [propeller\_optimize](#propeller_optimize) +* [cc\_binary](#cc_binary) +* [cc\_import](#cc_import) +* [cc\_library](#cc_library) +* [cc\_shared\_library](#cc_shared_library) +* [cc\_static\_library](#cc_static_library) +* [cc\_test](#cc_test) +* [cc\_toolchain](#cc_toolchain) +* [fdo\_prefetch\_hints](#fdo_prefetch_hints) +* [fdo\_profile](#fdo_profile) +* [memprof\_profile](#memprof_profile) +* [propeller\_optimize](#propeller_optimize) ## cc\_binary @@ -28,6 +26,7 @@ cc_binary(name, deps, srcs, data, additional_compiler_inputs, additional_linker_ It produces an executable binary. + The `name` of the target should be the same as the name of the source file that is the main entry point of the application (minus the extension). For example, if your entry point is in `main.cc`, then your name should @@ -35,415 +34,43 @@ be `main`. #### Implicit output targets -- `name.stripped` (only built if explicitly requested): A stripped - version of the binary. `strip -g` is run on the binary to remove debug - symbols. Additional strip options can be provided on the command line using - `--stripopt=-foo`. -- `name.dwp` (only built if explicitly requested): If - [Fission](https://gcc.gnu.org/wiki/DebugFission) is enabled: a debug - information package file suitable for debugging remotely deployed binaries. Else: an - empty file. +* `name.stripped` (only built if explicitly requested): A stripped + version of the binary. `strip -g` is run on the binary to remove debug + symbols. Additional strip options can be provided on the command line using + `--stripopt=-foo`. +* `name.dwp` (only built if explicitly requested): If + [Fission](https://gcc.gnu.org/wiki/DebugFission) is enabled: a debug + information package file suitable for debugging remotely deployed binaries. Else: an + empty file. ### Arguments -Attributes`name` - -[Name](/concepts/labels#target-names); required - -A unique name for this target. - -`deps` - -List of [labels](/concepts/labels); default is `[]` - - The list of other libraries to be linked in to the binary target. - -These can be `cc_library` or `objc_library` -targets. - -It is also allowed to -put linker scripts (.lds) into deps, and reference them in -[`linkopts`](#cc_binary.linkopts), -but please consider -[`additional_linker_inputs`](#cc_binary.additional_linker_inputs) -for that use case. - `srcs` - -List of [labels](/concepts/labels); default is `[]` - - The list of C and C++ files that are processed to create the library target. -These are C/C++ source and header files, either non-generated (normal source -code) or generated. - -All `.cc`, `.c`, and `.cpp` files will -be compiled. These might be generated files: if a named file is in -the `outs` of some other rule, this `cc_library` -will automatically depend on that other rule. - -Pure assembler files (.s, .asm) are not preprocessed and are typically built using -the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built -using the C/C++ compiler. - -A `.h` file will not be compiled, but will be available for -inclusion by sources in this rule. Both `.cc` and -`.h` files can directly include headers listed in -these `srcs` or in the `hdrs` of this rule or any -rule listed in the `deps` argument. - -All `#include` d files must be mentioned in the -`hdrs` attribute of this or referenced `cc_library` -rules, or they should be listed in `srcs` if they are private -to this library. See ["Header inclusion checking"](#hdrs) for -a more detailed description. - -`.so`, `.lo`, and `.a` files are -pre-compiled files. Your library might have these as -`srcs` if it uses third-party code for which we don't -have source code. - -If the `srcs` attribute includes the label of another rule, -`cc_library` will use the output files of that rule as source files to -compile. This is useful for one-off generation of source code (for more than occasional -use, it's better to implement a Starlark rule class and use the `cc_common` -API) - -Permitted `srcs` file types: - -- C and C++ source files: `.c`, `.cc`, `.cpp`, - `.cxx`, `.c++`, `.C` -- C and C++ header files: `.h`, `.hh`, `.hpp`, - `.hxx`, `.inc`, `.inl`, `.H` -- Assembler with C preprocessor: `.S` -- Archive: `.a`, `.pic.a` -- "Always link" library: `.lo`, `.pic.lo` -- Shared library, versioned or unversioned: `.so`, - `.so.version` -- Object file: `.o`, `.pic.o` - -... and any rules that produce those files (e.g. `cc_embed_data`). -Different extensions denote different programming languages in -accordance with gcc convention. - -`data` - -List of [labels](/concepts/labels); default is `[]` - - The list of files needed by this library at runtime. - -See general comments about `data` -at [Typical attributes defined by\ -most build rules](/reference/be/common-definitions#typical-attributes). - -If a `data` is the name of a generated file, then this -`cc_library` rule automatically depends on the generating -rule. - -If a `data` is a rule name, then this -`cc_library` rule automatically depends on that rule, -and that rule's `outs` are automatically added to -this `cc_library`'s data files. - -Your C++ code can access these data files like so: - -```lang-starlark - - const std::string path = devtools_build::GetDataDependencyFilepath( - "my/test/data/file"); - -``` - -`additional_compiler_inputs` - -List of [labels](/concepts/labels); default is `[]` - - Any additional files you might want to pass to the compiler command line, such as sanitizer -ignorelists, for example. Files specified here can then be used in copts with the -$(location) function. - `additional_linker_inputs` - -List of [labels](/concepts/labels); default is `[]` - - Dependencies that are only made available to the C++ linker command. - -Unlike `deps`, which is conceptually made for both compilation and -linking dependencies, `additional_linker_inputs` is specifically -made for only the latter, and signals a dependency that is required only for -linking (for example, files that are referenced in `linkopts`). - -For example, compiled Windows .res files can be provided here to be embedded in -the binary target. - -`conlyopts` - -List of strings; default is `[]` - - Add these options to the C compilation command. -Subject to ["Make variable"](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). - `copts` - -List of strings; default is `[]` - - Add these options to the C/C++ compilation command. -Subject to ["Make variable"](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). - -Each string in this attribute is added in the given order to `COPTS` before -compiling the binary target. The flags take effect only for compiling this target, not -its dependencies, so be careful about header files included elsewhere. -All paths should be relative to the workspace, not to the current package. -This attribute should not be needed outside of `third_party`. - -If the package declares the [feature](/reference/be/functions.html#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings -that consist of a single "Make" variable. - -`cxxopts` - -List of strings; default is `[]` - - Add these options to the C++ compilation command. -Subject to ["Make variable"](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). - `defines` - -List of strings; default is `[]` - - List of defines to add to the compile line of this and all dependent targets. -Subject to ["Make" variable](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). -Each string, which must consist of a single Bourne shell token, -is prepended with `-D` and added to the compile command line to this target, -as well as to every rule that depends on it. Be very careful, since this may have -far-reaching effects -- the defines are added to every target that depends on -this target. When in doubt, add define values to -[`local_defines`](#cc_binary.local_defines) instead. - `dynamic_deps` - -List of [labels](/concepts/labels); default is `[]` - - These are other `cc_shared_library` dependencies the current target depends on. - -The `cc_shared_library` implementation will use the list of -`dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the -current target's `dynamic_deps`) to decide which `cc_libraries` in -the transitive `deps` should not be linked in because they are already provided -by a different `cc_shared_library`. - - -`hdrs_check` - -String; default is `""` - - Deprecated, no-op. - `includes` - -List of strings; default is `[]` - - List of include dirs to be added to the compile line. -Subject to ["Make variable"](/reference/be/make-variables) substitution. -Each string is prepended with the package path and passed to the C++ toolchain for -expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system -with typical feature definitions will produce -`-isystem path_to_package/include_entry`. -This should only be used for third-party libraries that -do not conform to the Google style of writing #include statements. -Unlike [COPTS](#cc_binary.copts), these flags are added for this rule -and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add -"-I" flags to [COPTS](#cc_binary.copts) instead. - -The added `include` paths will include generated files as well as -files in the source tree. - -`link_extra_lib` - -[Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:link_extra_lib"` - - Control linking of extra libraries. - -By default, C++ binaries are linked against `@bazel_tools//tools/cpp:link_extra_lib`, -which by default depends on the label flag `@bazel_tools//tools/cpp:link_extra_libs`. -Without setting the flag, this library is empty by default. Setting the label flag -allows linking optional dependencies, such as overrides for weak symbols, interceptors -for shared library functions, or special runtime libraries (for malloc replacements, -prefer `malloc` or `--custom_malloc`). Setting this attribute to -`None` disables this behaviour. - -`linkopts` - -List of strings; default is `[]` - - Add these flags to the C++ linker command. -Subject to ["Make" variable](make-variables.html) substitution, -[Bourne shell tokenization](common-definitions.html#sh-tokenization) and -[label expansion](common-definitions.html#label-expansion). -Each string in this attribute is added to `LINKOPTS` before -linking the binary target. - -Each element of this list that does not start with `$` or `-` is -assumed to be the label of a target in `deps`. The -list of files generated by that target is appended to the linker -options. An error is reported if the label is invalid, or is -not declared in `deps`. - -`linkshared` - -Boolean; default is `False` - - Create a shared library. -To enable this attribute, include `linkshared=True` in your rule. By default -this option is off. - -The presence of this flag means that linking occurs with the `-shared` flag -to `gcc`, and the resulting shared library is suitable for loading into for -example a Java program. However, for build purposes it will never be linked into the -dependent binary, as it is assumed that shared libraries built with a -[cc\_binary](#cc_binary) rule are only loaded manually by other programs, so -it should not be considered a substitute for the [cc\_library](#cc_library) -rule. For sake of scalability we recommend avoiding this approach altogether and -simply letting `java_library` depend on `cc_library` rules -instead. - -If you specify both `linkopts=['-static']` and `linkshared=True`, -you get a single completely self-contained unit. If you specify both -`linkstatic=True` and `linkshared=True`, you get a single, mostly -self-contained unit. - -`linkstatic` - -Boolean; default is `True` - - For [`cc_binary`](/reference/be/c-cpp.html#cc_binary) and -[`cc_test`](/reference/be/c-cpp.html#cc_test): link the binary in static -mode. For `cc_library.link_static`: see below. - -By default this option is on for `cc_binary` and off for the rest. - -If enabled and this is a binary or test, this option tells the build tool to link in -`.a`'s instead of `.so`'s for user libraries whenever possible. -System libraries such as libc (but _not_ the C/C++ runtime libraries, -see below) are still linked dynamically, as are libraries for which -there is no static library. So the resulting executable will still be dynamically -linked, hence only _mostly_ static. - -There are really three different ways to link an executable: - -- STATIC with fully\_static\_link feature, in which everything is linked statically; - e.g. " `gcc -static foo.o libbar.a libbaz.a -lm`". - - - This mode is enabled by specifying `fully_static_link` in the - [`features`](/reference/be/common-definitions#features) attribute. -- STATIC, in which all user libraries are linked statically (if a static - version is available), but where system libraries (excluding C/C++ runtime libraries) - are linked dynamically, e.g. " `gcc foo.o libfoo.a libbaz.a -lm`". - - - This mode is enabled by specifying `linkstatic=True`. -- DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is - available), e.g. " `gcc foo.o libfoo.so libbaz.so -lm`". - - - This mode is enabled by specifying `linkstatic=False`. - -If the `linkstatic` attribute or `fully_static_link` in -`features` is used outside of `//third_party` -please include a comment near the rule to explain why. - -The `linkstatic` attribute has a different meaning if used on a -[`cc_library()`](/reference/be/c-cpp.html#cc_library) rule. -For a C++ library, `linkstatic=True` indicates that only -static linking is allowed, so no `.so` will be produced. linkstatic=False does -not prevent static libraries from being created. The attribute is meant to control the -creation of dynamic libraries. - -There should be very little code built with `linkstatic=False` in production. -If `linkstatic=False`, then the build tool will create symlinks to -depended-upon shared libraries in the `*.runfiles` area. - -`local_defines` - -List of strings; default is `[]` - - List of defines to add to the compile line. -Subject to ["Make" variable](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). -Each string, which must consist of a single Bourne shell token, -is prepended with `-D` and added to the compile command line for this target, -but not to its dependents. Unlike `defines`, the defines are only added to the -compile command line for this target. - `malloc` - -[Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:malloc"` - - Override the default dependency on malloc. - -By default, C++ binaries are linked against `//tools/cpp:malloc`, -which is an empty library so the binary ends up using libc malloc. -This label must refer to a `cc_library`. If compilation is for a non-C++ -rule, this option has no effect. The value of this attribute is ignored if -`linkshared=True` is specified. - -`module_interfaces` - -List of [labels](/concepts/labels); default is `[]` - - The list of files are regarded as C++20 Modules Interface. - -C++ Standard has no restriction about module interface file extension - -- Clang use cppm -- GCC can use any source file extension -- MSVC use ixx - -The use is guarded by the flag -`--experimental_cpp_modules`. - -`nocopts` - -String; default is `""` - - Remove matching options from the C++ compilation command. -Subject to ["Make" variable](/reference/be/make-variables) substitution. -The value of this attribute is interpreted as a regular expression. -Any preexisting `COPTS` that match this regular expression -(including values explicitly specified in the rule's [copts](#cc_binary.copts) attribute) -will be removed from `COPTS` for purposes of compiling this rule. -This attribute should not be needed or used -outside of `third_party`. The values are not preprocessed -in any way other than the "Make" variable substitution. - `reexport_deps` - -List of [labels](/concepts/labels); default is `[]` - -`stamp` - -Integer; default is `-1` - - Whether to encode build information into the binary. Possible values: - -- `stamp = 1`: Always stamp the build information into the binary, even in - [`--nostamp`](/docs/user-manual#flag--stamp) builds. **This** - **setting should be avoided**, since it potentially kills remote caching for the - binary and any downstream actions that depend on it. - -- `stamp = 0`: Always replace build information by constant values. This - gives good build result caching. - -- `stamp = -1`: Embedding of build information is controlled by the - [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. - - -Stamped binaries are _not_ rebuilt unless their dependencies change. - -`win_def_file` - -[Label](/concepts/labels); default is `None` - - The Windows DEF file to be passed to linker. - -This attribute should only be used when Windows is the target platform. -It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. +| Attributes | | +| --- | --- | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](/concepts/labels); default is `[]` The list of other libraries to be linked in to the binary target. These can be `cc_library` or `objc_library` targets. It is also allowed to put linker scripts (.lds) into deps, and reference them in [`linkopts`](#cc_binary.linkopts), but please consider [`additional_linker_inputs`](#cc_binary.additional_linker_inputs) for that use case. | +| `srcs` | List of [labels](/concepts/labels); default is `[]` The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated. All `.cc`, `.c`, and `.cpp` files will be compiled. These might be generated files: if a named file is in the `outs` of some other rule, this `cc_library` will automatically depend on that other rule. Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built using the C/C++ compiler. A `.h` file will not be compiled, but will be available for inclusion by sources in this rule. Both `.cc` and `.h` files can directly include headers listed in these `srcs` or in the `hdrs` of this rule or any rule listed in the `deps` argument. All `#include`d files must be mentioned in the `hdrs` attribute of this or referenced `cc_library` rules, or they should be listed in `srcs` if they are private to this library. See ["Header inclusion checking"](#hdrs) for a more detailed description. `.so`, `.lo`, and `.a` files are pre-compiled files. Your library might have these as `srcs` if it uses third-party code for which we don't have source code. If the `srcs` attribute includes the label of another rule, `cc_library` will use the output files of that rule as source files to compile. This is useful for one-off generation of source code (for more than occasional use, it's better to implement a Starlark rule class and use the `cc_common` API) Permitted `srcs` file types: * C and C++ source files: `.c`, `.cc`, `.cpp`, `.cxx`, `.c++`, `.C` * C and C++ header files: `.h`, `.hh`, `.hpp`, `.hxx`, `.inc`, `.inl`, `.H` * Assembler with C preprocessor: `.S` * Archive: `.a`, `.pic.a` * "Always link" library: `.lo`, `.pic.lo` * Shared library, versioned or unversioned: `.so`, `.so.version` * Object file: `.o`, `.pic.o` ... and any rules that produce those files (e.g. `cc_embed_data`). Different extensions denote different programming languages in accordance with gcc convention. | +| `data` | List of [labels](/concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](/reference/be/common-definitions#typical-attributes). If a `data` is the name of a generated file, then this `cc_library` rule automatically depends on the generating rule. If a `data` is a rule name, then this `cc_library` rule automatically depends on that rule, and that rule's `outs` are automatically added to this `cc_library`'s data files. Your C++ code can access these data files like so: ``` const std::string path = devtools_build::GetDataDependencyFilepath( "my/test/data/file"); ``` | +| `additional_compiler_inputs` | List of [labels](/concepts/labels); default is `[]` Any additional files you might want to pass to the compiler command line, such as sanitizer ignorelists, for example. Files specified here can then be used in copts with the $(location) function. | +| `additional_linker_inputs` | List of [labels](/concepts/labels); default is `[]` Dependencies that are only made available to the C++ linker command. Unlike `deps`, which is conceptually made for both compilation and linking dependencies, `additional_linker_inputs` is specifically made for only the latter, and signals a dependency that is required only for linking (for example, files that are referenced in `linkopts`). For example, compiled Windows .res files can be provided here to be embedded in the binary target. | +| `conlyopts` | List of strings; default is `[]` Add these options to the C compilation command. Subject to ["Make variable"](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). | +| `copts` | List of strings; default is `[]` Add these options to the C/C++ compilation command. Subject to ["Make variable"](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string in this attribute is added in the given order to `COPTS` before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. This attribute should not be needed outside of `third_party`. If the package declares the [feature](/reference/be/functions#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings that consist of a single "Make" variable. | +| `cxxopts` | List of strings; default is `[]` Add these options to the C++ compilation command. Subject to ["Make variable"](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). | +| `defines` | List of strings; default is `[]` List of defines to add to the compile line of this and all dependent targets. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects -- the defines are added to every target that depends on this target. When in doubt, add define values to [`local_defines`](#cc_binary.local_defines) instead. | +| `dynamic_deps` | List of [labels](/concepts/labels); default is `[]` These are other `cc_shared_library` dependencies the current target depends on. The `cc_shared_library` implementation will use the list of `dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the current target's `dynamic_deps`) to decide which `cc_libraries` in the transitive `deps` should not be linked in because they are already provided by a different `cc_shared_library`. | +| `hdrs_check` | String; default is `""` Deprecated, no-op. | +| `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](/reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The added `include` paths will include generated files as well as files in the source tree. | +| `link_extra_lib` | [Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:link_extra_lib"` Control linking of extra libraries. By default, C++ binaries are linked against `@bazel_tools//tools/cpp:link_extra_lib`, which by default depends on the label flag `@bazel_tools//tools/cpp:link_extra_libs`. Without setting the flag, this library is empty by default. Setting the label flag allows linking optional dependencies, such as overrides for weak symbols, interceptors for shared library functions, or special runtime libraries (for malloc replacements, prefer `malloc` or `--custom_malloc`). Setting this attribute to `None` disables this behaviour. | +| `linkopts` | List of strings; default is `[]` Add these flags to the C++ linker command. Subject to ["Make" variable](make-variables) substitution, [Bourne shell tokenization](common-definitions#sh-tokenization) and [label expansion](common-definitions#label-expansion). Each string in this attribute is added to `LINKOPTS` before linking the binary target. Each element of this list that does not start with `$` or `-` is assumed to be the label of a target in `deps`. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in `deps`. | +| `linkshared` | Boolean; default is `False` Create a shared library. To enable this attribute, include `linkshared=True` in your rule. By default this option is off. The presence of this flag means that linking occurs with the `-shared` flag to `gcc`, and the resulting shared library is suitable for loading into for example a Java program. However, for build purposes it will never be linked into the dependent binary, as it is assumed that shared libraries built with a [cc\_binary](#cc_binary) rule are only loaded manually by other programs, so it should not be considered a substitute for the [cc\_library](#cc_library) rule. For sake of scalability we recommend avoiding this approach altogether and simply letting `java_library` depend on `cc_library` rules instead. If you specify both `linkopts=['-static']` and `linkshared=True`, you get a single completely self-contained unit. If you specify both `linkstatic=True` and `linkshared=True`, you get a single, mostly self-contained unit. | +| `linkstatic` | Boolean; default is `True` For [`cc_binary`](/reference/be/c-cpp#cc_binary) and [`cc_test`](/reference/be/c-cpp#cc_test): link the binary in static mode. For `cc_library.link_static`: see below. By default this option is on for `cc_binary` and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in `.a`'s instead of `.so`'s for user libraries whenever possible. System libraries such as libc (but *not* the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only *mostly* static. There are really three different ways to link an executable: * STATIC with fully\_static\_link feature, in which everything is linked statically; e.g. "`gcc -static foo.o libbar.a libbaz.a -lm`". This mode is enabled by specifying `fully_static_link` in the [`features`](/reference/be/common-definitions#features) attribute. * STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "`gcc foo.o libfoo.a libbaz.a -lm`". This mode is enabled by specifying `linkstatic=True`. * DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "`gcc foo.o libfoo.so libbaz.so -lm`". This mode is enabled by specifying `linkstatic=False`. If the `linkstatic` attribute or `fully_static_link` in `features` is used outside of `//third_party` please include a comment near the rule to explain why. The `linkstatic` attribute has a different meaning if used on a [`cc_library()`](/reference/be/c-cpp#cc_library) rule. For a C++ library, `linkstatic=True` indicates that only static linking is allowed, so no `.so` will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with `linkstatic=False` in production. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area. | +| `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. Unlike `defines`, the defines are only added to the compile command line for this target. | +| `malloc` | [Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:malloc"` Override the default dependency on malloc. By default, C++ binaries are linked against `//tools/cpp:malloc`, which is an empty library so the binary ends up using libc malloc. This label must refer to a `cc_library`. If compilation is for a non-C++ rule, this option has no effect. The value of this attribute is ignored if `linkshared=True` is specified. | +| `module_interfaces` | List of [labels](/concepts/labels); default is `[]` The list of files are regarded as C++20 Modules Interface. C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx The use is guarded by the flag `--experimental_cpp_modules`. | +| `nocopts` | String; default is `""` Remove matching options from the C++ compilation command. Subject to ["Make" variable](/reference/be/make-variables) substitution. The value of this attribute is interpreted as a regular expression. Any preexisting `COPTS` that match this regular expression (including values explicitly specified in the rule's [copts](#cc_binary.copts) attribute) will be removed from `COPTS` for purposes of compiling this rule. This attribute should not be needed or used outside of `third_party`. The values are not preprocessed in any way other than the "Make" variable substitution. | +| `reexport_deps` | List of [labels](/concepts/labels); default is `[]` | +| `stamp` | Integer; default is `-1` Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in [`--nostamp`](/docs/user-manual#flag--stamp) builds. **This setting should be avoided**, since it potentially kills remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives good build result caching. * `stamp = -1`: Embedding of build information is controlled by the [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. Stamped binaries are *not* rebuilt unless their dependencies change. | +| `win_def_file` | [Label](/concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | ## cc\_import @@ -456,11 +83,9 @@ cc_import(name, deps, data, hdrs, alwayslink, aspect_hints, compatible_with, def `cc_import` rules allows users to import precompiled C/C++ libraries. The following are the typical use cases: +1. Linking a static library -1\. Linking a static library - -```lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -469,27 +94,23 @@ cc_import( # libmylib.a will be forcely linked into any binary that depends on it. # alwayslink = True, ) - ``` -2\. Linking a shared library (Unix) - -```lang-starlark +2. Linking a shared library (Unix) +``` cc_import( name = "mylib", hdrs = ["mylib.h"], shared_library = "libmylib.so", ) - ``` -3\. Linking a shared library with interface library +3. Linking a shared library with interface library On Unix: -```lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -498,13 +119,11 @@ cc_import( # libmylib.so will be available for runtime shared_library = "libmylib.so", ) - ``` On Windows: -```lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -513,15 +132,13 @@ cc_import( # mylib.dll will be available for runtime shared_library = "mylib.dll", ) - ``` -4\. Linking a shared library with `system_provided=True` +4. Linking a shared library with `system_provided=True` On Unix: -```lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -530,13 +147,11 @@ cc_import( # This indicates that Bazel is not responsible for making libmylib.so available. system_provided = True, ) - ``` On Windows: -```lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -546,28 +161,24 @@ cc_import( # This indicates that Bazel is not responsible for making mylib.dll available. system_provided = True, ) - ``` -5\. Linking to static or shared library +5. Linking to static or shared library On Unix: -```lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], static_library = "libmylib.a", shared_library = "libmylib.so", ) - ``` On Windows: -```lang-starlark - +``` cc_import( name = "mylib", hdrs = ["mylib.h"], @@ -575,13 +186,11 @@ cc_import( interface_library = "mylib.lib", # An import library for mylib.dll shared_library = "mylib.dll", ) - ``` The remaining is the same on Unix and Windows: -```lang-starlark - +``` # first will link to libmylib.a (or libmylib.lib) cc_binary( name = "first", @@ -597,183 +206,38 @@ cc_binary( deps = [":mylib"], linkstatic = False, ) - ``` `cc_import` supports an include attribute. For example: -```lang-starlark - +``` cc_import( name = "curl_lib", hdrs = glob(["vendor/curl/include/curl/*.h"]), includes = ["vendor/curl/include"], shared_library = "vendor/curl/lib/.libs/libcurl.dylib", ) - ``` ### Arguments -Attributes`name` - -[Name](/concepts/labels#target-names); required - -A unique name for this target. - -`deps` - -List of [labels](/concepts/labels); default is `[]` - - The list of other libraries that the target depends upon. -See general comments about `deps` -at [Typical attributes defined by\ -most build rules](/reference/be/common-definitions#typical-attributes). - `hdrs` - -List of [labels](/concepts/labels); default is `[]` - - The list of header files published by -this precompiled library to be directly included by sources in dependent rules. - `alwayslink` - -Boolean; default is `False` - - If enabled, any binary that depends (directly or indirectly) on this C++ -precompiled library will link in all the object files archived in the static library, -even if some contain no symbols referenced by the binary. -This is useful if your code isn't explicitly called by code in -the binary, e.g., if your code registers to receive some callback -provided by some service. - -If `alwayslink` doesn't work with VS 2017 on Windows, that is due to a -[known issue](https://github.com/bazelbuild/bazel/issues/3949), -please upgrade your VS 2017 to the latest version. - -`defines` - -List of strings; default is `[]` - - List of defines to add to the compile line of this and all dependent targets. -Subject to ["Make" variable](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). -Each string, which must consist of a single Bourne shell token, -is prepended with `-D` and added to the compile command line to this target, -as well as to every rule that depends on it. Be very careful, since this may have -far-reaching effects -- the defines are added to every target that depends on -this target. - `includes` - -List of strings; default is `[]` - - List of include dirs to be added to the compile line. -Subject to ["Make variable"](/reference/be/make-variables) substitution. -Each string is prepended with the package path and passed to the C++ toolchain for -expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system -with typical feature definitions will produce -`-isystem path_to_package/include_entry`. -This should only be used for third-party libraries that -do not conform to the Google style of writing #include statements. -Unlike [COPTS](#cc_binary.copts), these flags are added for this rule -and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add -"-I" flags to [COPTS](#cc_binary.copts) instead. - -The default `include` path doesn't include generated -files. If you need to `#include` a generated header -file, list it in the `srcs`. - -`interface_library` - -[Label](/concepts/labels); default is `None` - - A single interface library for linking the shared library. - -Permitted file types: -`.ifso`, -`.tbd`, -`.lib`, -`.so` -or `.dylib` - -`linkopts` - -List of strings; default is `[]` - - Add these flags to the C++ linker command. -Subject to ["Make" variable](make-variables.html) substitution, -[Bourne shell tokenization](common-definitions.html#sh-tokenization) and -[label expansion](common-definitions.html#label-expansion). -Each string in this attribute is added to `LINKOPTS` before -linking the binary target. - -Each element of this list that does not start with `$` or `-` is -assumed to be the label of a target in `deps`. The -list of files generated by that target is appended to the linker -options. An error is reported if the label is invalid, or is -not declared in `deps`. - -`objects` - -List of [labels](/concepts/labels); default is `[]` - -`pic_objects` - -List of [labels](/concepts/labels); default is `[]` - -`pic_static_library` - -[Label](/concepts/labels); default is `None` - -`shared_library` - -[Label](/concepts/labels); default is `None` - - A single precompiled shared library. Bazel ensures it is available to the -binary that depends on it during runtime. - -Permitted file types: -`.so`, -`.dll` `.dylib`, -or `.pyd` - -`static_library` - -[Label](/concepts/labels); default is `None` - - A single precompiled static library. - -Permitted file types: -`.a`, -`.pic.a` -or `.lib` - -`strip_include_prefix` - -String; default is `""` - - The prefix to strip from the paths of the headers of this rule. - -When set, the headers in the `hdrs` attribute of this rule are accessible -at their path with this prefix cut off. - -If it's a relative path, it's taken as a package-relative one. If it's an absolute one, -it's understood as a repository-relative path. - -The prefix in the `include_prefix` attribute is added after this prefix is -stripped. - -This attribute is only legal under `third_party`. - - -`system_provided` - -Boolean; default is `False` - - If enabled, it indicates the shared library required at runtime is provided by the system. In -this case, `interface_library` should be specified and -`shared_library` should be empty. - +| Attributes | | +| --- | --- | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](/concepts/labels); default is `[]` The list of other libraries that the target depends upon. See general comments about `deps` at [Typical attributes defined by most build rules](/reference/be/common-definitions#typical-attributes). | +| `hdrs` | List of [labels](/concepts/labels); default is `[]` The list of header files published by this precompiled library to be directly included by sources in dependent rules. | +| `alwayslink` | Boolean; default is `False` If enabled, any binary that depends (directly or indirectly) on this C++ precompiled library will link in all the object files archived in the static library, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. If `alwayslink` doesn't work with VS 2017 on Windows, that is due to a [known issue](https://github.com/bazelbuild/bazel/issues/3949), please upgrade your VS 2017 to the latest version. | +| `defines` | List of strings; default is `[]` List of defines to add to the compile line of this and all dependent targets. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects -- the defines are added to every target that depends on this target. | +| `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](/reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The default `include` path doesn't include generated files. If you need to `#include` a generated header file, list it in the `srcs`. | +| `interface_library` | [Label](/concepts/labels); default is `None` A single interface library for linking the shared library. Permitted file types: `.ifso`, `.tbd`, `.lib`, `.so` or `.dylib` | +| `linkopts` | List of strings; default is `[]` Add these flags to the C++ linker command. Subject to ["Make" variable](make-variables) substitution, [Bourne shell tokenization](common-definitions#sh-tokenization) and [label expansion](common-definitions#label-expansion). Each string in this attribute is added to `LINKOPTS` before linking the binary target. Each element of this list that does not start with `$` or `-` is assumed to be the label of a target in `deps`. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in `deps`. | +| `objects` | List of [labels](/concepts/labels); default is `[]` | +| `pic_objects` | List of [labels](/concepts/labels); default is `[]` | +| `pic_static_library` | [Label](/concepts/labels); default is `None` | +| `shared_library` | [Label](/concepts/labels); default is `None` A single precompiled shared library. Bazel ensures it is available to the binary that depends on it during runtime. Permitted file types: `.so`, `.dll` `.dylib`, or `.pyd` | +| `static_library` | [Label](/concepts/labels); default is `None` A single precompiled static library. Permitted file types: `.a`, `.pic.a` or `.lib` | +| `strip_include_prefix` | String; default is `""` The prefix to strip from the paths of the headers of this rule. When set, the headers in the `hdrs` attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the `include_prefix` attribute is added after this prefix is stripped. This attribute is only legal under `third_party`. | +| `system_provided` | Boolean; default is `False` If enabled, it indicates the shared library required at runtime is provided by the system. In this case, `interface_library` should be specified and `shared_library` should be empty. | ## cc\_library @@ -793,7 +257,7 @@ is the `.a` file. If you specify `alwayslink=True`, you get the `.lo` file. The actual output file name is `libfoo.so` for -the shared library, where _foo_ is the name of the rule. The +the shared library, where *foo* is the name of the rule. The other kinds of libraries end with `.lo` and `.a`, respectively. If you need a specific shared library name, for example, to define a Python module, use a genrule to copy the library @@ -824,8 +288,7 @@ the `srcs`. To illustrate these rules, look at the following example. -```lang-starlark - +``` cc_binary( name = "foo", srcs = [ @@ -853,16 +316,24 @@ cc_library( ], hdrs = ["baz.h"], ) - ``` The allowed direct inclusions in this example are listed in the table below. For example `foo.cc` is allowed to directly include `foo.h` and `bar.h`, but not `baz.h`. -Including fileAllowed inclusionsfoo.hbar.hfoo.ccfoo.h bar.hbar.hbar-impl.h baz.hbar-impl.hbar.h baz.hbar.ccbar.h bar-impl.h baz.hbaz.hbaz-impl.hbaz-impl.hbaz.hbaz.ccbaz.h baz-impl.h - -The inclusion checking rules only apply to _direct_ +| Including file | Allowed inclusions | +| --- | --- | +| foo.h | bar.h | +| foo.cc | foo.h bar.h | +| bar.h | bar-impl.h baz.h | +| bar-impl.h | bar.h baz.h | +| bar.cc | bar.h bar-impl.h baz.h | +| baz.h | baz-impl.h | +| baz-impl.h | baz.h | +| baz.cc | baz.h baz-impl.h | + +The inclusion checking rules only apply to *direct* inclusions. In the example above `foo.cc` is allowed to include `bar.h`, which may include `baz.h`, which in turn is allowed to include `baz-impl.h`. Technically, the @@ -880,7 +351,7 @@ The `layering_check` feature has to be supported by the toolchain and requested explicitly, for example via the `--features=layering_check` command-line flag or the `features` parameter of the -[`package`](/reference/be/functions.html#package) function. The toolchains +[`package`](/reference/be/functions#package) function. The toolchains provided by Bazel only support this feature with clang on Unix and macOS. #### Examples @@ -888,8 +359,7 @@ provided by Bazel only support this feature with clang on Unix and macOS. We use the `alwayslink` flag to force the linker to link in this code although the main binary code doesn't reference it. -```lang-starlark - +``` cc_library( name = "ast_inspector_lib", srcs = ["ast_inspector_lib.cc"], @@ -900,7 +370,6 @@ cc_library( # debug time, even if they aren't used anywhere in the code. alwayslink = True, ) - ``` The following example comes from @@ -910,8 +379,7 @@ another, dynamic library), so this rule specifies the `-ldl` link option to link the `dl` library. -```lang-starlark - +``` cc_library( name = "python2_4_3", linkopts = [ @@ -920,15 +388,13 @@ cc_library( ], deps = ["//third_party/expat"], ) - ``` The following example comes from `third_party/kde/BUILD`. We keep pre-built `.so` files in the depot. The header files live in a subdirectory named `include`. -```lang-starlark - +``` cc_library( name = "kde", srcs = [ @@ -941,15 +407,13 @@ cc_library( includes = ["include"], deps = ["//third_party/X11"], ) - ``` The following example comes from `third_party/gles/BUILD`. Third-party code often needs some `defines` and `linkopts`. -```lang-starlark - +``` cc_library( name = "gles", srcs = [ @@ -969,451 +433,68 @@ cc_library( "//third_party/X11", ], ) - ``` ### Arguments -Attributes`name` - -[Name](/concepts/labels#target-names); required - -A unique name for this target. - -`deps` - -List of [labels](/concepts/labels); default is `[]` - - The list of other libraries that the library target depends upon. - -These can be `cc_library` or `objc_library` targets. - -See general comments about `deps` -at [Typical attributes defined by\ -most build rules](/reference/be/common-definitions#typical-attributes). - -These should be names of C++ library rules. -When you build a binary that links this rule's library, -you will also link the libraries in `deps`. - -Despite the "deps" name, not all of this library's clients -belong here. Run-time data dependencies belong in `data`. -Source files generated by other rules belong in `srcs`. +| Attributes | | +| --- | --- | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](/concepts/labels); default is `[]` The list of other libraries that the library target depends upon. These can be `cc_library` or `objc_library` targets. See general comments about `deps` at [Typical attributes defined by most build rules](/reference/be/common-definitions#typical-attributes). These should be names of C++ library rules. When you build a binary that links this rule's library, you will also link the libraries in `deps`. Despite the "deps" name, not all of this library's clients belong here. Run-time data dependencies belong in `data`. Source files generated by other rules belong in `srcs`. To link in a pre-compiled third-party library, add its name to the `srcs` instead. To depend on something without linking it to this library, add its name to the `data` instead. | +| `srcs` | List of [labels](/concepts/labels); default is `[]` The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated. All `.cc`, `.c`, and `.cpp` files will be compiled. These might be generated files: if a named file is in the `outs` of some other rule, this `cc_library` will automatically depend on that other rule. Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built using the C/C++ compiler. A `.h` file will not be compiled, but will be available for inclusion by sources in this rule. Both `.cc` and `.h` files can directly include headers listed in these `srcs` or in the `hdrs` of this rule or any rule listed in the `deps` argument. All `#include`d files must be mentioned in the `hdrs` attribute of this or referenced `cc_library` rules, or they should be listed in `srcs` if they are private to this library. See ["Header inclusion checking"](#hdrs) for a more detailed description. `.so`, `.lo`, and `.a` files are pre-compiled files. Your library might have these as `srcs` if it uses third-party code for which we don't have source code. If the `srcs` attribute includes the label of another rule, `cc_library` will use the output files of that rule as source files to compile. This is useful for one-off generation of source code (for more than occasional use, it's better to implement a Starlark rule class and use the `cc_common` API) Permitted `srcs` file types: * C and C++ source files: `.c`, `.cc`, `.cpp`, `.cxx`, `.c++`, `.C` * C and C++ header files: `.h`, `.hh`, `.hpp`, `.hxx`, `.inc`, `.inl`, `.H` * Assembler with C preprocessor: `.S` * Archive: `.a`, `.pic.a` * "Always link" library: `.lo`, `.pic.lo` * Shared library, versioned or unversioned: `.so`, `.so.version` * Object file: `.o`, `.pic.o` ... and any rules that produce those files (e.g. `cc_embed_data`). Different extensions denote different programming languages in accordance with gcc convention. | +| `data` | List of [labels](/concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](/reference/be/common-definitions#typical-attributes). If a `data` is the name of a generated file, then this `cc_library` rule automatically depends on the generating rule. If a `data` is a rule name, then this `cc_library` rule automatically depends on that rule, and that rule's `outs` are automatically added to this `cc_library`'s data files. Your C++ code can access these data files like so: ``` const std::string path = devtools_build::GetDataDependencyFilepath( "my/test/data/file"); ``` | +| `hdrs` | List of [labels](/concepts/labels); default is `[]` The list of header files published by this library to be directly included by sources in dependent rules. This is the strongly preferred location for declaring header files that describe the interface for the library. These headers will be made available for inclusion by sources in this rule or in dependent rules. Headers not meant to be included by a client of this library should be listed in the `srcs` attribute instead, even if they are included by a published header. See ["Header inclusion checking"](#hdrs) for a more detailed description. Permitted `headers` file types: `.h`, `.hh`, `.hpp`, `.hxx`. | +| `additional_compiler_inputs` | List of [labels](/concepts/labels); default is `[]` Any additional files you might want to pass to the compiler command line, such as sanitizer ignorelists, for example. Files specified here can then be used in copts with the $(location) function. | +| `additional_linker_inputs` | List of [labels](/concepts/labels); default is `[]` Dependencies that are only made available to the C++ linker command. Unlike `deps`, which is conceptually made for both compilation and linking dependencies, `additional_linker_inputs` is specifically made for only the latter, and signals a dependency that is required only for linking (for example, files that are referenced in `linkopts`). For example, compiled Windows .res files can be provided here to be embedded in the binary target. | +| `alwayslink` | Boolean; default is `False` If 1, any binary that depends (directly or indirectly) on this C++ library will link in all the object files for the files listed in `srcs`, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. If alwayslink doesn't work with VS 2017 on Windows, that is due to a [known issue](https://github.com/bazelbuild/bazel/issues/3949), please upgrade your VS 2017 to the latest version. | +| `conlyopts` | List of strings; default is `[]` Add these options to the C compilation command. Subject to ["Make variable"](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). | +| `copts` | List of strings; default is `[]` Add these options to the C/C++ compilation command. Subject to ["Make variable"](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string in this attribute is added in the given order to `COPTS` before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. This attribute should not be needed outside of `third_party`. If the package declares the [feature](/reference/be/functions#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings that consist of a single "Make" variable. | +| `cxxopts` | List of strings; default is `[]` Add these options to the C++ compilation command. Subject to ["Make variable"](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). | +| `defines` | List of strings; default is `[]` List of defines to add to the compile line of this and all dependent targets. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects -- the defines are added to every target that depends on this target. When in doubt, add define values to [`local_defines`](#cc_binary.local_defines) instead. | +| `hdrs_check` | String; default is `""` Deprecated, no-op. | +| `implementation_deps` | List of [labels](/concepts/labels); default is `[]` The list of other libraries that the library target depends on. Unlike with `deps`, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with `implementation_deps` are still linked in binary targets that depend on this library. | +| `include_prefix` | String; default is `""` The prefix to add to the paths of the headers of this rule. When set, the headers in the `hdrs` attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the `strip_include_prefix` attribute is removed before this prefix is added. This attribute is only legal under `third_party`. | +| `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](/reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The added `include` paths will include generated files as well as files in the source tree. | +| `linkopts` | List of strings; default is `[]` See [`cc_binary.linkopts`](/reference/be/c-cpp#cc_binary.linkopts). The `linkopts` attribute is also applied to any target that depends, directly or indirectly, on this library via `deps` attributes (or via other attributes that are treated similarly: the [`malloc`](/reference/be/c-cpp#cc_binary.malloc) attribute of [`cc_binary`](/reference/be/c-cpp#cc_binary)). Dependency linkopts take precedence over dependent linkopts (i.e. dependency linkopts appear later in the command line). Linkopts specified in [`--linkopt`](../user-manual#flag--linkopt) take precedence over rule linkopts. | -To link in a pre-compiled third-party library, add its name to -the `srcs` instead. - -To depend on something without linking it to this library, add its -name to the `data` instead. - -`srcs` - -List of [labels](/concepts/labels); default is `[]` - - The list of C and C++ files that are processed to create the library target. -These are C/C++ source and header files, either non-generated (normal source -code) or generated. - -All `.cc`, `.c`, and `.cpp` files will -be compiled. These might be generated files: if a named file is in -the `outs` of some other rule, this `cc_library` -will automatically depend on that other rule. - -Pure assembler files (.s, .asm) are not preprocessed and are typically built using -the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built -using the C/C++ compiler. - -A `.h` file will not be compiled, but will be available for -inclusion by sources in this rule. Both `.cc` and -`.h` files can directly include headers listed in -these `srcs` or in the `hdrs` of this rule or any -rule listed in the `deps` argument. - -All `#include` d files must be mentioned in the -`hdrs` attribute of this or referenced `cc_library` -rules, or they should be listed in `srcs` if they are private -to this library. See ["Header inclusion checking"](#hdrs) for -a more detailed description. - -`.so`, `.lo`, and `.a` files are -pre-compiled files. Your library might have these as -`srcs` if it uses third-party code for which we don't -have source code. - -If the `srcs` attribute includes the label of another rule, -`cc_library` will use the output files of that rule as source files to -compile. This is useful for one-off generation of source code (for more than occasional -use, it's better to implement a Starlark rule class and use the `cc_common` -API) +Note that the `linkopts` attribute only applies +when creating `.so` files or executables, not +when creating `.a` or `.lo` files. +So if the `linkstatic=True` attribute is set, the +`linkopts` attribute has no effect on the creation of +this library, only on other targets which depend on this library. -Permitted `srcs` file types: +Also, it is important to note that "-Wl,-soname" or "-Xlinker -soname" +options are not supported and should never be specified in this attribute. -- C and C++ source files: `.c`, `.cc`, `.cpp`, - `.cxx`, `.c++`, `.C` -- C and C++ header files: `.h`, `.hh`, `.hpp`, - `.hxx`, `.inc`, `.inl`, `.H` -- Assembler with C preprocessor: `.S` -- Archive: `.a`, `.pic.a` -- "Always link" library: `.lo`, `.pic.lo` -- Shared library, versioned or unversioned: `.so`, - `.so.version` -- Object file: `.o`, `.pic.o` +The `.so` files produced by `cc_library` +rules are not linked against the libraries that they depend +on. If you're trying to create a shared library for use +outside of the main repository, e.g. for manual use +with `dlopen()` or `LD_PRELOAD`, +it may be better to use a `cc_binary` rule +with the `linkshared=True` attribute. +See [`cc_binary.linkshared`](/reference/be/c-cpp#cc_binary.linkshared). -... and any rules that produce those files (e.g. `cc_embed_data`). -Different extensions denote different programming languages in -accordance with gcc convention. +| `linkstamp` | [Label](/concepts/labels); default is `None` Simultaneously compiles and links the specified C++ source file into the final binary. This trickery is required to introduce timestamp information into binaries; if we compiled the source file to an object file in the usual way, the timestamp would be incorrect. A linkstamp compilation may not include any particular set of compiler flags and so should not depend on any particular header, compiler option, or other build variable. *This option should only be needed in the `base` package.* | +| `linkstatic` | Boolean; default is `False` For [`cc_binary`](/reference/be/c-cpp#cc_binary) and [`cc_test`](/reference/be/c-cpp#cc_test): link the binary in static mode. For `cc_library.link_static`: see below. By default this option is on for `cc_binary` and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in `.a`'s instead of `.so`'s for user libraries whenever possible. System libraries such as libc (but *not* the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only *mostly* static. There are really three different ways to link an executable: * STATIC with fully\_static\_link feature, in which everything is linked statically; e.g. "`gcc -static foo.o libbar.a libbaz.a -lm`". This mode is enabled by specifying `fully_static_link` in the [`features`](/reference/be/common-definitions#features) attribute. * STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "`gcc foo.o libfoo.a libbaz.a -lm`". This mode is enabled by specifying `linkstatic=True`. * DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "`gcc foo.o libfoo.so libbaz.so -lm`". This mode is enabled by specifying `linkstatic=False`. If the `linkstatic` attribute or `fully_static_link` in `features` is used outside of `//third_party` please include a comment near the rule to explain why. The `linkstatic` attribute has a different meaning if used on a [`cc_library()`](/reference/be/c-cpp#cc_library) rule. For a C++ library, `linkstatic=True` indicates that only static linking is allowed, so no `.so` will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with `linkstatic=False` in production. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area. | +| `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. Unlike `defines`, the defines are only added to the compile command line for this target. | +| `module_interfaces` | List of [labels](/concepts/labels); default is `[]` The list of files are regarded as C++20 Modules Interface. C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx The use is guarded by the flag `--experimental_cpp_modules`. | +| `strip_include_prefix` | String; default is `""` The prefix to strip from the paths of the headers of this rule. When set, the headers in the `hdrs` attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the `include_prefix` attribute is added after this prefix is stripped. This attribute is only legal under `third_party`. | +| `textual_hdrs` | List of [labels](/concepts/labels); default is `[]` The list of header files published by this library to be textually included by sources in dependent rules. This is the location for declaring header files that cannot be compiled on their own; that is, they always need to be textually included by other source files to build valid code. | +| `win_def_file` | [Label](/concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | -`data` +## cc\_shared\_library -List of [labels](/concepts/labels); default is `[]` +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_cc/blob/master/cc/private/rules_impl/cc_shared_library.bzl) - The list of files needed by this library at runtime. +``` +cc_shared_library(name, deps, additional_linker_inputs, aspect_hints, compatible_with, deprecation, dynamic_deps, exec_compatible_with, exec_group_compatible_with, exec_properties, exports_filter, features, package_metadata, restricted_to, roots, shared_lib_name, static_deps, tags, target_compatible_with, testonly, toolchains, user_link_flags, visibility, win_def_file) +``` -See general comments about `data` -at [Typical attributes defined by\ -most build rules](/reference/be/common-definitions#typical-attributes). +It produces a shared library. -If a `data` is the name of a generated file, then this -`cc_library` rule automatically depends on the generating -rule. - -If a `data` is a rule name, then this -`cc_library` rule automatically depends on that rule, -and that rule's `outs` are automatically added to -this `cc_library`'s data files. - -Your C++ code can access these data files like so: - -```lang-starlark - - const std::string path = devtools_build::GetDataDependencyFilepath( - "my/test/data/file"); - -``` - -`hdrs` - -List of [labels](/concepts/labels); default is `[]` - - The list of header files published by -this library to be directly included by sources in dependent rules. - -This is the strongly preferred location for declaring header files that -describe the interface for the library. These headers will be made -available for inclusion by sources in this rule or in dependent rules. -Headers not meant to be included by a client of this library should be -listed in the `srcs` attribute instead, even if they are -included by a published header. See ["Header inclusion\ -checking"](#hdrs) for a more detailed description. - -Permitted `headers` file types: -`.h`, -`.hh`, -`.hpp`, -`.hxx`. - -`additional_compiler_inputs` - -List of [labels](/concepts/labels); default is `[]` - - Any additional files you might want to pass to the compiler command line, such as sanitizer -ignorelists, for example. Files specified here can then be used in copts with the -$(location) function. - `additional_linker_inputs` - -List of [labels](/concepts/labels); default is `[]` - - Dependencies that are only made available to the C++ linker command. - -Unlike `deps`, which is conceptually made for both compilation and -linking dependencies, `additional_linker_inputs` is specifically -made for only the latter, and signals a dependency that is required only for -linking (for example, files that are referenced in `linkopts`). - -For example, compiled Windows .res files can be provided here to be embedded in -the binary target. - -`alwayslink` - -Boolean; default is `False` - - If 1, any binary that depends (directly or indirectly) on this C++ -library will link in all the object files for the files listed in -`srcs`, even if some contain no symbols referenced by the binary. -This is useful if your code isn't explicitly called by code in -the binary, e.g., if your code registers to receive some callback -provided by some service. - -If alwayslink doesn't work with VS 2017 on Windows, that is due to a -[known issue](https://github.com/bazelbuild/bazel/issues/3949), -please upgrade your VS 2017 to the latest version. - -`conlyopts` - -List of strings; default is `[]` - - Add these options to the C compilation command. -Subject to ["Make variable"](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). - `copts` - -List of strings; default is `[]` - - Add these options to the C/C++ compilation command. -Subject to ["Make variable"](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). - -Each string in this attribute is added in the given order to `COPTS` before -compiling the binary target. The flags take effect only for compiling this target, not -its dependencies, so be careful about header files included elsewhere. -All paths should be relative to the workspace, not to the current package. -This attribute should not be needed outside of `third_party`. - -If the package declares the [feature](/reference/be/functions.html#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings -that consist of a single "Make" variable. - -`cxxopts` - -List of strings; default is `[]` - - Add these options to the C++ compilation command. -Subject to ["Make variable"](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). - `defines` - -List of strings; default is `[]` - - List of defines to add to the compile line of this and all dependent targets. -Subject to ["Make" variable](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). -Each string, which must consist of a single Bourne shell token, -is prepended with `-D` and added to the compile command line to this target, -as well as to every rule that depends on it. Be very careful, since this may have -far-reaching effects -- the defines are added to every target that depends on -this target. When in doubt, add define values to -[`local_defines`](#cc_binary.local_defines) instead. - `hdrs_check` - -String; default is `""` - - Deprecated, no-op. - `implementation_deps` - -List of [labels](/concepts/labels); default is `[]` - - The list of other libraries that the library target depends on. Unlike with -`deps`, the headers and include paths of these libraries (and all their -transitive deps) are only used for compilation of this library, and not libraries that -depend on it. Libraries specified with `implementation_deps` are still linked in -binary targets that depend on this library. - `include_prefix` - -String; default is `""` - - The prefix to add to the paths of the headers of this rule. - -When set, the headers in the `hdrs` attribute of this rule are accessible -at is the value of this attribute prepended to their repository-relative path. - -The prefix in the `strip_include_prefix` attribute is removed before this -prefix is added. - -This attribute is only legal under `third_party`. - - -`includes` - -List of strings; default is `[]` - - List of include dirs to be added to the compile line. -Subject to ["Make variable"](/reference/be/make-variables) substitution. -Each string is prepended with the package path and passed to the C++ toolchain for -expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system -with typical feature definitions will produce -`-isystem path_to_package/include_entry`. -This should only be used for third-party libraries that -do not conform to the Google style of writing #include statements. -Unlike [COPTS](#cc_binary.copts), these flags are added for this rule -and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add -"-I" flags to [COPTS](#cc_binary.copts) instead. - -The added `include` paths will include generated files as well as -files in the source tree. - -`linkopts` - -List of strings; default is `[]` - - See [`cc_binary.linkopts`](/reference/be/c-cpp.html#cc_binary.linkopts). -The `linkopts` attribute is also applied to any target that -depends, directly or indirectly, on this library via `deps` -attributes (or via other attributes that are treated similarly: -the [`malloc`](/reference/be/c-cpp.html#cc_binary.malloc) -attribute of [`cc_binary`](/reference/be/c-cpp.html#cc_binary)). Dependency -linkopts take precedence over dependent linkopts (i.e. dependency linkopts -appear later in the command line). Linkopts specified in -[`--linkopt`](../user-manual.html#flag--linkopt) -take precedence over rule linkopts. - -Note that the `linkopts` attribute only applies -when creating `.so` files or executables, not -when creating `.a` or `.lo` files. -So if the `linkstatic=True` attribute is set, the -`linkopts` attribute has no effect on the creation of -this library, only on other targets which depend on this library. - -Also, it is important to note that "-Wl,-soname" or "-Xlinker -soname" -options are not supported and should never be specified in this attribute. - -The `.so` files produced by `cc_library` -rules are not linked against the libraries that they depend -on. If you're trying to create a shared library for use -outside of the main repository, e.g. for manual use -with `dlopen()` or `LD_PRELOAD`, -it may be better to use a `cc_binary` rule -with the `linkshared=True` attribute. -See [`cc_binary.linkshared`](/reference/be/c-cpp.html#cc_binary.linkshared). - -`linkstamp` - -[Label](/concepts/labels); default is `None` - - Simultaneously compiles and links the specified C++ source file into the final -binary. This trickery is required to introduce timestamp -information into binaries; if we compiled the source file to an -object file in the usual way, the timestamp would be incorrect. -A linkstamp compilation may not include any particular set of -compiler flags and so should not depend on any particular -header, compiler option, or other build variable. -_This option should only be needed in the_ -_`base` package._`linkstatic` - -Boolean; default is `False` - - For [`cc_binary`](/reference/be/c-cpp.html#cc_binary) and -[`cc_test`](/reference/be/c-cpp.html#cc_test): link the binary in static -mode. For `cc_library.link_static`: see below. - -By default this option is on for `cc_binary` and off for the rest. - -If enabled and this is a binary or test, this option tells the build tool to link in -`.a`'s instead of `.so`'s for user libraries whenever possible. -System libraries such as libc (but _not_ the C/C++ runtime libraries, -see below) are still linked dynamically, as are libraries for which -there is no static library. So the resulting executable will still be dynamically -linked, hence only _mostly_ static. - -There are really three different ways to link an executable: - -- STATIC with fully\_static\_link feature, in which everything is linked statically; - e.g. " `gcc -static foo.o libbar.a libbaz.a -lm`". - - - This mode is enabled by specifying `fully_static_link` in the - [`features`](/reference/be/common-definitions#features) attribute. -- STATIC, in which all user libraries are linked statically (if a static - version is available), but where system libraries (excluding C/C++ runtime libraries) - are linked dynamically, e.g. " `gcc foo.o libfoo.a libbaz.a -lm`". - - - This mode is enabled by specifying `linkstatic=True`. -- DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is - available), e.g. " `gcc foo.o libfoo.so libbaz.so -lm`". - - - This mode is enabled by specifying `linkstatic=False`. - -If the `linkstatic` attribute or `fully_static_link` in -`features` is used outside of `//third_party` -please include a comment near the rule to explain why. - -The `linkstatic` attribute has a different meaning if used on a -[`cc_library()`](/reference/be/c-cpp.html#cc_library) rule. -For a C++ library, `linkstatic=True` indicates that only -static linking is allowed, so no `.so` will be produced. linkstatic=False does -not prevent static libraries from being created. The attribute is meant to control the -creation of dynamic libraries. - -There should be very little code built with `linkstatic=False` in production. -If `linkstatic=False`, then the build tool will create symlinks to -depended-upon shared libraries in the `*.runfiles` area. - -`local_defines` - -List of strings; default is `[]` - - List of defines to add to the compile line. -Subject to ["Make" variable](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). -Each string, which must consist of a single Bourne shell token, -is prepended with `-D` and added to the compile command line for this target, -but not to its dependents. Unlike `defines`, the defines are only added to the -compile command line for this target. - `module_interfaces` - -List of [labels](/concepts/labels); default is `[]` - - The list of files are regarded as C++20 Modules Interface. - -C++ Standard has no restriction about module interface file extension - -- Clang use cppm -- GCC can use any source file extension -- MSVC use ixx - -The use is guarded by the flag -`--experimental_cpp_modules`. - -`strip_include_prefix` - -String; default is `""` - - The prefix to strip from the paths of the headers of this rule. - -When set, the headers in the `hdrs` attribute of this rule are accessible -at their path with this prefix cut off. - -If it's a relative path, it's taken as a package-relative one. If it's an absolute one, -it's understood as a repository-relative path. - -The prefix in the `include_prefix` attribute is added after this prefix is -stripped. - -This attribute is only legal under `third_party`. - - -`textual_hdrs` - -List of [labels](/concepts/labels); default is `[]` - - The list of header files published by -this library to be textually included by sources in dependent rules. - -This is the location for declaring header files that cannot be compiled on their own; -that is, they always need to be textually included by other source files to build valid -code. - -`win_def_file` - -[Label](/concepts/labels); default is `None` - - The Windows DEF file to be passed to linker. - -This attribute should only be used when Windows is the target platform. -It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. - -## cc\_shared\_library - -[View rule sourceopen\_in\_new](https://github.com/bazelbuild/rules_cc/blob/master/cc/private/rules_impl/cc_shared_library.bzl) - -``` -cc_shared_library(name, deps, additional_linker_inputs, aspect_hints, compatible_with, deprecation, dynamic_deps, exec_compatible_with, exec_group_compatible_with, exec_properties, exports_filter, features, package_metadata, restricted_to, roots, shared_lib_name, static_deps, tags, target_compatible_with, testonly, toolchains, user_link_flags, visibility, win_def_file) -``` - -It produces a shared library. - -#### Example +#### Example ``` cc_shared_library( @@ -1455,7 +536,6 @@ cc_library( srcs = ["baz.cc"], hdrs = ["baz.h"], ) - ``` In the example `foo_shared` statically links `foo` @@ -1507,7 +587,7 @@ A third way is to tag the culprit `cc_library` with `LINKABLE_MORE_THAN_ONCE` but this fix should be rare and you should absolutely make sure that the `cc_library` is indeed safe to link more than once. -##### ``'//foo:foo' is already linked statically in '//bar:bar' but not exported` `` +##### `` '//foo:foo' is already linked statically in '//bar:bar' but not exported` `` This means that a library in the transitive closure of your `deps` is reachable without going through one of the `cc_shared_library` dependencies but is already @@ -1517,7 +597,7 @@ exported. The solution is to export it from the `cc_shared_library` dependency or pull out a third `cc_shared_library` that exports it. -##### `Do not place libraries which only contain a precompiled dynamic library in deps. ` +##### `Do not place libraries which only contain a precompiled dynamic library in deps.` If you have a precompiled dynamic library, this doesn't need to and cannot be linked statically into the current `cc_shared_library` target that you are @@ -1536,135 +616,18 @@ dependency or make sure that the `exports_filter` doesn't catch this target. ### Arguments -Attributes`name` - -[Name](/concepts/labels#target-names); required - -A unique name for this target. - -`deps` - -List of [labels](/concepts/labels); default is `[]` - - Top level libraries that will unconditionally be statically linked into the shared library -after being whole-archived. - -Any transitive library dependency of these direct deps will be linked into this shared -library as long as they have not already been linked by a `cc_shared_library` -in `dynamic_deps`. - -During analysis, the rule implementation will consider any target listed in -`deps` as being exported by the shared library in order to give errors when -multiple `cc_shared_libraries` export the same targets. The rule implementation -does not take care of informing the linker about which symbols should be exported by the -shared object. The user should take care of this via linker scripts or visibility -declarations in the source code. - -The implementation will also trigger errors whenever the same library is linked statically -into more than one `cc_shared_library`. This can be avoided by adding -`"LINKABLE_MORE_THAN_ONCE"` to the `cc_library.tags` or by listing -the \`cc\_library\` as an export of one of the shared libraries so that one can be made a -`dynamic_dep` of the other. - -`additional_linker_inputs` - -List of [labels](/concepts/labels); default is `[]` - - Any additional files that you may want to pass to the linker, for example, linker scripts. -You have to separately pass any linker flags that the linker needs in order to be aware -of this file. You can do so via the `user_link_flags` attribute. - `dynamic_deps` - -List of [labels](/concepts/labels); default is `[]` - - These are other `cc_shared_library` dependencies the current target depends on. - -The `cc_shared_library` implementation will use the list of -`dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the -current target's `dynamic_deps`) to decide which `cc_libraries` in -the transitive `deps` should not be linked in because they are already provided -by a different `cc_shared_library`. - -`exports_filter` - -List of strings; default is `[]` - - This attribute contains a list of targets that are claimed to be exported by the current -shared library. - -Any target `deps` is already understood to be exported by the shared library. -This attribute should be used to list any targets that are exported by the shared library -but are transitive dependencies of `deps`. - -Note that this attribute is not actually adding a dependency edge to those targets, the -dependency edge should instead be created by `deps`.The entries in this -attribute are just strings. Keep in mind that when placing a target in this attribute, -this is considered a claim that the shared library exports the symbols from that target. -The `cc_shared_library` logic doesn't actually handle telling the linker which -symbols should be exported. - -The following syntax is allowed: - -`//foo:__pkg__` to account for any target in foo/BUILD - -`//foo:__subpackages__` to account for any target in foo/BUILD or any other -package below foo/ like foo/bar/BUILD - -`roots` - -List of [labels](/concepts/labels); default is `[]` - -`shared_lib_name` - -String; default is `""` - - By default cc\_shared\_library will use a name for the shared library output file based on -the target's name and the platform. This includes an extension and sometimes a prefix. -Sometimes you may not want the default name, for example, when loading C++ shared libraries -for Python the default lib\* prefix is often not desired, in which case you can use this -attribute to choose a custom name. - `static_deps` - -List of strings; default is `[]` - -`user_link_flags` - -List of strings; default is `[]` - - Any additional flags that you may want to pass to the linker. For example, to make the -linker aware of a linker script passed via additional\_linker\_inputs you can use the -following: - -```lang-starlark - - cc_shared_library( - name = "foo_shared", - additional_linker_inputs = select({ - "//src/conditions:linux": [ - ":foo.lds", - ":additional_script.txt", - ], - "//conditions:default": []}), - user_link_flags = select({ - "//src/conditions:linux": [ - "-Wl,-rpath,kittens", - "-Wl,--version-script=$(location :foo.lds)", - "-Wl,--script=$(location :additional_script.txt)", - ], - "//conditions:default": []}), - ... - ) - -``` - -`win_def_file` - -[Label](/concepts/labels); default is `None` - - The Windows DEF file to be passed to linker. - -This attribute should only be used when Windows is the target platform. -It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. +| Attributes | | +| --- | --- | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](/concepts/labels); default is `[]` Top level libraries that will unconditionally be statically linked into the shared library after being whole-archived. Any transitive library dependency of these direct deps will be linked into this shared library as long as they have not already been linked by a `cc_shared_library` in `dynamic_deps`. During analysis, the rule implementation will consider any target listed in `deps` as being exported by the shared library in order to give errors when multiple `cc_shared_libraries` export the same targets. The rule implementation does not take care of informing the linker about which symbols should be exported by the shared object. The user should take care of this via linker scripts or visibility declarations in the source code. The implementation will also trigger errors whenever the same library is linked statically into more than one `cc_shared_library`. This can be avoided by adding `"LINKABLE_MORE_THAN_ONCE"` to the `cc_library.tags` or by listing the `cc\_library` as an export of one of the shared libraries so that one can be made a `dynamic_dep` of the other. | +| `additional_linker_inputs` | List of [labels](/concepts/labels); default is `[]` Any additional files that you may want to pass to the linker, for example, linker scripts. You have to separately pass any linker flags that the linker needs in order to be aware of this file. You can do so via the `user_link_flags` attribute. | +| `dynamic_deps` | List of [labels](/concepts/labels); default is `[]` These are other `cc_shared_library` dependencies the current target depends on. The `cc_shared_library` implementation will use the list of `dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the current target's `dynamic_deps`) to decide which `cc_libraries` in the transitive `deps` should not be linked in because they are already provided by a different `cc_shared_library`. | +| `exports_filter` | List of strings; default is `[]` This attribute contains a list of targets that are claimed to be exported by the current shared library. Any target `deps` is already understood to be exported by the shared library. This attribute should be used to list any targets that are exported by the shared library but are transitive dependencies of `deps`. Note that this attribute is not actually adding a dependency edge to those targets, the dependency edge should instead be created by `deps`.The entries in this attribute are just strings. Keep in mind that when placing a target in this attribute, this is considered a claim that the shared library exports the symbols from that target. The `cc_shared_library` logic doesn't actually handle telling the linker which symbols should be exported. The following syntax is allowed: `//foo:__pkg__` to account for any target in foo/BUILD `//foo:__subpackages__` to account for any target in foo/BUILD or any other package below foo/ like foo/bar/BUILD | +| `roots` | List of [labels](/concepts/labels); default is `[]` | +| `shared_lib_name` | String; default is `""` By default cc\_shared\_library will use a name for the shared library output file based on the target's name and the platform. This includes an extension and sometimes a prefix. Sometimes you may not want the default name, for example, when loading C++ shared libraries for Python the default lib\* prefix is often not desired, in which case you can use this attribute to choose a custom name. | +| `static_deps` | List of strings; default is `[]` | +| `user_link_flags` | List of strings; default is `[]` Any additional flags that you may want to pass to the linker. For example, to make the linker aware of a linker script passed via additional\_linker\_inputs you can use the following: ``` cc_shared_library( name = "foo_shared", additional_linker_inputs = select({ "//src/conditions:linux": [ ":foo.lds", ":additional_script.txt", ], "//conditions:default": []}), user_link_flags = select({ "//src/conditions:linux": [ "-Wl,-rpath,kittens", "-Wl,--version-script=$(location :foo.lds)", "-Wl,--script=$(location :additional_script.txt)", ], "//conditions:default": []}), ... ) ``` | +| `win_def_file` | [Label](/concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | ## cc\_static\_library @@ -1674,7 +637,7 @@ It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k cc_static_library(name, deps, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility) ``` - Produces a static library from a list of targets and their transitive dependencies. +Produces a static library from a list of targets and their transitive dependencies. The resulting static library contains the object files of the targets listed in `deps` as well as their transitive dependencies, with preference given to @@ -1710,31 +673,19 @@ The auto-configured C++ toolchains shipped with Bazel support the `symbol_check` feature on all platforms. Custom toolchains can add support for it in one of two ways: -- Implementing the `ACTION_NAMES.validate_static_library` action and - enabling it with the `symbol_check` feature. The tool set in the action is - invoked with two arguments, the static library to check for duplicate symbols and the - path of a file that must be created if the check passes. -- Having the `symbol_check` feature add archiver flags that cause the - action creating the static library to fail on duplicate symbols. +* Implementing the `ACTION_NAMES.validate_static_library` action and + enabling it with the `symbol_check` feature. The tool set in the action is + invoked with two arguments, the static library to check for duplicate symbols and the + path of a file that must be created if the check passes. +* Having the `symbol_check` feature add archiver flags that cause the + action creating the static library to fail on duplicate symbols. ### Arguments -Attributes`name` - -[Name](/concepts/labels#target-names); required - -A unique name for this target. - -`deps` - -List of [labels](/concepts/labels); default is `[]` - - The list of targets to combine into a static library, including all their transitive -dependencies. - -Dependencies that do not provide any object files are not included in the static -library, but their labels are collected in the file provided by the -`linkdeps` output group. +| Attributes | | +| --- | --- | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](/concepts/labels); default is `[]` The list of targets to combine into a static library, including all their transitive dependencies. Dependencies that do not provide any object files are not included in the static library, but their labels are collected in the file provided by the `linkdeps` output group. | ## cc\_test @@ -1747,428 +698,55 @@ cc_test(name, deps, srcs, data, additional_compiler_inputs, additional_linker_in A `cc_test()` rule compiles a test. Here, a test is a binary wrapper around some testing code. -_By default, C++ tests are dynamically linked._ - +*By default, C++ tests are dynamically linked.* To statically link a unit test, specify -[`linkstatic=True`](/reference/be/c-cpp.html#cc_binary.linkstatic). +[`linkstatic=True`](/reference/be/c-cpp#cc_binary.linkstatic). It would probably be good to comment why your test needs `linkstatic`; this is probably not obvious. #### Implicit output targets -- `name.stripped` (only built if explicitly requested): A stripped - version of the binary. `strip -g` is run on the binary to remove debug - symbols. Additional strip options can be provided on the command line using - `--stripopt=-foo`. -- `name.dwp` (only built if explicitly requested): If - [Fission](https://gcc.gnu.org/wiki/DebugFission) is enabled: a debug - information package file suitable for debugging remotely deployed binaries. Else: an - empty file. +* `name.stripped` (only built if explicitly requested): A stripped + version of the binary. `strip -g` is run on the binary to remove debug + symbols. Additional strip options can be provided on the command line using + `--stripopt=-foo`. +* `name.dwp` (only built if explicitly requested): If + [Fission](https://gcc.gnu.org/wiki/DebugFission) is enabled: a debug + information package file suitable for debugging remotely deployed binaries. Else: an + empty file. -See the [cc\_binary()](/reference/be/c-cpp.html#cc_binary_args) arguments, except that +See the [cc\_binary()](/reference/be/c-cpp#cc_binary_args) arguments, except that the `stamp` argument is set to 0 by default for tests and that `cc_test` has extra [attributes common to all test rules (\*\_test)](/reference/be/common-definitions#common-attributes-tests). ### Arguments -Attributes`name` - -[Name](/concepts/labels#target-names); required - -A unique name for this target. - -`deps` - -List of [labels](/concepts/labels); default is `[]` - - The list of other libraries to be linked in to the binary target. - -These can be `cc_library` or `objc_library` -targets. - -It is also allowed to -put linker scripts (.lds) into deps, and reference them in -[`linkopts`](#cc_binary.linkopts), -but please consider -[`additional_linker_inputs`](#cc_binary.additional_linker_inputs) -for that use case. - `srcs` - -List of [labels](/concepts/labels); default is `[]` - - The list of C and C++ files that are processed to create the library target. -These are C/C++ source and header files, either non-generated (normal source -code) or generated. - -All `.cc`, `.c`, and `.cpp` files will -be compiled. These might be generated files: if a named file is in -the `outs` of some other rule, this `cc_library` -will automatically depend on that other rule. - -Pure assembler files (.s, .asm) are not preprocessed and are typically built using -the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built -using the C/C++ compiler. - -A `.h` file will not be compiled, but will be available for -inclusion by sources in this rule. Both `.cc` and -`.h` files can directly include headers listed in -these `srcs` or in the `hdrs` of this rule or any -rule listed in the `deps` argument. - -All `#include` d files must be mentioned in the -`hdrs` attribute of this or referenced `cc_library` -rules, or they should be listed in `srcs` if they are private -to this library. See ["Header inclusion checking"](#hdrs) for -a more detailed description. - -`.so`, `.lo`, and `.a` files are -pre-compiled files. Your library might have these as -`srcs` if it uses third-party code for which we don't -have source code. - -If the `srcs` attribute includes the label of another rule, -`cc_library` will use the output files of that rule as source files to -compile. This is useful for one-off generation of source code (for more than occasional -use, it's better to implement a Starlark rule class and use the `cc_common` -API) - -Permitted `srcs` file types: - -- C and C++ source files: `.c`, `.cc`, `.cpp`, - `.cxx`, `.c++`, `.C` -- C and C++ header files: `.h`, `.hh`, `.hpp`, - `.hxx`, `.inc`, `.inl`, `.H` -- Assembler with C preprocessor: `.S` -- Archive: `.a`, `.pic.a` -- "Always link" library: `.lo`, `.pic.lo` -- Shared library, versioned or unversioned: `.so`, - `.so.version` -- Object file: `.o`, `.pic.o` - -... and any rules that produce those files (e.g. `cc_embed_data`). -Different extensions denote different programming languages in -accordance with gcc convention. - -`data` - -List of [labels](/concepts/labels); default is `[]` - - The list of files needed by this library at runtime. - -See general comments about `data` -at [Typical attributes defined by\ -most build rules](/reference/be/common-definitions#typical-attributes). - -If a `data` is the name of a generated file, then this -`cc_library` rule automatically depends on the generating -rule. - -If a `data` is a rule name, then this -`cc_library` rule automatically depends on that rule, -and that rule's `outs` are automatically added to -this `cc_library`'s data files. - -Your C++ code can access these data files like so: - -```lang-starlark - - const std::string path = devtools_build::GetDataDependencyFilepath( - "my/test/data/file"); - -``` - -`additional_compiler_inputs` - -List of [labels](/concepts/labels); default is `[]` - - Any additional files you might want to pass to the compiler command line, such as sanitizer -ignorelists, for example. Files specified here can then be used in copts with the -$(location) function. - `additional_linker_inputs` - -List of [labels](/concepts/labels); default is `[]` - - Dependencies that are only made available to the C++ linker command. - -Unlike `deps`, which is conceptually made for both compilation and -linking dependencies, `additional_linker_inputs` is specifically -made for only the latter, and signals a dependency that is required only for -linking (for example, files that are referenced in `linkopts`). - -For example, compiled Windows .res files can be provided here to be embedded in -the binary target. - -`conlyopts` - -List of strings; default is `[]` - - Add these options to the C compilation command. -Subject to ["Make variable"](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). - `copts` - -List of strings; default is `[]` - - Add these options to the C/C++ compilation command. -Subject to ["Make variable"](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). - -Each string in this attribute is added in the given order to `COPTS` before -compiling the binary target. The flags take effect only for compiling this target, not -its dependencies, so be careful about header files included elsewhere. -All paths should be relative to the workspace, not to the current package. -This attribute should not be needed outside of `third_party`. - -If the package declares the [feature](/reference/be/functions.html#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings -that consist of a single "Make" variable. - -`cxxopts` - -List of strings; default is `[]` - - Add these options to the C++ compilation command. -Subject to ["Make variable"](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). - `defines` - -List of strings; default is `[]` - - List of defines to add to the compile line of this and all dependent targets. -Subject to ["Make" variable](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). -Each string, which must consist of a single Bourne shell token, -is prepended with `-D` and added to the compile command line to this target, -as well as to every rule that depends on it. Be very careful, since this may have -far-reaching effects -- the defines are added to every target that depends on -this target. When in doubt, add define values to -[`local_defines`](#cc_binary.local_defines) instead. - `dynamic_deps` - -List of [labels](/concepts/labels); default is `[]` - - These are other `cc_shared_library` dependencies the current target depends on. - -The `cc_shared_library` implementation will use the list of -`dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the -current target's `dynamic_deps`) to decide which `cc_libraries` in -the transitive `deps` should not be linked in because they are already provided -by a different `cc_shared_library`. - - -`hdrs_check` - -String; default is `""` - - Deprecated, no-op. - `includes` - -List of strings; default is `[]` - - List of include dirs to be added to the compile line. -Subject to ["Make variable"](/reference/be/make-variables) substitution. -Each string is prepended with the package path and passed to the C++ toolchain for -expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system -with typical feature definitions will produce -`-isystem path_to_package/include_entry`. -This should only be used for third-party libraries that -do not conform to the Google style of writing #include statements. -Unlike [COPTS](#cc_binary.copts), these flags are added for this rule -and every rule that depends on it. (Note: not the rules it depends upon!) Be -very careful, since this may have far-reaching effects. When in doubt, add -"-I" flags to [COPTS](#cc_binary.copts) instead. - -The added `include` paths will include generated files as well as -files in the source tree. - -`link_extra_lib` - -[Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:link_extra_lib"` - - Control linking of extra libraries. - -By default, C++ binaries are linked against `@bazel_tools//tools/cpp:link_extra_lib`, -which by default depends on the label flag `@bazel_tools//tools/cpp:link_extra_libs`. -Without setting the flag, this library is empty by default. Setting the label flag -allows linking optional dependencies, such as overrides for weak symbols, interceptors -for shared library functions, or special runtime libraries (for malloc replacements, -prefer `malloc` or `--custom_malloc`). Setting this attribute to -`None` disables this behaviour. - -`linkopts` - -List of strings; default is `[]` - - Add these flags to the C++ linker command. -Subject to ["Make" variable](make-variables.html) substitution, -[Bourne shell tokenization](common-definitions.html#sh-tokenization) and -[label expansion](common-definitions.html#label-expansion). -Each string in this attribute is added to `LINKOPTS` before -linking the binary target. - -Each element of this list that does not start with `$` or `-` is -assumed to be the label of a target in `deps`. The -list of files generated by that target is appended to the linker -options. An error is reported if the label is invalid, or is -not declared in `deps`. - -`linkshared` - -Boolean; default is `False` - - Create a shared library. -To enable this attribute, include `linkshared=True` in your rule. By default -this option is off. - -The presence of this flag means that linking occurs with the `-shared` flag -to `gcc`, and the resulting shared library is suitable for loading into for -example a Java program. However, for build purposes it will never be linked into the -dependent binary, as it is assumed that shared libraries built with a -[cc\_binary](#cc_binary) rule are only loaded manually by other programs, so -it should not be considered a substitute for the [cc\_library](#cc_library) -rule. For sake of scalability we recommend avoiding this approach altogether and -simply letting `java_library` depend on `cc_library` rules -instead. - -If you specify both `linkopts=['-static']` and `linkshared=True`, -you get a single completely self-contained unit. If you specify both -`linkstatic=True` and `linkshared=True`, you get a single, mostly -self-contained unit. - -`linkstatic` - -Boolean; default is `False` - - For [`cc_binary`](/reference/be/c-cpp.html#cc_binary) and -[`cc_test`](/reference/be/c-cpp.html#cc_test): link the binary in static -mode. For `cc_library.link_static`: see below. - -By default this option is on for `cc_binary` and off for the rest. - -If enabled and this is a binary or test, this option tells the build tool to link in -`.a`'s instead of `.so`'s for user libraries whenever possible. -System libraries such as libc (but _not_ the C/C++ runtime libraries, -see below) are still linked dynamically, as are libraries for which -there is no static library. So the resulting executable will still be dynamically -linked, hence only _mostly_ static. - -There are really three different ways to link an executable: - -- STATIC with fully\_static\_link feature, in which everything is linked statically; - e.g. " `gcc -static foo.o libbar.a libbaz.a -lm`". - - - This mode is enabled by specifying `fully_static_link` in the - [`features`](/reference/be/common-definitions#features) attribute. -- STATIC, in which all user libraries are linked statically (if a static - version is available), but where system libraries (excluding C/C++ runtime libraries) - are linked dynamically, e.g. " `gcc foo.o libfoo.a libbaz.a -lm`". - - - This mode is enabled by specifying `linkstatic=True`. -- DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is - available), e.g. " `gcc foo.o libfoo.so libbaz.so -lm`". - - - This mode is enabled by specifying `linkstatic=False`. - -If the `linkstatic` attribute or `fully_static_link` in -`features` is used outside of `//third_party` -please include a comment near the rule to explain why. - -The `linkstatic` attribute has a different meaning if used on a -[`cc_library()`](/reference/be/c-cpp.html#cc_library) rule. -For a C++ library, `linkstatic=True` indicates that only -static linking is allowed, so no `.so` will be produced. linkstatic=False does -not prevent static libraries from being created. The attribute is meant to control the -creation of dynamic libraries. - -There should be very little code built with `linkstatic=False` in production. -If `linkstatic=False`, then the build tool will create symlinks to -depended-upon shared libraries in the `*.runfiles` area. - -`local_defines` - -List of strings; default is `[]` - - List of defines to add to the compile line. -Subject to ["Make" variable](/reference/be/make-variables) substitution and -[Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). -Each string, which must consist of a single Bourne shell token, -is prepended with `-D` and added to the compile command line for this target, -but not to its dependents. Unlike `defines`, the defines are only added to the -compile command line for this target. - `malloc` - -[Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:malloc"` - - Override the default dependency on malloc. - -By default, C++ binaries are linked against `//tools/cpp:malloc`, -which is an empty library so the binary ends up using libc malloc. -This label must refer to a `cc_library`. If compilation is for a non-C++ -rule, this option has no effect. The value of this attribute is ignored if -`linkshared=True` is specified. - -`module_interfaces` - -List of [labels](/concepts/labels); default is `[]` - - The list of files are regarded as C++20 Modules Interface. - -C++ Standard has no restriction about module interface file extension - -- Clang use cppm -- GCC can use any source file extension -- MSVC use ixx - -The use is guarded by the flag -`--experimental_cpp_modules`. - -`nocopts` - -String; default is `""` - - Remove matching options from the C++ compilation command. -Subject to ["Make" variable](/reference/be/make-variables) substitution. -The value of this attribute is interpreted as a regular expression. -Any preexisting `COPTS` that match this regular expression -(including values explicitly specified in the rule's [copts](#cc_binary.copts) attribute) -will be removed from `COPTS` for purposes of compiling this rule. -This attribute should not be needed or used -outside of `third_party`. The values are not preprocessed -in any way other than the "Make" variable substitution. - `reexport_deps` - -List of [labels](/concepts/labels); default is `[]` - -`stamp` - -Integer; default is `0` - - Whether to encode build information into the binary. Possible values: - -- `stamp = 1`: Always stamp the build information into the binary, even in - [`--nostamp`](/docs/user-manual#flag--stamp) builds. **This** - **setting should be avoided**, since it potentially kills remote caching for the - binary and any downstream actions that depend on it. - -- `stamp = 0`: Always replace build information by constant values. This - gives good build result caching. - -- `stamp = -1`: Embedding of build information is controlled by the - [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. - - -Stamped binaries are _not_ rebuilt unless their dependencies change. - -`win_def_file` - -[Label](/concepts/labels); default is `None` - - The Windows DEF file to be passed to linker. - -This attribute should only be used when Windows is the target platform. -It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. +| Attributes | | +| --- | --- | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | +| `deps` | List of [labels](/concepts/labels); default is `[]` The list of other libraries to be linked in to the binary target. These can be `cc_library` or `objc_library` targets. It is also allowed to put linker scripts (.lds) into deps, and reference them in [`linkopts`](#cc_binary.linkopts), but please consider [`additional_linker_inputs`](#cc_binary.additional_linker_inputs) for that use case. | +| `srcs` | List of [labels](/concepts/labels); default is `[]` The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated. All `.cc`, `.c`, and `.cpp` files will be compiled. These might be generated files: if a named file is in the `outs` of some other rule, this `cc_library` will automatically depend on that other rule. Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built using the C/C++ compiler. A `.h` file will not be compiled, but will be available for inclusion by sources in this rule. Both `.cc` and `.h` files can directly include headers listed in these `srcs` or in the `hdrs` of this rule or any rule listed in the `deps` argument. All `#include`d files must be mentioned in the `hdrs` attribute of this or referenced `cc_library` rules, or they should be listed in `srcs` if they are private to this library. See ["Header inclusion checking"](#hdrs) for a more detailed description. `.so`, `.lo`, and `.a` files are pre-compiled files. Your library might have these as `srcs` if it uses third-party code for which we don't have source code. If the `srcs` attribute includes the label of another rule, `cc_library` will use the output files of that rule as source files to compile. This is useful for one-off generation of source code (for more than occasional use, it's better to implement a Starlark rule class and use the `cc_common` API) Permitted `srcs` file types: * C and C++ source files: `.c`, `.cc`, `.cpp`, `.cxx`, `.c++`, `.C` * C and C++ header files: `.h`, `.hh`, `.hpp`, `.hxx`, `.inc`, `.inl`, `.H` * Assembler with C preprocessor: `.S` * Archive: `.a`, `.pic.a` * "Always link" library: `.lo`, `.pic.lo` * Shared library, versioned or unversioned: `.so`, `.so.version` * Object file: `.o`, `.pic.o` ... and any rules that produce those files (e.g. `cc_embed_data`). Different extensions denote different programming languages in accordance with gcc convention. | +| `data` | List of [labels](/concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](/reference/be/common-definitions#typical-attributes). If a `data` is the name of a generated file, then this `cc_library` rule automatically depends on the generating rule. If a `data` is a rule name, then this `cc_library` rule automatically depends on that rule, and that rule's `outs` are automatically added to this `cc_library`'s data files. Your C++ code can access these data files like so: ``` const std::string path = devtools_build::GetDataDependencyFilepath( "my/test/data/file"); ``` | +| `additional_compiler_inputs` | List of [labels](/concepts/labels); default is `[]` Any additional files you might want to pass to the compiler command line, such as sanitizer ignorelists, for example. Files specified here can then be used in copts with the $(location) function. | +| `additional_linker_inputs` | List of [labels](/concepts/labels); default is `[]` Dependencies that are only made available to the C++ linker command. Unlike `deps`, which is conceptually made for both compilation and linking dependencies, `additional_linker_inputs` is specifically made for only the latter, and signals a dependency that is required only for linking (for example, files that are referenced in `linkopts`). For example, compiled Windows .res files can be provided here to be embedded in the binary target. | +| `conlyopts` | List of strings; default is `[]` Add these options to the C compilation command. Subject to ["Make variable"](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). | +| `copts` | List of strings; default is `[]` Add these options to the C/C++ compilation command. Subject to ["Make variable"](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string in this attribute is added in the given order to `COPTS` before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. This attribute should not be needed outside of `third_party`. If the package declares the [feature](/reference/be/functions#package.features) `no_copts_tokenization`, Bourne shell tokenization applies only to strings that consist of a single "Make" variable. | +| `cxxopts` | List of strings; default is `[]` Add these options to the C++ compilation command. Subject to ["Make variable"](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). | +| `defines` | List of strings; default is `[]` List of defines to add to the compile line of this and all dependent targets. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects -- the defines are added to every target that depends on this target. When in doubt, add define values to [`local_defines`](#cc_binary.local_defines) instead. | +| `dynamic_deps` | List of [labels](/concepts/labels); default is `[]` These are other `cc_shared_library` dependencies the current target depends on. The `cc_shared_library` implementation will use the list of `dynamic_deps` (transitively, i.e. also the `dynamic_deps` of the current target's `dynamic_deps`) to decide which `cc_libraries` in the transitive `deps` should not be linked in because they are already provided by a different `cc_shared_library`. | +| `hdrs_check` | String; default is `""` Deprecated, no-op. | +| `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](/reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include\_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The added `include` paths will include generated files as well as files in the source tree. | +| `link_extra_lib` | [Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:link_extra_lib"` Control linking of extra libraries. By default, C++ binaries are linked against `@bazel_tools//tools/cpp:link_extra_lib`, which by default depends on the label flag `@bazel_tools//tools/cpp:link_extra_libs`. Without setting the flag, this library is empty by default. Setting the label flag allows linking optional dependencies, such as overrides for weak symbols, interceptors for shared library functions, or special runtime libraries (for malloc replacements, prefer `malloc` or `--custom_malloc`). Setting this attribute to `None` disables this behaviour. | +| `linkopts` | List of strings; default is `[]` Add these flags to the C++ linker command. Subject to ["Make" variable](make-variables) substitution, [Bourne shell tokenization](common-definitions#sh-tokenization) and [label expansion](common-definitions#label-expansion). Each string in this attribute is added to `LINKOPTS` before linking the binary target. Each element of this list that does not start with `$` or `-` is assumed to be the label of a target in `deps`. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in `deps`. | +| `linkshared` | Boolean; default is `False` Create a shared library. To enable this attribute, include `linkshared=True` in your rule. By default this option is off. The presence of this flag means that linking occurs with the `-shared` flag to `gcc`, and the resulting shared library is suitable for loading into for example a Java program. However, for build purposes it will never be linked into the dependent binary, as it is assumed that shared libraries built with a [cc\_binary](#cc_binary) rule are only loaded manually by other programs, so it should not be considered a substitute for the [cc\_library](#cc_library) rule. For sake of scalability we recommend avoiding this approach altogether and simply letting `java_library` depend on `cc_library` rules instead. If you specify both `linkopts=['-static']` and `linkshared=True`, you get a single completely self-contained unit. If you specify both `linkstatic=True` and `linkshared=True`, you get a single, mostly self-contained unit. | +| `linkstatic` | Boolean; default is `False` For [`cc_binary`](/reference/be/c-cpp#cc_binary) and [`cc_test`](/reference/be/c-cpp#cc_test): link the binary in static mode. For `cc_library.link_static`: see below. By default this option is on for `cc_binary` and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in `.a`'s instead of `.so`'s for user libraries whenever possible. System libraries such as libc (but *not* the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only *mostly* static. There are really three different ways to link an executable: * STATIC with fully\_static\_link feature, in which everything is linked statically; e.g. "`gcc -static foo.o libbar.a libbaz.a -lm`". This mode is enabled by specifying `fully_static_link` in the [`features`](/reference/be/common-definitions#features) attribute. * STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "`gcc foo.o libfoo.a libbaz.a -lm`". This mode is enabled by specifying `linkstatic=True`. * DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "`gcc foo.o libfoo.so libbaz.so -lm`". This mode is enabled by specifying `linkstatic=False`. If the `linkstatic` attribute or `fully_static_link` in `features` is used outside of `//third_party` please include a comment near the rule to explain why. The `linkstatic` attribute has a different meaning if used on a [`cc_library()`](/reference/be/c-cpp#cc_library) rule. For a C++ library, `linkstatic=True` indicates that only static linking is allowed, so no `.so` will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with `linkstatic=False` in production. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area. | +| `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. Unlike `defines`, the defines are only added to the compile command line for this target. | +| `malloc` | [Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:malloc"` Override the default dependency on malloc. By default, C++ binaries are linked against `//tools/cpp:malloc`, which is an empty library so the binary ends up using libc malloc. This label must refer to a `cc_library`. If compilation is for a non-C++ rule, this option has no effect. The value of this attribute is ignored if `linkshared=True` is specified. | +| `module_interfaces` | List of [labels](/concepts/labels); default is `[]` The list of files are regarded as C++20 Modules Interface. C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx The use is guarded by the flag `--experimental_cpp_modules`. | +| `nocopts` | String; default is `""` Remove matching options from the C++ compilation command. Subject to ["Make" variable](/reference/be/make-variables) substitution. The value of this attribute is interpreted as a regular expression. Any preexisting `COPTS` that match this regular expression (including values explicitly specified in the rule's [copts](#cc_binary.copts) attribute) will be removed from `COPTS` for purposes of compiling this rule. This attribute should not be needed or used outside of `third_party`. The values are not preprocessed in any way other than the "Make" variable substitution. | +| `reexport_deps` | List of [labels](/concepts/labels); default is `[]` | +| `stamp` | Integer; default is `0` Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in [`--nostamp`](/docs/user-manual#flag--stamp) builds. **This setting should be avoided**, since it potentially kills remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives good build result caching. * `stamp = -1`: Embedding of build information is controlled by the [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. Stamped binaries are *not* rebuilt unless their dependencies change. | +| `win_def_file` | [Label](/concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | ## cc\_toolchain @@ -2182,16 +760,12 @@ Represents a C++ toolchain. This rule is responsible for: - - -- Collecting all artifacts needed for C++ actions to run. This is done by - attributes such as `all_files`, `compiler_files`, - `linker_files`, or other attributes ending with `_files`). These are - most commonly filegroups globbing all required files. - -- Generating correct command lines for C++ actions. This is done using - `CcToolchainConfigInfo` provider (details below). - +* Collecting all artifacts needed for C++ actions to run. This is done by + attributes such as `all_files`, `compiler_files`, + `linker_files`, or other attributes ending with `_files`). These are + most commonly filegroups globbing all required files. +* Generating correct command lines for C++ actions. This is done using + `CcToolchainConfigInfo` provider (details below). Use `toolchain_config` attribute to configure the C++ toolchain. See also this @@ -2202,135 +776,29 @@ unnecessarily when invoking `bazel build //...` ### Arguments -Attributes`name` - -[Name](/concepts/labels#target-names); required - -A unique name for this target. - -`all_files` - -[Label](/concepts/labels); required - - Collection of all cc\_toolchain artifacts. These artifacts will be added as inputs to all -rules\_cc related actions (with the exception of actions that are using more precise sets of -artifacts from attributes below). Bazel assumes that `all_files` is a superset -of all other artifact-providing attributes (e.g. linkstamp compilation needs both compile -and link files, so it takes `all_files`). - -This is what `cc_toolchain.files` contains, and this is used by all Starlark -rules using C++ toolchain. - -`ar_files` - -[Label](/concepts/labels); default is `None` - - Collection of all cc\_toolchain artifacts required for archiving actions. - `as_files` - -[Label](/concepts/labels); default is `None` - - Collection of all cc\_toolchain artifacts required for assembly actions. - `compiler_files` - -[Label](/concepts/labels); required - - Collection of all cc\_toolchain artifacts required for compile actions. - `compiler_files_without_includes` - -[Label](/concepts/labels); default is `None` - - Collection of all cc\_toolchain artifacts required for compile actions in case when -input discovery is supported (currently Google-only). - `coverage_files` - -[Label](/concepts/labels); default is `None` - - Collection of all cc\_toolchain artifacts required for coverage actions. If not specified, -all\_files are used. - `dwp_files` - -[Label](/concepts/labels); required - - Collection of all cc\_toolchain artifacts required for dwp actions. - `dynamic_runtime_lib` - -[Label](/concepts/labels); default is `None` - - Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so). - -This will be used when 'static\_link\_cpp\_runtimes' feature is enabled, and we're linking -dependencies dynamically. - -`exec_transition_for_inputs` - -Boolean; default is `False` - - Deprecated. No-op. - `libc_top` - -[Label](/concepts/labels); default is `None` - - A collection of artifacts for libc passed as inputs to compile/linking actions. - `linker_files` - -[Label](/concepts/labels); required - - Collection of all cc\_toolchain artifacts required for linking actions. - `module_map` - -[Label](/concepts/labels); default is `None` - - Module map artifact to be used for modular builds. - `objcopy_files` - -[Label](/concepts/labels); required - - Collection of all cc\_toolchain artifacts required for objcopy actions. - `output_licenses` - -List of strings; default is `[]` - -`static_runtime_lib` - -[Label](/concepts/labels); default is `None` - - Static library artifact for the C++ runtime library (e.g. libstdc++.a). - -This will be used when 'static\_link\_cpp\_runtimes' feature is enabled, and we're linking -dependencies statically. - -`strip_files` - -[Label](/concepts/labels); required - - Collection of all cc\_toolchain artifacts required for strip actions. - `supports_header_parsing` - -Boolean; default is `False` - - Set to True when cc\_toolchain supports header parsing actions. - `supports_param_files` - -Boolean; default is `True` - - Set to True when cc\_toolchain supports using param files for linking actions. - `toolchain_config` - -[Label](/concepts/labels); required - - The label of the rule providing `cc_toolchain_config_info`. - `toolchain_identifier` - -String; default is `""` - - The identifier used to match this cc\_toolchain with the corresponding -crosstool\_config.toolchain. - -Until issue [#5380](https://github.com/bazelbuild/bazel/issues/5380) is fixed -this is the recommended way of associating `cc_toolchain` with -`CROSSTOOL.toolchain`. It will be replaced by the `toolchain_config` -attribute ( [#5380](https://github.com/bazelbuild/bazel/issues/5380)). +| Attributes | | +| --- | --- | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | +| `all_files` | [Label](/concepts/labels); required Collection of all cc\_toolchain artifacts. These artifacts will be added as inputs to all rules\_cc related actions (with the exception of actions that are using more precise sets of artifacts from attributes below). Bazel assumes that `all_files` is a superset of all other artifact-providing attributes (e.g. linkstamp compilation needs both compile and link files, so it takes `all_files`). This is what `cc_toolchain.files` contains, and this is used by all Starlark rules using C++ toolchain. | +| `ar_files` | [Label](/concepts/labels); default is `None` Collection of all cc\_toolchain artifacts required for archiving actions. | +| `as_files` | [Label](/concepts/labels); default is `None` Collection of all cc\_toolchain artifacts required for assembly actions. | +| `compiler_files` | [Label](/concepts/labels); required Collection of all cc\_toolchain artifacts required for compile actions. | +| `compiler_files_without_includes` | [Label](/concepts/labels); default is `None` Collection of all cc\_toolchain artifacts required for compile actions in case when input discovery is supported (currently Google-only). | +| `coverage_files` | [Label](/concepts/labels); default is `None` Collection of all cc\_toolchain artifacts required for coverage actions. If not specified, all\_files are used. | +| `dwp_files` | [Label](/concepts/labels); required Collection of all cc\_toolchain artifacts required for dwp actions. | +| `dynamic_runtime_lib` | [Label](/concepts/labels); default is `None` Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so). This will be used when 'static\_link\_cpp\_runtimes' feature is enabled, and we're linking dependencies dynamically. | +| `exec_transition_for_inputs` | Boolean; default is `False` Deprecated. No-op. | +| `libc_top` | [Label](/concepts/labels); default is `None` A collection of artifacts for libc passed as inputs to compile/linking actions. | +| `linker_files` | [Label](/concepts/labels); required Collection of all cc\_toolchain artifacts required for linking actions. | +| `module_map` | [Label](/concepts/labels); default is `None` Module map artifact to be used for modular builds. | +| `objcopy_files` | [Label](/concepts/labels); required Collection of all cc\_toolchain artifacts required for objcopy actions. | +| `output_licenses` | List of strings; default is `[]` | +| `static_runtime_lib` | [Label](/concepts/labels); default is `None` Static library artifact for the C++ runtime library (e.g. libstdc++.a). This will be used when 'static\_link\_cpp\_runtimes' feature is enabled, and we're linking dependencies statically. | +| `strip_files` | [Label](/concepts/labels); required Collection of all cc\_toolchain artifacts required for strip actions. | +| `supports_header_parsing` | Boolean; default is `False` Set to True when cc\_toolchain supports header parsing actions. | +| `supports_param_files` | Boolean; default is `True` Set to True when cc\_toolchain supports using param files for linking actions. | +| `toolchain_config` | [Label](/concepts/labels); required The label of the rule providing `cc_toolchain_config_info`. | +| `toolchain_identifier` | String; default is `""` The identifier used to match this cc\_toolchain with the corresponding crosstool\_config.toolchain. Until issue [#5380](https://github.com/bazelbuild/bazel/issues/5380) is fixed this is the recommended way of associating `cc_toolchain` with `CROSSTOOL.toolchain`. It will be replaced by the `toolchain_config` attribute ([#5380](https://github.com/bazelbuild/bazel/issues/5380)). | ## fdo\_prefetch\_hints @@ -2343,30 +811,19 @@ fdo_prefetch_hints(name, aspect_hints, compatible_with, deprecation, exec_compat Represents an FDO prefetch hints profile that is either in the workspace. Examples: -```lang-starlark - +``` fdo_prefetch_hints( name = "hints", profile = "//path/to/hints:profile.afdo", ) - ``` ### Arguments -Attributes`name` - -[Name](/concepts/labels#target-names); required - -A unique name for this target. - -`profile` - -[Label](/concepts/labels); required - - Label of the hints profile. The hints file has the .afdo extension -The label can also point to an fdo\_absolute\_path\_profile rule. - +| Attributes | | +| --- | --- | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | +| `profile` | [Label](/concepts/labels); required Label of the hints profile. The hints file has the .afdo extension The label can also point to an fdo\_absolute\_path\_profile rule. | ## fdo\_profile @@ -2379,45 +836,21 @@ fdo_profile(name, aspect_hints, compatible_with, deprecation, exec_compatible_wi Represents an FDO profile that is in the workspace. Example: -```lang-starlark - +``` fdo_profile( name = "fdo", profile = "//path/to/fdo:profile.zip", ) - ``` ### Arguments -Attributes`name` - -[Name](/concepts/labels#target-names); required - -A unique name for this target. - -`memprof_profile` - -[Label](/concepts/labels); default is `None` - - Label of the MemProf profile. The profile is expected to have -either a .profdata extension (for an indexed/symbolized memprof -profile), or a .zip extension for a zipfile containing a memprof.profdata -file. - `profile` - -[Label](/concepts/labels); required - - Label of the FDO profile or a rule which generates it. The FDO file can have one of the -following extensions: .profraw for unindexed LLVM profile, .profdata for indexed LLVM -profile, .zip that holds an LLVM profraw profile, .afdo for AutoFDO profile, .xfdo for -XBinary profile. The label can also point to an fdo\_absolute\_path\_profile rule. - `proto_profile` - -[Label](/concepts/labels); default is `None` - - Label of the protobuf profile. - +| Attributes | | +| --- | --- | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | +| `memprof_profile` | [Label](/concepts/labels); default is `None` Label of the MemProf profile. The profile is expected to have either a .profdata extension (for an indexed/symbolized memprof profile), or a .zip extension for a zipfile containing a memprof.profdata file. | +| `profile` | [Label](/concepts/labels); required Label of the FDO profile or a rule which generates it. The FDO file can have one of the following extensions: .profraw for unindexed LLVM profile, .profdata for indexed LLVM profile, .zip that holds an LLVM profraw profile, .afdo for AutoFDO profile, .xfdo for XBinary profile. The label can also point to an fdo\_absolute\_path\_profile rule. | +| `proto_profile` | [Label](/concepts/labels); default is `None` Label of the protobuf profile. | ## memprof\_profile @@ -2430,33 +863,19 @@ memprof_profile(name, aspect_hints, compatible_with, deprecation, exec_compatibl Represents a MEMPROF profile that is in the workspace. Example: -```lang-starlark - +``` memprof_profile( name = "memprof", profile = "//path/to/memprof:profile.afdo", ) - ``` ### Arguments -Attributes`name` - -[Name](/concepts/labels#target-names); required - -A unique name for this target. - -`profile` - -[Label](/concepts/labels); required - - Label of the MEMPROF profile. The profile is expected to have -either a .profdata extension (for an indexed/symbolized memprof -profile), or a .zip extension for a zipfile containing a memprof.profdata -file. -The label can also point to an fdo\_absolute\_path\_profile rule. - +| Attributes | | +| --- | --- | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | +| `profile` | [Label](/concepts/labels); required Label of the MEMPROF profile. The profile is expected to have either a .profdata extension (for an indexed/symbolized memprof profile), or a .zip extension for a zipfile containing a memprof.profdata file. The label can also point to an fdo\_absolute\_path\_profile rule. | ## propeller\_optimize @@ -2469,33 +888,18 @@ propeller_optimize(name, aspect_hints, cc_profile, compatible_with, deprecation, Represents a Propeller optimization profile in the workspace. Example: -```lang-starlark - +``` propeller_optimize( name = "layout", cc_profile = "//path:cc_profile.txt", ld_profile = "//path:ld_profile.txt" ) - ``` ### Arguments -Attributes`name` - -[Name](/concepts/labels#target-names); required - -A unique name for this target. - -`cc_profile` - -[Label](/concepts/labels); required - - Label of the profile passed to the various compile actions. This file has -the .txt extension. - `ld_profile` - -[Label](/concepts/labels); required - - Label of the profile passed to the link action. This file has -the .txt extension. +| Attributes | | +| --- | --- | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | +| `cc_profile` | [Label](/concepts/labels); required Label of the profile passed to the various compile actions. This file has the .txt extension. | +| `ld_profile` | [Label](/concepts/labels); required Label of the profile passed to the link action. This file has the .txt extension. | \ No newline at end of file diff --git a/reference/be/common-definitions.mdx b/reference/be/common-definitions.mdx index 4c9db5eaf..6cab2c1f0 100644 --- a/reference/be/common-definitions.mdx +++ b/reference/be/common-definitions.mdx @@ -2,21 +2,19 @@ title: 'Common definitions' --- - - This section defines various terms and concepts that are common to many functions or build rules. ## Contents -- [Bourne shell tokenization](#sh-tokenization) -- [Label Expansion](#label-expansion) -- [Typical attributes defined by most build rules](#typical-attributes) -- [Attributes common to all build rules](#common-attributes) -- [Attributes common to all test rules (\*\_test)](#common-attributes-tests) -- [Attributes common to all binary rules (\*\_binary)](#common-attributes-binaries) -- [Configurable attributes](#configurable-attributes) -- [Implicit output targets](#implicit-outputs) +* [Bourne shell tokenization](#sh-tokenization) +* [Label Expansion](#label-expansion) +* [Typical attributes defined by most build rules](#typical-attributes) +* [Attributes common to all build rules](#common-attributes) +* [Attributes common to all test rules (\*\_test)](#common-attributes-tests) +* [Attributes common to all binary rules (\*\_binary)](#common-attributes-binaries) +* [Configurable attributes](#configurable-attributes) +* [Implicit output targets](#implicit-outputs) ## Bourne shell tokenization @@ -44,7 +42,8 @@ expansion: if those strings contain a valid label as a substring, such as `//mypkg:target`, and that label is a declared prerequisite of the current rule, it is expanded into the pathname of the file represented by the -[target](https://bazel.build/reference/glossary#target) `//mypkg:target`. +[target](https://bazel.build/reference/glossary#target) +`//mypkg:target`. Example attributes include `genrule.cmd` and `cc_binary.linkopts`. The details may vary significantly in @@ -58,639 +57,59 @@ specifics. This section describes attributes that are defined by many build rules, but not all. -AttributeDescription`data` - -List of [labels](/concepts/labels); default is `[]` - -Files needed by this rule at runtime. May list file or rule targets. Generally -allows any target. - -The default outputs and runfiles of targets in the `data` attribute -should appear in the `*.runfiles` area of any executable which is -output by or has a runtime dependency on this target. This may include data -files or binaries used when this target's -[`srcs`](#typical.srcs) are executed. See the -[data dependencies](/concepts/dependencies#data-dependencies) -section for more information about how to depend on and use data files. - -New rules should define a `data` attribute if they process -inputs which might use other inputs at runtime. Rules' implementation functions -must also [populate the target's\ -runfiles](https://bazel.build/rules/rules#runfiles) from the outputs and runfiles of any `data` attribute, -as well as runfiles from any dependency attribute which provides either -source code or runtime dependencies. - -`deps` - -List of [labels](/concepts/labels); default is `[]` - -Dependencies for this target. Generally should only list rule targets. (Though -some rules permit files to be listed directly in `deps`, this -should be avoided when possible.) - -Language-specific rules generally limit the listed targets to those with -specific [providers](https://bazel.build/extending/rules#providers). - -The precise semantics of what it means for a target to depend on another using -`deps` are specific to the kind of rule, and the rule-specific -documentation goes into more detail. For rules which process source code, -`deps` generally specifies code dependencies used by the code in -[`srcs`](#typical.srcs). - -Most often, a `deps` dependency is used to allow one module to use -symbols defined in another module written in the same programming language and -separately compiled. Cross-language dependencies are also permitted in many -cases: For example, a `java_library` target may depend on C++ code -in a `cc_library` target, by listing the latter in the -`deps` attribute. See the definition of -[dependencies](/concepts/build-ref#deps) -for more information. - -`licenses` - -List of strings; [nonconfigurable](#configurable-attributes); -default is `["none"]` - -A list of license-type strings to be used for this particular target. - -This is part of a deprecated licensing API that Bazel no longer uses. Don't -use this. - -`srcs` - -List of [labels](/concepts/labels); default is `[]` - -Files processed or included by this rule. Generally lists files directly, but -may list rule targets (like `filegroup` or `genrule`) to -include their default outputs. - -Language-specific rules often require that the listed files have particular -file extensions. +| Attribute | Description | +| --- | --- | +| `data` | List of [labels](/concepts/labels); default is `[]` Files needed by this rule at runtime. May list file or rule targets. Generally allows any target. The default outputs and runfiles of targets in the `data` attribute should appear in the `*.runfiles` area of any executable which is output by or has a runtime dependency on this target. This may include data files or binaries used when this target's [`srcs`](#typical.srcs) are executed. See the [data dependencies](/concepts/dependencies#data-dependencies) section for more information about how to depend on and use data files. New rules should define a `data` attribute if they process inputs which might use other inputs at runtime. Rules' implementation functions must also [populate the target's runfiles](https://bazel.build/rules/rules#runfiles) from the outputs and runfiles of any `data` attribute, as well as runfiles from any dependency attribute which provides either source code or runtime dependencies. | +| `deps` | List of [labels](/concepts/labels); default is `[]` Dependencies for this target. Generally should only list rule targets. (Though some rules permit files to be listed directly in `deps`, this should be avoided when possible.) Language-specific rules generally limit the listed targets to those with specific [providers](https://bazel.build/extending/rules#providers). The precise semantics of what it means for a target to depend on another using `deps` are specific to the kind of rule, and the rule-specific documentation goes into more detail. For rules which process source code, `deps` generally specifies code dependencies used by the code in [`srcs`](#typical.srcs). Most often, a `deps` dependency is used to allow one module to use symbols defined in another module written in the same programming language and separately compiled. Cross-language dependencies are also permitted in many cases: For example, a `java_library` target may depend on C++ code in a `cc_library` target, by listing the latter in the `deps` attribute. See the definition of [dependencies](/concepts/build-ref#deps) for more information. | +| `licenses` | List of strings; [nonconfigurable](#configurable-attributes); default is `["none"]` A list of license-type strings to be used for this particular target. This is part of a deprecated licensing API that Bazel no longer uses. Don't use this. | +| `srcs` | List of [labels](/concepts/labels); default is `[]` Files processed or included by this rule. Generally lists files directly, but may list rule targets (like `filegroup` or `genrule`) to include their default outputs. Language-specific rules often require that the listed files have particular file extensions. | ## Attributes common to all build rules This section describes attributes that are implicitly added to all build rules. -AttributeDescription`aspect_hints` - -List of [labels](/concepts/labels); default is `[]` - -A list of arbitrary labels which is exposed to [aspects](/extending/aspects) (in -particular - aspects invoked by this rule's reverse dependencies), but isn't exposed to this rule's -own implementation. Consult documentation for language-specific rule sets for details about what -effect a particular aspect hint would have. - -You could think of an aspect hint as a richer alternative to a [tag](#common.tags): -while a tag conveys only a boolean state (the tag is either present or absent in the -`tags` list), an aspect hint can convey arbitrary structured information in its -[providers](/extending/rules#providers). - -In practice, aspect hints are used for interoperability between different language-specific -rule sets. For example, imagine you have a `mylang_binary` target which needs to depend -on an `otherlang_library` target. The MyLang-specific logic needs some additional -information about the OtherLang target in order to use it, but `otherlang_library` -doesn't provide this information because it knows nothing about MyLang. One solution might be for -the MyLang rule set to define a `mylang_hint` rule which can be used to encode that -additional information; the user can add the hint to their `otherlang_library`'s -`aspect_hints`, and `mylang_binary` can use an aspect to collect the -additional information from a MyLang-specific provider in the `mylang_hint`. - -For a concrete example, see -[`swift_interop_hint`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_interop_hint) -and [`swift_overlay`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_overlay) -in `rules_swift`. - -Best practices: - -- Targets listed in `aspect_hints` should be lightweight and minimal. -- Language-specific logic should consider only aspect hints having providers relevant to that - language, and should ignore any other aspect hints. - -`compatible_with` - -List of [labels](/concepts/labels); -[nonconfigurable](#configurable-attributes); default is `[]` - -The list of environments this target can be built for, in addition to -default-supported environments. - -This is part of Bazel's constraint system, which lets users declare which -targets can and cannot depend on each other. For example, externally deployable -binaries shouldn't depend on libraries with company-secret code. See -[ConstraintSemantics](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/analysis/constraints/ConstraintSemantics.java#L46) for details. - -`deprecation` - -String; [nonconfigurable](#configurable-attributes); default is `None` - -An explanatory warning message associated with this target. -Typically this is used to notify users that a target has become obsolete, -or has become superseded by another rule, is private to a package, or is -perhaps considered harmful for some reason. It is a good idea to include -some reference (like a webpage, a bug number or example migration CLs) so -that one can easily find out what changes are required to avoid the message. -If there is a new target that can be used as a drop in replacement, it is a -good idea to just migrate all users of the old target. - -This attribute has no effect on the way things are built, but it -may affect a build tool's diagnostic output. The build tool issues a -warning when a rule with a `deprecation` attribute is -depended upon by a target in another package. - -Intra-package dependencies are exempt from this warning, so that, -for example, building the tests of a deprecated rule does not -encounter a warning. - -If a deprecated target depends on another deprecated target, no warning -message is issued. - -Once people have stopped using it, the target can be removed. - -`exec_compatible_with` - -List of [labels](/concepts/labels); -[nonconfigurable](#configurable-attributes); default is `[]` - -A list of -`constraint_values` -that must be present in the execution platform of this target's default exec -group. This is in addition to any constraints already set by the rule type. -Constraints are used to restrict the list of available execution platforms. - -For more details, see -the description of -[toolchain resolution](/docs/toolchains#toolchain-resolution). -and -[exec groups](/extending/exec-groups) - -`exec_group_compatible_with` - -Dictionary of strings to lists of [labels](/concepts/labels); -[nonconfigurable](#configurable-attributes); default is `{}` - -A dictionary of exec group names to lists of -`constraint_values` -that must be present in the execution platform for the given exec group. This -is in addition to any constraints already set on the exec group's definition. -Constraints are used to restrict the list of available execution platforms. - -For more details, see -the description of -[toolchain resolution](/docs/toolchains#toolchain-resolution). -and -[exec groups](/extending/exec-groups) - -`exec_properties` - -Dictionary of strings; default is `{}` - -A dictionary of strings that will be added to the `exec_properties` of a platform selected for this target. See `exec_properties` of the [platform](platforms-and-toolchains.html#platform) rule. - -If a key is present in both the platform and target-level properties, the value will be taken from the target. - -Keys can be prefixed with the name of an execution group followed by a `.` to apply them only to that particular exec group. - -`features` - -List of _feature_ strings; default is `[]` - -A feature is string tag that can be enabled or disabled on a target. The -meaning of a feature depends on the rule itself. - -This `features` attribute is combined with the [package](/reference/be/functions.html#package) level `features` attribute. For example, if -the features \["a", "b"\] are enabled on the package level, and a target's -`features` attribute contains \["-a", "c"\], the features enabled for the -rule will be "b" and "c". -[See example](https://github.com/bazelbuild/examples/blob/main/rules/features/BUILD). - -`package_metadata` - -List of [labels](/concepts/labels); -[nonconfigurable](#configurable-attributes); default is the package's -`default_package_metadata` - -A list of labels that are associated metadata about this target. -Typically, the labels are simple rules that return a provider of -constant values. Rules and aspects may use these labels to perform some -additional analysis on the build graph. - -The canonical use case is that of -[rules\_license](https://github.com/bazelbuild/rules_license). -For that use case, `package_metadata` and -`default_package_metadata` is used to attach information -about a package's licence or version to targets. An aspect applied -to a top-level binary can be used to gather those and produce -compliance reports. - -`restricted_to` - -List of [labels](/concepts/labels); -[nonconfigurable](#configurable-attributes); default is `[]` - -The list of environments this target can be built for, _instead_ of -default-supported environments. - -This is part of Bazel's constraint system. See -`compatible_with` -for details. - -`tags` - -List of strings; [nonconfigurable](#configurable-attributes); -default is `[]` - -_Tags_ can be used on any rule. _Tags_ on test and -`test_suite` rules are useful for categorizing the tests. -_Tags_ on non-test targets are used to control sandboxed execution of -`genrule` s and - -[Starlark](/rules/concepts) -actions, and for parsing by humans and/or external tools. - -Bazel modifies the behavior of its sandboxing code if it finds the following -keywords in the `tags` attribute of any test or `genrule` -target, or the keys of `execution_requirements` for any Starlark -action. - -- `no-sandbox` keyword results in the action or test never being - sandboxed; it can still be cached or run remotely - use `no-cache` - or `no-remote` to prevent either or both of those. - -- `no-cache` keyword results in the action or test never being - cached (locally or remotely). Note: for the purposes of this tag, the disk cache - is considered a local cache, whereas the HTTP and gRPC caches are considered - remote. Other caches, such as Skyframe or the persistent action cache, are not - affected. - -- `no-remote-cache` keyword results in the action or test never being - cached remotely (but it may be cached locally; it may also be executed remotely). - Note: for the purposes of this tag, the disk cache is considered a local cache, - whereas the HTTP and gRPC caches are considered remote. Other caches, such as - Skyframe or the persistent action cache, are not affected. - If a combination of local disk cache and remote cache are used (combined cache), - it's treated as a remote cache and disabled entirely unless `--incompatible_remote_results_ignore_disk` - is set in which case the local components will be used. - -- `no-remote-exec` keyword results in the action or test never being - executed remotely (but it may be cached remotely). - -- `no-remote` keyword prevents the action or test from being executed remotely or - cached remotely. This is equivalent to using both - `no-remote-cache` and `no-remote-exec`. - -- `no-remote-cache-upload` keyword disables upload part of remote caching of a spawn. - it does not disable remote execution. - -- `local` keyword precludes the action or test from being remotely cached, - remotely executed, or run inside the sandbox. - For genrules and tests, marking the rule with the `local = True` - attribute has the same effect. - -- `requires-network` keyword allows access to the external - network from inside the sandbox. This tag only has an effect if sandboxing - is enabled. - -- `block-network` keyword blocks access to the external - network from inside the sandbox. In this case, only communication - with localhost is allowed. This tag only has an effect if sandboxing is - enabled. - -- `requires-fakeroot` runs the test or action as uid and gid 0 (i.e., the root - user). This is only supported on Linux. This tag takes precedence over the - `--sandbox_fake_username` command-line option. - - -_Tags_ on tests are generally used to annotate a test's role in your -debug and release process. Typically, tags are most useful for C++ and Python -tests, which lack any runtime annotation ability. The use of tags and size -elements gives flexibility in assembling suites of tests based around codebase -check-in policy. - -Bazel modifies test running behavior if it finds the following keywords in the -`tags` attribute of the test rule: - -- `exclusive` will force the test to be run in the - "exclusive" mode, ensuring that no other tests are running at the - same time. Such tests will be executed in serial fashion after all build - activity and non-exclusive tests have been completed. Remote execution is - disabled for such tests because Bazel doesn't have control over what's - running on a remote machine. - -- `exclusive-if-local` will force the test to be run in the - "exclusive" mode if it is executed locally, but will run the test in parallel if it's - executed remotely. - -- `manual` keyword will exclude the target from expansion of target pattern wildcards - ( `...`, `:*`, `:all`, etc.) and `test_suite` rules - which do not list the test explicitly when computing the set of top-level targets to build/run - for the `build`, `test`, and `coverage` commands. It does not - affect target wildcard or test suite expansion in other contexts, including the - `query` command. Note that `manual` does not imply that a target should - not be built/run automatically by continuous build/test systems. For example, it may be - desirable to exclude a target from `bazel test ...` because it requires specific - Bazel flags, but still have it included in properly-configured presubmit or continuous test - runs. - - -- `external` keyword will force test to be unconditionally - executed (regardless of `--cache_test_results` - value). - - -See -[Tag Conventions](/reference/test-encyclopedia#tag-conventions) - in the Test Encyclopedia for more conventions on tags attached to test targets. -`target_compatible_with` - -List of [labels](/concepts/labels); default is `[]` - -A list of -`constraint_value` s -that must be present in the target platform for this target to be considered -_compatible_. This is in addition to any constraints already set by the -rule type. If the target platform does not satisfy all listed constraints then -the target is considered _incompatible_. Incompatible targets are -skipped for building and testing when the target pattern is expanded -(e.g. `//...`, `:all`). When explicitly specified on the -command line, incompatible targets cause Bazel to print an error and cause a -build or test failure. - -Targets that transitively depend on incompatible targets are themselves -considered incompatible. They are also skipped for building and testing. - -An empty list (which is the default) signifies that the target is compatible -with all platforms. - -All rules other than [Workspace Rules](workspace.html) support this -attribute. -For some rules this attribute has no effect. For example, specifying -`target_compatible_with` for a -`cc_toolchain` is not useful. - -See the -[Platforms](/docs/platforms#skipping-incompatible-targets) -page for more information about incompatible target skipping. - -`testonly` - -Boolean; [nonconfigurable](#configurable-attributes); default is `False` -except for test and test suite targets - -If `True`, only testonly targets (such as tests) can depend on this target. - -Equivalently, a rule that is not `testonly` is not allowed to -depend on any rule that is `testonly`. - -Tests ( `*_test` rules) -and test suites ( [test\_suite](/reference/be/general.html#test_suite) rules) -are `testonly` by default. - -This attribute is intended to mean that the target should not be -contained in binaries that are released to production. - -Because testonly is enforced at build time, not run time, and propagates -virally through the dependency tree, it should be applied judiciously. For -example, stubs and fakes that -are useful for unit tests may also be useful for integration tests -involving the same binaries that will be released to production, and -therefore should probably not be marked testonly. Conversely, rules that -are dangerous to even link in, perhaps because they unconditionally -override normal behavior, should definitely be marked testonly. - -`toolchains` - -List of [labels](/concepts/labels); -[nonconfigurable](#configurable-attributes); default is `[]` - -The set of targets whose [Make variables](/reference/be/make-variables) this target is -allowed to access. These targets are either instances of rules that provide -`TemplateVariableInfo` or special targets for toolchain types built into Bazel. These -include: - -- `@bazel_tools//tools/cpp:toolchain_type` -- `@rules_java//toolchains:current_java_runtime` - -Note that this is distinct from the concept of -[toolchain resolution](/docs/toolchains#toolchain-resolution) -that is used by rule implementations for platform-dependent configuration. You cannot use this -attribute to determine which specific `cc_toolchain` or `java_toolchain` a -target will use. - -`visibility` - -List of [labels](/concepts/labels); -[nonconfigurable](#configurable-attributes); -default varies - -The `visibility` attribute controls whether the target can be -depended on by targets in other locations. See the documentation for -[visibility](/concepts/visibility). - -For targets declared directly in a BUILD file or in legacy macros called from -a BUILD file, the default value is the package's -`default_visibility` -if specified, or else `["//visibility:private"]`. For targets -declared in one or more symbolic macros, the default value is always just -`["//visibility:private"]` (which makes it useable only within the -package containing the macro's code). +| Attribute | Description | +| --- | --- | +| `aspect_hints` | List of [labels](/concepts/labels); default is `[]` A list of arbitrary labels which is exposed to [aspects](/extending/aspects) (in particular - aspects invoked by this rule's reverse dependencies), but isn't exposed to this rule's own implementation. Consult documentation for language-specific rule sets for details about what effect a particular aspect hint would have. You could think of an aspect hint as a richer alternative to a [tag](#common.tags): while a tag conveys only a boolean state (the tag is either present or absent in the `tags` list), an aspect hint can convey arbitrary structured information in its [providers](/extending/rules#providers). In practice, aspect hints are used for interoperability between different language-specific rule sets. For example, imagine you have a `mylang_binary` target which needs to depend on an `otherlang_library` target. The MyLang-specific logic needs some additional information about the OtherLang target in order to use it, but `otherlang_library` doesn't provide this information because it knows nothing about MyLang. One solution might be for the MyLang rule set to define a `mylang_hint` rule which can be used to encode that additional information; the user can add the hint to their `otherlang_library`'s `aspect_hints`, and `mylang_binary` can use an aspect to collect the additional information from a MyLang-specific provider in the `mylang_hint`. For a concrete example, see [`swift_interop_hint`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_interop_hint) and [`swift_overlay`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_overlay) in `rules_swift`. Best practices: * Targets listed in `aspect_hints` should be lightweight and minimal. * Language-specific logic should consider only aspect hints having providers relevant to that language, and should ignore any other aspect hints. | +| `compatible_with` | List of [labels](/concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` The list of environments this target can be built for, in addition to default-supported environments. This is part of Bazel's constraint system, which lets users declare which targets can and cannot depend on each other. For example, externally deployable binaries shouldn't depend on libraries with company-secret code. See [ConstraintSemantics](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/analysis/constraints/ConstraintSemantics.java#L46) for details. | +| `deprecation` | String; [nonconfigurable](#configurable-attributes); default is `None` An explanatory warning message associated with this target. Typically this is used to notify users that a target has become obsolete, or has become superseded by another rule, is private to a package, or is perhaps considered harmful for some reason. It is a good idea to include some reference (like a webpage, a bug number or example migration CLs) so that one can easily find out what changes are required to avoid the message. If there is a new target that can be used as a drop in replacement, it is a good idea to just migrate all users of the old target. This attribute has no effect on the way things are built, but it may affect a build tool's diagnostic output. The build tool issues a warning when a rule with a `deprecation` attribute is depended upon by a target in another package. Intra-package dependencies are exempt from this warning, so that, for example, building the tests of a deprecated rule does not encounter a warning. If a deprecated target depends on another deprecated target, no warning message is issued. Once people have stopped using it, the target can be removed. | +| `exec_compatible_with` | List of [labels](/concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` A list of `constraint_values` that must be present in the execution platform of this target's default exec group. This is in addition to any constraints already set by the rule type. Constraints are used to restrict the list of available execution platforms. For more details, see the description of [toolchain resolution](/docs/toolchains#toolchain-resolution). and [exec groups](/extending/exec-groups) | +| `exec_group_compatible_with` | Dictionary of strings to lists of [labels](/concepts/labels); [nonconfigurable](#configurable-attributes); default is `{}` A dictionary of exec group names to lists of `constraint_values` that must be present in the execution platform for the given exec group. This is in addition to any constraints already set on the exec group's definition. Constraints are used to restrict the list of available execution platforms. For more details, see the description of [toolchain resolution](/docs/toolchains#toolchain-resolution). and [exec groups](/extending/exec-groups) | +| `exec_properties` | Dictionary of strings; default is `{}` A dictionary of strings that will be added to the `exec_properties` of a platform selected for this target. See `exec_properties` of the [platform](platforms-and-toolchains#platform) rule. If a key is present in both the platform and target-level properties, the value will be taken from the target. Keys can be prefixed with the name of an execution group followed by a `.` to apply them only to that particular exec group. | +| `features` | List of *feature* strings; default is `[]` A feature is string tag that can be enabled or disabled on a target. The meaning of a feature depends on the rule itself. This `features` attribute is combined with the [package](/reference/be/functions#package) level `features` attribute. For example, if the features ["a", "b"] are enabled on the package level, and a target's `features` attribute contains ["-a", "c"], the features enabled for the rule will be "b" and "c". [See example](https://github.com/bazelbuild/examples/blob/main/rules/features/BUILD). | +| `package_metadata` | List of [labels](/concepts/labels); [nonconfigurable](#configurable-attributes); default is the package's `default_package_metadata` A list of labels that are associated metadata about this target. Typically, the labels are simple rules that return a provider of constant values. Rules and aspects may use these labels to perform some additional analysis on the build graph. The canonical use case is that of [rules\_license](https://github.com/bazelbuild/rules_license). For that use case, `package_metadata` and `default_package_metadata` is used to attach information about a package's licence or version to targets. An aspect applied to a top-level binary can be used to gather those and produce compliance reports. | +| `restricted_to` | List of [labels](/concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` The list of environments this target can be built for, *instead* of default-supported environments. This is part of Bazel's constraint system. See `compatible_with` for details. | +| `tags` | List of strings; [nonconfigurable](#configurable-attributes); default is `[]` *Tags* can be used on any rule. *Tags* on test and `test_suite` rules are useful for categorizing the tests. *Tags* on non-test targets are used to control sandboxed execution of `genrule`s and [Starlark](/rules/concepts) actions, and for parsing by humans and/or external tools. Bazel modifies the behavior of its sandboxing code if it finds the following keywords in the `tags` attribute of any test or `genrule` target, or the keys of `execution_requirements` for any Starlark action. * `no-sandbox` keyword results in the action or test never being sandboxed; it can still be cached or run remotely - use `no-cache` or `no-remote` to prevent either or both of those. * `no-cache` keyword results in the action or test never being cached (locally or remotely). Note: for the purposes of this tag, the disk cache is considered a local cache, whereas the HTTP and gRPC caches are considered remote. Other caches, such as Skyframe or the persistent action cache, are not affected. * `no-remote-cache` keyword results in the action or test never being cached remotely (but it may be cached locally; it may also be executed remotely). Note: for the purposes of this tag, the disk cache is considered a local cache, whereas the HTTP and gRPC caches are considered remote. Other caches, such as Skyframe or the persistent action cache, are not affected. If a combination of local disk cache and remote cache are used (combined cache), it's treated as a remote cache and disabled entirely unless `--incompatible_remote_results_ignore_disk` is set in which case the local components will be used. * `no-remote-exec` keyword results in the action or test never being executed remotely (but it may be cached remotely). * `no-remote` keyword prevents the action or test from being executed remotely or cached remotely. This is equivalent to using both `no-remote-cache` and `no-remote-exec`. * `no-remote-cache-upload` keyword disables upload part of remote caching of a spawn. it does not disable remote execution. * `local` keyword precludes the action or test from being remotely cached, remotely executed, or run inside the sandbox. For genrules and tests, marking the rule with the `local = True` attribute has the same effect. * `requires-network` keyword allows access to the external network from inside the sandbox. This tag only has an effect if sandboxing is enabled. * `block-network` keyword blocks access to the external network from inside the sandbox. In this case, only communication with localhost is allowed. This tag only has an effect if sandboxing is enabled. * `requires-fakeroot` runs the test or action as uid and gid 0 (i.e., the root user). This is only supported on Linux. This tag takes precedence over the `--sandbox_fake_username` command-line option. *Tags* on tests are generally used to annotate a test's role in your debug and release process. Typically, tags are most useful for C++ and Python tests, which lack any runtime annotation ability. The use of tags and size elements gives flexibility in assembling suites of tests based around codebase check-in policy. Bazel modifies test running behavior if it finds the following keywords in the `tags` attribute of the test rule: * `exclusive` will force the test to be run in the "exclusive" mode, ensuring that no other tests are running at the same time. Such tests will be executed in serial fashion after all build activity and non-exclusive tests have been completed. Remote execution is disabled for such tests because Bazel doesn't have control over what's running on a remote machine. * `exclusive-if-local` will force the test to be run in the "exclusive" mode if it is executed locally, but will run the test in parallel if it's executed remotely. * `manual` keyword will exclude the target from expansion of target pattern wildcards (`...`, `:*`, `:all`, etc.) and `test_suite` rules which do not list the test explicitly when computing the set of top-level targets to build/run for the `build`, `test`, and `coverage` commands. It does not affect target wildcard or test suite expansion in other contexts, including the `query` command. Note that `manual` does not imply that a target should not be built/run automatically by continuous build/test systems. For example, it may be desirable to exclude a target from `bazel test ...` because it requires specific Bazel flags, but still have it included in properly-configured presubmit or continuous test runs. * `external` keyword will force test to be unconditionally executed (regardless of `--cache_test_results` value). See [Tag Conventions](/reference/test-encyclopedia#tag-conventions) in the Test Encyclopedia for more conventions on tags attached to test targets. | +| `target_compatible_with` | List of [labels](/concepts/labels); default is `[]` A list of `constraint_value`s that must be present in the target platform for this target to be considered *compatible*. This is in addition to any constraints already set by the rule type. If the target platform does not satisfy all listed constraints then the target is considered *incompatible*. Incompatible targets are skipped for building and testing when the target pattern is expanded (e.g. `//...`, `:all`). When explicitly specified on the command line, incompatible targets cause Bazel to print an error and cause a build or test failure. Targets that transitively depend on incompatible targets are themselves considered incompatible. They are also skipped for building and testing. An empty list (which is the default) signifies that the target is compatible with all platforms. All rules other than [Workspace Rules](workspace) support this attribute. For some rules this attribute has no effect. For example, specifying `target_compatible_with` for a `cc_toolchain` is not useful. See the [Platforms](/docs/platforms#skipping-incompatible-targets) page for more information about incompatible target skipping. | +| `testonly` | Boolean; [nonconfigurable](#configurable-attributes); default is `False` except for test and test suite targets If `True`, only testonly targets (such as tests) can depend on this target. Equivalently, a rule that is not `testonly` is not allowed to depend on any rule that is `testonly`. Tests (`*_test` rules) and test suites ([test\_suite](/reference/be/general#test_suite) rules) are `testonly` by default. This attribute is intended to mean that the target should not be contained in binaries that are released to production. Because testonly is enforced at build time, not run time, and propagates virally through the dependency tree, it should be applied judiciously. For example, stubs and fakes that are useful for unit tests may also be useful for integration tests involving the same binaries that will be released to production, and therefore should probably not be marked testonly. Conversely, rules that are dangerous to even link in, perhaps because they unconditionally override normal behavior, should definitely be marked testonly. | +| `toolchains` | List of [labels](/concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` The set of targets whose [Make variables](/reference/be/make-variables) this target is allowed to access. These targets are either instances of rules that provide `TemplateVariableInfo` or special targets for toolchain types built into Bazel. These include: * `@bazel_tools//tools/cpp:toolchain_type`* `@rules_java//toolchains:current_java_runtime` Note that this is distinct from the concept of [toolchain resolution](/docs/toolchains#toolchain-resolution) that is used by rule implementations for platform-dependent configuration. You cannot use this attribute to determine which specific `cc_toolchain` or `java_toolchain` a target will use. | +| `visibility` | List of [labels](/concepts/labels); [nonconfigurable](#configurable-attributes); default varies The `visibility` attribute controls whether the target can be depended on by targets in other locations. See the documentation for [visibility](/concepts/visibility). For targets declared directly in a BUILD file or in legacy macros called from a BUILD file, the default value is the package's `default_visibility` if specified, or else `["//visibility:private"]`. For targets declared in one or more symbolic macros, the default value is always just `["//visibility:private"]` (which makes it useable only within the package containing the macro's code). | ## Attributes common to all test rules (\*\_test) This section describes attributes that are common to all test rules. -AttributeDescription`args` - -List of strings; subject to -[$(location)](/reference/be/make-variables#predefined_label_variables) and -["Make variable"](/reference/be/make-variables) substitution, and -[Bourne shell tokenization](#sh-tokenization); default is `[]` - -Command line arguments that Bazel passes to the target when it is -executed with `bazel test`. - -These arguments are passed before any `--test_arg` values -specified on the `bazel test` command line. - -`env` - -Dictionary of strings; values are subject to -[$(location)](/reference/be/make-variables#predefined_label_variables) and -["Make variable"](/reference/be/make-variables) substitution; default is `{}` - -Specifies additional environment variables to set when the test is executed by -`bazel test`. - -This attribute only applies to native rules, like `cc_test`, -`py_test`, and `sh_test`. It does not apply to -Starlark-defined test rules. For your own Starlark rules, you can add an "env" -attribute and use it to populate a - -[RunEnvironmentInfo](/rules/lib/providers/RunEnvironmentInfo.html) -Provider. - -[TestEnvironment](/rules/lib/toplevel/testing#TestEnvironment) - - Provider. - -`env_inherit` - -List of strings; default is `[]` - -Specifies additional environment variables to inherit from the -external environment when the test is executed by `bazel test`. - -This attribute only applies to native rules, like `cc_test`, `py_test`, -and `sh_test`. It does not apply to Starlark-defined test rules. - -`size` - -String `"enormous"`, `"large"`, `"medium"`, or -`"small"`; [nonconfigurable](#configurable-attributes); -default is `"medium"` - -Specifies a test target's "heaviness": how much time/resources it needs to run. - -Unit tests are considered "small", integration tests "medium", and end-to-end tests "large" or -"enormous". Bazel uses the size to determine a default timeout, which can be overridden using the -`timeout` attribute. The timeout is for all tests in the BUILD target, not for each -individual test. When the test is run locally, the `size` is additionally used for -scheduling purposes: Bazel tries to respect `--local_{ram,cpu}_resources` and not -overwhelm the local machine by running lots of heavy tests at the same time. - -Test sizes correspond to the following default timeouts and assumed peak local resource -usages: - -SizeRAM (in MB)CPU (in CPU cores)Default timeoutsmall201short (1 minute)medium1001moderate (5 minutes)large3001long (15 minutes)enormous8001eternal (60 minutes) - -The environment variable -`TEST_SIZE` will be set to -the value of this attribute when spawning the test. - -`timeout` - -String `"short"`, `"moderate"`, `"long"`, or -`"eternal"`; [nonconfigurable](#configurable-attributes); default is derived -from the test's `size` attribute - -How long the test is expected to run before returning. - -While a test's size attribute controls resource estimation, a test's -timeout may be set independently. If not explicitly specified, the -timeout is based on the [test's size](#test.size). The test -timeout can be overridden with the `--test_timeout` flag, e.g. for -running under certain conditions which are known to be slow. Test timeout values -correspond to the following time periods: - -Timeout ValueTime Periodshort1 minutemoderate5 minuteslong15 minuteseternal60 minutes - -For times other than the above, the test timeout can be overridden with the -`--test_timeout` bazel flag, e.g. for manually running under -conditions which are known to be slow. The `--test_timeout` values -are in seconds. For example `--test_timeout=120` will set the test -timeout to two minutes. - -The environment variable -`TEST_TIMEOUT` will be set -to the test timeout (in seconds) when spawning the test. - -`flaky` - -Boolean; [nonconfigurable](#configurable-attributes); -default is `False` - -Marks test as flaky. - -If set, executes the test up to three times, marking it as failed only if it -fails each time. By default, this attribute is set to False and the test is -executed only once. Note, that use of this attribute is generally discouraged - -tests should pass reliably when their assertions are upheld. - -`shard_count` - -Non-negative integer less than or equal to 50; default is `-1` - -Specifies the number of parallel shards -to use to run the test. - -If set, this value will override any heuristics used to determine the number of -parallel shards with which to run the test. Note that for some test -rules, this parameter may be required to enable sharding -in the first place. Also see `--test_sharding_strategy`. - -If test sharding is enabled, the environment variable ` -TEST_TOTAL_SHARDS -` will be set to this value when spawning the test. - -Sharding requires the test runner to support the test sharding protocol. -If it does not, then it will most likely run every test in every shard, which -is not what you want. - -See -[Test Sharding](/reference/test-encyclopedia#test-sharding) -in the Test Encyclopedia for details on sharding. - -`local` - -Boolean; [nonconfigurable](#configurable-attributes); -default is `False` - -Forces the test to be run locally, without sandboxing. - -Setting this to True is equivalent to providing "local" as a tag -( `tags=["local"]`). +| Attribute | Description | +| --- | --- | +| `args` | List of strings; subject to [$(location)](/reference/be/make-variables#predefined_label_variables) and ["Make variable"](/reference/be/make-variables) substitution, and [Bourne shell tokenization](#sh-tokenization); default is `[]` Command line arguments that Bazel passes to the target when it is executed with `bazel test`. These arguments are passed before any `--test_arg` values specified on the `bazel test` command line. | +| `env` | Dictionary of strings; values are subject to [$(location)](/reference/be/make-variables#predefined_label_variables) and ["Make variable"](/reference/be/make-variables) substitution; default is `{}` Specifies additional environment variables to set when the test is executed by `bazel test`. This attribute only applies to native rules, like `cc_test`, `py_test`, and `sh_test`. It does not apply to Starlark-defined test rules. For your own Starlark rules, you can add an "env" attribute and use it to populate a [RunEnvironmentInfo](/rules/lib/providers/RunEnvironmentInfo) Provider. [TestEnvironment](/rules/lib/toplevel/testing#TestEnvironment) Provider. | +| `env_inherit` | List of strings; default is `[]` Specifies additional environment variables to inherit from the external environment when the test is executed by `bazel test`. This attribute only applies to native rules, like `cc_test`, `py_test`, and `sh_test`. It does not apply to Starlark-defined test rules. | +| `size` | String `"enormous"`, `"large"`, `"medium"`, or `"small"`; [nonconfigurable](#configurable-attributes); default is `"medium"` Specifies a test target's "heaviness": how much time/resources it needs to run. Unit tests are considered "small", integration tests "medium", and end-to-end tests "large" or "enormous". Bazel uses the size to determine a default timeout, which can be overridden using the `timeout` attribute. The timeout is for all tests in the BUILD target, not for each individual test. When the test is run locally, the `size` is additionally used for scheduling purposes: Bazel tries to respect `--local_{ram,cpu}_resources` and not overwhelm the local machine by running lots of heavy tests at the same time. Test sizes correspond to the following default timeouts and assumed peak local resource usages: | Size | RAM (in MB) | CPU (in CPU cores) | Default timeout | | --- | --- | --- | --- | | small | 20 | 1 | short (1 minute) | | medium | 100 | 1 | moderate (5 minutes) | | large | 300 | 1 | long (15 minutes) | | enormous | 800 | 1 | eternal (60 minutes) | The environment variable `TEST_SIZE` will be set to the value of this attribute when spawning the test. | +| `timeout` | String `"short"`, `"moderate"`, `"long"`, or `"eternal"`; [nonconfigurable](#configurable-attributes); default is derived from the test's `size` attribute How long the test is expected to run before returning. While a test's size attribute controls resource estimation, a test's timeout may be set independently. If not explicitly specified, the timeout is based on the [test's size](#test.size). The test timeout can be overridden with the `--test_timeout` flag, e.g. for running under certain conditions which are known to be slow. Test timeout values correspond to the following time periods: | Timeout Value | Time Period | | --- | --- | | short | 1 minute | | moderate | 5 minutes | | long | 15 minutes | | eternal | 60 minutes | For times other than the above, the test timeout can be overridden with the `--test_timeout` bazel flag, e.g. for manually running under conditions which are known to be slow. The `--test_timeout` values are in seconds. For example `--test_timeout=120` will set the test timeout to two minutes. The environment variable `TEST_TIMEOUT` will be set to the test timeout (in seconds) when spawning the test. | +| `flaky` | Boolean; [nonconfigurable](#configurable-attributes); default is `False` Marks test as flaky. If set, executes the test up to three times, marking it as failed only if it fails each time. By default, this attribute is set to False and the test is executed only once. Note, that use of this attribute is generally discouraged - tests should pass reliably when their assertions are upheld. | +| `shard_count` | Non-negative integer less than or equal to 50; default is `-1` Specifies the number of parallel shards to use to run the test. If set, this value will override any heuristics used to determine the number of parallel shards with which to run the test. Note that for some test rules, this parameter may be required to enable sharding in the first place. Also see `--test_sharding_strategy`. If test sharding is enabled, the environment variable `TEST_TOTAL_SHARDS` will be set to this value when spawning the test. Sharding requires the test runner to support the test sharding protocol. If it does not, then it will most likely run every test in every shard, which is not what you want. See [Test Sharding](/reference/test-encyclopedia#test-sharding) in the Test Encyclopedia for details on sharding. | +| `local` | Boolean; [nonconfigurable](#configurable-attributes); default is `False` Forces the test to be run locally, without sandboxing. Setting this to True is equivalent to providing "local" as a tag (`tags=["local"]`). | ## Attributes common to all binary rules (\*\_binary) This section describes attributes that are common to all binary rules. -AttributeDescription`args` - -List of strings; subject to -[$(location)](/reference/be/make-variables#predefined_label_variables) and -["Make variable"](/reference/be/make-variables) substitution, and -[Bourne shell tokenization](#sh-tokenization); -[nonconfigurable](#configurable-attributes); -default is `[]` - -Command line arguments that Bazel will pass to the target when it is executed -either by the `run` command or as a test. These arguments are -passed before the ones that are specified on the `bazel run` or -`bazel test` command line. - -_NOTE: The arguments are not passed when you run the target_ -_outside of Bazel (for example, by manually executing the binary in_ -_`bazel-bin/`)._ - -`env` - -Dictionary of strings; values are subject to -[$(location)](/reference/be/make-variables#predefined_label_variables) and -["Make variable"](/reference/be/make-variables) substitution; default is `{}` - -Specifies additional environment variables to set when the target is -executed by `bazel run`. - -This attribute only applies to native rules, like `cc_binary`, `py_binary`, -and `sh_binary`. It does not apply to Starlark-defined executable rules. For your own -Starlark rules, you can add an "env" attribute and use it to populate a - -[RunEnvironmentInfo](/rules/lib/providers/RunEnvironmentInfo.html) - -Provider. - -_NOTE: The environment variables are not set when you run the target_ -_outside of Bazel (for example, by manually executing the binary in_ -_`bazel-bin/`)._ - -`output_licenses` - -List of strings; default is `[]` - -The licenses of the output files that this binary generates. - -This is part of a deprecated licensing API that Bazel no longer uses. Don't -use this. +| Attribute | Description | +| --- | --- | +| `args` | List of strings; subject to [$(location)](/reference/be/make-variables#predefined_label_variables) and ["Make variable"](/reference/be/make-variables) substitution, and [Bourne shell tokenization](#sh-tokenization); [nonconfigurable](#configurable-attributes); default is `[]` Command line arguments that Bazel will pass to the target when it is executed either by the `run` command or as a test. These arguments are passed before the ones that are specified on the `bazel run` or `bazel test` command line. *NOTE: The arguments are not passed when you run the target outside of Bazel (for example, by manually executing the binary in `bazel-bin/`).* | +| `env` | Dictionary of strings; values are subject to [$(location)](/reference/be/make-variables#predefined_label_variables) and ["Make variable"](/reference/be/make-variables) substitution; default is `{}` Specifies additional environment variables to set when the target is executed by `bazel run`. This attribute only applies to native rules, like `cc_binary`, `py_binary`, and `sh_binary`. It does not apply to Starlark-defined executable rules. For your own Starlark rules, you can add an "env" attribute and use it to populate a [RunEnvironmentInfo](/rules/lib/providers/RunEnvironmentInfo) Provider. *NOTE: The environment variables are not set when you run the target outside of Bazel (for example, by manually executing the binary in `bazel-bin/`).* | +| `output_licenses` | List of strings; default is `[]` The licenses of the output files that this binary generates. This is part of a deprecated licensing API that Bazel no longer uses. Don't use this. | ## Configurable attributes @@ -721,13 +140,12 @@ config_setting( name = "arm_mode", values = { "cpu": "arm" } ) - ``` -The [`select()`](/reference/be/functions.html#select) function +The [`select()`](/reference/be/functions#select) function chooses among different alternative values for a configurable attribute based -on which [`config_setting`](/reference/be/general.html#config_setting) -or [`constraint_value`](/reference/be/platforms-and-toolchains.html#constraint_value) +on which [`config_setting`](/reference/be/general#config_setting) +or [`constraint_value`](/reference/be/platforms-and-toolchains#constraint_value) criteria the target's configuration satisfies. Bazel evaluates configurable attributes after processing macros and before @@ -749,18 +167,17 @@ See [Configurable Build Attributes](https://bazel.build/docs/configurable-attrib ## Implicit output targets -_Implicit outputs in C++ are deprecated. Please refrain from using it_ -_in other languages where possible. We don't have a deprecation path yet_ -_but they will eventually be deprecated too._ +*Implicit outputs in C++ are deprecated. Please refrain from using it +in other languages where possible. We don't have a deprecation path yet +but they will eventually be deprecated too.* When you define a build rule in a BUILD file, you are explicitly declaring a new, named rule target in a package. Many build rule -functions also _implicitly_ entail one or more output file +functions also *implicitly* entail one or more output file targets, whose contents and meaning are rule-specific. - For example, when you explicitly declare a `java_binary(name='foo', ...)` rule, you are also -_implicitly_ declaring an output file +*implicitly* declaring an output file target `foo_deploy.jar` as a member of the same package. (This particular target is a self-contained Java archive suitable for deployment.) @@ -778,12 +195,12 @@ outputs entailed by a declaration of that kind of rule. An important but somewhat subtle distinction between the two namespaces used by the build system: -[labels](/concepts/labels) identify _targets_, +[labels](/concepts/labels) identify *targets*, which may be rules or files, and file targets may be divided into either source (or input) file targets and derived (or output) file targets. These are the things you can mention in BUILD files, build from the command-line, or examine using `bazel query`; -this is the _target namespace_. Each file target corresponds +this is the *target namespace*. Each file target corresponds to one actual file on disk (the "file system namespace"); each rule target may correspond to zero, one or more actual files on disk. There may be files on disk that have no corresponding target; for @@ -791,4 +208,4 @@ example, `.o` object files produced during C++ compilation cannot be referenced from within BUILD files or from the command line. In this way, the build tool may hide certain implementation details of how it does its job. This is explained more fully in -the [BUILD Concept Reference](/concepts/build-ref). +the [BUILD Concept Reference](/concepts/build-ref). \ No newline at end of file diff --git a/reference/be/extra-actions.mdx b/reference/be/extra-actions.mdx index 0c16bd904..bf31904fe 100644 --- a/reference/be/extra-actions.mdx +++ b/reference/be/extra-actions.mdx @@ -2,12 +2,10 @@ title: 'Extra Actions Rules' --- - - ## Rules -- [action\_listener](#action_listener) -- [extra\_action](#extra_action) +* [action\_listener](#action_listener) +* [extra\_action](#extra_action) ## action\_listener @@ -23,15 +21,15 @@ instead. An `action_listener` rule doesn't produce any output itself. Instead, it allows tool developers to insert -[`extra_action`](/reference/be/extra-actions.html#extra_action) s into the build system, -by providing a mapping from action to [`extra_action`](/reference/be/extra-actions.html#extra_action). +[`extra_action`](/reference/be/extra-actions#extra_action)s into the build system, +by providing a mapping from action to [`extra_action`](/reference/be/extra-actions#extra_action). This rule's arguments map action mnemonics to -[`extra_action`](/reference/be/extra-actions.html#extra_action) rules. +[`extra_action`](/reference/be/extra-actions#extra_action) rules. By specifying the option [`--experimental_action_listener=