CMake プロジェクトでの vcpkg

[アーティクル]
10/15/2024

vcpkg は CMake とのシームレスな統合を提供し、インストールされているパッケージをプロジェクトで自動的に使用できるようにします。 vcpkg が統合されるメカニズムは、CMake ツールチェーンファイルを提供することです。

CMake は、プロジェクトを初めて構成するときに、実行可能な toolchain (コンパイラ、リンカーなど) を見つけるために内部検索ルーチンを実行します。この検索は、CMakeLists.txtのproject()関数内で実行されます。

ツールチェーンの選択プロセスをカスタマイズするために、CMake では、ツールチェーンファイルと呼ばれるカスタム CMake 言語スクリプトの使用がサポートされています。ツールチェーンファイルは、 CMAKE_TOOLCHAIN_FILE 変数を設定することによって指定されます。 CMake は、指定されたツールチェーンスクリプトの内容を評価し、それに応じて変数定義、必要なビルドツールへのパス、およびその他のビルドパラメーター (クロスコンパイルフラグなど) を設定します。

vcpkg ツールチェーン (<vcpkg-root>/scripts/buildsystems/vcpkg.cmake) を使用するようにCMAKE_TOOLCHAIN_FILEを設定すると、vcpkg はツールチェーンファイルメカニズムを利用してコードを挿入し、組み込みの CMake 関数と透過的に統合します。

ツールチェーンファイルを使用しても、 VCPKG_CHAINLOAD_TOOLCHAIN_FILE トリプレット変数を使用して独自のツールセットを構成できます。

vcpkg の統合は、使用している操作モードによって動作が異なります。

クラスモードでは vcpkg は CMake 検索パスを適切に設定し、インストールされているパッケージをfind_package()、find_library()、およびfind_path()関数を介して使用できるようにします。

manifest モードでは上記に加えて、ツールチェーンはマニフェストファイル (vcpkg.json ファイル) を検出し、vcpkg install実行してプロジェクトの依存関係を自動的に取得します。

ツールチェーンファイルは project() 呼び出し中に評価されるため、vcpkg 設定を変更するすべての CMake レベルの変数は、 project()の最初の呼び出しの前に設定する必要があります。また、 ABI ハッシュ変更が発生する vcpkg 設定を変更する場合は、CMake プロジェクトを再構成する必要があります。

CMake を使用した完全に機能する例については、「パッケージのインストールと使用の例: sqlite 」を参照してください。

`CMAKE_TOOLCHAIN_FILE`

Note

CMakeList.txt ファイルでCMAKE_TOOLCHAIN_FILEを設定する場合は、project()を呼び出す前に変数が設定されていることを確認します。

(CMake 設定 CMAKE_TOOLCHAIN_FILEを使用して) vcpkg ツールチェーンファイルを使用するように構成されたプロジェクトでは、標準の CMake 関数 ( find_package()、 find_path()、 find_library()) を使用して vcpkg からライブラリを検索できます。

CMake プリセットを使用してツールチェーンファイルを指定することをお勧めします。たとえば、環境変数 VCPKG_ROOTを定義した場合は、次の CMakePresets.json を使用して、構成行に --preset debug を渡すことができます。

