--- /dev/null
+# Versioning: Implementation details\r
+\r
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/versioning.implementation-details.md).**\r
+\r
+## Contents\r
+\r
+* [Minimum versioning](#minimum-versioning)\r
+* [Constraint resolution](#constraint-resolution)\r
+* [Acquiring port versions](#acquiring-port-versions)\r
+\r
+\r
+### Minimum versioning\r
+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:\r
+\r
+* Always starts from a fresh install, eliminates the need for upgrade/downgrade operations.\r
+* Allow unconstrained dependencies by introducing baselines.\r
+\r
+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.\r
+ \r
+Using a minimum version approach has the following advantages:\r
+* Is predictable and easy to understand.\r
+* User controls when upgrades happen, as in, no upgrades are performed automatically when a new version is released.\r
+* Avoids using a SAT solver.\r
+\r
+To give an example, consider the following package graph:\r
+```\r
+ (A 1.0) -> (B 1.0)\r
+ \r
+ (A 1.1) -> (B 1.0) \r
+ -> (C 3.0) \r
+ \r
+ (A 1.2) -> (B 2.0)\r
+ -> (C 3.0)\r
+\r
+ (C 2.0)\r
+```\r
+\r
+And the following manifest:\r
+```\r
+{\r
+ "name": "example",\r
+ "version": "1.0.0",\r
+ "dependencies": [ \r
+ { "name": "A", "version>=": "1.1" },\r
+ { "name": "C", "version>=": "2.0" }\r
+ ], \r
+ "builtin-baseline": "<some git commit with A's baseline at 1.0>"\r
+}\r
+```\r
+\r
+After accounting for transitive dependencies we have the following set of constraints:\r
+* A >= 1.1\r
+ * B >= 1.0\r
+ * C >= 3.0\r
+* C >= 2.0\r
+\r
+Since vcpkg has to satisfy all the constraints, the set of installed packages becomes:\r
+\r
+* `A 1.1`, even when `A 1.2` exists, there are no constraints higher than `1.1` so vcpkg selects the minimum version possible.\r
+* `B 1.0`, transitively required by `A 1.1`.\r
+* `C 3.0`, upgraded by the transitive constraint added by `B 1.0` in order to satisfy version constraints.\r
+\r
+## Constraint resolution\r
+Given a manifest with a set of versioned dependencies, vcpkg will attempt to calculate a package installation plan that satisfies all the constraints. \r
+\r
+Version constraints come in the following flavors:\r
+* **Declared constraints**: Constraints declared explicitly in the top-level manifest using `version>=`.\r
+* **Baseline constraints**: Constraints added implicitly by the `builtin-baseline`.\r
+* **Transitive constraints**: Constraints added indirectly by dependencies of your dependencies.\r
+* **Overridden constraints**: Constraints overridden in the top-level manifest using `overrides` declarations.\r
+\r
+To compute an installation plan, vcpkg follows roughly these steps:\r
+\r
+* Add all top-level constraints to the plan.\r
+* Recursively add transitive constraints to the plan.\r
+ * Each time a new package is added to the plan, also add its baseline constraint to the plan.\r
+ * Each time a constraint is added:\r
+ * If an override exists for the package\r
+ * Select the version in the override.\r
+ * Otherwise:\r
+ * If there is no previous version selected. \r
+ * Select the minimal version that satisfies the constraint.\r
+ * If there is a previous version selected:\r
+ * If the versioning scheme of the new constraint does not match that of the previously selected version:\r
+ * Add a version conflict.\r
+ * If the constraint's version is not comparable to the previously selected version. For example, comparing "version-string: apple" to "version-string: orange":\r
+ * Add a version conflict.\r
+ * If the constraints version is higher than the previously selected version:\r
+ * Select the highest version.\r
+ * Otherwise: \r
+ * Keep the previous selection.\r
+* Review the plan:\r
+ * If there are no conflicts\r
+ * Install the selected packages\r
+ * Otherwise:\r
+ * Report the conflicts to the user\r
+\r
+## Acquiring port versions\r
+Although the concept of package versions has always been present in vcpkg, the concept of version constraints has been not.\r
+\r
+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.\r
+\r
+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.\r
+\r
+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.\r
+\r
+Example: `zlib.json`\r
+\r
+```\r
+{\r
+ "versions": [\r
+ {\r
+ "git-tree": "2dfc991c739ab9f2605c2ad91a58a7982eb15687",\r
+ "version-string": "1.2.11",\r
+ "port-version": 9\r
+ },\r
+ ...\r
+ {\r
+ "git-tree": "a516e5ee220c8250f21821077d0e3dd517f02631",\r
+ "version-string": "1.2.10",\r
+ "port-version": 0\r
+ },\r
+ {\r
+ "git-tree": "3309ec82cd96d752ff890c441cb20ef49b52bf94",\r
+ "version-string": "1.2.8",\r
+ "port-version": 0\r
+ }\r
+ ]\r
+}\r
+```\r
+\r
+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`.\r
+\r
+\r
projects / ceph.git / blobdiff