開始使用版本控制

發行項
01/10/2024

搭配指令清單使用版本

讓我們從建立相依 fmt 於和 zlib的簡單 CMake 項目開始。

使用下列檔案建立資料夾：

vcpkg.json

{
    "name": "versions-test",
    "version": "1.0.0",
    "dependencies": [
        {
            "name": "fmt",
            "version>=": "7.1.3#1"
        }, 
        "zlib"
    ],
    "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc"
}

main.cpp

#include <fmt/core.h>
#include <zlib.h>

int main()
{
    fmt::print("fmt version is {}\n"
               "zlib version is {}\n", 
               FMT_VERSION, ZLIB_VERSION);
    return 0;
}

CMakeLists.txt

cmake_minimum_required(VERSION 3.18)

project(versionstest CXX)

add_executable(main main.cpp)

find_package(ZLIB REQUIRED)
find_package(fmt CONFIG REQUIRED)
target_link_libraries(main PRIVATE ZLIB::ZLIB fmt::fmt)

現在，我們會使用 CMake 建置並執行專案：

建立專案的組建目錄。

PS D:\versions-test> mkdir build
PS D:\versions-test> cd build

設定 CMake。

PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
-- Running vcpkg install
Detecting compiler hash for triplet x86-windows...
The following packages will be built and installed:
    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
...

組建專案。

PS D:\versions-test\build> cmake --build .
[2/2] Linking CXX executable main.exe

執行！

PS D:\versions-test\build> ./main.exe
fmt version is 70103
zlib version is 1.2.11

看看輸出：

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

vcpkg 會取出中每個版本的buildtrees/versioning/versions/檔案，而不是在中使用 ports/portfiles。在傳統模式中執行 vcpkg 時，仍會使用中的 ports/ 檔案。

注意

設定 CMake 時，vcpkg 的輸出僅適用於使用 CMake 版本或更新版本 3.18 時。如果您使用較舊的 CMake，您可以改為檢查 vcpkg-manifest-install.log 組建目錄中的檔案。

閱讀我們的指令清單公告部落格文章，瞭解如何搭配 MSBuild 使用指令清單。

指令清單變更

如果您之前已使用指令清單，您會發現有一些新的 JSON 屬性。讓我們來檢閱這些變更：

`version`

{
    "name": "versions-test",
    "version": "1.0.0"
}

這是您專案的版本宣告。先前，您只能使用 version-string 屬性來宣告專案的版本。現在版本控制已經來臨，vcpkg 知道一些新的版本控制配置。

版本配置	描述
`version`	以點分隔的數值： `1.0.0.5`。
`version-semver`	相容的語意版本： `1.2.0` 和 `1.2.0-rc`。
`version-date`	格式為 `YYYY-MM-DD` 的日期： `2021-01-01`
`version-string`	任意字串： `vista`、 `candy`。

`version>=`

{
    "dependencies": [
        { "name": "fmt", "version>=": "7.1.3" },
        "zlib"
    ]
}

這個屬性是用來表示最低版本條件約束，它只允許做為宣告的 "dependencies" 一部分。在我們的範例中，我們會在的版本7.1.3#1fmt上設定明確的條件約束。

如果可轉移的相依性需要較新版本，則允許 vcpkg 升級此條件約束。例如，如果要zlib宣告版本7.1.4相fmt依性，則 vcpkg 會改為安裝7.1.4。

vcpkg 會使用最低版本方法，在我們的範例中，即使 fmt 版本 8.0.0 已發行，vcpkg 仍會安裝版本，因為這是滿足條件約束的最低版本 7.1.3#1 。這種方法的優點是當您更新 vcpkg 時，不會收到非預期的相依性升級，只要使用相同的指令清單，您就會得到可重現的組建（就使用的版本而言）。

如果您想要升級相依性，您可以顛簸最低版本條件約束或使用較新的基準。

`builtin-baseline`

{ "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc" }

