From 2b533cf38d835b0a687dcf518622a76105f36b36 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 2 May 2026 08:53:09 +0000 Subject: [PATCH] chore: update documentation from upstream Bazel repo [skip ci] Synchronized pre-converted MDX files from upstream Bazel repository. --- navigation.json | 8 + reference/command-line-reference.mdx | 15 + rules/lib/fragments.mdx | 1 + rules/lib/overview.mdx | 1 + upstream | 2 +- versions/9.1.0/basics/task-based-builds.mdx | 14 +- versions/9.1.0/community/users.mdx | 4 +- versions/9.1.0/concepts/build-files.mdx | 13 + versions/9.1.0/concepts/dependencies.mdx | 84 +-- versions/9.1.0/concepts/labels.mdx | 19 +- versions/9.1.0/contribute/search.mdx | 8 +- .../docs/android-instrumentation-test.mdx | 8 +- .../docs/cc-toolchain-config-reference.mdx | 625 ++++++++++-------- versions/9.1.0/docs/user-manual.mdx | 350 +++++----- versions/9.1.0/extending/config.mdx | 2 +- versions/9.1.0/external/migration_tool.mdx | 12 +- versions/9.1.0/external/mod-command.mdx | 10 +- versions/9.1.0/external/registry.mdx | 7 +- versions/9.1.0/query/language.mdx | 61 +- versions/9.1.0/reference/flag-cheatsheet.mdx | 25 + .../9.1.0/reference/test-encyclopedia.mdx | 2 +- versions/9.1.0/remote/cache-local.mdx | 6 +- versions/9.1.0/remote/cache-remote.mdx | 2 +- versions/9.1.0/remote/dynamic.mdx | 4 +- versions/9.1.0/remote/sandbox.mdx | 2 +- versions/9.1.0/rules/lib/repo/http.mdx | 18 +- versions/9.1.0/run/build.mdx | 7 +- 27 files changed, 739 insertions(+), 571 deletions(-) diff --git a/navigation.json b/navigation.json index 99f6ff9e..a3d046ca 100644 --- a/navigation.json +++ b/navigation.json @@ -87,6 +87,14 @@ "$ref": "./navigation/7.7.en.json" } ] + }, + { + "version": "6.5", + "languages": [ + { + "$ref": "./navigation/6.5.en.json" + } + ] } ] } diff --git a/reference/command-line-reference.mdx b/reference/command-line-reference.mdx index 375b6af8..0f00cb9d 100644 --- a/reference/command-line-reference.mdx +++ b/reference/command-line-reference.mdx @@ -3397,6 +3397,9 @@ Miscellaneous options, not otherwise categorized.: Tags: [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--j2objc_translation_flags=` multiple uses are accumulated +: Additional options to pass to the J2ObjC tool. + `--java_debug` : Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. @@ -6063,6 +6066,9 @@ Miscellaneous options, not otherwise categorized.: Tags: [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--j2objc_translation_flags=` multiple uses are accumulated +: Additional options to pass to the J2ObjC tool. + `--java_debug` : Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. @@ -7874,6 +7880,9 @@ Miscellaneous options, not otherwise categorized.: Tags: [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--j2objc_translation_flags=` multiple uses are accumulated +: Additional options to pass to the J2ObjC tool. + `--java_debug` : Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. @@ -9506,6 +9515,9 @@ Miscellaneous options, not otherwise categorized.: Tags: [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--j2objc_translation_flags=` multiple uses are accumulated +: Additional options to pass to the J2ObjC tool. + `--java_debug` : Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. @@ -12496,6 +12508,9 @@ Miscellaneous options, not otherwise categorized.: Tags: [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE) +`--j2objc_translation_flags=` multiple uses are accumulated +: Additional options to pass to the J2ObjC tool. + `--java_debug` : Causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger (such as jdb) before starting the test. Implies -test_output=streamed. diff --git a/rules/lib/fragments.mdx b/rules/lib/fragments.mdx index bdd63e7b..8b497627 100644 --- a/rules/lib/fragments.mdx +++ b/rules/lib/fragments.mdx @@ -10,6 +10,7 @@ Rule implementations can get them using `ctx.fragments.[fragment name]` * [bazel_android](/rules/lib/fragments/bazel_android) * [coverage](/rules/lib/fragments/coverage) * [cpp](/rules/lib/fragments/cpp) +* [j2objc](/rules/lib/fragments/j2objc) * [java](/rules/lib/fragments/java) * [objc](/rules/lib/fragments/objc) * [platform](/rules/lib/fragments/platform) diff --git a/rules/lib/overview.mdx b/rules/lib/overview.mdx index dcd67501..307d2da4 100644 --- a/rules/lib/overview.mdx +++ b/rules/lib/overview.mdx @@ -17,6 +17,7 @@ title: 'One-Page Overview' * [bazel_android](/rules/lib/fragments/bazel_android) * [coverage](/rules/lib/fragments/coverage) * [cpp](/rules/lib/fragments/cpp) +* [j2objc](/rules/lib/fragments/j2objc) * [java](/rules/lib/fragments/java) * [objc](/rules/lib/fragments/objc) * [platform](/rules/lib/fragments/platform) diff --git a/upstream b/upstream index 215ec5cd..71610109 160000 --- a/upstream +++ b/upstream @@ -1 +1 @@ -Subproject commit 215ec5cd3a0aa09cd9ede99d132465f3c9c59000 +Subproject commit 716101092c644dcaae506655095bf9cd3ece1cf1 diff --git a/versions/9.1.0/basics/task-based-builds.mdx b/versions/9.1.0/basics/task-based-builds.mdx index b5a3d46a..a0fe9fb2 100644 --- a/versions/9.1.0/basics/task-based-builds.mdx +++ b/versions/9.1.0/basics/task-based-builds.mdx @@ -23,32 +23,32 @@ Take this example from the simple example build file - {/* set global properties for this build */} + - {/* Create the time stamp */} + - {/* Create the build directory structure used by compile */} + - {/* Compile the Java code from ${src} into ${build} */} + - {/* Create the distribution directory */} + - {/* Put everything in ${build} into the MyProject-${DSTAMP}.jar file */} + - {/* Delete the ${build} and ${dist} directory trees */} + diff --git a/versions/9.1.0/community/users.mdx b/versions/9.1.0/community/users.mdx index 39851e98..8cb35d79 100644 --- a/versions/9.1.0/community/users.mdx +++ b/versions/9.1.0/community/users.mdx @@ -1,5 +1,5 @@ --- -title: "Who's Using Bazel" +title: 'Who's Using Bazel' --- Note: Using Bazel? You can add your company on @@ -43,7 +43,7 @@ analysis. Their motto is _Big data is hard. We make it easy_. ### [ASML](https://asml.com) - + ASML is an innovation leader in the semiconductor industry. We provide chipmakers with everything they need – hardware, software and services – to mass produce diff --git a/versions/9.1.0/concepts/build-files.mdx b/versions/9.1.0/concepts/build-files.mdx index 57e853e2..542c2ded 100644 --- a/versions/9.1.0/concepts/build-files.mdx +++ b/versions/9.1.0/concepts/build-files.mdx @@ -130,6 +130,19 @@ for anyone to create new rules. 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 diff --git a/versions/9.1.0/concepts/dependencies.mdx b/versions/9.1.0/concepts/dependencies.mdx index e16b3549..4746b391 100644 --- a/versions/9.1.0/concepts/dependencies.mdx +++ b/versions/9.1.0/concepts/dependencies.mdx @@ -70,22 +70,21 @@ depends on `c`. -``` -rule( + 
rule(
     name = "a",
     srcs = "a.in",
     deps = "//b:b",
 )
-```
+
-``` + 
 rule(
     name = "b",
     srcs = "b.in",
     deps = "//c:c",
 )
-```
+
@@ -93,26 +92,25 @@ rule( b / b.in - -``` + 
 import b;
 b.foo();
-```
+
-``` + 
 import c;
 function foo() {
   c.bar();
 }
-```
+
Declared dependency graph with arrows connecting a, b, and c + alt="Declared dependency graph with arrows connecting a, b, and c">
Declared dependency graph
@@ -120,7 +118,7 @@ function foo() {
Actual dependency graph that matches the declared dependency - graph with arrows connecting a, b, and c + graph with arrows connecting a, b, and c">
Actual dependency graph
@@ -142,12 +140,12 @@ direct _actual_ dependency on `c`, but forgets to declare it in the build file -``` -import b; -import c; -b.foo(); -c.garply(); -``` + 
+        import b;
+        import c;
+        b.foo();
+        c.garply();
+
  @@ -155,7 +153,7 @@ c.garply();
Declared dependency graph with arrows connecting a, b, and c + alt="Declared dependency graph with arrows connecting a, b, and c">
Declared dependency graph
@@ -164,7 +162,7 @@ c.garply(); 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 + declared dependency graph">
Actual dependency graph
@@ -189,13 +187,12 @@ fault of their own.   -``` -rule( + 
rule(
     name = "b",
     srcs = "b.in",
     deps = "//d:d",
 )
-```
+
@@ -205,12 +202,12 @@ rule(   -``` -import d; -function foo() { - d.baz(); -} -``` + 
+      import d;
+      function foo() {
+        d.baz();
+      }
+
@@ -218,7 +215,7 @@ function foo() {
Declared dependency graph with arrows connecting a and b. - b no longer connects to c, which breaks a's connection to c + b no longer connects to c, which breaks a's connection to c">
Declared dependency graph
@@ -226,7 +223,7 @@ function foo() {
Actual dependency graph that shows a connecting to b and c, - but b no longer connects to c + but b no longer connects to c">
Actual dependency graph
@@ -302,18 +299,15 @@ 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 — +

Not recommended — data = ["//data/regression:unittest/."]

-

- Not recommended — +

Not recommended — data = ["testdata/."]

-

- Not recommended — +

Not recommended — data = ["testdata/"]

@@ -331,8 +325,7 @@ enumerate the set of files contained within them, either explicitly or using the [`glob()`](/versions/9.1.0/reference/be/functions#glob) function. (Use `**` to force the `glob()` to be recursive.) -

- Recommended — +

Recommended — data = glob(["testdata/**"])

@@ -365,3 +358,16 @@ filegroup( You can then reference the label `my_data` as the data dependency in your test. + + + + + +
+ BUILD files + + Visibility +
+ diff --git a/versions/9.1.0/concepts/labels.mdx b/versions/9.1.0/concepts/labels.mdx index f646d7d3..fb5807c8 100644 --- a/versions/9.1.0/concepts/labels.mdx +++ b/versions/9.1.0/concepts/labels.mdx @@ -124,7 +124,7 @@ construct tools and scripts that manipulate labels, such as the The precise details of allowed target names are below. -### Target names — `package-name:target-name` {#target-names} +### Target names — `{{ "" }}package-name{{ "" }}:target-name` {#target-names} `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` @@ -143,7 +143,7 @@ current-directory references (`./`) are forbidden.

Wrong — Do not use .. to refer to files in other packages

Correct — Use - //package-name:filename

+ //{{ "" }}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 @@ -155,7 +155,7 @@ 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` {#package-names} +### Package names — `//package-name:{{ "" }}target-name{{ "" }}` {#package-names} 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. @@ -239,3 +239,16 @@ 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](/versions/9.1.0/query/guide) operates. + + + + + + +
+ Targets + + BUILD files +
diff --git a/versions/9.1.0/contribute/search.mdx b/versions/9.1.0/contribute/search.mdx index 704c230b..c1d38830 100644 --- a/versions/9.1.0/contribute/search.mdx +++ b/versions/9.1.0/contribute/search.mdx @@ -225,8 +225,8 @@ You can refine your search using the following filters. file: -filepath:
-path:
+filepath:
+path:
f: @@ -256,10 +256,10 @@ f: hello -world -`\` +\ Escapes special characters, such as ., \, or (. -`run\(\)` +run\(\) "[term]" diff --git a/versions/9.1.0/docs/android-instrumentation-test.mdx b/versions/9.1.0/docs/android-instrumentation-test.mdx index 7ef394b5..70d87610 100644 --- a/versions/9.1.0/docs/android-instrumentation-test.mdx +++ b/versions/9.1.0/docs/android-instrumentation-test.mdx @@ -54,7 +54,7 @@ bazel info release ``` This results in output similar to the following: -``` +```none {:.devsite-disable-click-to-copy} release 4.1.0 ``` @@ -72,7 +72,7 @@ apt-get install cpu-checker && kvm-ok If it prints the following message, you have the correct configuration: -``` +```none {:.devsite-disable-click-to-copy} INFO: /dev/kvm exists KVM acceleration can be used ``` @@ -93,7 +93,7 @@ which Xvfb ``` The output is the following: -``` +```{:.devsite-disable-click-to-copy} /usr/bin/Xvfb ``` @@ -201,7 +201,7 @@ Here is an example `AndroidTestManifest.xml` for the test app: android:targetSdkVersion="27" /> - {/* ... */} + ``` diff --git a/versions/9.1.0/docs/cc-toolchain-config-reference.mdx b/versions/9.1.0/docs/cc-toolchain-config-reference.mdx index b025aa8c..ba1f531c 100644 --- a/versions/9.1.0/docs/cc-toolchain-config-reference.mdx +++ b/versions/9.1.0/docs/cc-toolchain-config-reference.mdx @@ -133,59 +133,57 @@ support and expansion. These are: - Constraint - Description + Constraint + + Description + - - 
requires = [
-     feature_set (features = [
-     'feature-name-1',
-     'feature-name-2'
-     ]),
-     ]
+ 
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). + 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.

+ 
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.

+ 
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'],
-     ),
-     ]
+ 
with_features = [
+  with_feature_set(
+    features = ['feature-1'],
+    not_features = ['feature-2'],
+  ),
+]
- - Flag set-level. A feature can specify multiple flag sets with multiple. + 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 @@ -224,16 +222,22 @@ that implements an action (such as `CppCompileAction`). In particular, the - Action - Description + Action + + Description + - preprocess-assemble - Assemble with preprocessing. Typically for .S files. + preprocess-assemble + + Assemble with preprocessing. Typically for .S files. + - assemble - Assemble without preprocessing. Typically for .s files. + assemble + + Assemble without preprocessing. Typically for .s files. + @@ -243,25 +247,33 @@ that implements an action (such as `CppCompileAction`). In particular, the - Action - Description + Action + + Description + - cc-flags-make-variable - Propagates CC_FLAGS to genrules. + cc-flags-make-variable + + Propagates CC_FLAGS to genrules. + - c-compile - Compile as C. + c-compile + + Compile as C. + - 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 + 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. @@ -274,20 +286,28 @@ that implements an action (such as `CppCompileAction`). In particular, the - Action - Description + Action + + Description + - c++-link-dynamic-library - Link a shared library containing all of its dependencies. + 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-nodeps-dynamic-library + + Link a shared library only containing cc_library sources. + - c++-link-executable - Link a final ready-to-run library. + c++-link-executable + + Link a final ready-to-run library. + @@ -300,12 +320,16 @@ and encode some semantics into the name. - Action - Description + Action + + Description + - c++-link-static-library - Create a static library (archive). + c++-link-static-library + + Create a static library (archive). + @@ -315,16 +339,22 @@ and encode some semantics into the name. - Action - Description + Action + + Description + - lto-backend - ThinLTO action compiling bitcodes into native objects. + lto-backend + + ThinLTO action compiling bitcodes into native objects. + - lto-index - ThinLTO action generating global index. + lto-index + + ThinLTO action generating global index. + @@ -341,37 +371,39 @@ The `action_config()` constructor has the following parameters: - Attribute - Description + Attribute + + Description + - action_name - - The Bazel action to which this action corresponds. - Bazel uses this attribute to discover per-action tool and execution - requirements. - + 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. + 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. + 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. + env_sets + + A list of environment constraints that applies to a group of actions. + Same as for a feature. @@ -401,18 +433,22 @@ The `tool()` constructor takes in the following parameters: - Field - Description + Field + + Description + - path - Path to the tool in question (relative to the current location). + 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. + with_features + + A list of feature sets out of which at least one must be satisfied + for this tool to apply. @@ -563,7 +599,7 @@ A variable can repeat multiple times. For example: expands to: - `-iprefix= -isystem= -iprefix= -isystem=` + -iprefix= -isystem= -iprefix= -isystem= Variables can correspond to structures accessible using dot-notation. For example: @@ -631,278 +667,323 @@ Note: The **Action** column indicates the relevant action type, if applicable. - - - + + + - + - + - + - + - + - + - + - - + - - + - - + - - + - - + - - + - + - + - + - + - + - + - + - + - + - + - + - + - - + - - + - - + - + - + - - + - - + - + - + - + - + - - + - + - + - - + - + - + - + - + - + - + - + - + - - + - + - + - - + - - + - - + - - + - + - + - + - + - + - + -
VariableActionDescriptionVariable + Action + Description +
source_filesource_file + compileSource file to compile.Source file to compile. +
input_fileinput_file + stripArtifact to strip.Artifact to strip. +
output_fileoutput_file + compile, stripCompilation output.Compilation output. +
output_assembly_fileoutput_assembly_file + compile - Emitted 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. + Emitted 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_fileoutput_preprocess_file + compile - Preprocessed output. Applies only to compile - actions that only preprocess the source files, typically when using the + Preprocessed 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.
includesincludes + compile - Sequence of files the compiler must - unconditionally include in the compiled source. + Sequence of files the compiler must + unconditionally include in the compiled source.
include_pathsinclude_paths + compile - Sequence directories in which the compiler - searches for headers included using #include<foo.h> - and #include "foo.h". + Sequence directories in which the compiler + searches for headers included using #include<foo.h> + and #include "foo.h".
quote_include_pathsquote_include_paths + compile - Sequence of -iquote includes - - directories in which the compiler searches for headers included using - #include "foo.h". + Sequence of -iquote includes - + directories in which the compiler searches for headers included using + #include "foo.h".
system_include_pathssystem_include_paths + compile - Sequence of -isystem includes - - directories in which the compiler searches for headers included using - #include <foo.h>. + Sequence of -isystem includes - + directories in which the compiler searches for headers included using + #include <foo.h>.
dependency_filedependency_file + compileThe .d dependency file generated by the compiler.The .d dependency file generated by the compiler. +
preprocessor_definespreprocessor_defines + compileSequence of defines, such as --DDEBUG.Sequence of defines, such as --DDEBUG. +
picpic + compileCompiles the output as position-independent code.Compiles the output as position-independent code. +
gcov_gcno_filegcov_gcno_file + compileThe gcov coverage file.The gcov coverage file. +
per_object_debug_info_fileper_object_debug_info_file + compileThe per-object debug info (.dwp) file.The per-object debug info (.dwp) file. +
stripoptsstripopts + stripSequence of stripopts.Sequence of stripopts. +
legacy_compile_flagslegacy_compile_flags + compile - Sequence of flags from legacy - CROSSTOOL fields such as compiler_flag, - optional_compiler_flag, cxx_flag, and - optional_cxx_flag. + Sequence of flags from legacy + CROSSTOOL fields such as compiler_flag, + optional_compiler_flag, cxx_flag, and + optional_cxx_flag.
user_compile_flagsuser_compile_flags + compile - Sequence of flags from either the - copt rule attribute or the --copt, - --cxxopt, and --conlyopt flags. + Sequence of flags from either the + copt rule attribute or the --copt, + --cxxopt, and --conlyopt flags.
unfiltered_compile_flagsunfiltered_compile_flags + compile - Sequence of flags from the + Sequence 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. + unfiltered_compile_flags feature. These are not filtered by + the nocopts rule attribute.
sysrootsysroot + The sysroot.The sysroot. +
runtime_library_search_directoriesruntime_library_search_directories + link - Entries in the linker runtime search path (usually - set with the -rpath flag). + Entries in the linker runtime search path (usually + set with the -rpath flag).
library_search_directorieslibrary_search_directories + link - Entries in the linker search path (usually set with - the -L flag). + Entries in the linker search path (usually set with + the -L flag).
libraries_to_linklibraries_to_link + linkFlags providing files to link as inputs in the linker invocation.Flags providing files to link as inputs in the linker invocation. +
def_file_pathdef_file_path + linkLocation of def file used on Windows with MSVC.Location of def file used on Windows with MSVC. +
linker_param_filelinker_param_file + link - Location of linker param file created by bazel to - overcome command line length limit. + Location of linker param file created by bazel to + overcome command line length limit.
output_execpathoutput_execpath + linkExecpath of the output of the linker.Execpath of the output of the linker. +
generate_interface_librarygenerate_interface_library + link - "yes" or "no" depending on whether interface library should - be generated. + "yes" or "no" depending on whether interface library should + be generated.
interface_library_builder_pathinterface_library_builder_path + linkPath to the interface library builder tool.Path to the interface library builder tool. +
interface_library_input_pathinterface_library_input_path + linkInput for the interface library ifso builder tool.Input for the interface library ifso builder tool. +
interface_library_output_pathinterface_library_output_path + linkPath where to generate interface library using the ifso builder tool.Path where to generate interface library using the ifso builder tool. +
legacy_link_flagslegacy_link_flags + linkLinker flags coming from the legacy CROSSTOOL fields.Linker flags coming from the legacy CROSSTOOL fields. +
user_link_flagsuser_link_flags + link - Linker flags coming from the --linkopt - or linkopts attribute. + Linker flags coming from the --linkopt + or linkopts attribute.
linkstamp_pathslinkstamp_paths + linkA build variable giving linkstamp paths.A build variable giving linkstamp paths. +
force_picforce_pic + link - Presence of this variable indicates that PIC/PIE code should + Presence of this variable indicates that PIC/PIE code should be generated (Bazel option `--force_pic` was passed).
strip_debug_symbolsstrip_debug_symbols + link - Presence of this variable indicates that the debug - symbols should be stripped. + Presence of this variable indicates that the debug + symbols should be stripped.
is_cc_testis_cc_test + link - Truthy when current action is a cc_test - linking action, false otherwise. + Truthy when current action is a cc_test + linking action, false otherwise.
is_using_fissionis_using_fission + compile, link - Presence of this variable indicates that fission (per-object debug info) + Presence 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. + of .o files and the compiler and linker need to know this.
fdo_instrument_pathfdo_instrument_path + compile, linkPath to the directory that stores FDO instrumentation profile. Path to the directory that stores FDO instrumentation profile. +
fdo_profile_pathfdo_profile_path + compilePath to FDO profile. Path to FDO profile. +
fdo_prefetch_hints_pathfdo_prefetch_hints_path + compilePath to the cache prefetch profile. Path to the cache prefetch profile. +
cs_fdo_instrument_pathcs_fdo_instrument_path + compile, link - Path to the directory that stores context sensitive FDO - instrumentation profile. + Path to the directory that stores context sensitive FDO + instrumentation profile.
@@ -916,29 +997,35 @@ conditions. - Feature - Documentation + Feature + + Documentation + - opt | dbg | fastbuild - Enabled by default based on compilation mode. + opt | dbg | fastbuild + + Enabled by default based on compilation mode. + - static_linking_mode | dynamic_linking_mode - Enabled by default based on linking 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. - + 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 + 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 @@ -946,25 +1033,25 @@ conditions. - supports_interface_shared_libraries - - If enabled (and the option --interface_shared_objects is + 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 + 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 + 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 @@ -972,21 +1059,24 @@ conditions. - supports_pic - - If enabled, toolchain will know to use PIC objects for dynamic libraries. + 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. + be enabled, `--force_pic` cannot be used. - static_linking_mode | dynamic_linking_mode + + static_linking_mode | dynamic_linking_mode + Enabled by default based on linking mode. - no_legacy_features + no_legacy_features + Prevents Bazel from adding legacy features to the C++ configuration when present. See the complete list of @@ -994,8 +1084,11 @@ conditions. - 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. + 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. + diff --git a/versions/9.1.0/docs/user-manual.mdx b/versions/9.1.0/docs/user-manual.mdx index e3639541..a8b13277 100644 --- a/versions/9.1.0/docs/user-manual.mdx +++ b/versions/9.1.0/docs/user-manual.mdx @@ -39,9 +39,9 @@ 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: @@ -71,14 +71,14 @@ 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} +#### `--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 @@ -96,7 +96,7 @@ 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} +#### `--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 @@ -116,11 +116,13 @@ Here are some typical values for this option: `--output_filter=` - Show everything. + Show everything. + `--output_filter=DONT_MATCH_ANYTHING` - Show nothing. + Show nothing. + @@ -128,7 +130,7 @@ Here are some typical values for this option: These options control which options Bazel will pass to other tools. -#### `--copt=cc-option` {#copt} +#### `--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 @@ -137,9 +139,9 @@ 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. @@ -157,35 +159,35 @@ 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} +#### `--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} +#### `--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} +#### `--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} +#### `--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} +#### `--conlyopt={{ "" }}cc-option{{ "" }}` {#cconlyopt} This option takes an argument which is to be passed to the compiler when compiling C source files. @@ -196,7 +198,7 @@ not to C++ compilation or linking. So you can pass C-specific options 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} +#### `--cxxopt={{ "" }}cc-option{{ "" }}` {#cxxopt} This option takes an argument which is to be passed to the compiler when compiling C++ source files. @@ -207,14 +209,14 @@ not to C compilation or linking. So you can pass C++-specific options 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} +#### `--linkopt={{ "" }}linker-option{{ "" }}` {#linkopt} This option takes an argument which is to be passed to the compiler when linking. @@ -223,9 +225,9 @@ 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 @@ -240,9 +242,9 @@ all binaries and shared libraries, by invoking the linker with the `-Wl,--strip- 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. @@ -264,7 +266,7 @@ pass `--stripopt=--strip-all` and explicitly build the `--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} +#### `--stripopt={{ "" }}strip-option{{ "" }}` {#stripopt} This is an additional option to pass to the `strip` command when generating a [`*.stripped` binary](/versions/9.1.0/reference/be/c-cpp#cc_binary_implicit_outputs). The default @@ -273,7 +275,7 @@ 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} +#### `--fdo_instrument={{ "" }}profile-output-dir{{ "" }}` {#fdo-instrument} The `--fdo_instrument` option enables the generation of FDO (feedback directed optimization) profile output when the @@ -283,16 +285,16 @@ 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` +`--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/`. +`--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} +#### `--fdo_optimize={{ "" }}profile-zip{{ "" }}` {#fdo-optimize} The `--fdo_optimize` option enables the use of the per-object file profile information to perform FDO (feedback @@ -313,66 +315,66 @@ extension. The options `--fdo_instrument` and `--fdo_optimize` cannot be used at the same time. -#### `--java_language_version=version` {#java-language-version} +#### `--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. +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} +#### `--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} +#### `--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`, +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} +#### `--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} +#### `--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} +#### `--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). @@ -381,9 +383,9 @@ 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 @@ -431,7 +433,7 @@ needing to do a full rebuild _every_ time. Debugging information will not be generated in `opt` mode unless you also pass `--copt -g`. -#### `--cpu=cpu` {#cpu} +#### `--cpu={{ "" }}cpu{{ "" }}` {#cpu} This option specifies the target CPU architecture to be used for the compilation of binaries during the build. @@ -440,7 +442,7 @@ 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} +#### `--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 @@ -450,17 +452,17 @@ 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} +#### `--experimental_action_listener={{ "" }}label{{ "" }}` {#experimental-action-listener} Warning: Extra actions are deprecated. Use [aspects](/versions/9.1.0/extending/aspects) instead. The `experimental_action_listener` option instructs Bazel to use -details from the [`action_listener`](/versions/9.1.0/reference/be/extra-actions#action_listener) rule specified by label to +details from the [`action_listener`](/versions/9.1.0/reference/be/extra-actions#action_listener) rule specified by {{ "" }}label{{ "" }} to insert [`extra_actions`](/versions/9.1.0/reference/be/extra-actions#extra_action) into the build graph. -#### `--[no]experimental_extra_action_top_level_only` {#experimental-extra-action-top-level-only} +#### `--[no]experimental_extra_action_top_level_only` {:experimental-extra-action-top-level-only} Warning: Extra actions are deprecated. Use [aspects](/versions/9.1.0/extending/aspects) instead. @@ -469,7 +471,7 @@ 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} +#### `--experimental_extra_action_filter={{ "" }}regex{{ "" }}` {#experimental-extra-action-filter} Warning: Extra actions are deprecated. Use [aspects](/versions/9.1.0/extending/aspects) instead. @@ -489,17 +491,16 @@ 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/... \ +
% bazel build --experimental_action_listener=//test:al //foo/... \
   --experimental_extra_action_filter=.*/bar/.*
-```
+
-#### `--host_cpu=cpu` {#host-cpu} +#### `--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} +#### `--android_platforms={{ "" }}platform[,platform]*{{ "" }}` {#android-platforms} The platforms to build the transitive `deps` of `android_binary` rules (specifically for native dependencies like C++). For @@ -516,7 +517,7 @@ 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} +#### `--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 @@ -557,7 +558,7 @@ to the C++ compiler. If an option contains a `,` it has to be quoted like so 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} +#### `--dynamic_mode={{ "" }}mode{{ "" }}` {#dynamic-mode} Determines whether C++ binaries will be linked dynamically, interacting with the [linkstatic attribute](/versions/9.1.0/reference/be/c-cpp#cc_binary.linkstatic) on build rules. @@ -608,32 +609,32 @@ Selects whether to perform resource shrinking for android_binary rules. Sets the [shrink_resources attribute](/versions/9.1.0/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} +#### `--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} +#### `--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} +#### `--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} +#### `--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} +#### `--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 @@ -643,7 +644,7 @@ specifying this flag. Note: Only certain combinations of crosstool version, compiler version, and target CPU are allowed. -#### `--android_sdk=label` {#android-sdk} +#### `--android_sdk={{ "" }}label{{ "" }}` {#android-sdk} Deprecated. This shouldn't be directly specified. @@ -654,19 +655,19 @@ 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} +#### `--java_toolchain={{ "" }}label{{ "" }}` {#java-toolchain} No-op. Kept only for backwards compatibility. -#### `--host_java_toolchain=label` {#host-java-toolchain} +#### `--host_java_toolchain={{ "" }}label{{ "" }}` {#host-java-toolchain} No-op. Kept only for backwards compatibility. -#### `--javabase=(label)` {#javabase} +#### `--javabase=({{ "" }}label{{ "" }})` {#javabase} No-op. Kept only for backwards compatibility. -#### `--host_javabase=label` {#host-javabase} +#### `--host_javabase={{ "" }}label{{ "" }}` {#host-javabase} No-op. Kept only for backwards compatibility. @@ -677,7 +678,7 @@ 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} +#### `--spawn_strategy={{ "" }}strategy{{ "" }}` {#spawn-strategy} This option controls where and how commands are executed. @@ -694,7 +695,7 @@ This option controls where and how commands are executed. * `remote` causes commands to be executed remotely; this is only available if a remote executor has been configured separately. -#### `--strategy mnemonic=strategy` {#strategy} +#### `--strategy {{ "" }}mnemonic{{ "" }}={{ "" }}strategy{{ "" }}` {#strategy} This option controls where and how commands are executed, overriding the [--spawn_strategy](#spawn-strategy) (and @@ -703,7 +704,7 @@ Genrule) on a per-mnemonic basis. See [--spawn_strategy](#spawn-strategy) for the supported strategies and their effects. -#### `--strategy_regexp==` {#strategy-regexp} +#### `--strategy_regexp={{ "" }}={{ "" }}` {#strategy-regexp} This option specifies which strategy should be used to execute commands that have descriptions matching a certain `regex_filter`. See @@ -725,11 +726,11 @@ other flags for specifying strategy. 'Compiling //foo/bar/baz' with the `local` strategy and falls back to `sandboxed` if it fails. -#### `--genrule_strategy=strategy` {#genrule-strategy} +#### `--genrule_strategy={{ "" }}strategy{{ "" }}` {#genrule-strategy} -This is a deprecated short-hand for `--strategy=Genrule=strategy`. +This is a deprecated short-hand for `--strategy=Genrule={{ "" }}strategy{{ "" }}`. -#### `--jobs=n` (-j) {#jobs} +#### `--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 @@ -743,7 +744,7 @@ 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} +#### `--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 @@ -757,7 +758,7 @@ 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} +#### `--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 @@ -780,7 +781,7 @@ 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`. +`$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 @@ -923,10 +924,10 @@ 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) +your [`--show_result {{ "" }}n{{ "" }}`](#show-result) setting is high enough. -#### `--build_tag_filters=tag[,tag]*` {#build-tag-filters} +#### `--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 @@ -938,7 +939,7 @@ 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} +#### `--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 @@ -946,21 +947,21 @@ 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} +#### `--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 @@ -971,7 +972,7 @@ for example syntax. By default, test timeout filtering is not applied. -#### `--test_tag_filters=tag[,tag]*` {#test-tag-filters} +#### `--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 @@ -982,9 +983,9 @@ 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. @@ -993,7 +994,7 @@ 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} +#### `--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 @@ -1001,17 +1002,17 @@ 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. @@ -1027,14 +1028,14 @@ 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} +#### `--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 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, @@ -1045,7 +1046,7 @@ but not all frameworks support it. These options control the verbosity of Bazel's output, either to the terminal, or to additional log files. -#### `--explain=logfile` {#explain} +#### `--explain={{ "" }}logfile{{ "" }}` {#explain} This option, which requires a filename argument, causes the dependency checker in `bazel build`'s execution phase to @@ -1078,7 +1079,7 @@ generated explanation file and the performance penalty of using If `--explain` is not enabled, then `--verbose_explanations` has no effect. -#### `--profile=file` {#profile} +#### `--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 @@ -1095,14 +1096,14 @@ messages. If it is disabled, the messages won't be shown. 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} +#### `--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. +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} +#### `--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 @@ -1147,12 +1148,12 @@ during execution can be examined. 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'] +

+  >>>>> # //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. @@ -1188,7 +1189,7 @@ binaries, such as the source control revision or other workspace-related informa this mechanism with rules that support the `stamp` attribute, such as `genrule`, `cc_binary`, and more. -#### `--workspace_status_command=program` {#workspace-status-command} +#### `--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. @@ -1250,13 +1251,13 @@ If the workspace status command fails (exits non-zero) for any reason, the build 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. @@ -1287,16 +1288,16 @@ control what execution platforms and toolchains are available to Bazel rules. Please see background information on [Platforms](/versions/9.1.0/extending/platforms) and [Toolchains](/versions/9.1.0/extending/toolchains). -#### `--platforms=labels` {#platforms} +#### `--platforms={{ "" }}labels{{ "" }}` {#platforms} The labels of the platform rules describing the target platforms for the current command. -#### `--host_platform=label` {#host-platform} +#### `--host_platform={{ "" }}label{{ "" }}` {#host-platform} The label of a platform rule that describes the host system. -#### `--extra_execution_platforms=labels` {#extra-execution-platforms} +#### `--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 @@ -1305,14 +1306,14 @@ platforms will be considered before those declared in MODULE.bazel files by 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} +#### `--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()](/versions/9.1.0/rules/lib/globals/module#register_toolchains). -#### `--toolchain_resolution_debug=regex` {#toolchain-resolution-debug} +#### `--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 @@ -1321,13 +1322,13 @@ of Bazel or Starlark rules with debugging failures due to missing toolchains. ### Miscellaneous {#miscellaneous} -#### `--flag_alias=alias_name=target_path` {#flag-alias} +#### `--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](/versions/9.1.0/extending/config#using-build-setting-aliases). -#### `--symlink_prefix=string` {#symlink-prefix} +#### `--symlink_prefix={{ "" }}string{{ "" }}` {#symlink-prefix} Changes the prefix of the generated convenience symlinks. The default value for the symlink prefix is `bazel-` which @@ -1355,7 +1356,7 @@ Some common values of this option: `--symlink_prefix=.bazel/` will cause Bazel to create symlinks called `bin` (etc) inside a hidden directory `.bazel`. -#### `--platform_suffix=string` {#platform-suffix} +#### `--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 @@ -1363,7 +1364,7 @@ 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} +#### `--default_visibility={{ "" }}(private|public){{ "" }}` {#default-visibility} Temporary flag for testing bazel default visibility changes. Not intended for general use but documented for completeness' sake. @@ -1378,7 +1379,7 @@ 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
@@ -1394,7 +1395,7 @@ Showing nodes accounting for 3.34s, 100% of 3.34s total
          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`. @@ -1507,7 +1508,7 @@ 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} +#### `--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 @@ -1522,7 +1523,7 @@ default), only a single attempt is allowed for regular tests, and 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} +#### `--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 @@ -1551,7 +1552,7 @@ 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} +#### `--test_summary={{ "" }}output_style{{ "" }}` {#test-summary} Specifies how the test result summary should be displayed. @@ -1564,7 +1565,7 @@ Specifies how the test result summary should be displayed. only each test. The names of test output files are omitted. * `none` does not print test summary. -#### `--test_output=output_style` {#test-output} +#### `--test_output={{ "" }}output_style{{ "" }}` {#test-output} Specifies how test output should be displayed: @@ -1595,7 +1596,7 @@ information (such as test attempts) to be printed to the test summary. If 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} +#### `--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 @@ -1605,7 +1606,7 @@ 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} +#### `--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 @@ -1627,7 +1628,7 @@ 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} +#### `--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, @@ -1645,21 +1646,21 @@ 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} +#### `--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 +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} +#### `--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 +{{ "" }}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. @@ -1672,18 +1673,18 @@ 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). + 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} @@ -1706,7 +1707,7 @@ 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...
