C++ vcpkg 기초 완벽 가이드 | 설치·Manifest·Triplet·버전·커스텀 포트 [#53-3]

· 35분 읽기 · 수정 중급 실습
C++ vcpkg 기초 완벽 가이드 | 설치·Manifest·Triplet·버전·커스텀 포트 [#53-3]

이 글의 핵심

C++ vcpkg 패키지 매니저 기초 가이드입니다. 설치, Manifest 모드, Triplet 설정, 버전 관리, 커스텀 포트 작성 방법을 실전 예제로 다룹니다. "findpackage(fmt) failed — fmt를 못 찾아요" "로컬에서는 되는데 CI에서만 빌드가 실패해요" "팀원 A는 빌드되는데 B는 실패해요.

들어가며: “vcpkg가 뭔데 이렇게 복잡해요”

문제 시나리오

"find_package(fmt) failed — fmt를 못 찾아요"
"로컬에서는 되는데 CI에서만 빌드가 실패해요"
"팀원 A는 빌드되는데 B는 실패해요. vcpkg 버전이 다르대요"
"Boost 설치하는데 30분 넘게 걸려요"
"정적 링크로 배포해야 하는데 동적 링크만 되요"
"공식 레지스트리에 없는 라이브러리를 쓰고 싶어요"
"undefined reference 에러가 나는데 헤더는 잘 찾아요"
"vcpkg install 했는데 CMake가 여전히 못 찾아요"

이 글은 vcpkg 기초 완벽 가이드입니다. 설치부터 Manifest 모드·Triplet·버전 관리·커스텀 포트까지, 실전 예제와 함께 다룹니다. 실무 문제 시나리오, 자주 발생하는 에러, 베스트 프랙티스, 프로덕션 패턴까지 900줄 분량으로 정리합니다.

이 글을 읽으면:

  • vcpkg를 설치하고 CMake 프로젝트에 연동할 수 있습니다.
  • Manifest 모드로 프로젝트별 의존성을 관리할 수 있습니다.
  • Triplet으로 동적/정적 링크·플랫폼을 선택할 수 있습니다.
  • 버전 관리(builtin-baseline, vcpkg.lock)로 재현 가능한 빌드를 만들 수 있습니다.
  • 커스텀 포트(오버레이)로 사내 라이브러리를 통합할 수 있습니다.
  • 자주 발생하는 에러와 해결법을 알 수 있습니다.

요구 환경: vcpkg 2024.01+, CMake 3.20+, C++17 이상

실무 적용 경험: 이 글은 대규모 C++ 프로젝트에서 실제로 겪은 문제와 해결 과정을 바탕으로 작성되었습니다. 책이나 문서에서 다루지 않는 실전 함정과 디버깅 팁을 포함합니다.

목차

  1. 문제 시나리오 상세
  2. vcpkg 설치
  3. Manifest 모드 완벽 예제
  4. Triplet 기초
  5. 버전 관리
  6. 커스텀 포트(오버레이)
  7. 완전한 예제 프로젝트
  8. 자주 발생하는 에러와 해결법
  9. 베스트 프랙티스
  10. 프로덕션 패턴
  11. 구현 체크리스트

1. 문제 시나리오 상세

시나리오 1: 신규 프로젝트 — 라이브러리 설치 지옥

상황: C++ 프로젝트에 fmt, spdlog를 추가하려 함
문제: 수동으로 소스 다운로드·빌드·경로 설정 반복
결과: vcpkg Manifest 모드로 vcpkg.json에 의존성 선언 → 한 번에 해결

시나리오 2: CI에서만 빌드 실패

상황: 로컬에서는 빌드 성공, GitHub Actions에서 find_package 실패
문제: 로컬에 Classic 모드로 설치한 패키지가 CI에 없음
결과: Manifest 모드 + vcpkg.json + CMAKE_TOOLCHAIN_FILE 지정

시나리오 3: 팀원마다 vcpkg 상태가 다름

상황: 팀원 A는 fmt 10.1, B는 10.2가 설치됨
문제: API 차이로 A는 되는데 B는 실패
결과: builtin-baseline 고정, vcpkg.lock Git 커밋

시나리오 4: 정적 링크 배포 필요

상황: 단일 실행 파일로 배포해야 함 (DLL 없이)
문제: 기본 triplet은 동적 링크
결과: x64-windows-static triplet 사용

시나리오 5: 사내 라이브러리 통합

상황: 공식 레지스트리에 없는 사내 유틸리티 라이브러리
문제: vcpkg install로 설치 불가
결과: 오버레이 포트로 사내 포트 디렉터리 등록

시나리오별 기술 선택

시나리오vcpkg 기능적용 방법
신규 프로젝트Manifest 모드vcpkg.json 생성
CI 빌드Manifest + 툴체인CMAKE_TOOLCHAIN_FILE
버전 통일builtin-baseline, vcpkg.lockvcpkg.json, lock 커밋
정적 링크TripletVCPKG_TARGET_TRIPLET
사내 라이브러리오버레이VCPKG_OVERLAY_PORTS
flowchart TD
  subgraph 문제[실무 문제]
    P1[라이브러리 설치 지옥] --> S1[Manifest 모드]
    P2[CI 빌드 실패] --> S2[툴체인 + vcpkg.json]
    P3[버전 불일치] --> S3[baseline + lock]
    P4[정적 링크] --> S4[Triplet]
    P5[사내 라이브러리] --> S5[오버레이]
  end

2. vcpkg 설치

2.1 설치 방법

vcpkg는 Git 저장소를 클론한 뒤 bootstrap 스크립트를 실행해 실행 파일을 만듭니다.

Linux/macOS:

# 1. vcpkg 클론 (프로젝트 밖 또는 프로젝트 내 서브모듈로)
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg

# 2. bootstrap 실행
./bootstrap-vcpkg.sh

# 3. 설치 확인
./vcpkg version

Windows (PowerShell 또는 cmd):

# 1. vcpkg 클론
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg

# 2. bootstrap 실행
.\bootstrap-vcpkg.bat

# 3. 설치 확인
.\vcpkg.exe version

설치 결과: vcpkg(또는 vcpkg.exe) 실행 파일이 생성됩니다. vcpkg 디렉터리에서 실행하거나, PATH에 추가해 전역에서 사용할 수 있습니다.

2.2 프로젝트에 vcpkg 서브모듈로 추가 (권장)

팀 전체가 동일한 vcpkg 버전을 쓰려면 프로젝트에 서브모듈로 추가합니다.

# 프로젝트 루트에서
git submodule add https://github.com/Microsoft/vcpkg.git vcpkg

# 서브모듈 초기화
git submodule update --init --recursive

# vcpkg bootstrap
cd vcpkg
./bootstrap-vcpkg.sh   # Linux/macOS
# .\bootstrap-vcpkg.bat  # Windows
cd ..

장점: 프로젝트와 vcpkg 버전이 함께 고정되어, “팀원 A는 되는데 B는 안 된다” 문제를 줄입니다.

2.3 사전 요구사항

항목최소 버전
Git2.x
CMake3.20+
C++ 컴파일러MSVC 2019+, GCC 9+, Clang 10+
Python3.8+ (일부 포트에서 필요)
# CMake 버전 확인
cmake --version

# C++ 컴파일러 확인
g++ --version   # Linux
clang++ --version  # macOS
cl  # Windows (Visual Studio Developer Command Prompt)

3. Manifest 모드 완벽 예제

3.1 Classic 모드 vs Manifest 모드

구분Classic 모드Manifest 모드
설치 방식vcpkg install fmt 전역 설치vcpkg.json에 선언, CMake 설정 시 자동 설치
의존성 위치vcpkg 설치 디렉터리프로젝트별 격리
재현성낮음 (팀원마다 다름)높음 (vcpkg.json + lock)
권장레거시신규 프로젝트는 Manifest 모드

3.2 최소 Manifest 모드 예제

프로젝트 구조:

my-app/
├── CMakeLists.txt
├── vcpkg.json
├── vcpkg/              # git submodule (선택)
└── src/
    └── main.cpp

vcpkg.json:

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "vcpkg Manifest 모드 예제",
  "dependencies": [
    "fmt",
    "spdlog"
  ]
}

CMakeLists.txt:

cmake_minimum_required(VERSION 3.20)
project(my-app VERSION 1.0.0 LANGUAGES CXX)

# vcpkg 툴체인 지정 (필수!)
set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
    CACHE STRING "Vcpkg toolchain")

