레지스트리 개념

개요

vcpkg는 다양한 라이브러리가 패키지된 포트를 https://github.com/Microsoft/vcpkg의에서 호스팅합니다. 이 포트 컬렉션은 큐레이팅된 레지스트리이라고 불립니다. 그러나 vcpkg는 큐레이팅된 레지스트리로 제한되지 않습니다. 사용자는 사용자 지정 레지스트리를 만들어 포트 선택을 확장할 수 있습니다.

레지스트리는 특정 구조로 정렬된 포트 및 도우미 파일의 컬렉션입니다. 레지스트리 구조에 따라 레지스트리에 포함된 포트는 큐레이팅된 레지스트리의 포트에 제공되는 동일한 기능(버전 관리, 이진 캐싱)을 사용하여 설치할 수 있습니다.

현재 세 가지 종류의 레지스트리가 있습니다.

• 기본 제공 레지스트리.
• Git 레지스트리및
• 파일 시스템 레지스트리 .

vcpkg는 vcpkg-configuration.json 파일사용하여 사용자 지정 레지스트리에서 사용할 수 있는 포트를 고려하도록 지시할 수 있습니다. 프로젝트에서 사용자 지정 레지스트리를 사용하는 방법에 대한 자습서는 자습서: Git 기반 레지스트리 문서에서 종속성 설치를 참조하세요.

레지스트리 구조

vcpkg가 레지스트리와 인터페이스하려면 다음 구조를 준수해야 합니다.

• ports 디렉터리에는 각 하위 디렉터리에 하위 디렉터리 이름과 일치하는 특정 포트가 포함된 포트 컬렉션이 포함됩니다. 예를 들어 포트 foo 파일은 ports/foo에 위치해 있습니다.
• versions 디렉터리에는 버전 데이터베이스구성하는 파일이 포함되어 있습니다.

예: 레지스트리 구조

ports/
  foo/
    portfile.cmake
    vcpkg.json
versions/
  f-/
    foo.json
  baseline.json

버전 데이터베이스

모든 레지스트리는 버전 데이터베이스포함하는 레지스트리의 루트에 versions 디렉터리를 포함합니다.

버전 데이터베이스에는 두 가지 구성 요소가 있습니다.

• 기준 파일
• 버전 파일

기준 파일은 versions 디렉터리의 루트에 있는 baseline.json JSON 파일입니다.

버전 파일은 사용 가능한 포트와 이름이 같은 JSON 파일입니다. 그것들은 versions/<prefix>/<port name>.json에 있어야 하며, 여기서 <prefix>은 포트 이름의 첫 글자 뒤에 하이픈이 붙습니다. 예를 들어 포트 foo 버전 파일은 versions/f-/foo.json있어야 합니다.

버전 파일의 용도는 두 배입니다.

• 각 포트의 사용 가능한 모든 버전 나열
• 각 버전의 검색 위치를 가리킵니다.

버전 파일의 형식은 레지스트리의 종류에 따라 달라집니다.

기준 파일

모든 레지스트리는 종류에 관계없이 versions/baseline.json에 위치한 baseline.json 파일을 포함해야 합니다.

기준 파일의 목적은 레지스트리의 모든 포트에 대한 최신 버전으로 간주되는 버전 집합을 설명하는 것입니다. 이 파일은 새 버전의 포트가 레지스트리에 추가될 때마다 업데이트될 것으로 예상됩니다.

이 파일은 속성이 기준 개체라는 단일 개체로 구성된 JSON 파일입니다. 각 기준 개체의 속성은 포트 이름이며, 해당 값은 버전 항목입니다. 레지스트리 참조 문서에서는 기준 파일의 레이아웃을 자세히 설명합니다.

각 기준 버전 항목은 다음 속성을 가진 개체입니다.

• baseline: 값은 해당 vcpkg.json 파일과 일치하는 포트의 버전입니다.
• port-version: 해당 vcpkg.json 파일과 일치하는 포트의 port-version 값입니다.

기준 파일 예제

{
  "default": {
    "foo": { "baseline": "1.0.0", "port-version": 0 },
    "bar": { "baseline": "2024-08-01", "port-version": 1 },
    "baz": { "baseline": "vista-xp", "port-version": 0 }
  }
}

참고 문서를 참조하세요.

• Git 레지스트리 대한 기준 파일 레이아웃
• 파일 시스템 레지스트리 대한 기준 파일 레이아웃

버전 파일들

레지스트리의 각 포트에는 해당 버전 파일이 있습니다. 버전 파일은 versions/<prefix>/<port name>.json 저장됩니다. 여기서 <prefix> 포트 이름의 첫 글자 뒤에 하이픈이 잇습니다. 예를 들어 포트 foo 대한 버전 파일은 versions/f-/foo.json.

버전 파일의 용도는 두 배입니다.

