skip to content

In an Xcode project, when do you run SwiftLint as SwiftLintBuildToolPlugin rather than a Run Script phase, and what breaks with each?

level: seniorimportance: should knowfreq 48%

answer

  1. per-target plugin versus one script
  2. the plugin takes no arguments
  3. topmost .swiftlint.yml sets the working directory
  4. Xcode 15 sandboxes user scripts
  5. deny(1) file-read-data

basics

~20 s

Use SwiftLintBuildToolPlugin when each target can be linted with one .swiftlint.yml inside the project and a pinned package version; use a Run Script phase when you need --config, --fix or one run over all targets, and then turn off user script sandboxing for it.

solid answer

~40 s

The plugin, added per target under Run Build Tool Plug-ins, always runs `swiftlint lint --quiet --force-exclude` on that target's Swift files with its own cache, and you cannot pass it arguments: no `--config`, no `--fix`, no command-line `--strict`, so settings such as `strict` and `baseline` go in `.swiftlint.yml`. It uses the folder of the topmost `.swiftlint.yml` inside the project as the working directory and fails if the target's files sit outside the project. A Run Script phase after Compile Sources can pass any flags, lint every target in one invocation and run `swiftlint --fix && swiftlint`, but since Xcode 15 defaults `ENABLE_USER_SCRIPT_SANDBOXING` to YES it fails with `Sandbox: swiftlint(...) deny(1) file-read-data` until that target sets it to NO, and it depends on a `swiftlint` binary being on the machine's PATH.

code

bash · 12 lines
bash
# Run Script phase, placed after Compile Sources
if [[ "$(uname -m)" == arm64 ]]
then
    export PATH="/opt/homebrew/bin:$PATH"
fi

if command -v swiftlint >/dev/null 2>&1
then
    swiftlint --fix && swiftlint --strict --baseline Baseline.json
else
    echo "warning: swiftlint command not found"
fi

go deeper

for a junior

Recall the two setups: SwiftLintBuildToolPlugin added per target, or a Run Script phase that calls swiftlint after Compile Sources.

for a middle

Explain that the plugin takes no arguments and picks the topmost .swiftlint.yml in the project, while a Run Script phase accepts any flags.

for a senior

Diagnose the sandbox deny(1) file-read-data failure, a missing binary on Apple silicon, and plugin layout errors, and choose the setup that fits the project.

for a principal

Weigh a pinned plugin and no --fix against a flexible script that needs sandboxing off and a managed binary on every machine.