add_executable(my-app src/main.cpp)

find_package(fmt CONFIG REQUIRED)
find_package(spdlog CONFIG REQUIRED)

target_link_libraries(my-app PRIVATE
    fmt::fmt
    spdlog::spdlog
)

target_compile_features(my-app PRIVATE cxx_std_17)

src/main.cpp:

#include <spdlog/spdlog.h>
#include <fmt/core.h>

int main() {
    spdlog::set_level(spdlog::level::debug);
    spdlog::info("Hello, vcpkg! {}", fmt::format("vcpkg works!"));
    return 0;
}

3.3 빌드 실행

# vcpkg가 서브모듈인 경우
cmake -B build -S . \
  -DCMAKE_TOOLCHAIN_FILE="$(pwd)/vcpkg/scripts/buildsystems/vcpkg.cmake"

cmake --build build
./build/my-app  # 또는 build\my-app.exe (Windows)

동작 흐름:

  1. CMake가 CMAKE_TOOLCHAIN_FILE을 로드
  2. vcpkg 툴체인이 vcpkg.json을 읽음
  3. fmt, spdlog가 없으면 자동 설치
  4. find_package가 vcpkg 설치 경로에서 패키지 검색
  5. 빌드 완료

3.4 Manifest 모드 — 의존성 객체 형태