• 각 포트의 사용 가능한 모든 버전 나열
• 이러한 각 버전의 검색 위치를 가리킵니다.

버전 파일의 레이아웃은 "versions" 배열을 포함하는 개체이며 해당 배열의 각 항목은 버전 개체입니다. 버전 개체에는 다음 속성이 포함되어야 합니다.

• 버전 속성: 속성의 키와 값은 vcpkg.json 파일의 포트에서 사용하는 키와 일치해야 합니다. 키는 version, version-semver, version-date또는 version-string; 중 하나여야 합니다. 이 값은 포트의 매니페스트 파일(vcpkg.json)에 표시되는 버전이어야 합니다.
• port-version: 값은 포트의 port-version이 포트의 vcpkg.json 파일에 나타나는 대로의 값입니다.
• git-tree: (Git 레지스트리에서만) 값은 포트의 디렉터리에 해당하는 git-tree SHA입니다. 이는 포트 디렉터리의 내용을 해시하여 계산된 SHA입니다. Git에서 이 git-tree SHA를 사용하여 제공된 git-tree와 일치하는 포트의 콘텐츠를 검색할 수 있습니다. 이렇게 하면 vcpkg가 레지스트리 Git 기록에서 이전 버전의 포트를 검색할 수 있습니다. 지정된 포트 버전에 대해 이 값을 가져오는 방법을 알아보려면 git 레지스트리 섹션을 참조하세요.
• path: (파일 시스템 레지스트리에서만) 값은 특정 버전의 포트 파일을 포함하는 디렉터리의 전체 경로입니다.

파일 시스템 레지스트리 버전 파일의 예

