次の方法で共有

チュートリアル: vcpkg を使用してライブラリをパッケージ化する

  • [アーティクル]

このチュートリアルでは、カスタム オーバーレイを使用して vcpkg 用のライブラリをパッケージ化する方法について説明します。 先に進む前に、 Install を読み、CMake チュートリアルでパッケージを使用することをお勧めします。

前提条件

  • ターミナル
  • C++ コンパイラ
  • CMake
  • Git

Note

Windows では、このチュートリアルでは C++ 開発用のコンパイラとして Visual Studio の MSVC を使用します。

1 - vcpkg を設定する

  1. リポジトリの複製

    最初の手順では、GitHub から vcpkg リポジトリを複製します。 リポジトリには、vcpkg 実行可能ファイルを取得するスクリプトと、vcpkg コミュニティによって管理されるキュレーションされたオープンソース ライブラリのレジストリが含まれています。 これを行うには、次を実行します。

    git clone https://github.com/microsoft/vcpkg.git

    vcpkg キュレーション レジストリは、2,000 を超えるオープンソース ライブラリのセットです。 これらのライブラリは、vcpkg の継続的インテグレーション パイプラインによって検証され、連携しています。 vcpkg リポジトリにはこれらのライブラリのソース コードは含まれていませんが、レシピとメタデータを保持して、それらをビルドしてシステムにインストールします。

  2. ブートストラップ スクリプトを実行する

    vcpkg リポジトリを複製したら、 vcpkg ディレクトリに移動し、ブートストラップ スクリプトを実行します。

    cd vcpkg && bootstrap-vcpkg.bat

    cd vcpkg; .\bootstrap-vcpkg.bat

    cd vcpkg && ./bootstrap-vcpkg.sh

    ブートストラップ スクリプトは前提条件チェックを実行し、vcpkg 実行可能ファイルをダウンロードします。

    これで完了です。 vcpkg がセットアップされ、使用する準備が整いました。

2 - VCPKG_ROOT 環境変数を構成する

VCPKG_ROOT環境変数を設定するには、次のコマンドを実行します。

export VCPKG_ROOT=/path/to/vcpkg
export PATH=$VCPKG_ROOT:$PATH

Note

export コマンドを使用して環境変数を設定すると、現在のシェル セッションにのみ影響します。 この変更をセッション間で永続的にするには、シェルのプロファイル スクリプト (~/.bashrcや~/.zshrcなど) に export コマンドを追加します。

set "VCPKG_ROOT=C:\path\to\vcpkg"
set PATH=%VCPKG_ROOT%;%PATH%

Note

この方法で環境変数を設定すると、現在のターミナル セッションにのみ影響します。 これらの変更をすべてのセッションで永続的にするには、[Windows システム環境変数] パネルで設定します。

$env:VCPKG_ROOT="C:\path\to\vcpkg"
$env:PATH="$env:VCPKG_ROOT;$env:PATH"

Note

この方法で環境変数を設定すると、現在のターミナル セッションにのみ影響します。 これらの変更をすべてのセッションで永続的にするには、[Windows システム環境変数] パネルで設定します。

VCPKG_ROOT設定すると、vcpkg インスタンスが配置されている場所が vcpkg に通知されます。 これを PATH に追加すると、シェルから直接 vcpkg コマンドを実行できます。

3 - カスタム オーバーレイを設定する

  1. Install で作成したHello World プロジェクトの横にcustom-overlayという名前の新しいディレクトリを作成し、CMake チュートリアルでパッケージを使用します。
  2. custom-overlayディレクトリ内に、vcpkg-sample-libraryという名前のフォルダーを作成します。

4 - ポート ファイルを設定する

まず、次の内容を含むcustom-overlay\vcpkg-sample-library フォルダー内にvcpkg.json ファイルを作成します。

{
  "name": "vcpkg-sample-library",
  "version": "1.0.2",
  "homepage": "https://github.com/microsoft/vcpkg-docs/tree/cmake-sample-lib",
  "description": "A sample C++ library designed to serve as a foundational example for a tutorial on packaging libraries with vcpkg.",
  "license": "MIT",
  "dependencies": [
    {
      "name" : "vcpkg-cmake",
      "host" : true
    },
    {
      "name" : "vcpkg-cmake-config",
      "host" : true
    },
    "fmt"
  ]
}

