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.
--package_path
--deleted_packages
Error checking options
--check_constraint constraint
Bazel performs special checks on each rule that is annotated with the given constraint.
The supported constraints and their checks are as follows:
public
: Verify that all java_libraries marked withconstraints = ['public']
only depend on java_libraries that are marked asconstraints = ['public']
too. If bazel finds a dependency that does not conform to this rule, bazel will issue an error.
--[no]check_visibility
--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.
--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/':
--experimental_extra_action_filter=.*/bar/.*
--output_filter regex
--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. This option is intended to be used to help focus efforts on fixing warnings in packages under development. Here are some typical values for this option:
--output_filter= | Show all output. |
--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=DONT_MATCH_ANYTHING | Don't show output. |
--[no]analysis_warnings_as_errors
--copt gcc-option
% 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 gcc 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, gcc options that only have an effect at link time (such as -l
) should be specified in --linkopt
, not in --copt
.
--host_copt gcc-option
--copt
option, but applies only to the host configuration.
--conlyopt gcc-option
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 gcc command line after these options.
--cxxopt gcc-option
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 gcc command line after these options.
--linkopt linker-option
This is similar to --copt
, but only applies to linking, not to compilation. So you can pass gcc 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 seecc_library.linkopts.
--strip (always|never|sometimes)
-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.
--lipo (off|binary)
The --lipo=binary
option enables LIPO (Lightweight Inter-Procedural Optimization). LIPO is an extended C/C++ optimization technique that optimizes code across different object files. It involves compiling each C/C++ source file differently for every binary. This is in contrast to normal compilation where compilation outputs are reused. This means that LIPO is more expensive than normal compilation.
This option only has an effect when FDO is also enabled (see the --fdo_instrument and --fdo_options). Currently LIPO is only supported when building a single cc_binary
rule.
Setting --lipo=binary
implicitly sets --dynamic_mode=off
.
--lipo_context context-binary
Specifies the label of a cc_binary
rule that was used to generate the profile information for LIPO that was given to the --fdo_optimize
option.
Specifying the context is mandatory when --lipo=binary
is set. Using this option implicitly also sets --linkopt=-Wl,--warn-unresolved-symbols
.
--[no]output_symbol_counts
If enabled, each gold-invoked link of a C++ executable binary will also output a symbol counts file (via the --print-symbol-counts
gold option) that logs the number of symbols from each .o input that were used in the binary. This 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
% 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
% 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 afterthese options.
-extra_checks[:(off|on)]
-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)
off
means checking is disabled.warn
means javac will generate standard java warnings of type[strict]
for each missing direct dependency.default
,strict
anderror
all mean javac will generate errors instead of warnings, causing the current target to fail to build if any missing direct dependencies are found. This is also the default behavior when the flag is unspecified.
--javawarn (all|cast|deprecation|empty|unchecked|fallthrough|path|rawtypes|serial|finally|overrides)
For example:
% bazel build --javawarn="deprecation" --javawarn="unchecked" //java/...
--javawarn
settings will force a recompilation of all affected classes.
Semantics options
--compilation_mode (fastbuild|opt|dbg)
(-c)
fastbuild
,
dbg
or
opt
, and affects various C/C++ code-generation options, such as the level of optimization and the completeness of debug tables. Bazel uses a different output directory for each different compilation mode, so you can switch between modes without needing to do a full rebuild
every time.
fastbuild
means build as fast as possible: generate minimal debugging information (-gmlt -Wl,-S
), and don't optimize. This is the default. Note:-DNDEBUG
will not be set.dbg
means build with debugging enabled (-g
), so that you can use gdb (or another debugger).opt
means build with optimization enabled and withassert()
calls disabled (-O2 -DNDEBUG
). Debugging information will not be generated inopt
mode unless you also pass--copt -g
.
--cpu cpu
Note that a particular combination of crosstool version, compiler version, libc version, and target CPU is allowed only if it has been specified in the currently used CROSSTOOL file.
--host_cpu cpu
--experimental_skip_static_outputs
--experimental_skip_static_outputs
option causes all statically-linked C++ binaries to
not be output in any meaningful way.
If you set this flag, you must also set --distinct_host_configuration
. It is also inherently incompatible with running tests — don't use it for that. This option is experimental and may go away at any time.
--per_file_copt [+-]regex[,[+-]regex]...@option[,option]...
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
Modes:
auto
: Translates to a platform-dependent mode;default
for linux andoff
for cygwin.default
: Allows bazel to choose whether to link dynamically. See linkstatic for more information.fully
: Links all targets dynamically. This will speed up linking time, and reduce the size of the resulting binaries.off
: Links all targets in mostly static mode. If-static
is set in linkopts, targets will change to fully static.
--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.
--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.
--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, libc version, and target CPU are allowed.
--glibc version
This option specifies the version of glibc that the target should be linked against. If you want to build with a custom crosstool, you should use a CROSSTOOL file instead of specifying this flag. In that case, Bazel will use the CROSSTOOL file and the following options where appropriate:
Note that only certain combinations of crosstool version, compiler version, glibc version, and target CPU are allowed.
--java_toolchain label
This option specifies the label of the java_toolchain used to compile Java source files.
--javabase (path|label)
This option sets the label or the path of the base Java installation to use for running JavaBuilder, SingleJar, for bazel run and bazel test, and for Java binaries built by java_binary
and java_test
rules. A path must be to a JDK or JRE directory that contains bin/java
. The various "Make" variables for Java (JAVABASE
, JAVA
, JAVAC
andJAR
) are derived from this option.
--java_toolchain
option.
--expunge
option. When executed with
--expunge
, the clean command simply removes the entire output base tree which, in addition to the build output, contains all temp files created by Bazel. It also stops the Bazel server after the clean, equivalent to the
shutdown
command. For example, to clean up all disk and memory traces of a Bazel instance, you could specify:
clean
command, analogous to that of Make. It deletes the output directories for all build configurations performed by this Bazel instance, or the entire working tree created by this Bazel instance, and resets internal caches. If executed without any command-line options, then the output directory for all configurations will be cleaned.
clean
command will delete all outputs from all builds you've done with that Bazel instance in that workspace.
clean
command is provided primarily as a means of reclaiming disk space for workspaces that are no longer needed. However, we recognize that Bazel's incremental rebuilds might not be perfect;
clean
may be used to recover a consistent state when problems arise.
The first is loading during which all the necessary BUILD files for the initial targets, and their transitive closure of dependencies, are loaded, parsed, evaluated and cached.
For the first build after a Bazel server is started, the loading phase typically takes many seconds as many BUILD files are loaded from the file system. In subsequent builds, especially if no BUILD files have changed, loading occurs very quickly.
The second phase, analysis, involves the semantic analysis and validation of each build rule, the construction of a build dependency graph, and the determination of exactly what work is to be done in each step of the build.
Like loading, analysis also takes several seconds when computed in its entirety. However, Bazel caches the dependency graph from one build to the next and only reanalyzes what it has to, which can make incremental builds extremely fast in the case where the packages haven't changed since the previous build.
Errors reported at this stage include: inappropriate dependencies, invalid inputs to a rule, and all rule-specific error messages.