Merge topic 'cpack-nuget'

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

Acked-by: Kitware Robot <[email protected]>
Merge-request: !5415

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

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/

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>

Modules/Internal/CPack/CPackNuGet.cmake

@@ -107,21 +107,44 @@ 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()
+
 # Print some debug info
 _cpack_nuget_debug("---[CPack NuGet Input Variables]---")
 _cpack_nuget_debug_var(CPACK_PACKAGE_NAME)
@@ -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)