버전 제약, 플랫폼별 의존성을 지정할 때는 객체 형태입니다.

{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": [
    "fmt",
    {
      "name": "spdlog",
      "version>=": "1.11.0",
      "version<": "2.0.0"
    },
    {
      "name": "openssl",
      "platform": "windows"
    }
  ]
}
필드설명
name패키지 이름
version>=최소 버전 (이 버전 이상)
version<최대 버전 (호환성 깨짐 방지)
platform플랫폼 조건 (windows, !windows, linux, osx)

4. Triplet 기초

4.1 Triplet이란?

Triplet은 arch-vendor-os 형식으로, 대상 플랫폼·아키텍처·빌드 타입을 지정합니다.

Triplet설명
x64-windowsWindows 64비트, 동적 링크
x64-windows-staticWindows 64비트, 정적 링크
x64-linuxLinux 64비트
x64-osxmacOS Intel
arm64-osxmacOS Apple Silicon (M1/M2)

4.2 Triplet 지정 방법

방법 1: CMake 옵션

cmake -B build -S . \
  -DCMAKE_TOOLCHAIN_FILE="$(pwd)/vcpkg/scripts/buildsystems/vcpkg.cmake" \
  -DVCPKG_TARGET_TRIPLET=x64-windows-static

방법 2: 환경 변수

export VCPKG_DEFAULT_TRIPLET=x64-windows-static
cmake -B build -S .

방법 3: vcpkg.json (vcpkg-configuration.json)

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg",
    "baseline": "..."
  },
  "triplet": "x64-windows-static"
}

4.3 정적 링크 vs 동적 링크

용도Triplet
개발 (빌드 속도 우선)x64-windows, x64-linux
배포 (단일 실행 파일)x64-windows-static, x64-linux-static

4.4 Triplet 확인

# 현재 기본 triplet
vcpkg version

# 설치된 패키지 확인 (triplet별)
vcpkg list

5. 버전 관리

5.1 builtin-baseline

builtin-baseline은 vcpkg 포트 저장소의 특정 커밋 해시입니다. 이 해시에 따라 사용 가능한 패키지 버전이 결정됩니다.

{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": ["fmt", "spdlog"],
  "builtin-baseline": "a1b2c3d4e5f6789012345678901234567890abc"
}

baseline 해시 가져오기:

cd vcpkg
git pull
git rev-parse HEAD
# 출력: a1b2c3d4e5f6789012345678901234567890abc

권장: 프로덕션에서는 baseline을 고정하고, 별도 브랜치에서 업데이트 테스트 후 반영합니다.

5.2 vcpkg.lock — 재현 가능한 빌드

Manifest 모드로 빌드하면 vcpkg.lock이 생성됩니다. 이 파일을 Git에 커밋하면 정확히 동일한 버전으로 빌드됩니다.

