api.md

Build API

The swift_common module provides API access to the behavior implemented by the Swift build rules, so that other custom rules can invoke Swift compilation and/or linking as part of their implementation.

swift_common.cc_feature_configuration

swift_common.cc_feature_configuration(feature_configuration)

Returns the C++ feature configuration in a Swift feature configuration.

PARAMETERS

Name	Description	Default Value
feature_configuration	The Swift feature configuration, as returned from swift_common.configure_features.	none

RETURNS

A C++ FeatureConfiguration value (see cc_common.configure_features for more information).

swift_common.compilation_attrs

swift_common.compilation_attrs(additional_deps_aspects, requires_srcs)

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:

1. If you only need access to the toolchain for its tools and libraries but are not doing any compilation, use toolchain_attrs.
2. If you need to invoke compilation actions but are not making the resulting object files into a static or shared library, use compilation_attrs.
3. If you want to provide a rule interface that is suitable as a drop-in replacement for swift_library, use library_rule_attrs.

Each of the attribute functions in the list above also contains the attributes from the earlier items in the list.

PARAMETERS

Name	Description	Default Value
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.	True

RETURNS

A new attribute dictionary that can be added to the attributes of a custom build rule to provide a similar interface to swift_binary, swift_library, and swift_test.

swift_common.compile

swift_common.compile(actions, additional_inputs, copts, defines, deps, feature_configuration,
                     generated_header_name, is_test, module_name, private_deps, srcs, swift_toolchain,
                     target_name, workspace_name)

Compiles a Swift module.

PARAMETERS

Name	Description	Default Value
actions	The context's actions object.	none
additional_inputs	A list of Files 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.	none
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.	None
is_test	Represents if the testonly value of the context.	none
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.	none
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.	none
swift_toolchain	The SwiftToolchainInfo provider of the toolchain.	none
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.	none
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.	none

RETURNS

A tuple containing three elements:

1. A Swift module context (as returned by swift_common.create_module) that contains the Swift (and potentially C/Objective-C) compilation prerequisites of the compiled module. This should typically be propagated by a SwiftInfo provider of the calling rule.
2. A CcCompilationOutputs object (as returned by cc_common.create_compilation_outputs) that contains the compiled object files.
3. A struct containing:
   • ast_files: A list of Files output from the DUMP_AST action.
   • indexstore: A File representing the directory that contains the index store data generated by the compiler if the "swift.index_while_building" feature is enabled, otherwise this will be None.
   • symbol_graph: A File representing the directory that contains the symbol graph data generated by the compiler if the "swift.emit_symbol_graph" feature is enabled, otherwise this will be None.

swift_common.configure_features

swift_common.configure_features(ctx, swift_toolchain, requested_features, unsupported_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).

PARAMETERS

Name	Description	Default Value
ctx	The rule context.	none
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.	none
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.	[]

RETURNS

An opaque value representing the feature configuration that can be passed to other swift_common functions. Note that the structure of this value should otherwise not be relied on or inspected directly.

swift_common.create_clang_module

swift_common.create_clang_module(compilation_context, module_map, precompiled_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.

PARAMETERS

Name	Description	Default Value
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.	none
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).	none
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.	None

RETURNS

A struct containing the compilation_context, module_map, and precompiled_module fields provided as arguments.

swift_common.create_compilation_context

swift_common.create_compilation_context(defines, srcs, transitive_modules)

Cretes a compilation context for a Swift target.

PARAMETERS

Name	Description	Default Value
defines	A list of defines	none
srcs	A list of Swift source files used to compile the target.	none
transitive_modules	A list of modules (as returned by swift_common.create_module) from the transitive dependencies of the target.	none

RETURNS

A struct containing four fields:

• defines: A sequence of defines used when compiling the target. Includes the defines for the target and its transitive dependencies.
• direct_sources: A sequence of Swift source files used to compile the target.
• module_maps: A sequence of module maps used to compile the clang module for this target.
• swiftmodules: A sequence of swiftmodules depended on by the target.

swift_common.create_linking_context_from_compilation_outputs

swift_common.create_linking_context_from_compilation_outputs(actions, additional_inputs, alwayslink,
                                                             compilation_outputs,
                                                             feature_configuration, is_test, label,
                                                             linking_contexts, module_context, name,
                                                             swift_toolchain, user_link_flags)

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.

PARAMETERS

Name	Description	Default Value
actions	The context's actions object.	none
additional_inputs	A list of Files 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.	False
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.	none
feature_configuration	A feature configuration obtained from swift_common.configure_features.	none
is_test	Represents if the testonly value of the context.	none
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.	none
linking_contexts	A list of CcLinkingContexts 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.	none
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.	None
swift_toolchain	The SwiftToolchainInfo provider of the toolchain.	none
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.	[]

RETURNS

A tuple of (CcLinkingContext, CcLinkingOutputs) containing the linking context to be propagated by the caller's CcInfo provider and the artifact representing the library that was linked, respectively.

swift_common.create_module

