From f81e71658cd3c31f65b209d69dee929a29aad814 Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Mon, 31 Jul 2023 11:02:41 -0700 Subject: [PATCH 01/18] Adding section for vcpkg purl spec with a preliminary spec. --- PURL-TYPES.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 27e747c..4ce2442 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -521,6 +521,29 @@ swift pkg:swift/github.com/Alamofire/Alamofire@5.4.3 pkg:swift/github.com/RxSwiftCommunity/RxFlow@2.12.4 +vcpkg +----- +``vcpkg`` for [vcpkg](https://vcpkg.io) C and C++ packages. + +- By default, vcpkg will build C and C++ dependencies from source, using configurations compatible with the user's project. For this and other reasons, it use's different terminology, documented here. + - __port__ - A package, along with it's build scripts and possibly minor modifications. + - __registry__ - A collection of ports, possibly private to the user. Analogous to __repository__. + +- The default registry (i.e., repository) is ``https://github.com/microsoft/vcpkg``. +- ``namespace``: A (percent-encoded)[https://www.rfc-editor.org/rfc/rfc3986#section-2.1] URI (specifically for (reserved characters)[https://www.rfc-editor.org/rfc/rfc3986#section-2.2]) for the registry the port came from. + - The URL encoded URI may be a (relative-path reference)[https://www.rfc-editor.org/rfc/rfc3986#section-4.2] or an (absolute URI)[https://www.rfc-editor.org/rfc/rfc3986#section-4.3]. + - If empty, the port comes from the default registry. + - Example: a ``namespace`` value of ``github.com%2Fmicrosoft%2Fvcpkg`` is the same as ``https%3A%2F%2Fgithub.com%2Fmicrosoft%2Fvcpkg`` or an empty value. +- ``name``: The case-sensitive name of the port. +- ``version``: The port version and is required. +- ``qualifiers``: The qualifiers below are used to provide more specific information on a port's origin registry and to distinguish between multiple instances of the same port dependency within the same project (for example, when the project targets multiple platforms). + - ``registry-version``: + - ``abi``: + - ``triplet``: + - ``features``: +- ``subpath``: Currently reserved for future use and should be empty. + + Other candidate types to define: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 9a5098ecf5219a1f4d1e652143a5f07dd0841121 Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Mon, 31 Jul 2023 11:08:02 -0700 Subject: [PATCH 02/18] Fixing links since .rst formatting for links is different than .md links. --- PURL-TYPES.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 4ce2442..a1561e4 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -523,15 +523,15 @@ swift vcpkg ----- -``vcpkg`` for [vcpkg](https://vcpkg.io) C and C++ packages. +``vcpkg`` for `vcpkg ` C and C++ packages. - By default, vcpkg will build C and C++ dependencies from source, using configurations compatible with the user's project. For this and other reasons, it use's different terminology, documented here. - __port__ - A package, along with it's build scripts and possibly minor modifications. - __registry__ - A collection of ports, possibly private to the user. Analogous to __repository__. - The default registry (i.e., repository) is ``https://github.com/microsoft/vcpkg``. -- ``namespace``: A (percent-encoded)[https://www.rfc-editor.org/rfc/rfc3986#section-2.1] URI (specifically for (reserved characters)[https://www.rfc-editor.org/rfc/rfc3986#section-2.2]) for the registry the port came from. - - The URL encoded URI may be a (relative-path reference)[https://www.rfc-editor.org/rfc/rfc3986#section-4.2] or an (absolute URI)[https://www.rfc-editor.org/rfc/rfc3986#section-4.3]. +- ``namespace``: A `percent-encoded `` URI (specifically for `reserved characters `) for the registry the port came from. + - The URL encoded URI may be a `relative-path reference `` or an `absolute URI `. - If empty, the port comes from the default registry. - Example: a ``namespace`` value of ``github.com%2Fmicrosoft%2Fvcpkg`` is the same as ``https%3A%2F%2Fgithub.com%2Fmicrosoft%2Fvcpkg`` or an empty value. - ``name``: The case-sensitive name of the port. From e43ca29368ee6c9789e77cd8b6c684eae116cc67 Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Mon, 31 Jul 2023 11:09:41 -0700 Subject: [PATCH 03/18] No, really fixing .rst link formatting. --- PURL-TYPES.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index a1561e4..223fc58 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -523,15 +523,15 @@ swift vcpkg ----- -``vcpkg`` for `vcpkg ` C and C++ packages. +``vcpkg`` for `vcpkg `_ C and C++ packages. - By default, vcpkg will build C and C++ dependencies from source, using configurations compatible with the user's project. For this and other reasons, it use's different terminology, documented here. - __port__ - A package, along with it's build scripts and possibly minor modifications. - __registry__ - A collection of ports, possibly private to the user. Analogous to __repository__. - The default registry (i.e., repository) is ``https://github.com/microsoft/vcpkg``. -- ``namespace``: A `percent-encoded `` URI (specifically for `reserved characters `) for the registry the port came from. - - The URL encoded URI may be a `relative-path reference `` or an `absolute URI `. +- ``namespace``: A `percent-encoded `_ URI (specifically for `reserved characters `_) for the registry the port came from. + - The URL encoded URI may be a `relative-path reference `_ or an `absolute URI `_. - If empty, the port comes from the default registry. - Example: a ``namespace`` value of ``github.com%2Fmicrosoft%2Fvcpkg`` is the same as ``https%3A%2F%2Fgithub.com%2Fmicrosoft%2Fvcpkg`` or an empty value. - ``name``: The case-sensitive name of the port. From ea3d2dc8941773c19f572c055eab86bafed8753b Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Mon, 31 Jul 2023 11:11:11 -0700 Subject: [PATCH 04/18] Formatting is still pretty weird. Seeing if I can fix that. --- PURL-TYPES.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 223fc58..8407ff0 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -537,10 +537,10 @@ vcpkg - ``name``: The case-sensitive name of the port. - ``version``: The port version and is required. - ``qualifiers``: The qualifiers below are used to provide more specific information on a port's origin registry and to distinguish between multiple instances of the same port dependency within the same project (for example, when the project targets multiple platforms). - - ``registry-version``: - - ``abi``: - - ``triplet``: - - ``features``: + - ``registry-version``: TBD + - ``abi``: TBD + - ``triplet``: TBD + - ``features``: TBD - ``subpath``: Currently reserved for future use and should be empty. From 876187abf035d9166745702ee6f5cbaa22953824 Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Mon, 31 Jul 2023 11:12:32 -0700 Subject: [PATCH 05/18] More formatting --- PURL-TYPES.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 8407ff0..b62fdfc 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -531,16 +531,21 @@ vcpkg - The default registry (i.e., repository) is ``https://github.com/microsoft/vcpkg``. - ``namespace``: A `percent-encoded `_ URI (specifically for `reserved characters `_) for the registry the port came from. + - The URL encoded URI may be a `relative-path reference `_ or an `absolute URI `_. - If empty, the port comes from the default registry. + - Example: a ``namespace`` value of ``github.com%2Fmicrosoft%2Fvcpkg`` is the same as ``https%3A%2F%2Fgithub.com%2Fmicrosoft%2Fvcpkg`` or an empty value. + - ``name``: The case-sensitive name of the port. - ``version``: The port version and is required. - ``qualifiers``: The qualifiers below are used to provide more specific information on a port's origin registry and to distinguish between multiple instances of the same port dependency within the same project (for example, when the project targets multiple platforms). + - ``registry-version``: TBD - ``abi``: TBD - ``triplet``: TBD - ``features``: TBD + - ``subpath``: Currently reserved for future use and should be empty. From 5b5c9d6740c5f62a724dda2cb955407c10717ed9 Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Mon, 31 Jul 2023 11:13:19 -0700 Subject: [PATCH 06/18] Even more formatting --- PURL-TYPES.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index b62fdfc..96d20d3 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -526,6 +526,7 @@ vcpkg ``vcpkg`` for `vcpkg `_ C and C++ packages. - By default, vcpkg will build C and C++ dependencies from source, using configurations compatible with the user's project. For this and other reasons, it use's different terminology, documented here. + - __port__ - A package, along with it's build scripts and possibly minor modifications. - __registry__ - A collection of ports, possibly private to the user. Analogous to __repository__. @@ -545,7 +546,7 @@ vcpkg - ``abi``: TBD - ``triplet``: TBD - ``features``: TBD - + - ``subpath``: Currently reserved for future use and should be empty. From c23ae7c7f608c811d76dfec05e9c267fa62e2df5 Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Mon, 31 Jul 2023 11:16:32 -0700 Subject: [PATCH 07/18] Fixing bold formatting --- PURL-TYPES.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 96d20d3..2ca1a76 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -527,8 +527,8 @@ vcpkg - By default, vcpkg will build C and C++ dependencies from source, using configurations compatible with the user's project. For this and other reasons, it use's different terminology, documented here. - - __port__ - A package, along with it's build scripts and possibly minor modifications. - - __registry__ - A collection of ports, possibly private to the user. Analogous to __repository__. + - **port** - A package, along with it's build scripts and possibly minor modifications. + - **registry** - A collection of ports, possibly private to the user. Analogous to **repository**. - The default registry (i.e., repository) is ``https://github.com/microsoft/vcpkg``. - ``namespace``: A `percent-encoded `_ URI (specifically for `reserved characters `_) for the registry the port came from. From 5fc8b5ca9a1b060f8580823b8e19ebe36fc60b69 Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Mon, 31 Jul 2023 11:19:15 -0700 Subject: [PATCH 08/18] Yet more formatting --- PURL-TYPES.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 2ca1a76..92733f4 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -523,7 +523,7 @@ swift vcpkg ----- -``vcpkg`` for `vcpkg `_ C and C++ packages. +``vcpkg`` for `vcpkg `_ C and C++ packages: - By default, vcpkg will build C and C++ dependencies from source, using configurations compatible with the user's project. For this and other reasons, it use's different terminology, documented here. @@ -536,7 +536,11 @@ vcpkg - The URL encoded URI may be a `relative-path reference `_ or an `absolute URI `_. - If empty, the port comes from the default registry. - - Example: a ``namespace`` value of ``github.com%2Fmicrosoft%2Fvcpkg`` is the same as ``https%3A%2F%2Fgithub.com%2Fmicrosoft%2Fvcpkg`` or an empty value. + - Equivalent example namespaces:: + + github.com%2Fmicrosoft%2Fvcpkg + https%3A%2F%2Fgithub.com%2Fmicrosoft%2Fvcpkg + an empty value - ``name``: The case-sensitive name of the port. - ``version``: The port version and is required. From 2b1e64abf4dbb840e37e3875e1dfccf0ed03fbf1 Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Mon, 31 Jul 2023 11:24:41 -0700 Subject: [PATCH 09/18] Spelling, formatting, and marking components as required or optional. --- PURL-TYPES.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 92733f4..a6dcd8f 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -525,16 +525,15 @@ vcpkg ----- ``vcpkg`` for `vcpkg `_ C and C++ packages: -- By default, vcpkg will build C and C++ dependencies from source, using configurations compatible with the user's project. For this and other reasons, it use's different terminology, documented here. +- By default, vcpkg will build C and C++ dependencies from source, using configurations compatible with the user's project. For this and other reasons, it uses different terminology, documented here. - **port** - A package, along with it's build scripts and possibly minor modifications. - **registry** - A collection of ports, possibly private to the user. Analogous to **repository**. -- The default registry (i.e., repository) is ``https://github.com/microsoft/vcpkg``. -- ``namespace``: A `percent-encoded `_ URI (specifically for `reserved characters `_) for the registry the port came from. +- ``namespace``: A `percent-encoded `_ URI (specifically for `reserved characters `_) for the registry the port came from. **Required** - The URL encoded URI may be a `relative-path reference `_ or an `absolute URI `_. - - If empty, the port comes from the default registry. + - If empty, the port comes from the default registry, ``https://github.com/microsoft/vcpkg``. - Equivalent example namespaces:: @@ -542,11 +541,12 @@ vcpkg https%3A%2F%2Fgithub.com%2Fmicrosoft%2Fvcpkg an empty value -- ``name``: The case-sensitive name of the port. -- ``version``: The port version and is required. +- ``name``: The case-sensitive name of the port. **Required** +- ``version``: The port version. **Required** - ``qualifiers``: The qualifiers below are used to provide more specific information on a port's origin registry and to distinguish between multiple instances of the same port dependency within the same project (for example, when the project targets multiple platforms). - - ``registry-version``: TBD + - ``registry-version``: TBD. **Required** + - The following group of qualifiers are optional, but if any appear, they must all appear. If none appear, the dependency is a "source-only" dependency. - ``abi``: TBD - ``triplet``: TBD - ``features``: TBD From b49e3778f729e78e30a8242a4b3c56382e86429c Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Mon, 14 Aug 2023 14:28:52 -0700 Subject: [PATCH 10/18] - Moving registry url from the namespace field to a repository_url parameter. - Renaming registry-version paramater to be consistent. - Adding description of features parameter. - Adding a distinct examples section. --- PURL-TYPES.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index a6dcd8f..d666954 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -530,28 +530,29 @@ vcpkg - **port** - A package, along with it's build scripts and possibly minor modifications. - **registry** - A collection of ports, possibly private to the user. Analogous to **repository**. -- ``namespace``: A `percent-encoded `_ URI (specifically for `reserved characters `_) for the registry the port came from. **Required** - - - The URL encoded URI may be a `relative-path reference `_ or an `absolute URI `_. - - If empty, the port comes from the default registry, ``https://github.com/microsoft/vcpkg``. - - - Equivalent example namespaces:: - - github.com%2Fmicrosoft%2Fvcpkg - https%3A%2F%2Fgithub.com%2Fmicrosoft%2Fvcpkg - an empty value +- ``namespace``: Currently reserved for future use and should be empty - ``name``: The case-sensitive name of the port. **Required** - ``version``: The port version. **Required** - ``qualifiers``: The qualifiers below are used to provide more specific information on a port's origin registry and to distinguish between multiple instances of the same port dependency within the same project (for example, when the project targets multiple platforms). - - ``registry-version``: TBD. **Required** + - ``registry_version``: TBD. **Required** + - ``repository_url``: A `percent-encoded `_ absolute URI for the registry the port came from. **Optional** + + - If empty, the port comes from the default registry, ``https://github.com/microsoft/vcpkg``. + - The following group of qualifiers are optional, but if any appear, they must all appear. If none appear, the dependency is a "source-only" dependency. - ``abi``: TBD - ``triplet``: TBD - - ``features``: TBD + - ``features``: A comma-delimited list of enabled features for the port. - ``subpath``: Currently reserved for future use and should be empty. +- Examples:: + + pkg:vcpkg/ms-gsl@4.0.0?registry_version=4e2b371 + pkg:vcpkg/llvm@15.0.7?registry_version=4e2b371&abi=???&triplet=????&features=clang + pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc + Other candidate types to define: From f4feca1bb118a6de7a56f54d61f9557578fcf5b6 Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Tue, 15 Aug 2023 12:00:42 -0700 Subject: [PATCH 11/18] Removing abi, triplet, and features qualifiers and specifying that additional, unspecified qualifeirs must be tolerated. --- PURL-TYPES.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index d666954..e836d7a 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -541,17 +541,15 @@ vcpkg - If empty, the port comes from the default registry, ``https://github.com/microsoft/vcpkg``. - - The following group of qualifiers are optional, but if any appear, they must all appear. If none appear, the dependency is a "source-only" dependency. - - ``abi``: TBD - - ``triplet``: TBD - - ``features``: A comma-delimited list of enabled features for the port. + - 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. - ``subpath``: Currently reserved for future use and should be empty. - Examples:: - pkg:vcpkg/ms-gsl@4.0.0?registry_version=4e2b371 - pkg:vcpkg/llvm@15.0.7?registry_version=4e2b371&abi=???&triplet=????&features=clang - pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc + Microsoft GSL version 4.0.0 from the default registry at commit 4e2b371 + pkg:vcpkg/ms-gsl@4.0.0?registry_version=4e2b371 + ffmpeg version 5.1.2 from the azure-sdk registry at commit e6c17cc + pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc From 060623363346b6aeddb0e9c3d043c62d3f652ea9 Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Fri, 18 Aug 2023 15:31:53 -0700 Subject: [PATCH 12/18] Providing a description of the `registry_version` qualifier. --- PURL-TYPES.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index e836d7a..93899d3 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -536,11 +536,15 @@ vcpkg - ``version``: The port version. **Required** - ``qualifiers``: The qualifiers below are used to provide more specific information on a port's origin registry and to distinguish between multiple instances of the same port dependency within the same project (for example, when the project targets multiple platforms). - - ``registry_version``: TBD. **Required** - - ``repository_url``: A `percent-encoded `_ absolute URI for the registry the port came from. **Optional** + - ``repository_url``: A `percent-encoded `_ absolute URI for the registry the port came from. For filesystem registries, the URI will have a `file` URI scheme. **Optional** - If empty, the port comes from the default registry, ``https://github.com/microsoft/vcpkg``. + - ``registry_version``: A string specifying the version of the registry specified by `repository_url`. + + - For git registries, the commit hash (potentially abbreviated). This must __NOT__ be any other kind of git reference, such as `HEAD` or tags. **Required** + - For filesystem registries, an string that can be used to identify specific versions, such as a Coordinated Universal Time (UTC) as described in `RFC 3339 `_. **Optional + - 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. - ``subpath``: Currently reserved for future use and should be empty. @@ -550,6 +554,8 @@ vcpkg pkg:vcpkg/ms-gsl@4.0.0?registry_version=4e2b371 ffmpeg version 5.1.2 from the azure-sdk registry at commit e6c17cc pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc + LLVM from a filesystem registry + pkg:vcpkg/llvm@15.0.7?registry_url=file%3A%2F%2F%2FC%3A%2Flocal-registry%2Fvcpkg®istry_version=2023-08-18T22:28:52Z From bbd623be9fc088fdb199864438abb3da680aa668 Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Fri, 18 Aug 2023 15:54:50 -0700 Subject: [PATCH 13/18] Clarifying that in accordance with the specification rules, the value of the registry_version qualifier should be percent-encoded. --- PURL-TYPES.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 93899d3..e50497f 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -543,7 +543,7 @@ vcpkg - ``registry_version``: A string specifying the version of the registry specified by `repository_url`. - For git registries, the commit hash (potentially abbreviated). This must __NOT__ be any other kind of git reference, such as `HEAD` or tags. **Required** - - For filesystem registries, an string that can be used to identify specific versions, such as a Coordinated Universal Time (UTC) as described in `RFC 3339 `_. **Optional + - For filesystem registries, an string that can be used to identify specific versions, such as Coordinated Universal Time (UTC) as described in `RFC 3339 `_. If using a UTC time, be sure to percent-encode it correctly. **Optional** - 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. @@ -555,7 +555,7 @@ vcpkg ffmpeg version 5.1.2 from the azure-sdk registry at commit e6c17cc pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc LLVM from a filesystem registry - pkg:vcpkg/llvm@15.0.7?registry_url=file%3A%2F%2F%2FC%3A%2Flocal-registry%2Fvcpkg®istry_version=2023-08-18T22:28:52Z + pkg:vcpkg/llvm@15.0.7?registry_url=file%3A%2F%2F%2FC%3A%2Flocal-registry%2Fvcpkg®istry_version=2023-08-18T22%3A28%3A52Z From 08ca6fa5e4d9fc03f28291f21b2e993c1f6fce62 Mon Sep 17 00:00:00 2001 From: "Michael B. Price" Date: Fri, 18 Aug 2023 15:55:48 -0700 Subject: [PATCH 14/18] Adding test suite data for the vcpkg purl type. --- test-suite-data.json | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/test-suite-data.json b/test-suite-data.json index a819fc8..cdc56a2 100644 --- a/test-suite-data.json +++ b/test-suite-data.json @@ -347,6 +347,42 @@ "subpath": null, "is_invalid": true }, + { + "description": "simple vcpkg purl", + "purl": "pkg:vcpkg/ms-gsl@4.0.0?registry_version=4e2b371", + "canonical_purl": "pkg:vcpkg/ms-gsl@4.0.0?registry_version=4e2b371", + "type": "vcpkg", + "namespace": null, + "name": "ms-gsl", + "version": "4.0.0", + "qualifiers": {"registry_version": "4e2b371"}, + "subpath": null, + "is_invalid": false + }, + { + "description": "vcpkg non-default git registry", + "purl": "pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc", + "canonical_purl": "pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc", + "type": "vcpkg", + "namespace": null, + "name": "ffmpeg", + "version": "5.1.2", + "qualifiers": {"registry_url": "https://github.com/azure-sdk/vcpkg", "registry_version": "e6c17cc"}, + "subpath": null, + "is_invalid": false + }, + { + "description": "vcpkg filesystem registry", + "purl": "pkg:vcpkg/llvm@15.0.7?registry_url=file%3A%2F%2F%2FC%3A%2Flocal-registry%2Fvcpkg®istry_version=2023-08-18T22%3A28%3A52Z", + "canonical_purl": "pkg:vcpkg/llvm@15.0.7?registry_url=file%3A%2F%2F%2FC%3A%2Flocal-registry%2Fvcpkg®istry_version=2023-08-18T22%3A28%3A52Z", + "type": "vcpkg", + "namespace": null, + "name": "llvm", + "version": "15.0.7", + "qualifiers": {"registry_url": "file:///C:/local-registry/vcpkg", "registry_version": "2023-08-18T22:28:52Z"}, + "subpath": null, + "is_invalid": false + }, { "description": "valid conda purl with qualifiers", "purl": "pkg:conda/absl-py@0.4.1?build=py36h06a4308_0&channel=main&subdir=linux-64&type=tar.bz2", From e94a237a5806761fc68a9d1a9d071c8b3526fbe3 Mon Sep 17 00:00:00 2001 From: aristotelos Date: Tue, 17 Sep 2024 13:43:11 +0200 Subject: [PATCH 15/18] Address review comments Revive https://github.com/package-url/purl-spec/pull/245 by adding the following changes: - `registry_url` -> `repository_url` - `registry_version` -> `port_revision` - Remove percent escaping from `repository_url` to be more consistent with other uses of `repository_url` in the purl spec --- PURL-TYPES.rst | 31 ++++++++++--------------------- test-suite-data.json | 30 +++++++++++++++++++++--------- 2 files changed, 31 insertions(+), 30 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index e50497f..c9a6998 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -530,32 +530,21 @@ vcpkg - **port** - A package, along with it's build scripts and possibly minor modifications. - **registry** - A collection of ports, possibly private to the user. Analogous to **repository**. -- ``namespace``: Currently reserved for future use and should be empty - +- ``namespace``: Currently reserved for future use and should be empty. - ``name``: The case-sensitive name of the port. **Required** -- ``version``: The port version. **Required** -- ``qualifiers``: The qualifiers below are used to provide more specific information on a port's origin registry and to distinguish between multiple instances of the same port dependency within the same project (for example, when the project targets multiple platforms). - - - ``repository_url``: A `percent-encoded `_ absolute URI for the registry the port came from. For filesystem registries, the URI will have a `file` URI scheme. **Optional** - - - If empty, the port comes from the default registry, ``https://github.com/microsoft/vcpkg``. - - - ``registry_version``: A string specifying the version of the registry specified by `repository_url`. - - - For git registries, the commit hash (potentially abbreviated). This must __NOT__ be any other kind of git reference, such as `HEAD` or tags. **Required** - - For filesystem registries, an string that can be used to identify specific versions, such as Coordinated Universal Time (UTC) as described in `RFC 3339 `_. If using a UTC time, be sure to percent-encode it correctly. **Optional** - - - 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. - +- ``version``: The upstream version of the port (excluding the port file revision). **Required** - ``subpath``: Currently reserved for future use and should be empty. +- Qualifier ``repository_url``: The vcpkg registry where the package is available (optional). If omitted, ``https://github.com/microsoft/vcpkg`` as default registry is assumed. +- Qualifier ``port_revision``: A string specifying the [port file revision](https://learn.microsoft.com/en-us/vcpkg/reference/vcpkg-json#port-version) (optional). +- 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. - Examples:: - Microsoft GSL version 4.0.0 from the default registry at commit 4e2b371 - pkg:vcpkg/ms-gsl@4.0.0?registry_version=4e2b371 - ffmpeg version 5.1.2 from the azure-sdk registry at commit e6c17cc - pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc + Microsoft GSL version 4.0.0 from the default registry with port file revision 4 + pkg:vcpkg/ms-gsl@4.0.0?port_revision=4 + ffmpeg version 5.1.2 from the azure-sdk registry + pkg:vcpkg/ffmpeg@5.1.2?repository_url=https://github.com/azure-sdk/vcpkg LLVM from a filesystem registry - pkg:vcpkg/llvm@15.0.7?registry_url=file%3A%2F%2F%2FC%3A%2Flocal-registry%2Fvcpkg®istry_version=2023-08-18T22%3A28%3A52Z + pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg diff --git a/test-suite-data.json b/test-suite-data.json index cdc56a2..9ac332a 100644 --- a/test-suite-data.json +++ b/test-suite-data.json @@ -349,37 +349,49 @@ }, { "description": "simple vcpkg purl", - "purl": "pkg:vcpkg/ms-gsl@4.0.0?registry_version=4e2b371", - "canonical_purl": "pkg:vcpkg/ms-gsl@4.0.0?registry_version=4e2b371", + "purl": "pkg:vcpkg/ms-gsl@4.0.0", + "canonical_purl": "pkg:vcpkg/ms-gsl@4.0.0", "type": "vcpkg", "namespace": null, "name": "ms-gsl", "version": "4.0.0", - "qualifiers": {"registry_version": "4e2b371"}, + "qualifiers": null, + "subpath": null, + "is_invalid": false + }, + { + "description": "vcpkg with port_revision", + "purl": "pkg:vcpkg/ms-gsl@4.0.0?port_revision=4", + "canonical_purl": "pkg:vcpkg/ms-gsl@4.0.0?port_revision=4", + "type": "vcpkg", + "namespace": null, + "name": "ms-gsl", + "version": "4.0.0", + "qualifiers": {"port_revision": "4"}, "subpath": null, "is_invalid": false }, { "description": "vcpkg non-default git registry", - "purl": "pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc", - "canonical_purl": "pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc", + "purl": "pkg:vcpkg/ffmpeg@5.1.2?repository_url=https://github.com/azure-sdk/vcpkg&port_revision=3", + "canonical_purl": "pkg:vcpkg/ffmpeg@5.1.2?repository_url=https://github.com/azure-sdk/vcpkg&port_revision=3", "type": "vcpkg", "namespace": null, "name": "ffmpeg", "version": "5.1.2", - "qualifiers": {"registry_url": "https://github.com/azure-sdk/vcpkg", "registry_version": "e6c17cc"}, + "qualifiers": {"repository_url": "https://github.com/azure-sdk/vcpkg", "port_revision": "3"}, "subpath": null, "is_invalid": false }, { "description": "vcpkg filesystem registry", - "purl": "pkg:vcpkg/llvm@15.0.7?registry_url=file%3A%2F%2F%2FC%3A%2Flocal-registry%2Fvcpkg®istry_version=2023-08-18T22%3A28%3A52Z", - "canonical_purl": "pkg:vcpkg/llvm@15.0.7?registry_url=file%3A%2F%2F%2FC%3A%2Flocal-registry%2Fvcpkg®istry_version=2023-08-18T22%3A28%3A52Z", + "purl": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg", + "canonical_purl": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg", "type": "vcpkg", "namespace": null, "name": "llvm", "version": "15.0.7", - "qualifiers": {"registry_url": "file:///C:/local-registry/vcpkg", "registry_version": "2023-08-18T22:28:52Z"}, + "qualifiers": {"repository_url": "file:///C:/local-registry/vcpkg"}, "subpath": null, "is_invalid": false }, From d67985927c4c70524e91cab7e1ec21af3338950c Mon Sep 17 00:00:00 2001 From: aristotelos Date: Thu, 10 Oct 2024 07:43:11 +0200 Subject: [PATCH 16/18] Make URL language-inspecific Co-authored-by: Michael B. Price --- PURL-TYPES.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index c9a6998..427cf1a 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -535,7 +535,7 @@ vcpkg - ``version``: The upstream version of the port (excluding the port file revision). **Required** - ``subpath``: Currently reserved for future use and should be empty. - Qualifier ``repository_url``: The vcpkg registry where the package is available (optional). If omitted, ``https://github.com/microsoft/vcpkg`` as default registry is assumed. -- Qualifier ``port_revision``: A string specifying the [port file revision](https://learn.microsoft.com/en-us/vcpkg/reference/vcpkg-json#port-version) (optional). +- Qualifier ``port_revision``: A string specifying the [port file revision](https://learn.microsoft.com/vcpkg/reference/vcpkg-json#port-version) (optional). - 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. - Examples:: From bf4b3cc859ace48486a74dffafb9ed92d0605ad7 Mon Sep 17 00:00:00 2001 From: aristotelos Date: Thu, 10 Oct 2024 08:37:50 +0200 Subject: [PATCH 17/18] Add optional `repository_revision` qualifier Add optional `repository_revision` so that mistakes in `port_revision` and `version` can be accounted for. Not relevant for filesystem registries or overlay ports because that gives no further external traceability. Along with this, describe the filesystem registries and overlay port cases. --- PURL-TYPES.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 427cf1a..a47af59 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -534,8 +534,9 @@ vcpkg - ``name``: The case-sensitive name of the port. **Required** - ``version``: The upstream version of the port (excluding the port file revision). **Required** - ``subpath``: Currently reserved for future use and should be empty. -- Qualifier ``repository_url``: The vcpkg registry where the package is available (optional). If omitted, ``https://github.com/microsoft/vcpkg`` as default registry is assumed. +- Qualifier ``repository_url``: 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. - Qualifier ``port_revision``: A string specifying the [port file revision](https://learn.microsoft.com/vcpkg/reference/vcpkg-json#port-version) (optional). +- Qualifier ``repository_revision``: The commit hash of the vcpkg registry, potentially abbreviated (optional). - 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. - Examples:: From a2b507ac646fb8603837201108836b7f206d7683 Mon Sep 17 00:00:00 2001 From: aristotelos Date: Thu, 10 Oct 2024 08:49:27 +0200 Subject: [PATCH 18/18] Extend test suite data Extend the port overlay or filesystem registry example with port revision. Add an example for additional qualifiers. --- test-suite-data.json | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/test-suite-data.json b/test-suite-data.json index 9ac332a..31bc492 100644 --- a/test-suite-data.json +++ b/test-suite-data.json @@ -384,14 +384,26 @@ "is_invalid": false }, { - "description": "vcpkg filesystem registry", - "purl": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg", - "canonical_purl": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg", + "description": "vcpkg filesystem registry or overlay port", + "purl": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg&port_revision=3", + "canonical_purl": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg&port_revision=3", "type": "vcpkg", "namespace": null, "name": "llvm", "version": "15.0.7", - "qualifiers": {"repository_url": "file:///C:/local-registry/vcpkg"}, + "qualifiers": {"repository_url": "file:///C:/local-registry/vcpkg", "port_revision": "3"}, + "subpath": null, + "is_invalid": false + }, + { + "description": "vcpkg with additional qualifiers", + "purl": "pkg:vcpkg/ms-gsl@4.0.0?port_revision=4&repository_revision=42301df395&os=Linux&os_arch=x64&build_type=Debug&linkage=dynamic", + "canonical_purl": "pkg:vcpkg/ms-gsl@4.0.0?port_revision=4&repository_revision=42301df395&os=Linux&os_arch=x64&build_type=Debug&linkage=dynamic", + "type": "vcpkg", + "namespace": null, + "name": "ms-gsl", + "version": "4.0.0", + "qualifiers": {"port_revision": "4", "repository_revision": "42301df395", "os": "Linux", "os_arch": "x64", "build_type": "Debug", "linkage": "dynamic"}, "subpath": null, "is_invalid": false },