[vcpkg] Add initial versioning documentation

docs/users/manifests.md

@@ -64,13 +64,27 @@ Additionally, the `"port-version"` field is used by registries of packages,
 as a way to version "the package gotten from `vcpkg install`" differently from the upstream package version.
 You shouldn't need to worry about this at all.
 
+#### Additional version fields
+
+**Experimental behind the `versions` feature flag**
+
+See [versioning.md](versioning.md#version%20schemes) for additional version types.
+
 ### `"description"`
 
 This is where you describe your project. Give it a good description to help in searching for it!
 This can be a single string, or it can be an array of strings;
 in the latter case, the first string is treated as a summary,
 while the remaining strings are treated as the full description.
 
+### `"builtin-baseline"`
+
+**Experimental behind the `versions` feature flag**
+
+This field indicates the commit of vcpkg which provides global minimum version information for your manifest. It is required for top-level manifest files using versioning.
+
+See also [versioning](versioning.md#builtin-baseline) for more semantic details.
+
 ### `"dependencies"`
 
 This field lists all the dependencies you'll need to build your library (as well as any your dependents might need,
@@ -131,6 +145,22 @@ The common identifiers are:
 
 although one can define their own.
 
+#### `"version>="`
+
+**Experimental behind the `versions` feature flag**
+
+A minimum version constraint on the dependency.
+
+This field specifies the primary scheme text of the dependency and the optional `"port-version"` field specifies a minimum port version (if any).
+
+See also [versioning](versioning.md#constraints) for more semantic details.
+
+#### `"port-version"`
+
+**Experimental behind the `versions` feature flag**
+
+See `"version>="` above.
+
 #### Example:
 
 ```json
@@ -151,6 +181,26 @@ although one can define their own.
 }
 ```
 
+### `"overrides"`
+
+**Experimental behind the `versions` feature flag**
+
+This field enables version resolution to be ignored for certain dependencies and to use specific versions instead.
+
+See also [versioning](versioning.md#overrides) for more semantic details.
+
+#### Example:
+
+```json
+{
+  "overrides": [
+    {
+      "name": "arrow", "version": "1.2.3", "port-version": 7
+    }
+  ]
+}
+```
+
 ### `"supports"`
 
 If your project doesn't support common platforms, you can tell your users this with the `"supports"` field.
@@ -180,17 +230,17 @@ and that's the `"default-features"` field, which is an array of feature names.
   "name": "libdb",
   "description": [
     "An example database library.",
-    "Optionally uses one of CBOR, JSON, or CSV as a backend."
+    "Optionally can build with CBOR, JSON, or CSV as backends."
   ],
+  "$default-features-explanation": "Users using this library transitively will get all backends automatically",
   "default-features": [ "cbor", "csv", "json" ],
   "features": {
     "cbor": {
       "description": "The CBOR backend",
       "dependencies": [
         {
           "$explanation": [
-            "This is currently how you tell vcpkg that the cbor feature depends on the json feature of this package",
-            "We're looking into making this easier"
+            "This is how you tell vcpkg that the cbor feature depends on the json feature of this package"
           ],
           "name": "libdb",
           "default-features": false,

docs/users/versioning.md

@@ -0,0 +1,84 @@
+# Versioning
+
+**This feature is experimental and requires `--feature-flags=versions`**
+
+Versioning allows you to deterministically control the precise revisions of dependencies used by
+your project from within your manifest file.
+
+## Version schemes
+
+### Schemes
+Versions in vcpkg come in three primary flavors:
+
+#### version
+A dot-separated sequence of numbers (1.2.3.4)
+
+#### version-date
+A date (2021-01-01.5)
+
+#### version-semver
+A Semantic Version 2.0 (2.1.0-rc2)
+
+See https://semver.org/ for a full specification.
+
+#### version-string
+An exact, incomparable version (strawberry)
+
+### Port Versions
+Each version additionally has a "port-version" which is a natural number. When rendered as text, the
+port version (if nonzero) is added as a suffix to the primary version text separated by a hash (#).
+Port-versions are sorted lexographically after the primary field, for example:
+
+    1.0.0 < 1.0.0#1 < 1.0.1 < 1.0.1#5 < 2.0.0
+
+## Constraints
+
+Manifests can place three kinds of constraints upon the versions used:
+
+### builtin-baseline
+The baseline references a commit within the vcpkg repository that
+establishes a minimum version on every dependency in the graph. If
+no other constraints are specified (directly or transitively),
+then the version from the baseline of the top level manifest will
+be used.
+
+You can get the current commit of your vcpkg instance either by adding an empty `"builtin-baseline"` field, installing, and examining the error message or by running `git rev-parse HEAD` in the root of the vcpkg instance.
+
+Baselines provide stability and ease of development for top-level manifest files. They are not considered from ports consumed as a dependency. If a minimum version constraint is required during transitive version resolution, the port should use `version>=`.
+
+### version>=
+Within the "dependencies" field, each dependency can have a
+minimum constraint listed. These minimum constraints will be used
+when transitively depending upon this library. A minimum
+port-version can additionally be specified with the "port-version"
+field in the same object.
+
+### overrides
+When used as the top-level manifest (such as when running `vcpkg
+install` in the directory), overrides allow a manifest to
+short-circuit dependency resolution and specify exactly the
+version to use. These can be used to handle version conflicts,
+such as with `version-string` dependencies.
+
+Overrides are not considered from ports consumed as a dependency.
+
+## Example top-level manifest:
+```json
+{
+    "name": "example",
+    "version": "1.0",
+    "builtin-baseline": "a14a6bcb27287e3ec138dba1b948a0cdbc337a3a",
+    "dependencies": [
+        { "name": "zlib", "version>=": "1.2.11", "port-version": 8 },
+        "rapidjson"
+    ],
+    "overrides": [
+        { "name": "rapidjson", "version": "2020-09-14" }
+    ]
+}
+```
+See also the [manifest documentation](manifests.md) for more syntax information.
+
+## Original Specification
+
+See also the [original specification](https://github.com/vicroms/vcpkg/blob/versioning-spec/docs/specifications/versioning.md)

scripts/azure-pipelines/end-to-end-tests-dir/versions.ps1

@@ -59,17 +59,35 @@ Throw-IfFailed
 Throw-IfFailed
 
 $CurrentTest = "default baseline"
-$out = ./vcpkg $commonArgs "--feature-flags=versions" install --x-manifest-root=scripts/testing/version-files/default-baseline-1
+$out = ./vcpkg $commonArgs "--feature-flags=versions" install --x-manifest-root=scripts/testing/version-files/default-baseline-1 2>&1 | Out-String
 Throw-IfNotFailed
-# if ($out -notmatch "Error: while checking out baseline" -or $out -notmatch " does not exist in ")
-# {
-#     $out
-#     throw "Expected to fail due to missing baseline"
-# }
+if ($out -notmatch ".*Error: while checking out baseline.*")
+{
+    $out
+    throw "Expected to fail due to missing baseline"
+}
 
 git fetch https://github.com/vicroms/test-registries
-$CurrentTest = "default baseline"
+$CurrentTest = "without default baseline 2 -- enabling versions should not change behavior"
+Remove-Item -Recurse $buildtreesRoot/versioning -ErrorAction SilentlyContinue
+./vcpkg $commonArgs "--feature-flags=versions" install `
+    "--dry-run" `
+    "--x-manifest-root=scripts/testing/version-files/without-default-baseline-2" `
+    "--x-builtin-port-versions-dir=scripts/testing/version-files/default-baseline-2/port_versions"
+Throw-IfFailed
+Require-FileNotExists $buildtreesRoot/versioning
+
+$CurrentTest = "default baseline 2"
 ./vcpkg $commonArgs "--feature-flags=versions" install `
+    "--dry-run" `
     "--x-manifest-root=scripts/testing/version-files/default-baseline-2" `
     "--x-builtin-port-versions-dir=scripts/testing/version-files/default-baseline-2/port_versions"
 Throw-IfFailed
+Require-FileExists $buildtreesRoot/versioning
+
+$CurrentTest = "using version features fails without flag"
+./vcpkg $commonArgs "--feature-flags=-versions" install `
+    "--dry-run" `
+    "--x-manifest-root=scripts/testing/version-files/default-baseline-2" `
+    "--x-builtin-port-versions-dir=scripts/testing/version-files/default-baseline-2/port_versions"
+Throw-IfNotFailed

scripts/azure-pipelines/end-to-end-tests-prelude.ps1

@@ -12,7 +12,7 @@ $commonArgs = @(
     "--x-buildtrees-root=$buildtreesRoot",
     "--x-install-root=$installRoot",
     "--x-packages-root=$packagesRoot",
-    "--overlay-ports=scripts/e2e_ports/overlays"
+    "--overlay-ports=$PSScriptRoot/../e2e_ports/overlays"
 )
 $Script:CurrentTest = 'unassigned'
 

scripts/generatePortVersionsDb.py

@@ -35,7 +35,7 @@ def generate_port_versions_file(port_name):
         env = os.environ.copy()
         env['GIT_OPTIONAL_LOCKS'] = '0'
         output = subprocess.run(
-            [os.path.join(SCRIPT_DIRECTORY, '../vcpkg.exe'),
+            [os.path.join(SCRIPT_DIRECTORY, '../vcpkg'),
              'x-history', port_name, '--x-json', f'--output={output_file_path}'],
             capture_output=True, encoding='utf-8', env=env)
         if output.returncode != 0:

scripts/testing/version-files/default-baseline-1/vcpkg.json

@@ -1,7 +1,7 @@
 {
     "name": "default-baseline-test",
     "version-string": "0",
-    "$x-default-baseline": "fca18ba3572f8aebe3b8158c359db62a7e26134e",
+    "builtin-baseline": "fca18ba3572f8aebe3b8158c359db62a7e26134e",
     "dependencies": [
         "zlib"
     ]

scripts/testing/version-files/default-baseline-2/vcpkg.json

@@ -1,7 +1,7 @@
 {
-    "name": "default-baseline-test",
+    "name": "default-baseline-test-2",
     "version-string": "0",
-    "$x-default-baseline": "cbd5a68012471f820b7cf28d618199b4a4d89c58",
+    "builtin-baseline": "cbd5a68012471f820b7cf28d618199b4a4d89c58",
     "dependencies": [
         "zlib"
     ]

scripts/testing/version-files/without-default-baseline-2/port_versions/z-/zlib.json

@@ -0,0 +1,14 @@
+{
+    "versions": [
+        {
+            "git-tree": "7bb2b2f3783303a4dd41163553fe4cc103dc9262",
+            "version-string": "1.2.11",
+            "port-version": 9
+        },
+        {
+            "git-tree": "4927735fa9baca564ebddf6e6880de344b20d7a8",
+            "version-string": "1.2.11",
+            "port-version": 8
+        }
+    ]
+}

scripts/testing/version-files/without-default-baseline-2/vcpkg.json

@@ -0,0 +1,7 @@
+{
+    "name": "without-default-baseline-test-2",
+    "version-string": "0",
+    "dependencies": [
+        "zlib"
+    ]
+}

scripts/vcpkg.schema.json

@@ -256,6 +256,10 @@
           "description": "An SPDX license expression at version 3.9.",
           "type": "string"
         },
+        "builtin-baseline": {
+          "description": "A vcpkg repository commit for version control.",
+          "type": "string"
+        },
         "dependencies": {
           "description": "Dependencies that are always required.",
           "type": "array",

toolsrc/include/vcpkg/base/expected.h

@@ -226,11 +226,10 @@ namespace vcpkg
         void exit_if_error(const LineInfo& line_info) const
         {
             // This is used for quick value_or_exit() calls, so always put line_info in the error message.
-            Checks::check_exit(line_info,
-                               !m_s.has_error(),
-                               "Failed at [%s] with message:\n%s",
-                               line_info.to_string(),
-                               m_s.to_string());
+            if (m_s.has_error())
+            {
+                Checks::exit_with_message(line_info, "Failed at [%s] with message:\n%s", line_info, m_s.to_string());
+            }
         }
 
         ErrorHolder<S> m_s;

toolsrc/include/vcpkg/sourceparagraph.h

@@ -68,6 +68,7 @@ namespace vcpkg
         std::vector<DependencyOverride> overrides;
         std::vector<std::string> default_features;
         std::string license; // SPDX license expression
+        Optional<std::string> builtin_baseline;
 
         Type type;
         PlatformExpression::Expr supports_expression;

toolsrc/include/vcpkg/vcpkgpaths.h

@@ -118,8 +118,12 @@ namespace vcpkg
         const std::string& get_tool_version(const std::string& tool) const;
 
         // Git manipulation in the vcpkg directory
-        fs::path git_checkout_baseline(Files::Filesystem& filesystem, StringView commit_sha) const;
-        fs::path git_checkout_port(Files::Filesystem& filesystem, StringView port_name, StringView git_tree) const;
+        ExpectedS<std::string> get_current_git_sha() const;
+        std::string get_current_git_sha_message() const;
+        ExpectedS<fs::path> git_checkout_baseline(StringView commit_sha) const;
+        ExpectedS<fs::path> git_checkout_port(StringView port_name,
+                                              StringView git_tree,
+                                              const fs::path& dot_git_dir) const;
         ExpectedS<std::string> git_show(const std::string& treeish, const fs::path& dot_git_dir) const;
 
         ExpectedS<std::map<std::string, std::string, std::less<>>> git_get_local_port_treeish_map() const;
@@ -158,12 +162,5 @@ namespace vcpkg
                                          const fs::path& destination,
                                          const fs::path& dot_git_dir,
                                          const fs::path& work_tree);
-
-        static void git_checkout_object(const VcpkgPaths& paths,
-                                        StringView git_object,
-                                        const fs::path& local_repo,
-                                        const fs::path& destination,
-                                        const fs::path& dot_git_dir,
-                                        const fs::path& work_tree);
     };
 }

toolsrc/include/vcpkg/versions.h

@@ -81,8 +81,7 @@ namespace vcpkg::Versions
         enum class Type
         {
             None,
-            Minimum,
-            Exact
+            Minimum
         };
     };
 }