skip to content

Manifest and Targets

Package.swift declares products, targets and dependencies in Swift code, versioned by swift-tools-version. Interviewers ask how targets map to modules and what a product exposes.

on this pageshow

explore

questions

6

In a Swift package, what does the `// swift-tools-version:` line in Package.swift control, and what goes wrong when it is set too low or too high?

level: juniorimportance: must knowfreq 58%

answer

  1. a comment SwiftPM parses first
  2. floor for the toolchain
  3. picks the PackageDescription API
  4. language mode default moves at 6.0

basics

~20 s

The swift-tools-version comment in Package.swift names the oldest Swift toolchain that can build the package and picks the PackageDescription API the manifest compiles against: too low hides newer manifest APIs, too high locks out older toolchains.

solid answer

~40 s

The comment at the top of `Package.swift`, for example `// swift-tools-version: 6.1`, is read before the manifest is compiled. It is the minimum toolchain that may build the package, and it selects the PackageDescription version, so an API marked `@available(_PackageDescription, introduced: 6.2)` such as `.defaultIsolation(MainActor.self)` fails under 6.1 with `'defaultIsolation' is unavailable`, whatever toolchain is installed. It also moves defaults: from tools version 6.0, targets compile in the Swift 6 language mode unless the manifest overrides it. A toolchain older than the declared version stops with `is using Swift tools version 6.5.0 but the installed version is 6.4.0`, and during resolution SwiftPM skips dependency versions whose tools version is newer than the toolchain. Change it deliberately with `swift package tools-version --set`.

code

plaintext · 6 lines
plaintext
$ swift build        # Package.swift declares: // swift-tools-version: 6.5
error: 'clientkit': package 'clientkit' is using Swift tools version 6.5.0 but the installed version is 6.4.0

$ swift build        # Package.swift declares 6.1 and uses .defaultIsolation(MainActor.self)
Package.swift:9:30: error: 'defaultIsolation' is unavailable
PackageDescription.SwiftSetting.defaultIsolation:3:22: note: 'defaultIsolation' was introduced in PackageDescription 6.2

go deeper

for a junior

Recall that the comment at the top of Package.swift is parsed, sets the oldest toolchain that can build the package, and decides which manifest APIs compile.

for a middle

Explain the @available(_PackageDescription, introduced:) gate with one example, and the 6.0 shift to Swift 6 mode as the default for targets.

for a senior

Show how you raise the tools version safely: separate commit, per-target language-mode overrides, and awareness that clients on older toolchains resolve older releases.

for a principal

Frame the tools version as a contract with consumers: which Xcode releases the package supports, and when version-specific manifests are worth their upkeep.

