Skip to content

Latest commit

 

History

History
804 lines (603 loc) · 72.6 KB

rules.md

File metadata and controls

804 lines (603 loc) · 72.6 KB
Raw

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("@build_bazel_rules_swift//swift:swift_library.bzl", "swift_library")
load("@build_bazel_rules_swift//proto:swift_proto_library.bzl", "swift_proto_library")

On this page:

swift_binary

swift_binary(name, deps, srcs, data, copts, defines, linkopts, 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 fat 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.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of targets that are dependencies of the target being built, which will be linked into that target.

If the Swift toolchain supports implementation-only imports (private_deps on swift_library), then targets in deps are treated as regular (non-implementation-only) imports that are propagated both to their direct and indirect (transitive) dependents.

Allowed kinds of dependencies are:

* swift_library (or anything propagating SwiftInfo)

* cc_library (or anything propagating CcInfo)

Additionally, on platforms that support Objective-C interop, objc_library targets (or anything propagating the apple_common.Objc provider) are allowed as dependencies. On platforms that do not support Objective-C interop (such as Linux), those dependencies will be ignored.		 List of labels optional []
srcs A list of .swift source files that will be compiled into the library. List of labels optional []
data The list of files needed by this target at runtime.

Files and targets named in the data attribute will appear in the *.runfiles area of this target, if it has one. This may include data files needed by a binary or library, or other programs needed by it.		 List of labels optional []
copts Additional compiler options that should be passed to swiftc. These strings are subject to $(location ...) and "Make" variable expansion. List of strings optional []
defines A list of defines to add to the compilation command line.

Note that unlike C-family languages, Swift defines do not have values; they are simply identifiers that are either defined or undefined. So strings in this list should be simple identifiers, not name=value pairs.

Each string is prepended with -D and added to the command line. Unlike copts, these flags are added for the target and every target that depends on it, so use this attribute with caution. It is preferred that you add defines directly to copts, only using this feature in the rare case that a library needs to propagate a symbol up to those that depend on it.		 List of strings optional []
linkopts Additional linker options that should be passed to clang. These strings are subject to $(location ...) expansion. List of strings optional []
malloc Override the default dependency on malloc.

By default, Swift binaries are linked against @bazel_tools//tools/cpp:malloc", which is an empty library and the resulting binary will use libc's malloc. This label must refer to a cc_library rule.		 Label optional "@bazel_tools//tools/cpp:malloc"
module_name The name of the Swift module being built.

If left unspecified, the module name will be computed based on the target's build label, by stripping the leading // and replacing /, :, and other non-identifier characters with underscores.		 String optional ""
package_name The semantic package of the Swift target being built. Targets with the same package_name can access APIs using the 'package' access control modifier in Swift 5.9+. String optional ""
plugins A list of swift_compiler_plugin targets that should be loaded by the compiler when compiling this module and any modules that directly depend on it. List of labels optional []
stamp Enable or disable link stamping; that is, whether to encode build information into the binary. Possible values are:

* stamp = 1: Stamp the build information into the binary. Stamped binaries are only rebuilt when their dependencies change. Use this if there are tests that depend on the build information.

* 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 flag.		 Integer optional -1
swiftc_inputs Additional files that are referenced using $(location ...) in attributes that support location expansion. List of labels optional []

swift_compiler_plugin

swift_compiler_plugin(name, deps, srcs, data, 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 = [
        "@SwiftSyntax",
        "@SwiftSyntax//:SwiftCompilerPlugin",
        "@SwiftSyntax//:SwiftSyntaxMacros",
    ],
)

# A target testing the macro itself
swift_test(
    name = "MacrosTests",
    srcs = glob(["MacrosTests/*.swift"]),
    deps = [
        ":Macros",
        "@SwiftSyntax//: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

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of targets that are dependencies of the target being built, which will be linked into that target.

If the Swift toolchain supports implementation-only imports (private_deps on swift_library), then targets in deps are treated as regular (non-implementation-only) imports that are propagated both to their direct and indirect (transitive) dependents.

Allowed kinds of dependencies are:

* swift_library (or anything propagating SwiftInfo)

* cc_library (or anything propagating CcInfo)

Additionally, on platforms that support Objective-C interop, objc_library targets (or anything propagating the apple_common.Objc provider) are allowed as dependencies. On platforms that do not support Objective-C interop (such as Linux), those dependencies will be ignored.		 List of labels optional []
srcs A list of .swift source files that will be compiled into the library. List of labels optional []
data The list of files needed by this target at runtime.

Files and targets named in the data attribute will appear in the *.runfiles area of this target, if it has one. This may include data files needed by a binary or library, or other programs needed by it.		 List of labels optional []
copts Additional compiler options that should be passed to swiftc. These strings are subject to $(location ...) and "Make" variable expansion. List of strings optional []
defines A list of defines to add to the compilation command line.

Note that unlike C-family languages, Swift defines do not have values; they are simply identifiers that are either defined or undefined. So strings in this list should be simple identifiers, not name=value pairs.

Each string is prepended with -D and added to the command line. Unlike copts, these flags are added for the target and every target that depends on it, so use this attribute with caution. It is preferred that you add defines directly to copts, only using this feature in the rare case that a library needs to propagate a symbol up to those that depend on it.		 List of strings optional []
linkopts Additional linker options that should be passed to clang. These strings are subject to $(location ...) expansion. List of strings optional []
malloc Override the default dependency on malloc.

By default, Swift binaries are linked against @bazel_tools//tools/cpp:malloc", which is an empty library and the resulting binary will use libc's malloc. This label must refer to a cc_library rule.		 Label optional "@bazel_tools//tools/cpp:malloc"
module_name The name of the Swift module being built.

If left unspecified, the module name will be computed based on the target's build label, by stripping the leading // and replacing /, :, and other non-identifier characters with underscores.		 String optional ""
package_name The semantic package of the Swift target being built. Targets with the same package_name can access APIs using the 'package' access control modifier in Swift 5.9+. String optional ""
plugins A list of swift_compiler_plugin targets that should be loaded by the compiler when compiling this module and any modules that directly depend on it. List of labels optional []
stamp Enable or disable link stamping; that is, whether to encode build information into the binary. Possible values are:

* stamp = 1: Stamp the build information into the binary. Stamped binaries are only rebuilt when their dependencies change. Use this if there are tests that depend on the build information.

* 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 flag.		 Integer optional 0
swiftc_inputs Additional files that are referenced using $(location ...) in attributes that support location expansion. List of labels optional []

swift_feature_allowlist

swift_feature_allowlist(name, 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

Name Description Type Mandatory Default
name A unique name for this target. Name required
managed_features A list of feature strings that are permitted to be specified by the targets in the packages matched by the packages attribute. This list may include both feature names and/or negations (a name with a leading -); a regular feature name means that the targets in the matching packages may explicitly request that the feature be enabled, and a negated feature means that the target may explicitly request that the feature be disabled.

For example, managed_features = ["foo", "-bar"] means that targets in the allowlist's packages may request that feature "foo" be enabled and that feature "bar" be disabled.		 List of strings optional []
packages A list of strings representing packages (possibly recursive) whose targets are allowed to enable/disable the features in managed_features. Each package pattern is written in the syntax used by the package_group function:

* //foo/bar: Targets in the package //foo/bar but not in subpackages. * //foo/bar/...: Targets in the package //foo/bar and any of its subpackages. * A leading - excludes packages that would otherwise have been included by the patterns in the list.

Exclusions always take priority over inclusions; order in the list is irrelevant.		 List of strings required

swift_import

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

Allows for the use of Swift textual module interfaces 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

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of targets that are dependencies of the target being built, which will be linked into that target.

If the Swift toolchain supports implementation-only imports (private_deps on swift_library), then targets in deps are treated as regular (non-implementation-only) imports that are propagated both to their direct and indirect (transitive) dependents.

Allowed kinds of dependencies are:

* swift_library (or anything propagating SwiftInfo)

* cc_library (or anything propagating CcInfo)

Additionally, on platforms that support Objective-C interop, objc_library targets (or anything propagating the apple_common.Objc provider) are allowed as dependencies. On platforms that do not support Objective-C interop (such as Linux), those dependencies will be ignored.		 List of labels optional []
data The list of files needed by this target at runtime.

Files and targets named in the data attribute will appear in the *.runfiles area of this target, if it has one. This may include data files needed by a binary or library, or other programs needed by it.		 List of labels optional []
archives The list of .a files provided to Swift targets that depend on this target. List of labels optional []
module_name The name of the module represented by this target. String required
swiftdoc The .swiftdoc file provided to Swift targets that depend on this target. Label optional None
swiftinterface The .swiftinterface file that defines the module interface for this target. May not be specified if swiftmodule is specified. Label optional None
swiftmodule The .swiftmodule file provided to Swift targets that depend on this target. May not be specified if swiftinterface is specified. Label optional None

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.

Note

Bazel 6 users must set the --experimental_enable_aspect_hints flag to utilize this rule. In addition, downstream consumers of rules that utilize this rule must also set the flag. The flag is enabled by default in Bazel 7.

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 @build_bazel_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 = ["@build_bazel_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 @build_bazel_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 = ["@build_bazel_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

Name Description Type Mandatory Default
name A unique name for this target. Name required
exclude_hdrs A list of header files that should be excluded from the Clang module generated for the target to which this hint is applied. This allows a target to exclude a subset of a library's headers specifically from the Swift module map without removing them from the library completely, which can be useful if some headers are not Swift-compatible but are still needed by other sources in the library or by non-Swift dependents.

This attribute may only be specified if a custom module_map is not provided. Setting both attributes is an error.		 List of labels optional []
module_map An optional custom .modulemap file that defines the Clang module for the headers in the target to which this hint is applied.

If this attribute is omitted, a module map will be automatically generated based on the headers in the hinted target.

If this attribute is provided, then module_name must also be provided and match the name of the desired top-level module in the .modulemap file. (A single .modulemap file may define multiple top-level modules.)		 Label optional None
module_name The name that will be used to import the hinted module into Swift.

If left unspecified, the module name will be computed based on the hinted target's build label, by stripping the leading // and replacing /, :, and other non-identifier characters with underscores.		 String optional ""
suppressed If True, the hinted target should suppress any module that it would otherwise generate. Boolean optional False

swift_library

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

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

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of targets that are dependencies of the target being built, which will be linked into that target.

If the Swift toolchain supports implementation-only imports (private_deps on swift_library), then targets in deps are treated as regular (non-implementation-only) imports that are propagated both to their direct and indirect (transitive) dependents.

Allowed kinds of dependencies are:

* swift_library (or anything propagating SwiftInfo)

* cc_library (or anything propagating CcInfo)

Additionally, on platforms that support Objective-C interop, objc_library targets (or anything propagating the apple_common.Objc provider) are allowed as dependencies. On platforms that do not support Objective-C interop (such as Linux), those dependencies will be ignored.		 List of labels optional []
srcs A list of .swift source files that will be compiled into the library. List of labels required
data The list of files needed by this target at runtime.

Files and targets named in the data attribute will appear in the *.runfiles area of this target, if it has one. This may include data files needed by a binary or library, or other programs needed by it.		 List of labels optional []
always_include_developer_search_paths If True, the developer framework search paths will be added to the compilation command. This enables a Swift module to access XCTest without having to mark the target as testonly = True. Boolean optional False
alwayslink If true, any binary that depends (directly or indirectly) on this Swift module will link in all the object files for the files listed in srcs, 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; for example, if you rely on runtime checks for protocol conformances added in extensions in the library but do not directly reference any other symbols in the object file that adds that conformance. Boolean optional False
copts Additional compiler options that should be passed to swiftc. These strings are subject to $(location ...) and "Make" variable expansion. List of strings optional []
defines A list of defines to add to the compilation command line.

Note that unlike C-family languages, Swift defines do not have values; they are simply identifiers that are either defined or undefined. So strings in this list should be simple identifiers, not name=value pairs.

Each string is prepended with -D and added to the command line. Unlike copts, these flags are added for the target and every target that depends on it, so use this attribute with caution. It is preferred that you add defines directly to copts, only using this feature in the rare case that a library needs to propagate a symbol up to those that depend on it.		 List of strings optional []
generated_header_name The name of the generated Objective-C interface header. This name must end with a .h extension and cannot contain any path separators.

If this attribute is not specified, then the default behavior is to name the header ${target_name}-Swift.h.

This attribute is ignored if the toolchain does not support generating headers.		 String optional ""
generates_header If True, an Objective-C header will be generated for this target, in the same build package where the target is defined. By default, the name of the header is ${target_name}-Swift.h; this can be changed using the generated_header_name attribute.

Targets should only set this attribute to True if they export Objective-C APIs. A header generated for a target that does not export Objective-C APIs will be effectively empty (except for a large amount of prologue and epilogue code) and this is generally wasteful because the extra file needs to be propagated in the build graph and, when explicit modules are enabled, extra actions must be executed to compile the Objective-C module for the generated header.		 Boolean optional False
linkopts Additional linker options that should be passed to the linker for the binary that depends on this target. These strings are subject to $(location ...) and "Make" variable expansion. List of strings optional []
linkstatic If True, the Swift module will be built for static linking. This will make all interfaces internal to the module that is being linked against and will inform the consuming module that the objects will be locally available (which may potentially avoid a PLT relocation). Set to False to build a .so or .dll. Boolean optional True
module_name The name of the Swift module being built.

If left unspecified, the module name will be computed based on the target's build label, by stripping the leading // and replacing /, :, and other non-identifier characters with underscores.		 String optional ""
package_name The semantic package of the Swift target being built. Targets with the same package_name can access APIs using the 'package' access control modifier in Swift 5.9+. String optional ""
plugins A list of swift_compiler_plugin targets that should be loaded by the compiler when compiling this module and any modules that directly depend on it. List of labels optional []
private_deps A list of targets that are implementation-only dependencies of the target being built. Libraries/linker flags from these dependencies will be propagated to dependent for linking, but artifacts/flags required for compilation (such as .swiftmodule files, C headers, and search paths) will not be propagated.

Allowed kinds of dependencies are:

* swift_library (or anything propagating SwiftInfo)

* cc_library (or anything propagating CcInfo)

Additionally, on platforms that support Objective-C interop, objc_library targets (or anything propagating the apple_common.Objc provider) are allowed as dependencies. On platforms that do not support Objective-C interop (such as Linux), those dependencies will be ignored.		 List of labels optional []
swiftc_inputs Additional files that are referenced using $(location ...) in attributes that support location expansion. List of labels optional []

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.

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

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of targets that should be included in the group. Allowed kinds of dependencies are:

* swift_library (or anything propagating SwiftInfo)

* cc_library (or anything propagating CcInfo)

Additionally, on platforms that support Objective-C interop, objc_library targets (or anything propagating the apple_common.Objc provider) are allowed as dependencies. On platforms that do not support Objective-C interop (such as Linux), those dependencies will be ignored.		 List of labels optional []

swift_module_alias

swift_module_alias(name, deps, module_name)

Creates a Swift module that re-exports other modules.

This rule effectively creates an "alias" for one or more modules such that a client can import the alias module and it will implicitly import those dependencies. It should be used primarily as a way to migrate users when a module name is being changed. An alias that depends on more than one module can be used to split a large module into smaller, more targeted modules.

Symbols in the original modules can be accessed through either the original module name or the alias module name, so callers can be migrated separately after moving the physical build target as needed. (An exception to this is runtime type metadata, which only encodes the module name of the type where the symbol is defined; it is not repeated by the alias module.)

Caution: This rule uses the undocumented @_exported feature to re-export the deps in the new module. You depend on undocumented features at your own risk, as they may change in a future version of Swift.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of targets that are dependencies of the target being built, which will be linked into that target. Allowed kinds are swift_import and swift_library (or anything else propagating SwiftInfo). List of labels optional []
module_name The name of the Swift module being built.

If left unspecified, the module name will be computed based on the target's build label, by stripping the leading // and replacing /, :, and other non-identifier characters with underscores.		 String optional ""

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

Name Description Type Mandatory Default
name A unique name for this target. Name required
configured_features A list of feature strings that will be applied by default to targets in the packages matched by the packages attribute, as if they had been specified by the package(features = ...) rule in the BUILD file.

This list may include both feature names and/or negations (a name with a leading -); a regular feature name means that the targets in the matching packages will have the feature enabled, and a negated feature means that the target will have the feature disabled.

For example, configured_features = ["foo", "-bar"] means that targets in the configuration's packages will have the feature "foo" enabled by default and the feature "bar" disabled by default.		 List of strings optional []
packages A list of strings representing packages (possibly recursive) whose targets will have this package configuration applied. Each package pattern is written in the syntax used by the package_group function:

* //foo/bar: Targets in the package //foo/bar but not in subpackages. * //foo/bar/...: Targets in the package //foo/bar and any of its subpackages. * A leading - excludes packages that would otherwise have been included by the patterns in the list.

Exclusions always take priority over inclusions; order in the list is irrelevant.		 List of strings required

swift_proto_compiler

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

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps List of targets providing SwiftInfo and CcInfo. Added as implicit dependencies for any swift_proto_library using this compiler. Typically, these are Well Known Types and proto runtime libraries. List of labels optional []
bundled_proto_paths List of proto paths for which to skip generation because they're built into the modules imported by the generated Swift proto code, e.g., SwiftProtobuf. List of strings optional ["google/protobuf/any.proto", "google/protobuf/api.proto", "google/protobuf/descriptor.proto", "google/protobuf/duration.proto", "google/protobuf/empty.proto", "google/protobuf/field_mask.proto", "google/protobuf/source_context.proto", "google/protobuf/struct.proto", "google/protobuf/timestamp.proto", "google/protobuf/type.proto", "google/protobuf/wrappers.proto"]
plugin A proto compiler plugin executable binary.

For example: "//tools/protoc_wrapper:protoc-gen-grpc-swift" "//tools/protoc_wrapper:ProtoCompilerPlugin"		 Label required
plugin_name Name of the proto compiler plugin passed to protoc.

For example:

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


This name will be used to prefix the option and output directory arguments. E.g.:

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


See the protobuf API reference for more information.		 String required
plugin_option_allowlist Allowlist of options allowed by the plugin. This is used to filter out any irrelevant plugin options passed down to the compiler from the library, which is especially useful when using multiple plugins in combination like GRPC and SwiftProtobuf. List of strings required
plugin_options Dictionary of plugin options passed to the plugin.

These are prefixed with the plugin_name + "_opt". E.g.:

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


Would be passed to protoc as:

protoc     --plugin=protoc-gen-NAME=path/to/plugin/binary     --NAME_opt=Visibility=Public     --NAME_opt=FileNaming=FullPath
 Dictionary: String -> String required
protoc A proto compiler executable binary.

E.g. "//tools/protoc_wrapper:protoc"		 Label required
suffixes Suffix used for Swift files generated by the plugin from protos.

E.g.

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


Each compiler target should configure this based on the suffix applied to the generated files.		 List of strings required

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, linkopts, linkstatic, module_name,
                    package_name, plugins, protos, swiftc_inputs)

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

load("@rules_proto//proto:defs.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("@rules_proto//proto:defs.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

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of targets that are dependencies of the target being built, which will be linked into that target.

If the Swift toolchain supports implementation-only imports (private_deps on swift_library), then targets in deps are treated as regular (non-implementation-only) imports that are propagated both to their direct and indirect (transitive) dependents.

Allowed kinds of dependencies are:

* swift_library (or anything propagating SwiftInfo)

* cc_library (or anything propagating CcInfo)

Additionally, on platforms that support Objective-C interop, objc_library targets (or anything propagating the apple_common.Objc provider) are allowed as dependencies. On platforms that do not support Objective-C interop (such as Linux), those dependencies will be ignored.		 List of labels optional []
srcs A list of .swift source files that will be compiled into the library. List of labels optional []
data The list of files needed by this target at runtime.

Files and targets named in the data attribute will appear in the *.runfiles area of this target, if it has one. This may include data files needed by a binary or library, or other programs needed by it.		 List of labels optional []
additional_compiler_deps List of additional dependencies required by the generated Swift code at compile time, whose SwiftProtoInfo will be ignored.

Allowed kinds of dependencies are:

* swift_library (or anything propagating SwiftInfo)

* cc_library (or anything propagating CcInfo)

Additionally, on platforms that support Objective-C interop, objc_library targets (or anything propagating the apple_common.Objc provider) are allowed as dependencies. On platforms that do not support Objective-C interop (such as Linux), those dependencies will be ignored.		 List of labels optional []
additional_compiler_info Dictionary of additional information passed to the compiler targets. See the documentation of the respective compiler rules for more information on which fields are accepted and how they are used. Dictionary: String -> String optional {}
always_include_developer_search_paths If True, the developer framework search paths will be added to the compilation command. This enables a Swift module to access XCTest without having to mark the target as testonly = True. Boolean optional False
alwayslink If true, any binary that depends (directly or indirectly) on this Swift module will link in all the object files for the files listed in srcs, 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; for example, if you rely on runtime checks for protocol conformances added in extensions in the library but do not directly reference any other symbols in the object file that adds that conformance. Boolean optional False
compilers One or more swift_proto_compiler targets (or targets producing SwiftProtoCompilerInfo), from which the Swift protos will be generated. List of labels optional ["@rules_swift//proto/compilers:swift_proto"]
copts Additional compiler options that should be passed to swiftc. These strings are subject to $(location ...) and "Make" variable expansion. List of strings optional []
defines A list of defines to add to the compilation command line.

Note that unlike C-family languages, Swift defines do not have values; they are simply identifiers that are either defined or undefined. So strings in this list should be simple identifiers, not name=value pairs.

Each string is prepended with -D and added to the command line. Unlike copts, these flags are added for the target and every target that depends on it, so use this attribute with caution. It is preferred that you add defines directly to copts, only using this feature in the rare case that a library needs to propagate a symbol up to those that depend on it.		 List of strings optional []
generated_header_name The name of the generated Objective-C interface header. This name must end with a .h extension and cannot contain any path separators.

If this attribute is not specified, then the default behavior is to name the header ${target_name}-Swift.h.

This attribute is ignored if the toolchain does not support generating headers.		 String optional ""
generates_header If True, an Objective-C header will be generated for this target, in the same build package where the target is defined. By default, the name of the header is ${target_name}-Swift.h; this can be changed using the generated_header_name attribute.

Targets should only set this attribute to True if they export Objective-C APIs. A header generated for a target that does not export Objective-C APIs will be effectively empty (except for a large amount of prologue and epilogue code) and this is generally wasteful because the extra file needs to be propagated in the build graph and, when explicit modules are enabled, extra actions must be executed to compile the Objective-C module for the generated header.		 Boolean optional False
linkopts Additional linker options that should be passed to the linker for the binary that depends on this target. These strings are subject to $(location ...) and "Make" variable expansion. List of strings optional []
linkstatic If True, the Swift module will be built for static linking. This will make all interfaces internal to the module that is being linked against and will inform the consuming module that the objects will be locally available (which may potentially avoid a PLT relocation). Set to False to build a .so or .dll. Boolean optional True
module_name The name of the Swift module being built.

If left unspecified, the module name will be computed based on the target's build label, by stripping the leading // and replacing /, :, and other non-identifier characters with underscores.		 String optional ""
package_name The semantic package of the Swift target being built. Targets with the same package_name can access APIs using the 'package' access control modifier in Swift 5.9+. String optional ""
plugins A list of swift_compiler_plugin targets that should be loaded by the compiler when compiling this module and any modules that directly depend on it. List of labels optional []
protos A list of proto_library targets (or targets producing ProtoInfo), from which the Swift source files should be generated. List of labels optional []
swiftc_inputs Additional files that are referenced using $(location ...) in attributes that support location expansion. List of labels optional []

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

Name Description Type Mandatory Default
name A unique name for this target. Name required
compiler A swift_proto_compiler target (or target producing SwiftProtoCompilerInfo), from which the Swift protos will be generated. Label optional "@rules_swift//proto/compilers:swift_proto"
proto Exactly one proto_library target (or target producing ProtoInfo), from which the Swift source files should be generated. Label required

swift_test

swift_test(name, deps, srcs, data, copts, defines, discover_tests, env, 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.


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

### Test Filtering

A subset of tests for a given target can be executed via the `--test_filter` parameter:

bazel test //:Tests --test_filter=TestModuleName.TestClassName/testMethodName


**ATTRIBUTES**


| Name  | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="swift_test-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
| <a id="swift_test-deps"></a>deps |  A list of targets that are dependencies of the target being built, which will be linked into that target.<br><br>If the Swift toolchain supports implementation-only imports (`private_deps` on `swift_library`), then targets in `deps` are treated as regular (non-implementation-only) imports that are propagated both to their direct and indirect (transitive) dependents.<br><br>Allowed kinds of dependencies are:<br><br>*   `swift_library` (or anything propagating `SwiftInfo`)<br><br>*   `cc_library` (or anything propagating `CcInfo`)<br><br>Additionally, on platforms that support Objective-C interop, `objc_library` targets (or anything propagating the `apple_common.Objc` provider) are allowed as dependencies. On platforms that do not support Objective-C interop (such as Linux), those dependencies will be **ignored.**   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |
| <a id="swift_test-srcs"></a>srcs |  A list of `.swift` source files that will be compiled into the library.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |
| <a id="swift_test-data"></a>data |  The list of files needed by this target at runtime.<br><br>Files and targets named in the `data` attribute will appear in the `*.runfiles` area of this target, if it has one. This may include data files needed by a binary or library, or other programs needed by it.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |
| <a id="swift_test-copts"></a>copts |  Additional compiler options that should be passed to `swiftc`. These strings are subject to `$(location ...)` and ["Make" variable](https://docs.bazel.build/versions/master/be/make-variables.html) expansion.   | List of strings | optional |  `[]`  |
| <a id="swift_test-defines"></a>defines |  A list of defines to add to the compilation command line.<br><br>Note that unlike C-family languages, Swift defines do not have values; they are simply identifiers that are either defined or undefined. So strings in this list should be simple identifiers, **not** `name=value` pairs.<br><br>Each string is prepended with `-D` and added to the command line. Unlike `copts`, these flags are added for the target and every target that depends on it, so use this attribute with caution. It is preferred that you add defines directly to `copts`, only using this feature in the rare case that a library needs to propagate a symbol up to those that depend on it.   | List of strings | optional |  `[]`  |
| <a id="swift_test-discover_tests"></a>discover_tests |  Determines whether or not tests are automatically discovered in the binary. The default value is `True`.<br><br>If tests are discovered, then you should not provide your own `main` entry point in the `swift_test` binary; the test runtime provides the entry point for you. If you set this attribute to `False`, then you are responsible for providing your own `main`. This allows you to write tests that use a framework other than Apple's `XCTest`. The only requirement of such a test is that it terminate with a zero exit code for success or a non-zero exit code for failure.<br><br>Additionally, on Apple platforms, test discovery is handled by the Objective-C runtime and the output of a `swift_test` rule is an `.xctest` bundle that is invoked using the `xctest` tool in Xcode. If this attribute is used to disable test discovery, then the output of the `swift_test` rule will instead be a standard executable binary that is invoked directly.   | Boolean | optional |  `True`  |
| <a id="swift_test-env"></a>env |  Dictionary of environment variables that should be set during the test execution.   | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional |  `{}`  |
| <a id="swift_test-linkopts"></a>linkopts |  Additional linker options that should be passed to `clang`. These strings are subject to `$(location ...)` expansion.   | List of strings | optional |  `[]`  |
| <a id="swift_test-malloc"></a>malloc |  Override the default dependency on `malloc`.<br><br>By default, Swift binaries are linked against `@bazel_tools//tools/cpp:malloc"`, which is an empty library and the resulting binary will use libc's `malloc`. This label must refer to a `cc_library` rule.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional |  `"@bazel_tools//tools/cpp:malloc"`  |
| <a id="swift_test-module_name"></a>module_name |  The name of the Swift module being built.<br><br>If left unspecified, the module name will be computed based on the target's build label, by stripping the leading `//` and replacing `/`, `:`, and other non-identifier characters with underscores.   | String | optional |  `""`  |
| <a id="swift_test-package_name"></a>package_name |  The semantic package of the Swift target being built. Targets with the same package_name can access APIs using the 'package' access control modifier in Swift 5.9+.   | String | optional |  `""`  |
| <a id="swift_test-plugins"></a>plugins |  A list of `swift_compiler_plugin` targets that should be loaded by the compiler when compiling this module and any modules that directly depend on it.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |
| <a id="swift_test-stamp"></a>stamp |  Enable or disable link stamping; that is, whether to encode build information into the binary. Possible values are:<br><br>* `stamp = 1`: Stamp the build information into the binary. Stamped binaries are   only rebuilt when their dependencies change. Use this if there are tests that   depend on the build information.<br><br>* `stamp = 0`: Always replace build information by constant values. This gives   good build result caching.<br><br>* `stamp = -1`: Embedding of build information is controlled by the   `--[no]stamp` flag.   | Integer | optional |  `0`  |
| <a id="swift_test-swiftc_inputs"></a>swiftc_inputs |  Additional files that are referenced using `$(location ...)` in attributes that support location expansion.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |


<a id="universal_swift_compiler_plugin"></a>

## universal_swift_compiler_plugin

<pre>
universal_swift_compiler_plugin(<a href="#universal_swift_compiler_plugin-name">name</a>, <a href="#universal_swift_compiler_plugin-plugin">plugin</a>)
</pre>

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:

```bzl
# The actual macro code, using SwiftSyntax, as usual.
swift_compiler_plugin(
    name = "Macros",
    srcs = glob(["Macros/*.swift"]),
    deps = [
        "@SwiftSyntax",
        "@SwiftSyntax//:SwiftCompilerPlugin",
        "@SwiftSyntax//: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

Name Description Type Mandatory Default
name A unique name for this target. Name required
plugin Target to generate a 'fat' binary from. Label required