vcpkg.json ファイルは、C++ ライブラリのメタデータと依存関係を定義するマニフェストとして機能し、パッケージのビルド、インストール、管理に必要な情報を vcpkg に提供します。

  • name: ライブラリの名前を指定します。 これはパッケージ識別子として使用されます。
  • version: ライブラリのバージョン番号を示します。
  • homepage: プロジェクトのホームページ (多くの場合、そのリポジトリ) への URL。 より多くを知りたい、または貢献したい人に役立ちます。
  • description: ライブラリの動作を説明する簡単なテキスト。 これは、ドキュメントとユーザーを対象とします。
  • license: ライブラリを配布するライセンスを指定します。
  • dependencies: ライブラリに必要な依存関係の一覧を含む配列。
  • name: vcpkg-cmake: vcpkg ポートで一般的に使用される CMake 関数とマクロを提供する、 vcpkg-cmakeへの依存関係を指定します。
  • host: true: vcpkg-cmake がホストの依存関係であることを指定します。つまり、パッケージのビルドには必要ですが、使用する場合は必須ではありません。
  • name: vcpkg-cmake-config: CMake 構成スクリプトの使用に役立つ、 vcpkg-cmake-configへの依存関係を指定します。
  • fmt: fmt ライブラリに対する実行時の依存関係を指定します。 つまり、パッケージのビルドと使用の両方に fmt が必要です。

vcpkg.jsonの詳細については、manifestsに関する次のドキュメントを参照してください。

次に、次の内容を使用して、custom-overlay\vcpkg-sample-library ディレクトリ内にusage ファイルを作成します。

vcpkg-sample-library provides CMake targets:

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(main PRIVATE my_sample_lib::my_sample_lib)

ポートの使用に関するドキュメントを提供すると、ユーザーはプロジェクトでそれらを簡単に採用できます。 ビルド システムとの統合に必要な最小限の手順を説明する usage ファイルをポートのディレクトリ (ports/<port name>/usage) 内に提供することを強くお勧めします。 正しい使用方法を判断するには、アップストリームのガイダンスに従うことをお勧めします。 アップストリームが使用状況情報を提供しない場合は、ビルド システムを調べ、エクスポートされたターゲットを見つける必要があります。

詳細なガイダンスについては、 使用状況ファイルの処理に関するページを参照してください。

最後に、次の内容を使用して、custom-overlay\vcpkg-sample-library ディレクトリ内にportfile.cmake ファイルを作成します。

vcpkg_check_linkage(ONLY_STATIC_LIBRARY)

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO Microsoft/vcpkg-docs
    REF "${VERSION}"
    SHA512 0  # This is a temporary value. We will modify this value in the next section.
    HEAD_REF cmake-sample-lib
)


vcpkg_cmake_configure(
    SOURCE_PATH "${SOURCE_PATH}"
)

vcpkg_cmake_install()

vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib")

file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")

file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage" COPYONLY)

この portfile では、vcpkg を使用して GitHub から特定の C++ ライブラリをダウンロード、ビルド、インストール、パッケージ化する方法を定義します。

  • vcpkg_check_linkage(ONLY_STATIC_LIBRARY): このパッケージに対して静的リンクのみがサポートされるように指定します。
  • vcpkg_from_github: GitHub リポジトリからソース コードをダウンロードする関数を開始します。
    • OUT_SOURCE_PATH SOURCE_PATH: ソース コードを抽出するディレクトリを設定します。
    • REPO Microsoft/vcpkg-docs: ソース コードを含む GitHub リポジトリ。
    • REF "${VERSION}": ダウンロードするソース コードのバージョン。
    • SHA512 0: 整合性検証用のソース コードの SHA-512 ハッシュのプレースホルダー。
    • HEAD_REF main: リポジトリの既定のブランチを指定します。
  • vcpkg_cmake_configure: CMake を使用してプロジェクトを構成し、ビルドを設定します。
    • SOURCE_PATH "${SOURCE_PATH}": 先ほどダウンロードしたソース コードへのパス。
  • vcpkg_cmake_install(): CMake を使用してパッケージをビルドしてインストールします。
  • vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib"): vcpkg と互換性のある CMake パッケージ構成ファイルを修正します。
  • file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): 重複を防ぐために、デバッグ インストールからインクルード ディレクトリを削除します。
  • file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION ...): LICENSE ファイルをパッケージの共有ディレクトリにインストールし、著作権に名前を変更します。
  • configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" ...): 使用命令ファイルをパッケージの共有ディレクトリにコピーします。

詳細については、 maintainer ガイドを参照してください。

5 - SHA512 の更新 portfile.cmake

実行 (Run):

vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay

長いエラー メッセージが表示されます。 次が見つかるまで出力をスキャンします。

Expected hash: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Actual hash: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

