CMake プロジェクトでの vcpkg

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

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

CMake は、プロジェクトを初めて構成するときに、実行可能なツールチェーン (コンパイラ、リンカーなど) を見つけるために内部検索ルーチンを実行します。この検索は、関数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_library()およびfind_path()関数をfind_package()介して使用できるようにします。

マニフェストモードでは、上記に加えて、ツールチェーンはマニフェストファイル (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 関数を使用して vcpkg からライブラリを検索できます。 find_package()find_path()find_library()

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 では、ライブラリを検索するための CMake のネイティブメカニズムがサポートされています。 find_package()find_library()find_path() 特定の 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

ツールチェーンの設定 (File > Settings Windows および Linux、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 のライブラリ設定を変更するには、(ツールチェーンを共有できる) カスタムトリプレットファイルを作成する必要があります**

設定リファレンス

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

`VCPKG_TARGET_TRIPLET`

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

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

`VCPKG_HOST_TRIPLET`

この変数は、インストールするトリプレットホストの依存関係を制御します。

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

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

`VCPKG_INSTALLED_DIR`

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

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

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

`VCPKG_MANIFEST_MODE`

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

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

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

`VCPKG_MANIFEST_DIR`

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

既定値は存在する ${CMAKE_SOURCE_DIR} 場合 ${CMAKE_SOURCE_DIR}/vcpkg.json です。

`VCPKG_MANIFEST_INSTALL`

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

既定値は ON if VCPKG_MANIFEST_MODE です 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_FIND_ROOT_PATH、CMAKE_LIBRARY_PATHツールチェーン/システムライブラリ/パッケージの後に vcpkg ライブラリ/パッケージが見つかるようにします。

既定値は OFF です。

`VCPKG_FEATURE_FLAGS`

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

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

`VCPKG_TRACE_FIND_PACKAGE`

に ON設定すると、すべての呼び出しを印刷します find_package。入れ子になった呼び出し (via 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`