Run Swift packages and Xcode projects with Putnami
@putnami/swift turns each Swift package and each Xcode project of a
repository into a Putnami project, and runs its lint, test and build with the
tools the team already uses: swift for a package, xcodebuild for an Xcode
project. It reads the repository the way putnami observe does. On a machine
with no Swift, or with a Swift outside the release a package states, a package
task installs that release under the Putnami home; it never installs Xcode.
Adopt it
@putnami/swift is not published yet: until its first release, putnami init --extension swift stops at the extension install, after it has written the
workspace files, and a workspace loads the extension from a source checkout.
At the root of the repository, run:
putnami init --extension swiftIt writes
putnami.workspace.jsonwith@putnami/swiftdeclared, installs the extension, and runsputnami projects sync, because the repository holds aPackage.swiftor an Xcode project. A repository of several languages takes a list, such as--extension swift,typescript, andputnami initwithout--extensionproposes the languages it finds. In a workspace that already exists, declare the extension inputnami.workspace.jsonand runputnami projects sync:{ "extensions": ["@putnami/swift"] }Each directory with a
Package.swift, and each directory that holds an.xcodeproj, joins the workspace'sincludes. Noputnami.jsonis needed: the extension names a package by its package name and an Xcode project by its first.xcodeproj, adds an edge to each local package it uses (.package(path:), or the project's local package references), and tags itswift.Run
putnami lint,test,build.
A package's targets are not projects of their own: swift builds and tests a
package as a whole. For the exact target edges of a package, write its export
beside the manifest in CI, as putnami observe advises:
swift package describe --type json > swiftpm.json.
What each task runs
Each task runs in the component's directory, with no shell. {component} is
the package name, or the Xcode project's name; {output} is the task's output
directory. {runtime} is the extension's own executable.
| Task | Package | Xcode project |
|---|---|---|
lint |
{runtime} swift-format-lint Package.swift Sources |
{runtime} swift-format-lint . |
test |
{runtime} swiftpm-test --output {output} |
{runtime} xcodebuild test --scheme {component} --result-bundle {output}/Tests.xcresult --junit {output}/junit.xml --cobertura {output}/coverage.xml |
build |
swift build --force-resolved-versions |
{runtime} xcodebuild build --scheme {component} |
Every step resolves packages with the versions the committed
Package.resolved pins (--force-resolved-versions,
-disableAutomaticPackageResolution), so a run never rewrites one of its own
inputs. A component with remote packages commits its Package.resolved: the
package's own, or <name>.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved.
The runtime commands:
swift-format-lintrunsswift format lint --strict(Swift 6 and later) on the paths that exist, with the.swift-formatof the component, else of the workspace root: the two files the task's key reads. Without one, it lints nothing and says so: swift-format's default style is no team's style.swiftpm-testrunsswift test --force-resolved-versions --enable-code-coverage --parallel --xunit-output {output}/xunit.xml, with the arguments after--, then exports the coverage to LCOV:llvm-cov exportof the package's test products withdefault.profdata, kept to the files under the package outside.buildandTests. The products are<Package>PackageTests.xctest, or with the Swift Build layout of Swift 6.4 each<Target>.xcteston macOS and each<Target>.soon Linux. It runsllvm-covfromPATH, else throughxcrun. Aswift testthat exits non-zero with a failed case lets the task read the failed cases; one with no failed case, a compile error for instance, fails the step. SwiftPM writes no coverage profile after a failed run, so such a run has no LCOV, and the task names the failed cases and the missing report.xcodebuildrunsxcodebuild testorbuildon the scheme, withCODE_SIGNING_ALLOWED=NO. Without--destination, it reads the scheme'sPLATFORM_NAME: a Mac scheme runs onplatform=macOS; an iOS, tvOS, watchOS or visionOS scheme builds for the generic simulator and tests on the first available simulator of the newest runtime. A test writes its result bundle with code coverage, then, with--junitor--cobertura, converts it asxcresultdoes; a failed test leaves the verdict to the failed cases.xcresultconverts the result bundle: a JUnit report fromxcrun xcresulttool get test-results tests(Xcode 16 and later), one suite perBundle.Suite, and a Cobertura report fromxcrun xccovof the app targets' files under the project's directory. Whenxcodebuild testfailed and no case did, it fails.
Coverage stays with its component: a local package the tests link reports its own coverage, in its own task.
The test task reads the JUnit and coverage reports into its test and coverage summary. A failed case, a step that fails, or a report that is missing fails the task.
Test filter and documentation links
putnami test --test <filter>, short -t, adds --filter <filter> to the
task's last step when that step is the swiftpm-test or xcodebuild command;
an override whose last step runs another program gets no filter. The
swiftpm-test command hands it to swift test --filter, a regular expression
over Module.Class/method; the xcodebuild command hands it to
xcodebuild -only-testing:<filter>, as Target/Class/method. The filter also
reaches the components the selected ones depend on: a package in which it
selects no test passes with empty reports. An Xcode project whose scheme has
no target the filter names fails, since xcodebuild refuses the selection.
putnami lint also checks every relative link and anchor of the component's
README.md files and doc/ trees, and a broken one fails it.
--docs-links=false turns the check off.
Install and upgrade dependencies
putnami install runs the workspace-install job of this extension over the
workspace's components, except the projects disable.tags excludes. A change
to Package.resolved at the workspace root makes the next putnami command
run it again:
| Component | What it runs |
|---|---|
| Package | swift package resolve --force-resolved-versions, except when its last successful resolve used its current Package.swift, Package@swift-*.swift and Package.resolved; --force resolves it as well |
| Xcode project | xcodebuild -resolvePackageDependencies -onlyUsePackageVersionsFromResolvedFile |
With no Swift on the machine, a package installs its Swift as a task does,
and an Xcode project without Xcode warns and passes. With offline dependencies,
as in a hosted run, it resolves nothing ahead of time: swift build and
xcodebuild then resolve the pinned versions themselves, over the network the
runner allows.
There is no workspace-fetch: resolving a package runs its Package.swift,
and the packages it depends on, with no sandbox on Linux, so the extension
fetches nothing ahead of a hosted run.
putnami upgrade runs swift package update in each package, which rewrites
its Package.resolved. An Xcode project keeps its pins and is left out, so a
machine with no Xcode still upgrades its packages: update an Xcode project's
packages in Xcode. With offline dependencies, the upgrade fails.
Run an application
A package is an application when its Package.swift declares an executable
product (.executable(name:)) or an executable target
(.executableTarget(name:)); any other package is a library, and serve and
run skip it. An Xcode project is neither served nor run.
| Command | What it runs |
|---|---|
putnami serve <project> |
swift run --force-resolved-versions <executable>, with -- <arguments> from --args, in the package, with PORT set: --port defaults to 3000, and 0 selects a free port. The executable reads PORT to listen. The command reports the server ready once the port accepts a connection, so putnami qualify and compose can wait on it. There is no watcher. |
putnami run <project> --args "<arguments>" |
swift run --force-resolved-versions <executable> -- <arguments>, and exits with its exit code. |
Both resolve with the versions Package.resolved pins. The executable is the
package's only executable product, or, with none, its only executable target;
with several, the one named after the project, else the one --entrypoint
names.
Package and publish an image
An application reaches a registry as an OCI image, a standard container image.
Declare the channel in the project's putnami.json:
{ "options": { "package": { "docker": true }, "publish": { "docker": true } } }putnami package assembles the image with no Docker daemon. --docker-load
also loads it into the local Docker daemon. The image name is the project name
in lowercase. putnami publish pushes it to the
registry that registries.oci.publish of putnami.workspace.json declares,
through the shared publisher of the other stacks. --docker-registry <registry> overrides that registry for one push. A library or an Xcode
project packages and publishes nothing.
The image holds a static binary, built with the Static Linux SDK of the selected Swift, so the same command packages from macOS and from Linux (ADR 0001):
swift --versionnames the swift.org release, such as6.4.2. The extension pins the checksum of the SDK of each release from 6.4.0 to 6.4.2; another release fails withswift.static_sdk_unavailableand names the pinned ones. Before 6.4, SwiftPM selects an SDK of the bundle whatever--triplenames, so no earlier release is pinned. The Swift of Xcode cannot build with the SDK: on macOS, state a swift.org release in.swift-version, which a task installs whenPATHhas none, or select one with swiftly or the swift.org installer.- When
swift sdk listdoes not name the SDK,swift sdk install <url> --checksum <pin>installs it, once per machine: one install of a bundle runs at a time. swift build -c release --swift-sdk <bundle> --triple <arch>-swift-linux-musl --force-resolved-versions --product <executable> -Xlinker -sbuilds the executable, stripped, with the pinned SDK and the versionsPackage.resolvedpins, holding the lock of the package as the other tasks do. The executable is the oneservestarts;--entrypointnames it among several.--platformselectslinux/amd64, the default, orlinux/arm64.
| Layer | Content |
|---|---|
| Resources | The .resources and .bundle directories SwiftPM writes beside the executable, under /app, where Bundle.module finds them. The job removes those of earlier builds first, so the image holds the bundles of its product only. Only a package with resources has this layer. |
| Executable | /app/<executable>, the image's entrypoint |
The image runs as the user 65532, the nonroot user of distroless, in
/app, with PORT set and exposed from --port, 8080 by default: the executable reads PORT to
listen, as it does under serve. The base is gcr.io/distroless/static:nonroot
pinned by digest, which holds CA certificates and time zones and no shell. A
project names another base with --docker-base-image image@sha256:<digest>; a
base with no digest fails with swift.base_not_pinned.
A Vapor application that serves files from Public/ or renders templates from
Resources/ reads them from its working directory, which the image does not
hold: declare them as target resources so that they reach Bundle.module.
The toolchain check
Before its first step, each task compares the version on the machine with the version the component states:
| Component | Machine version | Expected version |
|---|---|---|
| Package | swift --version (Apple Swift version 6.0.2) |
.swift-version in the package |
| Xcode project | xcodebuild -version (Xcode 16.1) |
.xcode-version in the project's directory |
A version with fewer components names the releases it prefixes: 6.0 matches
6.0.2. A mismatch fails the task with stacks.toolchain_mismatch; set
toolchain.check to warn to run anyway. A component that states no version
gets stacks.toolchain_unpinned, a warning, and its cache key carries no
toolchain version.
Swift installed at task time
A package task whose swift is missing, or outside the release its
.swift-version states, installs that release, or 6.4.2 when the package
states none, and runs it. A swift on PATH that satisfies the statement
always runs, and nothing is installed.
- The install runs swiftly 1.2.0,
which the extension downloads and checks against the SHA-256 it pins for
Linux (x86_64, aarch64) and macOS. It runs with a home, a toolchains
directory and a gpg keyring of its own under
<Putnami home>/tools/swift, so the machine's swiftly, toolchains and keyring stay untouched. On Linux, swiftly checks the toolchain's signature withgpg, and needs the system's CA certificates (ca-certificates), which the machine provides; it installs on the distributions swift.org publishes for: Ubuntu, Debian, Fedora, Amazon Linux and Red Hat UBI. On another one, the task fails with swiftly's reason. On macOS, the installed toolchain builds with the SDK of the Xcode Command Line Tools, which the machine provides. .swift-versionnames a release:6,6.4or6.4.2, as swiftly takes it;6.4installs the newest 6.4 patch. Any other statement, such as a snapshot, is refused: put a matchingswiftonPATH.- Each release installs once per machine: a later task, in any workspace, runs the release an earlier one installed.
- On Linux, a toolchain needs system packages, such as
libcurlandlibxml2headers. Installing them takes root, so the task says which ones swiftly names and does not install them. - The test task of a package appends the directory of its toolchain's
llvm-covto itsPATHwhen thatPATHholds none, soswiftpm-testexports the LCOV with thellvm-covof theswiftthat ran the tests. - With offline dependencies, as in a hosted run, nothing is installed: a
missing
swiftfails the task withstacks.toolchain_missing, and a mismatch withstacks.toolchain_mismatch. - An Xcode project keeps its toolchain check only: the extension installs no Xcode.
What reaches the cache key
Each task reads the files of its selector, swift:lint, swift:test or
swift:build, and its component's toolchain file:
| Input set | Package | Xcode project |
|---|---|---|
sources |
Sources/**, Plugins/** |
**: every file of the project's directory |
swiftSources |
**/*.swift |
|
tests |
Tests/** |
(in sources) |
manifests |
Package.swift, Package@swift-*.swift |
*.xcodeproj/project.pbxproj, *.xcodeproj/xcshareddata/** |
lintConfig |
.swift-format, in the component and at the workspace root |
the same |
lockfiles |
Package.resolved |
*.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved |
A ** walk never enters .build, DerivedData, SourcePackages, Pods,
Carthage, xcuserdata or node_modules.
A package's lint reads sources, manifests and lintConfig; its test
reads sources, tests, manifests and lockfiles. So a change to a
package's tests reruns its test, not its lint, and a Package.resolved
change does not rerun lint. An Xcode project's lint reads its Swift files
and lintConfig, and lints them all, tests included: a change to a Swift
test file reruns it, a change to any other file does not. Its test and
build read sources, manifests and lockfiles, so an override of
sources keeps the project file and its pins in the key. A lint of . leaves
out the hidden entries and the excluded directories.
The key also carries the component's name, its variant and its expected toolchain version, and the keys of the same task of the local packages it uses.
Override the profile
A component overrides any value of its profile in its own putnami.json,
under options["@putnami/swift"]. An object merges; any other value, a step
list or an input list, replaces the profile's whole. An Xcode project's
override applies after its xcode variant.
The overrides a team uses most:
{
"options": {
"@putnami/swift": {
"tasks": {
"test": {
"steps": [
["{runtime}", "xcodebuild", "test", "--scheme", "ShopCI", "--destination", "platform=iOS Simulator,name=iPhone 16",
"--result-bundle", "{output}/Tests.xcresult", "--junit", "{output}/junit.xml", "--cobertura", "{output}/coverage.xml"]
]
}
}
}
}
}- Another scheme or destination: the
xcodebuildsteps above, with--schemeand--destination. A directory with several projects adds--project Shop.xcodeproj. - A package without a test target:
"test": {"steps": [["swift", "build", "--force-resolved-versions"]], "reports": null}. - Flags for swift test:
["{runtime}", "swiftpm-test", "--output", "{output}", "--", "-c", "release"]. - A lint tool of the team's own:
"lint": {"steps": [["swiftlint", "lint", "--strict"]]}, with"lintConfig": ["{root}/.swift-format", ".swiftlint.yml"]ininputs. - An accepted toolchain difference:
"toolchain": {"check": "warn"}. - More inputs:
"inputs": {"sources": ["Sources/**", "Resources/**"]}.
An override that names an unknown member, changes id, markers or
variants, or adds a stack-root input fails the task with
stacks.project_config_invalid.
Limits
- An app built through an
.xcworkspace, with CocoaPods for instance, needs an override of its steps: the extension builds the.xcodeprojand its local packages. - A directory with both a
Package.swiftand an.xcodeprojis the package; the probe reportsstacks.component_conflict. - The scheme defaults to the project's name. A project whose scheme has another name overrides it.
- A toolchain file is read in the component's directory only. A
.swift-versionor.xcode-versionat the workspace root is in every task's key but is not read. - A
.swift-formatbetween the component and the workspace root is not read. - A package without a name the manifest spells as a literal, at the workspace root, is named after the checkout's directory.
- Two Xcode projects whose tests run at the same time may share a simulator.
- The result bundle is a task output, so it is cached with the reports.
- The extension does not install Xcode, a simulator or the system packages a Linux Swift needs, and does not archive or sign an app.
- An image holds a static binary only: a package that links a system library musl does not offer, or that needs the Foundation of a native Linux build, cannot be packaged: it builds its own image.
- An arm64 image is assembled as an amd64 one is; no test runs one.