Bazel is still in Beta and new releases may include backward incompatible changes. As we make changes and polish the extension mechanism, old features may be removed and new features that are not backward compatible may be added.
Backward incompatible changes are introduced gradually:
- The backward incompatible change is introduced behind a flag with its
default value set to
- In a later release, the flag’s default value will be set to
true. You can still use the flag to disable the change.
- Then in a later release, the flag will be removed and you will no longer be able to disable the change.
To check if your code will be compatible with future releases you can:
- Build your code with the flag
--all_incompatible_changes. This flag enables all backward incompatible changes, and so you can ensure your code is compatible with upcoming changes.
- Use boolean flags to enable/disable specific backward incompatible changes.
Current backward incompatible changes
The following are the backward incompatible changes that are implemented and guarded behind flags in the current release:
- Dictionary concatenation
- Load must appear at top of file
- Depset is no longer iterable
- Depset union
- String is no longer iterable
- Integer division operator is //
- Package name is a function
- FileType is deprecated
- New actions API
- New args API
- Disable objc provider resources
- Remove native git repository
- Remove native http archive
- New-style JavaInfo constructor
- Disallow tools in action inputs
We are removing the
+ operator on dictionaries. This includes the
where the left-hand side is a dictionary. This is done to improve compatibility
with Python. A possible workaround is to use the
.update method instead.
Load must appear at top of file
load statement could appear anywhere in a
.bzl file so long
as it was at the top level. With this change, for
appear at the beginning of the file, i.e. before any other non-
Depset is no longer iterable
When the flag is set to true,
depset objects are not treated as iterable. If
you need an iterable, call the
.to_list() method. This affects
for loops and
many functions, e.g.
The goal of this change is to avoid accidental iteration on
depset, which can
deps = depset() [x.path for x in deps] # deprecated [x.path for x in deps.to_list()] # recommended sorted(deps) # deprecated sorted(deps.to_list()) # recommended
To merge two sets, the following examples used to be supported, but are now deprecated:
depset1 + depset2 # deprecated depset1 | depset2 # deprecated depset1.union(depset2) # deprecated
The recommended solution is to use the
depset documentation for more information.
String is no longer iterable
When the flag is set to true,
string objects are not treated as iterable. This
for loops and many functions, e.g.
any. String iteration has been a source of errors and
confusion, such as this error:
def my_macro(name, srcs): for src in srcs: # do something with src # equivalent to: my_macro("hello", ["f", "o", "o", ".", "c", "c"]) my_macro( name = "hello", srcs = "foo.cc", )
String indexing and
len are still allowed. If you need to iterate over a
string, you may explicitly use:
my_string = "hello world" for i in range(len(my_string)): char = my_string[i] # do something with char
Integer division operator is
Integer division operator is now
// instead of
/. This aligns with
Python 3 and it highlights the fact it is a floor division.
x = 7 / 2 # deprecated x = 7 // 2 # x is 3
Package name is a function
The current package name should be retrieved by calling
BUILD files or
native.package_name() in .bzl files. The old way of referring
to the magic
PACKAGE_NAME variable bends the language since it is neither a
parameter, local variable, nor global variable.
Likewise, the magic
REPOSITORY_NAME variable is replaced by
native.repository_name(). Both deprecations use the
FileType is deprecated
The FileType function is going away. The main use-case was as an argument to the rule function. It’s no longer needed, you can simply pass a list of strings to restrict the file types the rule accepts.
New actions API
This change removes the old methods for registering actions within rules, and requires that you use the new methods instead. The deprecated methods and their replacements are as follows.
New args API
The Args object returned by
ctx.actions.args() has dedicated
methods for appending the contents of a list or depset to the command line.
Previously these use cases were lumped into its
method, resulting in a more cluttered API.
With this flag,
add() only works for scalar values, and its deprecated
parameters are disabled. To add many arguments at once you must use
Python 3 range behavior.
When set, the result of
range(...) function is a lazy
range type instead of
list. Because of this repetitions using
* operator are no longer
range slices are also lazy
Disable objc provider resources
This flag disables certain deprecated resource fields on ObjcProvider.
Remove native git repository
When set, the native
new_git_repository rules are
disabled. The Starlark versions
load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository", "new_git_repository")
should be used instead. These are drop-in replacements of the corresponding
native rules, however with the additional requirement that all label arguments
be provided as a fully qualified label (usually starting with
build_file = "@//third_party:repo.BUILD".
Remove native http archive
When set, the native
http_archive and all related rules are disabled.
The Starlark version
should be used instead. This is a drop-in replacement, however with the
additional requirement that all label arguments be provided as
fully qualified labels (usually starting with
@//). The Starlark
is also a drop-in replacement for the native
the same proviso).
http_file (the latter only supports the
New-style JavaInfo constructor
java_common.create_provider and certain arguments to
JavaInfo are deprecated. The
deprecated arguments are:
Example migration from
# Before provider = java_common.create_provider( ctx.actions, compile_time_jars = [output_jar], use_ijar = True, java_toolchain = ctx.attr._java_toolchain, transitive_compile_time_jars = transitive_compile_time, transitive_runtime_jars = transitive_runtime_jars, ) # After compile_jar = java_common.run_ijar( ctx.actions, jar = output_jar, target_label = ctx.label, java_toolchain = ctx.attr._java_toolchain, ) provider = JavaInfo( output_jar = output_jar, compile_jar = compile_jar, deps = deps, runtime_deps = runtime_deps, )
Example migration from deprecated
# Before provider = JavaInfo( output_jar = my_jar, use_ijar = True, sources = my_sources, deps = my_compile_deps, runtime_deps = my_runtime_deps, actions = ctx.actions, java_toolchain = my_java_toolchain, host_javabase = my_host_javabase, ) # After my_ijar = java_common.run_ijar( ctx.actions, jar = my_jar, target_label = ctx.label, java_toolchain, my_java_toolchain, ) my_source_jar = java_common.pack_sources( ctx.actions, sources = my_sources, java_toolchain = my_java_toolchain, host_javabase = my_host_javabase, ) provider = JavaInfo( output_jar = my_jar, compile_jar = my_ijar, source_jar = my_source_jar, deps = my_compile_deps, runtime_deps = my_runtime_deps, )
Disallow tools in action inputs
A tool is an input coming from an attribute of type
where the attribute has been marked
executable = True. In order for an action
to run a tool, it needs access to its runfiles.
Under the old API, tools are passed to
ctx.actions.run_shell() via their
inputs parameter. Bazel scans this
argument (which may be a large depset) to find all the inputs that are tools,
and adds their runfiles automatically.
In the new API, tools are instead passed to a dedicated
tools parameter. The
inputs are not scanned. If a tool is accidentally put in
inputs instead of
tools, the action will fail during the execution phase with an error due to
missing runfiles. This may be somewhat cryptic.
To support a gradual transition, all actions with a
tools argument are opted
into the new API, while all actions without a
tools argument still follow the
old one. In the future (when this flag is removed), all actions will use the new
This flag turns on a safety check that is useful for migrating existing code.
The safety check applies to all actions that do not have a
tools argument. It
inputs looking for tools, and if it finds any, it raises an error
during the analysis phase that clearly identifies the offending tools.
In the rare case that your action requires a tool as input, but does not
actually run the tool and therefore does not need its runfiles, the safety check
will fail even though the action would have succeeded. In this case, you can
bypass the check by adding a (possibly empty)
tools argument to your action.
Note that once an action has been modified to take a
tools argument, you will
no longer get helpful analysis-time errors for any remaining tools that should
have been migrated from