`swift_package_workspace`

Native Swift Package Manager workspace seed.

Description#

swift_package_workspace reads Package.swift through Swift Package Manager and lowers first-party libraries, executables, macros, binary targets, and tests into the existing Apple target kinds. The package manifest remains authoritative for products, target dependencies, source layout, compiler settings, resources, and platform constraints.

Executable products are linked into Apple application bundles, so their compiled executable is a declared build output alongside the bundle metadata.

Once discovers a workspace automatically from Package.swift. A repository without once.toml can therefore query and build its first-party package targets directly. Discovery skips generated package-manager state such as .build and .swiftpm.

Local path dependencies within the workspace are expanded transitively and shared package identities are deduplicated. A graph containing only local dependencies requires no lockfile or dependency-resolution command. Remote dependencies introduced by a local package still use the root package's resolved dependency versions.

A product can group several targets. Depending on that product includes every target it exports, even when one target has the same name as the product.

For source-control dependencies, the resolver uses Package.resolved or asks Swift Package Manager to create it when it is absent. It materializes the pinned sources and lowers their package targets into the same Apple target kinds. Once compiles those targets directly with the selected Swift compiler. Swift Package Manager supplies manifest and lockfile metadata, but does not build the dependency products. Registry dependencies are not supported by native package lowering yet.

Library targets are force-loaded into whatever links them, matching how Swift Package Manager hands the linker every object file a target produced. A source file whose only contribution is a protocol conformance would otherwise be dropped, and the conformance would be missing at runtime.

Package traits follow the declarations in Package.swift. Once enables the root package's defaults, combines traits requested by all packages that use a dependency, and expands traits that enable other traits. Explicit dependency trait lists replace that dependency declaration's defaults; an empty list enables none. Conditional trait requests activate when any of their required traits is enabled. The resolved traits control compilation conditions, compiler settings, and optional target dependencies, including macro builds.

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.

Attribute	Type	Required	Default	Description
`package_path`	string	no	`.`	Package-relative directory containing `Package.swift`
`resolver_inputs`	list<string>	no	`srcs`	Package-relative source globs available while deriving the graph
`platform`	string	no	`macos`	Apple platform used when lowering package targets
`minimum_os`	string	no	`13.0`	Minimum operating system version for lowered targets
`sdk_variant`	string	no	`simulator`	Simulator or device software development kit selection; ignored for macOS
`swift`	string	no	`swift`	Swift Package Manager executable; the default is paired with the selected Swift compiler
`xcode_developer_dir`	string	no		Specific Xcode developer directory
`package_name`	string	no	generated	Display name read from `Package.swift` while resolving. This value is generated by the resolver and must not be set in a manifest.

Providers and capabilities#

The target emits swift_package_workspace and exposes the build capability. The resolver emits the first-party Apple targets that implement the actual build products.

Direct use#

Inspect the automatically derived graph without writing a manifest:

bash

once query workspace
once query targets

To configure the resolver explicitly, author a seed equivalent to:

toml

[[target]]
name = "swift_package"
kind = "swift_package_workspace"
srcs = ["Package.swift"]

[target.attrs]
resolver_inputs = [
  "Package.swift",
  "Package.resolved",
  "Sources/**/*",
  "Tests/**/*",
  "Plugins/**/*",
  "Macros/**/*",
  "**/Package.swift",
  "**/Package.resolved",
]

Use swift_package_dependencies when an explicit Apple target needs selected static products from a locked package graph rather than native first-party package lowering.

Sources#

Swift Package Manager defines package manifests, products, and target metadata.
dump-package documentation describes the package metadata command used during graph loading.