skip to content

In a Package.swift manifest, how do you apply a build tool plugin that another package vends to one of your targets?

level: juniorimportance: should knowfreq 40%

answer

  1. two edits, two arrays
  2. not the dependencies array
  3. plugins: on the target
  4. .plugin(name:package:)

basics

~20 s

Add the package that vends the plugin to the manifest's dependencies, then list the plugin in that target's plugins: array as .plugin(name:package:). SwiftPM then invokes the plugin whenever it builds that target; there is no separate run step.

solid answer

~40 s

A build tool plugin is applied per target, in two edits. First add the package that defines it with `.package(url:from:)`; that package has to vend the plugin as a `.plugin(name:targets:)` product, because a plugin is visible only to its own package and to packages that depend on that package directly. Then add `plugins: [.plugin(name: "GraphQLCodegenPlugin", package: "graphql-codegen")]` to each target that should use it; a plugin defined in the same package is named alone, as `plugins: ["SchemaCodegen"]`. The plugin never goes in the target's `dependencies:`, which lists modules to link. Nothing else is needed: `swift build` invokes the plugin for that target and runs the commands it returns as part of the build. A command plugin is not listed under `plugins:` at all; you run it with `swift package <verb>`.

code

swift · 17 lines
swift
// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "Feature",
    dependencies: [
        .package(url: "https://example.com/graphql-codegen.git", from: "2.0.0"),
    ],
    targets: [
        .target(
            name: "Feature",
            plugins: [
                .plugin(name: "GraphQLCodegenPlugin", package: "graphql-codegen"),
            ]
        ),
    ]
)

go deeper

for a junior

Recall the two edits: the package goes in dependencies, the plugin goes in the target's plugins array as .plugin(name:package:). Then just build.

for a middle

Explain the visibility rules, a plugin product plus a direct dependency, and why plugins: is not dependencies: the plugin runs on the host and is never linked.

for a senior

Show you know each application is a per-target invocation with its own output directory, and diagnose a plugin that cannot be found or never runs.

for a principal

Weigh a shared build tool plugin against per-developer tooling: it pins one generator for every machine and CI job, at the cost of build time per target that applies it.

## What applying a plugin means A **package plugin** is Swift code that extends what Swift Package Manager (SwiftPM) does. A **build tool plugin** is the kind that takes part in a build: SwiftPM hands it a target and it returns the commands, such as running a code generator, that the build then executes. A build tool plugin does nothing until it is **applied** to a target, and applying it is a manifest change, not a command you run. Plugins arrived with Swift 5.6 (build tool plugins in SE-0303, command plugins in SE-0332), so every manifest a team writes today can use them. ## Step 1: depend on the package that vends it The plugin lives in some other package, for example a GraphQL code generator. Add that package to the manifest's `dependencies` exactly as you would a library: ```swift dependencies: [ .package(url: "https://example.com/graphql-codegen.git", from: "2.0.0"), ], ``` Two visibility rules decide whether you can then use its plugin: - The other package must declare a **plugin product**, `.plugin(name:targets:)`, in its `products`. A plugin target without a product is usable only inside the package that defines it. - Your package must depend on that package **directly**. SwiftPM's documentation says a plugin product is available to any package that has a direct dependency on the package that defines it, so a plugin reachable only through a transitive dependency is not available to you. ## Step 2: list the plugin on the target The initializers for targets that hold sources, such as `.target`, `.executableTarget` and `.testTarget`, take a `plugins:` parameter, an array of `Target.PluginUsage` values: - **From another package:** `.plugin(name: "GraphQLCodegenPlugin", package: "graphql-codegen")`. `name:` is the plugin's name, and `package:` names the package that defines it, as `.product(name:package:)` does for a library. - **From the same package:** `.plugin(name: "SchemaCodegen")`, or just the string `"SchemaCodegen"`. Apply the plugin only to the targets that need it. Each application is a separate invocation, so a plugin applied to five targets is invoked five times, once per target, each time with its own work directory. ## What happens on the next build Once the manifest names the plugin, a plain `swift build` (or a build of the package in an IDE that supports SwiftPM packages) does the rest: 1. SwiftPM resolves the package graph, including the plugin's package. 2. It compiles the plugin's Swift sources into an executable for the host machine; the plugin is never linked into your app. 3. It runs the plugin once for each target that lists it, passing a `PluginContext` and the target, and the plugin returns a list of commands. 4. It adds those commands to the build graph, runs them, and compiles any Swift files they generate into that target. The plugin's own process runs in a sandbox on platforms that support one, which blocks network access and writes to arbitrary locations. That is why a build tool plugin writes its output into a work directory SwiftPM gives it rather than into your `Sources` folder. ## Common wiring mistakes | Symptom | Cause | |---|---| | SwiftPM reports it cannot find the plugin | The plugin's package is only a transitive dependency, or it vends no plugin product | | The generator never runs | The plugin was added to `dependencies:` instead of `plugins:` | | The generator runs for the wrong module | It was applied to a different target than the one whose files it reads | | A target tries to `import` the plugin | Plugins are not modules; generated code arrives as source files | ## Where command plugins differ A **command plugin** is never listed on a target. You still depend on its package, then run `swift package plugin --list` to see the verbs it offers and invoke one with `swift package <verb>`, for example `swift package format-source-code`. Build tool plugins run because a target asked for them; command plugins run because a person or a CI script asked for them. The manifest that applies the plugin is short, and that is the point: once the two edits are in, every developer and every CI job that builds the target runs the same generator with no extra script, no tool installed on the machine and no run-script phase to keep in sync.

  • How do you apply a build tool plugin that is defined in the same package?
    Reference it by name alone: `plugins: ["SchemaCodegen"]` or `.plugin(name: "SchemaCodegen")`. The plugin target lives under `Plugins/SchemaCodegen` by default and needs no plugin product, because a product only matters for other packages that want to use it.
  • Why is the plugin not listed in the target's dependencies array?
    `dependencies:` lists modules the target imports and links. A plugin is compiled into a separate executable for the host machine and run during the build; it is never linked into the target. Generated code reaches the target as source files, so `plugins:` is a different relationship from a dependency.

  • Putting the plugin in the target's dependencies array like a library product.
  • Expecting a plugin from a transitive dependency to be usable without depending on its package.
  • Importing the plugin's module in the target's Swift files to make it run.
  • Running a build tool plugin by hand with swift package before every build.