"Actual hash" 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417をコピーし、portfile.cmakeのSHA512値をその値に置き換えます。

install コマンドを再実行します。

vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay

Computing installation plan...
The following packages will be built and installed:
    vcpkg-sample-library:x64-windows -> 1.0.2 -- C:\Users\dev\demo\custom-overlay\vcpkg-sample-library
Detecting compiler hash for triplet x64-windows...
Restored 0 package(s) from C:\Users\dev\AppData\Local\vcpkg\archives in 174 us. Use --debug to see more details.
Installing 1/1 vcpkg-sample-library:x64-windows...
Building vcpkg-sample-library:x64-windows...
-- Installing port from location: C:\Users\dev\demo\custom-overlay\vcpkg-sample-library
-- Note: vcpkg-sample-library only supports static library linkage. Building static library.
-- Using cached Microsoft-vcpkg-docs-1.0.2.tar.gz.
-- Cleaning sources at C:/Users/dev/demo/vcpkg/buildtrees/vcpkg-sample-library/src/1.0.2-2aff836404.clean. Use --editable to skip cleaning for the packages you specify.
-- Extracting source C:/Users/dev/demo/vcpkg/downloads/Microsoft-vcpkg-docs-1.0.2.tar.gz
-- Using source at C:/Users/dev/demo/vcpkg/buildtrees/vcpkg-sample-library/src/1.0.2-2aff836404.clean
-- Configuring x64-windows
-- Building x64-windows-dbg
-- Building x64-windows-rel
-- Installing: C:/Users/dev/demo/vcpkg/packages/vcpkg-sample-library_x64-windows/share/vcpkg-sample-library/copyright
-- Performing post-build validation
Stored binaries in 1 destinations in 94 ms.
Elapsed time to handle vcpkg-sample-library:x64-windows: 6.1 s
Total install time: 6.1 s
vcpkg-sample-library provides CMake targets:

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(main PRIVATE my_sample_lib::my_sample_lib)

6 - ポートビルドを確認する

ライブラリのビルドとリンクを正しく確認するには、install パッケージのチュートリアルで作成したhelloworld プロジェクトに新しい依存関係を追加。 プロジェクトのマニフェスト ファイルと構成ファイルに次の変更を加えます。

helloworld/vcpkg.jsonを変更して、vcpkg-sample-libraryへの依存関係を追加します。

{
    "dependencies": [
        "fmt",
        "vcpkg-sample-library"
    ]
}

helloworld/vcpkg-configuration.jsonを変更して、新しいポートを含むoverlay-ports フォルダーを含めます。

{
  "default-registry": {
    "kind": "git",
    "baseline": "45f6e57d3e10ad96b7db206cf7888f736ba5aa61",
    "repository": "https://github.com/microsoft/vcpkg"
  },
  "registries": [
    {
      "kind": "artifact",
      "location": "https://github.com/microsoft/vcpkg-ce-catalog/archive/refs/heads/main.zip",
      "name": "microsoft"
    }
  ],
  "overlay-ports": [
    "../custom-overlay"
  ]
}

次に、新しい依存関係を使用するように helloworld/CMakeLists.txt と helloworld/main.cpp を変更します。

次の内容で helloworld/CMakeLists.txt を変更します。

cmake_minimum_required(VERSION 3.10)

project(HelloWorld)

find_package(fmt CONFIG REQUIRED)
find_package(my_sample_lib CONFIG REQUIRED)  # Add this line

add_executable(HelloWorld helloworld.cpp)

target_link_libraries(HelloWorld PRIVATE fmt::fmt)
target_link_libraries(HelloWorld PRIVATE my_sample_lib::my_sample_lib)  # Add this line

次の内容で main.cpp を変更します。

#include "my_sample_lib.h"  // Replace #include <fmt/core.h> with "my_sample_lib.h"

int main()
{
    greet("vcpkg!");  // Replace fmt::print("Hello World!\n) with this line
    return 0;
}

アプリケーションを構成、ビルド、実行します。

  1. CMake を使用してビルドを構成します。
cmake --preset=default
  1. プロジェクトをビルドします。
cmake --build build
  1. アプリケーションを実行します。
./build/HelloWorld

プロジェクトの実行可能ファイルへのパスは、 ./build/Debug/HelloWorld.exeなど、異なる場合があります。

Hello vcpkg!

次のステップ

vcpkg-sample-libraryがポートとしてパッケージ化されたので、次の手順では vcpkg キュレーション レジストリに追加します。 vcpkg レジストリへのポートの追加を参照してください。

詳細については、以下を参照してください: