C++ vcpkg 패키지 만들기 | 포트 파일·빌드·배포 완벽 가이드 [#53-3]

· 28분 읽기 · 수정 고급 실습
C++ vcpkg 패키지 만들기 | 포트 파일·빌드·배포 완벽 가이드 [#53-3]

이 글의 핵심

C++ vcpkg 패키지 작성 포트 파일 구조, vcpkg.json·portfile.cmake 작성, vcpkg create 활용, SHA512·패치·usage 파일, 공식 레지스트리 PR·사내 오버레이 배포까지 실전 예제로 다룹니다.

들어가며: “우리 라이브러리를 vcpkg로 쓰고 싶어요”

문제 시나리오

vcpkg로 fmt, spdlog를 설치해 쓰다 보면 이런 상황을 마주합니다:

"우리 팀에서 만든 유틸리티 라이브러리를 vcpkg로 배포하고 싶어요."
"공식 레지스트리에 없는 오픈소스를 프로젝트에 넣고 싶어요."
"사내 fork한 라이브러리를 vcpkg로 통합해서 팀원들이 쉽게 쓰게 하고 싶어요."
"헤더만 있는 라이브러리인데, include 경로를 매번 수동으로 넣기 귀찮아요."
"패키지 빌드 중 'SHA512 was all zeros' 에러가 나요."
"find_package가 우리 라이브러리를 못 찾아요."

추가 시나리오:

  • 오픈소스 기여: GitHub에서 fork한 라이브러리를 vcpkg 공식 레지스트리에 기여할 때
  • 헤더-온리: nlohmann/json처럼 헤더만 있는 라이브러리는 빌드 없이 복사만 하면 됨
  • 레거시 빌드: Makefile/autotools만 있는 라이브러리는 vcpkg_configure_make 등 사용

원인: vcpkg는 포트(port) 라는 단위로 패키지를 관리합니다. 포트는 vcpkg.json(메타데이터·의존성)과 portfile.cmake(다운로드·빌드·설치 스크립트)로 구성됩니다. 이 두 파일을 올바르게 작성해야 vcpkg가 라이브러리를 인식하고 빌드·설치할 수 있습니다.

이 글에서 다루는 것:

  • 포트 구조 이해: vcpkg.json, portfile.cmake, usage, copyright
  • 단계별 패키지 생성: vcpkg create → 수정 → SHA512 → 검증
  • 완전한 예제: 헤더-온리, CMake 라이브러리, Makefile 기반
  • 자주 발생하는 에러와 해결법
  • 베스트 프랙티스: 패치, 플랫폼별 처리, 기능(feature) 설계
  • 프로덕션 패턴: 오버레이, 공식 레지스트리 PR, 사내 레지스트리

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

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

목차

  1. 포트 구조와 핵심 개념
  2. vcpkg create로 시작하기
  3. vcpkg.json 상세 작성
  4. portfile.cmake 상세 작성
  5. 완전한 패키지 생성 예제
  6. 자주 발생하는 에러와 해결법
  7. 베스트 프랙티스
  8. 프로덕션 패턴: 배포 전략
  9. 정리

1. 포트 구조와 핵심 개념

포트란?

포트(port) 는 vcpkg가 한 패키지를 빌드·설치하기 위해 필요한 레시피입니다. 하나의 포트 디렉터리에는 다음 파일들이 들어갑니다.

ports/my-library/
├── vcpkg.json        # 메타데이터, 버전, 의존성, 기능(feature)
├── portfile.cmake    # 다운로드·빌드·설치 스크립트
├── usage             # (권장) 사용법 안내
├── copyright         # (자동 생성) 라이선스 파일
└── patches/          # (선택) 빌드 수정용 패치
    └── 001-fix-cmake.patch

포트 생명 주기

flowchart LR
  subgraph download[1. 다운로드]
    D1[vcpkg_from_github 등] --> D2[소스 추출]
  end
  subgraph build[2. 빌드]
    B1[vcpkg_cmake_configure] --> B2[vcpkg_cmake_install]
  end
  subgraph install[3. 설치]
    I1[include/lib/share 복사] --> I2[usage·copyright]
  end
  download --> build --> install

패키지 생성 시퀀스

sequenceDiagram
    participant Dev as 개발자
    participant Vcpkg as vcpkg
    participant GH as GitHub/소스
    participant CMake as CMake

    Dev->>Vcpkg: vcpkg install my-lib --overlay-ports=...
    Vcpkg->>Vcpkg: vcpkg.json 파싱
    Vcpkg->>GH: 소스 다운로드 (SHA512 검증)
    GH-->>Vcpkg: 아카이브
    Vcpkg->>Vcpkg: 압축 해제
    Vcpkg->>CMake: vcpkg_cmake_configure
    CMake-->>Vcpkg: 설정 완료
    Vcpkg->>CMake: vcpkg_cmake_install
    CMake-->>Vcpkg: 빌드·설치 완료
    Vcpkg->>Vcpkg: config_fixup, usage, copyright
    Vcpkg-->>Dev: 패키지 설치 완료

핵심 변수 (portfile.cmake에서 사용):

변수설명
PORT현재 포트 이름 (예: my-library)
SOURCE_PATH다운로드 후 소스 경로
CURRENT_PACKAGES_DIR설치 대상 디렉터리
CURRENT_BUILDTREES_DIR빌드 중간 결과
TARGET_TRIPLET대상 triplet (예: x64-windows, x64-linux)
VCPKG_TARGET_IS_WINDOWSWindows 여부 (CMake 변수)

2. vcpkg create로 시작하기

vcpkg create 명령

새 포트를 자동 생성할 때 사용합니다. 소스 URL을 주면 다운로드 후 vcpkg.json과 portfile.cmake 초안을 만들어 줍니다.

# 형식: vcpkg create <포트이름> <소스-URL> [아카이브-파일명]
vcpkg create my-lib https://github.com/example/my-lib/archive/v1.0.0.tar.gz my-lib-1.0.0.tar.gz

주의: vcpkg create로 만든 포트는 시작점일 뿐이며, 대부분 추가 수정이 필요합니다. 버전, SHA512, 의존성, CMake 옵션 등을 채워 넣어야 합니다.

수동으로 포트 디렉터리 만들기

오버레이로 사내 라이브러리를 패키지할 때는 디렉터리와 파일을 직접 만듭니다.

mkdir -p custom-overlay/my-internal-lib
touch custom-overlay/my-internal-lib/vcpkg.json
touch custom-overlay/my-internal-lib/portfile.cmake

3. vcpkg.json 상세 작성

vcpkg.json 필수 필드

{
  "name": "my-library",
  "version": "1.0.2",
  "description": "A sample C++ library for vcpkg packaging tutorial.",
  "homepage": "https://github.com/example/my-library",
  "license": "MIT",
  "dependencies": [
    "fmt",
    {
      "name": "vcpkg-cmake",
      "host": true
    },
    {
      "name": "vcpkg-cmake-config",
      "host": true
    }
  ]
}
필드설명
name패키지 식별자. 소문자, 하이픈 사용
version시맨틱 버전 (예: 1.0.2)
description한 줄 설명. 사용자·문서용
homepage프로젝트 홈페이지/저장소 URL
license라이선스 (MIT, Apache-2.0, BSD-3-Clause 등)
dependencies빌드·실행 시 필요한 패키지

host 의존성

"host": true는 빌드 시에만 필요한 도구입니다. 최종 사용자에게 설치되지 않습니다.

{
  "name": "vcpkg-cmake",
  "host": true
}
  • vcpkg-cmake: CMake 헬퍼 함수 (vcpkg_cmake_configure 등)
  • vcpkg-cmake-config: vcpkg_cmake_config_fixup 등

기능(Feature) 설계

선택적 기능을 추가할 때 사용합니다.

{
  "name": "spdlog",
  "version": "1.12.1",
  "features": [
    {
      "name": "benchmark",
      "description": "Enable benchmarking support",
      "dependencies": [benchmark]
    },
    {
      "name": "wchar",
      "description": "Wide character support"
    }
  ],
  "default-features": [wchar]
}

4. portfile.cmake 상세 작성

기본 흐름

# 1. 링크 방식 제한 (선택)
vcpkg_check_linkage(ONLY_STATIC_LIBRARY)

# 2. 소스 다운로드
vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO example/my-library
    REF "v${VERSION}"
    SHA512 <해시값>
    HEAD_REF main
)

# 3. CMake 설정·빌드·설치
vcpkg_cmake_configure(SOURCE_PATH "${SOURCE_PATH}")
vcpkg_cmake_install()

# 4. CMake config 경로 수정 (find_package용)
vcpkg_cmake_config_fixup(PACKAGE_NAME "my_lib")

# 5. 정리·기타
file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")
file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

소스 다운로드 함수

GitHub (가장 흔함):

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO Microsoft/vcpkg
    REF "v2024.01.01"
    SHA512 abc123...
    HEAD_REF main
)

일반 URL (vcpkg_download_distfile + vcpkg_extract_source_archive_ex):

vcpkg_download_distfile(ARCHIVE
    URLS "https://example.com/releases/my-lib-1.0.0.tar.gz"
    FILENAME "my-lib-1.0.0.tar.gz"
    SHA512 def456...
)

vcpkg_extract_source_archive_ex(
    OUT_SOURCE_PATH SOURCE_PATH
    ARCHIVE "${ARCHIVE}"
)

Git (태그/브랜치 직접 체크아웃):

vcpkg_from_git(
    OUT_SOURCE_PATH SOURCE_PATH
    URL "https://github.com/example/my-lib.git"
    REF "v1.0.0"
)

SHA512 얻는 방법

처음에는 SHA512 0으로 두고 설치를 시도하면, vcpkg가 실제 해시를 에러 메시지에 출력합니다.

error: failing download because the expected SHA512 was all zeros, please change the expected SHA512 to: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

이 값을 복사해 portfile.cmake의 SHA512에 넣습니다.

패치 적용

업스트림에 버그가 있거나 vcpkg 빌드에 맞게 수정이 필요할 때:

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO example/my-lib
    REF "v${VERSION}"
    SHA512 ...
)

vcpkg_apply_patches(
    SOURCE_PATH "${SOURCE_PATH}"
    PATCHES "${CMAKE_CURRENT_LIST_DIR}/patches/001-fix-cmake.patch"
)