swift_common.create_module(name, clang, compilation_context, is_system, swift)

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

PARAMETERS

Name	Description	Default Value
name	The name of the module.	none
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.	None
compilation_context	A value returned from swift_common.create_compilation_context that contains the context needed to compile the module being built. This may be None if the module wasn't compiled from sources.	None
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.	False
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.	None

RETURNS

A struct containing the name, clang, is_system, and swift fields provided as arguments.

swift_common.create_swift_info

swift_common.create_swift_info(direct_swift_infos, modules, swift_infos)

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.

PARAMETERS

Name	Description	Default Value
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.	[]

RETURNS

A new SwiftInfo provider with the given values.

swift_common.create_swift_interop_info

swift_common.create_swift_interop_info(module_map, module_name, requested_features, swift_infos,
                                       unsupported_features)

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.

PARAMETERS

Name	Description	Default Value
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.	None
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.	None
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.	[]

RETURNS

A provider whose type/layout is an implementation detail and should not be relied upon.

swift_common.create_swift_module

swift_common.create_swift_module(swiftdoc, swiftmodule, ast_files, defines, indexstore,
                                 swiftsourceinfo, swiftinterface, symbol_graph)

Creates a value representing a Swift module use as a Swift dependency.

PARAMETERS

Name	Description	Default Value
swiftdoc	The .swiftdoc file emitted by the compiler for this module.	none
swiftmodule	The .swiftmodule file emitted by the compiler for this module.	none
ast_files	A list of Files output from the DUMP_AST action.	[]
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.	[]
indexstore	A File representing the directory that contains the index store data generated by the compiler if the "swift.index_while_building" feature is enabled, otherwise this will be None.	None
swiftsourceinfo	The .swiftsourceinfo file emitted by the compiler for this module. May be None if no source info file was emitted.	None
swiftinterface	The .swiftinterface file emitted by the compiler for this module. May be None if no module interface file was emitted.	None
symbol_graph	A File representing the directory that contains the symbol graph data generated by the compiler if the "swift.emit_symbol_graph" feature is enabled, otherwise this will be None.	None

RETURNS

A struct containing the ast_files, defines, indexstore, swiftdoc, swiftmodule, swiftinterface, and symbol_graph` fields provided as arguments.

swift_common.derive_module_name

swift_common.derive_module_name(args)

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.

PARAMETERS

Name	Description	Default Value
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.	none

RETURNS

The module name derived from the label.

swift_common.is_enabled

swift_common.is_enabled(feature_configuration, feature_name)

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.

PARAMETERS

Name	Description	Default Value
feature_configuration	The Swift feature configuration, as returned by swift_common.configure_features.	none
feature_name	The name of the feature to check.	none

RETURNS

True if the given feature is enabled in the feature configuration.

swift_common.library_rule_attrs

swift_common.library_rule_attrs(additional_deps_aspects, requires_srcs)

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:

1. If you only need access to the toolchain for its tools and libraries but are not doing any compilation, use toolchain_attrs.
2. If you need to invoke compilation actions but are not making the resulting object files into a static or shared library, use compilation_attrs.
3. If you want to provide a rule interface that is suitable as a drop-in replacement for swift_library, use library_rule_attrs.

Each of the attribute functions in the list above also contains the attributes from the earlier items in the list.

PARAMETERS

Name	Description	Default Value
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.	True

RETURNS

A new attribute dictionary that can be added to the attributes of a custom build rule to provide the same interface as swift_library.

swift_common.precompile_clang_module

swift_common.precompile_clang_module(actions, cc_compilation_context, feature_configuration,
                                     module_map_file, module_name, swift_toolchain, target_name,
                                     swift_infos)

Precompiles an explicit Clang module that is compatible with Swift.

PARAMETERS

Name	Description	Default Value
actions	The context's actions object.	none
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.	none
feature_configuration	A feature configuration obtained from swift_common.configure_features.	none
module_map_file	A textual module map file that defines the Clang module to be compiled.	none
module_name	The name of the top-level module in the module map that will be compiled.	none
swift_toolchain	The SwiftToolchainInfo provider of the toolchain.	none
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.	none
swift_infos	A list of SwiftInfo providers representing dependencies required to compile this module.	[]

RETURNS

A File representing the precompiled module (.pcm) file, or None if the toolchain or target does not support precompiled modules.

swift_common.toolchain_attrs

swift_common.toolchain_attrs(toolchain_attr_name)

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:

1. If you only need access to the toolchain for its tools and libraries but are not doing any compilation, use toolchain_attrs.
2. If you need to invoke compilation actions but are not making the resulting object files into a static or shared library, use compilation_attrs.
3. If you want to provide a rule interface that is suitable as a drop-in replacement for swift_library, use library_rule_attrs.

Each of the attribute functions in the list above also contains the attributes from the earlier items in the list.

PARAMETERS

Name	Description	Default Value
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.	"_toolchain"

RETURNS

A new attribute dictionary that can be added to the attributes of a custom build rule to provide access to the Swift toolchain.