diff options
| author | Victor Romero <romerosanchezv@gmail.com> | 2021-02-08 12:03:37 -0800 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-02-08 12:03:37 -0800 |
| commit | 3187f09a3c395849203d3edf0e15c012d7e7e1ff (patch) | |
| tree | 12cd37e80f7509aa7ba63b552e11f2b02354232f /docs/users/versioning.implementation-details.md | |
| parent | 5eea585548058540c3b73d087eb101c033b5fa85 (diff) | |
| download | vcpkg-3187f09a3c395849203d3edf0e15c012d7e7e1ff.tar.gz vcpkg-3187f09a3c395849203d3edf0e15c012d7e7e1ff.zip | |
[vcpkg] More versioning docs (#15693)
* [vcpkg] Versioning docs: Getting started
* Versioning docs: Getting started [revised]
* Link to example of manifests in msbuild
* [WIP] Reference docs
* [vcpkg] Fix links in Getting Started with Versioning
Diffstat (limited to 'docs/users/versioning.implementation-details.md')
| -rw-r--r-- | docs/users/versioning.implementation-details.md | 132 |
1 files changed, 132 insertions, 0 deletions
diff --git a/docs/users/versioning.implementation-details.md b/docs/users/versioning.implementation-details.md new file mode 100644 index 000000000..f363fb438 --- /dev/null +++ b/docs/users/versioning.implementation-details.md @@ -0,0 +1,132 @@ +# Versioning: Implementation details
+
+## Contents
+
+* [Minimum versioning](#minimum-versioning)
+* [Constraint resolution](#constraint-resolution)
+* [Acquiring port versions](#acquiring-port-versions)
+
+
+### Minimum versioning
+Vcpkg uses a minimal selection approach to versioning, inspired by the one [used by Go](https://research.swtch.com/vgo-mvs). But modified in some ways:
+
+* Always starts from a fresh install, eliminates the need for upgrade/downgrade operations.
+* Allow unconstrained dependencies by introducing baselines.
+
+The minimal selection principle, however, stays the same. Given a set of constraints, vcpkg will use the "oldest" possible versions of packages that can satisfy all the constraints.
+
+Using a minimum version approach has the following advantages:
+* Is predictable and easy to understand.
+* User controls when upgrades happen, as in, no upgrades are performed automatically when a new version is released.
+* Avoids using a SAT solver.
+
+To give an example, consider the following package graph:
+```
+ (A 1.0) -> (B 1.0)
+
+ (A 1.1) -> (B 1.0)
+ -> (C 3.0)
+
+ (A 1.2) -> (B 2.0)
+ -> (C 3.0)
+
+ (C 2.0)
+```
+
+And the following manifest:
+```
+{
+ "name": "example",
+ "version": "1.0.0",
+ "dependencies": [
+ { "name": "A", "version>=": "1.1" },
+ { "name": "C", "version>=": "2.0" }
+ ],
+ "builtin-baseline": "<some git commit with A's baseline at 1.0>"
+}
+```
+
+After accounting for transitive dependencies we have the following set of constraints:
+* A >= 1.1
+ * B >= 1.0
+ * C >= 3.0
+* C >= 2.0
+
+Since vcpkg has to satisfy all the constraints, the set of installed packages becomes:
+
+* `A 1.1`, even when `A 1.2` exists, there are no constraints higher than `1.1` so vcpkg selects the minimum version possible.
+* `B 1.0`, transitively required by `A 1.1`.
+* `C 3.0`, upgraded by the transitive constraint added by `B 1.0` in order to satisfy version constraints.
+
+## Constraint resolution
+Given a manifest with a set of versioned dependencies, vcpkg will attempt to calculate a package installation plan that satisfies all the constraints.
+
+Version constraints come in the following flavors:
+* **Declared constraints**: Constraints declared explicitly in the top-level manifest using `version>=`.
+* **Baseline constraints**: Constraints added implicitly by the `builtin-baseline`.
+* **Transitive constraints**: Constraints added indirectly by dependencies of your dependencies.
+* **Overriden constraints**: Constraints overriden in the top-level manifest using `overrides` declarations.
+
+To compute an installation plan, vcpkg follows roughly these steps:
+
+* Add all top-level constraints to the plan.
+* Recursively add transitive constraints to the plan.
+ * Each time a new package is added to the plan, also add its baseline constraint to the plan.
+ * Each time a constraint is added:
+ * If an override exists for the package
+ * Select the version in the override.
+ * Otherwise:
+ * If there is no previous version selected.
+ * Select the minimal version that satisfies the constraint.
+ * If there is a previous version selected:
+ * If the versioning scheme of the new constraint does not match that of the previously selected version:
+ * Add a version conflict.
+ * If the constraint’s version is not comparable to the previously selected version. For example, comparing “version-string: apple” to “version-string: orange”:
+ * Add a version conflict.
+ * If the constraints version is higher than the previously selected version:
+ * Select the highest version.
+ * Otherwise:
+ * Keep the previous selection.
+* Review the plan:
+ * If there are no conflicts
+ * Install the selected packages
+ * Otherwise:
+ * Report the conflicts to the user
+
+## Acquiring port versions
+Although the concept of package versions has always been present in vcpkg, the concept of version constraints has been not.
+
+With the introduction of versioning constraints, it is now possible that a package depends on a port version that does not match the one available locally. This raises a problem as vcpkg needs to know how to acquire the port files for the requested version.
+
+To solve this problem, a new set of metadata files was introduced. These files are located in the `versions/` directory at the root level of the vcpkg repository.
+
+The `versions/` directory, will contain JSON files for each one of the ports available in the registry. Each file will list all the versions available for a package and contain a Git tree-ish object that vcpkg can check out to obtain that version’s portfiles.
+
+Example: `zlib.json`
+
+```
+{
+ "versions": [
+ {
+ "git-tree": "2dfc991c739ab9f2605c2ad91a58a7982eb15687",
+ "version-string": "1.2.11",
+ "port-version": 9
+ },
+ ...
+ {
+ "git-tree": "a516e5ee220c8250f21821077d0e3dd517f02631",
+ "version-string": "1.2.10",
+ "port-version": 0
+ },
+ {
+ "git-tree": "3309ec82cd96d752ff890c441cb20ef49b52bf94",
+ "version-string": "1.2.8",
+ "port-version": 0
+ }
+ ]
+}
+```
+
+For each port, its corresponding versions file should be located in `versions/{first letter of port name}-/{port name}.json`. For example, zlib’s version file will be located in `versions/z-/zlib.json`. Aside from port version files, the current baseline file is located in `versions/baseline.json`.
+
+
|