유지 관리자 가이드

아티클
10/15/2024

이 문서에는 포트 레시피를 추가하거나 업데이트할 때 적용해야 하는 정책 집합이 나열되어 있습니다. Debian의 정책 설명서, Homebrew의 유지 관리자 지침 및 Homebrew의 수식 요리책 역할을 하기 위한 것입니다.

전체 레지스트리 디자인 목표

현재 기준의 포트를 동시에 설치할 수 있어야 합니다.

큐레이팅된 레지스트리에서 라이브러리의 다운스트림 사용자에게 게시하는 지정된 기준의 라이브러리 조합이 적어도 일부 구성에서 함께 작동하도록 테스트되었음을 표시할 수 있기를 바랍니다. 포트가 서로를 제외하도록 허용하면 이러한 테스트에 필요한 빌드 수가 다음과 같이 2^number_of_such_cases증가하므로 이러한 구성을 테스트하는 기능이 중단됩니다. 또한 추가 종속성 설치는 항상 "안전"으로 간주됩니다. 포트 또는 최종 사용자가 해당 요구 사항에 종속성이 설치되지 않았다고 어설션할 수 있는 방법은 없습니다.

사용자에게 이러한 대체 상황을 나타내려면 큐레이된 레지스트리의 연속 통합에서 portfile.cmake 빌드되지 않은 포트를 추가하지 않고 주석으로 대체 양식을 구현하는 오버레이 포트를 만드는 방법을 설명하는 것이 좋습니다. 예를 들어 glad@0.1.36을 참조 하세요.

레지스트리를 도입하기 전에 테스트되지 않은 몇 가지 포트를 대체(예: boringssl제작 오버레이 포트를 더 쉽게 만들 수 있음)를 수락했습니다. 레지스트리는 큐레이팅된 레지스트리를 수정하지 않고 이러한 테스트되지 않은 포트를 게시할 수 있으므로 더 이상 허용되지 않습니다.

PR 구조

포트당 별도의 끌어오기 요청 만들기

가능하면 변경 내용을 여러 PR로 구분합니다. 이렇게 하면 검토하기가 훨씬 쉬워지고 한 일련의 변경 내용으로 인해 다른 모든 변경 내용이 유지되지 않도록 방지할 수 있습니다.

손길이 닿지 않은 파일에서 사소한 변경 방지

예를 들어 현재 문제에 대해 수정할 이유가 없는 포트파일의 변수를 다시 포맷하거나 이름을 변경하지 않도록 합니다. 그러나 PR의 기본 목적(라이브러리 업데이트)을 위해 파일을 수정해야 하는 경우 오타 수정과 같은 분명히 유익한 변경 내용을 확인할 수 있습니다.

다른 리포지토리에 대한 이름 확인

포트 이름은 포트가 설치되는 패키지에 대해 명확하게 설명해야 합니다. 검색 엔진에서 포트 이름을 검색하면 해당 프로젝트로 빠르게 연결되는 것이 이상적입니다. 여러 리포지토리에서 여러 패키지 이름을 한 번에 확인하는 좋은 서비스는 Repology입니다.

이름이 짧거나 일반 단어의 이름을 따서 명명된 프로젝트는 특히 지정된 단어와 강한 연관성이 있는 프로젝트가 없는 경우 명확성이 필요할 수 있습니다. 예를 들어 이름이 ip 지정된 포트는 여러 프로젝트의 이름이 비슷하게 지정될 가능성이 있으므로 허용되지 않습니다.

좋은 명확성의 예는 다음과 같습니다.

리포지토리의 소유자 사용자 이름 또는 조직: google-cloud-cpp.
프로젝트가 속한 라이브러리 모음의 이름은 다음과 boost-dll같습니다.

C++ 및 오픈 소스 프로젝트에서 사용하는 일반적인 접두사 및 접미사는 유효한 명확성자가 아니며, 일부 예에서는 다음을 포함하지만 제한되지는 않습니다.

cpp,
free,
lib,
open,
번호

예를 들어 다음 포트 이름을 ip-cpplibip 비교하고 ip5 잘못된 명확성을 제거할 때 모두 동일한 스템(ip)으로 축소되므로 이름이 같은 것으로 간주됩니다.

단일 프로젝트와 강력하게 연결된 이름에 대해서는 이 지침에 대한 예외가 발생합니다. 예: libpng, openssl 및 zlib

GitHub 초안 PR 사용

GitHub 초안 PR은 아직 병합할 준비가 되지 않은 작업에 대한 CI 또는 사용자 피드백을 얻을 수 있는 좋은 방법입니다. CI가 통과되면 대부분의 새 PR을 초안으로 열고 일반 PR로 변환해야 합니다.

