From 41ae7c4e5161427eb46319231dcb475386862760 Mon Sep 17 00:00:00 2001 From: Bob Apthorpe Date: Thu, 22 Oct 2020 18:01:30 -0500 Subject: CPack/NuGet: Add settings for the license, icon, and language Also update the XML Schema. Fixes: #21348 --- Help/cpack_gen/nuget.rst | 65 ++++++++++++++++++++--- Help/release/dev/cpack-nuget.rst | 31 +++++++++++ Modules/Internal/CPack/CPack.NuGet.nuspec.in | 5 +- Modules/Internal/CPack/CPackNuGet.cmake | 78 ++++++++++++++++++++++++++-- 4 files changed, 168 insertions(+), 11 deletions(-) create mode 100644 Help/release/dev/cpack-nuget.rst diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst index f8aa626..39440b0 100644 --- 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__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__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__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__PACKAGE_LICENSE_FILE_NAME``) or a Software + Package Data Exchange `(SPDX) license identifier`_ or expression + (``CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`` or + ``CPACK_NUGET__PACKAGE_LICENSE_EXPRESSION``) + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION + CPACK_NUGET__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__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__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__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__PACKAGE_LANGUAGE + + Locale specifier for the package, for example ``en_CA``. + + * Mandatory : NO + * Default : - + .. variable:: CPACK_NUGET_PACKAGE_TAGS CPACK_NUGET__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 diff --git a/Help/release/dev/cpack-nuget.rst b/Help/release/dev/cpack-nuget.rst new file mode 100644 index 0000000..2c28b59 --- /dev/null +++ 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__PACKAGE_ICON` + allow package icons to be specified by local files. + - :variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` and + :variable:`CPACK_NUGET__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__PACKAGE_LICENSE_FILE_NAME` allow + licenses to be specified by local files. + - :variable:`CPACK_NUGET_PACKAGE_LANGUAGE` and + :variable:`CPACK_NUGET__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__PACKAGE_ICONURL` have been deprecated; + replace with a reference to a local icon file. + - :variable:`CPACK_NUGET_PACKAGE_LICENSEURL` and + :variable:`CPACK_NUGET__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/ diff --git a/Modules/Internal/CPack/CPack.NuGet.nuspec.in b/Modules/Internal/CPack/CPack.NuGet.nuspec.in index b7beb5d..d89d69f 100644 --- a/Modules/Internal/CPack/CPack.NuGet.nuspec.in +++ b/Modules/Internal/CPack/CPack.NuGet.nuspec.in @@ -1,5 +1,5 @@ - + @CPACK_NUGET_PACKAGE_NAME@ @@ -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@ diff --git a/Modules/Internal/CPack/CPackNuGet.cmake b/Modules/Internal/CPack/CPackNuGet.cmake index 20eed2e..56bbffd 100644 --- a/Modules/Internal/CPack/CPackNuGet.cmake +++ b/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}${_attributes}>${_value}" + 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) -- cgit v0.12