diff --git a/reference/be/c-cpp.mdx b/reference/be/c-cpp.mdx index 92350a5f..84b19d3e 100644 --- a/reference/be/c-cpp.mdx +++ b/reference/be/c-cpp.mdx @@ -21,7 +21,7 @@ title: 'C / C++ Rules' [View rule sourceopen_in_new](https://github.com/bazelbuild/rules_cc/blob/master/cc/private/rules_impl/cc_binary.bzl) ``` -cc_binary(name, deps, srcs, data, additional_compiler_inputs, additional_linker_inputs, args, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, dynamic_deps, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local_defines, local_includes, malloc, module_interfaces, nocopts, output_licenses, package_metadata, reexport_deps, restricted_to, stamp, tags, target_compatible_with, testonly, toolchains, visibility, win_def_file) +cc_binary(name, deps, srcs, data, additional_compiler_inputs, additional_linker_inputs, args, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, dynamic_deps, env, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local_defines, malloc, module_interfaces, nocopts, output_licenses, package_metadata, reexport_deps, restricted_to, stamp, tags, target_compatible_with, testonly, toolchains, visibility, win_def_file) ``` It produces an executable binary. @@ -65,10 +65,9 @@ be `main`. | `linkshared` | Boolean; default is `False` Create a shared library. To enable this attribute, include `linkshared=True` in your rule. By default this option is off. The presence of this flag means that linking occurs with the `-shared` flag to `gcc`, and the resulting shared library is suitable for loading into for example a Java program. However, for build purposes it will never be linked into the dependent binary, as it is assumed that shared libraries built with a [cc_binary](#cc_binary) rule are only loaded manually by other programs, so it should not be considered a substitute for the [cc_library](#cc_library) rule. For sake of scalability we recommend avoiding this approach altogether and simply letting `java_library` depend on `cc_library` rules instead. If you specify both `linkopts=['-static']` and `linkshared=True`, you get a single completely self-contained unit. If you specify both `linkstatic=True` and `linkshared=True`, you get a single, mostly self-contained unit. | | `linkstatic` | Boolean; default is `True` For [`cc_binary`](/reference/be/c-cpp#cc_binary) and [`cc_test`](/reference/be/c-cpp#cc_test): link the binary in static mode. For `cc_library.link_static`: see below. By default this option is on for `cc_binary` and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in `.a`'s instead of `.so`'s for user libraries whenever possible. System libraries such as libc (but *not* the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only *mostly* static. There are really three different ways to link an executable: * STATIC with fully_static_link feature, in which everything is linked statically; e.g. "`gcc -static foo.o libbar.a libbaz.a -lm`". This mode is enabled by specifying `fully_static_link` in the [`features`](/reference/be/common-definitions#features) attribute. * STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "`gcc foo.o libfoo.a libbaz.a -lm`". This mode is enabled by specifying `linkstatic=True`. * DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "`gcc foo.o libfoo.so libbaz.so -lm`". This mode is enabled by specifying `linkstatic=False`. If the `linkstatic` attribute or `fully_static_link` in `features` is used outside of `//third_party` please include a comment near the rule to explain why. The `linkstatic` attribute has a different meaning if used on a [`cc_library()`](/reference/be/c-cpp#cc_library) rule. For a C++ library, `linkstatic=True` indicates that only static linking is allowed, so no `.so` will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with `linkstatic=False` in production. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area. | | `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. Unlike `defines`, the defines are only added to the compile command line for this target. | -| `local_includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](/reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-I path_to_package/local_include_entry`. Unlike [INCLUDES](#cc_binary.includes), these flags are added for this target and not added to every target that depends on it. The `local_includes` paths will include generated files as well as files in the source tree. | | `malloc` | [Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:malloc"` Override the default dependency on malloc. By default, C++ binaries are linked against `//tools/cpp:malloc`, which is an empty library so the binary ends up using libc malloc. This label must refer to a `cc_library`. If compilation is for a non-C++ rule, this option has no effect. The value of this attribute is ignored if `linkshared=True` is specified. | | `module_interfaces` | List of [labels](/concepts/labels); default is `[]` The list of files are regarded as C++20 Modules Interface. C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx The use is guarded by the flag `--experimental_cpp_modules`. | -| `nocopts` | String; default is `""` Deprecated, no-op. | +| `nocopts` | String; default is `""` Remove matching options from the C++ compilation command. Subject to ["Make" variable](/reference/be/make-variables) substitution. The value of this attribute is interpreted as a regular expression. Any preexisting `COPTS` that match this regular expression (including values explicitly specified in the rule's [copts](#cc_binary.copts) attribute) will be removed from `COPTS` for purposes of compiling this rule. This attribute should not be needed or used outside of `third_party`. The values are not preprocessed in any way other than the "Make" variable substitution. | | `reexport_deps` | List of [labels](/concepts/labels); default is `[]` | | `stamp` | Integer; default is `-1` Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in [`--nostamp`](/docs/user-manual#flag--stamp) builds. **This setting should be avoided**, since it potentially kills remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives good build result caching. * `stamp = -1`: Embedding of build information is controlled by the [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. Stamped binaries are *not* rebuilt unless their dependencies change. | | `win_def_file` | [Label](/concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | @@ -226,7 +225,6 @@ cc_import( | --- | --- | | `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | | `deps` | List of [labels](/concepts/labels); default is `[]` The list of other libraries that the target depends upon. See general comments about `deps` at [Typical attributes defined by most build rules](/reference/be/common-definitions#typical-attributes). | -| `data` | List of [labels](/concepts/labels); default is `[]` The list of files needed by this library at runtime. See general comments about `data` at [Typical attributes defined by most build rules](/reference/be/common-definitions#typical-attributes). | | `hdrs` | List of [labels](/concepts/labels); default is `[]` The list of header files published by this precompiled library to be directly included by sources in dependent rules. | | `alwayslink` | Boolean; default is `False` If enabled, any binary that depends (directly or indirectly) on this C++ precompiled library will link in all the object files archived in the static library, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service. If `alwayslink` doesn't work with VS 2017 on Windows, that is due to a [known issue](https://github.com/bazelbuild/bazel/issues/3949), please upgrade your VS 2017 to the latest version. | | `defines` | List of strings; default is `[]` List of defines to add to the compile line of this and all dependent targets. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects -- the defines are added to every target that depends on this target. | @@ -246,7 +244,7 @@ cc_import( [View rule sourceopen_in_new](https://github.com/bazelbuild/rules_cc/blob/master/cc/private/rules_impl/cc_library.bzl) ``` -cc_library(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs, alwayslink, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hdrs_check, implementation_deps, include_prefix, includes, licenses, linkopts, linkstamp, linkstatic, local_defines, local_includes, module_interfaces, package_metadata, restricted_to, strip_include_prefix, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, win_def_file) +cc_library(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs, alwayslink, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, hdrs_check, implementation_deps, include_prefix, includes, licenses, linkopts, linkstamp, linkstatic, local_defines, module_interfaces, package_metadata, restricted_to, strip_include_prefix, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, win_def_file) ``` Use `cc_library()` for C++-compiled libraries. @@ -455,7 +453,7 @@ cc_library( | `defines` | List of strings; default is `[]` List of defines to add to the compile line of this and all dependent targets. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects -- the defines are added to every target that depends on this target. When in doubt, add define values to [`local_defines`](#cc_binary.local_defines) instead. | | `hdrs_check` | String; default is `""` Deprecated, no-op. | | `implementation_deps` | List of [labels](/concepts/labels); default is `[]` The list of other libraries that the library target depends on. Unlike with `deps`, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with `implementation_deps` are still linked in binary targets that depend on this library. | -| `include_prefix` | String; default is `""` The prefix to add to the paths of the headers of this rule. When set, the headers in the `hdrs` attribute of this rule are accessible at a path formed by prepending this attribute's value to their repository-relative path. For example, if a library in package `foo` sets `include_prefix = "mylib"` and has `bar.h` in `hdrs`, dependent rules would include it as `#include "mylib/bar.h"` instead of `#include "foo/bar.h"`. The prefix in the `strip_include_prefix` attribute is removed before this prefix is added. This attribute is only legal under `third_party`. | +| `include_prefix` | String; default is `""` The prefix to add to the paths of the headers of this rule. When set, the headers in the `hdrs` attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path. The prefix in the `strip_include_prefix` attribute is removed before this prefix is added. This attribute is only legal under `third_party`. | | `includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](/reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-isystem path_to_package/include_entry`. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike [COPTS](#cc_binary.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to [COPTS](#cc_binary.copts) instead. The added `include` paths will include generated files as well as files in the source tree. | | `linkopts` | List of strings; default is `[]` See [`cc_binary.linkopts`](/reference/be/c-cpp#cc_binary.linkopts). The `linkopts` attribute is also applied to any target that depends, directly or indirectly, on this library via `deps` attributes (or via other attributes that are treated similarly: the [`malloc`](/reference/be/c-cpp#cc_binary.malloc) attribute of [`cc_binary`](/reference/be/c-cpp#cc_binary)). Dependency linkopts take precedence over dependent linkopts (i.e. dependency linkopts appear later in the command line). Linkopts specified in [`--linkopt`](../user-manual#flag--linkopt) take precedence over rule linkopts. | @@ -481,7 +479,6 @@ See [`cc_binary.linkshared`](/reference/be/c-cpp#cc_binary.linkshared). | `linkstamp` | [Label](/concepts/labels); default is `None` Simultaneously compiles and links the specified C++ source file into the final binary. This trickery is required to introduce timestamp information into binaries; if we compiled the source file to an object file in the usual way, the timestamp would be incorrect. A linkstamp compilation may not include any particular set of compiler flags and so should not depend on any particular header, compiler option, or other build variable. *This option should only be needed in the `base` package.* | | `linkstatic` | Boolean; default is `False` For [`cc_binary`](/reference/be/c-cpp#cc_binary) and [`cc_test`](/reference/be/c-cpp#cc_test): link the binary in static mode. For `cc_library.link_static`: see below. By default this option is on for `cc_binary` and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in `.a`'s instead of `.so`'s for user libraries whenever possible. System libraries such as libc (but *not* the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only *mostly* static. There are really three different ways to link an executable: * STATIC with fully_static_link feature, in which everything is linked statically; e.g. "`gcc -static foo.o libbar.a libbaz.a -lm`". This mode is enabled by specifying `fully_static_link` in the [`features`](/reference/be/common-definitions#features) attribute. * STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "`gcc foo.o libfoo.a libbaz.a -lm`". This mode is enabled by specifying `linkstatic=True`. * DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "`gcc foo.o libfoo.so libbaz.so -lm`". This mode is enabled by specifying `linkstatic=False`. If the `linkstatic` attribute or `fully_static_link` in `features` is used outside of `//third_party` please include a comment near the rule to explain why. The `linkstatic` attribute has a different meaning if used on a [`cc_library()`](/reference/be/c-cpp#cc_library) rule. For a C++ library, `linkstatic=True` indicates that only static linking is allowed, so no `.so` will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with `linkstatic=False` in production. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area. | | `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. Unlike `defines`, the defines are only added to the compile command line for this target. | -| `local_includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](/reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-I path_to_package/local_include_entry`. Unlike [INCLUDES](#cc_binary.includes), these flags are added for this target and not added to every target that depends on it. The `local_includes` paths will include generated files as well as files in the source tree. | | `module_interfaces` | List of [labels](/concepts/labels); default is `[]` The list of files are regarded as C++20 Modules Interface. C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx The use is guarded by the flag `--experimental_cpp_modules`. | | `strip_include_prefix` | String; default is `""` The prefix to strip from the paths of the headers of this rule. When set, the headers in the `hdrs` attribute of this rule are accessible at their path with this prefix cut off. If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path. The prefix in the `include_prefix` attribute is added after this prefix is stripped. This attribute is only legal under `third_party`. | | `textual_hdrs` | List of [labels](/concepts/labels); default is `[]` The list of header files published by this library to be textually included by sources in dependent rules. This is the location for declaring header files that cannot be compiled on their own; that is, they always need to be textually included by other source files to build valid code. | @@ -695,7 +692,7 @@ it in one of two ways: [View rule sourceopen_in_new](https://github.com/bazelbuild/rules_cc/blob/master/cc/private/rules_impl/cc_test.bzl) ``` -cc_test(name, deps, srcs, data, additional_compiler_inputs, additional_linker_inputs, args, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, dynamic_deps, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local, local_defines, local_includes, malloc, module_interfaces, nocopts, package_metadata, reexport_deps, restricted_to, shard_count, size, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility, win_def_file) +cc_test(name, deps, srcs, data, additional_compiler_inputs, additional_linker_inputs, args, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, dynamic_deps, env, env_inherit, exec_compatible_with, exec_group_compatible_with, exec_properties, features, flaky, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local, local_defines, malloc, module_interfaces, nocopts, package_metadata, reexport_deps, restricted_to, shard_count, size, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility, win_def_file) ``` A `cc_test()` rule compiles a test. Here, a test @@ -744,10 +741,9 @@ that `cc_test` has extra [attributes common to all test rules (\*\_test)](/refer | `linkshared` | Boolean; default is `False` Create a shared library. To enable this attribute, include `linkshared=True` in your rule. By default this option is off. The presence of this flag means that linking occurs with the `-shared` flag to `gcc`, and the resulting shared library is suitable for loading into for example a Java program. However, for build purposes it will never be linked into the dependent binary, as it is assumed that shared libraries built with a [cc_binary](#cc_binary) rule are only loaded manually by other programs, so it should not be considered a substitute for the [cc_library](#cc_library) rule. For sake of scalability we recommend avoiding this approach altogether and simply letting `java_library` depend on `cc_library` rules instead. If you specify both `linkopts=['-static']` and `linkshared=True`, you get a single completely self-contained unit. If you specify both `linkstatic=True` and `linkshared=True`, you get a single, mostly self-contained unit. | | `linkstatic` | Boolean; default is `False` For [`cc_binary`](/reference/be/c-cpp#cc_binary) and [`cc_test`](/reference/be/c-cpp#cc_test): link the binary in static mode. For `cc_library.link_static`: see below. By default this option is on for `cc_binary` and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in `.a`'s instead of `.so`'s for user libraries whenever possible. System libraries such as libc (but *not* the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only *mostly* static. There are really three different ways to link an executable: * STATIC with fully_static_link feature, in which everything is linked statically; e.g. "`gcc -static foo.o libbar.a libbaz.a -lm`". This mode is enabled by specifying `fully_static_link` in the [`features`](/reference/be/common-definitions#features) attribute. * STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "`gcc foo.o libfoo.a libbaz.a -lm`". This mode is enabled by specifying `linkstatic=True`. * DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "`gcc foo.o libfoo.so libbaz.so -lm`". This mode is enabled by specifying `linkstatic=False`. If the `linkstatic` attribute or `fully_static_link` in `features` is used outside of `//third_party` please include a comment near the rule to explain why. The `linkstatic` attribute has a different meaning if used on a [`cc_library()`](/reference/be/c-cpp#cc_library) rule. For a C++ library, `linkstatic=True` indicates that only static linking is allowed, so no `.so` will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with `linkstatic=False` in production. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area. | | `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. Unlike `defines`, the defines are only added to the compile command line for this target. | -| `local_includes` | List of strings; default is `[]` List of include dirs to be added to the compile line. Subject to ["Make variable"](/reference/be/make-variables) substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce `-I path_to_package/local_include_entry`. Unlike [INCLUDES](#cc_binary.includes), these flags are added for this target and not added to every target that depends on it. The `local_includes` paths will include generated files as well as files in the source tree. | | `malloc` | [Label](/concepts/labels); default is `"@bazel_tools//tools/cpp:malloc"` Override the default dependency on malloc. By default, C++ binaries are linked against `//tools/cpp:malloc`, which is an empty library so the binary ends up using libc malloc. This label must refer to a `cc_library`. If compilation is for a non-C++ rule, this option has no effect. The value of this attribute is ignored if `linkshared=True` is specified. | | `module_interfaces` | List of [labels](/concepts/labels); default is `[]` The list of files are regarded as C++20 Modules Interface. C++ Standard has no restriction about module interface file extension * Clang use cppm * GCC can use any source file extension * MSVC use ixx The use is guarded by the flag `--experimental_cpp_modules`. | -| `nocopts` | String; default is `""` Deprecated, no-op. | +| `nocopts` | String; default is `""` Remove matching options from the C++ compilation command. Subject to ["Make" variable](/reference/be/make-variables) substitution. The value of this attribute is interpreted as a regular expression. Any preexisting `COPTS` that match this regular expression (including values explicitly specified in the rule's [copts](#cc_binary.copts) attribute) will be removed from `COPTS` for purposes of compiling this rule. This attribute should not be needed or used outside of `third_party`. The values are not preprocessed in any way other than the "Make" variable substitution. | | `reexport_deps` | List of [labels](/concepts/labels); default is `[]` | | `stamp` | Integer; default is `0` Whether to encode build information into the binary. Possible values: * `stamp = 1`: Always stamp the build information into the binary, even in [`--nostamp`](/docs/user-manual#flag--stamp) builds. **This setting should be avoided**, since it potentially kills remote caching for the binary and any downstream actions that depend on it. * `stamp = 0`: Always replace build information by constant values. This gives good build result caching. * `stamp = -1`: Embedding of build information is controlled by the [`--[no]stamp`](/docs/user-manual#flag--stamp) flag. Stamped binaries are *not* rebuilt unless their dependencies change. | | `win_def_file` | [Label](/concepts/labels); default is `None` The Windows DEF file to be passed to linker. This attribute should only be used when Windows is the target platform. It can be used to [export symbols](https://msdn.microsoft.com/en-us/library/d91k01sh.aspx) during linking a shared library. | @@ -757,7 +753,7 @@ that `cc_test` has extra [attributes common to all test rules (\*\_test)](/refer [View rule sourceopen_in_new](https://github.com/bazelbuild/rules_cc/blob/master/cc/private/rules_impl/cc_toolchain.bzl) ``` -cc_toolchain(name, all_files, ar_files, args, artifact_name_patterns, as_files, aspect_hints, compatible_with, compiler, compiler_files, compiler_files_without_includes, coverage_files, cpu, deprecation, dwp_files, dynamic_runtime_lib, enabled_features, exec_compatible_with, exec_group_compatible_with, exec_properties, exec_transition_for_inputs, features, known_features, legacy_tools, libc_top, licenses, linker_files, make_variables, module_map, objcopy_files, output_licenses, package_metadata, restricted_to, static_runtime_lib, strip_files, supports_header_parsing, supports_param_files, tags, target_compatible_with, target_libc, target_system_name, testonly, tool_map, toolchain_config, toolchain_identifier, toolchains, visibility) +cc_toolchain(name, all_files, ar_files, as_files, aspect_hints, compatible_with, compiler_files, compiler_files_without_includes, coverage_files, deprecation, dwp_files, dynamic_runtime_lib, exec_compatible_with, exec_group_compatible_with, exec_properties, exec_transition_for_inputs, features, libc_top, licenses, linker_files, module_map, objcopy_files, output_licenses, package_metadata, restricted_to, static_runtime_lib, strip_files, supports_header_parsing, supports_param_files, tags, target_compatible_with, testonly, toolchain_config, toolchain_identifier, toolchains, visibility) ``` Represents a C++ toolchain. @@ -783,36 +779,25 @@ unnecessarily when invoking `bazel build //...` | Attributes | | | --- | --- | | `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | -| `all_files` | [Label](/concepts/labels); default is `None` Collection of all cc_toolchain artifacts. These artifacts will be added as inputs to all rules_cc related actions (with the exception of actions that are using more precise sets of artifacts from attributes below). Bazel assumes that `all_files` is a superset of all other artifact-providing attributes (e.g. linkstamp compilation needs both compile and link files, so it takes `all_files`). This is what `cc_toolchain.files` contains, and this is used by all Starlark rules using C++ toolchain. | +| `all_files` | [Label](/concepts/labels); required Collection of all cc_toolchain artifacts. These artifacts will be added as inputs to all rules_cc related actions (with the exception of actions that are using more precise sets of artifacts from attributes below). Bazel assumes that `all_files` is a superset of all other artifact-providing attributes (e.g. linkstamp compilation needs both compile and link files, so it takes `all_files`). This is what `cc_toolchain.files` contains, and this is used by all Starlark rules using C++ toolchain. | | `ar_files` | [Label](/concepts/labels); default is `None` Collection of all cc_toolchain artifacts required for archiving actions. | -| `args` | List of [labels](/concepts/labels); default is `[]` | -| `artifact_name_patterns` | List of [labels](/concepts/labels); default is `[]` | | `as_files` | [Label](/concepts/labels); default is `None` Collection of all cc_toolchain artifacts required for assembly actions. | -| `compiler` | String; default is `""` | -| `compiler_files` | [Label](/concepts/labels); default is `None` Collection of all cc_toolchain artifacts required for compile actions. | +| `compiler_files` | [Label](/concepts/labels); required Collection of all cc_toolchain artifacts required for compile actions. | | `compiler_files_without_includes` | [Label](/concepts/labels); default is `None` Collection of all cc_toolchain artifacts required for compile actions in case when input discovery is supported (currently Google-only). | | `coverage_files` | [Label](/concepts/labels); default is `None` Collection of all cc_toolchain artifacts required for coverage actions. If not specified, all_files are used. | -| `cpu` | String; default is `""` | -| `dwp_files` | [Label](/concepts/labels); default is `None` Collection of all cc_toolchain artifacts required for dwp actions. | +| `dwp_files` | [Label](/concepts/labels); required Collection of all cc_toolchain artifacts required for dwp actions. | | `dynamic_runtime_lib` | [Label](/concepts/labels); default is `None` Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so). This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking dependencies dynamically. | -| `enabled_features` | List of [labels](/concepts/labels); default is `[]` | | `exec_transition_for_inputs` | Boolean; default is `False` Deprecated. No-op. | -| `known_features` | List of [labels](/concepts/labels); default is `[]` | -| `legacy_tools` | List of [labels](/concepts/labels); default is `[]` | | `libc_top` | [Label](/concepts/labels); default is `None` A collection of artifacts for libc passed as inputs to compile/linking actions. | -| `linker_files` | [Label](/concepts/labels); default is `None` Collection of all cc_toolchain artifacts required for linking actions. | -| `make_variables` | List of [labels](/concepts/labels); default is `[]` | +| `linker_files` | [Label](/concepts/labels); required Collection of all cc_toolchain artifacts required for linking actions. | | `module_map` | [Label](/concepts/labels); default is `None` Module map artifact to be used for modular builds. | -| `objcopy_files` | [Label](/concepts/labels); default is `None` Collection of all cc_toolchain artifacts required for objcopy actions. | +| `objcopy_files` | [Label](/concepts/labels); required Collection of all cc_toolchain artifacts required for objcopy actions. | | `output_licenses` | List of strings; default is `[]` | | `static_runtime_lib` | [Label](/concepts/labels); default is `None` Static library artifact for the C++ runtime library (e.g. libstdc++.a). This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking dependencies statically. | -| `strip_files` | [Label](/concepts/labels); default is `None` Collection of all cc_toolchain artifacts required for strip actions. | +| `strip_files` | [Label](/concepts/labels); required Collection of all cc_toolchain artifacts required for strip actions. | | `supports_header_parsing` | Boolean; default is `False` Set to True when cc_toolchain supports header parsing actions. | | `supports_param_files` | Boolean; default is `True` Set to True when cc_toolchain supports using param files for linking actions. | -| `target_libc` | String; default is `""` | -| `target_system_name` | String; default is `""` | -| `tool_map` | [Label](/concepts/labels); default is `None` | -| `toolchain_config` | [Label](/concepts/labels); default is `None` The label of the rule providing `cc_toolchain_config_info`. | +| `toolchain_config` | [Label](/concepts/labels); required The label of the rule providing `cc_toolchain_config_info`. | | `toolchain_identifier` | String; default is `""` The identifier used to match this cc_toolchain with the corresponding crosstool_config.toolchain. Until issue [#5380](https://github.com/bazelbuild/bazel/issues/5380) is fixed this is the recommended way of associating `cc_toolchain` with `CROSSTOOL.toolchain`. It will be replaced by the `toolchain_config` attribute ([#5380](https://github.com/bazelbuild/bazel/issues/5380)). | ## fdo_prefetch_hints diff --git a/reference/be/common-definitions.mdx b/reference/be/common-definitions.mdx index 07a86e76..6ae7a79a 100644 --- a/reference/be/common-definitions.mdx +++ b/reference/be/common-definitions.mdx @@ -81,7 +81,7 @@ rules. | `package_metadata` | List of [labels](/concepts/labels); [nonconfigurable](#configurable-attributes); default is the package's `default_package_metadata` A list of labels that are associated metadata about this target. Typically, the labels are simple rules that return a provider of constant values. Rules and aspects may use these labels to perform some additional analysis on the build graph. The canonical use case is that of [rules_license](https://github.com/bazelbuild/rules_license). For that use case, `package_metadata` and `default_package_metadata` is used to attach information about a package's licence or version to targets. An aspect applied to a top-level binary can be used to gather those and produce compliance reports. | | `restricted_to` | List of [labels](/concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` The list of environments this target can be built for, *instead* of default-supported environments. This is part of Bazel's constraint system. See `compatible_with` for details. | | `tags` | List of strings; [nonconfigurable](#configurable-attributes); default is `[]` *Tags* can be used on any rule. *Tags* on test and `test_suite` rules are useful for categorizing the tests. *Tags* on non-test targets are used to control sandboxed execution of `genrule`s and [Starlark](/rules/concepts) actions, and for parsing by humans and/or external tools. Bazel modifies the behavior of its sandboxing code if it finds the following keywords in the `tags` attribute of any test or `genrule` target, or the keys of `execution_requirements` for any Starlark action. * `no-sandbox` keyword results in the action or test never being sandboxed; it can still be cached or run remotely - use `no-cache` or `no-remote` to prevent either or both of those. * `no-cache` keyword results in the action or test never being cached (locally or remotely). Note: for the purposes of this tag, the disk cache is considered a local cache, whereas the HTTP and gRPC caches are considered remote. Other caches, such as Skyframe or the persistent action cache, are not affected. * `no-remote-cache` keyword results in the action or test never being cached remotely (but it may be cached locally; it may also be executed remotely). Note: for the purposes of this tag, the disk cache is considered a local cache, whereas the HTTP and gRPC caches are considered remote. Other caches, such as Skyframe or the persistent action cache, are not affected. If a combination of local disk cache and remote cache are used (combined cache), it's treated as a remote cache and disabled entirely unless `--incompatible_remote_results_ignore_disk` is set in which case the local components will be used. * `no-remote-exec` keyword results in the action or test never being executed remotely (but it may be cached remotely). * `no-remote` keyword prevents the action or test from being executed remotely or cached remotely. This is equivalent to using both `no-remote-cache` and `no-remote-exec`. * `no-remote-cache-upload` keyword disables upload part of remote caching of a spawn. it does not disable remote execution. * `local` keyword precludes the action or test from being remotely cached, remotely executed, or run inside the sandbox. For genrules and tests, marking the rule with the `local = True` attribute has the same effect. * `requires-network` keyword allows access to the external network from inside the sandbox. This tag only has an effect if sandboxing is enabled. * `block-network` keyword blocks access to the external network from inside the sandbox. In this case, only communication with localhost is allowed. This tag only has an effect if sandboxing is enabled. * `requires-fakeroot` runs the test or action as uid and gid 0 (i.e., the root user). This is only supported on Linux. This tag takes precedence over the `--sandbox_fake_username` command-line option. *Tags* on tests are generally used to annotate a test's role in your debug and release process. Typically, tags are most useful for C++ and Python tests, which lack any runtime annotation ability. The use of tags and size elements gives flexibility in assembling suites of tests based around codebase check-in policy. Bazel modifies test running behavior if it finds the following keywords in the `tags` attribute of the test rule: * `exclusive` will force the test to be run in the "exclusive" mode, ensuring that no other tests are running at the same time. Such tests will be executed in serial fashion after all build activity and non-exclusive tests have been completed. Remote execution is disabled for such tests because Bazel doesn't have control over what's running on a remote machine. * `exclusive-if-local` will force the test to be run in the "exclusive" mode if it is executed locally, but will run the test in parallel if it's executed remotely. * `manual` keyword will exclude the target from expansion of target pattern wildcards (`...`, `:*`, `:all`, etc.) and `test_suite` rules which do not list the test explicitly when computing the set of top-level targets to build/run for the `build`, `test`, and `coverage` commands. It does not affect target wildcard or test suite expansion in other contexts, including the `query` command. Note that `manual` does not imply that a target should not be built/run automatically by continuous build/test systems. For example, it may be desirable to exclude a target from `bazel test ...` because it requires specific Bazel flags, but still have it included in properly-configured presubmit or continuous test runs. * `external` keyword will force test to be unconditionally executed (regardless of `--cache_test_results` value). See [Tag Conventions](/reference/test-encyclopedia#tag-conventions) in the Test Encyclopedia for more conventions on tags attached to test targets. | -| `target_compatible_with` | List of [labels](/concepts/labels); default is `[]` A list of `constraint_value`s that must be present in the target platform and `config_setting`s that must match the target configuration for this target to be considered *compatible*. This is in addition to any constraints already set by the rule type. If the target platform does not satisfy all listed constraints, or the target configuration does not match all listed config_settings, then the target is considered *incompatible*. Incompatible targets are skipped for building and testing when the target pattern is expanded (e.g. `//...`, `:all`). When explicitly specified on the command line, incompatible targets cause Bazel to print an error and cause a build or test failure. Targets that transitively depend on incompatible targets are themselves considered incompatible. They are also skipped for building and testing. An empty list (which is the default) signifies that the target is compatible with all platforms. All rules other than [Workspace Rules](workspace) support this attribute. For some rules this attribute has no effect. For example, specifying `target_compatible_with` for a `cc_toolchain` is not useful. See the [Platforms](/docs/platforms#skipping-incompatible-targets) page for more information about incompatible target skipping. | +| `target_compatible_with` | List of [labels](/concepts/labels); default is `[]` A list of `constraint_value`s that must be present in the target platform for this target to be considered *compatible*. This is in addition to any constraints already set by the rule type. If the target platform does not satisfy all listed constraints then the target is considered *incompatible*. Incompatible targets are skipped for building and testing when the target pattern is expanded (e.g. `//...`, `:all`). When explicitly specified on the command line, incompatible targets cause Bazel to print an error and cause a build or test failure. Targets that transitively depend on incompatible targets are themselves considered incompatible. They are also skipped for building and testing. An empty list (which is the default) signifies that the target is compatible with all platforms. All rules other than [Workspace Rules](workspace) support this attribute. For some rules this attribute has no effect. For example, specifying `target_compatible_with` for a `cc_toolchain` is not useful. See the [Platforms](/docs/platforms#skipping-incompatible-targets) page for more information about incompatible target skipping. | | `testonly` | Boolean; [nonconfigurable](#configurable-attributes); default is `False` except for test and test suite targets If `True`, only testonly targets (such as tests) can depend on this target. Equivalently, a rule that is not `testonly` is not allowed to depend on any rule that is `testonly`. Tests (`*_test` rules) and test suites ([test_suite](/reference/be/general#test_suite) rules) are `testonly` by default. This attribute is intended to mean that the target should not be contained in binaries that are released to production. Because testonly is enforced at build time, not run time, and propagates virally through the dependency tree, it should be applied judiciously. For example, stubs and fakes that are useful for unit tests may also be useful for integration tests involving the same binaries that will be released to production, and therefore should probably not be marked testonly. Conversely, rules that are dangerous to even link in, perhaps because they unconditionally override normal behavior, should definitely be marked testonly. | | `toolchains` | List of [labels](/concepts/labels); [nonconfigurable](#configurable-attributes); default is `[]` The set of targets whose [Make variables](/reference/be/make-variables) this target is allowed to access. These targets are either instances of rules that provide `TemplateVariableInfo` or special targets for toolchain types built into Bazel. These include: * `@bazel_tools//tools/cpp:toolchain_type`* `@rules_java//toolchains:current_java_runtime` Note that this is distinct from the concept of [toolchain resolution](/docs/toolchains#toolchain-resolution) that is used by rule implementations for platform-dependent configuration. You cannot use this attribute to determine which specific `cc_toolchain` or `java_toolchain` a target will use. | | `visibility` | List of [labels](/concepts/labels); [nonconfigurable](#configurable-attributes); default varies The `visibility` attribute controls whether the target can be depended on by targets in other locations. See the documentation for [visibility](/concepts/visibility). For targets declared directly in a BUILD file or in legacy macros called from a BUILD file, the default value is the package's `default_visibility` if specified, or else `["//visibility:private"]`. For targets declared in one or more symbolic macros, the default value is always just `["//visibility:private"]` (which makes it useable only within the package containing the macro's code). | diff --git a/reference/be/objective-c.mdx b/reference/be/objective-c.mdx index e239da98..44898db9 100644 --- a/reference/be/objective-c.mdx +++ b/reference/be/objective-c.mdx @@ -40,7 +40,7 @@ attributes supported by `objc_library`. [View rule sourceopen_in_new](https://github.com/bazelbuild/rules_cc/blob/master/cc/private/rules_impl/objc_library.bzl) ``` -objc_library(name, deps, srcs, data, hdrs, alwayslink, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, enable_modules, exec_compatible_with, exec_group_compatible_with, exec_properties, features, implementation_deps, includes, linkopts, local_defines, module_map, module_name, non_arc_srcs, package_metadata, pch, restricted_to, sdk_dylibs, sdk_frameworks, sdk_includes, stamp, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, weak_sdk_frameworks) +objc_library(name, deps, srcs, data, hdrs, alwayslink, aspect_hints, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, enable_modules, exec_compatible_with, exec_group_compatible_with, exec_properties, features, implementation_deps, includes, linkopts, module_map, module_name, non_arc_srcs, package_metadata, pch, restricted_to, sdk_dylibs, sdk_frameworks, sdk_includes, stamp, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, weak_sdk_frameworks) ``` This rule produces a static library from the given Objective-C source files. @@ -62,7 +62,6 @@ This rule produces a static library from the given Objective-C source files. | `implementation_deps` | List of [labels](/concepts/labels); default is `[]` The list of other libraries that the library target depends on. Unlike with `deps`, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with `implementation_deps` are still linked in binary targets that depend on this library. | | `includes` | List of strings; default is `[]` List of `#include/#import` search paths to add to this target and all depending targets. This is to support third party and open-sourced libraries that do not specify the entire workspace path in their `#import/#include` statements. The paths are interpreted relative to the package directory, and the genfiles and bin roots (e.g. `blaze-genfiles/pkg/includedir` and `blaze-out/pkg/includedir`) are included in addition to the actual client root. Unlike [COPTS](/reference/be/objective-c#objc_library.copts), these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-iquote" flags to [COPTS](/reference/be/objective-c#objc_library.copts) instead. | | `linkopts` | List of strings; default is `[]` Extra flags to pass to the linker. | -| `local_defines` | List of strings; default is `[]` List of defines to add to the compile line. Subject to ["Make" variable](/reference/be/make-variables) substitution and [Bourne shell tokenization](/reference/be/common-definitions#sh-tokenization). Each string, which must consist of a single Bourne shell token, is prepended with `-D` and added to the compile command line for this target, but not to its dependents. Unlike `defines`, the defines are only added to the compile command line for this target. | | `module_map` | [Label](/concepts/labels); default is `None` custom Clang module map for this target. Use of a custom module map is discouraged. Most users should use module maps generated by Bazel. If specified, Bazel will not generate a module map for this target, but will pass the provided module map to the compiler. | | `module_name` | String; default is `""` Sets the module name for this target. By default the module name is the target path with all special symbols replaced by \_, e.g. //foo/baz:bar can be imported as foo_baz_bar. | | `non_arc_srcs` | List of [labels](/concepts/labels); default is `[]` The list of Objective-C files that are processed to create the library target that DO NOT use Automatic Reference Counting (ARC). The files in this attribute are treated very similar to those in the srcs attribute, but are compiled without ARC enabled. | diff --git a/reference/be/platforms-and-toolchains.mdx b/reference/be/platforms-and-toolchains.mdx index f1a239bd..9561a689 100644 --- a/reference/be/platforms-and-toolchains.mdx +++ b/reference/be/platforms-and-toolchains.mdx @@ -19,7 +19,7 @@ The user should be familiar with the concepts explained [here](/extending/platfo [View rule sourceopen_in_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintSettingRule.java) ``` -constraint_setting(name, aspect_hints, default_constraint_value, deprecation, features, licenses, refines_constraint_value, tags, testonly, visibility) +constraint_setting(name, aspect_hints, default_constraint_value, deprecation, features, licenses, tags, testonly, visibility) ``` This rule is used to introduce a new constraint type for which a platform may specify a value. @@ -40,7 +40,6 @@ define a platform targeting an obscure cpu architecture. | --- | --- | | `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | | `default_constraint_value` | [Name](/concepts/labels#target-names); [nonconfigurable](common-definitions#configurable-attributes); default is `None` The label of the default value for this setting, to be used if no value is given. If this attribute is present, the `constraint_value` it points to must be defined in the same package as this `constraint_setting`. If a constraint setting has a default value, then whenever a platform does not include any constraint value for that setting, it is the same as if the platform had specified the default value. Otherwise, if there is no default value, the constraint setting is considered to be unspecified by that platform. In that case, the platform would not match against any constraint list (such as for a `config_setting`) that requires a particular value for that setting. | -| `refines_constraint_value` | [Label](/concepts/labels); [nonconfigurable](common-definitions#configurable-attributes); default is `None` The label of a `constraint_value` that this setting refines. If set, any `platform` that specifies a non-default `constraint_value` for this setting must also specify the refined `constraint_value` in its `constraint_values` attribute. Platforms that resolve to the default `constraint_value` for this setting (either implicitly via `default_constraint_value` or explicitly) are exempt from this requirement. When both the refined `constraint_value` and a `constraint_value` for this setting appear as conditions in the same `select` and both are satisfied, the condition that includes the refining `constraint_value` is considered more specific and is chosen unambiguously. | ## constraint_value diff --git a/reference/command-line-reference.mdx b/reference/command-line-reference.mdx index 3e8f4afa..c1ef0ae7 100644 --- a/reference/command-line-reference.mdx +++ b/reference/command-line-reference.mdx @@ -1358,7 +1358,7 @@ Options that affect the verbosity, format or location of logging: [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) `--[no]slim_profile` default: "true" -: Slims down the size of the JSON profile by merging events if the profile gets too large. Supports boolean values or a size in bytes (e.g. 5M) to start slimming after the profile exceeds that size. +: Slims down the size of the JSON profile by merging events if the profile gets too large. Tags: [`bazel_monitoring`](#effect_tag_BAZEL_MONITORING) @@ -2371,6 +2371,18 @@ Options that configure the toolchain used for action execution: Tags: [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ios_sdk_version=` default: see description +: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--macos_sdk_version=` default: see description +: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + `--minimum_os_version=` default: see description : The minimum OS version which your compilation targets. @@ -2392,6 +2404,24 @@ Options that configure the toolchain used for action execution: Tags: [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--tvos_sdk_version=` default: see description +: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" +: Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_sdk_version=` default: see description +: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + `--xcode_version=` default: see description : If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. @@ -4149,12 +4179,6 @@ Options that affect the verbosity, format or location of logging: `--[no]debug_spawn_scheduler` default: "false" -`--[no]expand_param_files` default: "false" -: When displaying subcommands (--subcommands) or printing the command line of a failed action (--verbose_failures), expand the contents of param files. When enabled, param file references like @path/to/param_file are replaced with the actual arguments they contain. - - Tags: - [`terminal_output`](#effect_tag_TERMINAL_OUTPUT) - `--[no]experimental_bep_target_summary` default: "false" : Whether to publish `TargetSummary` events. @@ -5013,6 +5037,18 @@ Options that configure the toolchain used for action execution: Tags: [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ios_sdk_version=` default: see description +: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--macos_sdk_version=` default: see description +: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + `--minimum_os_version=` default: see description : The minimum OS version which your compilation targets. @@ -5034,6 +5070,24 @@ Options that configure the toolchain used for action execution: Tags: [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--tvos_sdk_version=` default: see description +: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" +: Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_sdk_version=` default: see description +: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + `--xcode_version=` default: see description : If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. @@ -6794,6 +6848,18 @@ Options that configure the toolchain used for action execution: Tags: [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ios_sdk_version=` default: see description +: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--macos_sdk_version=` default: see description +: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + `--minimum_os_version=` default: see description : The minimum OS version which your compilation targets. @@ -6815,6 +6881,24 @@ Options that configure the toolchain used for action execution: Tags: [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--tvos_sdk_version=` default: see description +: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" +: Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_sdk_version=` default: see description +: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + `--xcode_version=` default: see description : If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. @@ -8396,6 +8480,18 @@ Options that configure the toolchain used for action execution: Tags: [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ios_sdk_version=` default: see description +: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--macos_sdk_version=` default: see description +: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + `--minimum_os_version=` default: see description : The minimum OS version which your compilation targets. @@ -8417,6 +8513,24 @@ Options that configure the toolchain used for action execution: Tags: [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--tvos_sdk_version=` default: see description +: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" +: Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_sdk_version=` default: see description +: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + `--xcode_version=` default: see description : If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. @@ -11356,6 +11470,18 @@ Options that configure the toolchain used for action execution: Tags: [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS) +`--ios_sdk_version=` default: see description +: Specifies the version of the iOS SDK to use to build iOS applications. If unspecified, uses the default iOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--macos_sdk_version=` default: see description +: Specifies the version of the macOS SDK to use to build macOS applications. If unspecified, uses the default macOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + `--minimum_os_version=` default: see description : The minimum OS version which your compilation targets. @@ -11377,6 +11503,24 @@ Options that configure the toolchain used for action execution: Tags: [`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) +`--tvos_sdk_version=` default: see description +: Specifies the version of the tvOS SDK to use to build tvOS applications. If unspecified, uses the default tvOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + +`--[no]use_platforms_in_apple_crosstool_transition` default: "false" +: Makes apple_crosstool_transition fall back to using the value of `--platforms` flag instead of legacy `--cpu` when needed. + + Tags: + [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS) + +`--watchos_sdk_version=` default: see description +: Specifies the version of the watchOS SDK to use to build watchOS applications. If unspecified, uses the default watchOS SDK version from 'xcode_version'. + + Tags: + [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE) + `--xcode_version=` default: see description : If specified, uses Xcode of the given version for relevant build actions. If unspecified, uses the executor default version of Xcode. diff --git a/release/index.mdx b/release/index.mdx index fa867888..6fb24547 100644 --- a/release/index.mdx +++ b/release/index.mdx @@ -14,7 +14,7 @@ information about Bazel's release model. | LTS release | Support stage | Latest version | End of support | | ----------- | ------------- | -------------- | -------------- | | Bazel 10 | Rolling| [Check rolling release page](/release/rolling) | N/A | -| Bazel 9 | Active| [9.1.1](https://github.com/bazelbuild/bazel/releases/tag/9.1.1) | Dec 2028 | +| Bazel 9 | Active| [9.1.0](https://github.com/bazelbuild/bazel/releases/tag/9.1.0) | Dec 2028 | | Bazel 8 | Maintenance| [8.7.0](https://github.com/bazelbuild/bazel/releases/tag/8.7.0) | Dec 2027 | | Bazel 7 | Maintenance| [7.7.1](https://github.com/bazelbuild/bazel/releases/tag/7.7.1) | Dec 2026 | | Bazel 6 | Deprecated | [6.6.0](https://github.com/bazelbuild/bazel/releases/tag/6.6.0) | Dec 2025 | diff --git a/rules/lib/builtins/Args.mdx b/rules/lib/builtins/Args.mdx index a4509a77..9410c3c0 100644 --- a/rules/lib/builtins/Args.mdx +++ b/rules/lib/builtins/Args.mdx @@ -48,7 +48,6 @@ ctx.actions.run( * [add_all](#add_all) * [add_joined](#add_joined) * [set_param_file_format](#set_param_file_format) -* [set_param_file_path](#set_param_file_path) * [use_param_file](#use_param_file) ## add @@ -138,20 +137,6 @@ Sets the format of the param file, if one is used | --- | --- | | `format` | [string](../core/string); required Must be one of: * "multiline": Each item (argument name or value) is written verbatim to the param file with a newline character following it. * "shell": Same as "multiline", but the items are shell-quoted * "flag_per_line": Same as "multiline", but (1) only flags (beginning with '--') are written to the param file, and (2) the values of the flags, if any, are written on the same line with a '=' separator. This is the format expected by the Abseil flags library. The format defaults to "shell" if not called. | -## set_param_file_path - -``` -Args Args.set_param_file_path(path) -``` - -Sets the name of the parameter file when used in an action. By default, Bazel chooses a path derived from the primary output of the action. - -### Parameters - -| Parameter | Description | -| --- | --- | -| `path` | [string](../core/string); required The name for the parameter file. | - ## use_param_file ``` diff --git a/rules/lib/builtins/actions.mdx b/rules/lib/builtins/actions.mdx index 5f84da48..7a6910e6 100644 --- a/rules/lib/builtins/actions.mdx +++ b/rules/lib/builtins/actions.mdx @@ -132,7 +132,7 @@ Creates multiple actions based on the files within one or more input directories | `use_default_shell_env` | [bool](../core/bool); default is `False` Whether the created actions should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via [`--action_env`](/reference/command-line-reference#flag--action_env). If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | | `env` | [dict](../core/dict); or `None`; default is `None` Sets the dictionary of environment variables. If both `use_default_shell_env` and `env` are set to `True`, values set in `env` will overwrite the default shell environment. | | `mnemonic` | [string](../core/string); or `None`; default is `None` A one-word description of the created actions, for example, CppCompile or GoLink. | -| `implementation` | [function](../core/function); required A Starlark function that gets called after input directories have been built to generate actions that output files to the specified output directories. This function is passed the following arguments: * `template_ctx` (positional): A [`template_ctx`](../builtins/template_ctx) object that can be used to create actions. * `input_directories` (keyword-only): A dictionary mapping from the string keys of the `input_directories` argument of `actions.map_directory()` to their values' corresponding [`ExpandedDirectory`](../builtins/ExpandedDirectory) objects. * `output_directories` (keyword-only): The value of the `output_directories` argument of `actions.map_directory()`; a dictionary mapping from strings to output directories. * `additional_inputs` (keyword-only): The value of the `additional_inputs` argument of `actions.map_directory()`; a dictionary mapping from strings to input files. * `tools` (keyword-only): The value of the `tools` argument of `actions.map_directory()`; a dictionary mapping from strings to tools. * `additional_params` (keyword-only): The value of the `additional_params` argument of `actions.map_directory()`; a dictionary mapping from strings to strings, booleans, or integers. This function must be top-level, i.e. lambdas and nested functions are not allowed. | +| `implementation` | [function](../core/function); required A Starlark function that gets called after input directories have been built to generate actions that output files to the specified output directories. This function is passed the following arguments: * `template_ctx` (positional): A [`template_ctx`](../builtins/template_ctx) object that can be used to create actions. * `input_directories` (keyword-only): A dictionary mapping from the string keys of the `input_directories` argument of `actions.map_directory()` to their values' corresponding [`ExpandedDirectory`](../builtins/File) objects. * `output_directories` (keyword-only): The value of the `output_directories` argument of `actions.map_directory()`; a dictionary mapping from strings to output directories. * `additional_inputs` (keyword-only): The value of the `additional_inputs` argument of `actions.map_directory()`; a dictionary mapping from strings to input files. * `tools` (keyword-only): The value of the `tools` argument of `actions.map_directory()`; a dictionary mapping from strings to tools. * `additional_params` (keyword-only): The value of the `additional_params` argument of `actions.map_directory()`; a dictionary mapping from strings to strings, booleans, or integers. This function must be top-level, i.e. lambdas and nested functions are not allowed. | ## run diff --git a/upstream b/upstream index e05fcb16..7a820bf5 160000 --- a/upstream +++ b/upstream @@ -1 +1 @@ -Subproject commit e05fcb1658bce403337a3e73a0ca184c45128ad6 +Subproject commit 7a820bf55bc472c00ddcc5c000afc2c699611556