@@ -1719,7 +1720,7 @@ it is used to build _and run_ a single target. Here is a typical session
   $EXEC_ROOT/java/myapp/myapp
   --arg1
   --arg2
-```
+
Note: `--` is needed so that Bazel does not interpret `--arg1` and `--arg2` as @@ -1757,7 +1758,7 @@ a user-friendly way. ### Options for `bazel run` {#bazel-run-options} -#### `--run_under=command-prefix` {#run-run-under} +#### `--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)), @@ -1807,9 +1808,9 @@ stops the Bazel server after the clean, equivalent to the [`shutdown`](#shutdown 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 @@ -1862,9 +1863,9 @@ 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} @@ -1901,7 +1902,7 @@ that do not correspond to commands. #### `--[no]long` (`-l`) {#long} -By default, `bazel help [topic]` prints only a +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. @@ -1934,7 +1935,7 @@ the Bazel server instance, or with a specific build configuration. 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 +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`: @@ -1993,10 +1994,9 @@ through `sed -ne /key:/s/key://p`: Example: the process ID of the Bazel server. -``` -% bazel info server_pid +
% bazel info server_pid
 1285
-```
+
#### Configuration-specific data {#configuration-specific-data} @@ -2028,22 +2028,21 @@ 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 +
% 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} @@ -2121,30 +2120,29 @@ How the app should be started after installing it. Supported _start_type_s are: Note: If more than one of `--start=_start_type_`, `--start_app` or `--debug_app` is set, the last value is used. -#### `--adb=path` {#adb} +#### `--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} +#### `--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 -``` +
% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef
+
invokes `adb` as -``` +
 adb -s deadbeef install ...
-```
+
-#### `--incremental_install_verbosity=number` {#incremental-install-verbosity} +#### `--incremental_install_verbosity={{ "" }}number{{ "" }}` {#incremental-install-verbosity} The verbosity for incremental install. Set to 1 for debug logging to be printed to the console. @@ -2189,7 +2187,7 @@ 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>
@@ -2204,7 +2202,7 @@ Example:
     --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
     dump --skylark_memory=$HOME/prof.gz
     % pprof -flame $HOME/prof.gz
