# CPack

Build binary and source package installers.

## Variables common to all CPack generators

The 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 runs
- it includes CPackConfig.cmake
- it iterates over the generators listed in that file’s CPACK_GENERATOR list variable (unless told to use just a specific one via -G on the command line...)
- foreach generator, it then
  - 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_DIRECTORY`

  The directory in which CPack is doing its packaging. If it is not set then this will default (internally) to the build dir. This variable may be defined in CPack config file or from the cpack command line option “-B”. If set the command line option override the value found in the config file.

`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). Default value is:

      ${PROJECT_DESCRIPTION}

  if DESCRIPTION has given to the project() call or CMake generated string with PROJECT_NAME otherwise.

`CPACK_PACKAGE_FILE_NAME`

  The name of the package file to generate, not including the extension. For example, cmake-2.6.1-Linux-i686. The default value is:

      ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}.

`CPACK_PACKAGE_INSTALL_DIRECTORY`

  Installation directory on the target system. This may be used by some CPack generators like NSIS to create an installation directory e.g., “CMake 2.5” below the installation prefix. All installed element will be put inside this directory.

`CPACK_PACKAGE_ICON`

  A branding image that will be displayed inside the installer (used by GUI installers).

`CPACK_PACKAGE_CHECKSUM`

  An algorithm that will be used to generate additional file with checksum of the package. Output file name will be:

      ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}

  Supported algorithms are those listed by the string(<HASH>) command.

`CPACK_PROJECT_CONFIG_FILE`

  CPack-time project CPack configuration file. This file included at cpack time, once per generator after CPack has set CPACK_GENERATOR to the actual generator being used. It allows per-generator setting of CPACK_* variables at cpack time.

`CPACK_RESOURCE_FILE_LICENSE`

  License to be embedded in the installer. It will typically be displayed to the user by the produced installer (often with an explicit “Accept” button, for graphical installers) prior to installation. This license file is NOT added to installed file but is used by some CPack generators like NSIS. If you want to install a license file (may be the same as this one) along with your project you must add an appropriate CMake INSTALL command in your CMakeLists.txt.

`CPACK_RESOURCE_FILE_README`

  ReadMe file to be embedded in the installer. It typically describes in some detail the purpose of the project during the installation. Not all CPack generators uses this file.

`CPACK_RESOURCE_FILE_WELCOME`

  Welcome file to be embedded in the installer. It 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. When set the component specification is ignored and all installed items are put in a single “MONOLITHIC” package. Some CPack generators do monolithic packaging by default and may be asked to do component packaging by setting CPACK_<GENNAME>_COMPONENT_INSTALL to 1/TRUE.

`CPACK_GENERATOR`

  List of CPack generators to use. If not specified, CPack will create a set of options CPACK_BINARY_<GENNAME> (e.g., CPACK_BINARY_NSIS) allowing the user to enable/disable individual generators. This variable may be used on the command line as well as in:

      cpack -D CPACK_GENERATOR="ZIP;TGZ" /path/to/build/tree

`CPACK_OUTPUT_CONFIG_FILE`

  The name of the CPack binary configuration file. This file is the CPack configuration generated by the CPack module for binary installers. Defaults to CPackConfig.cmake.

`CPACK_PACKAGE_EXECUTABLES`

  Lists each of the executables and associated text label to be used to create Start Menu shortcuts. For example, setting this to the list ccmake;CMake will create a shortcut named “CMake” that will execute the installed executable ccmake. Not all CPack generators use it (at least NSIS, WIX and OSXX11 do).

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

`CPACK_VERBATIM_VARIABLES`

  If set to TRUE, values of variables prefixed with CPACK will be escaped before being written to the configuration files, so that the cpack program receives them exactly as they were specified. If not, characters like quotes and backslashes can cause parsing errors or alter the value received by the cpack program. Defaults to FALSE for backwards compatibility.

  - Mandatory : NO
  - Default : FALSE

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. For example 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 source configuration file. This file is the CPack configuration generated by the CPack module for source installers. 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 regular expression patterns (that must be properly escaped), e.g., /CVS/;/\.svn/;\.swp$;\.#;/#;.*~;cscope.*

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

`CPACK_PACKAGE_INSTALL_REGISTRY_KEY`

  Registry key used when installing this project. This is only used by installer for Windows. The default value is based on the installation directory.

`CPACK_CREATE_DESKTOP_LINKS`

  List of desktop links to create. Each desktop link requires a corresponding start menu shortcut as created by `CPACK_PACKAGE_EXECUTABLES`.

`CPACK_BINARY_<GENNAME>`

  CPack generated options for binary generators. The CPack.cmake module generates (when CPACK_GENERATOR is not set) a set of CMake options (see CMake option command) which may then be used to select the CPack generator(s) to be used when launching the package target.

  Provide options to choose generators we might check here if the required tools for the generates exist and set the defaults according to the results