Help/cpack_gen/nuget.rst

   1 CPack NuGet Generator
   2 ---------------------
   3
   4 .. versionadded:: 3.12
   5
   6 When build a NuGet package there is no direct way to control an output
   7 filename due a lack of the corresponding CLI option of NuGet, so there
   8 is no ``CPACK_NUGET_PACKAGE_FILE_NAME`` variable. To form the output filename
   9 NuGet uses the package name and the version according to its built-in rules.
  10
  11 Also, be aware that including a top level directory
  12 (``CPACK_INCLUDE_TOPLEVEL_DIRECTORY``) is ignored by this generator.
  13
  14
  15 Variables specific to CPack NuGet generator
  16 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  17
  18 The CPack NuGet generator may be used to create NuGet packages using
  19 :module:`CPack`. The CPack NuGet generator is a :module:`CPack` generator thus
  20 it uses the ``CPACK_XXX`` variables used by :module:`CPack`.
  21
  22 The CPack NuGet generator has specific features which are controlled by the
  23 specifics ``CPACK_NUGET_XXX`` variables. In the "one per group" mode
  24 (see :variable:`CPACK_COMPONENTS_GROUPING`), ``<compName>`` placeholder
  25 in the variables below would contain a group name (uppercased and turned into
  26 a "C" identifier).
  27
  28 List of CPack NuGet generator specific variables:
  29
  30 .. variable:: CPACK_NUGET_COMPONENT_INSTALL
  31
  32  Enable component packaging for CPack NuGet generator
  33
  34  * Mandatory : NO
  35  * Default   : OFF
  36
  37 .. variable:: CPACK_NUGET_PACKAGE_NAME
  38               CPACK_NUGET_<compName>_PACKAGE_NAME
  39
  40  The NUGET package name. ``CPACK_NUGET_PACKAGE_NAME`` is used as the
  41  package ``id`` on nuget.org_
  42
  43  * Mandatory : YES
  44  * Default   : :variable:`CPACK_PACKAGE_NAME`
  45
  46 .. variable:: CPACK_NUGET_PACKAGE_VERSION
  47               CPACK_NUGET_<compName>_PACKAGE_VERSION
  48
  49  The NuGet package version.
  50
  51  * Mandatory : YES
  52  * Default   : :variable:`CPACK_PACKAGE_VERSION`
  53
  54 .. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION
  55               CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION
  56
  57  A long description of the package for UI display.
  58
  59  * Mandatory : YES
  60  * Default   :
  61     - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION`,
  62     - ``CPACK_COMPONENT_GROUP_<groupName>_DESCRIPTION``,
  63     - :variable:`CPACK_PACKAGE_DESCRIPTION`
  64
  65 .. variable:: CPACK_NUGET_PACKAGE_AUTHORS
  66               CPACK_NUGET_<compName>_PACKAGE_AUTHORS
  67
  68  A comma-separated list of packages authors, matching the profile names
  69  on nuget.org_. These are displayed in the NuGet Gallery on
  70  nuget.org_ and are used to cross-reference packages by the same
  71  authors.
  72
  73  * Mandatory : YES
  74  * Default   : :variable:`CPACK_PACKAGE_VENDOR`
  75
  76 .. variable:: CPACK_NUGET_PACKAGE_TITLE
  77               CPACK_NUGET_<compName>_PACKAGE_TITLE
  78
  79  A human-friendly title of the package, typically used in UI displays
  80  as on nuget.org_ and the Package Manager in Visual Studio. If not
  81  specified, the package ID is used.
  82
  83  * Mandatory : NO
  84  * Default   :
  85     - :variable:`CPACK_COMPONENT_<compName>_DISPLAY_NAME`,
  86     - ``CPACK_COMPONENT_GROUP_<groupName>_DISPLAY_NAME``
  87
  88 .. variable:: CPACK_NUGET_PACKAGE_OWNERS
  89               CPACK_NUGET_<compName>_PACKAGE_OWNERS
  90
  91  A comma-separated list of the package creators using profile names
  92  on nuget.org_. This is often the same list as in authors,
  93  and is ignored when uploading the package to nuget.org_.
  94
  95  * Mandatory : NO
  96  * Default   : -
  97
  98 .. variable:: CPACK_NUGET_PACKAGE_HOMEPAGE_URL
  99               CPACK_NUGET_<compName>_PACKAGE_HOMEPAGE_URL
 100
 101  An URL for the package's home page, often shown in UI displays as well
 102  as nuget.org_.
 103
 104  * Mandatory : NO
 105  * Default   : :variable:`CPACK_PACKAGE_HOMEPAGE_URL`
 106
 107 .. variable:: CPACK_NUGET_PACKAGE_LICENSEURL
 108               CPACK_NUGET_<compName>_PACKAGE_LICENSEURL
 109
 110  .. deprecated:: 3.20
 111   Use a local license file
 112   (:variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`)
 113   or a `SPDX license identifier`_
 114   (:variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`) instead.
 115
 116  An URL for the package's license, often shown in UI displays as well
 117  as on nuget.org_.
 118
 119  * Mandatory : NO
 120  * Default   : -
 121
 122 .. variable:: CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION
 123               CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION
 124
 125  .. versionadded:: 3.20
 126
 127  A Software Package Data Exchange `SPDX license identifier`_ such as
 128  ``MIT``, ``BSD-3-Clause``, or ``LGPL-3.0-or-later``. In the case of a
 129  choice of licenses or more complex restrictions, compound license
 130  expressions may be formed using boolean operators, for example
 131  ``MIT OR BSD-3-Clause``.  See the `SPDX specification`_ for guidance
 132  on forming complex license expressions.
 133
 134  If ``CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`` is specified,
 135  ``CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`` is ignored.
 136
 137  * Mandatory : NO
 138  * Default   : -
 139
 140 .. variable:: CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME
 141               CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME
 142
 143  The package's license file in :file:`.txt` or :file:`.md` format.
 144
 145  If ``CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`` is specified,
 146  ``CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`` is ignored.
 147
 148  .. versionadded:: 3.20
 149
 150  * Mandatory : NO
 151  * Default   : -
 152
 153 .. variable:: CPACK_NUGET_PACKAGE_ICONURL
 154               CPACK_NUGET_<compName>_PACKAGE_ICONURL
 155
 156  .. deprecated:: 3.20
 157   Use a local icon file (:variable:`CPACK_NUGET_PACKAGE_ICON`) instead.
 158
 159  An URL for a 64x64 image with transparency background to use as the
 160  icon for the package in UI display.
 161
 162  * Mandatory : NO
 163  * Default   : -
 164
 165 .. variable:: CPACK_NUGET_PACKAGE_REQUIRE_LICENSE_ACCEPTANCE
 166
 167  When set to a true value, the user will be prompted to accept the license
 168  before installing the package.
 169
 170  * Mandatory : NO
 171  * Default   : -
 172
 173 .. variable:: CPACK_NUGET_PACKAGE_ICON
 174               CPACK_NUGET_<compName>_PACKAGE_ICON
 175
 176  .. versionadded:: 3.20
 177
 178  The filename of a 64x64 image with transparency background to use as the
 179  icon for the package in UI display.
 180
 181  * Mandatory : NO
 182  * Default   : -
 183
 184 .. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION_SUMMARY
 185               CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION_SUMMARY
 186
 187  A short description of the package for UI display. If omitted, a
 188  truncated version of description is used.
 189
 190  * Mandatory : NO
 191  * Default   : :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`
 192
 193 .. variable:: CPACK_NUGET_PACKAGE_RELEASE_NOTES
 194               CPACK_NUGET_<compName>_PACKAGE_RELEASE_NOTES
 195
 196  A description of the changes made in this release of the package,
 197  often used in UI like the Updates tab of the Visual Studio Package
 198  Manager in place of the package description.
 199
 200  * Mandatory : NO
 201  * Default   : -
 202
 203 .. variable:: CPACK_NUGET_PACKAGE_COPYRIGHT
 204               CPACK_NUGET_<compName>_PACKAGE_COPYRIGHT
 205
 206  Copyright details for the package.
 207
 208  * Mandatory : NO
 209  * Default   : -
 210
 211 .. variable:: CPACK_NUGET_PACKAGE_LANGUAGE
 212               CPACK_NUGET_<compName>_PACKAGE_LANGUAGE
 213
 214  .. versionadded:: 3.20
 215
 216  Locale specifier for the package, for example ``en_CA``.
 217
 218  * Mandatory : NO
 219  * Default   : -
 220
 221 .. variable:: CPACK_NUGET_PACKAGE_TAGS
 222               CPACK_NUGET_<compName>_PACKAGE_TAGS
 223
 224  A space-delimited list of tags and keywords that describe the
 225  package and aid discoverability of packages through search and
 226  filtering.
 227
 228  * Mandatory : NO
 229  * Default   : -
 230
 231 .. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES
 232               CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES
 233
 234  A list of package dependencies.
 235
 236  * Mandatory : NO
 237  * Default   : -
 238
 239 .. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES_<dependency>_VERSION
 240               CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES_<dependency>_VERSION
 241
 242  A `version specification`_ for the particular dependency, where
 243  ``<dependency>`` is an item of the dependency list (see above)
 244  transformed with ``MAKE_C_IDENTIFIER`` function of :command:`string`
 245  command.
 246
 247  * Mandatory : NO
 248  * Default   : -
 249
 250 .. variable:: CPACK_NUGET_PACKAGE_DEBUG
 251
 252  Enable debug messages while executing CPack NuGet generator.
 253
 254  * Mandatory : NO
 255  * Default   : OFF
 256
 257
 258 .. _nuget.org: https://www.nuget.org
 259 .. _version specification: https://learn.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges
 260 .. _SPDX license identifier: https://spdx.github.io/spdx-spec/SPDX-license-list
 261 .. _SPDX specification: https://spdx.github.io/spdx-spec/SPDX-license-expressions
 262
 263 .. NuGet spec docs https://docs.microsoft.com/en-us/nuget/reference/nuspec