## Two ways to run SwiftLint inside an Xcode build SwiftLint can be wired into an Xcode project as a **build tool plugin** or as a **Run Script build phase**. Both make violations appear as Xcode warnings and errors; they differ in what you control and in what breaks. (How SwiftPM plugins are built, scheduled and sandboxed is covered with Swift Package Manager plugins, and build phases in general with Xcode; this is SwiftLint's side.) ## SwiftLintBuildToolPlugin You add the SwiftLintPlugins package, then add `SwiftLintBuildToolPlugin` to the **Run Build Tool Plug-ins** phase of each target to lint. What the plugin does is fixed in its source: - it runs `swiftlint lint --quiet --force-exclude` followed by every Swift source file of that target; - `--force-exclude` matters because the files are passed explicitly, and without it the `excluded` list in `.swiftlint.yml` would not apply to explicit paths; - it keeps a cache under the plugin's work directory, or passes `--no-cache` when `CI_XCODE_CLOUD` is `TRUE`; - it sets SwiftLint's working directory to the folder holding the **topmost `.swiftlint.yml` inside the project directory**, falling back to the project directory. Consequences: 1. **No arguments.** A build tool plugin cannot take your flags, so there is no `--config`, `--fix`, `--strict` or `--baseline` on its command line. Put `strict: true`, `baseline:` and the rule selection in `.swiftlint.yml` instead. 2. **Layout limits.** If a target's Swift files are outside the project directory, the plugin throws "Swift files are not in project directory". A shared configuration stored elsewhere is reached with a local `.swiftlint.yml` that says `parent_config: path/to/.swiftlint.yml`. 3. **Trust prompts.** Xcode asks you to trust and enable the plugin. Unattended CI builds pass `-skipPackagePluginValidation` (and `-skipMacroValidation`) to `xcodebuild`, which implicitly trusts every plugin and macro, a real security trade-off. 4. **Per target.** Each target needs the plugin added separately, and each runs its own lint. 5. **Cache.** Because the plugin passes `--cache-path`, a file whose modification date and configuration have not changed reuses its cached violations instead of being re-linted; on Xcode Cloud, with `--no-cache`, every build lints from scratch. The version is pinned by the package dependency, so every developer and CI runner lints with the same SwiftLint. ## A Run Script phase The README's script, added to a **Run Script** phase of the main app target **after Compile Sources** (SwiftLint expects code that compiles, especially with `--fix`), is: ```bash if command -v swiftlint >/dev/null 2>&1 then swiftlint else echo "warning: swiftlint command not found" fi ``` What you gain: - any flags: `--config` with a parent-child list, `--strict`, `--baseline`, a reporter; - **one invocation over all targets**, with paths chosen by `included` and `excluded`; - fixing in the build: `swiftlint --fix && swiftlint` corrects what it can, then reports the rest. What breaks: - **User script sandboxing.** Xcode 15 changed the default of `ENABLE_USER_SCRIPT_SANDBOXING` from NO to YES. SwiftLint then cannot read the sources and fails with `error: Sandbox: swiftlint(19427) deny(1) file-read-data.` The README's fix is to set that setting to NO for the target running SwiftLint. - **Finding the binary.** On Apple silicon a package manager may install `swiftlint` in `/opt/homebrew/bin`, which the build phase's `PATH` may not include, so the script prints a not-installed warning; export that directory on `PATH` in the script or symlink the binary into `/usr/local/bin`. - **Version drift.** The script lints with whatever `swiftlint` each machine has, and the README's fallback only prints a warning when it is missing, so a laptop without SwiftLint silently skips the lint. - **Every build.** Unchecking "Based on dependency analysis" runs it on all incremental builds and silences Xcode's warning about a script with no declared outputs. ## Choosing | Need | Plugin | Run Script | |---|---|---| | Same SwiftLint version everywhere | pinned by the package | depends on each machine | | `--config`, `--fix`, flags | not possible | yes | | Config outside the project folder | via `parent_config` | via `--config` | | One lint across all targets | per target | one invocation | | `ENABLE_USER_SCRIPT_SANDBOXING` | not affected | must be NO for that target | For Swift packages there is also `SwiftLintCommandPlugin`, run as `swift package plugin swiftlint`; it declares permission to write to the package directory so that `--fix` can rewrite sources.

  • With the plugin, an excluded Generated folder is still being linted. What would you check?
    The plugin passes `--force-exclude`, so `excluded` does apply to the files it hands over, but each entry resolves relative to the `.swiftlint.yml` that declares it, and the plugin starts from the topmost one in the project. An entry written relative to some other folder, or a misspelled case-sensitive path, will not match. Fix the path relative to that file.
  • Why does the README place the Run Script phase after Compile Sources rather than before?
    SwiftLint is designed to analyse valid, compilable Swift. Run before compilation, a broken file can produce confusing violations, and `--fix` can rewrite it badly. After Compile Sources, a compile error stops the build first and SwiftLint only sees code that type-checks.

  • The build tool plugin can run --fix on every build.
  • You pass --config to the plugin in the target's build settings.
  • A Run Script phase works unchanged under Xcode 15's script sandboxing.
  • The plugin lints all targets once you add it to one.
  • A Run Script phase pins the SwiftLint version for the whole team.
  • Passing --no-cache fixes the sandbox file-read-data error.