# `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](/guide/graph/apple#explicit-modules-and-dependency-checks)
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:

```sh
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`](/reference/prelude/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](https://www.swift.org/documentation/package-manager/)
  defines package manifests, products, and target metadata.
- [`dump-package` documentation](https://github.com/swiftlang/swift-package-manager/blob/main/Documentation/Usage.md)
  describes the package metadata command used during graph loading.