Commit 2a2829cc authored by Kyle Edwards's avatar Kyle Edwards

Help: Add new section for CPack generators

The documentation for CPack generators previously lived in their
respective internal CMake modules. This setup was misleading,
because it implied that you should include the modules in your own
code, which is not the case. Moving the documentation into a
separate section does a better job of hiding the internal modules,
which are just an implementation detail. The generator documentation
has also been modified to remove any references to the module name.

The CPackIFW module is a special exception: since it has user-facing
macros, the documentation for these macros has been kept in the module
page, while all other documentation related to the IFW generator has
been moved into the new section.

To make it easier to find the new documentation, the old help pages
for the CPack*.cmake modules have not been deleted, but have been
replaced with a link to their respective help page in the new
documentation section.
parent be626780
CPack Archive Generator
-----------------------
Archive CPack generator that supports packaging of sources and binaries in
different formats:
- 7Z - 7zip - (.7z)
- TBZ2 (.tar.bz2)
- TGZ (.tar.gz)
- TXZ (.tar.xz)
- TZ (.tar.Z)
- ZIP (.zip)
Variables specific to CPack Archive generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. variable:: CPACK_ARCHIVE_FILE_NAME
CPACK_ARCHIVE_<component>_FILE_NAME
Package file name without extension which is added automatically depending
on the archive format.
* Mandatory : YES
* Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].<extension>`` with
spaces replaced by '-'
.. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL
Enable component packaging for CPackArchive
* Mandatory : NO
* Default : OFF
If enabled (ON) multiple packages are generated. By default a single package
containing files of all components is generated.
CPack Bundle Generator
----------------------
CPack Bundle generator (Mac OS X) specific options
Variables specific to CPack Bundle generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Installers built on Mac OS X using the Bundle generator use the
aforementioned DragNDrop (CPACK_DMG_xxx) variables, plus the following
Bundle-specific parameters (CPACK_BUNDLE_xxx).
.. variable:: CPACK_BUNDLE_NAME
The name of the generated bundle. This appears in the OSX finder as the
bundle name. Required.
.. variable:: CPACK_BUNDLE_PLIST
Path to an OSX plist file that will be used for the generated bundle. This
assumes that the caller has generated or specified their own Info.plist
file. Required.
.. variable:: CPACK_BUNDLE_ICON
Path to an OSX icon file that will be used as the icon for the generated
bundle. This is the icon that appears in the OSX finder for the bundle, and
in the OSX dock when the bundle is opened. Required.
.. variable:: CPACK_BUNDLE_STARTUP_COMMAND
Path to a startup script. This is a path to an executable or script that
will be run whenever an end-user double-clicks the generated bundle in the
OSX Finder. Optional.
.. variable:: CPACK_BUNDLE_APPLE_CERT_APP
The name of your Apple supplied code signing certificate for the application.
The name usually takes the form "Developer ID Application: [Name]" or
"3rd Party Mac Developer Application: [Name]". If this variable is not set
the application will not be signed.
.. variable:: CPACK_BUNDLE_APPLE_ENTITLEMENTS
The name of the plist file that contains your apple entitlements for sandboxing
your application. This file is required for submission to the Mac App Store.
.. variable:: CPACK_BUNDLE_APPLE_CODESIGN_FILES
A list of additional files that you wish to be signed. You do not need to
list the main application folder, or the main executable. You should
list any frameworks and plugins that are included in your app bundle.
.. variable:: CPACK_BUNDLE_APPLE_CODESIGN_PARAMETER
Additional parameter that will passed to codesign.
Default value: "--deep -f"
.. variable:: CPACK_COMMAND_CODESIGN
Path to the codesign(1) command used to sign applications with an
Apple cert. This variable can be used to override the automatically
detected command (or specify its location if the auto-detection fails
to find it.)
CPack Cygwin Generator
----------------------
Cygwin CPack generator (Cygwin).
Variables specific to CPack Cygwin generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The
following variable is specific to installers build on and/or for
Cygwin:
.. variable:: CPACK_CYGWIN_PATCH_NUMBER
The Cygwin patch number. FIXME: This documentation is incomplete.
.. variable:: CPACK_CYGWIN_PATCH_FILE
The Cygwin patch file. FIXME: This documentation is incomplete.
.. variable:: CPACK_CYGWIN_BUILD_SCRIPT
The Cygwin build script. FIXME: This documentation is incomplete.
<
CPack Deb Generator
-------------------
The built in (binary) CPack Deb generator (Unix only)
Variables specific to CPack Debian (DEB) generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The CPack Deb generator may be used to create Deb package using :module:`CPack`.
The CPack Deb generator is a :module:`CPack` generator thus it uses the
``CPACK_XXX`` variables used by :module:`CPack`.
The CPack Deb generator should work on any Linux host but it will produce
better deb package when Debian specific tools ``dpkg-xxx`` are usable on
the build system.
The CPack Deb generator has specific features which are controlled by the
specifics :code:`CPACK_DEBIAN_XXX` variables.
:code:`CPACK_DEBIAN_<COMPONENT>_XXXX` variables may be used in order to have
**component** specific values. Note however that ``<COMPONENT>`` refers to
the **grouping name** written in upper case. It may be either a component name
or a component GROUP name.
Here are some CPack Deb generator wiki resources that are here for historic
reasons and are no longer maintained but may still prove useful:
- https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Configuration
- https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators#deb-unix-only
List of CPack Deb generator specific variables:
.. variable:: CPACK_DEB_COMPONENT_INSTALL
Enable component packaging for CPackDEB
* Mandatory : NO
* Default : OFF
If enabled (ON) multiple packages are generated. By default a single package
containing files of all components is generated.
.. variable:: CPACK_DEBIAN_PACKAGE_NAME
CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME
Set Package control field (variable is automatically transformed to lower
case).
* Mandatory : YES
* Default :
- :variable:`CPACK_PACKAGE_NAME` for non-component based
installations
- :variable:`CPACK_DEBIAN_PACKAGE_NAME` suffixed with -<COMPONENT>
for component-based installations.
See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source
.. variable:: CPACK_DEBIAN_FILE_NAME
CPACK_DEBIAN_<COMPONENT>_FILE_NAME
Package file name.
* Mandatory : YES
* Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].deb``
This may be set to ``DEB-DEFAULT`` to allow the CPack Deb generator to generate
package file name by itself in deb format::
<PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb
Alternatively provided package file name must end
with either ``.deb`` or ``.ipk`` suffix.
.. note::
Preferred setting of this variable is ``DEB-DEFAULT`` but for backward
compatibility with the CPack Deb generator in CMake prior to version 3.6 this
feature is disabled by default.
.. note::
By using non default filenames duplicate names may occur. Duplicate files
get overwritten and it is up to the packager to set the variables in a
manner that will prevent such errors.
.. variable:: CPACK_DEBIAN_PACKAGE_EPOCH
The Debian package epoch
* Mandatory : No
* Default : -
Optional number that should be incremented when changing versioning schemas
or fixing mistakes in the version numbers of older packages.
.. variable:: CPACK_DEBIAN_PACKAGE_VERSION
The Debian package version
* Mandatory : YES
* Default : :variable:`CPACK_PACKAGE_VERSION`
This variable may contain only alphanumerics (A-Za-z0-9) and the characters
. + - ~ (full stop, plus, hyphen, tilde) and should start with a digit. If
:variable:`CPACK_DEBIAN_PACKAGE_RELEASE` is not set then hyphens are not
allowed.
.. note::
For backward compatibility with CMake 3.9 and lower a failed test of this
variable's content is not a hard error when both
:variable:`CPACK_DEBIAN_PACKAGE_RELEASE` and
:variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables are not set. An author
warning is reported instead.
.. variable:: CPACK_DEBIAN_PACKAGE_RELEASE
The Debian package release - Debian revision number.
* Mandatory : No
* Default : -
This is the numbering of the DEB package itself, i.e. the version of the
packaging and not the version of the content (see
:variable:`CPACK_DEBIAN_PACKAGE_VERSION`). One may change the default value
if the previous packaging was buggy and/or you want to put here a fancy Linux
distro specific numbering.
.. variable:: CPACK_DEBIAN_PACKAGE_ARCHITECTURE
CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE
The Debian package architecture
* Mandatory : YES
* Default : Output of :code:`dpkg --print-architecture` (or :code:`i386`
if :code:`dpkg` is not found)
.. variable:: CPACK_DEBIAN_PACKAGE_DEPENDS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS
Sets the Debian dependencies of this package.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS` for component-based
installations.
.. note::
If :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` or
more specifically :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`
is set for this component, the discovered dependencies will be appended
to :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` instead of
:variable:`CPACK_DEBIAN_PACKAGE_DEPENDS`. If
:variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` is an empty string,
only the automatically discovered dependencies will be set for this
component.
Example::
set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)")
.. variable:: CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS
Sets inter component dependencies if listed with
:variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables.
* Mandatory : NO
* Default : -
.. variable:: CPACK_DEBIAN_PACKAGE_MAINTAINER
The Debian package maintainer
* Mandatory : YES
* Default : :code:`CPACK_PACKAGE_CONTACT`
.. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION
CPACK_COMPONENT_<COMPONENT>_DESCRIPTION
The Debian package description
* Mandatory : YES
* Default :
- :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set or
- :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`
.. variable:: CPACK_DEBIAN_PACKAGE_SECTION
CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION
Set Section control field e.g. admin, devel, doc, ...
* Mandatory : YES
* Default : "devel"
See https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections
.. variable:: CPACK_DEBIAN_ARCHIVE_TYPE
The archive format used for creating the Debian package.
* Mandatory : YES
* Default : "paxr"
Possible values are:
- paxr
- gnutar
.. note::
Default pax archive format is the most portable format and generates
packages that do not treat sparse files specially.
GNU tar format on the other hand supports longer filenames.
.. variable:: CPACK_DEBIAN_COMPRESSION_TYPE
The compression used for creating the Debian package.
* Mandatory : YES
* Default : "gzip"
Possible values are:
- lzma
- xz
- bzip2
- gzip
.. variable:: CPACK_DEBIAN_PACKAGE_PRIORITY
CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY
Set Priority control field e.g. required, important, standard, optional,
extra
* Mandatory : YES
* Default : "optional"
See https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities
.. variable:: CPACK_DEBIAN_PACKAGE_HOMEPAGE
The URL of the web site for this package, preferably (when applicable) the
site from which the original source can be obtained and any additional
upstream documentation or information may be found.
* Mandatory : NO
* Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL`
.. note::
The content of this field is a simple URL without any surrounding
characters such as <>.
.. variable:: CPACK_DEBIAN_PACKAGE_SHLIBDEPS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS
May be set to ON in order to use :code:`dpkg-shlibdeps` to generate
better package dependency list.
* Mandatory : NO
* Default :
- :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` if set or
- OFF
.. note::
You may need set :variable:`CMAKE_INSTALL_RPATH` to an appropriate value
if you use this feature, because if you don't :code:`dpkg-shlibdeps`
may fail to find your own shared libs.
See https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/RPATH-handling
.. variable:: CPACK_DEBIAN_PACKAGE_DEBUG
May be set when invoking cpack in order to trace debug information
during the CPack Deb generator run.
* Mandatory : NO
* Default : -
.. variable:: CPACK_DEBIAN_PACKAGE_PREDEPENDS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS
Sets the `Pre-Depends` field of the Debian package.
Like :variable:`Depends <CPACK_DEBIAN_PACKAGE_DEPENDS>`, except that it
also forces :code:`dpkg` to complete installation of the packages named
before even starting the installation of the package which declares the
pre-dependency.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_PREDEPENDS` for component-based
installations.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_ENHANCES
CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES
Sets the `Enhances` field of the Debian package.
Similar to :variable:`Suggests <CPACK_DEBIAN_PACKAGE_SUGGESTS>` but works
in the opposite direction: declares that a package can enhance the
functionality of another package.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_ENHANCES` for component-based
installations.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_BREAKS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS
Sets the `Breaks` field of the Debian package.
When a binary package (P) declares that it breaks other packages (B),
:code:`dpkg` will not allow the package (P) which declares `Breaks` be
**unpacked** unless the packages that will be broken (B) are deconfigured
first.
As long as the package (P) is configured, the previously deconfigured
packages (B) cannot be reconfigured again.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_BREAKS` for component-based
installations.
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-breaks
.. variable:: CPACK_DEBIAN_PACKAGE_CONFLICTS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS
Sets the `Conflicts` field of the Debian package.
When one binary package declares a conflict with another using a `Conflicts`
field, :code:`dpkg` will not allow them to be unpacked on the system at
the same time.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_CONFLICTS` for component-based
installations.
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts
.. note::
This is a stronger restriction than
:variable:`Breaks <CPACK_DEBIAN_PACKAGE_BREAKS>`, which prevents the
broken package from being configured while the breaking package is in
the "Unpacked" state but allows both packages to be unpacked at the same
time.
.. variable:: CPACK_DEBIAN_PACKAGE_PROVIDES
CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES
Sets the `Provides` field of the Debian package.
A virtual package is one which appears in the `Provides` control field of
another package.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_PROVIDES` for component-based
installations.
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual
.. variable:: CPACK_DEBIAN_PACKAGE_REPLACES
CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES
Sets the `Replaces` field of the Debian package.
Packages can declare in their control file that they should overwrite
files in certain other packages, or completely replace other packages.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_REPLACES` for component-based
installations.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_RECOMMENDS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS
Sets the `Recommends` field of the Debian package.
Allows packages to declare a strong, but not absolute, dependency on other
packages.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_RECOMMENDS` for component-based
installations.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_SUGGESTS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS
Sets the `Suggests` field of the Debian package.
Allows packages to declare a suggested package install grouping.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_SUGGESTS` for component-based
installations.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS
* Mandatory : NO
* Default : OFF
Allows to generate shlibs control file automatically. Compatibility is defined by
:variable:`CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY` variable value.
.. note::
Libraries are only considered if they have both library name and version
set. This can be done by setting SOVERSION property with
:command:`set_target_properties` command.
.. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY
Compatibility policy for auto-generated shlibs control file.
* Mandatory : NO
* Default : "="
Defines compatibility policy for auto-generated shlibs control file.
Possible values: "=", ">="
See https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-sharedlibs-shlibdeps
.. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA
This variable allow advanced user to add custom script to the
control.tar.gz.
Typical usage is for conffiles, postinst, postrm, prerm.
* Mandatory : NO
* Default : -
Usage::
set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
"${CMAKE_CURRENT_SOURCE_DIR}/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm")
.. note::
The original permissions of the files will be used in the final
package unless the variable
:variable:`CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION` is set.
In particular, the scripts should have the proper executable
flag prior to the generation of the package.
.. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION
CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION
This variable indicates if the Debian policy on control files should be
strictly followed.
* Mandatory : NO
* Default : FALSE
Usage::