## What the line is Every `Package.swift` starts with a comment such as `// swift-tools-version: 6.1`. It looks like a comment, but SwiftPM reads it **before** it compiles the manifest, and it decides how the rest of the file is understood. The value is a semantic version whose patch component defaults to `0`, so `6.1` means `6.1.0`. The documentation places it on the first line; since Swift 6.0, SwiftPM also accepts it after leading comment lines, which matters when a licence header has to come first. The line does three jobs at once: - **It sets a floor for the toolchain.** It declares the oldest Swift toolchain, and so the oldest SwiftPM, that may build the package. - **It selects the manifest API.** The manifest is compiled against the PackageDescription version the line names, so APIs added in later versions are unavailable. - **It moves some defaults.** The most visible one is the Swift language mode that targets compile in. ## The floor: older toolchains stop A toolchain older than the declared version refuses the package outright. Swift 6.4 reading a manifest that declares 6.5 prints `package 'clientkit' is using Swift tools version 6.5.0 but the installed version is 6.4.0`. A manifest with no line at all is treated as tools version 3.1, which current toolchains no longer support, and the error suggests the current tools version instead. The same rule applies to dependencies. During resolution, a version of a dependency whose tools version is newer than the toolchain in use is ineligible, and SwiftPM moves on to the next-best version; if no version qualifies, resolution fails. How version requirements are chosen and pinned is a separate lesson, but this is why a library that raises its tools version can stop reaching clients who build with an older Xcode. ## The API gate: what the manifest may say Each PackageDescription declaration carries an `@available(_PackageDescription, introduced: X)` line, and the tools version is compared against it: | Manifest API | Tools version that added it | |---|---| | `resources:` on targets, `.process` and `.copy` | 5.3 | | `.plugin` targets and plugin products | 5.5 | | `.macro` targets (`CompilerPluginSupport`), the `package` access level | 5.9 | | `swiftLanguageModes`, per-target `.swiftLanguageMode(_:)` | 6.0 | | `traits:` and `.when(traits:)` conditions | 6.1 | | `.defaultIsolation(_:)`, `.strictMemorySafety()`, `.treatAllWarnings(as:)` | 6.2 | | `.iOS(.v27)` | 6.4 | Use a newer API under an older line and the manifest fails to compile: with `// swift-tools-version: 6.1`, `.defaultIsolation(MainActor.self)` produces `'defaultIsolation' is unavailable`, with a note that it was introduced in PackageDescription 6.2. Having the 6.4 toolchain installed does not help, because the line, not the toolchain, picks the API. The gate also works in the other direction: obsoleted spellings stop compiling and deprecated ones warn. `swiftLanguageVersions` is deprecated from tools version 6.0 in favour of `swiftLanguageModes`, and tools version 6.4 deprecates `.iOS(.v13)` and `.iOS(.v14)` with the message that iOS 15.0 is the oldest supported version. ## Defaults that move with it Raising the line is not only about new API. From tools version 6.0, targets compile in the **Swift 6 language mode** unless the manifest says otherwise. A target with a global `public var sharedCount = 0` that built cleanly at 5.10 fails at 6.0 with `var 'sharedCount' is not concurrency-safe because it is nonisolated global shared mutable state`. The manifest itself is compiled in the Swift 6 mode at that tools version too. The tools version and the language mode remain separate settings. A target can be held in the Swift 5 mode with `.swiftLanguageMode(.v5)`, or the whole package with `swiftLanguageModes`, without lowering the tools version, which is how teams adopt new manifest API before every module is migrated. ## Changing it on purpose 1. Pick the lowest tools version that has every manifest API you use, and check it against the Xcode releases your clients build with. 2. Change it with `swift package tools-version --set 6.1`, or `--set-current` for the toolchain in use, and build straight away. 3. Bump it in its own commit, and fix the language-mode fallout in the same review rather than in a dependent app. 4. If the package must still serve older toolchains, keep `Package.swift` at the newest tools version and add a version-specific manifest such as `[email protected]` for the older one, which is the arrangement the SwiftPM documentation recommends.

  • Does raising the tools version change the Swift language mode the package's targets compile in?
    Yes, from tools version 6.0 targets default to the Swift 6 language mode, so a module with unprotected global state can stop compiling after the bump. The two settings stay separate: `.swiftLanguageMode(.v5)` on one target, or `swiftLanguageModes` for the package, keeps code in Swift 5 mode while the manifest uses 6.x API.
  • What does SwiftPM do when a dependency's newest release declares a tools version newer than the toolchain?
    That release is ineligible, and resolution moves on to the next-best version that still meets the requirement. Only when no eligible version remains does SwiftPM report a resolution error. Clients on older toolchains therefore stay on older releases of the library rather than failing at once.
  • Can a licence header come before the tools-version comment?
    Since Swift 6.0, yes: SwiftPM accepts the `// swift-tools-version:` comment on a line after leading comment lines. Older toolchains expect it on the first line, so a package that still supports them keeps it there.

  • The swift-tools-version line is only a comment, so SwiftPM ignores it.
  • A newer manifest API works under an older tools version as long as the installed toolchain is new.
  • The tools version and the Swift language mode are the same setting.
  • Without the line, SwiftPM assumes the version of the toolchain that is running.
  • Raising the tools version is free because a newer toolchain builds every target exactly as before.

Assumes SwiftPM 6.4 (Swift 6.4, Xcode 27.0); the tools version named for each manifest API is read from PackageDescription's @available lines.

open as a page

In a Swift package manifest, how do targets map to modules, and what does a library product expose to the packages that depend on it?

level: middleimportance: must knowfreq 62%

basics

~20 s

Each SwiftPM target builds one module, by default from Sources/<TargetName>. A library product is the outward-facing unit: it vends the public API of the targets it lists, and other packages depend on products, never on bare targets.

open as a page

In a Package.swift manifest, when do you declare a target's resources with `.process` versus `.copy`, and what goes wrong with each?

level: middleimportance: should knowfreq 40%

basics

~20 s

Declare .process for files SwiftPM may optimise, which land flattened at the resource bundle's top level, and .copy for a file or folder that must stay untouched with its directory structure, such as nested JSON fixtures.

open as a page

In a Package.swift manifest, how do you wire a Swift macro so app code can use it, and why must app targets import a library target rather than the `.macro` target?

level: seniorimportance: should knowfreq 28%

basics

~20 s

Import CompilerPluginSupport, declare a .macro target depending on swift-syntax's SwiftSyntaxMacros and SwiftCompilerPlugin, plus a regular target that depends on it and declares the macros. Clients import that library target; the macro target is a compiler plugin.

open as a page

In a Package.swift manifest, how do `swiftSettings` set one target's language mode, default isolation and conditional flags, and why is `unsafeFlags` a problem in a published library?

level: seniorimportance: should knowfreq 38%

basics

~20 s

swiftSettings apply per target: .swiftLanguageMode(.v5) (tools 6.0) keeps one target in Swift 5 mode, .defaultIsolation(MainActor.self) (6.2) makes unannotated code main-actor isolated, and .define adds conditions. unsafeFlags makes products containing the target ineligible for use by other packages.

open as a page

In a Package.swift manifest with tools version 6.1, how do package traits make a dependency optional, and how does a client choose which traits it gets?

level: seniorimportance: nice to knowfreq 18%

basics

~20 s

A package declares traits in Package(traits:), sets defaults with .default(enabledTraits:), links an optional product under condition: .when(traits:) and guards code with #if. A client lists traits on its .package dependency; any list replaces the defaults unless it includes .defaults.

open as a page