--- layout: documentation title: User Manual ---

Commands and Options

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 the "Specifying targets to build" section of the User's Guide.

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

Options that affect how packages are located

--package_path

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, we recommend that you specify it in your Bazel configuration file 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 WORKSPACE
  % bazel build --package_path /some/other/path //foo

Error checking options

These options control Bazel's error-checking and/or warnings.

--check_constraint constraint

This option takes an argument that specifies which constraint should be checked.

Bazel performs special checks on each rule that is annotated with the given constraint.

The supported constraints and their checks are as follows:

--[no]check_visibility

If this option is set to false, visibility checks are demoted to warnings. The default value of this option is true, so that by default, visibility checking is done.

--output_filter regex

The --output_filter option will only show build and compilation warnings for targets that match the regular expression. If a target does not match the given regular expression and its execution succeeds, its standard output and standard error are thrown away.

Here are some typical values for this option:

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

Flags options

These options control which options Bazel will pass to other tools.

--copt cc-option

This option takes an argument which is to be passed to the compiler. The argument will be passed to the compiler whenever it is invoked for preprocessing, compiling, and/or assembling C, C++, or assembler code. It will not be passed when linking.

This option can be used multiple times. For example:

  % bazel build --copt="-g0" --copt="-fpic" //foo

will compile the foo library without debug tables, generating position-independent code.

Note that changing --copt settings will force a recompilation of all affected object files. Also note that copts values listed in specific cc_library or cc_binary build rules will be placed on the compiler command line after these options.

Warning: C++-specific options (such as -fno-implicit-templates) should be specified in --cxxopt, not in --copt. Likewise, C-specific options (such as -Wstrict-prototypes) should be specified in --conlyopt, not in copt. Similarly, compiler options that only have an effect at link time (such as -l) should be specified in --linkopt, not in --copt.

--host_copt cc-option

This option takes an argument which is to be passed to the compiler for source files that are compiled in the host configuration. This is analogous to the --copt option, but applies only to the host configuration.

--host_cxxopt cc-option

This option takes an argument which is to be passed to the compiler for C++ source files that are compiled in the host configuration. This is analogous to the --cxxopt option, but applies only to the host configuration.

--conlyopt cc-option

This option takes an argument which is to be passed to the compiler when compiling C source files.

This is similar to --copt, but only applies to C compilation, not to C++ compilation or linking. So you can pass C-specific options (such as -Wno-pointer-sign) using --conlyopt.

Note that copts parameters listed in specific cc_library or cc_binary build rules will be placed on the compiler command line after these options.

--cxxopt cc-option

This option takes an argument which is to be passed to the compiler when compiling C++ source files.

This is similar to --copt, but only applies to C++ compilation, not to C compilation or linking. So you can pass C++-specific options (such as -fpermissive or -fno-implicit-templates) using --cxxopt. For example:

  % bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code

Note that copts parameters listed in specific cc_library or cc_binary build rules will be placed on the compiler command line after these options.

--linkopt linker-option

This option takes an argument which is to be passed to the compiler when linking.

This is similar to --copt, but only applies to linking, not to compilation. So you can pass compiler options that only make sense at link time (such as -lssp or -Wl,--wrap,abort) using --linkopt. For example:

  % bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code

Build rules can also specify link options in their attributes. This option's settings always take precedence. Also see cc_library.linkopts.

--strip (always|never|sometimes)

This option determines whether Bazel will strip debugging information from all binaries and shared libraries, by invoking the linker with the -Wl,--strip-debug option. --strip=always means always strip debugging information. --strip=never means never strip debugging information. The default value of --strip=sometimes means strip iff the --compilation_mode is fastbuild.

  % bazel build --strip=always //foo:bar

will compile the target while stripping debugging information from all generated binaries.

Note that 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.

Note also that 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.

--stripopt strip-option

An additional option to pass to the strip command when generating a *.stripped binary. The default is -S -p. This option can be used multiple times.

Note that --stripopt does not apply to the stripping of the main binary with --strip=(always|sometimes).

--fdo_instrument profile-output-dir

The --fdo_instrument option enables the generation of FDO (feedback directed optimization) profile output when the built C/C++ binary is executed. For GCC, the argument provided is used as a directory prefix for a per-object file directory tree of .gcda files containing profile information for each .o file.

Once the profile data tree has been generated, the profile tree should be zipped up, and provided to the --fdo_optimize=profile-zip Bazel option to enable the FDO optimized compilation.