{
  "version": 2,

  "configurePresets": [
    {
      "name": "debug",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

cmake -B build -S /my/project --preset debug

現在のマシンに固有の vcpkg の絶対パスを使用する必要がある場合は、 CMakeUserPresets.json を使用して、 .gitignore ファイルに追加できます。

{
  "version": 2,

  "configurePresets": [
    {
      "name": "debug",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

3.19 より前の CMake バージョンでは、構成コマンドラインでツールチェーンファイルを渡す必要があります。

cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake

ライブラリの使用

vcpkg では、 find_package()、 find_library()、 find_path()などのライブラリを検索するための CMake のネイティブメカニズムがサポートされています。特定の CMake サポートを使用してライブラリをインストールすると、vcpkg はライブラリの使用方法に関する使用状況情報を表示します。

The package zlib is compatible with built-in CMake targets:

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

vcpkg は、インクルードパスまたはリンクパスをプロジェクトに自動的に追加しません。ヘッダーのみのライブラリを使用するには、すべてのプラットフォームで正しく動作する find_path() を使用できます。

# To find and use catch2
find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
target_include_directories(main PRIVATE ${CATCH_INCLUDE_DIR})

IDE の統合

Visual Studio /Visual Studio Code

Visual Studio と Visual Studio Code の両方で CMake プリセットを使用することをお勧めします。

詳細については、「 Visual Studio の CMake プリセットを使用した構成とビルド Visual Studio Code の CMake プリセットを使用した構成とビルド。

CLion

ツールチェーンの設定 (Windows と Linux でFile > Settings 、macOS で CLion > Preferences ) を開き、CMake 設定 (Build, Execution, Deployment > CMake) に移動します。 CMake optionsで、次の行を追加します。

-DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake

この行は、各プロファイルに個別に追加する必要があります。

複数のツールチェーンファイルの使用

vcpkg のツールチェーンファイルを別のツールチェーンファイルと組み合わせるには、CMake キャッシュ変数を次 VCPKG_CHAINLOAD_TOOLCHAIN_FILE設定します。

cmake ../my/project \
   -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \
   -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/toolchain.cmake

または、プライマリツールチェーンファイルの末尾に vcpkg ツールチェーンを含めることもできます。

# MyToolchain.cmake
set(CMAKE_CXX_COMPILER ...)
set(VCPKG_TARGET_TRIPLET x64-my-custom-windows-triplet)
include(/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake)

Note

vcpkg は、ライブラリのビルド中に、コンパイラやコンパイルフラグなどのツールチェーンの設定を自動的に適用しません。 vcpkg のライブラリ設定を変更するには、 custom triplet ファイルを作成する必要があります (ツールチェーンを共有できます)**

設定リファレンス

vcpkg に影響を与える変数はすべて、CMakePresets.jsonの"cacheVariables" マップ、コマンドライン、set() ステートメントなど、最初のproject() ディレクティブの前に定義する必要があります。

`VCPKG_TARGET_TRIPLET`

この設定により、 triplet が制御されます vcpkg はライブラリをインストールして使用します。

未設定の場合、vcpkg は、現在のコンパイラ設定を指定すると、適切な既定のトリプレットを自動的に検出します。この CMake 変数を変更する場合は、キャッシュを削除して再構成する必要があります。

`VCPKG_HOST_TRIPLET`

この変数は、 triplet ホストの依存関係をインストールする対象を制御します。

設定を解除すると、vcpkg は適切なネイティブトリプレット (x64-windows、x64-osx、x64-linux) を自動的に検出します。

「ホストの依存関係も参照してください。

`VCPKG_INSTALLED_DIR`

この変数は、ライブラリをインストールして使用する場所を設定します。

マニフェストモードでは、既定値は ${CMAKE_BINARY_DIR}/vcpkg_installed です。

クラシックモードでは、既定値は ${VCPKG_ROOT}/installed です。

`VCPKG_MANIFEST_MODE`

この変数は、vcpkg をマニフェストモードまたはクラシックモードで強制的に動作させます。

既定値は、VCPKG_MANIFEST_DIRが空でない場合、または${CMAKE_SOURCE_DIR}/vcpkg.jsonが存在する場合にONします。

vcpkg.jsonが検出されている間にマニフェストモードを無効にするには、これを OFF に設定します。

`VCPKG_MANIFEST_DIR`

この変数は、 vcpkg.json マニフェストを含む代替フォルダーを指定します。

既定では、${CMAKE_SOURCE_DIR}/vcpkg.jsonが存在する場合は${CMAKE_SOURCE_DIR}されます。

`VCPKG_MANIFEST_INSTALL`

この変数は、構成手順中に vcpkg を自動的に実行して依存関係をインストールするかどうかを制御します。

VCPKG_MANIFEST_MODEがONの場合、既定値は ON です。

`VCPKG_BOOTSTRAP_OPTIONS`

この変数は、 ./bootstrap-vcpkgに渡す追加のコマンドパラメーターに設定できます。

マニフェストモードでは、実行可能ファイルが存在しない場合、vcpkg は自動的にブートストラップされます。

`VCPKG_OVERLAY_TRIPLETS`

この変数は、コマンドラインで渡されるパスの一覧に設定できます。 --overlay-triplets=...

`VCPKG_OVERLAY_PORTS`

この変数は、コマンドラインで渡されるパスの一覧に設定できます。 --overlay-ports=...

`VCPKG_MANIFEST_FEATURES`

この変数は、マニフェストからインストールするときにアクティブにする機能の一覧に設定できます。

たとえば、プロジェクトで機能を使用して、追加の依存関係を使用してビルドを制御し、テストまたはサンプルを有効にすることができます。

{
  "name": "mylibrary",
  "version": "1.0",
  "dependencies": [ "curl" ],
  "features": {
    "samples": {
      "description": "Build Samples",
      "dependencies": [ "fltk" ]
    },
    "tests": {
      "description": "Build Tests",
      "dependencies": [ "gtest" ]
    }
  }
}

この設定は、 CMake プリセットで直接制御できます他の設定に基づいて "cacheVariables" または間接的に制御できます。

# CMakeLists.txt

option(BUILD_TESTING "Build tests" OFF)
if(BUILD_TESTING)
  list(APPEND VCPKG_MANIFEST_FEATURES "tests")
endif()

option(BUILD_SAMPLES "Build samples" OFF)
if(BUILD_SAMPLES)
  list(APPEND VCPKG_MANIFEST_FEATURES "samples")
endif()

project(myapp)

# ...

`VCPKG_MANIFEST_NO_DEFAULT_FEATURES`

この変数は、 VCPKG_MANIFEST_FEATURESに記載されているものに加えて、既定の機能のアクティブ化を制御します。 ONに設定すると、既定の機能は自動的にアクティブ化されません。

既定値は OFF です。

`VCPKG_INSTALL_OPTIONS`

この変数は、自動インストール時に vcpkg ツールに渡す追加のコマンドラインパラメーターの一覧に設定できます。

`VCPKG_PREFER_SYSTEM_LIBS`

警告

この機能は廃止されました。代わりに空のオーバーレイポートを使用してください。

この変数は、vcpkg のパスを CMAKE_PREFIX_PATH、 CMAKE_LIBRARY_PATH 、および CMAKE_FIND_ROOT_PATH に付加する代わりに vcpkg を追加するかどうかを制御します。これにより、vcpkg ライブラリ/パッケージはツールチェーン/システムライブラリ/パッケージの後に見つかります。

既定値は OFF です。

`VCPKG_FEATURE_FLAGS`

この変数は、自動インストール時に vcpkg ツールに渡す機能フラグの一覧に設定して、試験的な動作にオプトインできます。

詳細については、 --feature-flags= コマンドラインオプションを参照してください。

`VCPKG_TRACE_FIND_PACKAGE`

ONに設定すると、find_packageのすべての呼び出しを印刷します。入れ子になった呼び出し ( find_dependency経由など) は、入れ子になった深さに従ってインデントされます。

次の方法で共有

CMake プロジェクトでの vcpkg

`CMAKE_TOOLCHAIN_FILE`

ライブラリの使用

IDE の統合

Visual Studio /Visual Studio Code

CLion

複数のツールチェーンファイルの使用

設定リファレンス

`VCPKG_TARGET_TRIPLET`

`VCPKG_HOST_TRIPLET`

`VCPKG_INSTALLED_DIR`

`VCPKG_MANIFEST_MODE`

`VCPKG_MANIFEST_DIR`

`VCPKG_MANIFEST_INSTALL`

`VCPKG_BOOTSTRAP_OPTIONS`

`VCPKG_OVERLAY_TRIPLETS`

`VCPKG_OVERLAY_PORTS`

`VCPKG_MANIFEST_FEATURES`

`VCPKG_MANIFEST_NO_DEFAULT_FEATURES`

`VCPKG_INSTALL_OPTIONS`

`VCPKG_PREFER_SYSTEM_LIBS`

`VCPKG_FEATURE_FLAGS`

`VCPKG_TRACE_FIND_PACKAGE`

その他のリソース

次の方法で共有

CMake プロジェクトでの vcpkg

CMAKE_TOOLCHAIN_FILE

ライブラリの使用

IDE の統合

Visual Studio /Visual Studio Code

CLion

複数のツールチェーン ファイルの使用

設定リファレンス

VCPKG_TARGET_TRIPLET

VCPKG_HOST_TRIPLET

VCPKG_INSTALLED_DIR

VCPKG_MANIFEST_MODE

VCPKG_MANIFEST_DIR

VCPKG_MANIFEST_INSTALL

VCPKG_BOOTSTRAP_OPTIONS

VCPKG_OVERLAY_TRIPLETS

VCPKG_OVERLAY_PORTS

VCPKG_MANIFEST_FEATURES

VCPKG_MANIFEST_NO_DEFAULT_FEATURES

VCPKG_INSTALL_OPTIONS

VCPKG_PREFER_SYSTEM_LIBS

VCPKG_FEATURE_FLAGS

VCPKG_TRACE_FIND_PACKAGE

その他のリソース

`CMAKE_TOOLCHAIN_FILE`

複数のツールチェーンファイルの使用

`VCPKG_TARGET_TRIPLET`

`VCPKG_HOST_TRIPLET`

`VCPKG_INSTALLED_DIR`

`VCPKG_MANIFEST_MODE`

`VCPKG_MANIFEST_DIR`

`VCPKG_MANIFEST_INSTALL`

`VCPKG_BOOTSTRAP_OPTIONS`

`VCPKG_OVERLAY_TRIPLETS`

`VCPKG_OVERLAY_PORTS`

`VCPKG_MANIFEST_FEATURES`

`VCPKG_MANIFEST_NO_DEFAULT_FEATURES`

`VCPKG_INSTALL_OPTIONS`

`VCPKG_PREFER_SYSTEM_LIBS`

`VCPKG_FEATURE_FLAGS`

`VCPKG_TRACE_FIND_PACKAGE`