GitHub 초안 PR에 대한 자세한 내용은 초안 끌어오기 요청 소개를 참조 하세요.

포트 파일

사용되지 않는 도우미 함수 방지

현재 다음 도우미는 더 이상 사용되지 않습니다.

vcpkg_extract_source_archive_ex() 은 (with)의 vcpkg_extract_source_archive() 지원되는 오버로드로 ARCHIVE바꿔야 합니다.
사용되지 않는 오버 ARCHIVE 로드는 vcpkg_extract_source_archive() 지원되는 오버로드ARCHIVE로 바꿔야 합니다.
vcpkg_apply_patches()는 "추출" 도우미에 PATCHES 대한 인수로 바꿔야 합니다(예: ). vcpkg_from_github()
vcpkg_build_msbuild() 는 다음으로 바꿔야 합니다. vcpkg_install_msbuild()
vcpkg_copy_tool_dependencies() 는 다음으로 바꿔야 합니다. vcpkg_copy_tools()
vcpkg_configure_cmake 를 제거한 vcpkg_cmake_configure() 후 바꿔야 합니다. PREFER_NINJA
vcpkg_build_cmake 는 다음으로 바꿔야 합니다. vcpkg_cmake_build()
vcpkg_install_cmake 는 다음으로 바꿔야 합니다. vcpkg_cmake_install()
vcpkg_fixup_cmake_targets 는 다음으로 바꿔야 합니다. vcpkg_cmake_config_fixup

일부 대체 도우미 함수는 소비자가 특정 버전에서 동작을 고정하여 특정 버전에서 도우미의 동작을 잠글 수 있도록 하는 "도구 포트"에 있습니다. 다음과 같이 도구 포트를 포트에 "dependencies"추가해야 합니다.

{
  "name": "vcpkg-cmake",
  "host": true
},
{
  "name": "vcpkg-cmake-config",
  "host": true
}

포트파일에서 과도한 주석 방지

이상적으로 포트파일은 짧고 단순하며 가능한 한 선언적이어야 합니다. PR을 제출하기 전에 명령에서 도입한 create 보일러 플레이트 주석을 제거합니다.

포트는 경로에 종속되어서는 안 됩니다.

포트가 설치하는 콘텐츠를 변경하는 양식에 이미 설치된 포트에 따라 해당 동작을 변경해서는 안 됩니다. 예를 들어 다음과 같은 조건이 있습니다.

> vcpkg install a
> vcpkg install b
> vcpkg remove a

및

> vcpkg install b

설치한 파일은 b 이전 설치 a의 영향과 관계없이 동일해야 합니다. 즉, 일부 작업을 수행하기 전에 포트가 설치된 트리에서 다른 포트에 의해 제공된 항목을 검색하지 않아야 합니다. 이러한 "경로 종속" 동작의 구체적이고 일반적인 원인은 아래 "기능을 정의할 때 종속성을 명시적으로 제어"에 설명되어 있습니다.

고유 포트 특성 규칙

전체 vcpkg 시스템에서는 사용자가 동시에 사용할 것으로 예상되는 두 개의 포트가 동일한 파일을 제공할 수 없습니다. 포트가 다른 파일에서 이미 제공한 파일을 설치하려고 하면 설치가 실패합니다. 예를 들어 포트가 헤더에 매우 일반적인 이름을 사용하려는 경우 해당 헤더를 내부가 아닌 include하위 디렉터리에 배치해야 합니다.

이 속성은 레지스트리의 모든 포트를 설치하려고 하는 연속 통합 실행을 통해 정기적으로 확인되며, 두 포트가 동일한 파일을 제공하는 경우 실패 FILE_CONFLICTS 합니다.

비공식 네임스페이스에 CMake 내보내기 추가

vcpkg의 핵심 디자인 이상은 사용자에 대한 "잠금"을 만들지 않는 것입니다. 빌드 시스템에서는 시스템의 라이브러리에 따라 vcpkg의 라이브러리에 따라 차이가 없어야 합니다. 이를 위해 업스트림이 vcpkg와 충돌하지 않고 고유한 공식 CMake 내보내기를 추가할 수 있도록 "명백한 이름"을 사용하여 기존 라이브러리에 CMake 내보내기 또는 대상을 추가하지 않습니다.

이를 위해 업스트림 라이브러리에 없는 포트 내보내기 CMake는 접두사로 사용해야 unofficial- 합니다. 추가 대상은 네임스페이스에 unofficial::<port>:: 있어야 합니다.

즉, 사용자에게 다음이 표시됩니다.

find_package(unofficial-<port> CONFIG) 고유-vcpkg 패키지를 가져오는 방법
unofficial::<port>::<target> 은 해당 포트에서 내보낸 대상입니다.

예:

brotli는 대상unofficial::brotli::brotli을 unofficial-brotli 생성하여 패키지를 만듭니다.

저작권 파일 설치

각 포트는 폴더${CURRENT_PACKAGES_DIR}/share/${PORT}에 명명된 copyright 파일을 제공해야 합니다. 패키지의 라이선스 콘텐츠를 원본 파일 내에서 사용할 수 있는 경우 이 파일을 호출하여 vcpkg_install_copyright()만들어야 합니다. vcpkg_install_copyright 또한 필요한 경우 여러 저작권 파일을 번들로 묶습니다.

vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

이 파일을 수동으로 만드는 이전 메서드는 CMake의 기본 제공 file 명령을 사용하는 것입니다. 새 포트에서는 vcpkg_install_copyright 권장되지 않지만 여전히 허용됩니다.

file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)

업스트림 원본 파일의 라이선스 콘텐츠가 텍스트 형식(예: PDF 파일) copyright 이 아닌 경우 사용자가 라이선스 요구 사항을 찾는 방법에 대한 설명을 포함해야 합니다. 가능하면 이를 나타내는 원래 원본 파일에 대한 링크도 포함해야 하므로 사용자는 최신 상태인지 확인할 수 있습니다.

file(WRITE "${CURRENT_PACKAGES_DIR}/share/${PORT}/copyright" [[As of 2023-07-25, according to
https://github.com/GPUOpen-LibrariesAndSDKs/display-library/blob/master/Public-Documents/README.md#end-user-license-agreement
this software is bound by the "SOFTWARE DEVELOPMENT KIT LICENSE AGREEMENT" PDF located at
https://github.com/GPUOpen-LibrariesAndSDKs/display-library/blob/master/Public-Documents/ADL%20SDK%20EULA.pdf
]])

포트의 버전 제약 조건

포트 내의 버전 제약 조건은 프로젝트의 독립적인 진화를 방해할 수 있으므로 일반적으로 방지해야 합니다. 이러한 제약 조건을 추가하는 것은 특정 이전 버전과 호환되지 않는 것으로 입증된 것과 같이 잘 문서화된 타당성이 있는 경우에만 허용됩니다. 이러한 제약 조건은 독립 프로젝트와의 패리티를 유지하기 위해만 사용해서는 안 됩니다.

기능

기능을 사용하여 대안을 구현하지 마세요.

기능은 추가 기능으로 처리되어야 합니다. 설치 및 port[featureB] 설치하는 port[featureA,featureB] 경우 port[featureA] 설치해야 합니다. 또한 두 번째 포트가 종속 [featureA] 되고 세 번째 포트가 종속된 [featureB]경우 두 번째 포트와 세 번째 포트를 모두 설치하면 해당 종속성이 충족되어야 합니다.

이 상황에서 라이브러리는 vcpkg에 표현된 대로 사용 가능한 옵션 중 하나를 선택해야 하며, 다른 설정을 원하는 사용자는 현재 오버레이 포트를 사용해야 합니다.

이전 버전과의 호환성을 위해 현재는 허용하지 않는 기존 예제:

libgit2, libzipopen62541 모두 TLS 또는 암호화 백 엔드를 선택하는 기능이 있습니다. curl 에는 다른 암호화 백 엔드 옵션이 있지만 런타임에 둘 중에서 선택할 수 있습니다. 즉, 위의 테넌트가 유지됩니다.
darknetopencv3에는 opencv2종속성에 사용할 opencv 버전을 제어하는 기능이 있습니다.

기능은 미리 보기 또는 베타 기능을 사용할 수 있습니다.

위와는 달리 미리 보기 기능이 미리 보기가 아닌 기능(예: API 제거 없음)을 방해하지 않을 가능성이 높은 미리 보기 분기 또는 이와 유사한 경우 이 설정을 모델링할 수 있는 기능이 허용됩니다.

예:

Azure SDK(양식 azure-Xxx)에는 기능이 있습니다 public-preview .
imguiexperimental-docking 에는 각 공개 번호가 매겨진 릴리스에 연결된 병합 커밋을 사용하는 미리 보기 도킹 분기를 사용하는 기능이 있습니다.

기본 기능은 API를 추가하지 않아야 합니다.

기본 기능은 라이브러리를 사용하고 있는지 모르는 고객을 위해 라이브러리의 합리적으로 기능적인 빌드가 설치되도록 하기 위한 것입니다. 라이브러리를 사용하고 있는지 모르는 경우 기능을 나열할 수 없습니다. 예를 들어 libarchive 압축 알고리즘을 사용하도록 설정하는 기능을 기존 제네릭 인터페이스에 노출합니다. 이러한 기능 없이 빌드된 경우 라이브러리에 유틸리티가 없을 수 있습니다.