{
  "version": 1,
  "port-version": 0,
  "builtin-baseline": "a1b2c3d4e5f6789012345678901234567890abc",
  "packages": [
    {
      "name": "fmt",
      "version": "10.1.1",
      "port-version": 0
    },
    {
      "name": "spdlog",
      "version": "1.12.1",
      "port-version": 0
    }
  ]
}

주의: vcpkg.lock이 있으면 vcpkg가 이 버전을 우선 사용합니다. 의존성 추가/변경 시 lock 파일이 자동 갱신되므로, 변경 후 테스트하고 커밋하세요.

5.3 버전 제약 문법

{
  "dependencies": [
    {
      "name": "spdlog",
      "version>=": "1.11.0",
      "version<": "2.0.0"
    }
  ]
}
  • version>=: 최소 버전
  • version<: 최대 버전 (마이저 업그레이드 시 예기치 않은 깨짐 방지)

6. 커스텀 포트(오버레이)

6.1 오버레이란?

오버레이는 vcpkg 공식 레지스트리보다 우선 적용되는 포트 디렉터리입니다. 사내 라이브러리, 수정된 포트, 아직 upstream되지 않은 패키지를 사용할 때 씁니다.

6.2 오버레이 디렉터리 구조

my-ports/
├── internal-lib/
│   ├── vcpkg.json
│   └── portfile.cmake
└── patched-spdlog/
    ├── vcpkg.json
    ├── portfile.cmake
    └── patches/
        └── fix-logging.patch

6.3 최소 오버레이 포트 예제 (헤더-온리)

my-ports/header-only-lib/vcpkg.json:

{
  "name": "header-only-lib",
  "version": "1.0.0",
  "description": "헤더 전용 유틸리티 라이브러리",
  "license": "MIT",
  "dependencies": []
}

my-ports/header-only-lib/portfile.cmake:

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO example/header-only-lib
    REF "v1.0.0"
    SHA512 0
    HEAD_REF main
)

# 헤더만 복사 (빌드 없음)
file(INSTALL "${SOURCE_PATH}/include/"
    DESTINATION "${CURRENT_PACKAGES_DIR}/include"
    FILES_MATCHING PATTERN "*.hpp"
)

file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage"
    DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

주의: SHA512 0으로 두고 설치 시도 → 에러 메시지에 실제 해시가 출력됨 → 복사해 넣기.

6.4 오버레이 사용

cmake -B build -S . \
  -DCMAKE_TOOLCHAIN_FILE="$(pwd)/vcpkg/scripts/buildsystems/vcpkg.cmake" \
  -DVCPKG_OVERLAY_PORTS="$(pwd)/my-ports"

vcpkg.json에서 오버레이 포트를 의존성으로 추가:

{
  "dependencies": [
    "fmt",
    "header-only-lib"
  ]
}

6.5 vcpkg-configuration.json으로 오버레이 등록

프로젝트 루트에 vcpkg-configuration.json을 두면 CMake 옵션 없이 오버레이가 적용됩니다.

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg",
    "baseline": "a1b2c3d4e5f6..."
  },
  "overlay-ports": [./my-ports]
}

7. 완전한 예제 프로젝트

7.1 예제 1: 기본 Manifest 모드

vcpkg-basics-demo/
├── CMakeLists.txt
├── vcpkg.json
├── vcpkg.lock          # Git 커밋 권장
├── vcpkg/              # git submodule
└── src/
    └── main.cpp

vcpkg.json:

{
  "name": "vcpkg-basics-demo",
  "version": "1.0.0",
  "description": "vcpkg 기초 완벽 예제",
  "dependencies": [
    "fmt",
    "spdlog",
    "nlohmann-json"
  ],
  "builtin-baseline": "a1b2c3d4e5f6789012345678901234567890abc"
}

CMakeLists.txt:

cmake_minimum_required(VERSION 3.20)
project(vcpkg-basics-demo VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
    CACHE STRING "Vcpkg toolchain")

add_executable(demo src/main.cpp)

find_package(fmt CONFIG REQUIRED)
find_package(spdlog CONFIG REQUIRED)
find_package(nlohmann_json CONFIG REQUIRED)

target_link_libraries(demo PRIVATE
    fmt::fmt
    spdlog::spdlog
    nlohmann_json::nlohmann_json
)

target_compile_features(demo PRIVATE cxx_std_17)

src/main.cpp:

#include <spdlog/spdlog.h>
#include <fmt/core.h>
#include <nlohmann/json.hpp>

int main() {
    spdlog::info("vcpkg 기초 예제");
    nlohmann::json j = {{"name", "vcpkg"}, {"version", "1.0"}};
    spdlog::info("JSON: {}", j.dump());
    return 0;
}

7.2 예제 2: Triplet + 정적 링크

cmake -B build -S . \
  -DCMAKE_TOOLCHAIN_FILE="$(pwd)/vcpkg/scripts/buildsystems/vcpkg.cmake" \
  -DVCPKG_TARGET_TRIPLET=x64-windows-static \
  -DCMAKE_BUILD_TYPE=Release

cmake --build build --config Release

7.3 예제 3: 오버레이 + Manifest

my-project/
├── CMakeLists.txt
├── vcpkg.json
├── vcpkg-configuration.json
├── vcpkg/
├── my-ports/
│   └── internal-lib/
│       ├── vcpkg.json
│       └── portfile.cmake
└── src/
    └── main.cpp

vcpkg-configuration.json:

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg",
    "baseline": "a1b2c3d4e5f6..."
  },
  "overlay-ports": [./my-ports]
}

8. 자주 발생하는 에러와 해결법

에러 1: “Could not find a package configuration file provided by ‘fmt’”

CMake Error: Could not find a package configuration file provided by "fmt"

원인: CMAKE_TOOLCHAIN_FILE을 지정하지 않았거나, vcpkg가 패키지를 아직 빌드하지 않음.

해결법:

# 1. 툴체인 파일 반드시 지정
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE="$(pwd)/vcpkg/scripts/buildsystems/vcpkg.cmake"

# 2. build 폴더 삭제 후 재시도 (캐시된 잘못된 설정 제거)
rm -rf build
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=...

에러 2: “Port xxx is not in the baseline”

Error: Could not find a version that satisfies the requirement ...

원인: builtin-baseline이 오래되었거나, 해당 패키지가 baseline에 없음.

해결법:

cd vcpkg
git pull
git rev-parse HEAD   # 이 해시를 vcpkg.json의 builtin-baseline에 넣기
{
  "builtin-baseline": "최신_커밋_해시"
}

에러 3: “Building package xxx failed”

Building package spdlog:x64-linux failed

원인: 패키지 빌드 중 컴파일 에러, 의존성 누락, 네트워크 오류 등.

해결법:

# 상세 로그로 원인 파악
export VCPKG_VERBOSE=1
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=...

# 특정 패키지만 수동 빌드
./vcpkg install spdlog --debug

에러 4: “A suitable version of cmake was not found”

Error: vcpkg was unable to find the version of cmake in your PATH

원인: PATH에 CMake가 없거나 버전이 낮음 (3.20+ 권장).

해결법:

which cmake
cmake --version
# 3.20 이상이어야 함. PATH에 추가하거나 최신 CMake 설치

에러 5: “undefined reference” / 링크 에러

