skip to content

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%

answer

  1. files that are not source
  2. optimise versus untouched
  3. flattened to the bundle's top level
  4. duplicate names across subfolders

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.

solid answer

~40 s

From tools version 5.3 a target can bundle resources. Asset catalogs, storyboards, XIBs and Core Data models are handled automatically on Apple platforms; anything else, such as JSON fixtures, must be declared with a rule or `exclude`d, or SwiftPM warns that it found unhandled files and leaves them out. `.process` applies the platform's processing, recurses into folders, and files with no special processing land at the bundle's top level, so `users/list.json` and `orders/list.json` fail with `multiple resources named 'list.json'`. `.copy` keeps a file untouched and a folder's structure intact, so code can ask `Bundle.module` for `subdirectory: "Fixtures/users"`. The documentation prefers `.process` when possible; `.embedInCode` (5.9) compiles small files into a generated `PackageResources` struct.

code

swift · 18 lines
swift
// swift-tools-version: 6.1
import PackageDescription

let package = Package(
    name: "ClientKit",
    targets: [
        .target(
            name: "Networking",
            exclude: ["README.md"],
            resources: [.process("Resources/endpoints.plist")]
        ),
        .testTarget(
            name: "NetworkingTests",
            dependencies: ["Networking"],
            resources: [.copy("Fixtures")]   // keeps users/ and orders/
        ),
    ]
)

go deeper

for a junior

Recall that non-code files in a target need a rule in resources:, and that code reads them through Bundle.module.

for a middle

Explain the difference between processing and copying, including flattening and the duplicate-name error, and when exclude: is the right tool.

for a senior

Diagnose missing or nil resources from the build warning and the bundle layout, and choose .copy for fixtures whose paths tests depend on.

for a principal

Set the team convention for where fixtures and assets live in packages so that resource layout stays predictable across modules.

## Which files count as resources From tools version 5.3, a target can carry **resources**: files that are not source code but ship with the module, such as JSON fixtures, images or property lists. SwiftPM scopes resources to the target whose folder contains them; the documented convention is a `Resources` subfolder such as `Sources/Networking/Resources`. Some types are recognised automatically on Apple platforms: asset catalogs, storyboards, XIBs and Core Data model files need no declaration. Every other file in a target's folder has to be declared with a rule or excluded, otherwise SwiftPM warns and does not bundle it: ``` warning: 'clientkit': found 1 file(s) which are unhandled; explicitly declare them as resources or exclude from the target ``` ## The rules | Rule | What SwiftPM does | Given a folder | Reach for it when | |---|---|---|---| | `.process(_:localization:)` | applies the platform's processing for the file type; a file with none is copied as is to the bundle's top level | recurses, so the files lose their subfolders | images, property lists, localised files; the documented default | | `.copy(_:)` | copies the file untouched to the bundle's top level | keeps the folder and its structure | fixtures and folders whose layout code relies on | | `.embedInCode(_:)` (5.9) | compiles the bytes into a generated `PackageResources` struct as a `[UInt8]` property | not a bundle at all | small files read without a bundle lookup | The documentation says to use `.process` if possible, because it lets the build optimise files for the platform, and reserves `.copy` for resources that must remain untouched or keep a directory structure. `.process` also takes a `localization:` argument, `.default` or `.base`, for localised resources, which pairs with the package-level `defaultLocalization`. ## What goes wrong with each - **`.process` on a folder flattens it.** With `Fixtures/users/list.json` and `Fixtures/orders/list.json`, `.process("Fixtures")` fails the build with `multiple resources named 'list.json' in target 'NetworkingTests'`. - **Lookups by subfolder miss after processing.** Code that asks for `subdirectory: "Fixtures/users"` finds nothing, because processed files without special handling sit at the top level. - **`.copy` skips the platform's processing.** A copied file is never optimised for the platform, which is why the documentation does not make it the default. - **Undeclared files are missing at run time.** Apart from the build warning, a lookup for them returns `nil`, and if the target has no resources at all, `Bundle.module` is not generated. - **`exclude:` wins.** A path in the target's `exclude` list is neither source nor resource, which is how a `README.md` or a script in a target folder stays out of the bundle and out of the warning. ## Reading them back For each target with resources, SwiftPM builds a resource bundle and generates an internal static `Bundle.module` accessor in that module; the documentation says to always use it rather than assume a location. With `.copy("Fixtures")`, a test reads `Bundle.module.url(forResource: "list", withExtension: "json", subdirectory: "Fixtures/users")`. How an app consumes package resources through `Bundle.module` is covered with app integration. SwiftPM 6.4 made Swift Build the default build system, and its release notes say that when targeting Apple platforms it applies the same resource rules as `xcodebuild` for types such as asset catalogs, storyboards and Metal sources, so a package's resources behave the same from the command line and from Xcode. ## Choosing per file, not per folder The rules apply to whatever path they name, so a target can mix them. A common shape for a networking module is `.process("Resources/endpoints.plist")` for a configuration file that benefits from the platform's handling and `.copy("Fixtures")` on the test target for fixtures whose layout tests depend on. Declaring a folder with `.process` is convenient while every file name in it is unique; the moment two files share a name in different subfolders, the build fails, and the right fix is usually `.copy` for that folder rather than renaming fixtures to dodge the collision. ## A fixtures checklist 1. Put test fixtures under the test target's folder, for example `Tests/NetworkingTests/Fixtures`, and declare them on the `.testTarget`. 2. Use `.copy("Fixtures")` when file names repeat across subfolders or when code builds paths from the folder layout. 3. Use `.process` for individual assets that benefit from platform processing and have unique names. 4. Keep notes and scripts out with `exclude:` instead of living with the unhandled-files warning. 5. Treat the warning as a defect in review: it means a file someone expected to ship is not in the bundle.

  • How does a test read a fixture from a folder declared with `.copy`?
    Through the generated accessor, keeping the folder path: `Bundle.module.url(forResource: "list", withExtension: "json", subdirectory: "Fixtures/users")`. `Bundle.module` exists only in a module that has resources, and it is internal to that module.
  • When is `.embedInCode` a better choice than a bundled resource?
    For a small file the code needs at start-up without any bundle lookup. Since tools version 5.9 it makes SwiftPM generate a `PackageResources` struct with a static `[UInt8]` property per embedded file, so the bytes are compiled into the module.

  • Every non-Swift file in a target's folder is bundled automatically.
  • .copy is the recommended default because it never changes a file.
  • With .process, a folder's subfolders are preserved inside the bundle.
  • Package resources are read through Bundle.main, like the app's own resources.
  • An asset catalog must be listed with .process before SwiftPM will bundle it.

Assumes tools version 5.3 or later for resources and 5.9 or later for .embedInCode; messages and bundle layout checked with SwiftPM 6.4, whose default build system is Swift Build.