기본 기능을 사용하지 않도록 설정하는 것은 복잡하기 때문에 기본적으로 기능을 켜야 하는지 여부를 신중하게 고려해야 합니다.

기본 기능을 '전이적' 소비자로 사용하지 않도록 설정하려면 다음이 필요합니다.

모든 고객은 명령줄의 기능 목록을 통해 "default-features": false 또는 명령줄에 포함된 [core] 기본 기능을 명시적으로 사용하지 않도록 설정합니다.
명령줄에 대한 전이적 종속성 vcpkg install 또는 최상위 매니페스트의 직접 종속성 이름 지정

vcpkg의 큐레이팅된 레지스트리에서 기능이 추가 API, 실행 파일 또는 기타 이진 파일을 추가하는 경우 기본적으로 꺼져 있어야 합니다. 확실하지 않은 경우 기능을 기본값으로 표시하지 마세요.

게시된 인터페이스에서 대안을 제어하기 위해 기능을 사용하지 마세요.

포트의 소비자가 해당 포트의 핵심 기능에만 의존하는 경우 높은 확률로 기능을 켜서 끊어서는 안 됩니다. 이는 소비자가 직접 제어하는 것이 아니라 다음과 같은 /std:c++17 / -std=c++17컴파일러 설정에 의해 대체가 제어되는 경우 더욱 중요합니다.

이전 버전과의 호환성을 위해 현재는 허용하지 않는 기존 예제:

redis-plus-plus[cxx17] 는 폴리필을 제어하지만 설치된 트리에 설정을 굽지 않습니다.
ace[wchar]가 아닌 const char*모든 API를 수락 const wchar_t* 하도록 변경합니다.

교체가 설치된 트리에 구워지는 경우 기능이 폴리필을 별칭으로 바꿀 수 있습니다.

위의 내용에도 불구하고 포트는 다음과 같은 경우 기능으로 폴리필을 제거할 수 있습니다.

기능을 켜면 폴리필이 폴리필링된 엔터티의 별칭으로 변경됩니다.
폴리필의 상태가 설치된 헤더에 구워지게 되므로 ABI 불일치 "불가능한" 런타임 오류는 거의 없습니다.
포트 소비자가 두 모드에서 작동하는 코드를 작성할 수 있습니다. 예를 들어 다각형이거나 그렇지 않은 typedef를 사용할 수 있습니다.

예시:

abseil[cxx17]대체 또는 std::string_view패치로 변경 absl::string_view 하면 베이킹 요구 사항이 구현됩니다.

권장 솔루션

기본 대안을 노출하는 것이 중요한 경우 빌드 시 사용자에게 포트를 프라이빗 오버레이로 복사하는 방법을 지시하는 메시지를 제공하는 것이 좋습니다.

set(USING_DOG 0)
message(STATUS "This version of LibContoso uses the Kittens backend. To use the Dog backend instead, create an overlay port of this with USING_DOG set to 1 and the `kittens` dependency replaced with `dog`.")
message(STATUS "This recipe is at ${CMAKE_CURRENT_LIST_DIR}")
message(STATUS "See the overlay ports documentation at https://github.com/microsoft/vcpkg/blob/master/docs/specifications/ports-overlay.md")

빌드 기술

공급업체 종속성 사용 안 함

라이브러리의 포함된 복사본을 사용하지 마세요. 모든 종속성을 분할하고 별도로 패키징하여 업데이트하고 유지 관리해야 합니다.

CMake를 사용하는 것이 좋습니다.

여러 빌드 시스템을 사용할 수 있는 경우 CMake를 사용하는 것이 좋습니다. 또한 적절한 경우 지시문을 사용하여 file(GLOB) 대체 빌드 시스템을 CMake로 다시 작성하는 것이 더 쉽고 유지 관리가 용이할 수 있습니다.

예: abseil

정적 또는 공유 이진 파일 선택

CMake 라이브러리를 vcpkg_cmake_configure() 빌드할 때 사용자의 요청된 변형에 BUILD_SHARED_LIBS 따라 올바른 값을 전달합니다.

를 사용하여 string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" ...)대체 구성 매개 변수를 계산할 수 있습니다.

# portfile.cmake

string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED)

vcpkg_cmake_configure(
    SOURCE_PATH ${SOURCE_PATH}
    OPTIONS
        -DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC}
        -DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED}
)

라이브러리에서 빌드 변형을 선택하는 구성 옵션을 제공하지 않는 경우 빌드를 패치해야 합니다. 빌드를 패치할 때는 항상 포트의 향후 유지 관리를 최대화해야 합니다. 일반적으로 이는 현재 문제를 해결하기 위해 처리해야 하는 줄 수를 최소화하는 것을 의미합니다.

