swift_macro
Swift compiler-plugin executable built for the host.
Description#
Compiles Swift sources into a macOS host executable that the Swift compiler
loads at compile time. The macro implementation typically depends on a
swift-syntax checkout supplied through deps. Any
apple_library dependency edge that
reaches a swift_macro target picks up the executable and declaring module
automatically.
A macro is a tool for the targets that expand it, so its code stays out of what
they link. A target that unit-tests the macro is the exception: it imports the
module to reach the implementation types, so an
apple_test_bundle that depends on a
macro compiles and links against it. A macro only ever builds for the host, so
such a test target builds for the host too, and so does everything it depends
on.
Attributes#
explicit_modules is a boolean, defaulting to false, that enables
compiler-scanned, cacheable Swift and Clang module actions.
dependency_check accepts "off" (the default) or "error"; checking
requires explicit modules. See explicit modules
for native propagation, dependency errors, and current limitations.
The resolver-owned _declared_deps metadata preserves declarations before
import inference and should not be authored manually.
| Attribute | Type | Required | Default | Description |
|---|---|---|---|---|
minimum_os | string | no | "13.0" | Minimum macOS version for the host plugin |
module_name | string | no | target name | Compiled module name (not configurable) |
swift_flags | list<string> | no | [] | Extra Swift compiler flags |
xcode_developer_dir | string | no | Pin a specific Xcode by overriding DEVELOPER_DIR. Folded into the action cache key |
Dependency Edges#
| Edge | Accepts | Description |
|---|---|---|
deps | apple_linkable | Libraries the plugin links against (typically a swift-syntax checkout) |
Providers#
The target emits apple_swift_plugin.
Capabilities#
| Capability | Output groups |
|---|---|
build | default, plugin_executable, swiftmodule |
Provider record#
| Field | Type | Meaning |
|---|---|---|
label_id | string | Canonical target id |
plugin_executable | string | Path to the produced macOS host executable |
plugin_module_name | string | Declaring module name paired with the executable by downstream compilers |
transitive_plugin_executables | list<string> | <path>#<module> descriptors propagated through libraries and frameworks |
Outputs#
| Output | Location |
|---|---|
| Plugin executable | .once/out/<target>/<module_name>-tool |
| Swift module | .once/out/<target>/<module_name>.swiftmodule |
Example#
[[target]]
name = "StringifyMacro"
kind = "swift_macro"
srcs = ["Sources/**/*.swift"]
deps = [
"//third_party/swift-syntax:SwiftSyntax",
"//third_party/swift-syntax:SwiftCompilerPlugin",
]