spm backend

The spm backend installs command-line executables from Swift Package Manager packages hosted on GitHub or GitLab. It uses a prebuilt artifact bundle from the release when one matches your platform, and otherwise builds the package from source with swift build.

Requirements

This backend needs Swift, even for artifact bundles, because mise asks Swift for the target triple. Install Swift manually or with mise. On macOS, the toolchain in Xcode works when Xcode is selected with xcode-select. Source builds also need Git and the package's own build dependencies.

Usage

Install SwiftFormat in the current project, then run it:

mise use spm:nicklockwood/SwiftFormat
mise exec -- swiftformat --version

This writes the following to mise.toml. Add -g for a global tool.

[tools]
"spm:nicklockwood/SwiftFormat" = "latest"

SwiftFormat's releases include swiftformat.artifactbundle.zip. When the bundle has an executable for your Swift target triple, mise installs it; otherwise mise builds the package from source. Check the package's required Swift or Xcode version before a source build.

A package can also ship only an artifact bundle:

mise use spm:giginet/swift-testing-revolutionary@0.4.0
mise exec -- swift-testing-revolutionary --help

Versions are release tags exactly as published, so mise ls-remote spm:owner/repo shows v1.2.0 for a repository that tags v1.2.0. Both @1.2.0 and @v1.2.0 resolve to that tag.

Supported syntax

Form	Example
GitHub shorthand	spm:nicklockwood/SwiftFormat
GitHub shorthand with a release version	spm:nicklockwood/SwiftFormat@0.63.1
GitHub URL	spm:https://github.com/nicklockwood/SwiftFormat.git
GitHub URL with a release version	spm:https://github.com/nicklockwood/SwiftFormat.git@0.63.1
GitLab URL	spm:https://gitlab.com/owner/repo.git
Self-hosted URL	spm:https://git.example.com/owner/repo.git
A specific commit	spm:owner/repo@rev:<commit>
A specific commit, by URL	spm:https://github.com/owner/repo.git@rev:<commit>

A shorthand means GitHub unless the tool sets provider = "gitlab". A gitlab.com URL always uses GitLab. For a self-hosted URL, mise derives the API URL from the host; set provider = "gitlab" when the server runs GitLab.

A commit selector (rev:<commit>, or the equivalent ref:<commit>) always builds from source. Use a full commit SHA for a reproducible installation. Artifact bundles are release assets, so they cannot be combined with a commit selector.

Tool options

install_env

Environment variables for the Swift commands mise runs, such as swift package dump-package, swift -print-target-info and swift build. For an artifact bundle install, they reach only swift -print-target-info; mise downloads, extracts and links the bundle itself. On macOS, select the Xcode developer directory for a system Swift toolchain:

[tools]
"spm:nicklockwood/SwiftFormat" = { version = "latest", install_env = { DEVELOPER_DIR = "/Applications/Xcode.app/Contents/Developer" } }

provider

The forge that hosts the package: github (the default) or gitlab. Set it for a GitLab shorthand or a self-hosted GitLab URL.

[tools]
"spm:patricklorran/ios-settings" = { version = "latest", provider = "gitlab" }

api_url

The provider's API URL. For a self-hosted package, write the full package URL, so that source builds clone from that server. mise derives the API URL from its host, https://<host>/api/v3 for GitHub or https://<host>/api/v4 for GitLab; set api_url when the API lives somewhere else:

[tools]
"spm:https://git.acme.com/acme/my-tool.git" = { version = "latest", provider = "gitlab", api_url = "https://git.acme.com/gitlab/api/v4" }

A package given as owner/repo clones from the host of api_url: mise drops an /api/v3 or /api/v4 suffix, turns a GitHub https://api.<host> into https://<host>, and leaves out any credentials in the URL. Any other api_url, such as a proxy of the public API, still clones from github.com or gitlab.com, so write the full repository URL instead:

[tools]
"spm:acme/SwiftTool" = { version = "1.2.0", api_url = "https://github.acme.com/api/v3" } # clones https://github.acme.com/acme/SwiftTool.git

artifactbundle

Whether to use SwiftPM artifact bundles. When it is unset, mise tries a matching *.artifactbundle.zip release asset first and builds from source if none matches. Set artifactbundle = true to require a bundle: the install fails when no bundle matches the current Swift target triple. Set artifactbundle = false to always build from source; it conflicts with the spm.artifactbundle_only setting.

[tools]
"spm:giginet/swift-testing-revolutionary" = { version = "0.4.0", artifactbundle = true }
"spm:nicklockwood/SwiftFormat" = { version = "latest", artifactbundle = false }

artifactbundle_asset

The artifact bundle to use when a release has several *.artifactbundle.zip assets. Setting it also requires a bundle, as artifactbundle = true does.

[tools]
"spm:giginet/swift-testing-revolutionary" = { version = "0.4.0", artifactbundle_asset = "swift-testing-revolutionary.artifactbundle.zip" }

filter_bins

The executable products to install. When it is unset, mise builds and links every executable product declared in Package.swift, or links every matching executable from an artifact bundle. Use it when a package ships helper executables, such as test harnesses, that you do not want on PATH. For source builds, mise filters before swift build, so it never builds the other products.

The value is an array or a comma-separated string. The install fails when a name does not match an executable product.

[tools]
"spm:swiftlang/swiftly" = { version = "latest", filter_bins = ["swiftly"] }

install_command

A command to run in the checked-out package directory instead of discovering executable products and running swift build --product. It runs with mise's default inline shell and gets install_env, the Swift that mise manages on PATH, and PREFIX and MISE_TOOL_INSTALL_PATH set to the install directory. It applies only to source builds and cannot be combined with filter_bins. mise never runs a package's Makefile or install script unless you configure it here.

Use it for packages that install more than the executable, such as a dynamic library or Swift modules placed by the package's own make install:

[tools]
"spm:owner/repo" = { version = "1.2.3", artifactbundle = false, install_command = "make install PREFIX=\"$MISE_TOOL_INSTALL_PATH\"" }

Some install scripts exit successfully even when swift build failed, so mise checks that the command put at least one executable in bin/ and fails the install otherwise.

Settings

Set these under [settings] in a config file, with mise settings set, or with a setting's environment variable where it has one. See which value wins when a setting is set in more than one place.

spm.artifactbundle_only

Install spm: tools only from prebuilt artifact bundles, and fail instead of building from source.

• Type: boolean
• Default: false
• Environment variable: MISE_SPM_ARTIFACTBUNDLE_ONLY

A tool with the artifactbundle = false option, or a version that selects a Git revision, then fails to install. See artifactbundle.

Troubleshooting

Problem	What to check
No matching artifact bundle	The Swift target triple. Allow a source build only if the package supports your host and its build prerequisites are installed.
An unexpected source build	Set artifactbundle = true so that a missing bundle fails the install.
Several artifact bundles	Set artifactbundle_asset to choose one.
No executable products	That the package publishes a command-line tool, the filter_bins names, or an install_command for a custom installation.
latest resolves to an unrelated tag	Repositories that release several products tag each one, and mise lists tags exactly as published. Pin a version, as in spm:owner/repo@1.2.0.

Implementation: src/backend/spm.rs.