예: 원치 않는 변형을 빌드하지 않도록 CMake 라이브러리 패치

예를 들어 CMake 기반 라이브러리를 패치할 때 원치 않는 대상에 추가하고 EXCLUDE_FROM_ALL 호출if(BUILD_SHARED_LIBS)을 래핑 install(TARGETS ...) 하는 것으로 충분할 수 있습니다. 이는 원치 않는 변형을 언급하는 모든 줄을 래핑하거나 삭제하는 것보다 짧습니다.

다음 내용이 포함된 프로젝트의 CMakeLists.txt 경우:

add_library(contoso SHARED contoso.c)
add_library(contoso_static STATIC contoso.c)

install(TARGETS contoso contoso_static EXPORT ContosoTargets)

install(EXPORT ContosoTargets
  FILE ContosoTargets
  NAMESPACE contoso::
  DESTINATION share/contoso)

install(TARGETS) 줄만 패치해야 합니다.

add_library(contoso SHARED contoso.c)
add_library(contoso_static STATIC contoso.c)

if(BUILD_SHARED_LIBS)
  set_target_properties(contoso_static PROPERTIES EXCLUDE_FROM_ALL 1)
  install(TARGETS contoso EXPORT ContosoTargets)
else()
  set_target_properties(contoso PROPERTIES EXCLUDE_FROM_ALL 1)
  install(TARGETS contoso_static EXPORT ContosoTargets)
endif()

install(EXPORT ContosoTargets
  FILE ContosoTargets
  NAMESPACE contoso::
  DESTINATION share/contoso)

기능을 정의할 때 종속성을 명시적으로 제어합니다.

선택적 종속성을 캡처하는 기능을 정의할 때 기능이 명시적으로 사용하도록 설정되지 않은 경우 종속성이 실수로 사용되지 않도록 합니다.

set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB OFF)
if ("zlib" IN_LIST FEATURES)
  set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
  set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB ON)
endif()

vcpkg_cmake_configure(
  SOURCE_PATH ${SOURCE_PATH}
  OPTIONS
    -DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
    -DCMAKE_REQUIRE_FIND_PACKAGE_ZLIB=${CMAKE_REQUIRE_FIND_PACKAGE_ZLIB}
)

아래 사용 vcpkg_check_features() 코드 조각은 동일합니다.

vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
  FEATURES
    "zlib"    CMAKE_REQUIRE_FIND_PACKAGE_ZLIB
  INVERTED_FEATURES
    "zlib"    CMAKE_DISABLE_FIND_PACKAGE_ZLIB
)

vcpkg_cmake_configure(
    SOURCE_PATH ${SOURCE_PATH}
    OPTIONS
      ${FEATURE_OPTIONS}
)

ZLIB 코드 조각에서 대/소문자를 구분합니다. 자세한 내용은 설명서 및 CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> 문서를 참조 CMAKE_DISABLE_FIND_PACKAGE_<PackageName> 하세요.

디렉터리에 충돌하는 라이브러리 배치 `manual-link`

lib는 다음 중 어느 것을 수행하는 경우 충돌하는 것으로 간주됩니다.

정의 main
malloc 정의
다른 라이브러리에도 선언된 기호 정의

충돌하는 라이브러리는 일반적으로 설계되었으며 결함으로 간주되지 않습니다. 일부 빌드 시스템은 lib 디렉터리의 모든 항목에 연결되므로 이름이 지정된 manual-link하위 디렉터리로 이동해야 합니다.

버전 관리

필드에 대한 일반적인 규칙 따르기 `"version"`

새 포트를 만들 때 패키지 작성자가 사용하는 버전 관리 규칙을 따릅니다. 포트를 업데이트할 때 업스트림이 달리 명시하지 않는 한 동일한 규칙을 계속 사용합니다. 규칙에 대한 전체 설명은 버전 관리 설명서를 참조하세요.

업스트림에서 릴리스를 게시하지 않은 경우 최신 변경 내용을 가져오기 위해 포트의 버전 관리 체계 version-date 를 변경하지 마세요. 이러한 커밋에는 프로덕션 준비가 되지 않은 변경 내용이 포함될 수 있습니다. 대신 업스트림 리포지토리에 새 릴리스를 게시하도록 요청합니다.

수정된 `"port-version"` 포트의 매니페스트 파일에서 필드 업데이트

vcpkg는 이 필드를 사용하여 지정된 포트가 만료되었는지 여부를 확인하고 포트의 동작이 변경될 때마다 변경해야 합니다.

이 규칙은 업스트림 버전을 변경하지 않는 포트에 대한 변경에 필드를 사용하고 "port-version" 업스트림 버전에 대한 업데이트가 이루어질 때 다시 0으로 다시 설정하는 "port-version" 것입니다.