undefined reference to `spdlog::...'

원인: target_link_libraries에 누락, 또는 정적/동적 링크 혼용.

해결법:

# find_package 후 반드시 target_link_libraries에 추가
find_package(spdlog CONFIG REQUIRED)
target_link_libraries(my-app PRIVATE spdlog::spdlog)

에러 6: “C++ 표준 불일치”

error: #error "spdlog requires C++17 or later"

원인: 프로젝트가 C++14로 빌드되는데 의존성이 C++17 요구.

해결법:

target_compile_features(my-app PRIVATE cxx_std_17)
# 또는
set(CMAKE_CXX_STANDARD 17)

에러 7: 오버레이 포트를 찾을 수 없음

Error: Could not find port internal-lib

원인: VCPKG_OVERLAY_PORTS 경로가 잘못되었거나, 포트 디렉터리 구조가 맞지 않음.

해결법:

# 경로 확인 (절대 경로 권장)
ls -la my-ports/internal-lib/vcpkg.json
cmake -B build -S . \
  -DVCPKG_OVERLAY_PORTS="$(pwd)/my-ports"

에러 8: vcpkg.lock과 vcpkg.json 충돌

Error: Version conflict: lock file expects [email protected] but vcpkg.json allows 10.2.0

원인: vcpkg.json을 수정했는데 vcpkg.lock을 갱신하지 않음.

해결법:

# lock 파일 삭제 후 재생성
rm vcpkg.lock
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=...
# 새 vcpkg.lock 생성됨 → Git 커밋

에러 9: CI에서만 “Could NOT find” 발생

원인: 로컬에 Classic 모드로 설치한 패키지에 의존. CI에는 해당 패키지가 없음.

해결법: Manifest 모드로 전환. vcpkg.json에 의존성 선언하고 CMAKE_TOOLCHAIN_FILE 지정.

에러 10: “vcpkg integrate install” 했는데 안 됨

원인: integrate install은 Classic 모드용. Manifest 모드는 CMAKE_TOOLCHAIN_FILE을 명시적으로 지정해야 함.

해결법: Manifest 모드에서는 -DCMAKE_TOOLCHAIN_FILE=...를 반드시 CMake 설정 시 전달합니다.

9. 베스트 프랙티스

1. Manifest 모드 사용

  • vcpkg.json을 프로젝트 루트에 두고 Git에 커밋
  • Classic 모드는 레거시. 신규 프로젝트는 Manifest 모드

2. builtin-baseline 고정

  • 재현 가능한 빌드를 위해 특정 커밋 해시 사용
  • 업데이트 시 별도 브랜치에서 테스트 후 main 반영

3. vcpkg.lock 커밋

  • vcpkg.lock을 Git에 커밋하면 팀 전체가 동일한 버전 사용
  • 의존성 추가/변경 시 lock 갱신 후 테스트·커밋

4. vcpkg 서브모듈

git submodule add https://github.com/Microsoft/vcpkg.git vcpkg
  • vcpkg 버전을 프로젝트와 함께 고정
  • CI에서 submodules: recursive로 체크아웃

5. find_package CONFIG 모드

find_package(fmt CONFIG REQUIRED)
target_link_libraries(my-app PRIVATE fmt::fmt)
  • vcpkg 패키지는 대부분 Config 모드. CONFIG 명시 권장

6. 의존성 최소화

  • 꼭 필요한 패키지만 추가
  • 헤더 전용 라이브러리(nlohmann-json 등)는 빌드 없이 사용 가능

7. CI 캐시 활용

  • buildtrees, packages, downloads 캐시
  • hashFiles('vcpkg.json', 'vcpkg.lock')를 key에 포함

8. CMake Presets

  • CMakePresets.json으로 팀 전체 설정 통일
  • cmake --preset vcpkg-default로 간편 설정

10. 프로덕션 패턴

패턴 1: 멀티 플랫폼 CI 매트릭스

# .github/workflows/build.yml
strategy:
  matrix:
    include:
      - os: ubuntu-latest
        triplet: x64-linux
      - os: windows-latest
        triplet: x64-windows-static
      - os: macos-latest
        triplet: arm64-osx
steps:
  - uses: actions/checkout@v4
    with:
      submodules: recursive

  - name: Configure
    run: |
      cmake -B build -S . \
        -DCMAKE_TOOLCHAIN_FILE=${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake \
        -DVCPKG_TARGET_TRIPLET=${{ matrix.triplet }}

패턴 2: CI vcpkg 캐시

- name: Cache vcpkg
  uses: actions/cache@v4
  with:
    path: |
      ${{ github.workspace }}/vcpkg/buildtrees
      ${{ github.workspace }}/vcpkg/packages
      ${{ github.workspace }}/vcpkg/downloads
    key: vcpkg-${{ runner.os }}-${{ hashFiles('vcpkg.json', 'vcpkg.lock') }}
    restore-keys: vcpkg-${{ runner.os }}-

패턴 3: CMakePresets.json

{
  "version": 3,
  "configurePresets": [
    {
      "name": "vcpkg-default",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "${sourceDir}/vcpkg/scripts/buildsystems/vcpkg.cmake"
      }
    },
    {
      "name": "vcpkg-static",
      "inherits": "vcpkg-default",
      "cacheVariables": {
        "VCPKG_TARGET_TRIPLET": "x64-windows-static"
      }
    }
  ]
}

패턴 4: 의존성 업데이트 전략

1. 개발: 주기적으로 baseline 업데이트, 로컬 테스트
2. 스테이징: 업데이트 후 CI 전체 통과 확인
3. 프로덕션: vcpkg.lock 커밋으로 버전 고정

패턴 5: 사내 오버레이 공유

회사 레포지토리: company/vcpkg-ports
각 프로젝트에서:
  -DVCPKG_OVERLAY_PORTS="$(pwd)/../vcpkg-ports"
또는 서브모듈로 vcpkg-ports 포함

11. 구현 체크리스트

vcpkg 기초 설정

  • vcpkg 설치 (bootstrap 완료)
  • vcpkg 서브모듈 추가 (권장)
  • CMAKE_TOOLCHAIN_FILE 지정
  • Manifest 모드 + vcpkg.json

버전 관리

  • builtin-baseline 고정
  • vcpkg.lock Git 커밋
  • 버전 제약 (version>=, version<) 사용

Triplet

  • 배포용 정적 링크 시 x64-windows-static 등 사용
  • 팀 전체 triplet 통일

오버레이 (사내 라이브러리)

  • my-ports/ 디렉터리 구조
  • VCPKG_OVERLAY_PORTS 또는 vcpkg-configuration.json

CI/CD

  • submodules: recursive
  • vcpkg 캐시 (buildtrees, packages, downloads)
  • hashFiles(‘vcpkg.json’, ‘vcpkg.lock’) key

자주 묻는 질문 (FAQ)

Q. vcpkg Classic 모드와 Manifest 모드 차이는?

A. Classic 모드는 vcpkg install로 전역 설치. Manifest 모드는 프로젝트 vcpkg.json에 의존성을 선언하고 CMake 설정 시 자동 설치. 재현 가능한 빌드를 위해 Manifest 모드를 권장합니다.

Q. CMAKE_TOOLCHAIN_FILE을 매번 지정해야 하나요?

A. CMakePresets.json에 cacheVariables로 넣어 두면 cmake --preset vcpkg-default로 한 번에 설정됩니다. IDE(CLion, VS)에서도 preset을 선택하면 됩니다.

Q. vcpkg.lock은 꼭 커밋해야 하나요?

A. 팀 전체가 동일한 버전으로 빌드하려면 커밋하는 것이 좋습니다. 의존성 변경 시 lock이 자동 갱신되므로, 변경 후 테스트하고 함께 커밋합니다.

Q. 사내 라이브러리를 vcpkg로 쓰려면?

A. 오버레이 포트를 만듭니다. my-ports/내라이브러리/에 vcpkg.json과 portfile.cmake를 두고, -DVCPKG_OVERLAY_PORTS로 경로를 지정합니다. 자세한 내용은 vcpkg 패키지 만들기를 참고하세요.

Q. CI 빌드가 너무 느려요.

A. actions/cache로 vcpkg의 buildtrees, packages, downloads를 캐시하세요. hashFiles('vcpkg.json', 'vcpkg.lock')를 key에 넣으면 의존성 변경 시에만 캐시가 갱신됩니다.

Q. builtin-baseline을 언제 업데이트하나요?

A. 보안 패치·버그 수정이 필요할 때. 별도 브랜치에서 업데이트 후 전체 테스트를 돌리고, 통과하면 main에 반영합니다.

한 줄 요약: vcpkg Manifest 모드 + vcpkg.json + CMAKE_TOOLCHAIN_FILE 지정만으로 대부분의 C++ 의존성 관리 문제를 해결할 수 있습니다.

다음 글: [C++ #53-3] vcpkg 고급 활용 | Manifest·Triplet·오버레이·바이너리 캐시

이전 글: [C++ #53-2] Visual Studio C++ 완벽 가이드

관련 글

  • C++ vcpkg 고급 활용 | Manifest·Triplet·오버레이·바이너리 캐시 가이드
  • C++ vcpkg 패키지 만들기 | 포트 파일·빌드·배포 완벽 가이드 [#53-3]
  • C++ Conan 기초 완벽 가이드 | 설치·conanfile·프로필·CMake 연동 [#53-4]
  • CMake 입문 | 수십 개 파일 컴파일할 때 필요한 빌드 자동화 (CMakeLists.txt 기초)
  • C++ Conan 완벽 가이드 | 현대적인 C++ 패키지 관리
... 996 lines not shown ... Token usage: 63706/1000000; 936294 remaining Start-Sleep -Seconds 3