CPack
: foreach generator, it thenThe CPack module generates binary and source installers in a variety of formats using the cpack program. Inclusion of the CPack module adds two new targets to the resulting makefiles, package and package_source, which build the binary and source installers, respectively. The generated binary installers contain everything installed via CMake's INSTALL command (and the deprecated INSTALL_FILES, INSTALL_PROGRAMS, and INSTALL_TARGETS commands).
For certain kinds of binary installers (including the graphical installers on Mac OS X and Windows), CPack generates installers that allow users to select individual application components to install. See CPackComponent module for that.
The CPACK_GENERATOR variable has different meanings in different contexts. In your CMakeLists.txt file, CPACK_GENERATOR is a *list of generators*: when run with no other arguments, CPack will iterate over that list and produce one package for each generator. In a CPACK_PROJECT_CONFIG_FILE, though, CPACK_GENERATOR is a *string naming a single generator*. If you need per-cpack- generator logic to control *other* cpack settings, then you need a CPACK_PROJECT_CONFIG_FILE.
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file CMakeCPackOptions.cmake.in for an example.
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only need contain overrides.
Here's how it works:
CPACK_GENERATOR list variable (unless told to use just a
specific one via -G on the command line...)
- sets CPACK_GENERATOR to the one currently being iterated
- includes the CPACK_PROJECT_CONFIG_FILE
- produces the package for that generator
This is the key: For each generator listed in CPACK_GENERATOR in CPackConfig.cmake, cpack will *reset* CPACK_GENERATOR internally to *the one currently being used* and then include the CPACK_PROJECT_CONFIG_FILE.
Before including this CPack module in your CMakeLists.txt file, there are a variety of variables that can be set to customize the resulting installers. The most commonly-used variables are:
CPACK_PACKAGE_NAME - The name of the package (or application). If
not specified, defaults to the project name.
CPACK_PACKAGE_VENDOR - The name of the package vendor (e.g.,
"Kitware").
CPACK_PACKAGE_VERSION_MAJOR - Package major Version
CPACK_PACKAGE_VERSION_MINOR - Package minor Version
CPACK_PACKAGE_VERSION_PATCH - Package patch Version
CPACK_PACKAGE_DESCRIPTION_FILE - A text file used to describe the
project. Used, for example, the introduction screen of a
CPack-generated Windows installer to describe the project.
CPACK_PACKAGE_DESCRIPTION_SUMMARY - Short description of the
project (only a few words).
CPACK_PACKAGE_FILE_NAME - The name of the package file to generate,
not including the extension. For example, cmake-2.6.1-Linux-i686.
CPACK_PACKAGE_INSTALL_DIRECTORY - Installation directory on the
target system, e.g., "CMake 2.5".
CPACK_PROJECT_CONFIG_FILE - File included at cpack time, once per
generator after setting CPACK_GENERATOR to the actual generator
being used. Allows per-generator setting of CPACK_* variables at
cpack time.
CPACK_RESOURCE_FILE_LICENSE - License file for the project, which
will typically be displayed to the user (often with an explicit
"Accept" button, for graphical installers) prior to installation.
CPACK_RESOURCE_FILE_README - ReadMe file for the project, which
typically describes in some detail
CPACK_RESOURCE_FILE_WELCOME - Welcome file for the project, which
welcomes users to this installer. Typically used in the graphical
installers on Windows and Mac OS X.
CPACK_MONOLITHIC_INSTALL - Disables the component-based
installation mechanism, so that all components are always installed.
CPACK_GENERATOR - List of CPack generators to use. If not
specified, CPack will create a set of options (e.g.,
CPACK_BINARY_NSIS) allowing the user to enable/disable individual
generators.
CPACK_OUTPUT_CONFIG_FILE - The name of the CPack configuration file
for binary installers that will be generated by the CPack
module. Defaults to CPackConfig.cmake.
CPACK_PACKAGE_EXECUTABLES - Lists each of the executables along
with a text label, to be used to create Start Menu shortcuts on
Windows. For example, setting this to the list ccmake;CMake will
create a shortcut named "CMake" that will execute the installed
executable ccmake.
CPACK_STRIP_FILES - List of files to be stripped. Starting with
CMake 2.6.0 CPACK_STRIP_FILES will be a boolean variable which
enables stripping of all files (a list of files evaluates to TRUE
in CMake, so this change is compatible).
The following CPack variables are specific to source packages, and will not affect binary packages:
CPACK_SOURCE_PACKAGE_FILE_NAME - The name of the source package,
e.g., cmake-2.6.1
CPACK_SOURCE_STRIP_FILES - List of files in the source tree that
will be stripped. Starting with CMake 2.6.0
CPACK_SOURCE_STRIP_FILES will be a boolean variable which enables
stripping of all files (a list of files evaluates to TRUE in CMake,
so this change is compatible).
CPACK_SOURCE_GENERATOR - List of generators used for the source
packages. As with CPACK_GENERATOR, if this is not specified then
CPack will create a set of options (e.g., CPACK_SOURCE_ZIP)
allowing users to select which packages will be generated.
CPACK_SOURCE_OUTPUT_CONFIG_FILE - The name of the CPack
configuration file for source installers that will be generated by
the CPack module. Defaults to CPackSourceConfig.cmake.
CPACK_SOURCE_IGNORE_FILES - Pattern of files in the source tree
that won't be packaged when building a source package. This is a
list of patterns, e.g., /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
The following variables are specific to the DragNDrop installers built on Mac OS X:
CPACK_DMG_VOLUME_NAME - The volume name of the generated disk
image. Defaults to CPACK_PACKAGE_FILE_NAME.
CPACK_DMG_FORMAT - The disk image format. Common values are UDRO
(UDIF read-only), UDZO (UDIF zlib-compressed) or UDBZ (UDIF
bzip2-compressed). Refer to hdiutil(1) for more information on
other available formats.
CPACK_DMG_DS_STORE - Path to a custom .DS_Store file which e.g.
can be used to specify the Finder window position/geometry and
layout (such as hidden toolbars, placement of the icons etc.).
This file has to be generated by the Finder (either manually or
through OSA-script) using a normal folder from which the .DS_Store
file can then be extracted.
CPACK_DMG_BACKGROUND_IMAGE - Path to an image file which is to be
used as the background for the Finder Window when the disk image
is opened. By default no background image is set. The background
image is applied after applying the custom .DS_Store file.
CPACK_COMMAND_HDIUTIL - Path to the hdiutil(1) command used to
operate on disk image files on Mac OS X. This variable can be used
to override the automatically detected command (or specify its
location if the auto-detection fails to find it.)
CPACK_COMMAND_SETFILE - Path to the SetFile(1) command used to set
extended attributes on files and directories on Mac OS X. This
variable can be used to override the automatically detected
command (or specify its location if the auto-detection fails to
find it.)
CPACK_COMMAND_REZ - Path to the Rez(1) command used to compile
resources on Mac OS X. This variable can be used to override the
automatically detected command (or specify its location if the
auto-detection fails to find it.)
The following variable is specific to installers build on Mac OS X using PackageMaker:
CPACK_OSX_PACKAGE_VERSION - The version of Mac OS X that the
resulting PackageMaker archive should be compatible
with. Different versions of Mac OS X support different
features. For example, CPack can only build component-based
installers for Mac OS X 10.4 or newer, and can only build
installers that download component son-the-fly for Mac OS X 10.5
or newer. If left blank, this value will be set to the minimum
version of Mac OS X that supports the requested features. Set this
variable to some value (e.g., 10.4) only if you want to guarantee
that your installer will work on that version of Mac OS X, and
don't mind missing extra features available in the installer
shipping with later versions of Mac OS X.
The following variables are for advanced uses of CPack:
CPACK_CMAKE_GENERATOR - What CMake generator should be used if the
project is CMake project. Defaults to the value of CMAKE_GENERATOR;
few users will want to change this setting.
CPACK_INSTALL_CMAKE_PROJECTS - List of four values that specify
what project to install. The four values are: Build directory,
Project Name, Project Component, Directory. If omitted, CPack will
build an installer that installers everything.
CPACK_SYSTEM_NAME - System name, defaults to the value of
${CMAKE_SYSTEM_NAME}.
CPACK_PACKAGE_VERSION - Package full version, used internally. By
default, this is built from CPACK_PACKAGE_VERSION_MAJOR,
CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
CPACK_TOPLEVEL_TAG - Directory for the installed files.
CPACK_INSTALL_COMMANDS - Extra commands to install components.
CPACK_INSTALLED_DIRECTORIES - Extra directories to install.