vcpkg_cmake_configure(SOURCE_PATH "${SOURCE_PATH}")

패치 생성:

cd buildtrees/my-lib/src/<해시>.clean
# 수정 후
git diff > ../../../../ports/my-lib/patches/001-fix-cmake.patch

vcpkg_copy_pdbs (Windows 디버그 심볼)

Windows에서 DLL/정적 라이브러리의 PDB 파일을 패키지에 포함할 때:

vcpkg_cmake_install()
vcpkg_copy_pdbs()  # Debug 빌드 시 .pdb 파일 복사

vcpkg_fixup_pkgconfig (pkg-config)

Makefile/autotools 기반 라이브러리가 .pc 파일을 설치할 때, 경로를 vcpkg 설치 구조에 맞게 수정합니다.

vcpkg_install_make()
vcpkg_fixup_pkgconfig()

5. 완전한 패키지 생성 예제

예제 1: 헤더-온리 라이브러리

시나리오: single_include/ 아래 헤더만 있는 라이브러리. 빌드 없이 복사만 하면 됩니다.

custom-overlay/header-only-lib/vcpkg.json:

{
  "name": "header-only-lib",
  "version": "2.1.0",
  "description": "Header-only utility library",
  "homepage": "https://github.com/example/header-only-lib",
  "license": "MIT",
  "dependencies": []
}

