[vcpkg] Add initial versioning documentation (#15565)

* [vcpkg] Improve efficiency and tests of versioning

* [vcpkg] Add initial versioning documentation and rename x-default-baseline to builtin-baseline

* [vcpkg] Enable metrics for builtin-baseline & overrides

* [vcpkg] Address PR comments

* [vcpkg] Add support for  syntax in version>=

* [vcpkg] Remove port-version from dependency syntax

* [vcpkg] Address CR comment

* [vcpkg] Minor docs fixup

3 files changed, 44 insertions, 42 deletions

diff --git a/scripts/azure-pipelines/end-to-end-tests-dir/registries.ps1 b/scripts/azure-pipelines/end-to-end-tests-dir/registries.ps1
index 777c0901f..ef7023c85 100644
--- a/scripts/azure-pipelines/end-to-end-tests-dir/registries.ps1
+++ b/scripts/azure-pipelines/end-to-end-tests-dir/registries.ps1
@@ -14,12 +14,13 @@ Throw-IfNotFailed
 Run-Vcpkg install @builtinRegistryArgs --feature-flags=registries 'zlib'
 Throw-IfFailed
 
-# Test git and filesystem registries
+Write-Trace "Test git and filesystem registries"
 Refresh-TestRoot
 $filesystemRegistry = "$TestingRoot/filesystem-registry"
 $gitRegistryUpstream = "$TestingRoot/git-registry-upstream"
 
 # build a filesystem registry
+Write-Trace "build a filesystem registry"
 New-Item -Path $filesystemRegistry -ItemType Directory
 $filesystemRegistry = (Get-Item $filesystemRegistry).FullName
 
@@ -51,6 +52,7 @@ New-Item `
 
 
 # build a git registry
+Write-Trace "build a git registry"
 New-Item -Path $gitRegistryUpstream -ItemType Directory
 $gitRegistryUpstream = (Get-Item $gitRegistryUpstream).FullName
 
@@ -82,6 +84,7 @@ finally
 }
 
 # actually test the registries
+Write-Trace "actually test the registries"
 $vcpkgJson = @{
     "name" = "manifest-test";
     "version-string" = "1.0.0";
@@ -90,37 +93,8 @@ $vcpkgJson = @{
     )
 }
 
-$manifestDir = "$TestingRoot/builtin-registry-test-manifest-dir"
-
-New-Item -Path $manifestDir -ItemType Directory
-$manifestDir = (Get-Item $manifestDir).FullName
-
-Push-Location $manifestDir
-
-try
-{
-    $vcpkgJsonWithBaseline = $vcpkgJson.Clone()
-    $vcpkgJsonWithBaseline['$x-default-baseline'] = 'default'
-
-    New-Item -Path 'vcpkg.json' -ItemType File `
-        -Value (ConvertTo-Json -Depth 5 -InputObject $vcpkgJson)
-
-    Run-Vcpkg install @builtinRegistryArgs '--feature-flags=registries,manifests'
-    Throw-IfNotFailed
-
-    New-Item -Path 'vcpkg.json' -ItemType File -Force `
-        -Value (ConvertTo-Json -Depth 5 -InputObject $vcpkgJsonWithBaseline)
-
-    Run-Vcpkg install @builtinRegistryArgs '--feature-flags=registries,manifests'
-    Throw-IfFailed
-}
-finally
-{
-    Pop-Location
-}
-
-
 # test the filesystem registry
+Write-Trace "test the filesystem registry"
 $manifestDir = "$TestingRoot/filesystem-registry-test-manifest-dir"
 
 New-Item -Path $manifestDir -ItemType Directory
@@ -154,6 +128,7 @@ finally
 }
 
 # test the git registry
+Write-Trace "test the git registry"
 $manifestDir = "$TestingRoot/git-registry-test-manifest-dir"
 
 New-Item -Path $manifestDir -ItemType Directory
diff --git a/scripts/azure-pipelines/end-to-end-tests-dir/versions.ps1 b/scripts/azure-pipelines/end-to-end-tests-dir/versions.ps1
index f5f9de20b..11550d7bd 100644
--- a/scripts/azure-pipelines/end-to-end-tests-dir/versions.ps1
+++ b/scripts/azure-pipelines/end-to-end-tests-dir/versions.ps1
@@ -59,17 +59,40 @@ 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"

-./vcpkg $commonArgs --debug "--feature-flags=versions" install `

-    "--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

+foreach ($opt_registries in @("",",registries"))

+{

+    Write-Trace "testing baselines: $opt_registries"

+    Refresh-TestRoot

+    $CurrentTest = "without default baseline 2 -- enabling versions should not change behavior"

+    Remove-Item -Recurse $buildtreesRoot/versioning -ErrorAction SilentlyContinue

+    ./vcpkg $commonArgs "--feature-flags=versions$opt_registries" 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$opt_registries" 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$opt_registries" 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

+}
\ No newline at end of file
diff --git a/scripts/azure-pipelines/end-to-end-tests-prelude.ps1 b/scripts/azure-pipelines/end-to-end-tests-prelude.ps1
index deadb210c..29718bf76 100644
--- a/scripts/azure-pipelines/end-to-end-tests-prelude.ps1
+++ b/scripts/azure-pipelines/end-to-end-tests-prelude.ps1
@@ -63,6 +63,10 @@ function Throw-IfNotFailed {
     }

 }

 

+function Write-Trace ([string]$text) {

+    Write-Host (@($MyInvocation.ScriptName, ":", $MyInvocation.ScriptLineNumber, ": ", $text) -join "")

+}

+

 function Run-Vcpkg {

     Param(

         [Parameter(ValueFromRemainingArguments)]