4 The built in (binary) CPack DEB generator (Unix only)
6 Variables specific to CPack Debian (DEB) generator
7 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9 The CPack DEB generator may be used to create DEB package using :module:`CPack`.
10 The CPack DEB generator is a :module:`CPack` generator thus it uses the
11 ``CPACK_XXX`` variables used by :module:`CPack`.
13 The CPack DEB generator should work on any Linux host but it will produce
14 better deb package when Debian specific tools ``dpkg-xxx`` are usable on
17 The CPack DEB generator has specific features which are controlled by the
18 specifics ``CPACK_DEBIAN_XXX`` variables.
20 ``CPACK_DEBIAN_<COMPONENT>_XXXX`` variables may be used in order to have
21 **component** specific values. Note however that ``<COMPONENT>`` refers to
22 the **grouping name** written in upper case. It may be either a component name
23 or a component GROUP name.
25 Here are some CPack DEB generator wiki resources that are here for historic
26 reasons and are no longer maintained but may still prove useful:
28 - https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/Configuration
29 - https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/PackageGenerators#deb-unix-only
31 List of CPack DEB generator specific variables:
33 .. variable:: CPACK_DEB_COMPONENT_INSTALL
35 Enable component packaging for CPackDEB
40 If enabled (ON) multiple packages are generated. By default a single package
41 containing files of all components is generated.
43 .. variable:: CPACK_DEBIAN_PACKAGE_NAME
44 CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME
46 Set Package control field (variable is automatically transformed to lower
52 - :variable:`CPACK_PACKAGE_NAME` for non-component based
54 - :variable:`CPACK_DEBIAN_PACKAGE_NAME` suffixed with -<COMPONENT>
55 for component-based installations.
58 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME`` variables.
60 See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source
62 .. variable:: CPACK_DEBIAN_FILE_NAME
63 CPACK_DEBIAN_<COMPONENT>_FILE_NAME
70 * Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].deb``
72 This may be set to ``DEB-DEFAULT`` to allow the CPack DEB generator to generate
73 package file name by itself in deb format::
75 <PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb
77 Alternatively provided package file name must end
78 with either ``.deb`` or ``.ipk`` suffix.
80 .. versionadded:: 3.10
81 ``.ipk`` suffix used by OPKG packaging system.
85 Preferred setting of this variable is ``DEB-DEFAULT`` but for backward
86 compatibility with the CPack DEB generator in CMake prior to version 3.6 this
87 feature is disabled by default.
91 By using non default filenames duplicate names may occur. Duplicate files
92 get overwritten and it is up to the packager to set the variables in a
93 manner that will prevent such errors.
95 .. variable:: CPACK_DEBIAN_PACKAGE_EPOCH
97 .. versionadded:: 3.10
99 The Debian package epoch
104 Optional number that should be incremented when changing versioning schemas
105 or fixing mistakes in the version numbers of older packages.
107 .. variable:: CPACK_DEBIAN_PACKAGE_VERSION
109 The Debian package version
112 * Default : :variable:`CPACK_PACKAGE_VERSION`
114 This variable may contain only alphanumerics (A-Za-z0-9) and the characters
115 . + - ~ (full stop, plus, hyphen, tilde) and should start with a digit. If
116 :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` is not set then hyphens are not
121 For backward compatibility with CMake 3.9 and lower a failed test of this
122 variable's content is not a hard error when both
123 :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` and
124 :variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables are not set. An author
125 warning is reported instead.
127 .. variable:: CPACK_DEBIAN_PACKAGE_RELEASE
129 .. versionadded:: 3.6
131 The Debian package release - Debian revision number.
136 This is the numbering of the DEB package itself, i.e. the version of the
137 packaging and not the version of the content (see
138 :variable:`CPACK_DEBIAN_PACKAGE_VERSION`). One may change the default value
139 if the previous packaging was buggy and/or you want to put here a fancy Linux
140 distro specific numbering.
142 .. variable:: CPACK_DEBIAN_PACKAGE_ARCHITECTURE
143 CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE
145 The Debian package architecture
148 * Default : Output of ``dpkg --print-architecture`` (or ``i386``
149 if ``dpkg`` is not found)
151 .. versionadded:: 3.6
152 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`` variables.
154 .. variable:: CPACK_DEBIAN_PACKAGE_DEPENDS
155 CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS
157 Sets the Debian dependencies of this package.
162 - An empty string for non-component based installations
163 - :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS` for component-based
167 .. versionadded:: 3.3
168 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS`` variables.
172 If :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` or
173 more specifically :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`
174 is set for this component, the discovered dependencies will be appended
175 to :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` instead of
176 :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS`. If
177 :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` is an empty string,
178 only the automatically discovered dependencies will be set for this
183 set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)")
185 .. variable:: CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS
187 .. versionadded:: 3.6
189 Sets inter-component dependencies if listed with
190 :variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables.
195 .. variable:: CPACK_DEBIAN_PACKAGE_MAINTAINER
197 The Debian package maintainer
200 * Default : ``CPACK_PACKAGE_CONTACT``
202 .. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION
203 CPACK_DEBIAN_<COMPONENT>_DESCRIPTION
205 The Debian package description
210 - :variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` (component
211 based installers only) if set, or :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set, or
212 - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION` (component
213 based installers only) if set, or :variable:`CPACK_PACKAGE_DESCRIPTION` if set, or
214 - content of the file specified in :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` if set
216 If after that description is not set, :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` going to be
217 used if set. Otherwise, :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` will be added as the first
218 line of description as defined in `Debian Policy Manual`_.
220 .. versionadded:: 3.3
221 Per-component ``CPACK_COMPONENT_<compName>_DESCRIPTION`` variables.
223 .. versionadded:: 3.16
224 Per-component ``CPACK_DEBIAN_<COMPONENT>_DESCRIPTION`` variables.
226 .. versionadded:: 3.16
227 The ``CPACK_PACKAGE_DESCRIPTION_FILE`` variable.
229 .. _Debian Policy Manual: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description
231 .. variable:: CPACK_DEBIAN_PACKAGE_SECTION
232 CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION
234 Set Section control field e.g. admin, devel, doc, ...
239 .. versionadded:: 3.5
240 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION`` variables.
242 See https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections
244 .. variable:: CPACK_DEBIAN_ARCHIVE_TYPE
246 .. versionadded:: 3.7
250 The archive format used for creating the Debian package.
261 This variable previously defaulted to the ``paxr`` value, but ``dpkg``
262 has never supported that tar format. For backwards compatibility the
263 ``paxr`` value will be mapped to ``gnutar`` and a deprecation message
266 .. variable:: CPACK_DEBIAN_COMPRESSION_TYPE
268 .. versionadded:: 3.1
270 The compression used for creating the Debian package.
278 Lempel–Ziv–Markov chain algorithm
284 bzip2 Burrows–Wheeler algorithm
290 .. versionadded:: 3.22
292 Zstandard compression
295 .. variable:: CPACK_DEBIAN_PACKAGE_PRIORITY
296 CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY
298 Set Priority control field e.g. required, important, standard, optional,
302 * Default : "optional"
304 .. versionadded:: 3.5
305 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`` variables.
307 See https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities
309 .. variable:: CPACK_DEBIAN_PACKAGE_HOMEPAGE
311 The URL of the web site for this package, preferably (when applicable) the
312 site from which the original source can be obtained and any additional
313 upstream documentation or information may be found.
316 * Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL`
318 .. versionadded:: 3.12
319 The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable.
323 The content of this field is a simple URL without any surrounding
324 characters such as <>.
326 .. variable:: CPACK_DEBIAN_PACKAGE_SHLIBDEPS
327 CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS
329 May be set to ON in order to use ``dpkg-shlibdeps`` to generate
330 better package dependency list.
335 - :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` if set or
340 You may need set :variable:`CMAKE_INSTALL_RPATH` to an appropriate value
341 if you use this feature, because if you don't ``dpkg-shlibdeps``
342 may fail to find your own shared libs.
343 See https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/RPATH-handling
347 You can also set :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS`
348 to an appropriate value if you use this feature, in order to please
349 ``dpkg-shlibdeps``. However, you should only do this for private
350 shared libraries that could not get resolved otherwise.
352 .. versionadded:: 3.3
353 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`` variables.
355 .. versionadded:: 3.6
356 Correct handling of ``$ORIGIN`` in :variable:`CMAKE_INSTALL_RPATH`.
358 .. variable:: CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS
360 .. versionadded:: 3.20
362 May be set to a list of directories that will be given to ``dpkg-shlibdeps``
363 via its ``-l`` option. These will be searched by ``dpkg-shlibdeps`` in order
364 to find private shared library dependencies.
371 You should prefer to set :variable:`CMAKE_INSTALL_RPATH` to an appropriate
372 value if you use ``dpkg-shlibdeps``. The current option is really only
373 needed for private shared library dependencies.
375 .. variable:: CPACK_DEBIAN_PACKAGE_DEBUG
377 May be set when invoking cpack in order to trace debug information
378 during the CPack DEB generator run.
383 .. variable:: CPACK_DEBIAN_PACKAGE_PREDEPENDS
384 CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS
386 Sets the `Pre-Depends` field of the Debian package.
387 Like :variable:`Depends <CPACK_DEBIAN_PACKAGE_DEPENDS>`, except that it
388 also forces ``dpkg`` to complete installation of the packages named
389 before even starting the installation of the package which declares the
395 - An empty string for non-component based installations
396 - :variable:`CPACK_DEBIAN_PACKAGE_PREDEPENDS` for component-based
399 .. versionadded:: 3.4
400 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS`` variables.
402 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
404 .. variable:: CPACK_DEBIAN_PACKAGE_ENHANCES
405 CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES
407 Sets the `Enhances` field of the Debian package.
408 Similar to :variable:`Suggests <CPACK_DEBIAN_PACKAGE_SUGGESTS>` but works
409 in the opposite direction: declares that a package can enhance the
410 functionality of another package.
415 - An empty string for non-component based installations
416 - :variable:`CPACK_DEBIAN_PACKAGE_ENHANCES` for component-based
419 .. versionadded:: 3.4
420 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES`` variables.
422 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
424 .. variable:: CPACK_DEBIAN_PACKAGE_BREAKS
425 CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS
427 Sets the `Breaks` field of the Debian package.
428 When a binary package (P) declares that it breaks other packages (B),
429 ``dpkg`` will not allow the package (P) which declares `Breaks` be
430 **unpacked** unless the packages that will be broken (B) are deconfigured
432 As long as the package (P) is configured, the previously deconfigured
433 packages (B) cannot be reconfigured again.
438 - An empty string for non-component based installations
439 - :variable:`CPACK_DEBIAN_PACKAGE_BREAKS` for component-based
442 .. versionadded:: 3.4
443 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS`` variables.
445 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-breaks
447 .. variable:: CPACK_DEBIAN_PACKAGE_CONFLICTS
448 CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS
450 Sets the `Conflicts` field of the Debian package.
451 When one binary package declares a conflict with another using a `Conflicts`
452 field, ``dpkg`` will not allow them to be unpacked on the system at
458 - An empty string for non-component based installations
459 - :variable:`CPACK_DEBIAN_PACKAGE_CONFLICTS` for component-based
462 .. versionadded:: 3.4
463 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS`` variables.
465 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts
469 This is a stronger restriction than
470 :variable:`Breaks <CPACK_DEBIAN_PACKAGE_BREAKS>`, which prevents the
471 broken package from being configured while the breaking package is in
472 the "Unpacked" state but allows both packages to be unpacked at the same
475 .. variable:: CPACK_DEBIAN_PACKAGE_PROVIDES
476 CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES
478 Sets the `Provides` field of the Debian package.
479 A virtual package is one which appears in the `Provides` control field of
485 - An empty string for non-component based installations
486 - :variable:`CPACK_DEBIAN_PACKAGE_PROVIDES` for component-based
489 .. versionadded:: 3.4
490 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES`` variables.
492 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual
494 .. variable:: CPACK_DEBIAN_PACKAGE_REPLACES
495 CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES
497 Sets the `Replaces` field of the Debian package.
498 Packages can declare in their control file that they should overwrite
499 files in certain other packages, or completely replace other packages.
504 - An empty string for non-component based installations
505 - :variable:`CPACK_DEBIAN_PACKAGE_REPLACES` for component-based
508 .. versionadded:: 3.4
509 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES`` variables.
511 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
513 .. variable:: CPACK_DEBIAN_PACKAGE_RECOMMENDS
514 CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS
516 Sets the `Recommends` field of the Debian package.
517 Allows packages to declare a strong, but not absolute, dependency on other
523 - An empty string for non-component based installations
524 - :variable:`CPACK_DEBIAN_PACKAGE_RECOMMENDS` for component-based
527 .. versionadded:: 3.4
528 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS`` variables.
530 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
532 .. variable:: CPACK_DEBIAN_PACKAGE_SUGGESTS
533 CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS
535 Sets the `Suggests` field of the Debian package.
536 Allows packages to declare a suggested package install grouping.
541 - An empty string for non-component based installations
542 - :variable:`CPACK_DEBIAN_PACKAGE_SUGGESTS` for component-based
545 .. versionadded:: 3.4
546 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS`` variables.
548 See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
550 .. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS
552 .. versionadded:: 3.6
557 Allows to generate shlibs control file automatically. Compatibility is defined by
558 :variable:`CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY` variable value.
562 Libraries are only considered if they have both library name and version
563 set. This can be done by setting SOVERSION property with
564 :command:`set_target_properties` command.
566 .. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY
568 .. versionadded:: 3.6
570 Compatibility policy for auto-generated shlibs control file.
575 Defines compatibility policy for auto-generated shlibs control file.
576 Possible values: "=", ">="
578 See https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-sharedlibs-shlibdeps
580 .. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
581 CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA
583 This variable allow advanced user to add custom script to the
585 Typical usage is for conffiles, postinst, postrm, prerm.
592 set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
593 "${CMAKE_CURRENT_SOURCE_DIR}/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm")
595 .. versionadded:: 3.4
596 Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA`` variables.
598 .. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION
599 CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION
601 .. versionadded:: 3.4
603 This variable indicates if the Debian policy on control files should be
611 set(CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION TRUE)
613 This overrides the permissions on the original files, following the rules
615 https://www.debian.org/doc/debian-policy/ch-files.html#s-permissions-owners
619 The original permissions of the files will be used in the final
620 package unless this variable is set to ``TRUE``.
621 In particular, the scripts should have the proper executable
622 flag prior to the generation of the package.
624 .. variable:: CPACK_DEBIAN_PACKAGE_SOURCE
625 CPACK_DEBIAN_<COMPONENT>_PACKAGE_SOURCE
627 .. versionadded:: 3.5
629 Sets the ``Source`` field of the binary Debian package.
630 When the binary package name is not the same as the source package name
631 (in particular when several components/binaries are generated from one
632 source) the source from which the binary has been generated should be
633 indicated with the field ``Source``.
638 - An empty string for non-component based installations
639 - :variable:`CPACK_DEBIAN_PACKAGE_SOURCE` for component-based
642 See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source
646 This value is not interpreted. It is possible to pass an optional
647 revision number of the referenced source package as well.
649 Packaging of debug information
650 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
652 .. versionadded:: 3.13
654 Dbgsym packages contain debug symbols for debugging packaged binaries.
656 Dbgsym packaging has its own set of variables:
658 .. variable:: CPACK_DEBIAN_DEBUGINFO_PACKAGE
659 CPACK_DEBIAN_<component>_DEBUGINFO_PACKAGE
661 Enable generation of dbgsym .ddeb package(s).
668 Setting this also strips the ELF files in the generated non-dbgsym package,
669 which results in debuginfo only being available in the dbgsym package.
673 Binaries must contain debug symbols before packaging so use either ``Debug``
674 or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value.
676 Additionally, if :variable:`CPACK_STRIP_FILES` is set, the files will be stripped before
677 they get to the DEB generator, so will not contain debug symbols and
678 a dbgsym package will not get built. Do not use with :variable:`CPACK_STRIP_FILES`.
680 Building Debian packages on Windows
681 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
683 .. versionadded:: 3.10
685 To communicate UNIX file permissions from the install stage
686 to the CPack DEB generator the "cmake_mode_t" NTFS
687 alternate data stream (ADT) is used.
689 When a filesystem without ADT support is used only owner read/write
690 permissions can be preserved.
692 Reproducible packages
693 ^^^^^^^^^^^^^^^^^^^^^
695 .. versionadded:: 3.13
697 The environment variable ``SOURCE_DATE_EPOCH`` may be set to a UNIX
698 timestamp, defined as the number of seconds, excluding leap seconds,
699 since 01 Jan 1970 00:00:00 UTC. If set, the CPack DEB generator will
700 use its value for timestamps in the package.