예를 들면 다음과 같습니다.

Zlib의 패키지 버전은 현재 1.2.1명시적 "port-version" ("port-version"0해당)이 없습니다.
잘못된 저작권 파일이 배포된 것을 발견하고 포트파일에서 수정했습니다.
매니페스트 파일1의 "port-version" 필드를 .로 업데이트해야 합니다.

자세한 내용은 버전 관리 설명서를 참조하세요.

수정된 포트의 `versions/` 버전 파일 업데이트

vcpkg는 메타데이터 파일 집합을 사용하여 버전 관리 기능을 지원합니다. 이러한 파일은 다음 위치에 있습니다.

${VCPKG_ROOT}/versions/baseline.json, (이 파일은 모든 포트에 공통) 및
${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json (포트당 하나씩).

예를 들어 관련 파일의 경우 zlib 다음과 같습니다.

${VCPKG_ROOT}/versions/baseline.json
${VCPKG_ROOT}/versions/z-/zlib.json

포트를 업데이트할 때마다 해당 버전 파일도 업데이트할 것으로 예상됩니다.

이러한 파일을 업데이트하는 권장 방법은 다음과 같은 명령을 실행하는 x-add-version 것입니다.

vcpkg x-add-version zlib

여러 포트를 동시에 업데이트하는 경우 다음을 실행할 수 있습니다.

vcpkg x-add-version --all

수정된 모든 포트에 대한 파일을 한 번에 업데이트합니다.

참고 항목

이러한 명령을 실행하려면 포트를 실행하기 전에 변경 내용을 커밋해야 합니다. 그 이유는 이러한 버전 파일에서 포트 디렉터리의 Git SHA가 필요하기 때문입니다. 하지만 커 x-add-version 밋되지 않은 로컬 변경 내용이 있는 경우 명령이 경고합니다.

자세한 내용은 버전 관리 참조 및 레지스트리 만들기를 참조하세요.

패치

vcpkg는 배포하는 구성 요소의 최종 소유자가 아닌 패키징 솔루션입니다. 플랫폼과의 구성 요소 호환성 또는 구성 요소의 호환성을 개선하기 위해 경우에 따라 패치를 적용해야 합니다.

다음과 같은 패치를 방지하려고 합니다.
- 업스트림은
- 취약성 또는 충돌 원인
- 업스트림 버전 업데이트에서 유지 관리할 수 없습니다.
- 은 vcpkg 리포지토리 자체와 라이선스 얽힘을 일으킬 만큼 충분히 큽

업스트림 소유자에게 업스트림 관련 패치 알림

패치가 업스트림에서 유용할 수 있는 경우 업스트림에 패치의 콘텐츠에 대한 알림을 받아야 합니다. (종속성 배포와 같이 업스트림과 관련이 없는 vcpkg 관련 동작을 적용하는 패치는 알림이 필요하지 않습니다.)

업스트림이 패치에 동의하지 않는 상황을 방지하기 위해 이러한 패치를 적용하기 위해 최소 30일을 기다립니다.

변경 내용이 정확하다는 확신이 높은 경우 이 대기 기간을 건너뜁니다. 높은 신뢰도 패치의 예로는 다음이 포함되지만 제한되지는 않습니다.

업스트림이 패치로 수락한 경우(예: 끌어오기 요청 업스트림에서 특정 변경 내용 백포팅이 병합됨)
누락된 #includes를 추가합니다.
작고 명백한 제품 코드 수정(예: 초기화되지 않은 변수 초기화).
테스트 또는 예제와 같은 빌드의 관련 없는 vcpkg 구성 요소를 사용하지 않도록 설정

패치보다 옵션 선호

설정을 직접 패치하는 동안 호출 vcpkg_configure_xyz() 에서 옵션을 설정하는 것이 좋습니다.

패치를 방지할 수 있는 일반적인 옵션:

[MSBUILD] <PropertyGroup> 매개 변수를 통해 /p: 프로젝트 파일 내의 설정을 재정의할 수 있습니다.
[CMAKE] find_package(XYz) CMake 스크립트의 호출은 다음을 통해 비활성화할 수 있습니다. -DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON
[CMAKE] 캐시 변수(또는 로 set(VAR "value" CACHE STRING "Documentation") option(VAR "Documentation" "Default Value")선언됨)는 명령줄에서 로 -DVAR:STRING=Foo전달하여 재정의할 수 있습니다. 한 가지 주목할 만한 예외는 매개 변수가 FORCE .에 set()전달되는 경우입니다. 자세한 내용은 CMake set 설명서를 참조하세요.

포트에 체크 인하는 대신 승인된 패치를 다운로드하는 것이 좋습니다.

승인되거나 병합된 패치 파일을 업스트림에서 가져올 수 있는 경우 포트는 이를 다운로드하여 포트 파일의 일부로 사용하는 대신 적용해야 합니다. 이 프로세스는 다음과 같은 이유로 선호됩니다.

업스트림이 패치 변경 내용을 수락했는지 확인합니다.
onus 업스트림을 이동하여 검토 프로세스를 간소화합니다.
패치를 사용하지 않는 사용자의 vcpkg 리포지토리 크기를 줄입니다.
vcpkg 리포지토리와 라이선스 충돌 방지

SHA 충돌을 방지하려면 안정적인 엔드포인트에서 패치를 다운로드해야 합니다. 끌어오기 요청에서 패치 파일을 다운로드하거나 GitHub 및 GitLab에서 커밋할 때 매개 변수를 ?full_index=1 다운로드 URL에 추가해야 합니다.

예:

https://github.com/google/farmhash/pull/40.diff?full_index=1
https://github.com/linux-audit/audit-userspace/commit/f8e9bc5914d715cdacb2edc938ab339d5094d017.patch?full_index=1
https://gitlab.kitware.com/paraview/paraview/-/merge_requests/6375.diff?full_index=1

값 재정의를 패치하는 것이 좋습니다.`VCPKG_<VARIABLE>`

접두사로 접두사로 VCPKG_<VARIABLE> 지정된 일부 변수에는 해당하는 CMAKE_<VARIABLE>변수가 있습니다. 그러나 모든 패키지가 내부 패키지 빌드 에 전달되는 것은 아닙니다(구현 참조: Windows 도구 체인).

다음 예시를 참조하세요.

set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}")
set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}")