For the LLVM compiler the argument is also the directory under which the raw LLVM profile data file(s) is dumped, e.g. --fdo_instrument=/path/to/rawprof/dir/.

The options --fdo_instrument and --fdo_optimize cannot be used at the same time.

--fdo_optimize profile-zip

The --fdo_optimize option enables the use of the per-object file profile information to perform FDO (feedback directed optimization) optimizations when compiling. For GCC, the argument provided is the zip file containing the previously-generated file tree of .gcda files containing profile information for each .o file.

Alternatively, the argument provided can point to an auto profile identified by the extension .afdo.

Note that 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.

--[no]output_symbol_counts

If enabled, each gold-invoked link of a C++ executable binary will output a symbol counts file (via the --print-symbol-counts gold option). For each linker input, the file logs the number of symbols that were defined and the number of symbols that were used in the binary. This information can be used to track unnecessary link dependencies. The symbol counts file is written to the binary's output path with the name [targetname].sc.

This option is disabled by default.

--jvmopt jvm-option

This option allows option arguments to be passed to the Java VM. It can be used with one big argument, or multiple times with individual arguments. For example:

  % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all

will use the server VM for launching all Java binaries and set the startup heap size for the VM to 256 MB.

--javacopt javac-option

This option allows option arguments to be passed to javac. It can be used with one big argument, or multiple times with individual arguments. For example:

  % bazel build --javacopt="-g:source,lines" //myprojects:prog

will rebuild a java_binary with the javac default debug info (instead of the bazel default).

The option is passed to javac after the Bazel built-in default options for javac and before the per-rule options. The last specification of any option to javac wins. The default options for javac are:

  -source 8 -target 8 -encoding UTF-8

Note that 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.

-extra_checks[:(off|on)]

This javac option enables extra correctness checks. Any problems found will be presented as errors. Either -extra_checks or -extra_checks:on may be used to force the checks to be turned on. -extra_checks:off completely disables the analysis. When this option is not specified, the default behavior is used.

--strict_java_deps (default|strict|off|warn|error)

This option controls whether javac checks for missing direct dependencies. Java targets must explicitly declare all directly used targets as dependencies. This flag instructs javac to determine the jars actually used for type checking each java file, and warn/error if they are not the output of a direct dependency of the current target.

Semantics options

These options affect the build commands and/or the output file contents.

--compilation_mode (fastbuild|opt|dbg) (-c)

This option 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.

--cpu cpu

This option specifies the target CPU architecture to be used for the compilation of binaries during the build.

Note that 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.

--experimental_action_listener=label

The experimental_action_listener option instructs Bazel to use details from the action_listener rule specified by label to insert extra_actions into the build graph.

--[no]experimental_extra_action_top_level_only

If this option is set to true, extra actions specified by the --experimental_action_listener command line option will only be scheduled for top level targets.

--experimental_extra_action_filter=regex

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

By default all extra_actions in the transitive closure of the requested targets-to-build get scheduled for execution. --experimental_extra_action_filter will restrict scheduling to extra_actions of which the owner's label matches the specified regular expression.

The following example will limit scheduling of extra_actions to only apply to actions of which the owner's label contains '/bar/':

% bazel build --experimental_action_listener=//test:al //foo/... \
  --experimental_extra_action_filter=.*/bar/.*

--host_cpu cpu

This option specifies the name of the CPU architecture that should be used to build host tools.

--fat_apk_cpu cpu[,cpu]*

The CPUs to build C/C++ libraries for in the transitive deps of android_binary rules. Other C/C++ rules are not affected. For example, if a cc_library appears in the transitive deps of an android_binary rule and a cc_binary rule, the cc_library will be built at least twice: once for each CPU specified with --fat_apk_cpu for the android_binary rule, and once for the CPU specified with --cpu for the cc_binary rule.

The default is armeabi-v7a.

One .so file will be created and packaged in the APK for each CPU specified with --fat_apk_cpu. The name of the .so file will be the name of the android_binary rule prefixed with "lib", e.g., if the name of the android_binary is "foo", then the file will be libfoo.so.

Note that an Android-compatible crosstool must be selected. If an android_ndk_repository rule is defined in the WORKSPACE file, an Android-compatible crosstool is automatically selected. Otherwise, the crostool can be selected using the --android_crosstool_top or --crosstool_top flags.

--per_file_copt [+-]regex[,[+-]regex]...@option[,option]...