{
  "versions": [
    {
      "path": "$/ports/foo/1.2.0",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.1.0",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.0.0",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

자세한 내용은 참조 문서를 확인하세요.

• Git 레지스트리 대한 버전 파일 레이아웃
• 파일 시스템 레지스트리 대한 버전 파일 레이아웃

기본 제공 레지스트리

기본 제공 레지스트리는 특수한 종류의 레지스트리입니다. 클래식 모드사용되는 기본 레지스트리입니다. 매니페스트 모드기본 레지스트리 지정되지 않은 경우 vcpkg는 기본 제공 레지스트리를 암시적으로 사용합니다.

내장 레지스트리는 https://github.com/Microsoft/vcpkg에서 vcpkg 리포지토리를 git clone할 때 생성된 관리된 레지스트리의 로컬 복사본을 나타냅니다. 일부 작업은 VCPKG_ROOT 환경 변수가 기본 제공 레지스트리를 가리키는 것을 기대합니다.

"간단한 명령어" 또는 Visual Studio 설치 관리자를 통해 vcpkg를 가져오는 경우, 내장된 레지스트리는 https://github.com/Microsoft/vcpkg 리포지토리를 가리키는 Git 레지스트리와 동일하게 됩니다.

Git 레지스트리

Git 레지스트리는 레지스트리 구조를 따르고 Git의 기능을 활용하여 레지스트리의 포트에 대한 버전 관리 기능을 제공하는 리포지토리입니다. https://github.com/Microsoft/vcpkg 큐레이팅된 레지스트리는 Git 레지스트리의 구현입니다.

Git 레지스트리는 모든 Git 리포지토리 공급자에서 호스트할 수 있으므로 선택한 Git 호스팅 서비스를 사용하여 사용자 지정 레지스트리에 대한 액세스를 제어하는 동시에 레지스트리를 쉽게 공유할 수 있습니다.

Git 레지스트리는 사용자 지정 레지스트리를 구현하는 데 권장되는 방법입니다. 버전 관리 메커니즘은 큐레이팅된 레지스트리에서 사용하는 것과 동일하므로 Git 레지스트리는 x-add-version 사용하여 버전 데이터베이스 파일을 관리할 수 있습니다.

Git 레지스트리의 구현 세부 정보는 레지스트리 참조 참조하세요.

Git 레지스트리에 새 버전 추가

x-add-version 명령을 사용하여 레지스트리에 새 포트 또는 새 버전을 추가할 수 있습니다. 이 명령을 사용하여 버전을 추가할 때 유의해야 할 몇 가지 사항이 있습니다.

중요하다

새 버전을 추가할 때 버전 기록을 다시 작성하지 않으려면 항상 포트의 선언된 버전을 아직 게시되지 않은 버전으로 업데이트해야 합니다.

포트를 변경하는 경우 첫 번째 단계는 vcpkg.json 파일에서 해당 버전을 늘리는 것입니다. 변경 내용에 패키지의 업스트림 버전에 대한 업데이트가 포함된 경우 port-version0;로 설정해야 합니다. 그렇지 않으면 port-version 하나씩 늘려야 합니다.

x-add-version 명령 버전 데이터베이스를 업데이트하기 전에 모든 포트 변경 내용을 리포지토리에 커밋해야 합니다.

예: Git 레지스트리에 새 포트 버전 추가

git add ports/foo/.
git commit -m "Temporary commit"
vcpkg x-add-version --x-builtin-ports-root=./ports --x-builtin-registry-versions-dir=./versions foo
added version 1.0.0#1 to path/to/registry/versions/f-/foo.json
added version 1.0.0#1 to path/to/registry/versions/baseline.json

--x-builtin-ports-root 및 --x-builtin-registry-versions-dir 리디렉션 옵션은 레지스트리의 ports 및 versions 디렉터리를 각각 가리킵니다.

x-add-version 명령이 성공적으로 실행되면 버전 파일 변경 내용을 포함하도록 마지막 커밋을 수정합니다.

git commit --amend -m "Update foo to new version"

파일 시스템 레지스트리

파일 시스템 레지스트리는 파일 시스템에 있는 레지스트리의 구현입니다. 일반적인 레지스트리 구조를 따르지만 Git을 사용하여 버전 관리 기능을 제공하지는 않습니다. 대신 포트의 각 버전에 대해 고유한 경로를 사용하여 기본 형식의 버전 제어를 사용합니다.

이러한 종류의 레지스트리는 포트의 테스트 장이 되거나 Git이 아닌 버전 제어 시스템의 레지스트리에 대한 대안을 제공하는 데 적합합니다. 파일 시스템 레지스트리는 대용량 포트 컬렉션에는 권장되지 않으며 이러한 종류의 레지스트리에 대한 버전 데이터베이스 파일을 조작하기 위한 도구가 제공되지 않습니다.

파일 시스템 레지스트리를 구현하는 방법에 대한 자세한 내용은 레지스트리 참조 참조하세요.

레지스트리 사용

프로젝트에서 사용자 지정 레지스트리를 사용하려면 프로젝트의 매니페스트 파일(vcpkg.json)옆에 구성 파일(vcpkg-configuration.json) 만들어야 합니다.

기본 레지스트리

포트 이름을 확인하는경우 포트 이름이 registries 배열다른 레지스트리에서 선언한 패키지 패턴과 일치하지 경우 기본 레지스트리가 대체(fallback)로 작동합니다.

사용자 지정 레지스트리에 참여하지 않는 사용자의 편의를 위해 vcpkg는 기본 레지스트리로 기본 제공 레지스트리를 암시적으로 추가합니다. 이 동작을 변경하려면 기본 레지스트리를 다른 레지스트리로 설정하거나 완전히 비활성화할 수 있습니다. default-registry 속성입니다.

예: 사용자 지정 레지스트리를 기본값으로 설정

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  }
}

예: 기본 레지스트리 사용 안 함

vcpkg-configuration.json

{
  "default-registry": null
}

레지스트리 배열

vcpkg를 사용하여 설치할 수 있는 포트 선택을 확장하려면 registries 배열사용하여 추가 레지스트리를 지정할 수 있습니다.

예: 구성에 사용자 지정 레지스트리 추가

메모

레지스트리 종류에 따라 registries 배열에 다른 정보를 제공해야 할 수 있습니다. 각 레지스트리 종류에 필요한 속성을 알아보려면 vcpkg-configurtion.json 참조 참조하세요.

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://my.privateregistry.git",
      "baseline": "caf6b70db5784a143e4f28d05c480fa4c41df4a8",
      "packages": [ "foo" ]
    },
    {
      "kind": "filesystem",
      "path": "C:/path/to/registry",
      "baseline": "baseline1",
      "packages": [ "bar" ]
    }
  ]
}

레지스트리에 대한 권장 사례

버전 기록을 다시 작성하지 마세요.

버전이 버전 파일에 게시되면 git 레지스트리나 파일 시스템 레지스트리의 디렉터리에서 연결된 git-tree를 변경하지 마세요.

vcpkg의 디자인 원칙 중 하나는 설치된 종속성의 버전이 사용자 개입 없이 변경되지 않는다는 것입니다. git-tree 항목을 변경하여 버전 파일 기록을 다시 작성하는 것은 이 원칙을 위반합니다.

기존 버전에 문제가 있는 경우 새 port-version만드는 것이 좋습니다.

버전 파일 삭제 안 함

메모

이 섹션은 Git 레지스트리에만 적용됩니다

레지스트리에서 포트를 제거할 때 포트 디렉터리 및 기준 파일의 항목에서 해당 콘텐츠를 제거합니다. 그러나 연결된 버전 파일을 제거하지 마십시오.

버전 파일이 남아 있는 한 레지스트리에 포트가 더 이상 없더라도 포트 사용자는 버전 overrides사용하여 이전 버전을 설치할 수 있습니다.

다음 단계

다음에 시도할 몇 가지 작업은 다음과 같습니다.

• 사용자 고유의 Git 기반 레지스트리 만들기
• 사용자 지정 레지스트리에서 패키지 설치
• 레지스트리 참조 설명서 읽기