기본 제공 도구 체인을 사용하면 vcpkg값 VCPKG_<LANG>_FLAGS 이 적절한 CMAKE_LANG_FLAGS 변수로 전달되기 때문에 작동합니다. 그러나 '의 변수를 인식하지 vcpkg못하는 사용자 지정 도구 체인은 전달하지 않습니다.

이 때문에 설정할 CMAKE_<LANG>_FLAGS때 빌드 시스템을 직접 패치하는 것이 좋습니다.

패치 최소화

라이브러리를 변경할 때 최종 차이 최소화를 위해 노력합니다. 즉, 지역에 영향을 주는 변경을 수행할 때 업스트림 소스 코드를 다시 포맷해서는 안 됩니다. 조건부를 사용하지 않도록 설정하는 경우 조건부의 모든 줄을 삭제하는 것보다 조건을 추가하거나 && 0 조건에 추가하는 AND FALSE 것이 좋습니다. 큰 지역을 사용하지 않도록 설정해야 하는 경우 패치의 모든 줄을 삭제하는 대신 지역 주위에 추가하거나 #if 0 주변에 추가하는 if(0) 것이 더 짧습니다.

포트가 오래된 경우 패치를 추가하지 마세요. 최신 릴리스 버전으로 포트를 업데이트하면 동일한 문제가 해결됩니다. vcpkg는 오래된 버전 패치보다 포트를 업데이트하는 것을 선호합니다.

이렇게 하면 vcpkg 리포지토리의 크기를 줄이면서 패치가 향후 코드 버전에 적용될 가능성을 높일 수 있습니다.

패치에서 기능 구현 안 함

vcpkg에서 패치를 적용하는 목적은 컴파일러, 라이브러리 및 플랫폼과의 호환성을 사용하도록 설정하는 것입니다. 적절한 오픈 소스 프로시저(문제/PR/등 제출)를 따르는 대신 새 기능을 구현하지 않습니다.

기본적으로 테스트/문서/예제를 빌드하지 마세요.

새 포트를 제출할 때 같은 BUILD_TESTS 옵션을 확인하거나 WITH_TESTS POCO_ENABLE_SAMPLES 추가 이진 파일을 사용하지 않도록 설정했는지 확인합니다. 이렇게 하면 평균 사용자에 대한 빌드 시간과 종속성이 최소화됩니다.

필요에 따라 테스트를 빌드할 수 있는 기능을 추가할 test 수 있지만 목록에 있으면 안 됩니다 Default-Features .

라이브러리의 기존 사용자가 vcpkg로 전환할 수 있도록 설정

추가 안 함 `CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS`

라이브러리 작성자가 이미 사용하고 있지 않으면 C++ 템플릿과 제대로 상호 작용하지 않고 특정 컴파일러 기능을 중단하므로 이 CMake 기능을 사용하면 안 됩니다. .def 파일을 제공하지 않고 __declspec() 선언을 사용하지 않는 라이브러리는 단순히 Windows용 공유 빌드를 지원하지 않으며 다음과 vcpkg_check_linkage(ONLY_STATIC_LIBRARY)같이 표시되어야 합니다.

