バージョン管理の概要

[アーティクル]
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

ports/でポートファイルを使用する代わりに、vcpkg は buildtrees/versioning/versions/の各バージョンのファイルをチェックアウトしています。 ports/ 内のファイルは、クラシックモードで vcpkg を実行するときに引き続き使用されます。

手記

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" 宣言の一部としてのみ許可されます。この例では、fmtのバージョン 7.1.3#1 に明示的な制約を設定しています。

推移的な依存関係に新しいバージョンが必要な場合、vcpkg はこの制約をアップグレードできます。たとえば、zlibfmt バージョンへの依存関係を宣言 7.1.4 場合、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を表します。

ベースラインでは、1.2.11#9 で zlib の最小バージョン制約が導入され、上位のバージョンが 1.2.11#7の最小バージョン制約を満たしているため、vcpkg はそれをアップグレードできます。

ベースラインは、複数のバージョンを一度にアップグレードする便利なメカニズムでもあります。たとえば、複数の boost ライブラリに依存する場合は、各パッケージでバージョン制約を宣言するよりも、baseline を 1 回設定する方が便利です。

ただし、ベースラインより古いバージョンをピン留めする場合はどうでしょうか。

`overrides`

ベースラインは、すべてのパッケージのバージョンフロアを確立し、明示的な制約がベースラインより低い場合にアップグレードされるため、ベースラインを超えてバージョンをダウングレードする別のメカニズムが必要です。

vcpkg がそのシナリオに対して提供するメカニズムは overridesです。パッケージでオーバーライドが宣言されている場合、vcpkg は、マニフェストで直接宣言された、または推移的な依存関係から他のすべてのバージョン制約を無視します。つまり、overrides は vcpkg に、宣言された正確なバージョンである period を使用するように強制します。

この例をもう一度変更してみましょう。今度は、vcpkg に fmtのバージョン 6.0.0 を強制的に使用させます。

{
    "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 は常にオーバーレイポートを使用し、それに含まれているバージョンを気にしません。その理由は 2 つあります。(1) 既存のポートを完全にマスクするオーバーレイポートの既存の動作と一致し、(2) オーバーレイポートは vcpkg のバージョン管理機能に電力を供給するのに十分な情報を提供しません (また、想定されていません)。

バージョン管理と共に柔軟なポートカスタマイズを行う場合は、独自のカスタムレジストリをすることを検討する必要があります。

詳細については、次を参照してください。

バージョン管理のしくみの詳細については、バージョン管理のリファレンスとバージョン管理の概念を参照することをお勧めします。

次の方法で共有

バージョン管理の概要

マニフェストでのバージョンの使用

マニフェストの変更

`version`

`version>=`

`builtin-baseline`

`overrides`

バージョンとカスタムポート

詳細については、次を参照してください。

その他のリソース

次の方法で共有

バージョン管理の概要

マニフェストでのバージョンの使用

マニフェストの変更

version

version>=

builtin-baseline

overrides

バージョンとカスタム ポート

詳細については、次を参照してください。

その他のリソース

`version`

`version>=`

`builtin-baseline`

`overrides`

バージョンとカスタムポート