CPack/NuGet: Add settings for the license, icon, and language

Also update the XML Schema. Fixes: #21348
2026-02-22 06:59:01 -06:00 · 2020-10-22 18:01:30 -05:00
parent 3a82ff6a11
commit 41ae7c4e51
4 changed files with 168 additions and 11 deletions
--- a/Help/cpack_gen/nuget.rst
+++ b/Help/cpack_gen/nuget.rst
@@ -3,7 +3,7 @@ CPack NuGet Generator

 When build a NuGet package there is no direct way to control an output
 filename due a lack of the corresponding CLI option of NuGet, so there
-is no ``CPACK_NUGET_PACKAGE_FILENAME`` variable. To form the output filename
+is no ``CPACK_NUGET_PACKAGE_FILE_NAME`` variable. To form the output filename
 NuGet uses the package name and the version according to its built-in rules.

 Also, be aware that including a top level directory
@@ -35,7 +35,8 @@ List of CPack NuGet generator specific variables:
 .. variable:: CPACK_NUGET_PACKAGE_NAME
              CPACK_NUGET_<compName>_PACKAGE_NAME

- The NUGET package name.
+ The NUGET package name. ``CPACK_NUGET_PACKAGE_NAME`` is used as the
+ package ``id`` on nuget.org_

 * Mandatory : YES
 * Default   : :variable:`CPACK_PACKAGE_NAME`
@@ -95,7 +96,7 @@ List of CPack NuGet generator specific variables:
 .. variable:: CPACK_NUGET_PACKAGE_HOMEPAGE_URL
              CPACK_NUGET_<compName>_PACKAGE_HOMEPAGE_URL

- A URL for the package's home page, often shown in UI displays as well
+ An URL for the package's home page, often shown in UI displays as well
 as nuget.org_.

 * Mandatory : NO
@@ -104,8 +105,40 @@ List of CPack NuGet generator specific variables:
 .. variable:: CPACK_NUGET_PACKAGE_LICENSEURL
              CPACK_NUGET_<compName>_PACKAGE_LICENSEURL

- A URL for the package's license, often shown in UI displays as well
- as nuget.org_.
+ An URL for the package's license, often shown in UI displays as well
+ as on nuget.org_. To be deprecated in favor of a reference to a local
+ license file (``CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`` or
+ ``CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME``) or a Software
+ Package Data Exchange `(SPDX) license identifier`_ or expression
+ (``CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`` or
+ ``CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION``)
+
+ * Mandatory : NO
+ * Default   : -
+
+.. variable:: CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION
+              CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION
+
+ A Software Package Data Exchange `(SPDX) license identifier`_ such as
+ ``MIT``, ``BSD-3-Clause``, or ``LGPL-3.0-or-later``. In the case of a
+ choice of licenses or more complex restrictions, compound license
+ expressions may be formed using boolean operators, for example
+ ``MIT OR BSD-3-Clause``.  See the `SPDX specification`_ for guidance
+ on forming complex license expressions.
+
+ If ``CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`` is specified,
+ ``CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`` is ignored.
+
+ * Mandatory : NO
+ * Default   : -
+
+.. variable:: CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME
+              CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME
+
+ The package's license file in :file:`.txt` or :file:`.md` format.
+
+ If ``CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`` is specified,
+ ``CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`` is ignored.

 * Mandatory : NO
 * Default   : -
@@ -113,7 +146,17 @@ List of CPack NuGet generator specific variables:
 .. variable:: CPACK_NUGET_PACKAGE_ICONURL
              CPACK_NUGET_<compName>_PACKAGE_ICONURL

- A URL for a 64x64 image with transparency background to use as the
+ An URL for a 64x64 image with transparency background to use as the
+ icon for the package in UI display. To be deprecated in favor of
+ ``CPACK_NUGET_PACKAGE_ICON``.
+
+ * Mandatory : NO
+ * Default   : -
+
+.. variable:: CPACK_NUGET_PACKAGE_ICON
+              CPACK_NUGET_<compName>_PACKAGE_ICON
+
+ The filename of a 64x64 image with transparency background to use as the
 icon for the package in UI display.

 * Mandatory : NO
@@ -146,6 +189,14 @@ List of CPack NuGet generator specific variables:
 * Mandatory : NO
 * Default   : -

+.. variable:: CPACK_NUGET_PACKAGE_LANGUAGE
+              CPACK_NUGET_<compName>_PACKAGE_LANGUAGE
+
+ Locale specifier for the package, for example ``en_CA``.
+
+ * Mandatory : NO
+ * Default   : -
+
 .. variable:: CPACK_NUGET_PACKAGE_TAGS
              CPACK_NUGET_<compName>_PACKAGE_TAGS

@@ -185,5 +236,7 @@ List of CPack NuGet generator specific variables:

 .. _nuget.org: http://nuget.org
 .. _version specification: https://docs.microsoft.com/en-us/nuget/reference/package-versioning#version-ranges-and-wildcards