업스트림에서 지정한 이름 외부에 있는 이진 파일의 이름을 바꾸지 마세요.

즉, 업스트림 라이브러리의 릴리스 및 디버그 이름(libx 및 libxd)이 서로 다른 경우 디버그 라이브러리의 이름을 바꿔 libx서는 안 됩니다. 그 반대로, 업스트림 라이브러리가 릴리스 및 디버그에서 동일한 이름을 갖는 경우 새 이름을 도입해서는 안 됩니다.

중요한 주의 사항:

정적 및 공유 변형의 이름을 일반적인 체계로 바꿔야 하는 경우가 많습니다. 이를 통해 소비자는 일반 이름을 사용하고 다운스트림 연결을 무시할 수 있습니다. 한 번에 하나씩만 사용할 수 있기 때문에 안전합니다.

라이브러리에서 CMake 통합 파일()foo-config.cmake을 생성하는 경우 단순히 출력 보관 파일/LIB를 호출 file(RENAME) 하는 대신 CMake 빌드 자체를 패치하여 이름을 변경해야 합니다.

마지막으로 Windows의 DLL 파일은 생성된 LIB를 중단하므로 빌드 후 이름을 바꿔서는 안 됩니다.

매니페스트

매니페스트 파일의 형식을 지정해야 합니다. 다음 명령을 사용하여 모든 매니페스트 파일의 서식을 지정합니다.

> vcpkg format-manifest --all

쌍둥이

현재는 비공동체 트리플렛을 추가하라는 요청을 수락하지 않습니다. 커뮤니티에서 전체 트리플렛 상태로의 승격은 주로 하드웨어가 이러한 삼중항을 테스트하기 위한 예산을 기반으로 하며, 사람들이 실제로 사용하는 것이 완전히 테스트될 가능성을 최대화하기 위해 vcpkg에서 제출한 메트릭에 의해 구동됩니다.

다음과 같은 경우 커뮤니티 트리플렛을 추가합니다.

그것은 사람들이 실제로 그 지역 사회 트리플렛을 사용하는 것으로 입증된다; 그리고
우리는 그러한 세 쌍둥이가 깨진 것을 알지 못합니다.

예를 들어 작성자가 실제로 이러한 항목을 사용할 것임을 나타내는 대신 "집합을 완료"하려고 했기 때문에 삼중 https://github.com/microsoft/vcpkg/pull/29034 자를 추가하지 않았으며, 결과를 재배치할 수 있도록 하는 patchelf 솔루션이 생성될 때까지 Linux 동적을 추가하지 않았습니다.

유용한 구현 정보

포트파일은 스크립트 모드에서 실행됩니다.

portfile.cmake's 및 CMakeLists.txt's는 일반적인 구문과 핵심 CMake 언어 구문(즉, "스크립팅 명령")을 공유하지만 포트파일은 "스크립트 모드"에서 실행되는 반면 CMakeLists.txt 파일은 "프로젝트 모드"에서 실행됩니다. 이러한 두 모드 간의 가장 중요한 차이점은 "스크립트 모드"에 "도구 체인", "언어" 및 "대상" 개념이 없다는 것입니다. 이러한 구문(예: CMAKE_CXX_COMPILER, CMAKE_EXECUTABLE_SUFFIXCMAKE_SYSTEM_NAME)에 따라 달라지는 스크립팅 명령을 비롯한 모든 동작은 올바르지 않습니다.

포트파일은 삼중항 파일에 설정된 변수에 직접 액세스할 수 있지만 CMakeLists.txt그렇지 않습니다(대 번역이 발생하는 VCPKG_LIBRARY_LINKAGE BUILD_SHARED_LIBS경우가 많지만).

포트파일에서 호출된 포트파일 및 프로젝트 빌드는 서로 다른 프로세스에서 실행됩니다. 개념적:

+----------------------------+       +------------------------------------+
| CMake.exe                  |       | CMake.exe                          |
+----------------------------+       +------------------------------------+
| Triplet file               | ====> | Toolchain file                     |
| (x64-windows.cmake)        |       | (scripts/buildsystems/vcpkg.cmake) |
+----------------------------+       +------------------------------------+
| Portfile                   | ====> | CMakeLists.txt                     |
| (ports/foo/portfile.cmake) |       | (buildtrees/../CMakeLists.txt)     |
+----------------------------+       +------------------------------------+

포트파일의 호스트를 확인하기 위해 표준 CMake 변수는 괜찮습니다(CMAKE_HOST_WIN32).

포트파일에서 대상을 확인하려면 vcpkg triplet 변수를 사용해야 합니다(VCPKG_CMAKE_SYSTEM_NAME).

가능한 설정의 전체 열거형은 삼중 설명서도 참조하세요.

다음을 통해 공유