From 4e11de312b983f3eccf85d37776aa3dc30e54158 Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Mon, 17 Jun 2024 17:07:06 +0400 Subject: [PATCH 1/6] Help: Reorder variables as they mentioned in the official spec Also, group 'em into sub-sub-sections (same as in the upstream doc). See also, https://learn.microsoft.com/en-us/nuget/reference/nuspec --- Help/cpack_gen/nuget.rst | 90 +++++++++++++++++++++++----------------- 1 file changed, 51 insertions(+), 39 deletions(-) diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst index e25364f0fc..8c94959aee 100644 --- a/Help/cpack_gen/nuget.rst +++ b/Help/cpack_gen/nuget.rst @@ -34,6 +34,17 @@ List of CPack NuGet generator specific variables: :Mandatory: No :Default: ``OFF`` +.. variable:: CPACK_NUGET_PACKAGE_DEBUG + + Enable debug messages while executing CPack NuGet generator. + + :Mandatory: No + :Default: ``OFF`` + + +Required metadata variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. variable:: CPACK_NUGET_PACKAGE_NAME CPACK_NUGET__PACKAGE_NAME @@ -74,18 +85,9 @@ List of CPack NuGet generator specific variables: :Mandatory: Yes :Default: :variable:`CPACK_PACKAGE_VENDOR` -.. variable:: CPACK_NUGET_PACKAGE_TITLE - CPACK_NUGET__PACKAGE_TITLE - A human-friendly title of the package, typically used in UI displays - as on nuget.org_ and the Package Manager in Visual Studio. If not - specified, the package ID is used. - - :Mandatory: No - :Default: - - - :variable:`CPACK_COMPONENT__DISPLAY_NAME`, - - :variable:`!CPACK_COMPONENT_GROUP__DISPLAY_NAME` +Optional metadata variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. variable:: CPACK_NUGET_PACKAGE_OWNERS CPACK_NUGET__PACKAGE_OWNERS @@ -121,6 +123,19 @@ List of CPack NuGet generator specific variables: :Mandatory: No :Default: None +.. variable:: CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME + CPACK_NUGET__PACKAGE_LICENSE_FILE_NAME + + The package's license file in :file:`.txt` or :file:`.md` format. + + If :variable:`!CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` is specified, + :variable:`!CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` is ignored. + + .. versionadded:: 3.20 + + :Mandatory: No + :Default: None + .. variable:: CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION CPACK_NUGET__PACKAGE_LICENSE_EXPRESSION @@ -139,19 +154,6 @@ List of CPack NuGet generator specific variables: :Mandatory: No :Default: None -.. variable:: CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME - CPACK_NUGET__PACKAGE_LICENSE_FILE_NAME - - The package's license file in :file:`.txt` or :file:`.md` format. - - If :variable:`!CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` is specified, - :variable:`!CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` is ignored. - - .. versionadded:: 3.20 - - :Mandatory: No - :Default: None - .. variable:: CPACK_NUGET_PACKAGE_ICONURL CPACK_NUGET__PACKAGE_ICONURL @@ -164,14 +166,6 @@ List of CPack NuGet generator specific variables: :Mandatory: No :Default: None -.. variable:: CPACK_NUGET_PACKAGE_REQUIRE_LICENSE_ACCEPTANCE - - When set to a true value, the user will be prompted to accept the license - before installing the package. - - :Mandatory: No - :Default: None - .. variable:: CPACK_NUGET_PACKAGE_ICON CPACK_NUGET__PACKAGE_ICON @@ -183,6 +177,14 @@ List of CPack NuGet generator specific variables: :Mandatory: No :Default: None +.. variable:: CPACK_NUGET_PACKAGE_REQUIRE_LICENSE_ACCEPTANCE + + When set to a true value, the user will be prompted to accept the license + before installing the package. + + :Mandatory: No + :Default: None + .. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION_SUMMARY CPACK_NUGET__PACKAGE_DESCRIPTION_SUMMARY @@ -230,6 +232,23 @@ List of CPack NuGet generator specific variables: :Mandatory: No :Default: None +.. variable:: CPACK_NUGET_PACKAGE_TITLE + CPACK_NUGET__PACKAGE_TITLE + + A human-friendly title of the package, typically used in UI displays + as on nuget.org_ and the Package Manager in Visual Studio. If not + specified, the package ID is used. + + :Mandatory: No + :Default: + + - :variable:`CPACK_COMPONENT__DISPLAY_NAME`, + - :variable:`!CPACK_COMPONENT_GROUP__DISPLAY_NAME` + + +Dependencies specification +~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES CPACK_NUGET__PACKAGE_DEPENDENCIES @@ -284,13 +303,6 @@ List of CPack NuGet generator specific variables: :Mandatory: No :Default: None -.. variable:: CPACK_NUGET_PACKAGE_DEBUG - - Enable debug messages while executing CPack NuGet generator. - - :Mandatory: No - :Default: ``OFF`` - Example usage ^^^^^^^^^^^^^ From 391e3399263c200038a609a174713ec924bc94ef Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Mon, 17 Jun 2024 17:15:38 +0400 Subject: [PATCH 2/6] Help: CPack/NuGet add deprecation notes according to the current spec --- Help/cpack_gen/nuget.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst index 8c94959aee..c12d0c14ef 100644 --- a/Help/cpack_gen/nuget.rst +++ b/Help/cpack_gen/nuget.rst @@ -92,6 +92,9 @@ Optional metadata variables .. variable:: CPACK_NUGET_PACKAGE_OWNERS CPACK_NUGET__PACKAGE_OWNERS + .. deprecated:: 3.30 + Use authors (:variable:`CPACK_NUGET_PACKAGE_AUTHORS`) instead. + A comma-separated list of the package creators using profile names on nuget.org_. This is often the same list as in authors, and is ignored when uploading the package to nuget.org_. @@ -188,6 +191,10 @@ Optional metadata variables .. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION_SUMMARY CPACK_NUGET__PACKAGE_DESCRIPTION_SUMMARY + .. deprecated:: 3.30 + Summary is being deprecated. Use description + (:variable:`CPACK_NUGET_PACKAGE_DESCRIPTION`) instead. + A short description of the package for UI display. If omitted, a truncated version of description is used. From 039bf0f3f3b1f47a9a5750aba19c33dec5e15fde Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Mon, 17 Jun 2024 17:19:04 +0400 Subject: [PATCH 3/6] Help: CPack/NuGet fix `versionadded` position It should be right after `.. variable::` --- Help/cpack_gen/nuget.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst index c12d0c14ef..e6ff9cc724 100644 --- a/Help/cpack_gen/nuget.rst +++ b/Help/cpack_gen/nuget.rst @@ -129,13 +129,13 @@ Optional metadata variables .. variable:: CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME CPACK_NUGET__PACKAGE_LICENSE_FILE_NAME + .. versionadded:: 3.20 + The package's license file in :file:`.txt` or :file:`.md` format. If :variable:`!CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` is specified, :variable:`!CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` is ignored. - .. versionadded:: 3.20 - :Mandatory: No :Default: None From a6a8212ba2084184b9ff5d98a022f1c4c9e0c661 Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Mon, 17 Jun 2024 17:46:10 +0400 Subject: [PATCH 4/6] Help: CPack/NuGet add description to the added variables --- Help/cpack_gen/nuget.rst | 55 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst index e6ff9cc724..3773a1dccb 100644 --- a/Help/cpack_gen/nuget.rst +++ b/Help/cpack_gen/nuget.rst @@ -180,6 +180,17 @@ Optional metadata variables :Mandatory: No :Default: None +.. variable:: CPACK_NUGET_PACKAGE_README + CPACK_NUGET__PACKAGE_README + + .. versionadded:: 3.30 + + The package path relative to the root of the package to a readme file. + Supported file formats include only Markdown (``*.md``). + + :Mandatory: No + :Default: None + .. variable:: CPACK_NUGET_PACKAGE_REQUIRE_LICENSE_ACCEPTANCE When set to a true value, the user will be prompted to accept the license @@ -239,6 +250,50 @@ Optional metadata variables :Mandatory: No :Default: None +.. variable:: CPACK_NUGET_PACKAGE_REPOSITORY_URL + CPACK_NUGET__REPOSITORY_URL + + .. versionadded:: 3.30 + + Repository metadata allows you to map the ``*.nupkg`` to the repository + that built it. This should be a publicly available URL that can be invoked + directly by a version control software. It should not be an HTML page as + this is meant for the computer. + + :Mandatory: No + :Default: None + +.. variable:: CPACK_NUGET_PACKAGE_REPOSITORY_TYPE + CPACK_NUGET__REPOSITORY_TYPE + + .. versionadded:: 3.30 + + A type of the VCS repository. When uploading a package to nuget.org_, the + type is limited to 100 characters. + + :Mandatory: Yes, if repository URL has been specified + :Default: None + +.. variable:: CPACK_NUGET_PACKAGE_REPOSITORY_BRANCH + CPACK_NUGET__REPOSITORY_BRANCH + + .. versionadded:: 3.30 + + A VSC branch name to build the package. + + :Mandatory: No + :Default: None + +.. variable:: CPACK_NUGET_PACKAGE_REPOSITORY_COMMIT + CPACK_NUGET__REPOSITORY_COMMIT + + .. versionadded:: 3.30 + + A SHA-1 hash of the commit to build the package. + + :Mandatory: No + :Default: None + .. variable:: CPACK_NUGET_PACKAGE_TITLE CPACK_NUGET__PACKAGE_TITLE From d06a39dd59930f28c02e268186d2047233b9cf87 Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Mon, 17 Jun 2024 17:57:39 +0400 Subject: [PATCH 5/6] Help: CPack/NuGet add `:Supported:` to some variables Some features of NuGet require relatively fresh versions. Mention that versions as they are specified in the upstream spec. --- Help/cpack_gen/nuget.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst index 3773a1dccb..8b66ec126a 100644 --- a/Help/cpack_gen/nuget.rst +++ b/Help/cpack_gen/nuget.rst @@ -125,6 +125,7 @@ Optional metadata variables :Mandatory: No :Default: None + :Supported: NuGet 4.9.0 and above .. variable:: CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME CPACK_NUGET__PACKAGE_LICENSE_FILE_NAME @@ -138,6 +139,7 @@ Optional metadata variables :Mandatory: No :Default: None + :Supported: NuGet 4.9.0 and above .. variable:: CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION CPACK_NUGET__PACKAGE_LICENSE_EXPRESSION @@ -179,6 +181,8 @@ Optional metadata variables :Mandatory: No :Default: None + :Supported: NuGet 5.3.0 and above + .. variable:: CPACK_NUGET_PACKAGE_README CPACK_NUGET__PACKAGE_README @@ -190,6 +194,7 @@ Optional metadata variables :Mandatory: No :Default: None + :Supported: NuGet 5.10.0 preview 2 and above .. variable:: CPACK_NUGET_PACKAGE_REQUIRE_LICENSE_ACCEPTANCE @@ -262,6 +267,7 @@ Optional metadata variables :Mandatory: No :Default: None + :Supported: NuGet 4.0 and above .. variable:: CPACK_NUGET_PACKAGE_REPOSITORY_TYPE CPACK_NUGET__REPOSITORY_TYPE @@ -273,6 +279,7 @@ Optional metadata variables :Mandatory: Yes, if repository URL has been specified :Default: None + :Supported: NuGet 4.0 and above .. variable:: CPACK_NUGET_PACKAGE_REPOSITORY_BRANCH CPACK_NUGET__REPOSITORY_BRANCH @@ -283,6 +290,7 @@ Optional metadata variables :Mandatory: No :Default: None + :Supported: NuGet 4.6 and above .. variable:: CPACK_NUGET_PACKAGE_REPOSITORY_COMMIT CPACK_NUGET__REPOSITORY_COMMIT @@ -293,6 +301,7 @@ Optional metadata variables :Mandatory: No :Default: None + :Supported: NuGet 4.6 and above .. variable:: CPACK_NUGET_PACKAGE_TITLE CPACK_NUGET__PACKAGE_TITLE From dbdca565550a8ebab9693cd6db96894c5fe89b55 Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Mon, 17 Jun 2024 18:14:22 +0400 Subject: [PATCH 6/6] Help: CPack/NuGet avoid deprecated variables in the usage example --- Help/cpack_gen/nuget.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst index 8b66ec126a..d97f0c0c13 100644 --- a/Help/cpack_gen/nuget.rst +++ b/Help/cpack_gen/nuget.rst @@ -385,9 +385,8 @@ Example usage set(CPACK_PACKAGE_NAME SamplePackage) set(CPACK_PACKAGE_VERSION "1.0.0") set(CPACK_PACKAGE_VENDOR "Example Inc") - set(CPACK_NUGET_PACKAGE_OWNERS "Example Inc") + set(CPACK_NUGET_PACKAGE_AUTHORS "ExampleInc") set(CPACK_PACKAGE_DESCRIPTION "A .NET wrapper around the foobar library for frobbling bratchens") - set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "A .NET wrapper around the foobar library for frobbling bratchens") set(CPACK_PACKAGE_HOMEPAGE_URL "https://www.example.com") set(CPACK_NUGET_PACKAGE_REPOSITORY_URL "https://github.com/example/libfoobar.git") set(CPACK_NUGET_PACKAGE_REPOSITORY_TYPE git)