Merge topic 'cpack-generator-documentation'

57e4c51e Help: Update old version release notes for CPack generator docs
41818308 Help: Add release notes for CPack generator documentation and module updates
48bc8b2b CPack: Move internal implementation modules into Internal/CPack directory
2a2829cc Help: Add new section for CPack generators
be626780 CPackIFW: Turn documentation into a block comment
0180524c

 Help: Move legacy CPack modules into separate section
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2149

Help/cpack_gen/archive.rst

+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.

Help/cpack_gen/bundle.rst

+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.)

Help/cpack_gen/cygwin.rst

+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.

Help/cpack_gen/deb.rst

+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::
+
+  set(CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION TRUE)
+
+ .. note::