custom-overlay/header-only-lib/portfile.cmake:

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO example/header-only-lib
    REF "v${VERSION}"
    SHA512 0
    HEAD_REF main
)

# 헤더만 복사 (빌드 없음)
file(INSTALL "${SOURCE_PATH}/single_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")

custom-overlay/header-only-lib/usage:

header-only-lib provides headers:

#include <header_only_lib/foo.hpp>

No find_package or target_link_libraries needed for header-only.

예제 2: CMake 기반 라이브러리 (실전)

시나리오: CMake로 빌드되는 라이브러리. fmt에 의존하고, 정적 링크만 지원합니다.

custom-overlay/my-sample-lib/vcpkg.json:

{
  "name": "my-sample-lib",
  "version": "1.0.2",
  "description": "A sample C++ library for vcpkg packaging tutorial.",
  "homepage": "https://github.com/example/my-sample-lib",
  "license": "MIT",
  "dependencies": [
    "fmt",
    {
      "name": "vcpkg-cmake",
      "host": true
    },
    {
      "name": "vcpkg-cmake-config",
      "host": true
    }
  ]
}

custom-overlay/my-sample-lib/portfile.cmake:

vcpkg_check_linkage(ONLY_STATIC_LIBRARY)

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO example/my-sample-lib
    REF "v${VERSION}"
    SHA512 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417
    HEAD_REF main
)

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 "${CMAKE_CURRENT_LIST_DIR}/usage"
    DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

custom-overlay/my-sample-lib/usage:

my-sample-lib provides CMake targets:

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

사용 예 (프로젝트 vcpkg.json):

{
  "dependencies": ["fmt", "my-sample-lib"]
}

사용 예 (CMakeLists.txt):

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(my-app PRIVATE my_sample_lib::my_sample_lib)

예제 3: Makefile 기반 (vcpkg_fixup_makefile)

Makefile만 있는 레거시 라이브러리는 vcpkg_configure_make를 사용합니다.

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO example/legacy-lib
    REF "v1.0.0"
    SHA512 ...
)

vcpkg_configure_make(
    SOURCE_PATH "${SOURCE_PATH}"
)

vcpkg_install_make()
vcpkg_fixup_pkgconfig()
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/COPYING")

예제 4: vcpkg create로 생성 후 수정

vcpkg create zlib2 https://github.com/madler/zlib/archive/v1.2.11.tar.gz zlib-1.2.11.tar.gz

생성된 portfile.cmake 초안:

vcpkg_download_distfile(ARCHIVE
    URLS "https://github.com/madler/zlib/archive/v1.2.11.tar.gz"
    FILENAME "zlib-1.2.11.tar.gz"
    SHA512 104c62ed1228b5f1199bc037081861576900eb0697a226cafa62a35c4c890b5cb46622e399f9aad82ee5dfb475bae26ae75e2bd6da3d261361b1c8b996970faf
)

vcpkg_extract_source_archive_ex(
    OUT_SOURCE_PATH SOURCE_PATH
    ARCHIVE "${ARCHIVE}"
)

vcpkg_cmake_configure(SOURCE_PATH "${SOURCE_PATH}")
vcpkg_cmake_install()

vcpkg.json에 버전·설명을 채우고, 필요 시 vcpkg_cmake_config_fixup()을 추가합니다.

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

에러 1: “SHA512 was all zeros”

error: failing download because the expected SHA512 was all zeros, please change the expected SHA512 to: 42021259...

원인: portfile.cmake에서 SHA512 0으로 두었을 때, vcpkg가 무결성 검증을 위해 실제 해시를 요구함.

해결법: 에러 메시지에 나온 Actual hash 값을 복사해 SHA512 자리에 넣습니다.