+.. _(SPDX) license identifier: https://spdx.org/licenses/
+.. _SPDX specification: https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/

 .. NuGet spec docs https://docs.microsoft.com/en-us/nuget/reference/nuspec
--- a/Help/release/dev/cpack-nuget.rst
+++ b/Help/release/dev/cpack-nuget.rst
@@ -0,0 +1,31 @@
+cpack-nuget
+-----------
+
+* The :cpack_gen:`CPack NuGet Generator` gained options:
+
+  - :variable:`CPACK_NUGET_PACKAGE_ICON` and
+    :variable:`CPACK_NUGET_<compName>_PACKAGE_ICON`
+    allow package icons to be specified by local files.
+  - :variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` and
+    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION` add
+    support for specifying licenses recognized by the
+    `Software Package Data Exchange`_ (SPDX).
+  - :variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` and
+    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME` allow
+    licenses to be specified by local files.
+  - :variable:`CPACK_NUGET_PACKAGE_LANGUAGE` and
+    :variable:`CPACK_NUGET_<compName>_PACKAGE_LANGUAGE` allow the locale
+    for a package to be specified, for example ``en_CA``.
+
+ Some other variables have been deprecated to reflect changes in the
+ NuGet specification:
+
+ - :variable:`CPACK_NUGET_PACKAGE_ICONURL` and
+   :variable:`CPACK_NUGET_<compName>_PACKAGE_ICONURL` have been deprecated;
+   replace with a reference to a local icon file.
+ - :variable:`CPACK_NUGET_PACKAGE_LICENSEURL` and
+   :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSEURL` have been deprecated;
+   replace with a reference to the project's license file or SPDX
+   license expression.
+
+.. _Software Package Data Exchange: https://spdx.org/
--- a/Modules/Internal/CPack/CPack.NuGet.nuspec.in
+++ b/Modules/Internal/CPack/CPack.NuGet.nuspec.in
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
+<package xmlns="http://schemas.microsoft.com/packaging/2011/08/nuspec.xsd">
    <metadata>
        <!-- Required elements-->
        <id>@CPACK_NUGET_PACKAGE_NAME@</id>
@@ -12,11 +12,14 @@
        @_CPACK_NUGET_OWNERS_TAG@
        @_CPACK_NUGET_PROJECTURL_TAG@
        @_CPACK_NUGET_LICENSEURL_TAG@
+        @_CPACK_NUGET_LICENSE_TAG@
        @_CPACK_NUGET_ICONURL_TAG@
+        @_CPACK_NUGET_ICON_TAG@
        @_CPACK_NUGET_REQUIRELICENSEACCEPTANCE_TAG@
        @_CPACK_NUGET_SUMMARY_TAG@
        @_CPACK_NUGET_RELEASENOTES_TAG@
        @_CPACK_NUGET_COPYRIGHT_TAG@
+        @_CPACK_NUGET_LANGUAGE_TAG@
        @_CPACK_NUGET_TAGS_TAG@
        @_CPACK_NUGET_DEPENDENCIES_TAG@
    </metadata>
--- a/Modules/Internal/CPack/CPackNuGet.cmake
+++ b/Modules/Internal/CPack/CPackNuGet.cmake
@@ -107,18 +107,41 @@ endfunction()
 function(_cpack_nuget_variable_fallback_and_wrap_into_element ELEMENT NUGET_VAR_NAME)
    set(_options)
    set(_one_value_args)
-    set(_multi_value_args FALLBACK_VARS)
-    cmake_parse_arguments(PARSE_ARGV 0 _args "${_options}" "${_one_value_args}" "${_multi_value_args}")
+    set(_multi_value_args FALLBACK_VARS ATTRIBUTES)
+    cmake_parse_arguments(PARSE_ARGV 2 _args "${_options}" "${_one_value_args}" "${_multi_value_args}")
+
+    if(_args_ATTRIBUTES)
+        list(JOIN _args_ATTRIBUTES " " _attributes)
+        string(PREPEND _attributes " ")
+    endif()

    _cpack_nuget_variable_fallback(_value ${NUGET_VAR_NAME} ${ARGN} USE_CDATA)

+    string(TOUPPER "${ELEMENT}" _ELEMENT_UP)
    if(_value)
-        string(TOUPPER "${ELEMENT}" _ELEMENT_UP)
        set(
            _CPACK_NUGET_${_ELEMENT_UP}_TAG
-            "<${ELEMENT}>${_value}</${ELEMENT}>"
+            "<${ELEMENT}${_attributes}>${_value}</${ELEMENT}>"
            PARENT_SCOPE
          )
+    elseif(_attributes)
+        set(
+            _CPACK_NUGET_${_ELEMENT_UP}_TAG
+            "<${ELEMENT}${_attributes} />"
+            PARENT_SCOPE
+          )
+    endif()
+endfunction()
+
+# Warn of obsolete nuspec fields, referencing CMake variables and suggested
+# replacement, if any
+function(_cpack_nuget_deprecation_warning NUGET_ELEMENT VARNAME REPLACEMENT)
+    if(${VARNAME})
+        if(REPLACEMENT)
+            message(DEPRECATION "nuspec element `${NUGET_ELEMENT}` is deprecated in NuGet; consider replacing `${VARNAME}` with `${REPLACEMENT}`")
+        else()
+            message(DEPRECATION "nuspec element `${NUGET_ELEMENT}` is deprecated in NuGet; consider removing `${VARNAME}`")
+        endif()
    endif()
 endfunction()

@@ -168,6 +191,21 @@ function(_cpack_nuget_render_spec)
        set(CPACK_NUGET_PACKAGE_NAME "${CPACK_PACKAGE_NAME}")
    endif()

+    # Warn about deprecated nuspec elements; warnings only display if
+    # variable is set
+    # Note that while nuspec's "summary" element is deprecated, there
+    # is no suggested replacement so (for now) no deprecation warning
+    # is shown for `CPACK_NUGET_*_DESCRIPTION_SUMMARY`
+    _cpack_nuget_deprecation_warning("licenseUrl" CPACK_NUGET_PACKAGE_LICENSEURL
+        "CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME or CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION")
+    _cpack_nuget_deprecation_warning("licenseUrl" CPACK_NUGET_${CPACK_NUGET_PACKAGE_COMPONENT}_LICENSEURL
+        "CPACK_NUGET_${CPACK_NUGET_PACKAGE_COMPONENT}_LICENSE_FILE_NAME or CPACK_NUGET_${CPACK_NUGET_PACKAGE_COMPONENT}_LICENSE_EXPRESSION")
+    _cpack_nuget_deprecation_warning("iconUrl" CPACK_NUGET_PACKAGE_ICONURL
+        "CPACK_NUGET_PACKAGE_ICON")
+    _cpack_nuget_deprecation_warning("iconUrl" CPACK_NUGET_${CPACK_NUGET_PACKAGE_COMPONENT}_ICONURL
+        "CPACK_NUGET_${CPACK_NUGET_PACKAGE_COMPONENT}_ICON")
+
+    # Set nuspec fields
    _cpack_nuget_variable_fallback(
        CPACK_NUGET_PACKAGE_VERSION VERSION
        FALLBACK_VARS
@@ -207,8 +245,35 @@ function(_cpack_nuget_render_spec)
        FALLBACK_VARS
            CPACK_PACKAGE_HOMEPAGE_URL
      )
+
+    # "licenseUrl" is deprecated in favor of "license"
    _cpack_nuget_variable_fallback_and_wrap_into_element(licenseUrl LICENSEURL)
+
+    # "iconUrl" is deprecated in favor of "icon"
    _cpack_nuget_variable_fallback_and_wrap_into_element(iconUrl ICONURL)
+
+    # "license" takes a "type" attribute of either "file" or "expression"
+    # "file" refers to a file path of a .txt or .md file relative to the installation root
+    # "expression" refers to simple or compound expression of license identifiers
+    # listed at https://spdx.org/licenses/
+    # Note that only one of CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME and
+    # CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION may be specified. If both are specified,
+    # CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME takes precedence and CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION is ignored.
+    if(CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME)
+        _cpack_nuget_variable_fallback_and_wrap_into_element(
+            license LICENSE_FILE_NAME
+            ATTRIBUTES [[type="file"]]
+          )
+    elseif(CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION)
+        _cpack_nuget_variable_fallback_and_wrap_into_element(
+            license LICENSE_EXPRESSION
+            ATTRIBUTES [[type="expression"]]
+          )
+    endif()
+
+    # "icon" refers to a file path relative to the installation root
+    _cpack_nuget_variable_fallback_and_wrap_into_element(icon ICON)
+    # "summary" is deprecated in favor of "description"
    _cpack_nuget_variable_fallback_and_wrap_into_element(
        summary DESCRIPTION_SUMMARY
        FALLBACK_VARS
@@ -222,7 +287,12 @@ function(_cpack_nuget_render_spec)
    endif()
    _cpack_nuget_variable_fallback_and_wrap_into_element(releaseNotes RELEASE_NOTES)
    _cpack_nuget_variable_fallback_and_wrap_into_element(copyright COPYRIGHT)
+    # "language" is a locale identifier such as "en_CA"
+    _cpack_nuget_variable_fallback_and_wrap_into_element(language LANGUAGE)
    _cpack_nuget_variable_fallback_and_wrap_into_element(tags TAGS LIST_GLUE " ")
+    # "repository" holds repository metadata consisting of four optional
+    # attributes: "type", "url", "branch", and "commit". While all fields are
+    # considered optional, they are not independent. Currently unsupported.

    # Handle dependencies
    _cpack_nuget_variable_fallback(_deps DEPENDENCIES)