In a Package.swift manifest, when do you declare a target's resources with `.process` versus `.copy`, and what goes wrong with each?
answer
- files that are not source
- optimise versus untouched
- flattened to the bundle's top level
- duplicate names across subfolders
basics
~20 sDeclare .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 sFrom 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-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
Recall that non-code files in a target need a rule in resources:, and that code reads them through Bundle.module.
Explain the difference between processing and copying, including flattening and the duplicate-name error, and when exclude: is the right tool.
Diagnose missing or nil resources from the build warning and the bundle layout, and choose .copy for fixtures whose paths tests depend on.
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.