vcpkg_from_github(
    ...
    SHA512 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417
    ...
)

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

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

원인:

  1. vcpkg_cmake_config_fixup(PACKAGE_NAME "my_lib")를 호출하지 않음
  2. 업스트림 CMake가 *Config.cmake를 lib/cmake/ 아래에 설치하지 않음
  3. PACKAGE_NAME이 실제 CMake 패키지 이름과 다름

해결법:

# 업스트림이 my_sample_libConfig.cmake를 설치한다면
vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib")

업스트림에 Config 파일이 없다면, share/${PORT} 아래에 수동으로 my_libConfig.cmake를 만들어 설치할 수 있습니다.

에러 3: “Port my-lib is not in the baseline”

Error: Could not find a version that satisfies the requirement my-lib

원인: 오버레이 포트인데 --overlay-ports를 지정하지 않았거나, 경로가 잘못됨.

해결법:

# 설치 시
vcpkg install my-lib --overlay-ports=/path/to/custom-overlay

# CMake 설정 시
cmake -B build -S . \
  -DCMAKE_TOOLCHAIN_FILE=... \
  -DVCPKG_OVERLAY_PORTS=/path/to/custom-overlay

vcpkg-configuration.json 사용 시:

{
  "overlay-ports": [./custom-overlay]
}

에러 4: “Building package my-lib failed”

Building package my-lib:x64-windows failed

원인: 컴파일 에러, 의존성 누락, CMake 옵션 불일치 등.

해결법:

# 상세 로그
export VCPKG_VERBOSE=1
vcpkg install my-lib --overlay-ports=...

# 빌드 트리 직접 확인
ls vcpkg/buildtrees/my-lib/
cd vcpkg/buildtrees/my-lib/src/<해시>.clean
# 여기서 수동으로 cmake .. && cmake --build . 해보기

에러 5: “only dynamic linkage is supported” / “only static linkage is supported”

error: my-lib only supports dynamic linkage

원인: 포트가 vcpkg_check_linkage(ONLY_DYNAMIC_LIBRARY) 또는 ONLY_STATIC_LIBRARY로 제한했는데, triplet이 다른 링크 방식을 요구함.

해결법: triplet을 맞추거나, 포트의 vcpkg_check_linkage를 제거/수정합니다. 정적 링크만 지원하는 라이브러리라면 x64-windows-static triplet을 사용합니다.

에러 6: “undefined reference” (Linux)

