자습서: vcpkg를 사용하여 라이브러리 패키지

이 자습서에서는 사용자 지정 오버레이를 사용하여 vcpkg용 라이브러리를 패키지하는 방법을 안내합니다. 계속하기 전에 CMake 자습서에서 패키지 설치를 읽고 사용하는 것이 좋습니다.

필수 조건

• 터미널
• C++ 컴파일러
• CMake
• Git

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

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

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

설정 VCPKG_ROOT은 vcpkg 인스턴스의 위치를 vcpkg에 알려줍니다. PATH 셸에서 직접 vcpkg 명령을 실행할 수 있도록 추가합니다.

3 - 사용자 지정 오버레이 설정

1. custom-overlay 자습서에서 만든 Hello World 프로젝트 옆에 라는 새 디렉터리를 만드세요.
2. 디렉터리 내에서 custom-overlay .라는 vcpkg-sample-library폴더를 만듭니다.

4 - 포트 파일 설정

먼저 다음 콘텐츠를 사용하여 vcpkg.json 폴더 내에 custom-overlay/vcpkg-sample-library 파일을 만듭니다.

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

이 파일은 vcpkg.json C++ 라이브러리에 대한 메타데이터 및 종속성을 정의하는 매니페스트 역할을 하며, vcpkg에 패키지를 빌드, 설치 및 관리하는 데 필요한 정보를 제공합니다.

• name: 라이브러리의 이름을 지정합니다. 패키지 식별자로 사용됩니다.
• version: 라이브러리의 버전 번호를 나타냅니다.
• homepage: 프로젝트의 홈페이지에 대한 URL로, 종종 해당 리포지토리입니다. 더 많은 것을 알고 싶거나 기여하려는 사람들에게 유용합니다.
• description: 라이브러리가 수행하는 작업을 설명하는 간단한 텍스트입니다. 이는 설명서 및 사용자를 위한 것입니다.
• license: 라이브러리가 배포되는 라이선스를 지정합니다.
• dependencies: 라이브러리에 필요한 종속성 목록을 포함하는 배열입니다.
• name: vcpkg-cmake: CMake 함수 및 매크로를 vcpkg 포트에서 일반적으로 제공하는 vcpkg-cmake에 대한 종속성을 지정합니다.
• host: true: 호스트 종속성을 지정합니다 vcpkg-cmake . 즉, 패키지를 빌드하는 데 필요하지만 사용하는 데는 필요하지 않습니다.
• name: vcpkg-cmake-config: vcpkg-cmake-config에 대한 종속성을 지정하여 CMake 구성 스크립트를 사용하는 데 도움을 줍니다.
• fmt: 라이브러리에 대한 fmt 런타임 종속성을 지정합니다. 즉 fmt , 패키지를 빌드하고 사용하는 데 모두 필요합니다.

자세한 내용은 매니페스트에 대한 vcpkg.json다음 설명서를 참조하세요.

이제 다음 콘텐츠를 사용하여 usagecustom-overlay\vcpkg-sample-library 디렉터리 내에 파일을 만듭니다.

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) 내에 제공하는 것을 강력히 권장합니다. 올바른 사용 지침을 확인하려면 업스트림의 지침을 따르는 것이 좋습니다. 업스트림에서 사용 정보를 제공하지 않는 경우 빌드 시스템을 파헤쳐 내보낸 대상을 찾아야 할 수 있습니다.

자세한 지침은 사용량 파일 처리를 참조 하세요.

마지막으로 다음 콘텐츠를 사용하여 portfile.cmake 디렉터리 내에 custom-overlay\vcpkg-sample-library 파일을 만듭니다.

vcpkg_check_linkage(ONLY_STATIC_LIBRARY)

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

vcpkg portfile 를 사용하여 GitHub에서 특정 C++ 라이브러리를 다운로드, 빌드, 설치 및 패키지하는 방법을 정의합니다.

• vcpkg_check_linkage(ONLY_STATIC_LIBRARY): 이 패키지에 대해 정적 연결만 지원되도록 지정합니다.
• vcpkg_from_github: GitHub 리포지토리에서 소스 코드를 다운로드하는 함수를 시작합니다.
  • OUT_SOURCE_PATH SOURCE_PATH: 소스 코드가 추출될 디렉터리를 설정합니다.
  • REPO MicrosoftDocs/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"): 중복을 방지하기 위해 디버그 설치에서 include 디렉터리를 삭제합니다.
• file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" ...): 사용 지침 파일을 패키지의 공유 디렉터리에 복사합니다.
• vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE"): 패키지의 공유 디렉터리에 LICENSE 파일을 설치하고 이름을 저작권으로 바꿉니다.

자세한 내용은 유지 관리자 가이드를 참조하세요.

5 - portfile.cmake의 SHA512 업데이트

실행:

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

긴 오류 메시지가 표시됩니다. 출력을 검사하여 다음을 찾습니다.

Downloading https://github.com/MicrosoftDocs/vcpkg-docs/archive/1.0.2.tar.gz -> MicrosoftDocs-vcpkg-docs-1.0.2.tar.gz
Successfully downloaded MicrosoftDocs-vcpkg-docs-1.0.2.tar.gz
error: failing download because the expected SHA512 was all zeros, please change the expected SHA512 to: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

"실제 해시" 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417를 복사한 다음 SHA512의 portfile.cmake 값을 해당 값으로 바꾸십시오.

설치 명령을 다시 실행합니다.

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/usage
-- 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 - 포트 빌드 확인

라이브러리가 제대로 빌드되고 연결되는지 확인하려면 설치 패키지 자습서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

2. 프로젝트를 빌드합니다.

cmake --build build

3. 애플리케이션을 실행합니다.

./build/HelloWorld

프로젝트 실행 파일의 경로는 다음과 같이 ./build/Debug/HelloWorld.exe다를 수 있습니다.

Hello vcpkg!

다음 단계

vcpkg-sample-library 이제 포트로 패키지되었으므로 다음 단계는 vcpkg 큐레이팅된 레지스트리에 추가하는 것입니다. vcpkg 레지스트리에 포트 추가를 참조하세요.

자세한 내용은 다음을 참조하세요.

• 포트
• 유지 관리자 가이드