BUILD rules to define Swift libraries and executable binaries.
This file is the public interface that users should import to use the Swift
rules. Do not import definitions from the internal
subdirectory directly.
To use the Swift build rules in your BUILD files, load them from
@build_bazel_rules_swift//swift:swift.bzl
.
For example:
load("@build_bazel_rules_swift//swift:swift.bzl", "swift_library")
Macros and Functions
swift_common.cc_feature_configuration
Returns the C++ feature configuration in a Swift feature configuration.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.cc_feature_configuration(
# The Swift feature configuration, as returned from
feature_configuration = None,
)
feature_configuration
The Swift feature configuration, as returned from
swift_common.configure_features
.
swift_common.compilation_attrs
Returns an attribute dictionary for rules that compile Swift code.
The returned dictionary contains the subset of attributes that are shared by
the swift_binary
, swift_library
, and swift_test
rules that deal with
inputs and options for compilation. Users who are authoring custom rules
that compile Swift code but not as a library can add this dictionary to
their own rule's attributes to give it a familiar API.
Do note, however, that it is the responsibility of the rule implementation
to retrieve the values of those attributes and pass them correctly to the
other swift_common
APIs.
There is a hierarchy to the attribute sets offered by the swift_common
API:
- If you only need access to the toolchain for its tools and libraries but
are not doing any compilation, use
toolchain_attrs
. - If you need to invoke compilation actions but are not making the
resulting object files into a static or shared library, use
compilation_attrs
. - If you want to provide a rule interface that is suitable as a drop-in
replacement for
swift_library
, uselibrary_rule_attrs
.
Each of the attribute functions in the list above also contains the attributes from the earlier items in the list.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.compilation_attrs(
)
additional_deps_aspects
A list of additional aspects that should be
applied to deps
. Defaults to the empty list. These must be passed
by the individual rules to avoid potential circular dependencies
between the API and the aspects; the API loaded the aspects
directly, then those aspects would not be able to load the API.
requires_srcs
Indicates whether the srcs
attribute should be marked
as mandatory and non-empty. Defaults to True
.
swift_common.compile
Compiles a Swift module.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.compile(
# The context's `actions` object.
actions = None,
# A feature configuration obtained from
feature_configuration = None,
# The name of the Swift module being compiled
module_name = None,
# The Swift source files to compile.
srcs = [],
# The `SwiftToolchainInfo` provider of the toolchain.
swift_toolchain = None,
# The name of the target for which the code is being
target_name = None,
# The name of the workspace for which the code is being
workspace_name = None,
)
actions
The context's actions
object.
additional_inputs
A list of File
s representing additional input files
that need to be passed to the Swift compile action because they are
referenced by compiler flags.
copts
A list of compiler flags that apply to the target being built.
These flags, along with those from Bazel's Swift configuration
fragment (i.e., --swiftcopt
command line flags) are scanned to
determine whether whole module optimization is being requested,
which affects the nature of the output files.
defines
Symbols that should be defined by passing -D
to the compiler.
deps
Non-private dependencies of the target being compiled. These
targets are used as dependencies of both the Swift module being
compiled and the Clang module for the generated header. These
targets must propagate one of the following providers: CcInfo
,
SwiftInfo
, or apple_common.Objc
.
feature_configuration
A feature configuration obtained from
swift_common.configure_features
.
generated_header_name
The name of the Objective-C generated header that should be generated for this module. If omitted, no header will be generated.
module_name
The name of the Swift module being compiled. This must be
present and valid; use swift_common.derive_module_name
to generate
a default from the target's label if needed.
private_deps
Private (implementation-only) dependencies of the target
being compiled. These are only used as dependencies of the Swift
module, not of the Clang module for the generated header. These
targets must propagate one of the following providers: CcInfo
,
SwiftInfo
, or apple_common.Objc
.
srcs
The Swift source files to compile.
swift_toolchain
The SwiftToolchainInfo
provider of the toolchain.
target_name
The name of the target for which the code is being compiled, which is used to determine unique file paths for the outputs.
workspace_name
The name of the workspace for which the code is being compiled, which is used to determine unique file paths for some outputs.
swift_common.configure_features
Creates a feature configuration to be passed to Swift build APIs.
This function calls through to cc_common.configure_features
to configure
underlying C++ features as well, and nests the C++ feature configuration
inside the Swift one. Users who need to call C++ APIs that require a feature
configuration can extract it by calling
swift_common.cc_feature_configuration(feature_configuration)
.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.configure_features(
# The rule context.
ctx = None,
# The `SwiftToolchainInfo` provider of the toolchain
swift_toolchain = None,
)
ctx
The rule context.
swift_toolchain
The SwiftToolchainInfo
provider of the toolchain
being used to build. This is used to determine features that are
enabled by default or unsupported by the toolchain, and the C++
toolchain associated with the Swift toolchain is used to create the
underlying C++ feature configuration.
requested_features
The list of features to be enabled. This is
typically obtained using the ctx.features
field in a rule
implementation function.
unsupported_features
The list of features that are unsupported by the
current rule. This is typically obtained using the
ctx.disabled_features
field in a rule implementation function.
swift_common.create_clang_module
Creates a value representing a Clang module used as a Swift dependency.
Note: The compilation_context
argument of this function is primarily
intended to communicate information to the Swift build rules, not to
retrieve information back out. In most cases, it is better to depend on
the CcInfo
provider propagated by a Swift target to collect transitive
C/Objective-C compilation information about that target. This is because the
context used when compiling the module itself may not be the same as the
context desired when depending on it. (For example, apple_common.Objc
supports "strict include paths" which are only propagated to direct
dependents.)
One valid exception to the guidance above is retrieving the generated header
associated with a specific Swift module. Since the CcInfo
provider
propagated by the library will have already merged them transitively (or,
in the case of a hypothetical custom rule that propagates multiple direct
modules, the direct_public_headers
of the CcInfo
would also have them
merged), it is acceptable to read the headers from the compilation context
of the module struct itself in order to associate them with the module that
generated them.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.create_clang_module(
# A `CcCompilationContext` that contains the header
compilation_context = None,
# The text module map file that defines this module
module_map = None,
)
compilation_context
A CcCompilationContext
that contains the header
files and other context (such as include paths, preprocessor
defines, and so forth) needed to compile this module as an explicit
module.
module_map
The text module map file that defines this module. This
argument may be specified as a File
or as a string
; in the
latter case, it is assumed to be the path to a file that cannot
be provided as an action input because it is outside the workspace
(for example, the module map for a module from an Xcode SDK).
precompiled_module
A File
representing the precompiled module (.pcm
file) if one was emitted for the module. This may be None
if no
explicit module was built for the module; in that case, targets that
depend on the module will fall back to the text module map and
headers.
swift_common.create_linking_context_from_compilation_outputs
Creates a linking context from the outputs of a Swift compilation.
On some platforms, this function will spawn additional post-compile actions
for the module in order to add their outputs to the linking context. For
example, if the toolchain that requires a "module-wrap" invocation to embed
the .swiftmodule
into an object file for debugging purposes, or if it
extracts auto-linking information from the object files to generate a linker
command line parameters file, those actions will be created here.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.create_linking_context_from_compilation_outputs(
# The context's `actions` object.
actions = None,
# A `CcCompilationOutputs` value containing the
compilation_outputs = None,
# A feature configuration obtained from
feature_configuration = None,
# The `Label` of the target being built
label = None,
# The module context returned by `swift_common.compile`
module_context = None,
# The `SwiftToolchainInfo` provider of the toolchain.
swift_toolchain = None,
)
actions
The context's actions
object.
additional_inputs
A list
of File
s containing any additional files
that are referenced by user_link_flags
and therefore need to be
propagated up to the linker.
alwayslink
If True, any binary that depends on the providers returned by this function will link in all of the library's object files, even if some contain no symbols referenced by the binary.
compilation_outputs
A CcCompilationOutputs
value containing the
object files to link. Typically, this is the second tuple element in
the value returned by swift_common.compile
.
feature_configuration
A feature configuration obtained from
swift_common.configure_features
.
label
The Label
of the target being built. This is used as the owner
of the linker inputs created for post-compile actions (if any), and
the label's name component also determines the name of the artifact
unless it is overridden by the name
argument.
linking_contexts
A list
of CcLinkingContext
s containing libraries
from dependencies.
module_context
The module context returned by swift_common.compile
containing information about the Swift module that was compiled.
Typically, this is the first tuple element in the value returned by
swift_common.compile
.
name
A string that is used to derive the name of the library or
libraries linked by this function. If this is not provided or is a
falsy value, the name component of the label
argument is used.
swift_toolchain
The SwiftToolchainInfo
provider of the toolchain.
user_link_flags
A list
of strings containing additional flags that
will be passed to the linker for any binary that links with the
returned linking context.
swift_common.create_module
Creates a value containing Clang/Swift module artifacts of a dependency.
It is possible for both clang
and swift
to be present; this is the case
for Swift modules that generate an Objective-C header, where the Swift
module artifacts are propagated in the swift
context and the generated
header and module map are propagated in the clang
context.
Though rare, it is also permitted for both the clang
and swift
arguments
to be None
. One example of how this can be used is to model system
dependencies (like Apple SDK frameworks) that are implicitly available as
part of a non-hermetic SDK (Xcode) but do not propagate any artifacts of
their own. This would only apply in a build using implicit modules, however;
when using explicit modules, one would propagate the module artifacts
explicitly. But allowing for the empty case keeps the build graph consistent
if switching between the two modes is necessary, since it will not change
the set of transitive module names that are propagated by dependencies
(which other build rules may want to depend on for their own analysis).
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.create_module(
# The name of the module.
name = "",
)
name
The name of the module.
clang
A value returned by swift_common.create_clang_module
that
contains artifacts related to Clang modules, such as a module map or
precompiled module. This may be None
if the module is a pure Swift
module with no generated Objective-C interface.
is_system
Indicates whether the module is a system module. The default
value is False
. System modules differ slightly from non-system
modules in the way that they are passed to the compiler. For
example, non-system modules have their Clang module maps passed to
the compiler in both implicit and explicit module builds. System
modules, on the other hand, do not have their module maps passed to
the compiler in implicit module builds because there is currently no
way to indicate that modules declared in a file passed via
-fmodule-map-file
should be treated as system modules even if they
aren't declared with the [system]
attribute, and some system
modules may not build cleanly with respect to warnings otherwise.
Therefore, it is assumed that any module with is_system == True
must be able to be found using import search paths in order for
implicit module builds to succeed.
swift
A value returned by swift_common.create_swift_module
that
contains artifacts related to Swift modules, such as the
.swiftmodule
, .swiftdoc
, and/or .swiftinterface
files emitted
by the compiler. This may be None
if the module is a pure
C/Objective-C module.
swift_common.create_swift_info
Creates a new SwiftInfo
provider with the given values.
This function is recommended instead of directly creating a SwiftInfo
provider because it encodes reasonable defaults for fields that some rules
may not be interested in and ensures that the direct and transitive fields
are set consistently.
This function can also be used to do a simple merge of SwiftInfo
providers, by leaving the modules
argument unspecified. In that case, the
returned provider will not represent a true Swift module; it is merely a
"collector" for other dependencies.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.create_swift_info(
)
direct_swift_infos
A list of SwiftInfo
providers from dependencies
whose direct modules should be treated as direct modules in the
resulting provider, in addition to their transitive modules being
merged.
modules
A list of values (as returned by swift_common.create_module
)
that represent Clang and/or Swift module artifacts that are direct
outputs of the target being built.
swift_infos
A list of SwiftInfo
providers from dependencies whose
transitive modules should be merged into the resulting provider.
swift_common.create_swift_interop_info
Returns a provider that lets a target expose C/Objective-C APIs to Swift.
The provider returned by this function allows custom build rules written in
Starlark to be uninvolved with much of the low-level machinery involved in
making a Swift-compatible module. Such a target should propagate a CcInfo
provider whose compilation context contains the headers that it wants to
make into a module, and then also propagate the provider returned from this
function.
The simplest usage is for a custom rule to call
swift_common.create_swift_interop_info
passing it only the list of
SwiftInfo
providers from its dependencies; this tells
swift_clang_module_aspect
to derive the module name from the target label
and create a module map using the headers from the compilation context.
If the custom rule has reason to provide its own module name or module map,
then it can do so using the module_name
and module_map
arguments.
When a rule returns this provider, it must provide the full set of
SwiftInfo
providers from dependencies that will be merged with the one
that swift_clang_module_aspect
creates for the target itself; the aspect
will not do so automatically. This allows the rule to not only add extra
dependencies (such as support libraries from implicit attributes) but also
exclude dependencies if necessary.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.create_swift_interop_info(
)
module_map
A File
representing an existing module map that should be
used to represent the module, or None
(the default) if the module
map should be generated based on the headers in the target's
compilation context. If this argument is provided, then
module_name
must also be provided.
module_name
A string denoting the name of the module, or None
(the
default) if the name should be derived automatically from the target
label.
requested_features
A list of features (empty by default) that should be
requested for the target, which are added to those supplied in the
features
attribute of the target. These features will be enabled
unless they are otherwise marked as unsupported (either on the
target or by the toolchain). This allows the rule implementation to
have additional control over features that should be supported by
default for all instances of that rule as if it were creating the
feature configuration itself; for example, a rule can request that
swift.emit_c_module
always be enabled for its targets even if it
is not explicitly enabled in the toolchain or on the target
directly.
swift_infos
A list of SwiftInfo
providers from dependencies, which
will be merged with the new SwiftInfo
created by the aspect.
unsupported_features
A list of features (empty by default) that should
be considered unsupported for the target, which are added to those
supplied as negations in the features
attribute. This allows the
rule implementation to have additional control over features that
should be disabled by default for all instances of that rule as if
it were creating the feature configuration itself; for example, a
rule that processes frameworks with headers that do not follow
strict layering can request that swift.strict_module
always be
disabled for its targets even if it is enabled by default in the
toolchain.
swift_common.create_swift_module
Creates a value representing a Swift module use as a Swift dependency.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.create_swift_module(
# The `.swiftdoc` file emitted by the compiler for this module.
swiftdoc = None,
# The `.swiftmodule` file emitted by the compiler for this
swiftmodule = None,
)
swiftdoc
The .swiftdoc
file emitted by the compiler for this module.
swiftmodule
The .swiftmodule
file emitted by the compiler for this
module.
defines
A list of defines that will be provided as copts
to targets
that depend on this module. If omitted, the empty list will be used.
swiftsourceinfo
The .swiftsourceinfo
file emitted by the compiler for
this module. May be None
if no source info file was emitted.
swiftinterface
The .swiftinterface
file emitted by the compiler for
this module. May be None
if no module interface file was emitted.
swift_common.derive_module_name
Returns a derived module name from the given build label.
For targets whose module name is not explicitly specified, the module name is computed using the following algorithm:
- The package and name components of the label are considered separately.
All interior sequences of non-identifier characters (anything other
than
a-z
,A-Z
,0-9
, and_
) are replaced by a single underscore (_
). Any leading or trailing non-identifier characters are dropped. - If the package component is non-empty after the above transformation, it is joined with the transformed name component using an underscore. Otherwise, the transformed name is used by itself.
- If this would result in a string that begins with a digit (
0-9
), an underscore is prepended to make it identifier-safe.
This mapping is intended to be fairly predictable, but not reversible.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.derive_module_name(
)
args
Either a single argument of type Label
, or two arguments of
type str
where the first argument is the package name and the
second argument is the target name.
swift_common.is_enabled
Returns True
if the feature is enabled in the feature configuration.
This function handles both Swift-specific features and C++ features so that users do not have to manually extract the C++ configuration in order to check it.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.is_enabled(
# The Swift feature configuration, as returned by
feature_configuration = None,
# The name of the feature to check.
feature_name = None,
)
feature_configuration
The Swift feature configuration, as returned by
swift_common.configure_features
.
feature_name
The name of the feature to check.
swift_common.library_rule_attrs
Returns an attribute dictionary for swift_library
-like rules.
The returned dictionary contains the same attributes that are defined by the
swift_library
rule (including the private _toolchain
attribute that
specifies the toolchain dependency). Users who are authoring custom rules
can use this dictionary verbatim or add other custom attributes to it in
order to make their rule a drop-in replacement for swift_library
(for
example, if writing a custom rule that does some preprocessing or generation
of sources and then compiles them).
Do note, however, that it is the responsibility of the rule implementation
to retrieve the values of those attributes and pass them correctly to the
other swift_common
APIs.
There is a hierarchy to the attribute sets offered by the swift_common
API:
- If you only need access to the toolchain for its tools and libraries but
are not doing any compilation, use
toolchain_attrs
. - If you need to invoke compilation actions but are not making the
resulting object files into a static or shared library, use
compilation_attrs
. - If you want to provide a rule interface that is suitable as a drop-in
replacement for
swift_library
, uselibrary_rule_attrs
.
Each of the attribute functions in the list above also contains the attributes from the earlier items in the list.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.library_rule_attrs(
)
additional_deps_aspects
A list of additional aspects that should be
applied to deps
. Defaults to the empty list. These must be passed
by the individual rules to avoid potential circular dependencies
between the API and the aspects; the API loaded the aspects
directly, then those aspects would not be able to load the API.
requires_srcs
Indicates whether the srcs
attribute should be marked
as mandatory and non-empty. Defaults to True
.
swift_common.precompile_clang_module
Precompiles an explicit Clang module that is compatible with Swift.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.precompile_clang_module(
# The context's `actions` object.
actions = None,
# A `CcCompilationContext` that contains headers
cc_compilation_context = None,
# A feature configuration obtained from
feature_configuration = None,
# A textual module map file that defines the Clang module
module_map_file = "",
# The name of the top-level module in the module map that
module_name = None,
# The `SwiftToolchainInfo` provider of the toolchain.
swift_toolchain = None,
# The name of the target for which the code is being
target_name = None,
)
actions
The context's actions
object.
cc_compilation_context
A CcCompilationContext
that contains headers
and other information needed to compile this module. This
compilation context should contain all headers required to compile
the module, which includes the headers for the module itself and
any others that must be present on the file system/in the sandbox
for compilation to succeed. The latter typically refers to the set
of headers of the direct dependencies of the module being compiled,
which Clang needs to be physically present before it detects that
they belong to one of the precompiled module dependencies.
feature_configuration
A feature configuration obtained from
swift_common.configure_features
.
module_map_file
A textual module map file that defines the Clang module to be compiled.
module_name
The name of the top-level module in the module map that will be compiled.
swift_toolchain
The SwiftToolchainInfo
provider of the toolchain.
target_name
The name of the target for which the code is being compiled, which is used to determine unique file paths for the outputs.
swift_infos
A list of SwiftInfo
providers representing dependencies
required to compile this module.
swift_common.toolchain_attrs
Returns an attribute dictionary for toolchain users.
The returned dictionary contains a key with the name specified by the
argument toolchain_attr_name
(which defaults to the value "_toolchain"
),
the value of which is a BUILD API attr.label
that references the default
Swift toolchain. Users who are authoring custom rules can add this
dictionary to the attributes of their own rule in order to depend on the
toolchain and access its SwiftToolchainInfo
provider to pass it to other
swift_common
functions.
There is a hierarchy to the attribute sets offered by the swift_common
API:
- If you only need access to the toolchain for its tools and libraries but
are not doing any compilation, use
toolchain_attrs
. - If you need to invoke compilation actions but are not making the
resulting object files into a static or shared library, use
compilation_attrs
. - If you want to provide a rule interface that is suitable as a drop-in
replacement for
swift_library
, uselibrary_rule_attrs
.
Each of the attribute functions in the list above also contains the attributes from the earlier items in the list.
Example usage (generated)
load("@rules_swift//swift:swift.bzl", "swift_common")
swift_common.toolchain_attrs(
)
toolchain_attr_name
The name of the attribute that should be created
that points to the toolchain. This defaults to _toolchain
, which
is sufficient for most rules; it is customizable for certain aspects
where having an attribute with the same name but different values
applied to a particular target causes a build crash.