vcpkgの取得と初期ビルド

まず、vcpkgのリポジトリをクローンし、実行ファイルをビルドします。環境の再現性を高めるため、特定のリリースタグにチェックアウトすることを推奨します。

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
git checkout 2025.03.19

PowerShellを開き、ブートストラップスクリプトを実行してvcpkg本体をコンパイルします。正常に完了すると、カレントディレクトリに vcpkg.exe が生成されます。

.\bootstrap-vcpkg.bat

次に、ユーザーレベルでのグローバル統合を実行します。これにより、Visual StudioやMSBuildがvcpkgでインストールしたライブラリを自動的に認識し、インクルードパスやリンカー設定を個別に行う必要がなくなります。

.\vcpkg.exe integrate install

パッケージの検索とインストール

利用可能なパッケージは search コマンドで探します。ここではBoostライブラリを例にします。

.\vcpkg.exe search boost

検索結果の左端がパッケージ名（ID）、右端が説明です。目的のライブラリを確認したら、そのIDを指定してインストールを実行します。

.\vcpkg.exe install boost

開発環境への統合と動作検証

CMakeプロジェクトでの利用

CMakeLists.txtの配置場所（単一ディレクトリか、サブディレクトリに分割するか）によって設定手法が異なります。Visual StudioでCMakeプロジェクトを開く際は、「常にCMakeプリセットを使用する」オプションを有効にしておくと subsequent なプロジェクトオープンがスムーズになります。

単一ディレクトリ構成

プロジェクトのルートディレクトリに CMakeLists.txt とソースコードを配置する場合の設定です。

cmake_minimum_required(VERSION 3.15)
project(VcpkgDemoApp LANGUAGES CXX)

# vcpkgのルートディレクトリを指定
set(VCPKG_ROOT "C:/tools/vcpkg" CACHE PATH "vcpkg root directory")
set(CMAKE_TOOLCHAIN_FILE "${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake" 
    CACHE STRING "Vcpkg toolchain file")

find_package(Boost REQUIRED COMPONENTS algorithm)

add_executable(${PROJECT_NAME} main.cpp)
target_link_libraries(${PROJECT_NAME} PRIVATE Boost::algorithm)
set_target_properties(${PROJECT_NAME} PROPERTIES CXX_STANDARD 17)

複数ディレクトリ構成

ソースコードを src などのサブディレクトリに分離する場合、ルートとサブディレクトリでCMakeLists.txtを分割します。

ルートディレクトリの CMakeLists.txt:

cmake_minimum_required(VERSION 3.15)
project(VcpkgDemoApp LANGUAGES CXX)

set(VCPKG_ROOT "C:/tools/vcpkg" CACHE PATH "vcpkg root directory")
set(CMAKE_TOOLCHAIN_FILE "${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake" 
    CACHE STRING "Vcpkg toolchain file")

add_subdirectory(src)

src/CMakeLists.txt:

find_package(Boost REQUIRED COMPONENTS algorithm)

add_executable(${PROJECT_NAME} main.cpp)
target_link_libraries(${PROJECT_NAME} PRIVATE Boost::algorithm)
set_target_properties(${PROJECT_NAME} PROPERTIES CXX_STANDARD 17)

検証用ソースコード (main.cpp):

#include <iostream>
#include <string>
#include <boost/algorithm/string.hpp>
#include <boost/version.hpp>

int main() {
    std::string target_str = "vcpkg package manager";
    std::cout << "Original string: " << target_str << std::endl;

    boost::algorithm::to_upper(target_str);
    
    std::cout << "Modified string: " << target_str << std::endl;
    std::cout << "Current Boost version: " << BOOST_LIB_VERSION << std::endl;

    return 0;
}

Visual Studioネイティブプロジェクトでの利用

通常のコンソールアプリケーションとしてプロジェクトを作成した場合、前述の integrate install が適用されていれば、追加のリンカー設定やインクルードパスの指定は不要です。直接ヘッダーをインクルードしてビルドできます。

#include <iostream>
#include <string>
#include <boost/algorithm/string.hpp>
#include <boost/version.hpp>

int main() {
    std::string payload = "visual studio integration";
    std::cout << "Before: " << payload << "\n";

    boost::algorithm::to_upper(payload);
    
    std::cout << "After: " << payload << "\n";
    std::cout << "Boost: " << BOOST_LIB_VERSION << "\n";
    
    return 0;
}

よくあるビルドエラーと対処法

Cmakeの展開失敗

vcpkgはビルドプロセス内でCMakeを自動的にダウンロード・展開しようとします。この際、以下のようなエラーが発生して展開に失敗する場合があります。

error: Expected cmake-3.30.1-windows-i386/bin/cmake.exe to exist after fetching

自動ダウンロードが機能しない場合は、手動で該当バージョン（またはそれ以降）のCMakeをインストールし、その bin ディレクトリをシステムの環境変数 PATH に追加することで回避できます。

コンソールのコード頁設定による干渉

コマンドプロンプト起動時に「Active code page: 65001」などの文字列が出力されていないか確認してください。vcpkgはビルドプロセスの標準出力をキャプチャしてログに書き込むため、AutoRunによる余分な出力が混入するとパースエラーやビルド失敗を引き起こします。

レジストリエディタを開き、以下の2つのパスを確認してください。

• HKEY_CURRENT_USER\SOFTWARE\Microsoft\Command Processor\AutoRun
• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Command Processor\AutoRun

これらの値に chcp 65001 が設定されている場合、chcp 65001 >nul に変更します。これにより、UTF-8への切り替えを維持しつつ、標準出力への不要な文字列出力を抑制できます。

ファイルパスの長さ制限

Qtの一部モジュールなど、ディレクトリ階層が深くなるライブラリをビルドする際、Windowsのパス長制限（MAX_PATH）に引っかかりエラーになることがあります。

CMake Error at ports/qt5-webengine/portfile.cmake:6 (message):
  terminating due to C:/tools/vcpkg/buildtrees/qt5-webengine being too long.

これを回避する最も効果的な方法は、subst コマンドを使用して仮想ドライブを割り当て、短いパスでビルドを実行することです。

subst Z: "C:\tools\vcpkg"
Z:
.\vcpkg.exe install qt5-webengine:x64-windows

ビルド時のメモリ不足

大規模なライブラリをビルドする際、vcpkgはデフォルトで利用可能な全CPUスレッドを使用して並列ビルドを行います。これにより物理メモリが枯渇し、ビルドが失敗する場合があります。

CMake Warning at scripts/cmake/vcpkg_execute_build_process.cmake:65 (message):
  Please ensure your system has sufficient memory.

環境変数 VCPKG_MAX_CONCURRENCY を設定することで、並列ビルドのスレッド数を制限し、メモリ使用量を抑えることができます。この設定は現在のコンソールセッションでのみ有効です。

set VCPKG_MAX_CONCURRENCY=4