rules.md

Bazel rules to define Swift libraries and executable binaries.

Users should load these rules from .bzl files under the swift and proto directories. Do not import definitions from the internal subdirectory directly.

For example:

load("@rules_swift//swift:swift_library.bzl", "swift_library")
load("@rules_swift//proto:swift_proto_library.bzl", "swift_proto_library")

On this page:

• swift_binary
• swift_compiler_plugin
• swift_compiler_plugin_import
• swift_cross_import_overlay
• swift_feature_allowlist
• swift_import
• swift_interop_hint
• swift_library
• swift_library_group
• swift_module_mapping
• swift_module_mapping_test
• swift_overlay
• swift_package_configuration
• swift_proto_compiler
• swift_proto_library
• swift_proto_library_group
• swift_test
• universal_swift_compiler_plugin
• mixed_language_library

swift_binary

swift_binary(name, deps, srcs, data, additional_linker_inputs, copts, defines, env, linkopts,
             linkshared, malloc, module_name, package_name, plugins, stamp, swiftc_inputs)

Compiles and links Swift code into an executable binary.

On Linux, this rule produces an executable binary for the desired target architecture.

On Apple platforms, this rule produces a single-architecture binary; it does not produce universal binaries. As such, this rule is mainly useful for creating Swift tools intended to run on the local build machine.

If you want to create a multi-architecture binary or a bundled application, please use one of the platform-specific application rules in rules_apple instead of swift_binary.

Setting linkshared = True links a shared library instead of an executable; see the linkshared attribute.

ATTRIBUTES

swift_compiler_plugin

swift_compiler_plugin(name, deps, srcs, data, additional_linker_inputs, copts, defines, linkopts,
                      malloc, module_name, package_name, plugins, stamp, swiftc_inputs)

Compiles and links a Swift compiler plugin (for example, a macro).

A compiler plugin is a standalone executable that minimally implements the CompilerPlugin protocol from the SwiftCompilerPlugin module in swift-syntax. As of the time of this writing (Xcode 15.0), a compiler plugin can contain one or more macros, which can be associated with other Swift targets to perform syntax-tree-based expansions.

When a swift_compiler_plugin target is listed in the plugins attribute of a swift_library, it will be loaded by that library and any targets that directly depend on it. (The plugins attribute also exists on swift_binary, swift_test, and swift_compiler_plugin itself, to support plugins that are only used within those targets.)

Compiler plugins also support being built as a library so that they can be tested. The swift_test rule can contain swift_compiler_plugin targets in its deps, and the plugin's module can be imported by the test's sources so that unit tests can be written against the plugin.

Example:

# The actual macro code, using SwiftSyntax
swift_compiler_plugin(
    name = "Macros",
    srcs = glob(["Macros/*.swift"]),
    deps = [
        "@swift-syntax//:SwiftSyntax",
        "@swift-syntax//:SwiftCompilerPlugin",
        "@swift-syntax//:SwiftSyntaxMacros",
    ],
)

# A target testing the macro itself
swift_test(
    name = "MacrosTests",
    srcs = glob(["MacrosTests/*.swift"]),
    deps = [
        ":Macros",
        "@swift-syntax//:SwiftSyntaxMacrosTestSupport",
    ],
)

# The library that defines the macro hook for use in your project
swift_library(
    name = "MacroLibrary",
    srcs = glob(["MacroLibrary/*.swift"]),
    plugins = [":Macros"],
)

# A consumer of the macro library. This doesn't have to be separate from the
# MacroLibrary depending on what makes sense for your project's organization
swift_library(
    name = "MacroConsumer",
    srcs = glob(["Sources/*.swift"]),
    deps = [":MacroLibrary"],
)

ATTRIBUTES

swift_compiler_plugin_import

swift_compiler_plugin_import(name, executable, module_names)

Allows for a Swift compiler plugin to be loaded from a prebuilt executable or some other binary-propagating rule, instead of building the plugin from source using swift_compiler_plugin.

ATTRIBUTES

swift_cross_import_overlay

swift_cross_import_overlay(name, deps, bystanding_module, bystanding_module_name, declaring_module,
                           declaring_module_name, swiftoverlay)

Declares a cross-import overlay that will be automatically added as a dependency by the toolchain if its declaring and bystanding modules are both imported.

Since Bazel requires the dependency graph to be explicit, cross-import overlays do not work correctly when the Swift compiler attempts to import them automatically when they aren't represented in the graph. Users can explicitly depend on the cross-import overlay module, but this is unsatisfying because there is no single import declaration in the source code that indicates what needs to be depended on.

To address this, the toolchain owner can define a swift_cross_import_overlay target for each cross-import overlay that they wish to support and set them as cross_import_overlays on the toolchain. During Swift compilation analysis, the direct dependencies will be scanned and if any pair of dependencies matches a cross-import overlay defined by the toolchain, the overlay module will be automatically injected as a dependency as well.

NOTE: This rule and its associated APIs only exists to support cross-import overlays already defined by Apple's SDKs. Since cross-import overlays are not a public feature of the compiler and its design and implementation may change in the future, this rule is not recommended for other widespread use.

ATTRIBUTES

swift_feature_allowlist

swift_feature_allowlist(name, aspect_ids, managed_features, packages)

Limits the ability to request or disable certain features to a set of packages (and possibly subpackages) in the workspace.

A Swift toolchain target can reference any number (zero or more) of swift_feature_allowlist targets. The features managed by these allowlists may overlap. For some package P, a feature is allowed to be used by targets in that package if P matches the packages patterns in all of the allowlists that manage that feature.

A feature that is not managed by any allowlist is allowed to be used by any package.

ATTRIBUTES

swift_import

swift_import(name, deps, data, archives, module_name, plugins, swiftdoc, swiftinterface,
             swiftmodule)

Allows for the use of Swift textual module interfaces and/or precompiled Swift modules as dependencies in other swift_library and swift_binary targets.

To use swift_import targets across Xcode versions and/or OS versions, it is required to use .swiftinterface files. These can be produced by the pre-built target if built with:

• --features=swift.enable_library_evolution
• --features=swift.emit_swiftinterface

If the pre-built target supports .private.swiftinterface files, these can be used instead of .swiftinterface files in the swiftinterface attribute.

To import pre-built Swift modules that use @_spi when using swiftinterface, the .private.swiftinterface files are required in order to build any code that uses the API marked with @_spi.

ATTRIBUTES

swift_interop_hint

swift_interop_hint(name, exclude_hdrs, module_map, module_name, suppressed)

Defines an aspect hint that associates non-Swift BUILD targets with additional information required for them to be imported by Swift.

Some build rules, such as objc_library, support interoperability with Swift simply by depending on them; a module map is generated automatically. This is for convenience, because the common case is that most objc_library targets contain code that is compatible (i.e., capable of being imported) by Swift.

For other rules, like cc_library, additional information must be provided to indicate that a particular target is compatible with Swift. This is done using the aspect_hints attribute and the swift_interop_hint rule.

Using the automatically derived module name (recommended)

If you want to import a non-Swift, non-Objective-C target into Swift using the module name that is automatically derived from the BUILD label, there is no need to declare an instance of swift_interop_hint. A canonical one that requests module name derivation has been provided in @rules_swift//swift:auto_module. Simply add it to the aspect_hints of the target you wish to import:

# //my/project/BUILD
cc_library(
    name = "somelib",
    srcs = ["somelib.c"],
    hdrs = ["somelib.h"],
    aspect_hints = ["@rules_swift//swift:auto_module"],
)

When this cc_library is a dependency of a Swift target, a module map will be generated for it. In this case, the module's name would be my_project_somelib.

Using an explicit module name

If you need to provide an explicit name for the module (for example, if it is part of a third-party library that expects to be imported with a specific name), then you can declare your own swift_interop_hint target to define the name:

# //my/project/BUILD
cc_library(
    name = "somelib",
    srcs = ["somelib.c"],
    hdrs = ["somelib.h"],
    aspect_hints = [":somelib_swift_interop"],
)

swift_interop_hint(
    name = "somelib_swift_interop",
    module_name = "CSomeLib",
)

When this cc_library is a dependency of a Swift target, a module map will be generated for it with the module name CSomeLib.

Using a custom module map

In rare cases, the automatically generated module map may not be suitable. For example, a Swift module may depend on a C module that defines specific submodules, and this is not handled by the Swift build rules. In this case, you can provide the module map file using the module_map attribute.

When setting the module_map attribute, module_name must also be set to the name of the desired top-level module; it cannot be omitted.

# //my/project/BUILD
cc_library(
    name = "somelib",
    srcs = ["somelib.c"],
    hdrs = ["somelib.h"],
    aspect_hints = [":somelib_swift_interop"],
)

swift_interop_hint(
    name = "somelib_swift_interop",
    module_map = "module.modulemap",
    module_name = "CSomeLib",
)

Suppressing a module

As mentioned above, objc_library and other Objective-C targets generate modules by default, without an explicit hint, for convenience. In some situations, this behavior may not be desirable. For example, an objc_library might contain only Objective-C++ code in its headers that would not be possible to import into Swift at all.

When building with implicit modules, this is not typically an issue because the module map would only be used if Swift code tried to import it (although it does create useless actions and compiler inputs during the build). When building with explicit modules, however, Bazel needs to know which targets represent modules that it can compile and which do not.

In these cases, there is no need to declare an instance of swift_interop_hint. A canonical one that suppresses module generation has been provided in @rules_swift//swift:no_module. Simply add it to the aspect_hints of the target whose module you wish to suppress:

# //my/project/BUILD
objc_library(
    name = "somelib",
    srcs = ["somelib.mm"],
    hdrs = ["somelib.h"],
    aspect_hints = ["@rules_swift//swift:no_module"],
)

When this objc_library is a dependency of a Swift target, no module map or explicit module will be generated for it, nor will any Swift information from its transitive dependencies be propagated.

ATTRIBUTES

swift_library

swift_library(name, deps, srcs, data, always_include_developer_search_paths, alwayslink, copts,
              defines, generated_header_name, generates_header, library_evolution, linkopts,
              linkstatic, module_name, package_name, plugins, private_deps, swiftc_inputs)

Compiles and links Swift code into a static library and Swift module.

ATTRIBUTES

swift_library_group

swift_library_group(name, deps)

Groups Swift compatible libraries (e.g. swift_library and objc_library). The target can be used anywhere a swift_library can be used. It behaves similar to source-less {cc,obj}_library targets.

A new module isn't created for this target, you need to import the grouped libraries directly.

ATTRIBUTES

swift_module_mapping

swift_module_mapping(name, aliases)

Defines a set of module aliases that will be passed to the Swift compiler.

This rule defines a mapping from original module names to aliased names. This is useful if you are building a library or framework for external use and want to ensure that dependencies do not conflict with other versions of the same library that another framework or the client may use.

To use this feature, first define a swift_module_mapping target that lists the aliases you need:

# //some/package/BUILD

swift_library(
    name = "Utils",
    srcs = [...],
    module_name = "Utils",
)

swift_library(
    name = "Framework",
    srcs = [...],
    module_name = "Framework",
    deps = [":Utils"],
)

swift_module_mapping(
    name = "mapping",
    aliases = {
        "Utils": "GameUtils",
    },
)

Then, pass the label of that target to Bazel using the --@rules_swift//swift:module_mapping build flag:

bazel build //some/package:Framework \
    --@rules_swift//swift:module_mapping=//some/package:mapping

When Utils is compiled, it will be given the module name GameUtils instead. Then, when Framework is compiled, it will import GameUtils anywhere that the source asked to import Utils.

ATTRIBUTES