undefined reference to `my_lib::foo()'

원인: 링크 순서 문제, 또는 debug/release 혼용.

해결법: target_link_libraries에서 의존성을 올바른 순서로 지정하고, triplet을 통일합니다.

에러 7: 패치 적용 실패

Applying patch failed.

원인: 패치가 현재 소스와 맞지 않음 (줄 번호·컨텍스트 변경).

해결법: git diff로 패치를 다시 만들고, -p1 옵션을 고려합니다. vcpkg는 기본적으로 -p1로 패치를 적용합니다.

에러 8: “Version conflict” (vcpkg.lock)

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

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

해결법: vcpkg.lock을 삭제하고 CMake를 다시 실행하면 vcpkg가 새 lock을 생성합니다. 또는 vcpkg upgrade로 의존성을 갱신합니다.

에러 9: “The port directory does not exist”

Error: The port directory ... does not exist

원인: --overlay-ports 경로가 잘못되었거나, 포트 이름과 디렉터리 이름이 일치하지 않음.

해결법:

# 경로 확인 (절대 경로 권장)
ls -la /path/to/custom-overlay/my-lib/vcpkg.json
ls -la /path/to/custom-overlay/my-lib/portfile.cmake

# 상대 경로 사용 시 현재 디렉터리 기준
vcpkg install my-lib --overlay-ports="$(pwd)/custom-overlay"

7. 베스트 프랙티스

usage 파일 작성

모든 포트에 usage 파일을 두면 사용자가 vcpkg x-help <port>로 사용법을 볼 수 있습니다.

my-lib provides CMake targets:

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

For header-only usage:
#include <my_lib/foo.hpp>
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")
# 또는
vcpkg_install_copyright(FILE_LIST
    "${SOURCE_PATH}/LICENSE"
    "${SOURCE_PATH}/LICENSE.md"
)

debug/include 제거

일반적으로 debug 빌드에서도 include는 동일하므로, 중복을 제거합니다.

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

플랫폼별 처리

if(VCPKG_TARGET_IS_WINDOWS)
    vcpkg_cmake_configure(SOURCE_PATH "${SOURCE_PATH}" OPTIONS -DWIN32=ON)
else()
    vcpkg_cmake_configure(SOURCE_PATH "${SOURCE_PATH}")
endif()

버전 변수 사용

vcpkg.json의 version을 portfile.cmake에서 쓰려면, vcpkg가 자동으로 VERSION 변수를 설정합니다.

vcpkg_from_github(
    REF "v${VERSION}"
    ...
)

포트 검증 체크리스트

  • vcpkg.json에 name, version, description, homepage, license 기입
  • portfile.cmake에 SHA512 실제 값 설정 (0이 아님)
  • usage 파일 작성
  • vcpkg_install_copyright 호출
  • vcpkg install <port> --overlay-ports=... 로 설치 성공 확인
  • 샘플 프로젝트에서 find_package 및 링크 성공 확인

8. 프로덕션 패턴: 배포 전략

패턴 1: 오버레이 포트 (사내/로컬)

용도: 공식 레지스트리에 없는 라이브러리, 사내 fork, 버그 수정 패치 적용 버전.

구조:

my-project/
├── vcpkg/                 # git submodule
├── my-ports/              # 오버레이
│   ├── internal-lib/
│   │   ├── vcpkg.json
│   │   └── portfile.cmake
│   └── patched-spdlog/
│       ├── vcpkg.json
│       ├── portfile.cmake
│       └── patches/
│           └── 001-fix.patch
├── vcpkg.json
└── CMakeLists.txt

설정:

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

패턴 2: 공식 레지스트리 PR

용도: 오픈소스 라이브러리를 vcpkg 공식 레지스트리에 기여.

절차:

  1. vcpkg 저장소 fork
  2. ports/<port-name>/ 에 vcpkg.json, portfile.cmake 추가
  3. versions/<port-name>-base.json 에 버전 정보 추가 (또는 vcpkg x-add-version 사용)
  4. PR 제출 후 CI 통과 확인
cd vcpkg
./vcpkg x-add-version my-new-port
git add ports/my-new-port versions/
git commit -m "Add my-new-port"

패턴 3: Git 기반 사내 레지스트리

용도: 팀 전체가 사용하는 사내 패키지 레지스트리.

레지스트리 구조:

my-vcpkg-registry/
├── ports/
│   └── internal-lib/
│       ├── vcpkg.json
│       └── portfile.cmake
└── versions/
    └── internal-lib/
        └── base.json

vcpkg-configuration.json (프로젝트에서):

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg",
    "baseline": "..."
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/my-org/my-vcpkg-registry",
      "baseline": "main",
      "packages": [internal-lib]
    }
  ]
}

패턴 4: 바이너리 캐시로 CI 가속

오버레이 포트도 바이너리 캐시를 사용하면 CI 빌드 시간을 줄일 수 있습니다.

env:
  VCPKG_BINARY_SOURCES: "clear;default,readwrite,github,https://github.com/${{ github.repository }},readwrite"

패턴 5: 프로덕션 오버레이 프로젝트 구조

실무에서 사내 라이브러리를 여러 개 오버레이로 관리할 때의 권장 구조입니다.

company-cpp/
├── vcpkg/                    # git submodule
├── ports/                    # 사내 포트 모음
│   ├── company-utils/
│   │   ├── vcpkg.json
│   │   ├── portfile.cmake
│   │   └── usage
│   ├── company-protocol/
│   │   ├── vcpkg.json
│   │   └── portfile.cmake
│   └── patched-openssl/      # 사내 수정 OpenSSL
│       ├── vcpkg.json
│       ├── portfile.cmake
│       └── patches/
│           └── 001-tls13-fix.patch
├── vcpkg-configuration.json  # 오버레이 경로 등록
├── app-a/
│   ├── vcpkg.json
│   └── CMakeLists.txt
└── app-b/
    ├── vcpkg.json
    └── CMakeLists.txt

vcpkg-configuration.json:

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

이렇게 하면 app-a, app-b 모두 -DCMAKE_TOOLCHAIN_FILE=../vcpkg/scripts/buildsystems/vcpkg.cmake만 지정해도 ports/ 아래 사내 포트를 자동으로 사용합니다.

소스 유형별 portfile 함수 매핑

소스 유형다운로드 함수빌드 함수
GitHubvcpkg_from_githubvcpkg_cmake_configure
GitLabvcpkg_from_gitlabvcpkg_cmake_configure
일반 URLvcpkg_download_distfile + vcpkg_extract_source_archive_exvcpkg_cmake_configure
Makefilevcpkg_from_*vcpkg_configure_make
Autotoolsvcpkg_from_*vcpkg_configure_autotools
Mesonvcpkg_from_*vcpkg_configure_meson
헤더-온리vcpkg_from_*file(INSTALL …)

9. 정리

핵심 요약

항목설명
포트 구성vcpkg.json (메타데이터) + portfile.cmake (빌드 스크립트)
소스 다운로드vcpkg_from_github, vcpkg_download_distfile + vcpkg_extract_source_archive_ex
SHA5120으로 두고 설치 시도 → 에러 메시지에서 실제 해시 복사
CMake 빌드vcpkg_cmake_configure → vcpkg_cmake_install → vcpkg_cmake_config_fixup
usage사용법 안내. find_package, include 등
배포오버레이(사내) / 공식 PR / Git 레지스트리

구현 체크리스트

  • vcpkg.json에 name, version, description, homepage, license 작성
  • portfile.cmake에 SHA512 실제 값 설정
  • usage 파일 작성
  • vcpkg_install_copyright 호출
  • vcpkg install로 설치 성공 확인
  • 샘플 프로젝트에서 find_package·링크 검증
  • (선택) 패치, 플랫폼별 처리, feature 설계

참고 자료

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

A. 오픈소스 라이브러리 배포, 사내 패키지 관리, 의존성 표준화 등에 활용합니다. 실무에서는 위 본문의 예제와 선택 가이드를 참고해 적용하면 됩니다.

Q. 선행으로 읽으면 좋은 글은?

A. 각 글 하단의 이전 글 링크를 따라가면 순서대로 배울 수 있습니다. C++ 시리즈 목차에서 전체 흐름을 확인할 수 있습니다.

Q. 더 깊이 공부하려면?

A. cppreference와 해당 라이브러리 공식 문서를 참고하세요. 글 말미의 참고 자료 링크도 활용하면 좋습니다.

한 줄 요약: vcpkg.json·portfile.cmake·usage로 포트를 만들고, 오버레이·공식 PR·사내 레지스트리로 배포할 수 있습니다.

관련 글

  • C++ vcpkg 기초 완벽 가이드 | 설치·Manifest·Triplet·버전·커스텀 포트 [#53-3]
  • C++ vcpkg 고급 활용 | Manifest·Triplet·오버레이·바이너리 캐시 가이드
  • C++ Conan 레시피 작성 완벽 가이드 | 패키지·빌드·원격 저장소 [#53-4]
... 996 lines not shown ... Token usage: 63706/1000000; 936294 remaining Start-Sleep -Seconds 3