다음을 통해 공유

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

  • 아티클

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

필수 조건

참고 항목

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

참고 항목

명령을 사용하여 환경 변수를 설정하면 export 현재 셸 세션에만 영향을 줍니다. 세션 간에 이 변경 내용을 영구적으로 변경하려면 셸의 프로필 스크립트(예: 또는~/.zshrc)에 ~/.bashrc 명령을 추가 export 합니다.

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

참고 항목

이러한 방식으로 환경 변수를 설정하면 현재 터미널 세션에만 영향을 줍니다. 모든 세션에서 이러한 변경 내용을 영구적으로 변경하려면 Windows 시스템 환경 변수 패널을 통해 설정합니다.

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

참고 항목

이러한 방식으로 환경 변수를 설정하면 현재 터미널 세션에만 영향을 줍니다. 모든 세션에서 이러한 변경 내용을 영구적으로 변경하려면 Windows 시스템 환경 변수 패널을 통해 설정합니다.

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

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

  1. 설치에서 만든 프로젝트 옆에 Hello World 호출 custom-overlay 되는 새 디렉터리를 만들고 CMake 자습서에서 패키지를 사용합니다.
  2. 디렉터리 내에서 custom-overlay .라는 vcpkg-sample-library폴더를 만듭니다.

4 - 포트 파일 설정

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

{
  "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-cmakevcpkg 포트에서 vcpkg-cmake일반적으로 사용되는 CMake 함수 및 매크로를 제공하는 종속성을 지정합니다.
  • host: true: 호스트 종속성을 지정합니다 vcpkg-cmake . 즉, 패키지를 빌드하는 데 필요하지만 사용하는 데는 필요하지 않습니다.
  • name: vcpkg-cmake-configCMake 구성 스크립트를 사용하는 데 도움이 되는 종속성을 vcpkg-cmake-config지정합니다.
  • fmt: 라이브러리에 대한 fmt 런타임 종속성을 지정합니다. 즉 fmt , 패키지를 빌드하고 사용하는 데 모두 필요합니다.

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

이제 다음 콘텐츠를 사용하여 usage custom-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 데 필요한 최소 단계를 설명하는 포트의 디렉터리(ports/<port name>/usage) 내에 파일을 제공하는 것이 좋습니다. 올바른 사용 지침을 확인하려면 업스트림의 지침을 따르는 것이 좋습니다. 업스트림에서 사용 정보를 제공하지 않는 경우 빌드 시스템을 파헤쳐 내보낸 대상을 찾아야 할 수 있습니다.

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

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

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)

vcpkg portfile 를 사용하여 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"): 중복을 방지하기 위해 디버그 설치에서 include 디렉터리를 삭제합니다.
  • file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION ...): 패키지의 공유 디렉터리에 LICENSE 파일을 설치하고 이름을 저작권으로 바꿉니다.
  • configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" ...): 사용 지침 파일을 패키지의 공유 디렉터리에 복사합니다.

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

5 - 다음을 위한 SHA512 업데이트 portfile.cmake

다음을 실행합니다.

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

긴 오류 메시지가 표시됩니다. 다음을 찾을 때까지 출력을 검색합니다.

Expected hash: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Actual hash: 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/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"
    ]
}

새 포트가 포함된 폴더를 overlay-ports 포함하도록 수정 helloworld/vcpkg-configuration.json 합니다.

{
  "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 레지스트리에 포트 추가를 참조하세요.

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