swift_module_mapping_test

swift_module_mapping_test(name, deps, exclude, mapping)

Validates that a swift_module_mapping target covers all the modules in the transitive closure of a list of dependencies.

If you are building a static library or framework for external distribution and you are using swift_module_mapping to rename some of the modules used by your implementation, this rule will detect if any of your dependencies have taken on a new dependency that you need to add to the mapping (otherwise, its symbols would leak into your library with their original names).

When executed, this test will collect the names of all Swift modules in the transitive closure of deps. System modules and modules whose names are listed in the exclude attribute are omitted. Then, the test will fail if any of the remaining modules collected are not present in the aliases of the swift_module_mapping target specified by the mapping attribute.

ATTRIBUTES

swift_overlay

swift_overlay(name, deps, srcs, always_include_developer_search_paths, alwayslink, copts, defines,
              library_evolution, linkopts, linkstatic, package_name, plugins, private_deps,
              swiftc_inputs)

A Swift overlay that sits on top of a C/Objective-C library, allowing an author of a C/Objective-C library to create additional Swift-specific APIs that are automatically available when a Swift target depends on their C/Objective-C library.

The Swift overlay will only be compiled when other Swift targets depend on the original library that uses the overlay; non-Swift clients depending on the original library will not cause the Swift overlay code to be built or linked. This is done to retain optimium build performance and binary size for non-Swift clients. For this reason, swift_overlay is not a general purpose mechanism for creating mixed-language modules; swift_overlay does not support generation of an Objective-C header.

The swift_overlay rule does not perform any compilation of its own. Instead, it must be placed in the aspect_hints attribute of another rule such as objc_library or cc_library. For example,

objc_library(
    name = "MyModule",
    srcs = ["MyModule.m"],
    hdrs = ["MyModule.h"],
    aspect_hints = [":MyModule_overlay"],
    deps = [...],
)

swift_overlay(
    name = "MyModule_overlay",
    srcs = ["MyModule.swift"],
    deps = [...],
)

When some other Swift target, such as a swift_library, depends on MyModule, the Swift code in MyModule_overlay will be compiled into the same module. Therefore, when that library imports MyModule, it will see the APIs from the objc_library and the swift_overlay as a single combined module.

When writing a Swift overlay, the Swift code must do a re-exporting import of its own module in order to access the C/Objective-C APIs; they are not available automatically. Continuing the example above, any Swift sources that want to use or extend the API from the C/Objective-C side of the module would need to write the following:

@_exported import MyModule

The swift_overlay rule supports all the same attributes as swift_library, except for the following:

• module_name is not supported because the overlay inherits the same module name as the target it is attached to.
• generates_header and generated_header_name are not supported because it is assumed that the overlay is pure Swift code that does not export any APIs that would be of interest to C/Objective-C clients.

Aside from its module name and its underlying C/Objective-C module dependency, swift_overlay does not inherit anything else from its associated target. If the swift_overlay imports any modules other than its C/Objective-C side, the overlay target must explicitly depend on them as well. This means that an overlay can have a different set of dependencies than the underlying module, if desired.

There is a tight coupling between a Swift overlay and the C/Objective-C module to which it is being applied, so a specific swift_overlay target should only be referenced by the aspect_hints of a single objc_library or cc_library target. Referencing a swift_overlay from multiple targets' aspect_hints is almost always an anti-pattern.

ATTRIBUTES

swift_package_configuration

swift_package_configuration(name, configured_features, packages)

A compilation configuration to apply to the Swift targets in a set of packages.

A Swift toolchain target can reference any number (zero or more) of swift_package_configuration targets. When the compilation action for a target is being configured, those package configurations will be applied if the target's label is included by the package specifications in the configuration.

ATTRIBUTES

swift_proto_compiler

swift_proto_compiler(name, deps, bundled_proto_paths, plugin, plugin_name, plugin_option_allowlist,
                     plugin_options, protoc, suffixes)

ATTRIBUTES

