Skip to content

Commit 4592649

Browse files
authored
using more direct language to make it clear Package.resolved doesn't pin versions for dependencies (#9181)
Update the language in the section about Package.resolved to provide additional clarity and directness about when it can be useful, and when Swift Package Manager ignores it in favor of global dependency resolution.
1 parent 1abd9a2 commit 4592649

File tree

1 file changed

+19
-9
lines changed

1 file changed

+19
-9
lines changed

Sources/PackageManagerDocs/Documentation.docc/ResolvingPackageVersions.md

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,39 @@ Coordinate and constrain dependencies for your package.
55
## Overview
66

77
The package manager records the result of dependency resolution in a file named `Package.resolved` at the top-level of the package.
8-
When this file is already present and you are directly resolving dependencies, `Package.resolved` is used to define the versions of the dependencies rather than the package manager finding the latest eligible versions.
9-
If the package is being resolved as a dependency from another package, any local `Package.resolved` file is ignored during that resolution.
8+
When this file is present and you are resolving dependencies for the top-level (leaf) package of a dependency tree, the package manager uses the `Package.resolved` file as a cache of versions of the dependencies.
9+
The Package.resolved file does not pin dependency versions for packages used as libraries, or are otherwise included as a dependency for another Swift project.
10+
If the package is being resolved as a dependency from another package, its own `Package.resolved` file is ignored during that resolution.
1011

1112
Most SwiftPM commands implicitly invoke dependency resolution before running, and cancel with an error if dependencies cannot be resolved.
1213

1314
### Resolving Dependencies
1415

1516
Run <doc:PackageResolve> to resolve the dependencies, taking into account the current version constraints in the `Package.swift` manifest and a `Package.resolved` resolved versions file.
1617
For packages with a `Package.resolved` file, the `resolve` command resolves to those versions as long as they are still eligible.
18+
If you want to explicitly use the dependencies written into `Package.resolved`, use the `--force-resolved-versions` when invoking `swift resolve`.
19+
For example, to force the dependencies to align with the versions defined in `Package.resolved`, use:
1720

18-
If the resolved version's file changes (for example, because a teammate shared an update through source control) the next `resolve` command attempts to update the package dependencies to match that file.
19-
In most cases the resolve command performs no changes unless the `Package.swift` manifest or `Package.resolved` file changed.
21+
```bash
22+
swift package resolve --force-resolved-versions
23+
```
24+
25+
If the resolved version's file changes (for example, because a teammate shared an update through source control), the next `resolve` command attempts to update the package dependencies to match that file.
26+
In most cases, the resolve command performs no changes unless the `Package.swift` manifest or `Package.resolved` file has changed.
2027

2128
### Updating the dependencies
2229

23-
Running <doc:PackageUpdate> updates all dependencies to the latest eligible versions and updates the `Package.resolved` file accordingly.
30+
Run <doc:PackageUpdate> to update a package's dependencies to the latest eligible versions, which also updates the `Package.resolved` file.
2431

2532
### Coordinating versions of dependencies for your package
2633

27-
Keep the `Package.resolved` file in source control to coordinate specific dependencies for direct consumers of the package.
28-
If a `Package.resolved` doesn't exist, each user separately resolves dependency versions, only updating when they run <doc:PackageUpdate>, and new users start with the latest eligible version of each dependency.
29-
If the `Package.resolved` file does exist, any command that requires dependencies (for example, <doc:SwiftBuild> or <doc:SwiftRun>) attempts to resolve the versions of dependencies recorded in the file.
34+
You can use `Package.resolved` to coordinate the versions of dependencies it uses for a leaf Swift project - one that isn't being used as a dependency.
35+
For example, you can keep a `Package.resolved` file in source control, or resolve it locally and pass it to a container image build process, in order to ensure another build uses the same versions of dependencies.
3036

31-
The `Package.resolved` doesn't constrain upstream dependencies of the package.
37+
The `Package.resolved` only helps to resolve dependencies to the specific versions it defines for leaf projects.
38+
It does not provide any dependency pinning for libraries or packages that are used as dependencies for other Swift projects.
3239
For example, if your package presents a library and has `Package.resolved` checked in, those versions are ignored by the package that depends on your library, and the latest eligible versions are chosen.
3340
For more information on constraining dependency versions, see <doc:AddingDependencies>.
41+
42+
If a `Package.resolved` doesn't exist, each user or build system separately resolves dependency versions, only updating when they run <doc:PackageUpdate>, and new users start with the latest eligible version of each dependency.
43+
If the `Package.resolved` file does exist, any command that requires dependencies (for example, <doc:SwiftBuild> or <doc:SwiftRun>) attempts to resolve the versions of dependencies recorded in the file.

0 commit comments

Comments
 (0)