CMake:Packaging With CPack: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
No edit summary
(Remove leading space rectangles from preformatted blocks)
(22 intermediate revisions by 8 users not shown)
Line 1: Line 1:
<!-- CPack documentation and manual -->
=Introduction=
=Introduction=


''CPack'' is a software packaging tool distributed with [http://www.cmake.org
''CPack'' is a powerful, easy to use, cross-platform software packaging tool distributed with [http://www.cmake.org CMake] since version 2.4.2. It uses the [[CMake:CPackPackageGenerators|generators]] concept from CMake, to abstract package generation on specific platforms, and it can be used with or without CMake.
CMake]. It uses the generators concept from CMake, to abstract package
 
generation on specific platforms. It can be used with or without CMake, but it
Using either a simple configuration file or the CMake module, a complex project can be packaged into an installer.
may depend on some software being installed on the system. For example, on Mac
 
OSX, it relies on Xcode to be installed and on Windows it requires NSIS.
=Using CPack without CMake=
 
CPack can be used directly by specifying a CPackConfig.cmake file, which uses CMake syntax and defines several variables. Here is an example CPackConfig.cmake file for a Linux system:
 
<pre><nowiki>SET(CPACK_CMAKE_GENERATOR "Unix Makefiles")
SET(CPACK_GENERATOR "STGZ;TGZ;TZ")
SET(CPACK_INSTALL_CMAKE_PROJECTS "/home/andy/vtk/CMake-bin;CMake;ALL;/")
SET(CPACK_NSIS_DISPLAY_NAME "CMake 2.5")
SET(CPACK_OUTPUT_CONFIG_FILE "/home/andy/vtk/CMake-bin/CPackConfig.cmake")
SET(CPACK_PACKAGE_DESCRIPTION_FILE "/home/andy/vtk/CMake/Copyright.txt")
SET(CPACK_PACKAGE_DESCRIPTION_SUMMARY "CMake is a build tool")
SET(CPACK_PACKAGE_EXECUTABLES "ccmake;CMake")
SET(CPACK_PACKAGE_FILE_NAME "cmake-2.5.0-Linux-i686")
SET(CPACK_PACKAGE_INSTALL_DIRECTORY "CMake 2.5")
SET(CPACK_PACKAGE_INSTALL_REGISTRY_KEY "CMake 2.5.0")
SET(CPACK_PACKAGE_NAME "CMake")
SET(CPACK_PACKAGE_VENDOR "Kitware")
SET(CPACK_PACKAGE_VERSION "2.5.0")
SET(CPACK_PACKAGE_VERSION_MAJOR "2")
SET(CPACK_PACKAGE_VERSION_MINOR "5")
SET(CPACK_PACKAGE_VERSION_PATCH "0")
SET(CPACK_RESOURCE_FILE_LICENSE "/home/andy/vtk/CMake/Copyright.txt")
SET(CPACK_RESOURCE_FILE_README "/home/andy/vtk/CMake/Templates/CPack.GenericDescription.txt")
SET(CPACK_RESOURCE_FILE_WELCOME "/home/andy/vtk/CMake/Templates/CPack.GenericWelcome.txt")
SET(CPACK_SOURCE_GENERATOR "TGZ;TZ")
SET(CPACK_SOURCE_OUTPUT_CONFIG_FILE "/home/andy/vtk/CMake-bin/CPackSourceConfig.cmake")
SET(CPACK_SOURCE_PACKAGE_FILE_NAME "cmake-2.5.0")
SET(CPACK_SOURCE_STRIP_FILES "")
SET(CPACK_STRIP_FILES "bin/ccmake;bin/cmake;bin/cpack;bin/ctest")
SET(CPACK_SYSTEM_NAME "Linux-i686")
SET(CPACK_TOPLEVEL_TAG "Linux-i686")</nowiki></pre>
 
These variables can also be overwritten on the command line using the option "-D":
 
<pre>
cpack -D CPACK_PACKAGE_VENDOR=Me -D CPACK_SYSTEM_NAME=super-duper-linux ...
</pre>
 


=Using CPack with CMake=
=Using CPack with CMake=


CMake comes with CPack module, which will generate appropriate CPack input
CMake comes with a CPack module, which will automatically generate an appropriate CPack configuration file. To use the module, simply invoke the following command (BTW, failure to do so will result in an annoying "CPack Error: CPack project name not specified" message...):
file. To use this module, some CMake variables need to be set. These variables
will be copied to the CPack input file.


A simple CMake section to use CPack from CMake is this:
<pre><nowiki>INCLUDE(CPack)</nowiki></pre>


<pre><nowiki>INCLUDE(CPack)</nowiki></pre>
This generates a new target called ''"package"'' in your build system. When this target is built, CPack will be invoked to generate all of the packages.  Internally, CPack will use [[CMake:Install_Commands | CMake's install mechanism]] to automatically populate the package.


This will generate new target in Makefile (or Visual Studio, or Xcode) called ''"package"''. By running this target, CPack will be invoked, which will generate all the packages. Example output of the ''"package"'' target of Makefile is:
An example output of the ''"package"'' target (from a Linux Makefile) is:


<pre><nowiki>Run CPack packaging tool...
<pre><nowiki>Run CPack packaging tool...
Line 45: Line 81:
CPack: Package /home/andy/CMake-bin/cmake-2.5.0-Linux-i686.tar.Z generated.</nowiki></pre>
CPack: Package /home/andy/CMake-bin/cmake-2.5.0-Linux-i686.tar.Z generated.</nowiki></pre>


When adding line:
INCLUDE(CPack)
CMake module ''CPack.cmake'' will generate CPack configuration file called CPackConfig.cmake.


A more typical CMake list section for CPack configuration would be:
==Using CMake variables to configure CPack==
 
To configure CPack, it is possible to define [[CMake:CPackConfiguration| CPack variables]] inside a CMake file.  These variables will be copied across to the generated CPackConfig.cmake file before CPack is invoked.
 
This is an example CMake list section for CPack configuration:


<pre><nowiki>
<pre><nowiki>
Line 79: Line 116:
INCLUDE(CPack)</nowiki></pre>
INCLUDE(CPack)</nowiki></pre>


==CPack and INSTALL commands==
== CPack Generators ==
 
There are several [[CMake:CPackPackageGenerators|generators]] usable with CPack.
CPack will internally use CMake's install mechanism to populate the package. The [[CMake:Install_Commands|Install Commands]] page describes how to use the CMake's INSTALL command.
 
=Using CPack without CMake=
 
CPack can be used directly by specifying CPackConfig.cmake file. This file uses CMake syntax and has to contain several variables. Here is example CPackConfig.cmake files from CMake build directory on Linux system:
 
<pre><nowiki>SET(CPACK_CMAKE_GENERATOR "Unix Makefiles")
SET(CPACK_GENERATOR "STGZ;TGZ;TZ")
SET(CPACK_INSTALL_CMAKE_PROJECTS "/home/andy/vtk/CMake-bin;CMake;ALL;/")
SET(CPACK_NSIS_DISPLAY_NAME "CMake 2.5")
SET(CPACK_OUTPUT_CONFIG_FILE "/home/andy/vtk/CMake-bin/CPackConfig.cmake")
SET(CPACK_PACKAGE_DESCRIPTION_FILE "/home/andy/vtk/CMake/Copyright.txt")
SET(CPACK_PACKAGE_DESCRIPTION_SUMMARY "CMake is a build tool")
SET(CPACK_PACKAGE_EXECUTABLES "ccmake;CMake")
SET(CPACK_PACKAGE_FILE_NAME "cmake-2.5.0-Linux-i686")
SET(CPACK_PACKAGE_INSTALL_DIRECTORY "CMake 2.5")
SET(CPACK_PACKAGE_INSTALL_REGISTRY_KEY "CMake 2.5.0")
SET(CPACK_PACKAGE_NAME "CMake")
SET(CPACK_PACKAGE_VENDOR "Kitware")
SET(CPACK_PACKAGE_VERSION "2.5.0")
SET(CPACK_PACKAGE_VERSION_MAJOR "2")
SET(CPACK_PACKAGE_VERSION_MINOR "5")
SET(CPACK_PACKAGE_VERSION_PATCH "0")
SET(CPACK_RESOURCE_FILE_LICENSE "/home/andy/vtk/CMake/Copyright.txt")
SET(CPACK_RESOURCE_FILE_README "/home/andy/vtk/CMake/Templates/CPack.GenericDescription.txt")
SET(CPACK_RESOURCE_FILE_WELCOME "/home/andy/vtk/CMake/Templates/CPack.GenericWelcome.txt")
SET(CPACK_SOURCE_GENERATOR "TGZ;TZ")
SET(CPACK_SOURCE_OUTPUT_CONFIG_FILE "/home/andy/vtk/CMake-bin/CPackSourceConfig.cmake")
SET(CPACK_SOURCE_PACKAGE_FILE_NAME "cmake-2.5.0")
SET(CPACK_SOURCE_STRIP_FILES "")
SET(CPACK_STRIP_FILES "bin/ccmake;bin/cmake;bin/cpack;bin/ctest")
SET(CPACK_SYSTEM_NAME "Linux-i686")
SET(CPACK_TOPLEVEL_TAG "Linux-i686")</nowiki></pre>
 
These variables can be overwritten on the command line using the option "-D":
 
cpack -D CPACK_PACKAGE_VENDOR=Me -D CPACK_SYSTEM_NAME=super-duper-linux ...
 
=CPack Settings=
{|
|- bgcolor="#abcdef"
! Variable Name || ____________Description____________ || Example
|-
| CPACK_CMAKE_GENERATOR || What CMake generator should be used if the project is CMake project || Unix Makefiles
|-
| CPACK_GENERATOR || CPack generator to be used || STGZ;TGZ;TZ
|-
| CPACK_INSTALL_CMAKE_PROJECTS || List of four values: Build directory, Project Name, Project Component, Directory in the package || /home/andy/vtk/CMake-bin;CMake;ALL;/
|-
| CPACK_PACKAGE_DESCRIPTION_FILE || File used as a description of a project || /path/to/project/ReadMe.txt
|-
| CPACK_PACKAGE_DESCRIPTION_SUMMARY || Description summary of a project || CMake is a build tool
|-
| CPACK_PACKAGE_EXECUTABLES || Pair of project executable and label || ccmake;CMake
|-
| CPACK_PACKAGE_FILE_NAME || Package file name without extension. Also a directory of installer || cmake-2.5.0-Linux-i686
|-
| CPACK_PACKAGE_INSTALL_DIRECTORY || Installation directory on the target system || CMake 2.5")
|-
| CPACK_PACKAGE_INSTALL_REGISTRY_KEY || Registry key used when installing this project || CMake 2.5.0
|-
| CPACK_PACKAGE_NAME || Package name || CMake
|-
| CPACK_PACKAGE_VENDOR || Package vendor name || Kitware
|-
| CPACK_PACKAGE_VERSION || Package full version || 2.5.0
|-
| CPACK_PACKAGE_VERSION_MAJOR || Package Major Version || 2
|-
| CPACK_PACKAGE_VERSION_MINOR || Package Minor Version || 5
|-
| CPACK_PACKAGE_VERSION_PATCH || Package Patch Version || 0
|-
| CPACK_RESOURCE_FILE_LICENSE || License file for the project || /home/andy/vtk/CMake/Copyright.txt
|-
| CPACK_RESOURCE_FILE_README || ReadMe file for the project || /home/andy/vtk/CMake/Templates/CPack.GenericDescription.txt
|-
| CPACK_RESOURCE_FILE_WELCOME || Welcome file for the project || /home/andy/vtk/CMake/Templates/CPack.GenericWelcome.txt
|-
| CPACK_SOURCE_GENERATOR || List of generators used for the source package || TGZ;TZ
|-
| CPACK_SOURCE_IGNORE_FILES || Pattern of files in the source tree that won't be packaged ||  /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
|-
| CPACK_SOURCE_PACKAGE_FILE_NAME || Name of the source package || cmake-2.5.0
|-
| 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_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). || bin/ccmake;bin/cmake;bin/cpack;bin/ctest
|-
| CPACK_SYSTEM_NAME || System name || Linux-i686
|-
| CPACK_TOPLEVEL_TAG || Directory for the installed || Linux-i686
|}
 
=CPack Package Generators=
 
Currently CPack features the following package generators:
 
; TGZ : Tar GZip compressed packages.
; STGZ : Self extracting Tar GZip compressed packages (needs /bin/sh, tar and gunzip for extracting).
; NSIS : Nullsoft Installer. Requires NSIS for creating the package.
; ZIP : ZIP compressed packages. Requires zip, WinZip or 7Zip for creating the package.
; TBZ2 : Tar BZip2 compressed packages. Requires bzip2 for creating the package.
; TZ : Tar UNIX compress compressed packages.
; PackageMaker (OSX only): Mac OSX Package Maker packages. Requires Package Maker for creating the package.
; OSXX11 (OSX only): Mac OSX X11 Bundle. Requires hdiutil for creating the package.
; CygwinBinary (Cygwin only): Tar Bzip2 compressed Cygwin package.  Requires bzip2 for creating the package.
; CygwinSource (Cygwin only): Tar Bzip2 compressed Cygwin source package.  Requires bzip2 for creating the package.
 
 
 


=Conclusion=
=Example=
Here is an [[CMake/CPackExample|example]].


CPack is a powerful, easy to use, cross-platform packaging tool. Using a simple
=Debugging=
configuration file or using a CMake module, the author of a project can package
A very detailed log of CPack execution steps can be obtained via cpack --debug --verbose (which, as a side note, are features that are awfully hidden at least in older versions of CPack).
a complex project into a simple installer.


{{CMake/Template/Footer}}
{{CMake/Template/Footer}}

Revision as of 21:04, 20 April 2018

Introduction

CPack is a powerful, easy to use, cross-platform software packaging tool distributed with CMake since version 2.4.2. It uses the generators concept from CMake, to abstract package generation on specific platforms, and it can be used with or without CMake.

Using either a simple configuration file or the CMake module, a complex project can be packaged into an installer.

Using CPack without CMake

CPack can be used directly by specifying a CPackConfig.cmake file, which uses CMake syntax and defines several variables. Here is an example CPackConfig.cmake file for a Linux system:

SET(CPACK_CMAKE_GENERATOR "Unix Makefiles")
SET(CPACK_GENERATOR "STGZ;TGZ;TZ")
SET(CPACK_INSTALL_CMAKE_PROJECTS "/home/andy/vtk/CMake-bin;CMake;ALL;/")
SET(CPACK_NSIS_DISPLAY_NAME "CMake 2.5")
SET(CPACK_OUTPUT_CONFIG_FILE "/home/andy/vtk/CMake-bin/CPackConfig.cmake")
SET(CPACK_PACKAGE_DESCRIPTION_FILE "/home/andy/vtk/CMake/Copyright.txt")
SET(CPACK_PACKAGE_DESCRIPTION_SUMMARY "CMake is a build tool")
SET(CPACK_PACKAGE_EXECUTABLES "ccmake;CMake")
SET(CPACK_PACKAGE_FILE_NAME "cmake-2.5.0-Linux-i686")
SET(CPACK_PACKAGE_INSTALL_DIRECTORY "CMake 2.5")
SET(CPACK_PACKAGE_INSTALL_REGISTRY_KEY "CMake 2.5.0")
SET(CPACK_PACKAGE_NAME "CMake")
SET(CPACK_PACKAGE_VENDOR "Kitware")
SET(CPACK_PACKAGE_VERSION "2.5.0")
SET(CPACK_PACKAGE_VERSION_MAJOR "2")
SET(CPACK_PACKAGE_VERSION_MINOR "5")
SET(CPACK_PACKAGE_VERSION_PATCH "0")
SET(CPACK_RESOURCE_FILE_LICENSE "/home/andy/vtk/CMake/Copyright.txt")
SET(CPACK_RESOURCE_FILE_README "/home/andy/vtk/CMake/Templates/CPack.GenericDescription.txt")
SET(CPACK_RESOURCE_FILE_WELCOME "/home/andy/vtk/CMake/Templates/CPack.GenericWelcome.txt")
SET(CPACK_SOURCE_GENERATOR "TGZ;TZ")
SET(CPACK_SOURCE_OUTPUT_CONFIG_FILE "/home/andy/vtk/CMake-bin/CPackSourceConfig.cmake")
SET(CPACK_SOURCE_PACKAGE_FILE_NAME "cmake-2.5.0")
SET(CPACK_SOURCE_STRIP_FILES "")
SET(CPACK_STRIP_FILES "bin/ccmake;bin/cmake;bin/cpack;bin/ctest")
SET(CPACK_SYSTEM_NAME "Linux-i686")
SET(CPACK_TOPLEVEL_TAG "Linux-i686")

These variables can also be overwritten on the command line using the option "-D":

cpack -D CPACK_PACKAGE_VENDOR=Me -D CPACK_SYSTEM_NAME=super-duper-linux ...


Using CPack with CMake

CMake comes with a CPack module, which will automatically generate an appropriate CPack configuration file. To use the module, simply invoke the following command (BTW, failure to do so will result in an annoying "CPack Error: CPack project name not specified" message...):

INCLUDE(CPack)

This generates a new target called "package" in your build system. When this target is built, CPack will be invoked to generate all of the packages. Internally, CPack will use CMake's install mechanism to automatically populate the package.

An example output of the "package" target (from a Linux Makefile) is:

Run CPack packaging tool...
CPack: Create package using STGZ
CPack: Install projects
CPack: - Run preinstall target for: CMake
CPack: - Install project: CMake
CPack: - Strip files
CPack: Compress package
CPack: Finalize package
CPack: Package /home/andy/CMake-bin/cmake-2.5.0-Linux-i686.sh generated.
CPack: Create package using TGZ
CPack: Install projects
CPack: - Run preinstall target for: CMake
CPack: - Install project: CMake
CPack: - Strip files
CPack: Compress package
CPack: Finalize package
CPack: Package /home/andy/CMake-bin/cmake-2.5.0-Linux-i686.tar.gz generated.
CPack: Create package using TZ
CPack: Install projects
CPack: - Run preinstall target for: CMake
CPack: - Install project: CMake
CPack: - Strip files
CPack: Compress package
CPack: Finalize package
CPack: Package /home/andy/CMake-bin/cmake-2.5.0-Linux-i686.tar.Z generated.


Using CMake variables to configure CPack

To configure CPack, it is possible to define CPack variables inside a CMake file. These variables will be copied across to the generated CPackConfig.cmake file before CPack is invoked.

This is an example CMake list section for CPack configuration:

INCLUDE(InstallRequiredSystemLibraries)

SET(CPACK_PACKAGE_DESCRIPTION_SUMMARY "My funky project")
SET(CPACK_PACKAGE_VENDOR "Me, myself, and I")
SET(CPACK_PACKAGE_DESCRIPTION_FILE "${CMAKE_CURRENT_SOURCE_DIR}/ReadMe.txt")
SET(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/Copyright.txt")
SET(CPACK_PACKAGE_VERSION_MAJOR "1")
SET(CPACK_PACKAGE_VERSION_MINOR "3")
SET(CPACK_PACKAGE_VERSION_PATCH "2")
SET(CPACK_PACKAGE_INSTALL_DIRECTORY "CMake ${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}")
IF(WIN32 AND NOT UNIX)
  # There is a bug in NSI that does not handle full unix paths properly. Make
  # sure there is at least one set of four (4) backlasshes.
  SET(CPACK_PACKAGE_ICON "${CMake_SOURCE_DIR}/Utilities/Release\\\\InstallIcon.bmp")
  SET(CPACK_NSIS_INSTALLED_ICON_NAME "bin\\\\MyExecutable.exe")
  SET(CPACK_NSIS_DISPLAY_NAME "${CPACK_PACKAGE_INSTALL_DIRECTORY} My Famous Project")
  SET(CPACK_NSIS_HELP_LINK "http:\\\\\\\\www.my-project-home-page.org")
  SET(CPACK_NSIS_URL_INFO_ABOUT "http:\\\\\\\\www.my-personal-home-page.com")
  SET(CPACK_NSIS_CONTACT "me@my-personal-home-page.com")
  SET(CPACK_NSIS_MODIFY_PATH ON)
ELSE(WIN32 AND NOT UNIX)
  SET(CPACK_STRIP_FILES "bin/MyExecutable")
  SET(CPACK_SOURCE_STRIP_FILES "")
ENDIF(WIN32 AND NOT UNIX)
SET(CPACK_PACKAGE_EXECUTABLES "MyExecutable" "My Executable")
INCLUDE(CPack)

CPack Generators

There are several generators usable with CPack.

Example

Here is an example.

Debugging

A very detailed log of CPack execution steps can be obtained via cpack --debug --verbose (which, as a side note, are features that are awfully hidden at least in older versions of CPack).



CMake: [Welcome | Site Map]