protoc     --plugin=protoc-gen-NAME=path/to/plugin/binary

protoc     --plugin=protoc-gen-NAME=path/to/mybinary     --NAME_out=OUT_DIR     --NAME_opt=Visibility=Public

plugin_name = "swift"
plugin_options = {
"Visibility": "Public",
"FileNaming": "FullPath",
}

protoc     --plugin=protoc-gen-NAME=path/to/plugin/binary     --NAME_opt=Visibility=Public     --NAME_opt=FileNaming=FullPath

foo.proto => foo.pb.swift
foo_service.proto => foo.grpc.swift

swift_proto_library

swift_proto_library(name, deps, srcs, data, additional_compiler_deps, additional_compiler_info,
                    always_include_developer_search_paths, alwayslink, compilers, copts, defines,
                    generated_header_name, generates_header, library_evolution, linkopts, linkstatic,
                    module_name, package_name, plugins, protos, swiftc_inputs)

Generates a Swift static library from one or more targets producing ProtoInfo.

load("@protobuf//bazel:proto_library.bzl", "proto_library")
load("//proto:swift_proto_library.bzl", "swift_proto_library")

proto_library(
    name = "foo",
    srcs = ["foo.proto"],
)

swift_proto_library(
    name = "foo_swift",
    protos = [":foo"],
)

If your protos depend on protos from other targets, add dependencies between the swift_proto_library targets which mirror the dependencies between the proto targets.

load("@protobuf//bazel:proto_library.bzl", "proto_library")
load("//proto:swift_proto_library.bzl", "swift_proto_library")

proto_library(
    name = "bar",
    srcs = ["bar.proto"],
    deps = [":foo"],
)

swift_proto_library(
    name = "bar_swift",
    protos = [":bar"],
    deps = [":foo_swift"],
)

ATTRIBUTES

swift_proto_library_group

swift_proto_library_group(name, compiler, proto)

Generates a collection of Swift static library from a target producing ProtoInfo and its dependencies.

This rule is intended to facilitate migration from the deprecated swift proto library rules to the new ones. Unlike swift_proto_library which is a drop-in-replacement for swift_library, this rule uses an aspect over the direct proto library dependency and its transitive dependencies, compiling each into a swift static library.

For example, in the following targets, the proto_library_group_swift_proto target only depends on package_2_proto target, and this transitively depends on package_1_proto.

When used as a dependency from a swift_library or swift_binary target, two modules generated from these proto library targets are visible.

Because these are derived from the proto library targets via an aspect, though, you cannot customize many of the attributes including the swift proto compiler targets or the module names. The module names are derived from the proto library names.

In this case, the module names are:

import examples_xplatform_proto_library_group_package_1_package_1_proto
import examples_xplatform_proto_library_group_package_2_package_2_proto

For this reason, we would encourage new consumers of the proto rules to use swift_proto_library when possible.

proto_library(
    name = "package_1_proto",
    srcs = glob(["*.proto"]),
    visibility = ["//visibility:public"],
)

...

proto_library(
    name = "package_2_proto",
    srcs = glob(["*.proto"]),
    visibility = ["//visibility:public"],
    deps = ["//examples/xplatform/proto_library_group/package_1:package_1_proto"],
)

...

swift_proto_library_group(
    name = "proto_library_group_swift_proto",
    proto = "//examples/xplatform/proto_library_group/package_2:package_2_proto",
)

...

swift_binary(
    name = "proto_library_group_example",
    srcs = ["main.swift"],
    deps = [
        ":proto_library_group_swift_proto",
    ],
)

ATTRIBUTES

swift_test

swift_test(name, deps, srcs, data, additional_linker_inputs, copts, defines, discover_tests, env,
           env_inherit, linkopts, malloc, module_name, package_name, plugins, stamp, swiftc_inputs)

Compiles and links Swift code into an executable test target.

XCTest Test Discovery

By default, this rule performs test discovery that finds tests written with the XCTest framework and executes them automatically, without the user providing their own main entry point.