-```
+
### `analyze-profile` {#analyze-profile} @@ -2229,11 +2227,11 @@ _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} @@ -2248,7 +2246,7 @@ All of the options described in this section must be specified using the 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} +#### `--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 @@ -2269,10 +2267,10 @@ 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 @@ -2285,7 +2283,7 @@ 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} +#### `--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, @@ -2307,15 +2305,15 @@ 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} +#### `--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 @@ -2326,14 +2324,14 @@ This flag was previously named `--host_javabase` (sometimes referred to as the build flag [--host_javabase](#host-javabase) (sometimes referred to as the 'right-hand side' `--host_javabase`). -#### `--host_jvm_args=string` {#host-jvm-args} +#### `--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, @@ -2392,7 +2390,7 @@ for the purpose of build isolation, you should use the command option 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} +#### `--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 @@ -2440,7 +2438,7 @@ 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} +#### `--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. @@ -2473,7 +2471,7 @@ 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} +#### `--config={{ "" }}name{{ "" }}` {#config} Selects additional config section from [the rc files](/versions/9.1.0/run/bazelrc#bazelrc-file-locations); for the current `command`, diff --git a/versions/9.1.0/extending/config.mdx b/versions/9.1.0/extending/config.mdx index 86aa680e..6af106d3 100644 --- a/versions/9.1.0/extending/config.mdx +++ b/versions/9.1.0/extending/config.mdx @@ -424,7 +424,7 @@ hot_chocolate_transition = transition( 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 +`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 diff --git a/versions/9.1.0/external/migration_tool.mdx b/versions/9.1.0/external/migration_tool.mdx index ed2250c9..b8fc6c09 100644 --- a/versions/9.1.0/external/migration_tool.mdx +++ b/versions/9.1.0/external/migration_tool.mdx @@ -366,7 +366,7 @@ bazel_dep(name = "rules_shell", version = "0.6.1") -
+
@@ -427,7 +427,7 @@ go_deps.gazelle_override(
-
+
@@ -477,7 +477,7 @@ python.toolchain(python_version = "3.11")
-
+
@@ -529,7 +529,7 @@ maven.artifact(
-
+
@@ -560,7 +560,7 @@ http_archive(
-
+
@@ -593,7 +593,7 @@ extension_for_my_custom_macro = module_extension(implementation = _extension_for
-
+
## Tips with debugging {#migration-tool-tips} diff --git a/versions/9.1.0/external/mod-command.mdx b/versions/9.1.0/external/mod-command.mdx index 244507e2..c8968973 100644 --- a/versions/9.1.0/external/mod-command.mdx +++ b/versions/9.1.0/external/mod-command.mdx @@ -138,7 +138,7 @@ The following options only affect the subcommands that print graphs (`graph`, legacy platforms which cannot use Unicode. * `--output `: Include information about the module extension usages as - part of the output graph. `` can be one of: + part of the output graph. `' can be one of: * `text` *(default)*: A human-readable representation of the output graph (flattened as a tree). @@ -213,7 +213,7 @@ use_repo(toolchains, my_jdk="remotejdk17_linux") Graph Before Resolution
Graph Before Resolution
-{/* digraph mygraph { +
Graph After Resolution
Graph After Resolution
-{/* digraph mygraph { + diff --git a/versions/9.1.0/external/registry.mdx b/versions/9.1.0/external/registry.mdx index 2b62adbe..5cd57320 100644 --- a/versions/9.1.0/external/registry.mdx +++ b/versions/9.1.0/external/registry.mdx @@ -134,13 +134,14 @@ field, which defaults to `archive`. ## Bazel Central Registry {#bazel-central-registry} -The Bazel Central Registry (BCR) at https://bcr.bazel.build/ is an index +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 https://registry.bazel.build/. +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]. +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 diff --git a/versions/9.1.0/query/language.mdx b/versions/9.1.0/query/language.mdx index e984021d..f78b32d0 100644 --- a/versions/9.1.0/query/language.mdx +++ b/versions/9.1.0/query/language.mdx @@ -103,7 +103,7 @@ tokens: 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. ``` @@ -259,14 +259,14 @@ the [`allrdeps`](#allrdeps) and 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)" ``` @@ -274,7 +274,7 @@ 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)))" ``` @@ -303,7 +303,7 @@ it is faster and uses less memory. 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) @@ -364,7 +364,7 @@ of the result nodes against other nodes.) For more details, see the ### Variables {#variables} -``` +```none {:.devsite-disable-click-to-copy} expr ::= let name = expr1 in expr2 | $name ``` @@ -402,7 +402,7 @@ efficient query evaluation. ### Parenthesized expressions {#parenthesized-expressions} -``` +```none {:.devsite-disable-click-to-copy} expr ::= (expr) ``` @@ -411,7 +411,7 @@ 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 @@ -455,7 +455,7 @@ query expression. ### Read targets from an external source: set {#set} -``` +```none {:.devsite-disable-click-to-copy} expr ::= set(word *) ``` @@ -469,7 +469,7 @@ that text file using other programs (such as standard UNIX shell tools), and the 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 ... ')' ``` @@ -522,7 +522,7 @@ functions are available: ### Transitive closure of dependencies: deps {#deps} -``` +```none {:.devsite-disable-click-to-copy} expr ::= deps(expr) | deps(expr, depth) ``` @@ -552,7 +552,7 @@ 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) ``` @@ -663,7 +663,7 @@ See the section on [graph order](#graph-order) for more details. Somepath
somepath(S1 + S2, E), one possible result.
-{/* digraph somepath1 { +
Somepath
somepath(S1 + S2, E), another possible result.
-{/* digraph somepath2 { +
Allpaths
allpaths(S1 + S2, E)
-{/* digraph allpaths { + @@ -1041,7 +1041,7 @@ 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 ``` @@ -1277,7 +1277,8 @@ 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)). +`--[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. @@ -1366,9 +1367,7 @@ 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 -``` +```--output package``` This option prints the name of all packages to which some target in the result set belongs. The names are printed in @@ -1386,9 +1385,7 @@ out in order to build a given set of targets. ### Display a graph of the result {#display-result-graph} -``` ---output 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 @@ -1434,9 +1431,7 @@ unless `--output=graph` is being used. ### XML {#xml} -``` ---output 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 @@ -1446,8 +1441,8 @@ form. The output starts with an XML header such as this ``` -{/* The docs should continue to document version 2 into perpetuity, - even if we add new formats, to handle clients synced to old CLs. */} + and then continues with an XML element for each target in the result graph, in topological order (unless diff --git a/versions/9.1.0/reference/flag-cheatsheet.mdx b/versions/9.1.0/reference/flag-cheatsheet.mdx index 6abfef35..08f53736 100644 --- a/versions/9.1.0/reference/flag-cheatsheet.mdx +++ b/versions/9.1.0/reference/flag-cheatsheet.mdx @@ -1,3 +1,10 @@ + + + + + + + --- title: 'Bazel flag cheat sheet' --- @@ -5,6 +12,22 @@ title: 'Bazel flag cheat sheet' Navigating Bazel's extensive list of command line flags can be a challenge. This page focuses on the most crucial flags you'll need to know. + +