When present, any C++ file with a label or an execution path matching one of the inclusion regex expressions and not matching any of the exclusion expressions will be built with the given options. The label matching uses the canonical form of the label (i.e //package:label_name). The execution path is the relative path to your workspace directory including the base name (including extension) of the C++ file. It also includes any platform dependent prefixes. Note, that if only one of the label or the execution path matches the options will be used.

Notes: To match the generated files (e.g. 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. I.e. it is possible to compile with --compilation_mode=opt and selectively compile some files with stronger optimization turned on, or with optimization disabled.

Caveat: If some files are selectively compiled with debug symbols the symbols might be stripped during linking. This can be prevented by setting --strip=never.

Syntax: [+-]regex[,[+-]regex]...@option[,option]... Where regex stands for a regular expression that can be prefixed with a + to identify include patterns and with - to identify exclude patterns. option stands for an arbitrary option that is passed to the C++ compiler. If an option contains a , it has to be quoted like so \,. Options can also contain @, since only the first @ is used to separate regular expressions from options.

Example: --per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs adds the -O0 and the -fprofile-arcs options to the command line of the C++ compiler for all .cc files in //foo/ except file.cc.

--dynamic_mode mode

Determines whether C++ binaries will be linked dynamically, interacting with the linkstatic attribute on build rules.

Modes:

--fission (yes|no|[dbg][,opt][,fastbuild])

Enables Fission, 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 dbg.

--force_ignore_dash_static

If this flag is set, any -static options in linkopts of cc_* rules BUILD files are ignored. This is only intended as a workaround for C++ hardening builds.

--[no]force_pic

If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce position-independent executables ("-pie"). Default is disabled.

Note that dynamically linked binaries (i.e. --dynamic_mode fully) generate PIC code regardless of this flag's setting. So this flag is for cases where users want PIC code explicitly generated for static links.

--android_resource_shrinking

Selects whether to perform resource shrinking for android_binary rules. Sets the default for the shrink_resources attribute on android_binary rules; see the documentation for that rule for further details. Defaults to off.

--custom_malloc malloc-library-target

When specified, always use the given malloc implementation, overriding all malloc="target" attributes, including in those targets that use the default (by not specifying any malloc).

--crosstool_top label

This option specifies the location of the crosstool compiler suite to be used for all C++ compilation during a build. Bazel will look in that location for a CROSSTOOL file and uses that to automatically determine settings for --compiler.

--host_crosstool_top label

If not specified, bazel uses the value of --crosstool_top to compile code in the host configuration, i.e., tools run during the build. The main purpose of this flag is to enable cross-compilation.

--apple_crosstool_top label

The crosstool to use for compiling C/C++ rules in the transitive deps of objc_*, ios__*, and apple_* rules. For those targets, this flag overwrites --crosstool_top.

--android_crosstool_top label

The crosstool to use for compiling C/C++ rules in the transitive deps of android_binary rules. This is useful if other targets in the build require a different crosstool. The default is to use the crosstool generated by the android_ndk_repository rule in the WORKSPACE file. See also --fat_apk_cpu.

--compiler version

This option specifies the C/C++ compiler version (e.g. 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 that only certain combinations of crosstool version, compiler version, and target CPU are allowed.

--android_sdk label

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

This option specifies the label of the java_toolchain used to compile Java source files.

--host_java_toolchain label

If not specified, bazel uses the value of --java_toolchain to compile code in the host configuration, i.e., tools run during the build. The main purpose of this flag is to enable cross-compilation.

--javabase (label)

This option sets the label of the base Java installation to use for bazel run, bazel test, and for Java binaries built by java_binary and java_test rules. The JAVABASE and JAVA "Make" variables are derived from this option.

--host_javabase label

This option sets the label of the base Java installation to use in the host configuration, for example for host build tools including JavaBuilder and Singlejar.

This does not select the Java compiler that is used to compile Java source files. The compiler can be selected by settings the --java_toolchain option.

Build strategy options

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 on the build.

--spawn_strategy strategy

This option controls where and how commands are executed.

--strategy mnemonic=strategy

This option controls where and how commands are executed, overriding the default setting on a per-mnemonic basis. See --spawn_strategy for the supported strategies and their effects.

--strategy_regexp <filter,filter,...>=<strategy>

This option specifies which strategy should be used to execute commands that have descriptions matching a certain regex_filter. See --per_file_copt for details on regex_filter matching. See --spawn_strategy for the supported strategies and their effects.

The first regex_filter that matches the description is used. This option overrides other flags for specifying strategy.

--genrule_strategy strategy

This is a deprecated short-hand for --strategy=Genrule=strategy.