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_ICON
 166               CPACK_NUGET_<compName>_PACKAGE_ICON
 167
 168  .. versionadded:: 3.20
 169
 170  The filename of a 64x64 image with transparency background to use as the
 171  icon for the package in UI display.
 172
 173  * Mandatory : NO
 174  * Default   : -
 175
 176 .. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION_SUMMARY
 177               CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION_SUMMARY
 178
 179  A short description of the package for UI display. If omitted, a
 180  truncated version of description is used.
 181
 182  * Mandatory : NO
 183  * Default   : :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`
 184
 185 .. variable:: CPACK_NUGET_PACKAGE_RELEASE_NOTES
 186               CPACK_NUGET_<compName>_PACKAGE_RELEASE_NOTES
 187
 188  A description of the changes made in this release of the package,
 189  often used in UI like the Updates tab of the Visual Studio Package
 190  Manager in place of the package description.
 191
 192  * Mandatory : NO
 193  * Default   : -
 194
 195 .. variable:: CPACK_NUGET_PACKAGE_COPYRIGHT
 196               CPACK_NUGET_<compName>_PACKAGE_COPYRIGHT
 197
 198  Copyright details for the package.
 199
 200  * Mandatory : NO
 201  * Default   : -
 202
 203 .. variable:: CPACK_NUGET_PACKAGE_LANGUAGE
 204               CPACK_NUGET_<compName>_PACKAGE_LANGUAGE
 205
 206  .. versionadded:: 3.20
 207
 208  Locale specifier for the package, for example ``en_CA``.
 209
 210  * Mandatory : NO
 211  * Default   : -
 212
 213 .. variable:: CPACK_NUGET_PACKAGE_TAGS
 214               CPACK_NUGET_<compName>_PACKAGE_TAGS
 215
 216  A space-delimited list of tags and keywords that describe the
 217  package and aid discoverability of packages through search and
 218  filtering.
 219
 220  * Mandatory : NO
 221  * Default   : -
 222
 223 .. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES
 224               CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES
 225
 226  A list of package dependencies.
 227
 228  * Mandatory : NO
 229  * Default   : -
 230
 231 .. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES_<dependency>_VERSION
 232               CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES_<dependency>_VERSION
 233
 234  A `version specification`_ for the particular dependency, where
 235  ``<dependency>`` is an item of the dependency list (see above)
 236  transformed with ``MAKE_C_IDENTIFIER`` function of :command:`string`
 237  command.
 238
 239  * Mandatory : NO
 240  * Default   : -
 241
 242 .. variable:: CPACK_NUGET_PACKAGE_DEBUG
 243
 244  Enable debug messages while executing CPack NuGet generator.
 245
 246  * Mandatory : NO
 247  * Default   : OFF
 248
 249
 250 .. _nuget.org: http://nuget.org
 251 .. _version specification: https://docs.microsoft.com/en-us/nuget/reference/package-versioning#version-ranges-and-wildcards
 252 .. _(SPDX) license identifier: https://spdx.org/licenses/
 253 .. _SPDX specification: https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/
 254
 255 .. NuGet spec docs https://docs.microsoft.com/en-us/nuget/reference/nuspec