此欄位會宣告所有埠的版本設定基準。若要啟用版本控制，則需要設定基準，否則您會在目錄上 ports/ 取得目前的版本。您可以執行『git rev-parse HEAD』，以取得 vcpkg 的目前認可，並將其設定為內建基準。如需詳細資訊， "builtin-baseline" 請參閱檔。

在我們的範例中，我們不會針對宣告版本條件約束 zlib;相反地，版本取自基準。就內部而言，vcpkg 會查看認可 3426db05b996481ca31e95fff3734cf23e0f51bc ，以找出該時間點的最新版本 zlib （在我們的案例中為 1.2.11#9）。

在版本解析期間，基準版本會被視為最低版本條件約束。如果您宣告低於基準版本的明確條件約束，則會將明確條件約束升級至基準版本。

例如，如果我們修改了相依性，如下所示：

{ "dependencies": [
    {
        "name": "fmt",
        "version>=": "7.1.3#1"
    },
    {
        "name": "zlib",
        "version>=": "1.2.11#7"
    }
] }

注意

值 1.2.11#7 表示版本 1.2.11、埠版本 7。

由於基準引進的最小版本條件約束 zlib ， 1.2.11#9 且較高版本確實滿足的最低版本條件約束 1.2.11#7，因此允許 vcpkg 升級它。

基準也是一次升級多個版本的便利機制，例如，如果您想要相依於多個 boost 連結庫，則設定一次比在每個套件上宣告版本條件約束更方便 baseline 。

但是，如果您想要釘選比基準還舊的版本，該怎麼辦？

`overrides`

由於基準會為所有套件建立版本底板，而且當它們低於基準時，會升級明確條件約束，因此我們需要另一個機制來降級超過基準的版本。

vcpkg 針對該案例提供的機制為 overrides。在封裝上宣告覆寫時，vcpkg 會忽略指令清單中直接宣告或從可轉移相依性宣告的所有其他版本條件約束。簡言之， overrides 將會強制 vcpkg 使用宣告的確切版本句號。

讓我們再次修改我們的範例，這次會強制 vcpkg 使用版本的 6.0.0fmt。

{
    "name": "versions-test",
    "version": "1.0.0",
    "dependencies": [
        {
            "name": "fmt",
            "version>=": "7.1.3#1"
        },
        {
            "name": "zlib",
            "version>=": "1.2.11#7"
        }
    ],
    "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc",
    "overrides": [
        {
            "name": "fmt",
            "version": "6.0.0"
        }
    ]
}

重建我們的專案：

PS D:\versions-test\build> rm ./CMakeCache.txt
PS D:\versions-test\build> rm -r ./vcpkg_installed
PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
-- Running vcpkg install
Detecting compiler hash for triplet x86-windows...
The following packages will be built and installed:
    fmt[core]:x86-windows -> 6.0.0 -- D:\vcpkg\buildtrees\versioning\versions\fmt\d99b6a35e1406ba6b6e09d719bebd086f83ed5f3
    zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
...
PS D:\versions-test\build> cmake --build .
[2/2] Linking CXX executable main.exe

然後執行它！

PS D:\versions-test\build> .\main.exe
fmt version is 60000
zlib version is 1.2.11

請注意， fmt 現在 6.0.0 的版本就像我們想要的一樣。

版本和自定義埠

最後一件事是重迭埠如何與版本控制解析度互動。答案是：他們不。

進一步詳細說明，當您提供埠的重疊時，vcpkg 一律會使用重疊埠，而不需考慮其所包含的版本。原因有兩倍：（1）它與完全遮罩現有埠的重疊埠的現有行為一致，而重迭埠則不會（且預計不會）提供足夠的資訊來提供 vcpkg 的版本設定功能。

如果您想要有彈性的埠自定義以及版本設定，您應該考慮建立自己的自定義登錄。

進一步閱讀

如果您想要深入瞭解版本控制運作方式的詳細數據，建議您閱讀版本設定參考和版本控制概念。

共用方式為