1CPack NuGet Generator
2---------------------
3
4.. versionadded:: 3.12
5
6When build a NuGet package there is no direct way to control an output
7filename due a lack of the corresponding CLI option of NuGet, so there
8is no ``CPACK_NUGET_PACKAGE_FILE_NAME`` variable. To form the output filename
9NuGet uses the package name and the version according to its built-in rules.
10
11Also, be aware that including a top level directory
12(``CPACK_INCLUDE_TOPLEVEL_DIRECTORY``) is ignored by this generator.
13
14
15Variables specific to CPack NuGet generator
16^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17
18The CPack NuGet generator may be used to create NuGet packages using
19:module:`CPack`. The CPack NuGet generator is a :module:`CPack` generator thus
20it uses the ``CPACK_XXX`` variables used by :module:`CPack`.
21
22The CPack NuGet generator has specific features which are controlled by the
23specifics ``CPACK_NUGET_XXX`` variables. In the "one per group" mode
24(see :variable:`CPACK_COMPONENTS_GROUPING`), ``<compName>`` placeholder
25in the variables below would contain a group name (uppercased and turned into
26a "C" identifier).
27
28List 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
256