You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
Copy file name to clipboardExpand all lines: Sources/PackageManagerDocs/Documentation.docc/ResolvingPackageVersions.md
+19-9Lines changed: 19 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,29 +5,39 @@ Coordinate and constrain dependencies for your package.
5
5
## Overview
6
6
7
7
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.
10
11
11
12
Most SwiftPM commands implicitly invoke dependency resolution before running, and cancel with an error if dependencies cannot be resolved.
12
13
13
14
### Resolving Dependencies
14
15
15
16
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.
16
17
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:
17
20
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.
20
27
21
28
### Updating the dependencies
22
29
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.
24
31
25
32
### Coordinating versions of dependencies for your package
26
33
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.
30
36
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.
32
39
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.
33
40
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