3party/vcpkg
0
0
Fork 0
mirror of https://github.com/microsoft/vcpkg.git synced 2024-12-28 11:21:12 +08:00
Code Issues Projects Releases Wiki Activity

[docs] More Getting Started fixes (#18970)

Browse Source 
* Use valid commmit ID for baseline

* More doc fixes
This commit is contained in:
Victor Romero 2021-07-20 16:24:38 -07:00 committed by GitHub
parent 1c20782ea4
commit 3c82e1931e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 27 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
docs/examples/versioning.getting-started.md
View File

@ -20,11 +20,11 @@ Create a folder with the following files:
"dependencies": [
{
"name": "fmt",
"version>=": "7.1.3"
"version>=": "7.1.3#1"
},
"zlib"
],
"builtin-baseline": "68a74950d0400f5a803026d0860f49853984bf11"
"builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc"
}
```
@ -69,8 +69,10 @@ PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/script
-- Running vcpkg install
Detecting compiler hash for triplet x86-windows...
The following packages will be built and installed:
fmt[core]:x86-windows -> 7.1.3 -- D:\vcpkg\buildtrees\versioning\versions\fmt\dd8cf5e1a2dce2680189a0744102d4b0f1cfb8b6
zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
fmt[core]:x64-windows -> 7.1.3#1 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72
vcpkg-cmake[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake\51896aa8073adb5c8450daa423d03eedf0dfc61f
vcpkg-cmake-config[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake-config\d255b3d566a8861dcc99a958240463e678528066
zlib[core]:x64-windows -> 1.2.11#9 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
...
```
@ -90,7 +92,8 @@ zlib version is 1.2.11
Take a look at the output:
```
fmt[core]:x86-windows -> 7.1.3 -- D:\vcpkg\buildtrees\versioning\versions\fmt\dd8cf5e1a2dce2680189a0744102d4b0f1cfb8b6
fmt[core]:x86-windows -> 7.1.3#1 -- D:\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72
...
zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
```
@ -130,23 +133,23 @@ Version scheme | Description
}
```
This property is used to express minimum version constraints, it is allowed only as part of the `"dependencies"` declarations. In our example we set an explicit constraint on version `7.1.3` of `fmt`.
This property is used to express minimum version constraints, it is allowed only as part of the `"dependencies"` declarations. In our example we set an explicit constraint on version `7.1.3#1` of `fmt`.
Vcpkg is allowed to upgrade this constraint if a transitive dependency requires a newer version. For example, if `zlib` were to declare a dependency on `fmt` version `7.1.4` then vcpkg would install `7.1.4` instead.
Vcpkg uses a minimum version approach, in our example, even if `fmt` version `8.0.0` were to be released, vcpkg would still install version `7.1.3` as that is the minimum version that satisfies the constraint. The advantages of this approach are that you don't get unexpected dependency upgrades when you update vcpkg and you get reproducible builds (in terms of version used) as long as you use the same manifest.
Vcpkg uses a minimum version approach, in our example, even if `fmt` version `8.0.0` were to be released, vcpkg would still install version `7.1.3#1` as that is the minimum version that satisfies the constraint. The advantages of this approach are that you don't get unexpected dependency upgrades when you update vcpkg and you get reproducible builds (in terms of version used) as long as you use the same manifest.
If you want to upgrade your dependencies, you can bump the minimum version constraint or use a newer baseline.
#### **`builtin-baseline`**
```json
{ "builtin-baseline": "68a74950d0400f5a803026d0860f49853984bf11" }
{ "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc" }
```
This field declares the versioning baseline for all ports. Setting a baseline is required to enable versioning, otherwise you will get the current versions on the ports directory. You can run 'git rev-parse HEAD' to get the current commit of vcpkg and set it as the builtin-baseline. See the [`builtin-baseline` documentation](../users/versioning.md#builtin-baseline) for more information.
In our example, you can notice that we do not declare a version constraint for `zlib`; instead, the version is taken from the baseline. Internally, vcpkg will look in commit `68a74950d0400f5a803026d0860f49853984bf11` to find out what version of `zlib` was the latest at that point in time (in our case it was `1.2.11#9`).
In our example, you can notice that we do not declare a version constraint for `zlib`; instead, the version is taken from the baseline. Internally, vcpkg will look in commit `3426db05b996481ca31e95fff3734cf23e0f51bc` to find out what version of `zlib` was the latest at that point in time (in our case it was `1.2.11#9`).
During version resolution, baseline versions are treated as minimum version constraints. If you declare an explicit constraint that is lower than a baseline version, the explicit constraint will be upgraded to the baseline version.
@ -155,7 +158,7 @@ For example, if we modified our dependencies like this:
{ "dependencies": [
{
"name": "fmt",
"version>=": "7.1.3"
"version>=": "7.1.3#1"
},
{
"name": "zlib",
@ -187,14 +190,14 @@ Let's modify our example once more, this time to force vcpkg to use version `6.0
"dependencies": [
{
"name": "fmt",
"version>=": "7.1.3"
"version>=": "7.1.3#1"
},
{
"name": "zlib",
"version>=": "1.2.11#7"
}
],
"builtin-baseline": "68a74950d0400f5a803026d0860f49853984bf11",
"builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc",
"overrides": [
{
"name": "fmt",

21
docs/users/versioning.md
View File

@ -33,6 +33,10 @@ Manifest property | Versioning scheme
A manifest must contain only one version declaration.
_NOTE: By design, vcpkg does not compare versions that use different schemes. For example, a package
that has a `version-string: 7.1.3` cannot be compared with the same package using `version: 7.1.4`, even if the
conversion seems obvious._
#### `version`
Accepts version strings that follow a relaxed, dot-separated-, semver-like scheme.
@ -111,13 +115,10 @@ Example:
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.
When resolving version constraints for a package, vcpkg will look for a baseline version:
* First by looking at the baseline file in the given commit ID.
* If the given commit ID does not contain a baseline file, vcpkg will fallback to use the local baseline file instead.
* If there's no local baseline file, vcpkg will use the version currently available in the ports directory.
_NOTE: If a baseline file is found, but it does not contain an entry for the package, the vcpkg invocation will fail._
When resolving version constraints for a package, vcpkg will look for a baseline version by looking
at the baseline file in the given commit ID.
If the given commit ID doesn't have a `versions/baseline.json` file or if the baseline file exists
but it does not declare a baseline version for the package the invocation will fail.
### `version>=`
Expresses a minimum version requirement, `version>=` declarations put a lower boundary on the versions that can be used to satisfy a dependency.
@ -130,9 +131,9 @@ Example:
"version-semver": "1.0.0",
"dependencies": [
{ "name": "zlib", "version>=": "1.2.11#9" },
{ "name": "fmt", "version>=": "7.1.3" }
{ "name": "fmt", "version>=": "7.1.3#1" }
],
"builtin-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe"
"builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc"
}
```
@ -153,7 +154,7 @@ For an override to take effect, the overridden package must form part of the dep
{ "name": "zlib", "version>=": "1.2.11#9" },
"fmt"
],
"builtin-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe",
"builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc",
"overrides": [
{ "name": "fmt", "version": "6.0.0" }
]