On Apple platforms, XCTest-style tests are automatically discovered and executed using the Objective-C runtime. To provide the same behavior on Linux, the swift_test rule performs its own scan for XCTest-style tests. In other words, you can write a single swift_test target that executes the same tests on either Linux or Apple platforms.

There are two approaches that one can take to write a swift_test that supports test discovery:

1. Preferred approach: Write a swift_test target whose srcs contain your tests. In this mode, only these sources will be scanned for tests; direct dependencies will not be scanned.

2. Write a swift_test target with no srcs. In this mode, all direct dependencies of the target will be scanned for tests; indirect dependencies will not be scanned. This approach is useful if you want to share tests with an Apple-specific test target like ios_unit_test.

See the documentation of the discover_tests attribute for more information about how this behavior affects the rule's outputs.

Test Bundles

The swift_test rule always produces a standard executable binary. This is true even when targeting macOS, where the typical practice is to use a Mach-O bundle binary. However, when targeting macOS, the executable binary is still generated inside a bundle-like directory structure: {name}.xctest/Contents/MacOS/{name}. This allows tests to still work if they contain logic that looks for the path to their bundle.

Test Filtering

swift_test supports Bazel's --test_filter flag on all platforms (i.e., Apple and Linux), which can be used to run only a subset of tests. The test filter can be a test name of the form ClassName/MethodName or a regular expression that matches names of that form.

For example,

• --test_filter='ArrayTests/testAppend' would only run the test method testAppend in the ArrayTests class.

• --test_filter='ArrayTests/test(App.*|Ins.*)' would run all test methods starting with testApp or testIns in the ArrayTests class.

Xcode Integration

If integrating with Xcode, the relative paths in test binaries can prevent the Issue navigator from working for test failures. To work around this, you can have the paths made absolute via swizzling by enabling the "apple.swizzle_absolute_xcttestsourcelocation" feature. You'll also need to set the BUILD_WORKSPACE_DIRECTORY environment variable in your scheme to the root of your workspace (i.e. $(SRCROOT)).

ATTRIBUTES

universal_swift_compiler_plugin

universal_swift_compiler_plugin(name, plugin)

Wraps an existing swift_compiler_plugin target to produce a universal binary.

This is useful to allow sharing of caches between Intel and Apple Silicon Macs at the cost of building everything twice.

Example:

# The actual macro code, using SwiftSyntax, as usual.
swift_compiler_plugin(
    name = "Macros",
    srcs = glob(["Macros/*.swift"]),
    deps = [
        "@swift-syntax//:SwiftSyntax",
        "@swift-syntax//:SwiftCompilerPlugin",
        "@swift-syntax//:SwiftSyntaxMacros",
    ],
)

# Wrap your compiler plugin in this universal shim.
universal_swift_compiler_plugin(
    name = "Macros.universal",
    plugin = ":Macros",
)

# The library that defines the macro hook for use in your project, this
# references the universal_swift_compiler_plugin.
swift_library(
    name = "MacroLibrary",
    srcs = glob(["MacroLibrary/*.swift"]),
    plugins = [":Macros.universal"],
)

ATTRIBUTES

mixed_language_library

mixed_language_library(*, name, additional_objc_compiler_inputs,
                       always_include_developer_search_paths, alwayslink, clang_copts, clang_defines,
                       clang_deps, clang_srcs, data, enable_modules, hdrs, includes, linkopts,
                       module_map, module_name, non_arc_srcs, package_name, private_deps, sdk_dylibs,
                       sdk_frameworks, swift_copts, swift_defines, swift_plugins, swift_srcs,
                       swiftc_inputs, textual_hdrs, umbrella_header, weak_sdk_frameworks, deps,
                       **kwargs)

Creates a mixed language library from a Clang and Swift library target pair.

Note: In the future swift_library will support mixed-language libraries. Once that is the case, this macro will be deprecated.

PARAMETERS