diff --git a/purl-types-index.json b/purl-types-index.json index 6941ab2c..24535198 100644 --- a/purl-types-index.json +++ b/purl-types-index.json @@ -36,6 +36,7 @@ "rpm", "swid", "swift", + "vcpkg", "vscode-extension", "yocto" ] diff --git a/tests/types/vcpkg-test.json b/tests/types/vcpkg-test.json new file mode 100644 index 00000000..cc01eea1 --- /dev/null +++ b/tests/types/vcpkg-test.json @@ -0,0 +1,97 @@ +{ + "$schema": "https://packageurl.org/schemas/purl-test.schema-0.1.json", + "tests": [ + { + "description": "simple vcpkg purl", + "test_group": "base", + "test_type": "parse", + "input": "pkg:vcpkg/bzip2@1.0.8", + "expected_output": { + "type": "vcpkg", + "namespace": null, + "name": "bzip2", + "version": "1.0.8", + "qualifiers": null, + "subpath": null + }, + "expected_failure": false, + "expected_failure_reason": null + }, + { + "description": "vcpkg with port_version", + "test_group": "base", + "test_type": "parse", + "input": "pkg:vcpkg/bzip2@1.0.8?port_version=6", + "expected_output": { + "type": "vcpkg", + "namespace": null, + "name": "bzip2", + "version": "1.0.8", + "qualifiers": { + "port_version": "6" + }, + "subpath": null + }, + "expected_failure": false, + "expected_failure_reason": null + }, + { + "description": "vcpkg non-default git registry", + "test_group": "base", + "test_type": "parse", + "input": "pkg:vcpkg/ffmpeg@5.1.2?repository_url=https://github.com/azure-sdk/vcpkg&port_version=3", + "expected_output": { + "type": "vcpkg", + "namespace": null, + "name": "ffmpeg", + "version": "5.1.2", + "qualifiers": { + "repository_url": "https://github.com/azure-sdk/vcpkg", + "port_version": "3" + }, + "subpath": null + }, + "expected_failure": false, + "expected_failure_reason": null + }, + { + "description": "vcpkg filesystem registry or overlay port", + "test_group": "base", + "test_type": "parse", + "input": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg&port_version=3", + "expected_output": { + "type": "vcpkg", + "namespace": null, + "name": "llvm", + "version": "15.0.7", + "qualifiers": { + "repository_url": "file:///C:/local-registry/vcpkg", + "port_version": "3" + }, + "subpath": null + }, + "expected_failure": false, + "expected_failure_reason": null + }, + { + "description": "vcpkg with additional qualifiers", + "test_group": "base", + "test_type": "parse", + "input": "pkg:vcpkg/bzip2@1.0.8?port_version=6&repository_revision=84a143e4caf6b70db57f28d04c41df4a85c480fa&triplet=x64-linux", + "expected_output": { + "type": "vcpkg", + "namespace": null, + "name": "bzip2", + "version": "1.0.8", + "qualifiers": { + "port_version": "6", + "repository_revision": "84a143e4caf6b70db57f28d04c41df4a85c480fa", + "triplet": "x64-linux" + }, + "subpath": null + }, + "expected_failure": false, + "expected_failure_reason": null + } + ] +} diff --git a/types-doc/vcpkg-definition.md b/types-doc/vcpkg-definition.md new file mode 100644 index 00000000..378fb0bd --- /dev/null +++ b/types-doc/vcpkg-definition.md @@ -0,0 +1,55 @@ + + +# PURL Type Definition: vcpkg + +- **Type Name:** Vcpkg C/C++ packages +- **Description:** Vcpkg C/C++ packages +- **Schema ID:** `https://packageurl.org/types/vcpkg-definition.json` + +## PURL Syntax + +The structure of a PURL for this package type is: + + pkg:vcpkg/@?# + +## Repository Information + +- **Use Repository:** Yes +- **Default Repository URL:** https://github.com/microsoft/vcpkg/ +- **Note:** The absolute URL of the vcpkg registry where the package is available (optional). If omitted, ``https://github.com/microsoft/vcpkg`` as default registry is assumed. For filesystem registries or [overlay ports](https://learn.microsoft.com/vcpkg/concepts/overlay-ports), the URI will have a `file` URI scheme. + +## Namespace definition + +- **Requirement:** Prohibited + +## Name definition + +- **Requirement:** Required +- **Native Label:** package-name +- **Note:** `The vcpkg package name.` + +## Version definition + +- **Requirement:** Optional +- **Native Label:** package-version +- **Note:** `The vcpkg package version.` + +## Qualifiers Definition + +| Key | Requirement | Native name | Default Value | Description | +|------|-------------|-------------|---------------|-------------| +| port_version | Optional | port_version | | A string specifying the [port file revision](https://learn.microsoft.com/vcpkg/reference/vcpkg-json#port-version). If omitted, the purl refers to port file revision 0. | +| repository_revision | Optional | repository_revision | | The full 40-character commit hash of the vcpkg registry. For git registries this corresponds to the registry `baseline` field in `vcpkg-configuration.json`. If omitted, the purl refers to the latest revision available. | +| triplet | Optional | triplet | | The vcpkg [triplet](https://learn.microsoft.com/vcpkg/concepts/triplets) describing the target build configuration (architecture, operating system, and CRT/library linkage), for example `x64-windows` or `arm64-osx`. This is build/target context and does not affect package identity. | + +## Examples + +- `pkg:vcpkg/bzip2@1.0.8?port_version=6` +- `pkg:vcpkg/ffmpeg@5.1.2?repository_url=https://github.com/azure-sdk/vcpkg` +- `pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg` +- `pkg:vcpkg/bzip2@1.0.8?port_version=6&repository_revision=84a143e4caf6b70db57f28d04c41df4a85c480fa&triplet=x64-linux` + +## Note + +Additional qualifiers may be present on the purl that provide additional information about the context in which the package is being used, such as build configuration or platform information. These additional qualifiers must be tolerated during parsing and can be ignored if the parser does not expect them. The `features` qualifier, a comma-separated list of enabled vcpkg feature names, may be used to record which optional features were enabled at build time; this is informational and not currently normative. diff --git a/types/vcpkg-definition.json b/types/vcpkg-definition.json new file mode 100644 index 00000000..d723ee78 --- /dev/null +++ b/types/vcpkg-definition.json @@ -0,0 +1,52 @@ +{ + "$schema": "https://packageurl.org/schemas/purl-type-definition.schema-1.0.json", + "$id": "https://packageurl.org/types/vcpkg-definition.json", + "type": "vcpkg", + "type_name": "Vcpkg C/C++ packages", + "description": "Vcpkg C/C++ packages", + "repository": { + "use_repository": true, + "default_repository_url": "https://github.com/microsoft/vcpkg/", + "note": "The absolute URL of the vcpkg registry where the package is available (optional). If omitted, ``https://github.com/microsoft/vcpkg`` as default registry is assumed. For filesystem registries or [overlay ports](https://learn.microsoft.com/vcpkg/concepts/overlay-ports), the URI will have a `file` URI scheme." + }, + "namespace_definition": { + "requirement": "prohibited" + }, + "name_definition": { + "requirement": "required", + "native_name": "package-name", + "note": "The vcpkg package name." + }, + "version_definition": { + "requirement": "optional", + "native_name": "package-version", + "note": "The vcpkg package version." + }, + "qualifiers_definition": [ + { + "key": "port_version", + "native_name": "port_version", + "requirement": "optional", + "description": "A string specifying the [port file revision](https://learn.microsoft.com/vcpkg/reference/vcpkg-json#port-version). If omitted, the purl refers to port file revision 0." + }, + { + "key": "repository_revision", + "native_name": "repository_revision", + "requirement": "optional", + "description": "The full 40-character commit hash of the vcpkg registry. For git registries this corresponds to the registry `baseline` field in `vcpkg-configuration.json`. If omitted, the purl refers to the latest revision available." + }, + { + "key": "triplet", + "native_name": "triplet", + "requirement": "optional", + "description": "The vcpkg [triplet](https://learn.microsoft.com/vcpkg/concepts/triplets) describing the target build configuration (architecture, operating system, and CRT/library linkage), for example `x64-windows` or `arm64-osx`. This is build/target context and does not affect package identity." + } + ], + "note": "Additional qualifiers may be present on the purl that provide additional information about the context in which the package is being used, such as build configuration or platform information. These additional qualifiers must be tolerated during parsing and can be ignored if the parser does not expect them. The `features` qualifier, a comma-separated list of enabled vcpkg feature names, may be used to record which optional features were enabled at build time; this is informational and not currently normative.", + "examples": [ + "pkg:vcpkg/bzip2@1.0.8?port_version=6", + "pkg:vcpkg/ffmpeg@5.1.2?repository_url=https://github.com/azure-sdk/vcpkg", + "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg", + "pkg:vcpkg/bzip2@1.0.8?port_version=6&repository_revision=84a143e4caf6b70db57f28d04c41df4a85c480fa&triplet=x64-linux" + ] +}