https://public.kitware.com/Wiki/api.php?action=feedcontributions&user=Erk&feedformat=atomKitwarePublic - User contributions [en]2024-03-28T14:08:43ZUser contributionsMediaWiki 1.38.6https://public.kitware.com/Wiki/index.php?title=File:Toolchain-cross-mingw32-linux.cmake&diff=48283File:Toolchain-cross-mingw32-linux.cmake2012-07-04T20:13:44Z<p>Erk: An example of mingw32 CMake toolchain file for Linux</p>
<hr />
<div>An example of mingw32 CMake toolchain file for Linux</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CmakeMingw&diff=48282CmakeMingw2012-07-04T20:12:45Z<p>Erk: /* Write a CMake toolchain file */</p>
<hr />
<div>= How to use MinGW to cross compile software for Windows =<br />
<br />
MinGW is the GNU toolchain for Windows, it also exists as cross compiler under<br />
Linux (and probably other UNIXes). You can use it to build Windows software on Linux.<br />
<br />
== Install the mingw cross compiling toolchain ==<br />
<br />
There are several ways to get the mingw cross compiler on your machine.<br />
With Ubuntu/Debian you can simply install it using apt: "apt-get install mingw32". This will <br />
install the toolchain as i586-mingw32msvc-gcc to /usr/bin/ .<br />
You can of course also build this toolchain from sources yourself, but this is more work.<br />
<br />
== Write a CMake toolchain file ==<br />
<br />
For CMake to be able to crosscompile software, it requires you to write a toolchain file, which tells CMake<br />
some information about the toolchain.<br />
With the examples used above it will look like:<br />
<pre><br />
# the name of the target operating system<br />
SET(CMAKE_SYSTEM_NAME Windows)<br />
<br />
# which compilers to use for C and C++<br />
SET(CMAKE_C_COMPILER i586-mingw32msvc-gcc)<br />
SET(CMAKE_CXX_COMPILER i586-mingw32msvc-g++)<br />
SET(CMAKE_RC_COMPILER i586-mingw32msvc-windres)<br />
<br />
# here is the target environment located<br />
SET(CMAKE_FIND_ROOT_PATH /usr/i586-mingw32msvc /home/alex/mingw-install )<br />
<br />
# adjust the default behaviour of the FIND_XXX() commands:<br />
# search headers and libraries in the target environment, search <br />
# programs in the host environment<br />
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)<br />
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)<br />
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)<br />
</pre><br />
<br />
Save this file as Toolchain-mingw32.cmake to some location where you will put<br />
all your toolchain files, e.g. $HOME.<br />
As you can see CMAKE_FIND_ROOT_PATH is set to /usr/i586-mingw32msvc, which contains the headers and libraries<br />
installed with the toolchain, and /home/alex/mingw-install/. This second directory is intended to hold <br />
other libraries you will compile using mingw32, they should be installed under this install prefix. This way<br />
the FIND_XXX() commands in CMake will find both the headers and libraries coming with the toolchain as well<br />
as additional libraries you have built for this platform.<br />
<br />
You can try this toolchain file as well [[File:Toolchain-cross-mingw32-linux.cmake]] which is trying to be <br />
as simple as possible by only setting COMPILER_PREFIX var.<br />
<br />
== Build the software for Windows ==<br />
<br />
Let's say you have the classical hello world software with a CMake based buildsystem and want to build this for Windows<br />
using mingw32.<br />
main.c:<br />
<pre><br />
#include <stdio.h><br />
<br />
int main()<br />
{<br />
printf("Hello world\n");<br />
return 0;<br />
}<br />
</pre><br />
<br />
CMakeLists.txt:<br />
<pre><br />
ADD_EXECUTABLE(hello main.c)<br />
</pre><br />
<br />
Then run CMake on it to generate the buildfiles, the important point is that you tell it to use the toolchain file you just wrote:<br />
<pre><br />
~/src/helloworld/ $ mkdir build<br />
~/src/helloworld/ $ cd build<br />
~/src/helloworld/build/ $ cmake -DCMAKE_TOOLCHAIN_FILE=~/Toolchain-mingw32.cmake -DCMAKE_INSTALL_PREFIX=/home/alex/mingw-install .. <br />
-- Configuring done<br />
-- Generating done<br />
-- Build files have been written to: /home/alex/src/helloworld/build<br />
~/src/helloworld/build/ $ make<br />
Scanning dependencies of target hello<br />
[100%] Building C object CMakeFiles/hello.dir/main.o<br />
Linking C executable hello.exe<br />
[100%] Built target hello<br />
</pre><br />
<br />
So that's all. It actually doesn't matter whether it's just a "hello world" or some complex piece of software,<br />
the only difference is the usage of the toolchain file. If the software has all required configure checks, it should just<br />
build also with this toolchain.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CmakeMingw&diff=48281CmakeMingw2012-07-04T20:10:32Z<p>Erk: /* Write a CMake toolchain file */</p>
<hr />
<div>= How to use MinGW to cross compile software for Windows =<br />
<br />
MinGW is the GNU toolchain for Windows, it also exists as cross compiler under<br />
Linux (and probably other UNIXes). You can use it to build Windows software on Linux.<br />
<br />
== Install the mingw cross compiling toolchain ==<br />
<br />
There are several ways to get the mingw cross compiler on your machine.<br />
With Ubuntu/Debian you can simply install it using apt: "apt-get install mingw32". This will <br />
install the toolchain as i586-mingw32msvc-gcc to /usr/bin/ .<br />
You can of course also build this toolchain from sources yourself, but this is more work.<br />
<br />
== Write a CMake toolchain file ==<br />
<br />
For CMake to be able to crosscompile software, it requires you to write a toolchain file, which tells CMake<br />
some information about the toolchain.<br />
With the examples used above it will look like:<br />
<pre><br />
# the name of the target operating system<br />
SET(CMAKE_SYSTEM_NAME Windows)<br />
<br />
# which compilers to use for C and C++<br />
SET(CMAKE_C_COMPILER i586-mingw32msvc-gcc)<br />
SET(CMAKE_CXX_COMPILER i586-mingw32msvc-g++)<br />
SET(CMAKE_RC_COMPILER i586-mingw32msvc-windres)<br />
<br />
# here is the target environment located<br />
SET(CMAKE_FIND_ROOT_PATH /usr/i586-mingw32msvc /home/alex/mingw-install )<br />
<br />
# adjust the default behaviour of the FIND_XXX() commands:<br />
# search headers and libraries in the target environment, search <br />
# programs in the host environment<br />
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)<br />
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)<br />
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)<br />
</pre><br />
<br />
Save this file as Toolchain-mingw32.cmake to some location where you will put<br />
all your toolchain files, e.g. $HOME.<br />
As you can see CMAKE_FIND_ROOT_PATH is set to /usr/i586-mingw32msvc, which contains the headers and libraries<br />
installed with the toolchain, and /home/alex/mingw-install/. This second directory is intended to hold <br />
other libraries you will compile using mingw32, they should be installed under this install prefix. This way<br />
the FIND_XXX() commands in CMake will find both the headers and libraries coming with the toolchain as well<br />
as additional libraries you have built for this platform.<br />
<br />
[[File:Example.jpg]]<br />
<br />
== Build the software for Windows ==<br />
<br />
Let's say you have the classical hello world software with a CMake based buildsystem and want to build this for Windows<br />
using mingw32.<br />
main.c:<br />
<pre><br />
#include <stdio.h><br />
<br />
int main()<br />
{<br />
printf("Hello world\n");<br />
return 0;<br />
}<br />
</pre><br />
<br />
CMakeLists.txt:<br />
<pre><br />
ADD_EXECUTABLE(hello main.c)<br />
</pre><br />
<br />
Then run CMake on it to generate the buildfiles, the important point is that you tell it to use the toolchain file you just wrote:<br />
<pre><br />
~/src/helloworld/ $ mkdir build<br />
~/src/helloworld/ $ cd build<br />
~/src/helloworld/build/ $ cmake -DCMAKE_TOOLCHAIN_FILE=~/Toolchain-mingw32.cmake -DCMAKE_INSTALL_PREFIX=/home/alex/mingw-install .. <br />
-- Configuring done<br />
-- Generating done<br />
-- Build files have been written to: /home/alex/src/helloworld/build<br />
~/src/helloworld/build/ $ make<br />
Scanning dependencies of target hello<br />
[100%] Building C object CMakeFiles/hello.dir/main.o<br />
Linking C executable hello.exe<br />
[100%] Built target hello<br />
</pre><br />
<br />
So that's all. It actually doesn't matter whether it's just a "hello world" or some complex piece of software,<br />
the only difference is the usage of the toolchain file. If the software has all required configure checks, it should just<br />
build also with this toolchain.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake_builtin_documentation_handling&diff=48009CMake builtin documentation handling2012-06-18T07:18:21Z<p>Erk: /* Documentation markup in CMake script files */</p>
<hr />
<div>== CMake,CPack,CTest builtin documentation ==<br />
<br />
All CMake tools command line do have some builtin documentation support. The tools (cmake, cpack, ctest) supports a variable subset of:<br />
<br />
ctool --help-command[-list] <br />
ctool --help-module[-list]<br />
ctool --help-variable[-list]<br />
ctool --help-policy[-list]<br />
ctool --help-property[-list]<br />
ctool --help-full<br />
ctool --help-html<br />
<br />
for the detail see:<br />
<br />
cmake --help<br />
cpack --help<br />
ctest --help<br />
<br />
This builtin documentation comes from 2 different places:<br />
# static variables in C++ sources<br />
# text surrounded by markup in CMake script files<br />
<br />
== Documentation in C++ sources ==<br />
<br />
This is the primary source of builtin documentation.<br />
<br />
== Documentation markup in CMake script files ==<br />
<br />
This source is available since CMake 2.8.8 and is currently only used by CPack.<br />
The idea behind CMake script markup is to be able to document CMake scripts. Documenting a script means being able to put in structured documentation using some comments.<br />
<br />
Before 2.8.8, this was available through:<br />
cmake --help-module<br />
which was basically extracting the first block of comments stripping out the comment character ('#').<br />
<br />
From 2.8.8 and up we may be able to do more by using a basic markup language which may be used to document:<br />
* variable<br />
* command<br />
* section/module<br />
<br />
The markup may then be automatically extracted by ctool (cmake, cpack, ctest) in order to feed their<br />
--help-variable[s|-list]<br />
--help-command[s|-list]<br />
command lines options.<br />
<br />
A comment in a CMake script is a line which begin by a '#' character. A markup line is a special line which begin with a '##' (double '#') followed by a markup word. The list of currently supported markup words is:<br />
* section<br />
* module<br />
* variable<br />
* macro<br />
* end<br />
A documentation block must always begins with a non-end markup line and finishes with a ##end markup line.<br />
<br />
=== Variable ===<br />
<br />
=== Command ===<br />
<br />
=== Section ===</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake_builtin_documentation_handling&diff=48008CMake builtin documentation handling2012-06-18T07:12:47Z<p>Erk: /* Documentation markup in CMake script files */</p>
<hr />
<div>== CMake,CPack,CTest builtin documentation ==<br />
<br />
All CMake tools command line do have some builtin documentation support. The tools (cmake, cpack, ctest) supports a variable subset of:<br />
<br />
ctool --help-command[-list] <br />
ctool --help-module[-list]<br />
ctool --help-variable[-list]<br />
ctool --help-policy[-list]<br />
ctool --help-property[-list]<br />
ctool --help-full<br />
ctool --help-html<br />
<br />
for the detail see:<br />
<br />
cmake --help<br />
cpack --help<br />
ctest --help<br />
<br />
This builtin documentation comes from 2 different places:<br />
# static variables in C++ sources<br />
# text surrounded by markup in CMake script files<br />
<br />
== Documentation in C++ sources ==<br />
<br />
This is the primary source of builtin documentation.<br />
<br />
== Documentation markup in CMake script files ==<br />
<br />
This source is available since CMake 2.8.8 and is currently only used by CPack.<br />
The idea behind CMake script markup is to be able to document CMake scripts. Documenting a script means being able to put in structured documentation using some comments.<br />
<br />
Before 2.8.8, this was available through:<br />
cmake --help-module<br />
which was basically extracting the first block of comments stripping out the comment character ('#').<br />
<br />
From 2.8.8 and up we may be able to do more by using a basic markup language which may be used to document<br />
- variable<br />
- command<br />
- section<br />
<br />
The markup may then be automatically extracted by ctool (cmake, cpack, ctest) in order to feed their<br />
--help-variable[s|-list]<br />
--help-command[s|-list]<br />
command lines options</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=48007CMake:CPackPackageGenerators2012-06-18T07:06:08Z<p>Erk: /* CPack Package Generators */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
CPack may generate several kind of package on behalf of various ''CPack Generators''. All generators share common properties explained below. Some if not all generators do have specific features or restriction which are explained in specific sections.<br />
<br />
Since CPack 2.8.8, CPack has builtin documentation just like CMake so that one can use:<br />
<br />
cpack --help-variable-list<br />
cpack --help-variable <VARNAME><br />
cpack --help-command-list<br />
cpack --help-command <CMDNAME><br />
...<br />
cpack --help<br />
<br />
in order to get specific documentation. This [http://www.cmake.org/Wiki/CMake_builtin_documentation_handling builtin documentation] should be the most up to date documentation for CPack.<br />
The current Wiki is a convenient place to find informations but may not be as up to date as the builtin doc.<br />
<br />
If ever you find undocumented variable and/or innaccurate documentation please file a [http://public.kitware.com/Bug/main_page.php bug report].<br />
The main part of CPack variable or command documentation may be found in CPack<GEN>.cmake file in the CMake source, the documentation is extracted from those files automatically and dynamically by CPack, so you can submit a documentation patch using one of those files.<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Archive Generators==<br />
<br />
The archive generators are a family of CPack generators derived from the same base class generator. These generators use the [http://code.google.com/p/libarchive/ libarchive] library to produce various archive file formats. These generators share common properties which are explained in this section. Specific features are explained in sections corresponding to the specific generator.<br />
<br />
Please note that one might want to try to avoid packaging symlinks within .tgz, .tbz2 or similar archives, the reason being that libarchive converts them to hard links, and, to add insult to injury, it then even ''clips'' (read: '''corrupts''') even moderately long paths, causing tar '''extraction failure''' (observed in CMake 2.6.4 Linux, TODO list experience with newer versions).<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package. See the [[CMake:CPackNSISAdvancedTips|Advanced Tips]] for details on customizing an NSIS script through CPack.<br />
<br />
=== NSIS Generator Specifics settings ===<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_NSIS_MUI_ICON || The icon file (.ico) for the generated install program. Both this and CPACK_NSIS_MUI_UNIICON need to set for this to have any effect. || installer.ico<br />
|-<br />
| CPACK_NSIS_MUI_UNIICON || The icon file (.ico) for the generated uninstall program. Both this and CPACK_NSIS_MUI_ICON need to set for this to have any effect. || uninstaller.ico<br />
|-<br />
| CPACK_PACKAGE_ICON || A branding image that will be displayed on the top bar inside the installer. || installer.bmp<br />
|-<br />
| CPACK_NSIS_EXTRA_INSTALL_COMMANDS || Extra NSIS commands that will be added to the install Section. || ExecWait '\\\"$INSTDIR\\\\vcredist_x86.exe\\\" /q:a'<br />
|-<br />
| CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS || Extra NSIS commands that will be added to the uninstall Section. || <br />
|-<br />
| CPACK_NSIS_COMPRESSOR || The arguments that will be passed to the NSIS SetCompressor command. || /SOLID lzma<br />
|-<br />
| CPACK_NSIS_MODIFY_PATH || If this is set to "ON", then an extra page will appear in the installer that will allow the user to choose whether the program directory should be added to the system PATH variable. || ON<br />
|-<br />
| CPACK_NSIS_DISPLAY_NAME || Undocumented. || "${CPACK_PACKAGE_INSTALL_DIRECTORY} My Famous Project"<br />
|-<br />
| CPACK_NSIS_INSTALLED_ICON_NAME || Set the icon used for the Windows "Add or Remove Programs" tool. || "bin\\\\MyExecutable.exe"<br />
|-<br />
| CPACK_NSIS_HELP_LINK || Adds link to registry. URI. || "http:\\\\\\\\www.my-project-home-page.org"<br />
|-<br />
| CPACK_NSIS_URL_INFO_ABOUT || Adds link to registry and the vendor in add/remove programs' "Click here for support information" in program entry links here. || "http:\\\\\\\\www.my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CONTACT || Adds link to add/remove programs' "Click here for support information" in program entry. || "me@my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CREATE_ICONS_EXTRA || Additional NSIS commands for creating start menu shortcuts. || set(CPACK_NSIS_CREATE_ICONS "CreateShortCut '\$SMPROGRAMS\\\\$STARTMENU_FOLDER\\\\${PROJECT_NAME}.lnk' '\$INSTDIR\\\\${PROJECT_NAME}.exe'")<br />
|-<br />
| CPACK_NSIS_DELETE_ICONS_EXTRA || Undocumented. Possibly: Additional NSIS commands to uninstall start menu shortcuts. ||<br />
|-<br />
| CPACK_NSIS_MENU_LINKS || Used to override the Start Menu links. || "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/CMakeSetup.html" "CMakeSetup Help"<br />
|-<br />
| CPACK_NSIS_MUI_FINISHPAGE_RUN || If used, will make it possible for user to choose (on an additional page, displayed at the end of the installation) to run intalled program. Should point to program name to run, seemingly without any sub-directories of the installation directory in case program installed in such sub-directories (but please check generated NSIS script if you can't make it work). || "MyExecutable.exe"<br />
|-<br />
|}<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
===Debian Generator specific settings===<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_MAINTAINER || The maintenainer informations || Firstname Lastname <email@example.com><br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_SUMMARY || Package short description || Here is my short description<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION || Package description || Here is my long description<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_DEPENDS || Package dependencies (use dpkg -s <packagename> to retrieve version) || libc6 (>= 2.7-18)<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA || This variable allow advanced user to add custom script to the control.tar.gz (inside the .deb archive) || ${CMAKE_CURRENT_SOURCE_DIR}/postinst<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_SECTION || Package section (see http://packages.debian.org/stable/) || Network<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_VERSION || Package version || ${CPACK_PACKAGE_VERSION}+lenny1<br />
|-<br />
|}<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
The CPack RPM generator supports [[CMake:Component_Install_With_CPack|CPack Component installation]]. You can find details about the implementation [[http://public.kitware.com/Bug/view.php?id=7645 here]].<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is similar to other CPack generators. Its execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, a detailed description of how to use the CPACK_RPM_xxxx is available in this article or from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
=== CPack RPM generators specific settings ===<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_PACKAGE_PROVIDES'' || May be used to set the virtual packages provided by the RPM. It is somewhat complimentary to CPACK_RPM_PACKAGE_REQUIRES, but note that you do not need to list things like libraries, etc. here, since rpmbuild will figure that out by itself when generating the RPM. Most packages leave this blank. NOTE: This variable was added in cmake 2.8.1 (see [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584]]).|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]]). This is '''not to be confused''' with .spec %post section (the action specified here is being invoked at ''rpmbuild'' time, not ''post-install-package'' time at user side) || -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake_builtin_documentation_handling&diff=48006CMake builtin documentation handling2012-06-18T07:04:31Z<p>Erk: /* CMake,CPack,CTest builtin documentation */</p>
<hr />
<div>== CMake,CPack,CTest builtin documentation ==<br />
<br />
All CMake tools command line do have some builtin documentation support. The tools (cmake, cpack, ctest) supports a variable subset of:<br />
<br />
ctool --help-command[-list] <br />
ctool --help-module[-list]<br />
ctool --help-variable[-list]<br />
ctool --help-policy[-list]<br />
ctool --help-property[-list]<br />
ctool --help-full<br />
ctool --help-html<br />
<br />
for the detail see:<br />
<br />
cmake --help<br />
cpack --help<br />
ctest --help<br />
<br />
This builtin documentation comes from 2 different places:<br />
# static variables in C++ sources<br />
# text surrounded by markup in CMake script files<br />
<br />
== Documentation in C++ sources ==<br />
<br />
This is the primary source of builtin documentation.<br />
<br />
== Documentation markup in CMake script files ==<br />
<br />
This source is available since CMake 2.8.8 and is currently only used by CPack.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake_builtin_documentation_handling&diff=48005CMake builtin documentation handling2012-06-18T07:02:30Z<p>Erk: Created page with "== CMake,CPack,CTest builtin documentation == All CMake tools command line do have some builtin documentation support. The tools (cmake, cpack, ctest) supports a variable subset..."</p>
<hr />
<div>== CMake,CPack,CTest builtin documentation ==<br />
<br />
All CMake tools command line do have some builtin documentation support. The tools (cmake, cpack, ctest) supports a variable subset of:<br />
<br />
ctool --help-command[-list] <br />
ctool --help-module[-list]<br />
ctool --help-variable[-list]<br />
ctool --help-policy[-list]<br />
ctool --help-property[-list]<br />
ctool --help-full<br />
ctool --help-html<br />
<br />
see<br />
<br />
cmake --help<br />
cpack --help<br />
ctest --help<br />
<br />
for the details.<br />
<br />
This builtin documentation comes from 2 different place:<br />
# static variables in C++ sources<br />
# text surrounded by markup in CMake script files<br />
<br />
== Documentation in C++ sources ==<br />
<br />
This is the primary source of builtin documentation.<br />
<br />
== Documentation markup in CMake script files ==<br />
<br />
This source is available since CMake 2.8.8 and is currently only used by CPack.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake&diff=48004CMake2012-06-18T06:53:25Z<p>Erk: /* Development Topics */</p>
<hr />
<div>http://www.cmake.org/cmake/img/CMake-logo-download.jpg<br />
<br />
<!-- documentation manual man information help tutorial --><br />
Welcome to CMake, the cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform and compiler independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. CMake is quite sophisticated: it is possible to support complex environments requiring system configuration, pre-processor generation, code generation, and template instantiation.<br />
<br />
You will find here not only documentation for CMake, but also for CPack and CTest.<br />
<br />
=CMake=<br />
<br />
==Primary Resources - Look here first! ==<br />
* Where can I [http://www.cmake.org/HTML/Download.html download CMake]?<br />
* [http://www.cmake.org/HTML/Documentation.html CMake Documentation]<br />
* [[CMake Useful Variables|Useful CMake Variables]]<br />
* [[CMake FAQ| FAQ (Frequently asked questions)]]<br />
* [http://www.cmake.org/mailman/listinfo/cmake CMake Mailing List] (for searchable archives see [[CMake_FAQ#Where_can_I_find_searchable_CMake_Mailing_Archives | CMake FAQ ]])<br />
* [[CMake_2.6_Notes|CMake 2.6 Notes]]<br />
* ''Getting Started With CMake'' Screencasts @[http://playcontrol.net/ewing/screencasts/getting_started_with_cmake_.html PlayControl.net]<br />
<br />
==Development Topics==<br />
* [[CMake Cross Compiling| Cross compiling]]<br />
* [[CMake RPATH handling|RPATH handling]]<br />
* [[CMake/Assembler|Assembler Support]]<br />
* [[CMake Editors Support|Editors/IDEs with CMake syntax support]]<br />
* [[CMake Generator Specific Information|Docs for Specific Project Generators]] (Eclipse, KDevelop3, CodeBlocks, Makefile)<br />
* [[CMake User Contributed Macros| Contributed macros]]<br />
* [[CMake:Module Maintainers|Module Maintainers]]<br />
* [[CMake Platform Dependent Issues|Platform Dependent Information]]<br />
* [[CMake Released Versions|Documentation for previous releases]]<br />
* [[CMake Version Compatibility Matrix|Matrix for checking backwards-compatibility of current features]]<br />
* [[CMake builtin documentation handling]]<br />
<br />
==Tutorials==<br />
<br />
===Basic Introductions===<br />
* [http://www.cmake.org/HTML/Examples.html A Simple CMake Example]<br />
* [http://www.linuxjournal.com/article/6700 Cross-Platform Software Development Using CMake]<br />
* [http://clubjuggler.livejournal.com/138364.html CMake: The Cross Platform Build System]<br />
* [http://www.elpauer.org/stuff/learning_cmake.pdf "Learning CMake"] - Slides of a CMake workshop, including CPack, CTest and CDash<br />
* [https://github.com/TheErk/CMake-tutorial CMake tutorial] - Slides (with LaTeX bearmer source) of a CMake tutorial including CPack, CTest.<br />
* [http://www.visgraf.impa.br/seminar/slides/rodlima_cmake_presentation.pdf "CMake: Behind the Scenes of Code Development"] - Slides of an introductory talk/tutorial about CMake and its benefits<br />
* [http://snikt.net/index.php/2010/04/01/howto-use-cmake-with-cc-projects Howto use cmake with C/C++ projects] A simple walk-through about creating a cmake C project including integration of subversion, doxygen and how-to add optional project parts as configurables<br />
* [http://hackerwithin.org/thw/plugin_wiki/page/buildsystems The Hacker Within: Build Systems] Explains why and how to use build systems with a CMake example.<br />
* Syntax of the CMake language<br />
** [http://www.cmake.org/HTML/syntax.html A quick introduction to CMake syntax]<br />
** [[CMake/Language Syntax | Language syntax]] (wiki page)<br />
** [[CMake:VariablesListsStrings| On variables, lists, strings, maps, regexps, etc.]]<br />
* How CMake simplifies the build process by Bruno Abinader<br />
** [http://www.abinader.com.br/bruno/how-cmake-simplifies-the-build-process-part-1-basic-build-system/ Part 1 - Basic build system]<br />
** [http://web.archive.org/web/20101030232202/http://cabledogs.org/abinader/2009/12/09/how-cmake-simplifies-the-build-process-part-2-advanced-build-system/ Part 2 - Advanced build system]<br />
* [http://rachid.koucha.free.fr/tech_corner/cmake_manual.html Empirical approach to CMAKE] by Rachid Koucha<br />
<br />
===Finding stuff and platform checking===<br />
<br />
* [[CMake HowToDoPlatformChecks| How to write platform checks with CMake]]<br>Describes how to implement platform or configure checks with CMake.<br />
<br />
* [[CMake/Tutorials#CMake_Packages|How to package your project for use by others]], create FooConfig.cmake files, and exporting and importing targets.<br />
<br />
* [[CMake:How_To_Find_Libraries | How to find libraries]] <br>Describes how to use external libraries in a CMake project and how to write your own find modules for libraries that don't already have one.<br />
<br />
* [[CMake:HowToUseExistingOSXFrameworks | How to find and use existing frameworks on OS X]]<br> A quick example to help OS X users find frameworks automatically.<br />
<br />
===How to use CMake with specific Libraries ===<br />
<br />
* [[CMake:How To Build Qt4 Software | How to build Qt4 software with CMake]]<br />
<br />
* [http://qtnode.net/wiki?title=Qt_with_cmake Qt with CMake] <br>Explains how to use CMake to build software with Qt4, Qt3 and KDE3.<br />
<br />
* [http://mikemcquaid.com/2012/01/deploying-qt-applications-with-deployqt4/ Deploying Qt4 applications with CMake] <br>Explains how to use the DeployQt4.cmake module coming with CMake 2.8.7.<br />
<br />
* [[CMake:How To Build KDE4 Software | How to build KDE4 software with CMake]]<br />
<br />
* [[CMake:MatlabMex | How to use CMake to create Matlab MEX files]] <br> Describes how to use CMake when developing Matlab Executable (MEX) files for use with The Mathworks Matlab scripting language.<br />
<br />
* [http://www.wxwidgets.org/wiki/index.php/CMake How to use CMake for building software with wxWidgets ]<br />
<br />
* [http://www.linuxdevices.com/articles/AT6762290643.html Building eCos applications with CMake]<br />
<br />
* [http://www.smslana.eu Building Sms applications with CMake]<br />
<br />
* [http://blog.quickforge.co.uk/2011/10/exploration-of-cross-compiling-on-windows-for-arm-linux-distributions/ Cross compiling from Windows to ARM Linux]<br />
<br />
* [[CMakeForFLTK| Using CMake to build an FLTK application]]<br />
<br />
===Recipes===<br />
<br />
* [[CMake:How To Process Lots Of Input Files | How to process lots of input files with a processor built by CMake]]<br />
<br />
* [[BuildingWinDLL| How to export symbols from a Windows DLL for the non-Windows Developer]]<br />
<br />
* [[VSConfigSpecificSettings| Configuration Specific Settings for Visual Studio Generated Project Files]]<br />
<br />
* [[BundleUtilitiesExample| How to use the 'BundleUtilities' to deploy your OS X Application. Example uses Qt 4.]]<br />
<br />
* [[CMakeForFortranExample|How to write a simple CMakeLists.txt for Fortran code]]<br />
<br />
* [[CMakeEmulateMakeCheck|How to emulate GNU Autotools 'make check']]<br />
<br />
* [[CustomCommandCustomTargetInstall|A toy model for add_custom_command and add_custom_target]]<br />
<br />
* [[CMake:OSX_InterfaceBuilderFiles|Working with OS X Interface Builder Files]]<br />
<br />
* [[RecipeAppendVersionNumberToInstallpath|Append the Version Number to the Install path]]<br />
<br />
* [[RecipeInstallToALocalFolderForTesting|Install to a local folder in the build dir for testing]]<br />
<br />
* [[RecipeAddUninstallTarget|Adding an uninstall target to your project]]<br />
<br />
* [[RecipeAddSoVersionToDLLs|Appending the SO version to DLLs]]<br />
<br />
==Converters from other buildsystems to CMake==<br />
<br />
All converters listed here are not "complete", i.e. the generated CMake files are not 100% finished, in all cases some work is left for the developer.<br />
<br />
====automake/autotools/autoconf====<br />
* [http://websvn.kde.org/trunk/KDE/kdesdk/cmake/scripts/ am2cmake (requires Ruby) ] Converts automake/autotools/libtool based projects to CMake, specialized in converting from KDE 3 to KDE 4, should also work for others. This one has been used for converting the KDE buildsystem to CMake.<br />
<br />
* [http://emanuelgreisen.dk/stuff/kdevelop_am2cmake.php.tgz Alternative Automake2CMake (requires PHP)] Converts KDevelop projects that use automake to CMake.<br />
<br />
* [[GccXmlAutoConfHints|Converting autoconf tests]]<br />
<br />
====qmake====<br />
* [[CMake:ConvertFromQmake | qmake converter (requires Ruby)]] Converts projects that use Qt's qmake.<br />
<br />
====Visual Studio====<br />
* [http://vcproj2cmake.sf.net vcproj2cmake.rb (requires Ruby) SourceForge project] Creates '''and maintains''' CMakeLists.txt files by extracting info from Visual Studio project files. Elaborate script for development side-by-side the updated original static .vcproj files, supports script hooks and powerful definition mappings. Patches and new project members very welcome. Older script versions below:<br />
** [http://www.eskilson.se/vcproj2cmake.rb Original vcproj2cmake.rb version (requires Ruby)] <br />
** Slightly newer version here [http://dgwarp.hd.free.fr/vcproj2cmake.rb vcproj2cmake.rb], see:[[User_talk:Dweeves]] for details<br />
* [http://nberserk.blogspot.com/2010/11/converting-vc-projectsvcproj-to.html vcproj2cmake.ps1(PowerShell version)] Creates CMakeLists.txt. it supports vcproj configuration and detect 'exclude from build' option<br />
* [http://sourceforge.net/projects/folders4cmake/ folders4cmake (requires Java)] Use Visual Studio project files to generate corresponding "source_group" information that you can use inside your own CMake scripts. Supports Visual Studio 9/10 project files (full round-trip possible).<br />
<br />
====Basic CMakeLists.txt from-scratch-generator====<br />
* [http://websvn.kde.org/trunk/KDE/kdesdk/cmake/scripts/ gencmake (requires Ruby) ] Creates basic CMakeLists.txt files from looking at the existing files.<br />
* [http://www.vanvelzensoftware.com/postnuke/index.php?name=Downloads&req=viewdownload&cid=7 CMakeListGenerator (Win32) ] Creates complete CMakeLists.txt files as described in the [https://gucef.svn.sourceforge.net/svnroot/gucef/trunk/tools/CMakeListGenerator/docs/README.txt README ] using a combination of file and directory structure analysis. Supports resolving dependencies between multiple archives.<br />
<br />
==Success Stories==<br />
<br />
* What are some [[CMake Projects|projects using CMake]]?<br />
* [[CMake:Articles|Articles about CMake]]<br />
* [[Really Cool CMake Features]]<br />
<br />
<br />
==More Topics==<br />
<br />
* [[CMake Fortran Issues|Fortran Issues]]<br />
* [[CMake:For CMake Hackers|Generating dependency graphs with CMake]]<br />
* [[CMake:Experiments With Lua|Experiments With Lua]]<br />
* [[CMake Performance Tips|Performance Tips]]<br />
* [[CMake:Install Commands| Replacing deprecated INSTALL_FILES, INSTALL_PROGRAMS and INSTALL_TARGETS commands]]<br />
* [[CMake:GNU style example | GNU style directory layout with CMake]]<br />
* [[CMake:OpenTasks| CMake TODO]]<br />
* [[CMake:CreateQtAssistantDocs| Creating Qt Assistant Docs]]<br />
* [[CMake:Static libraries| Writing FindXXX.cmake modules that work with static libraries]]<br />
* [[CMake:Multiple versions| Writing FindXXX.cmake modules that work when multiple versions of packages are installed]]<br />
* [[CMake:Improving Find* Modules ]]<br />
* [[/C Plugins for Loadable Commands/]]<br>For anyone who wonders what the <tt>load_command</tt> command is for.<br />
* [[PC-Lint]] support for CMake<br />
<br />
=CTest=<br />
<br />
===Tutorials===<br />
* [[CMake Testing With CTest|Testing With CTest]]<br>Introduces to testing with CTest, submitting dashboards, and using CMake to add tests to the test system.<br />
<br />
* [[CMake Scripting Of CTest|CTest Scripting]]<br>Describes the scripting with CTest which can significantly simplify and automate testing and submitting dashboards.<br />
<br />
* [[CMake Generating Testing Files|Generating Input Files For CTest]]<br>Describe more in details the concepts behind testing with CTest and also explans how to use CTest without using CMake.<br />
<br />
* [[CTest:Buildserver|Buildmanagement With CTest]]<br>Describes how to setup a central configuration for all CTest scripts.<br />
<br />
===More Information===<br />
* [[CTest:Submission Issues|Configuring CTest Submission Methods]]<br />
* [[CTest:Nightly, Experimental, Continuous|CTest Nightly, Experimental, Continuous, ...]]<br />
* [[CTest:Coverage]]<br />
* [[Media:CTest Running Modes.pdf]]<br />
* [[CTest:FAQ|CTest Frequently asked questions]]<br />
<br />
===More Topics===<br />
* [[CTest:OpenTasks| CTest TODO]]<br />
* [[CTest:TestWithoutBuild| Run tests on machines without building first]]<br />
<br />
=CDash=<br />
* [http://public.kitware.com/Wiki/CDash CDash Wiki].<br />
* [http://public.kitware.com/Wiki/CDash:FAQ CDash FAQ].<br />
<br />
<br />
=CPack=<br />
===Tutorials===<br />
* [[CMake:Packaging With CPack|Packaging with CPack]]<br>Introduction to CPack, installing and packaging of software.<br />
* [https://github.com/TheErk/CMake-tutorial CMake tutorial] - Slides from a CMake tutorial (including LaTeX beamer source) including CPack.<br />
* [[CMake:CPackConfiguration|CPack Variables]]<br><br />
* [[CMake:CPackPackageGenerators|Supported package formats]]<br><br />
* [[CMake:CPackWin32NewbiesChecklist|CPack Win32 Newbie Checklist]] <br><br />
* [[CMake:Component_Install_With_CPack|Component Install With CPack]] <br><br />
<br />
===Recipes===<br />
<br />
* [[RecipeAddShortcutToStartMenu|Add an application shortcut to the Start Menu]]<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=48003CMake:CPackPackageGenerators2012-06-18T06:40:24Z<p>Erk: /* CPack Package Generators */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
CPack may generate several kind of package on behalf of various ''CPack Generators''. All generators share common properties explained below. Some if not all generators do have specific features or restriction which are explained in specific sections.<br />
<br />
Since CPack 2.8.8, CPack has builtin documentation just like CMake so that one can use:<br />
<br />
cpack --help-variable-list<br />
cpack --help-variable <VARNAME><br />
cpack --help-command-list<br />
cpack --help-command <CMDNAME><br />
...<br />
cpack --help<br />
<br />
in order to get specific documentation. This builtin documentation should be the most up to date documentation for CPack.<br />
The current Wiki is a convenient place to find informations but may not be as up to date as the builtin doc.<br />
<br />
If ever you find undocumented variable and/or innaccurate documentation please file a [http://public.kitware.com/Bug/main_page.php bug report].<br />
The main part of CPack variable or command documentation may be found in CPack<GEN>.cmake file in the CMake source, the documentation is extracted from those files automatically and dynamically by CPack, so you can submit a documentation patch using one of those files.<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Archive Generators==<br />
<br />
The archive generators are a family of CPack generators derived from the same base class generator. These generators use the [http://code.google.com/p/libarchive/ libarchive] library to produce various archive file formats. These generators share common properties which are explained in this section. Specific features are explained in sections corresponding to the specific generator.<br />
<br />
Please note that one might want to try to avoid packaging symlinks within .tgz, .tbz2 or similar archives, the reason being that libarchive converts them to hard links, and, to add insult to injury, it then even ''clips'' (read: '''corrupts''') even moderately long paths, causing tar '''extraction failure''' (observed in CMake 2.6.4 Linux, TODO list experience with newer versions).<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package. See the [[CMake:CPackNSISAdvancedTips|Advanced Tips]] for details on customizing an NSIS script through CPack.<br />
<br />
=== NSIS Generator Specifics settings ===<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_NSIS_MUI_ICON || The icon file (.ico) for the generated install program. Both this and CPACK_NSIS_MUI_UNIICON need to set for this to have any effect. || installer.ico<br />
|-<br />
| CPACK_NSIS_MUI_UNIICON || The icon file (.ico) for the generated uninstall program. Both this and CPACK_NSIS_MUI_ICON need to set for this to have any effect. || uninstaller.ico<br />
|-<br />
| CPACK_PACKAGE_ICON || A branding image that will be displayed on the top bar inside the installer. || installer.bmp<br />
|-<br />
| CPACK_NSIS_EXTRA_INSTALL_COMMANDS || Extra NSIS commands that will be added to the install Section. || ExecWait '\\\"$INSTDIR\\\\vcredist_x86.exe\\\" /q:a'<br />
|-<br />
| CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS || Extra NSIS commands that will be added to the uninstall Section. || <br />
|-<br />
| CPACK_NSIS_COMPRESSOR || The arguments that will be passed to the NSIS SetCompressor command. || /SOLID lzma<br />
|-<br />
| CPACK_NSIS_MODIFY_PATH || If this is set to "ON", then an extra page will appear in the installer that will allow the user to choose whether the program directory should be added to the system PATH variable. || ON<br />
|-<br />
| CPACK_NSIS_DISPLAY_NAME || Undocumented. || "${CPACK_PACKAGE_INSTALL_DIRECTORY} My Famous Project"<br />
|-<br />
| CPACK_NSIS_INSTALLED_ICON_NAME || Set the icon used for the Windows "Add or Remove Programs" tool. || "bin\\\\MyExecutable.exe"<br />
|-<br />
| CPACK_NSIS_HELP_LINK || Adds link to registry. URI. || "http:\\\\\\\\www.my-project-home-page.org"<br />
|-<br />
| CPACK_NSIS_URL_INFO_ABOUT || Adds link to registry and the vendor in add/remove programs' "Click here for support information" in program entry links here. || "http:\\\\\\\\www.my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CONTACT || Adds link to add/remove programs' "Click here for support information" in program entry. || "me@my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CREATE_ICONS_EXTRA || Additional NSIS commands for creating start menu shortcuts. || set(CPACK_NSIS_CREATE_ICONS "CreateShortCut '\$SMPROGRAMS\\\\$STARTMENU_FOLDER\\\\${PROJECT_NAME}.lnk' '\$INSTDIR\\\\${PROJECT_NAME}.exe'")<br />
|-<br />
| CPACK_NSIS_DELETE_ICONS_EXTRA || Undocumented. Possibly: Additional NSIS commands to uninstall start menu shortcuts. ||<br />
|-<br />
| CPACK_NSIS_MENU_LINKS || Used to override the Start Menu links. || "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/CMakeSetup.html" "CMakeSetup Help"<br />
|-<br />
| CPACK_NSIS_MUI_FINISHPAGE_RUN || If used, will make it possible for user to choose (on an additional page, displayed at the end of the installation) to run intalled program. Should point to program name to run, seemingly without any sub-directories of the installation directory in case program installed in such sub-directories (but please check generated NSIS script if you can't make it work). || "MyExecutable.exe"<br />
|-<br />
|}<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
===Debian Generator specific settings===<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_MAINTAINER || The maintenainer informations || Firstname Lastname <email@example.com><br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_SUMMARY || Package short description || Here is my short description<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION || Package description || Here is my long description<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_DEPENDS || Package dependencies (use dpkg -s <packagename> to retrieve version) || libc6 (>= 2.7-18)<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA || This variable allow advanced user to add custom script to the control.tar.gz (inside the .deb archive) || ${CMAKE_CURRENT_SOURCE_DIR}/postinst<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_SECTION || Package section (see http://packages.debian.org/stable/) || Network<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_VERSION || Package version || ${CPACK_PACKAGE_VERSION}+lenny1<br />
|-<br />
|}<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
The CPack RPM generator supports [[CMake:Component_Install_With_CPack|CPack Component installation]]. You can find details about the implementation [[http://public.kitware.com/Bug/view.php?id=7645 here]].<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is similar to other CPack generators. Its execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, a detailed description of how to use the CPACK_RPM_xxxx is available in this article or from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
=== CPack RPM generators specific settings ===<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_PACKAGE_PROVIDES'' || May be used to set the virtual packages provided by the RPM. It is somewhat complimentary to CPACK_RPM_PACKAGE_REQUIRES, but note that you do not need to list things like libraries, etc. here, since rpmbuild will figure that out by itself when generating the RPM. Most packages leave this blank. NOTE: This variable was added in cmake 2.8.1 (see [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584]]).|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]]). This is '''not to be confused''' with .spec %post section (the action specified here is being invoked at ''rpmbuild'' time, not ''post-install-package'' time at user side) || -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=48002CMake:CPackPackageGenerators2012-06-18T06:31:34Z<p>Erk: </p>
<hr />
<div>=CPack Package Generators=<br />
<br />
CPack may generate several kind of package on behalf of various ''CPack Generators''. All generators share common properties explained below. Some if not all generators do have specific features or restriction which are explained in specific sections.<br />
<br />
Since CPack 2.8.8, CPack has builtin documentation just like CMake so that one can use:<br />
<br />
cpack --help-variable-list<br />
cpack --help-variable <VARNAME><br />
cpack --help-command-list<br />
cpack --help-command <CMDNAME><br />
...<br />
cpack --help<br />
<br />
in order to get specific documentation. This builtin documentation should be the most up to date documentation for CPack.<br />
The current Wiki is a convenient place to find informations but may not be as up to date as the builtin doc.<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Archive Generators==<br />
<br />
The archive generators are a family of CPack generators derived from the same base class generator. These generators use the [http://code.google.com/p/libarchive/ libarchive] library to produce various archive file formats. These generators share common properties which are explained in this section. Specific features are explained in sections corresponding to the specific generator.<br />
<br />
Please note that one might want to try to avoid packaging symlinks within .tgz, .tbz2 or similar archives, the reason being that libarchive converts them to hard links, and, to add insult to injury, it then even ''clips'' (read: '''corrupts''') even moderately long paths, causing tar '''extraction failure''' (observed in CMake 2.6.4 Linux, TODO list experience with newer versions).<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package. See the [[CMake:CPackNSISAdvancedTips|Advanced Tips]] for details on customizing an NSIS script through CPack.<br />
<br />
=== NSIS Generator Specifics settings ===<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_NSIS_MUI_ICON || The icon file (.ico) for the generated install program. Both this and CPACK_NSIS_MUI_UNIICON need to set for this to have any effect. || installer.ico<br />
|-<br />
| CPACK_NSIS_MUI_UNIICON || The icon file (.ico) for the generated uninstall program. Both this and CPACK_NSIS_MUI_ICON need to set for this to have any effect. || uninstaller.ico<br />
|-<br />
| CPACK_PACKAGE_ICON || A branding image that will be displayed on the top bar inside the installer. || installer.bmp<br />
|-<br />
| CPACK_NSIS_EXTRA_INSTALL_COMMANDS || Extra NSIS commands that will be added to the install Section. || ExecWait '\\\"$INSTDIR\\\\vcredist_x86.exe\\\" /q:a'<br />
|-<br />
| CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS || Extra NSIS commands that will be added to the uninstall Section. || <br />
|-<br />
| CPACK_NSIS_COMPRESSOR || The arguments that will be passed to the NSIS SetCompressor command. || /SOLID lzma<br />
|-<br />
| CPACK_NSIS_MODIFY_PATH || If this is set to "ON", then an extra page will appear in the installer that will allow the user to choose whether the program directory should be added to the system PATH variable. || ON<br />
|-<br />
| CPACK_NSIS_DISPLAY_NAME || Undocumented. || "${CPACK_PACKAGE_INSTALL_DIRECTORY} My Famous Project"<br />
|-<br />
| CPACK_NSIS_INSTALLED_ICON_NAME || Set the icon used for the Windows "Add or Remove Programs" tool. || "bin\\\\MyExecutable.exe"<br />
|-<br />
| CPACK_NSIS_HELP_LINK || Adds link to registry. URI. || "http:\\\\\\\\www.my-project-home-page.org"<br />
|-<br />
| CPACK_NSIS_URL_INFO_ABOUT || Adds link to registry and the vendor in add/remove programs' "Click here for support information" in program entry links here. || "http:\\\\\\\\www.my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CONTACT || Adds link to add/remove programs' "Click here for support information" in program entry. || "me@my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CREATE_ICONS_EXTRA || Additional NSIS commands for creating start menu shortcuts. || set(CPACK_NSIS_CREATE_ICONS "CreateShortCut '\$SMPROGRAMS\\\\$STARTMENU_FOLDER\\\\${PROJECT_NAME}.lnk' '\$INSTDIR\\\\${PROJECT_NAME}.exe'")<br />
|-<br />
| CPACK_NSIS_DELETE_ICONS_EXTRA || Undocumented. Possibly: Additional NSIS commands to uninstall start menu shortcuts. ||<br />
|-<br />
| CPACK_NSIS_MENU_LINKS || Used to override the Start Menu links. || "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/CMakeSetup.html" "CMakeSetup Help"<br />
|-<br />
| CPACK_NSIS_MUI_FINISHPAGE_RUN || If used, will make it possible for user to choose (on an additional page, displayed at the end of the installation) to run intalled program. Should point to program name to run, seemingly without any sub-directories of the installation directory in case program installed in such sub-directories (but please check generated NSIS script if you can't make it work). || "MyExecutable.exe"<br />
|-<br />
|}<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
===Debian Generator specific settings===<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_MAINTAINER || The maintenainer informations || Firstname Lastname <email@example.com><br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_SUMMARY || Package short description || Here is my short description<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION || Package description || Here is my long description<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_DEPENDS || Package dependencies (use dpkg -s <packagename> to retrieve version) || libc6 (>= 2.7-18)<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA || This variable allow advanced user to add custom script to the control.tar.gz (inside the .deb archive) || ${CMAKE_CURRENT_SOURCE_DIR}/postinst<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_SECTION || Package section (see http://packages.debian.org/stable/) || Network<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_VERSION || Package version || ${CPACK_PACKAGE_VERSION}+lenny1<br />
|-<br />
|}<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
The CPack RPM generator supports [[CMake:Component_Install_With_CPack|CPack Component installation]]. You can find details about the implementation [[http://public.kitware.com/Bug/view.php?id=7645 here]].<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is similar to other CPack generators. Its execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, a detailed description of how to use the CPACK_RPM_xxxx is available in this article or from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
=== CPack RPM generators specific settings ===<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_PACKAGE_PROVIDES'' || May be used to set the virtual packages provided by the RPM. It is somewhat complimentary to CPACK_RPM_PACKAGE_REQUIRES, but note that you do not need to list things like libraries, etc. here, since rpmbuild will figure that out by itself when generating the RPM. Most packages leave this blank. NOTE: This variable was added in cmake 2.8.1 (see [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584]]).|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]]). This is '''not to be confused''' with .spec %post section (the action specified here is being invoked at ''rpmbuild'' time, not ''post-install-package'' time at user side) || -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake&diff=47320CMake2012-05-31T07:28:24Z<p>Erk: /* Tutorials */</p>
<hr />
<div>http://www.cmake.org/cmake/img/CMake-logo-download.jpg<br />
<br />
<!-- documentation manual man information help tutorial --><br />
Welcome to CMake, the cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform and compiler independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. CMake is quite sophisticated: it is possible to support complex environments requiring system configuration, pre-processor generation, code generation, and template instantiation.<br />
<br />
You will find here not only documentation for CMake, but also for CPack and CTest.<br />
<br />
=CMake=<br />
<br />
==Primary Resources - Look here first! ==<br />
* Where can I [http://www.cmake.org/HTML/Download.html download CMake]?<br />
* [http://www.cmake.org/HTML/Documentation.html CMake Documentation]<br />
* [[CMake Useful Variables|Useful CMake Variables]]<br />
* [[CMake FAQ| FAQ (Frequently asked questions)]]<br />
* [http://www.cmake.org/mailman/listinfo/cmake CMake Mailing List] (for searchable archives see [[CMake_FAQ#Where_can_I_find_searchable_CMake_Mailing_Archives | CMake FAQ ]])<br />
* [[CMake_2.6_Notes|CMake 2.6 Notes]]<br />
* ''Getting Started With CMake'' Screencasts @[http://playcontrol.net/ewing/screencasts/getting_started_with_cmake_.html PlayControl.net]<br />
<br />
==Development Topics==<br />
* [[CMake Cross Compiling| Cross compiling]]<br />
* [[CMake RPATH handling|RPATH handling]]<br />
* [[CMake/Assembler|Assembler Support]]<br />
* [[CMake Editors Support|Editors/IDEs with CMake syntax support]]<br />
* [[CMake Generator Specific Information|Docs for Specific Project Generators]] (Eclipse, KDevelop3, CodeBlocks, Makefile)<br />
* [[CMake User Contributed Macros| Contributed macros]]<br />
* [[CMake:Module Maintainers|Module Maintainers]]<br />
* [[CMake Platform Dependent Issues|Platform Dependent Information]]<br />
* [[CMake Released Versions|Documentation for previous releases]]<br />
* [[CMake Version Compatibility Matrix|Matrix for checking backwards-compatibility of current features]]<br />
<br />
==Tutorials==<br />
<br />
===Basic Introductions===<br />
* [http://www.cmake.org/HTML/Examples.html A Simple CMake Example]<br />
* [http://www.linuxjournal.com/article/6700 Cross-Platform Software Development Using CMake]<br />
* [http://clubjuggler.livejournal.com/138364.html CMake: The Cross Platform Build System]<br />
* [http://www.elpauer.org/stuff/learning_cmake.pdf "Learning CMake"] - Slides of a CMake workshop, including CPack, CTest and CDash<br />
* [https://github.com/TheErk/CMake-tutorial CMake tutorial] - Slides (with LaTeX bearmer source) of a CMake tutorial including CPack, CTest.<br />
* [http://www.visgraf.impa.br/seminar/slides/rodlima_cmake_presentation.pdf "CMake: Behind the Scenes of Code Development"] - Slides of an introductory talk/tutorial about CMake and its benefits<br />
* [http://snikt.net/index.php/2010/04/01/howto-use-cmake-with-cc-projects Howto use cmake with C/C++ projects] A simple walk-through about creating a cmake C project including integration of subversion, doxygen and how-to add optional project parts as configurables<br />
* [http://hackerwithin.org/thw/plugin_wiki/page/buildsystems The Hacker Within: Build Systems] Explains why and how to use build systems with a CMake example.<br />
* Syntax of the CMake language<br />
** [http://www.cmake.org/HTML/syntax.html A quick introduction to CMake syntax]<br />
** [[CMake/Language Syntax | Language syntax]] (wiki page)<br />
** [[CMake:VariablesListsStrings| On variables, lists, strings, maps, regexps, etc.]]<br />
* How CMake simplifies the build process by Bruno Abinader<br />
** [http://www.abinader.com.br/bruno/how-cmake-simplifies-the-build-process-part-1-basic-build-system/ Part 1 - Basic build system]<br />
** [http://web.archive.org/web/20101030232202/http://cabledogs.org/abinader/2009/12/09/how-cmake-simplifies-the-build-process-part-2-advanced-build-system/ Part 2 - Advanced build system]<br />
* [http://rachid.koucha.free.fr/tech_corner/cmake_manual.html Empirical approach to CMAKE] by Rachid Koucha<br />
<br />
===Finding stuff and platform checking===<br />
<br />
* [[CMake HowToDoPlatformChecks| How to write platform checks with CMake]]<br>Describes how to implement platform or configure checks with CMake.<br />
<br />
* [[CMake/Tutorials#CMake_Packages|How to package your project for use by others]], create FooConfig.cmake files, and exporting and importing targets.<br />
<br />
* [[CMake:How_To_Find_Libraries | How to find libraries]] <br>Describes how to use external libraries in a CMake project and how to write your own find modules for libraries that don't already have one.<br />
<br />
* [[CMake:HowToUseExistingOSXFrameworks | How to find and use existing frameworks on OS X]]<br> A quick example to help OS X users find frameworks automatically.<br />
<br />
===How to use CMake with specific Libraries ===<br />
<br />
* [[CMake:How To Build Qt4 Software | How to build Qt4 software with CMake]]<br />
<br />
* [http://qtnode.net/wiki?title=Qt_with_cmake Qt with CMake] <br>Explains how to use CMake to build software with Qt4, Qt3 and KDE3.<br />
<br />
* [http://mikemcquaid.com/2012/01/deploying-qt-applications-with-deployqt4/ Deploying Qt4 applications with CMake] <br>Explains how to use the DeployQt4.cmake module coming with CMake 2.8.7.<br />
<br />
* [[CMake:How To Build KDE4 Software | How to build KDE4 software with CMake]]<br />
<br />
* [[CMake:MatlabMex | How to use CMake to create Matlab MEX files]] <br> Describes how to use CMake when developing Matlab Executable (MEX) files for use with The Mathworks Matlab scripting language.<br />
<br />
* [http://www.wxwidgets.org/wiki/index.php/CMake How to use CMake for building software with wxWidgets ]<br />
<br />
* [http://www.linuxdevices.com/articles/AT6762290643.html Building eCos applications with CMake]<br />
<br />
* [http://www.smslana.eu Building Sms applications with CMake]<br />
<br />
* [http://blog.quickforge.co.uk/2011/10/exploration-of-cross-compiling-on-windows-for-arm-linux-distributions/ Cross compiling from Windows to ARM Linux]<br />
<br />
* [[CMakeForFLTK| Using CMake to build an FLTK application]]<br />
<br />
===Recipes===<br />
<br />
* [[CMake:How To Process Lots Of Input Files | How to process lots of input files with a processor built by CMake]]<br />
<br />
* [[BuildingWinDLL| How to export symbols from a Windows DLL for the non-Windows Developer]]<br />
<br />
* [[VSConfigSpecificSettings| Configuration Specific Settings for Visual Studio Generated Project Files]]<br />
<br />
* [[BundleUtilitiesExample| How to use the 'BundleUtilities' to deploy your OS X Application. Example uses Qt 4.]]<br />
<br />
* [[CMakeForFortranExample|How to write a simple CMakeLists.txt for Fortran code]]<br />
<br />
* [[CMakeEmulateMakeCheck|How to emulate GNU Autotools 'make check']]<br />
<br />
* [[CustomCommandCustomTargetInstall|A toy model for add_custom_command and add_custom_target]]<br />
<br />
* [[CMake:OSX_InterfaceBuilderFiles|Working with OS X Interface Builder Files]]<br />
<br />
* [[RecipeAppendVersionNumberToInstallpath|Append the Version Number to the Install path]]<br />
<br />
* [[RecipeInstallToALocalFolderForTesting|Install to a local folder in the build dir for testing]]<br />
<br />
* [[RecipeAddUninstallTarget|Adding an uninstall target to your project]]<br />
<br />
* [[RecipeAddSoVersionToDLLs|Appending the SO version to DLLs]]<br />
<br />
==Converters from other buildsystems to CMake==<br />
<br />
All converters listed here are not "complete", i.e. the generated CMake files are not 100% finished, in all cases some work is left for the developer.<br />
<br />
====automake/autotools/autoconf====<br />
* [http://websvn.kde.org/trunk/KDE/kdesdk/cmake/scripts/ am2cmake (requires Ruby) ] Converts automake/autotools/libtool based projects to CMake, specialized in converting from KDE 3 to KDE 4, should also work for others. This one has been used for converting the KDE buildsystem to CMake.<br />
<br />
* [http://emanuelgreisen.dk/stuff/kdevelop_am2cmake.php.tgz Alternative Automake2CMake (requires PHP)] Converts KDevelop projects that use automake to CMake.<br />
<br />
* [[GccXmlAutoConfHints|Converting autoconf tests]]<br />
<br />
====qmake====<br />
* [[CMake:ConvertFromQmake | qmake converter (requires Ruby)]] Converts projects that use Qt's qmake.<br />
<br />
====Visual Studio====<br />
* [http://vcproj2cmake.sf.net vcproj2cmake.rb (requires Ruby) SourceForge project] Creates '''and maintains''' CMakeLists.txt files by extracting info from Visual Studio project files. Elaborate script for development side-by-side the updated original static .vcproj files, supports script hooks and powerful definition mappings. Patches and new project members very welcome. Older script versions below:<br />
** [http://www.eskilson.se/vcproj2cmake.rb Original vcproj2cmake.rb version (requires Ruby)] <br />
** Slightly newer version here [http://dgwarp.hd.free.fr/vcproj2cmake.rb vcproj2cmake.rb], see:[[User_talk:Dweeves]] for details<br />
* [http://nberserk.blogspot.com/2010/11/converting-vc-projectsvcproj-to.html vcproj2cmake.ps1(PowerShell version)] Creates CMakeLists.txt. it supports vcproj configuration and detect 'exclude from build' option<br />
* [http://sourceforge.net/projects/folders4cmake/ folders4cmake (requires Java)] Use Visual Studio project files to generate corresponding "source_group" information that you can use inside your own CMake scripts. Supports Visual Studio 9/10 project files (full round-trip possible).<br />
<br />
====Basic CMakeLists.txt from-scratch-generator====<br />
* [http://websvn.kde.org/trunk/KDE/kdesdk/cmake/scripts/ gencmake (requires Ruby) ] Creates basic CMakeLists.txt files from looking at the existing files.<br />
* [http://www.vanvelzensoftware.com/postnuke/index.php?name=Downloads&req=viewdownload&cid=7 CMakeListGenerator (Win32) ] Creates complete CMakeLists.txt files as described in the [https://gucef.svn.sourceforge.net/svnroot/gucef/trunk/tools/CMakeListGenerator/docs/README.txt README ] using a combination of file and directory structure analysis. Supports resolving dependencies between multiple archives.<br />
<br />
==Success Stories==<br />
<br />
* What are some [[CMake Projects|projects using CMake]]?<br />
* [[CMake:Articles|Articles about CMake]]<br />
* [[Really Cool CMake Features]]<br />
<br />
<br />
==More Topics==<br />
<br />
* [[CMake Fortran Issues|Fortran Issues]]<br />
* [[CMake:For CMake Hackers|Generating dependency graphs with CMake]]<br />
* [[CMake:Experiments With Lua|Experiments With Lua]]<br />
* [[CMake Performance Tips|Performance Tips]]<br />
* [[CMake:Install Commands| Replacing deprecated INSTALL_FILES, INSTALL_PROGRAMS and INSTALL_TARGETS commands]]<br />
* [[CMake:GNU style example | GNU style directory layout with CMake]]<br />
* [[CMake:OpenTasks| CMake TODO]]<br />
* [[CMake:CreateQtAssistantDocs| Creating Qt Assistant Docs]]<br />
* [[CMake:Static libraries| Writing FindXXX.cmake modules that work with static libraries]]<br />
* [[CMake:Multiple versions| Writing FindXXX.cmake modules that work when multiple versions of packages are installed]]<br />
* [[CMake:Improving Find* Modules ]]<br />
* [[/C Plugins for Loadable Commands/]]<br>For anyone who wonders what the <tt>load_command</tt> command is for.<br />
* [[PC-Lint]] support for CMake<br />
<br />
=CTest=<br />
<br />
===Tutorials===<br />
* [[CMake Testing With CTest|Testing With CTest]]<br>Introduces to testing with CTest, submitting dashboards, and using CMake to add tests to the test system.<br />
<br />
* [[CMake Scripting Of CTest|CTest Scripting]]<br>Describes the scripting with CTest which can significantly simplify and automate testing and submitting dashboards.<br />
<br />
* [[CMake Generating Testing Files|Generating Input Files For CTest]]<br>Describe more in details the concepts behind testing with CTest and also explans how to use CTest without using CMake.<br />
<br />
* [[CTest:Buildserver|Buildmanagement With CTest]]<br>Describes how to setup a central configuration for all CTest scripts.<br />
<br />
===More Information===<br />
* [[CTest:Submission Issues|Configuring CTest Submission Methods]]<br />
* [[CTest:Nightly, Experimental, Continuous|CTest Nightly, Experimental, Continuous, ...]]<br />
* [[CTest:Coverage]]<br />
* [[Media:CTest Running Modes.pdf]]<br />
* [[CTest:FAQ|CTest Frequently asked questions]]<br />
<br />
===More Topics===<br />
* [[CTest:OpenTasks| CTest TODO]]<br />
* [[CTest:TestWithoutBuild| Run tests on machines without building first]]<br />
<br />
=CDash=<br />
* [http://public.kitware.com/Wiki/CDash CDash Wiki].<br />
* [http://public.kitware.com/Wiki/CDash:FAQ CDash FAQ].<br />
<br />
<br />
=CPack=<br />
===Tutorials===<br />
* [[CMake:Packaging With CPack|Packaging with CPack]]<br>Introduction to CPack, installing and packaging of software.<br />
* [https://github.com/TheErk/CMake-tutorial CMake tutorial] - Slides from a CMake tutorial (including LaTeX beamer source) including CPack.<br />
* [[CMake:CPackConfiguration|CPack Variables]]<br><br />
* [[CMake:CPackPackageGenerators|Supported package formats]]<br><br />
* [[CMake:CPackWin32NewbiesChecklist|CPack Win32 Newbie Checklist]] <br><br />
* [[CMake:Component_Install_With_CPack|Component Install With CPack]] <br><br />
<br />
===Recipes===<br />
<br />
* [[RecipeAddShortcutToStartMenu|Add an application shortcut to the Start Menu]]<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake&diff=47319CMake2012-05-31T07:28:00Z<p>Erk: /* Basic Introductions */</p>
<hr />
<div>http://www.cmake.org/cmake/img/CMake-logo-download.jpg<br />
<br />
<!-- documentation manual man information help tutorial --><br />
Welcome to CMake, the cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform and compiler independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. CMake is quite sophisticated: it is possible to support complex environments requiring system configuration, pre-processor generation, code generation, and template instantiation.<br />
<br />
You will find here not only documentation for CMake, but also for CPack and CTest.<br />
<br />
=CMake=<br />
<br />
==Primary Resources - Look here first! ==<br />
* Where can I [http://www.cmake.org/HTML/Download.html download CMake]?<br />
* [http://www.cmake.org/HTML/Documentation.html CMake Documentation]<br />
* [[CMake Useful Variables|Useful CMake Variables]]<br />
* [[CMake FAQ| FAQ (Frequently asked questions)]]<br />
* [http://www.cmake.org/mailman/listinfo/cmake CMake Mailing List] (for searchable archives see [[CMake_FAQ#Where_can_I_find_searchable_CMake_Mailing_Archives | CMake FAQ ]])<br />
* [[CMake_2.6_Notes|CMake 2.6 Notes]]<br />
* ''Getting Started With CMake'' Screencasts @[http://playcontrol.net/ewing/screencasts/getting_started_with_cmake_.html PlayControl.net]<br />
<br />
==Development Topics==<br />
* [[CMake Cross Compiling| Cross compiling]]<br />
* [[CMake RPATH handling|RPATH handling]]<br />
* [[CMake/Assembler|Assembler Support]]<br />
* [[CMake Editors Support|Editors/IDEs with CMake syntax support]]<br />
* [[CMake Generator Specific Information|Docs for Specific Project Generators]] (Eclipse, KDevelop3, CodeBlocks, Makefile)<br />
* [[CMake User Contributed Macros| Contributed macros]]<br />
* [[CMake:Module Maintainers|Module Maintainers]]<br />
* [[CMake Platform Dependent Issues|Platform Dependent Information]]<br />
* [[CMake Released Versions|Documentation for previous releases]]<br />
* [[CMake Version Compatibility Matrix|Matrix for checking backwards-compatibility of current features]]<br />
<br />
==Tutorials==<br />
<br />
===Basic Introductions===<br />
* [http://www.cmake.org/HTML/Examples.html A Simple CMake Example]<br />
* [http://www.linuxjournal.com/article/6700 Cross-Platform Software Development Using CMake]<br />
* [http://clubjuggler.livejournal.com/138364.html CMake: The Cross Platform Build System]<br />
* [http://www.elpauer.org/stuff/learning_cmake.pdf "Learning CMake"] - Slides of a CMake workshop, including CPack, CTest and CDash<br />
* [https://github.com/TheErk/CMake-tutorial CMake tutorial] - Slides (with LaTeX bearmer source) of a CMake tutorial including CPack, CTest.<br />
* [http://www.visgraf.impa.br/seminar/slides/rodlima_cmake_presentation.pdf "CMake: Behind the Scenes of Code Development"] - Slides of an introductory talk/tutorial about CMake and its benefits<br />
* [http://snikt.net/index.php/2010/04/01/howto-use-cmake-with-cc-projects Howto use cmake with C/C++ projects] A simple walk-through about creating a cmake C project including integration of subversion, doxygen and how-to add optional project parts as configurables<br />
* [http://hackerwithin.org/thw/plugin_wiki/page/buildsystems The Hacker Within: Build Systems] Explains why and how to use build systems with a CMake example.<br />
* Syntax of the CMake language<br />
** [http://www.cmake.org/HTML/syntax.html A quick introduction to CMake syntax]<br />
** [[CMake/Language Syntax | Language syntax]] (wiki page)<br />
** [[CMake:VariablesListsStrings| On variables, lists, strings, maps, regexps, etc.]]<br />
* How CMake simplifies the build process by Bruno Abinader<br />
** [http://www.abinader.com.br/bruno/how-cmake-simplifies-the-build-process-part-1-basic-build-system/ Part 1 - Basic build system]<br />
** [http://web.archive.org/web/20101030232202/http://cabledogs.org/abinader/2009/12/09/how-cmake-simplifies-the-build-process-part-2-advanced-build-system/ Part 2 - Advanced build system]<br />
* [http://rachid.koucha.free.fr/tech_corner/cmake_manual.html Empirical approach to CMAKE] by Rachid Koucha<br />
<br />
===Finding stuff and platform checking===<br />
<br />
* [[CMake HowToDoPlatformChecks| How to write platform checks with CMake]]<br>Describes how to implement platform or configure checks with CMake.<br />
<br />
* [[CMake/Tutorials#CMake_Packages|How to package your project for use by others]], create FooConfig.cmake files, and exporting and importing targets.<br />
<br />
* [[CMake:How_To_Find_Libraries | How to find libraries]] <br>Describes how to use external libraries in a CMake project and how to write your own find modules for libraries that don't already have one.<br />
<br />
* [[CMake:HowToUseExistingOSXFrameworks | How to find and use existing frameworks on OS X]]<br> A quick example to help OS X users find frameworks automatically.<br />
<br />
===How to use CMake with specific Libraries ===<br />
<br />
* [[CMake:How To Build Qt4 Software | How to build Qt4 software with CMake]]<br />
<br />
* [http://qtnode.net/wiki?title=Qt_with_cmake Qt with CMake] <br>Explains how to use CMake to build software with Qt4, Qt3 and KDE3.<br />
<br />
* [http://mikemcquaid.com/2012/01/deploying-qt-applications-with-deployqt4/ Deploying Qt4 applications with CMake] <br>Explains how to use the DeployQt4.cmake module coming with CMake 2.8.7.<br />
<br />
* [[CMake:How To Build KDE4 Software | How to build KDE4 software with CMake]]<br />
<br />
* [[CMake:MatlabMex | How to use CMake to create Matlab MEX files]] <br> Describes how to use CMake when developing Matlab Executable (MEX) files for use with The Mathworks Matlab scripting language.<br />
<br />
* [http://www.wxwidgets.org/wiki/index.php/CMake How to use CMake for building software with wxWidgets ]<br />
<br />
* [http://www.linuxdevices.com/articles/AT6762290643.html Building eCos applications with CMake]<br />
<br />
* [http://www.smslana.eu Building Sms applications with CMake]<br />
<br />
* [http://blog.quickforge.co.uk/2011/10/exploration-of-cross-compiling-on-windows-for-arm-linux-distributions/ Cross compiling from Windows to ARM Linux]<br />
<br />
* [[CMakeForFLTK| Using CMake to build an FLTK application]]<br />
<br />
===Recipes===<br />
<br />
* [[CMake:How To Process Lots Of Input Files | How to process lots of input files with a processor built by CMake]]<br />
<br />
* [[BuildingWinDLL| How to export symbols from a Windows DLL for the non-Windows Developer]]<br />
<br />
* [[VSConfigSpecificSettings| Configuration Specific Settings for Visual Studio Generated Project Files]]<br />
<br />
* [[BundleUtilitiesExample| How to use the 'BundleUtilities' to deploy your OS X Application. Example uses Qt 4.]]<br />
<br />
* [[CMakeForFortranExample|How to write a simple CMakeLists.txt for Fortran code]]<br />
<br />
* [[CMakeEmulateMakeCheck|How to emulate GNU Autotools 'make check']]<br />
<br />
* [[CustomCommandCustomTargetInstall|A toy model for add_custom_command and add_custom_target]]<br />
<br />
* [[CMake:OSX_InterfaceBuilderFiles|Working with OS X Interface Builder Files]]<br />
<br />
* [[RecipeAppendVersionNumberToInstallpath|Append the Version Number to the Install path]]<br />
<br />
* [[RecipeInstallToALocalFolderForTesting|Install to a local folder in the build dir for testing]]<br />
<br />
* [[RecipeAddUninstallTarget|Adding an uninstall target to your project]]<br />
<br />
* [[RecipeAddSoVersionToDLLs|Appending the SO version to DLLs]]<br />
<br />
==Converters from other buildsystems to CMake==<br />
<br />
All converters listed here are not "complete", i.e. the generated CMake files are not 100% finished, in all cases some work is left for the developer.<br />
<br />
====automake/autotools/autoconf====<br />
* [http://websvn.kde.org/trunk/KDE/kdesdk/cmake/scripts/ am2cmake (requires Ruby) ] Converts automake/autotools/libtool based projects to CMake, specialized in converting from KDE 3 to KDE 4, should also work for others. This one has been used for converting the KDE buildsystem to CMake.<br />
<br />
* [http://emanuelgreisen.dk/stuff/kdevelop_am2cmake.php.tgz Alternative Automake2CMake (requires PHP)] Converts KDevelop projects that use automake to CMake.<br />
<br />
* [[GccXmlAutoConfHints|Converting autoconf tests]]<br />
<br />
====qmake====<br />
* [[CMake:ConvertFromQmake | qmake converter (requires Ruby)]] Converts projects that use Qt's qmake.<br />
<br />
====Visual Studio====<br />
* [http://vcproj2cmake.sf.net vcproj2cmake.rb (requires Ruby) SourceForge project] Creates '''and maintains''' CMakeLists.txt files by extracting info from Visual Studio project files. Elaborate script for development side-by-side the updated original static .vcproj files, supports script hooks and powerful definition mappings. Patches and new project members very welcome. Older script versions below:<br />
** [http://www.eskilson.se/vcproj2cmake.rb Original vcproj2cmake.rb version (requires Ruby)] <br />
** Slightly newer version here [http://dgwarp.hd.free.fr/vcproj2cmake.rb vcproj2cmake.rb], see:[[User_talk:Dweeves]] for details<br />
* [http://nberserk.blogspot.com/2010/11/converting-vc-projectsvcproj-to.html vcproj2cmake.ps1(PowerShell version)] Creates CMakeLists.txt. it supports vcproj configuration and detect 'exclude from build' option<br />
* [http://sourceforge.net/projects/folders4cmake/ folders4cmake (requires Java)] Use Visual Studio project files to generate corresponding "source_group" information that you can use inside your own CMake scripts. Supports Visual Studio 9/10 project files (full round-trip possible).<br />
<br />
====Basic CMakeLists.txt from-scratch-generator====<br />
* [http://websvn.kde.org/trunk/KDE/kdesdk/cmake/scripts/ gencmake (requires Ruby) ] Creates basic CMakeLists.txt files from looking at the existing files.<br />
* [http://www.vanvelzensoftware.com/postnuke/index.php?name=Downloads&req=viewdownload&cid=7 CMakeListGenerator (Win32) ] Creates complete CMakeLists.txt files as described in the [https://gucef.svn.sourceforge.net/svnroot/gucef/trunk/tools/CMakeListGenerator/docs/README.txt README ] using a combination of file and directory structure analysis. Supports resolving dependencies between multiple archives.<br />
<br />
==Success Stories==<br />
<br />
* What are some [[CMake Projects|projects using CMake]]?<br />
* [[CMake:Articles|Articles about CMake]]<br />
* [[Really Cool CMake Features]]<br />
<br />
<br />
==More Topics==<br />
<br />
* [[CMake Fortran Issues|Fortran Issues]]<br />
* [[CMake:For CMake Hackers|Generating dependency graphs with CMake]]<br />
* [[CMake:Experiments With Lua|Experiments With Lua]]<br />
* [[CMake Performance Tips|Performance Tips]]<br />
* [[CMake:Install Commands| Replacing deprecated INSTALL_FILES, INSTALL_PROGRAMS and INSTALL_TARGETS commands]]<br />
* [[CMake:GNU style example | GNU style directory layout with CMake]]<br />
* [[CMake:OpenTasks| CMake TODO]]<br />
* [[CMake:CreateQtAssistantDocs| Creating Qt Assistant Docs]]<br />
* [[CMake:Static libraries| Writing FindXXX.cmake modules that work with static libraries]]<br />
* [[CMake:Multiple versions| Writing FindXXX.cmake modules that work when multiple versions of packages are installed]]<br />
* [[CMake:Improving Find* Modules ]]<br />
* [[/C Plugins for Loadable Commands/]]<br>For anyone who wonders what the <tt>load_command</tt> command is for.<br />
* [[PC-Lint]] support for CMake<br />
<br />
=CTest=<br />
<br />
===Tutorials===<br />
* [[CMake Testing With CTest|Testing With CTest]]<br>Introduces to testing with CTest, submitting dashboards, and using CMake to add tests to the test system.<br />
<br />
* [[CMake Scripting Of CTest|CTest Scripting]]<br>Describes the scripting with CTest which can significantly simplify and automate testing and submitting dashboards.<br />
<br />
* [[CMake Generating Testing Files|Generating Input Files For CTest]]<br>Describe more in details the concepts behind testing with CTest and also explans how to use CTest without using CMake.<br />
<br />
* [[CTest:Buildserver|Buildmanagement With CTest]]<br>Describes how to setup a central configuration for all CTest scripts.<br />
<br />
===More Information===<br />
* [[CTest:Submission Issues|Configuring CTest Submission Methods]]<br />
* [[CTest:Nightly, Experimental, Continuous|CTest Nightly, Experimental, Continuous, ...]]<br />
* [[CTest:Coverage]]<br />
* [[Media:CTest Running Modes.pdf]]<br />
* [[CTest:FAQ|CTest Frequently asked questions]]<br />
<br />
===More Topics===<br />
* [[CTest:OpenTasks| CTest TODO]]<br />
* [[CTest:TestWithoutBuild| Run tests on machines without building first]]<br />
<br />
=CDash=<br />
* [http://public.kitware.com/Wiki/CDash CDash Wiki].<br />
* [http://public.kitware.com/Wiki/CDash:FAQ CDash FAQ].<br />
<br />
<br />
=CPack=<br />
===Tutorials===<br />
* [[CMake:Packaging With CPack|Packaging with CPack]]<br>Introduction to CPack, installing and packaging of software.<br />
* [[https://github.com/TheErk/CMake-tutorial | "CMake tutorial]] - Slides from a CMake tutorial (including LaTeX beamer source) including CPack.<br />
* [[CMake:CPackConfiguration|CPack Variables]]<br><br />
* [[CMake:CPackPackageGenerators|Supported package formats]]<br><br />
* [[CMake:CPackWin32NewbiesChecklist|CPack Win32 Newbie Checklist]] <br><br />
* [[CMake:Component_Install_With_CPack|Component Install With CPack]] <br><br />
<br />
===Recipes===<br />
<br />
* [[RecipeAddShortcutToStartMenu|Add an application shortcut to the Start Menu]]<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake&diff=47318CMake2012-05-31T07:27:18Z<p>Erk: /* Tutorials */</p>
<hr />
<div>http://www.cmake.org/cmake/img/CMake-logo-download.jpg<br />
<br />
<!-- documentation manual man information help tutorial --><br />
Welcome to CMake, the cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform and compiler independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. CMake is quite sophisticated: it is possible to support complex environments requiring system configuration, pre-processor generation, code generation, and template instantiation.<br />
<br />
You will find here not only documentation for CMake, but also for CPack and CTest.<br />
<br />
=CMake=<br />
<br />
==Primary Resources - Look here first! ==<br />
* Where can I [http://www.cmake.org/HTML/Download.html download CMake]?<br />
* [http://www.cmake.org/HTML/Documentation.html CMake Documentation]<br />
* [[CMake Useful Variables|Useful CMake Variables]]<br />
* [[CMake FAQ| FAQ (Frequently asked questions)]]<br />
* [http://www.cmake.org/mailman/listinfo/cmake CMake Mailing List] (for searchable archives see [[CMake_FAQ#Where_can_I_find_searchable_CMake_Mailing_Archives | CMake FAQ ]])<br />
* [[CMake_2.6_Notes|CMake 2.6 Notes]]<br />
* ''Getting Started With CMake'' Screencasts @[http://playcontrol.net/ewing/screencasts/getting_started_with_cmake_.html PlayControl.net]<br />
<br />
==Development Topics==<br />
* [[CMake Cross Compiling| Cross compiling]]<br />
* [[CMake RPATH handling|RPATH handling]]<br />
* [[CMake/Assembler|Assembler Support]]<br />
* [[CMake Editors Support|Editors/IDEs with CMake syntax support]]<br />
* [[CMake Generator Specific Information|Docs for Specific Project Generators]] (Eclipse, KDevelop3, CodeBlocks, Makefile)<br />
* [[CMake User Contributed Macros| Contributed macros]]<br />
* [[CMake:Module Maintainers|Module Maintainers]]<br />
* [[CMake Platform Dependent Issues|Platform Dependent Information]]<br />
* [[CMake Released Versions|Documentation for previous releases]]<br />
* [[CMake Version Compatibility Matrix|Matrix for checking backwards-compatibility of current features]]<br />
<br />
==Tutorials==<br />
<br />
===Basic Introductions===<br />
* [http://www.cmake.org/HTML/Examples.html A Simple CMake Example]<br />
* [http://www.linuxjournal.com/article/6700 Cross-Platform Software Development Using CMake]<br />
* [http://clubjuggler.livejournal.com/138364.html CMake: The Cross Platform Build System]<br />
* [http://www.elpauer.org/stuff/learning_cmake.pdf "Learning CMake"] - Slides of a CMake workshop, including CPack, CTest and CDash<br />
* [https://github.com/TheErk/CMake-tutorial "CMake tutorial"] - Slides (with LaTeX bearmer source) of a CMake tutorial including CPack, CTest.<br />
* [http://www.visgraf.impa.br/seminar/slides/rodlima_cmake_presentation.pdf "CMake: Behind the Scenes of Code Development"] - Slides of an introductory talk/tutorial about CMake and its benefits<br />
* [http://snikt.net/index.php/2010/04/01/howto-use-cmake-with-cc-projects Howto use cmake with C/C++ projects] A simple walk-through about creating a cmake C project including integration of subversion, doxygen and how-to add optional project parts as configurables<br />
* [http://hackerwithin.org/thw/plugin_wiki/page/buildsystems The Hacker Within: Build Systems] Explains why and how to use build systems with a CMake example.<br />
* Syntax of the CMake language<br />
** [http://www.cmake.org/HTML/syntax.html A quick introduction to CMake syntax]<br />
** [[CMake/Language Syntax | Language syntax]] (wiki page)<br />
** [[CMake:VariablesListsStrings| On variables, lists, strings, maps, regexps, etc.]]<br />
* How CMake simplifies the build process by Bruno Abinader<br />
** [http://www.abinader.com.br/bruno/how-cmake-simplifies-the-build-process-part-1-basic-build-system/ Part 1 - Basic build system]<br />
** [http://web.archive.org/web/20101030232202/http://cabledogs.org/abinader/2009/12/09/how-cmake-simplifies-the-build-process-part-2-advanced-build-system/ Part 2 - Advanced build system]<br />
* [http://rachid.koucha.free.fr/tech_corner/cmake_manual.html Empirical approach to CMAKE] by Rachid Koucha<br />
<br />
===Finding stuff and platform checking===<br />
<br />
* [[CMake HowToDoPlatformChecks| How to write platform checks with CMake]]<br>Describes how to implement platform or configure checks with CMake.<br />
<br />
* [[CMake/Tutorials#CMake_Packages|How to package your project for use by others]], create FooConfig.cmake files, and exporting and importing targets.<br />
<br />
* [[CMake:How_To_Find_Libraries | How to find libraries]] <br>Describes how to use external libraries in a CMake project and how to write your own find modules for libraries that don't already have one.<br />
<br />
* [[CMake:HowToUseExistingOSXFrameworks | How to find and use existing frameworks on OS X]]<br> A quick example to help OS X users find frameworks automatically.<br />
<br />
===How to use CMake with specific Libraries ===<br />
<br />
* [[CMake:How To Build Qt4 Software | How to build Qt4 software with CMake]]<br />
<br />
* [http://qtnode.net/wiki?title=Qt_with_cmake Qt with CMake] <br>Explains how to use CMake to build software with Qt4, Qt3 and KDE3.<br />
<br />
* [http://mikemcquaid.com/2012/01/deploying-qt-applications-with-deployqt4/ Deploying Qt4 applications with CMake] <br>Explains how to use the DeployQt4.cmake module coming with CMake 2.8.7.<br />
<br />
* [[CMake:How To Build KDE4 Software | How to build KDE4 software with CMake]]<br />
<br />
* [[CMake:MatlabMex | How to use CMake to create Matlab MEX files]] <br> Describes how to use CMake when developing Matlab Executable (MEX) files for use with The Mathworks Matlab scripting language.<br />
<br />
* [http://www.wxwidgets.org/wiki/index.php/CMake How to use CMake for building software with wxWidgets ]<br />
<br />
* [http://www.linuxdevices.com/articles/AT6762290643.html Building eCos applications with CMake]<br />
<br />
* [http://www.smslana.eu Building Sms applications with CMake]<br />
<br />
* [http://blog.quickforge.co.uk/2011/10/exploration-of-cross-compiling-on-windows-for-arm-linux-distributions/ Cross compiling from Windows to ARM Linux]<br />
<br />
* [[CMakeForFLTK| Using CMake to build an FLTK application]]<br />
<br />
===Recipes===<br />
<br />
* [[CMake:How To Process Lots Of Input Files | How to process lots of input files with a processor built by CMake]]<br />
<br />
* [[BuildingWinDLL| How to export symbols from a Windows DLL for the non-Windows Developer]]<br />
<br />
* [[VSConfigSpecificSettings| Configuration Specific Settings for Visual Studio Generated Project Files]]<br />
<br />
* [[BundleUtilitiesExample| How to use the 'BundleUtilities' to deploy your OS X Application. Example uses Qt 4.]]<br />
<br />
* [[CMakeForFortranExample|How to write a simple CMakeLists.txt for Fortran code]]<br />
<br />
* [[CMakeEmulateMakeCheck|How to emulate GNU Autotools 'make check']]<br />
<br />
* [[CustomCommandCustomTargetInstall|A toy model for add_custom_command and add_custom_target]]<br />
<br />
* [[CMake:OSX_InterfaceBuilderFiles|Working with OS X Interface Builder Files]]<br />
<br />
* [[RecipeAppendVersionNumberToInstallpath|Append the Version Number to the Install path]]<br />
<br />
* [[RecipeInstallToALocalFolderForTesting|Install to a local folder in the build dir for testing]]<br />
<br />
* [[RecipeAddUninstallTarget|Adding an uninstall target to your project]]<br />
<br />
* [[RecipeAddSoVersionToDLLs|Appending the SO version to DLLs]]<br />
<br />
==Converters from other buildsystems to CMake==<br />
<br />
All converters listed here are not "complete", i.e. the generated CMake files are not 100% finished, in all cases some work is left for the developer.<br />
<br />
====automake/autotools/autoconf====<br />
* [http://websvn.kde.org/trunk/KDE/kdesdk/cmake/scripts/ am2cmake (requires Ruby) ] Converts automake/autotools/libtool based projects to CMake, specialized in converting from KDE 3 to KDE 4, should also work for others. This one has been used for converting the KDE buildsystem to CMake.<br />
<br />
* [http://emanuelgreisen.dk/stuff/kdevelop_am2cmake.php.tgz Alternative Automake2CMake (requires PHP)] Converts KDevelop projects that use automake to CMake.<br />
<br />
* [[GccXmlAutoConfHints|Converting autoconf tests]]<br />
<br />
====qmake====<br />
* [[CMake:ConvertFromQmake | qmake converter (requires Ruby)]] Converts projects that use Qt's qmake.<br />
<br />
====Visual Studio====<br />
* [http://vcproj2cmake.sf.net vcproj2cmake.rb (requires Ruby) SourceForge project] Creates '''and maintains''' CMakeLists.txt files by extracting info from Visual Studio project files. Elaborate script for development side-by-side the updated original static .vcproj files, supports script hooks and powerful definition mappings. Patches and new project members very welcome. Older script versions below:<br />
** [http://www.eskilson.se/vcproj2cmake.rb Original vcproj2cmake.rb version (requires Ruby)] <br />
** Slightly newer version here [http://dgwarp.hd.free.fr/vcproj2cmake.rb vcproj2cmake.rb], see:[[User_talk:Dweeves]] for details<br />
* [http://nberserk.blogspot.com/2010/11/converting-vc-projectsvcproj-to.html vcproj2cmake.ps1(PowerShell version)] Creates CMakeLists.txt. it supports vcproj configuration and detect 'exclude from build' option<br />
* [http://sourceforge.net/projects/folders4cmake/ folders4cmake (requires Java)] Use Visual Studio project files to generate corresponding "source_group" information that you can use inside your own CMake scripts. Supports Visual Studio 9/10 project files (full round-trip possible).<br />
<br />
====Basic CMakeLists.txt from-scratch-generator====<br />
* [http://websvn.kde.org/trunk/KDE/kdesdk/cmake/scripts/ gencmake (requires Ruby) ] Creates basic CMakeLists.txt files from looking at the existing files.<br />
* [http://www.vanvelzensoftware.com/postnuke/index.php?name=Downloads&req=viewdownload&cid=7 CMakeListGenerator (Win32) ] Creates complete CMakeLists.txt files as described in the [https://gucef.svn.sourceforge.net/svnroot/gucef/trunk/tools/CMakeListGenerator/docs/README.txt README ] using a combination of file and directory structure analysis. Supports resolving dependencies between multiple archives.<br />
<br />
==Success Stories==<br />
<br />
* What are some [[CMake Projects|projects using CMake]]?<br />
* [[CMake:Articles|Articles about CMake]]<br />
* [[Really Cool CMake Features]]<br />
<br />
<br />
==More Topics==<br />
<br />
* [[CMake Fortran Issues|Fortran Issues]]<br />
* [[CMake:For CMake Hackers|Generating dependency graphs with CMake]]<br />
* [[CMake:Experiments With Lua|Experiments With Lua]]<br />
* [[CMake Performance Tips|Performance Tips]]<br />
* [[CMake:Install Commands| Replacing deprecated INSTALL_FILES, INSTALL_PROGRAMS and INSTALL_TARGETS commands]]<br />
* [[CMake:GNU style example | GNU style directory layout with CMake]]<br />
* [[CMake:OpenTasks| CMake TODO]]<br />
* [[CMake:CreateQtAssistantDocs| Creating Qt Assistant Docs]]<br />
* [[CMake:Static libraries| Writing FindXXX.cmake modules that work with static libraries]]<br />
* [[CMake:Multiple versions| Writing FindXXX.cmake modules that work when multiple versions of packages are installed]]<br />
* [[CMake:Improving Find* Modules ]]<br />
* [[/C Plugins for Loadable Commands/]]<br>For anyone who wonders what the <tt>load_command</tt> command is for.<br />
* [[PC-Lint]] support for CMake<br />
<br />
=CTest=<br />
<br />
===Tutorials===<br />
* [[CMake Testing With CTest|Testing With CTest]]<br>Introduces to testing with CTest, submitting dashboards, and using CMake to add tests to the test system.<br />
<br />
* [[CMake Scripting Of CTest|CTest Scripting]]<br>Describes the scripting with CTest which can significantly simplify and automate testing and submitting dashboards.<br />
<br />
* [[CMake Generating Testing Files|Generating Input Files For CTest]]<br>Describe more in details the concepts behind testing with CTest and also explans how to use CTest without using CMake.<br />
<br />
* [[CTest:Buildserver|Buildmanagement With CTest]]<br>Describes how to setup a central configuration for all CTest scripts.<br />
<br />
===More Information===<br />
* [[CTest:Submission Issues|Configuring CTest Submission Methods]]<br />
* [[CTest:Nightly, Experimental, Continuous|CTest Nightly, Experimental, Continuous, ...]]<br />
* [[CTest:Coverage]]<br />
* [[Media:CTest Running Modes.pdf]]<br />
* [[CTest:FAQ|CTest Frequently asked questions]]<br />
<br />
===More Topics===<br />
* [[CTest:OpenTasks| CTest TODO]]<br />
* [[CTest:TestWithoutBuild| Run tests on machines without building first]]<br />
<br />
=CDash=<br />
* [http://public.kitware.com/Wiki/CDash CDash Wiki].<br />
* [http://public.kitware.com/Wiki/CDash:FAQ CDash FAQ].<br />
<br />
<br />
=CPack=<br />
===Tutorials===<br />
* [[CMake:Packaging With CPack|Packaging with CPack]]<br>Introduction to CPack, installing and packaging of software.<br />
* [[https://github.com/TheErk/CMake-tutorial | "CMake tutorial]] - Slides from a CMake tutorial (including LaTeX beamer source) including CPack.<br />
* [[CMake:CPackConfiguration|CPack Variables]]<br><br />
* [[CMake:CPackPackageGenerators|Supported package formats]]<br><br />
* [[CMake:CPackWin32NewbiesChecklist|CPack Win32 Newbie Checklist]] <br><br />
* [[CMake:Component_Install_With_CPack|Component Install With CPack]] <br><br />
<br />
===Recipes===<br />
<br />
* [[RecipeAddShortcutToStartMenu|Add an application shortcut to the Start Menu]]<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake&diff=47317CMake2012-05-31T07:24:37Z<p>Erk: /* Basic Introductions */</p>
<hr />
<div>http://www.cmake.org/cmake/img/CMake-logo-download.jpg<br />
<br />
<!-- documentation manual man information help tutorial --><br />
Welcome to CMake, the cross-platform, open-source make system. CMake is used to control the software compilation process using simple platform and compiler independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. CMake is quite sophisticated: it is possible to support complex environments requiring system configuration, pre-processor generation, code generation, and template instantiation.<br />
<br />
You will find here not only documentation for CMake, but also for CPack and CTest.<br />
<br />
=CMake=<br />
<br />
==Primary Resources - Look here first! ==<br />
* Where can I [http://www.cmake.org/HTML/Download.html download CMake]?<br />
* [http://www.cmake.org/HTML/Documentation.html CMake Documentation]<br />
* [[CMake Useful Variables|Useful CMake Variables]]<br />
* [[CMake FAQ| FAQ (Frequently asked questions)]]<br />
* [http://www.cmake.org/mailman/listinfo/cmake CMake Mailing List] (for searchable archives see [[CMake_FAQ#Where_can_I_find_searchable_CMake_Mailing_Archives | CMake FAQ ]])<br />
* [[CMake_2.6_Notes|CMake 2.6 Notes]]<br />
* ''Getting Started With CMake'' Screencasts @[http://playcontrol.net/ewing/screencasts/getting_started_with_cmake_.html PlayControl.net]<br />
<br />
==Development Topics==<br />
* [[CMake Cross Compiling| Cross compiling]]<br />
* [[CMake RPATH handling|RPATH handling]]<br />
* [[CMake/Assembler|Assembler Support]]<br />
* [[CMake Editors Support|Editors/IDEs with CMake syntax support]]<br />
* [[CMake Generator Specific Information|Docs for Specific Project Generators]] (Eclipse, KDevelop3, CodeBlocks, Makefile)<br />
* [[CMake User Contributed Macros| Contributed macros]]<br />
* [[CMake:Module Maintainers|Module Maintainers]]<br />
* [[CMake Platform Dependent Issues|Platform Dependent Information]]<br />
* [[CMake Released Versions|Documentation for previous releases]]<br />
* [[CMake Version Compatibility Matrix|Matrix for checking backwards-compatibility of current features]]<br />
<br />
==Tutorials==<br />
<br />
===Basic Introductions===<br />
* [http://www.cmake.org/HTML/Examples.html A Simple CMake Example]<br />
* [http://www.linuxjournal.com/article/6700 Cross-Platform Software Development Using CMake]<br />
* [http://clubjuggler.livejournal.com/138364.html CMake: The Cross Platform Build System]<br />
* [http://www.elpauer.org/stuff/learning_cmake.pdf "Learning CMake"] - Slides of a CMake workshop, including CPack, CTest and CDash<br />
* [https://github.com/TheErk/CMake-tutorial "CMake tutorial"] - Slides (with LaTeX bearmer source) of a CMake tutorial including CPack, CTest.<br />
* [http://www.visgraf.impa.br/seminar/slides/rodlima_cmake_presentation.pdf "CMake: Behind the Scenes of Code Development"] - Slides of an introductory talk/tutorial about CMake and its benefits<br />
* [http://snikt.net/index.php/2010/04/01/howto-use-cmake-with-cc-projects Howto use cmake with C/C++ projects] A simple walk-through about creating a cmake C project including integration of subversion, doxygen and how-to add optional project parts as configurables<br />
* [http://hackerwithin.org/thw/plugin_wiki/page/buildsystems The Hacker Within: Build Systems] Explains why and how to use build systems with a CMake example.<br />
* Syntax of the CMake language<br />
** [http://www.cmake.org/HTML/syntax.html A quick introduction to CMake syntax]<br />
** [[CMake/Language Syntax | Language syntax]] (wiki page)<br />
** [[CMake:VariablesListsStrings| On variables, lists, strings, maps, regexps, etc.]]<br />
* How CMake simplifies the build process by Bruno Abinader<br />
** [http://www.abinader.com.br/bruno/how-cmake-simplifies-the-build-process-part-1-basic-build-system/ Part 1 - Basic build system]<br />
** [http://web.archive.org/web/20101030232202/http://cabledogs.org/abinader/2009/12/09/how-cmake-simplifies-the-build-process-part-2-advanced-build-system/ Part 2 - Advanced build system]<br />
* [http://rachid.koucha.free.fr/tech_corner/cmake_manual.html Empirical approach to CMAKE] by Rachid Koucha<br />
<br />
===Finding stuff and platform checking===<br />
<br />
* [[CMake HowToDoPlatformChecks| How to write platform checks with CMake]]<br>Describes how to implement platform or configure checks with CMake.<br />
<br />
* [[CMake/Tutorials#CMake_Packages|How to package your project for use by others]], create FooConfig.cmake files, and exporting and importing targets.<br />
<br />
* [[CMake:How_To_Find_Libraries | How to find libraries]] <br>Describes how to use external libraries in a CMake project and how to write your own find modules for libraries that don't already have one.<br />
<br />
* [[CMake:HowToUseExistingOSXFrameworks | How to find and use existing frameworks on OS X]]<br> A quick example to help OS X users find frameworks automatically.<br />
<br />
===How to use CMake with specific Libraries ===<br />
<br />
* [[CMake:How To Build Qt4 Software | How to build Qt4 software with CMake]]<br />
<br />
* [http://qtnode.net/wiki?title=Qt_with_cmake Qt with CMake] <br>Explains how to use CMake to build software with Qt4, Qt3 and KDE3.<br />
<br />
* [http://mikemcquaid.com/2012/01/deploying-qt-applications-with-deployqt4/ Deploying Qt4 applications with CMake] <br>Explains how to use the DeployQt4.cmake module coming with CMake 2.8.7.<br />
<br />
* [[CMake:How To Build KDE4 Software | How to build KDE4 software with CMake]]<br />
<br />
* [[CMake:MatlabMex | How to use CMake to create Matlab MEX files]] <br> Describes how to use CMake when developing Matlab Executable (MEX) files for use with The Mathworks Matlab scripting language.<br />
<br />
* [http://www.wxwidgets.org/wiki/index.php/CMake How to use CMake for building software with wxWidgets ]<br />
<br />
* [http://www.linuxdevices.com/articles/AT6762290643.html Building eCos applications with CMake]<br />
<br />
* [http://www.smslana.eu Building Sms applications with CMake]<br />
<br />
* [http://blog.quickforge.co.uk/2011/10/exploration-of-cross-compiling-on-windows-for-arm-linux-distributions/ Cross compiling from Windows to ARM Linux]<br />
<br />
* [[CMakeForFLTK| Using CMake to build an FLTK application]]<br />
<br />
===Recipes===<br />
<br />
* [[CMake:How To Process Lots Of Input Files | How to process lots of input files with a processor built by CMake]]<br />
<br />
* [[BuildingWinDLL| How to export symbols from a Windows DLL for the non-Windows Developer]]<br />
<br />
* [[VSConfigSpecificSettings| Configuration Specific Settings for Visual Studio Generated Project Files]]<br />
<br />
* [[BundleUtilitiesExample| How to use the 'BundleUtilities' to deploy your OS X Application. Example uses Qt 4.]]<br />
<br />
* [[CMakeForFortranExample|How to write a simple CMakeLists.txt for Fortran code]]<br />
<br />
* [[CMakeEmulateMakeCheck|How to emulate GNU Autotools 'make check']]<br />
<br />
* [[CustomCommandCustomTargetInstall|A toy model for add_custom_command and add_custom_target]]<br />
<br />
* [[CMake:OSX_InterfaceBuilderFiles|Working with OS X Interface Builder Files]]<br />
<br />
* [[RecipeAppendVersionNumberToInstallpath|Append the Version Number to the Install path]]<br />
<br />
* [[RecipeInstallToALocalFolderForTesting|Install to a local folder in the build dir for testing]]<br />
<br />
* [[RecipeAddUninstallTarget|Adding an uninstall target to your project]]<br />
<br />
* [[RecipeAddSoVersionToDLLs|Appending the SO version to DLLs]]<br />
<br />
==Converters from other buildsystems to CMake==<br />
<br />
All converters listed here are not "complete", i.e. the generated CMake files are not 100% finished, in all cases some work is left for the developer.<br />
<br />
====automake/autotools/autoconf====<br />
* [http://websvn.kde.org/trunk/KDE/kdesdk/cmake/scripts/ am2cmake (requires Ruby) ] Converts automake/autotools/libtool based projects to CMake, specialized in converting from KDE 3 to KDE 4, should also work for others. This one has been used for converting the KDE buildsystem to CMake.<br />
<br />
* [http://emanuelgreisen.dk/stuff/kdevelop_am2cmake.php.tgz Alternative Automake2CMake (requires PHP)] Converts KDevelop projects that use automake to CMake.<br />
<br />
* [[GccXmlAutoConfHints|Converting autoconf tests]]<br />
<br />
====qmake====<br />
* [[CMake:ConvertFromQmake | qmake converter (requires Ruby)]] Converts projects that use Qt's qmake.<br />
<br />
====Visual Studio====<br />
* [http://vcproj2cmake.sf.net vcproj2cmake.rb (requires Ruby) SourceForge project] Creates '''and maintains''' CMakeLists.txt files by extracting info from Visual Studio project files. Elaborate script for development side-by-side the updated original static .vcproj files, supports script hooks and powerful definition mappings. Patches and new project members very welcome. Older script versions below:<br />
** [http://www.eskilson.se/vcproj2cmake.rb Original vcproj2cmake.rb version (requires Ruby)] <br />
** Slightly newer version here [http://dgwarp.hd.free.fr/vcproj2cmake.rb vcproj2cmake.rb], see:[[User_talk:Dweeves]] for details<br />
* [http://nberserk.blogspot.com/2010/11/converting-vc-projectsvcproj-to.html vcproj2cmake.ps1(PowerShell version)] Creates CMakeLists.txt. it supports vcproj configuration and detect 'exclude from build' option<br />
* [http://sourceforge.net/projects/folders4cmake/ folders4cmake (requires Java)] Use Visual Studio project files to generate corresponding "source_group" information that you can use inside your own CMake scripts. Supports Visual Studio 9/10 project files (full round-trip possible).<br />
<br />
====Basic CMakeLists.txt from-scratch-generator====<br />
* [http://websvn.kde.org/trunk/KDE/kdesdk/cmake/scripts/ gencmake (requires Ruby) ] Creates basic CMakeLists.txt files from looking at the existing files.<br />
* [http://www.vanvelzensoftware.com/postnuke/index.php?name=Downloads&req=viewdownload&cid=7 CMakeListGenerator (Win32) ] Creates complete CMakeLists.txt files as described in the [https://gucef.svn.sourceforge.net/svnroot/gucef/trunk/tools/CMakeListGenerator/docs/README.txt README ] using a combination of file and directory structure analysis. Supports resolving dependencies between multiple archives.<br />
<br />
==Success Stories==<br />
<br />
* What are some [[CMake Projects|projects using CMake]]?<br />
* [[CMake:Articles|Articles about CMake]]<br />
* [[Really Cool CMake Features]]<br />
<br />
<br />
==More Topics==<br />
<br />
* [[CMake Fortran Issues|Fortran Issues]]<br />
* [[CMake:For CMake Hackers|Generating dependency graphs with CMake]]<br />
* [[CMake:Experiments With Lua|Experiments With Lua]]<br />
* [[CMake Performance Tips|Performance Tips]]<br />
* [[CMake:Install Commands| Replacing deprecated INSTALL_FILES, INSTALL_PROGRAMS and INSTALL_TARGETS commands]]<br />
* [[CMake:GNU style example | GNU style directory layout with CMake]]<br />
* [[CMake:OpenTasks| CMake TODO]]<br />
* [[CMake:CreateQtAssistantDocs| Creating Qt Assistant Docs]]<br />
* [[CMake:Static libraries| Writing FindXXX.cmake modules that work with static libraries]]<br />
* [[CMake:Multiple versions| Writing FindXXX.cmake modules that work when multiple versions of packages are installed]]<br />
* [[CMake:Improving Find* Modules ]]<br />
* [[/C Plugins for Loadable Commands/]]<br>For anyone who wonders what the <tt>load_command</tt> command is for.<br />
* [[PC-Lint]] support for CMake<br />
<br />
=CTest=<br />
<br />
===Tutorials===<br />
* [[CMake Testing With CTest|Testing With CTest]]<br>Introduces to testing with CTest, submitting dashboards, and using CMake to add tests to the test system.<br />
<br />
* [[CMake Scripting Of CTest|CTest Scripting]]<br>Describes the scripting with CTest which can significantly simplify and automate testing and submitting dashboards.<br />
<br />
* [[CMake Generating Testing Files|Generating Input Files For CTest]]<br>Describe more in details the concepts behind testing with CTest and also explans how to use CTest without using CMake.<br />
<br />
* [[CTest:Buildserver|Buildmanagement With CTest]]<br>Describes how to setup a central configuration for all CTest scripts.<br />
<br />
===More Information===<br />
* [[CTest:Submission Issues|Configuring CTest Submission Methods]]<br />
* [[CTest:Nightly, Experimental, Continuous|CTest Nightly, Experimental, Continuous, ...]]<br />
* [[CTest:Coverage]]<br />
* [[Media:CTest Running Modes.pdf]]<br />
* [[CTest:FAQ|CTest Frequently asked questions]]<br />
<br />
===More Topics===<br />
* [[CTest:OpenTasks| CTest TODO]]<br />
* [[CTest:TestWithoutBuild| Run tests on machines without building first]]<br />
<br />
=CDash=<br />
* [http://public.kitware.com/Wiki/CDash CDash Wiki].<br />
* [http://public.kitware.com/Wiki/CDash:FAQ CDash FAQ].<br />
<br />
<br />
=CPack=<br />
===Tutorials===<br />
* [[CMake:Packaging With CPack|Packaging with CPack]]<br>Introduction to CPack, installing and packaging of software.<br />
* [[CMake:CPackConfiguration|CPack Variables]]<br><br />
* [[CMake:CPackPackageGenerators|Supported package formats]]<br><br />
* [[CMake:CPackWin32NewbiesChecklist|CPack Win32 Newbie Checklist]] <br><br />
* [[CMake:Component_Install_With_CPack|Component Install With CPack]] <br><br />
<br />
===Recipes===<br />
<br />
* [[RecipeAddShortcutToStartMenu|Add an application shortcut to the Start Menu]]<br />
<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=44032CMake:Component Install With CPack2011-12-02T07:50:28Z<p>Erk: /* CPack Generator specific behavior */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure (see the list of supported [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators CPack generators]). Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging are based on different<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# An object cannot belong to several COMPONENT<br />
# Each COMPONENT may only belong to a single component GROUP<br />
# Each COMPONENT may be included in several INSTALL_TYPE<br />
# The name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# The name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT<br />
# A component GROUP may have a PARENT_GROUP which is a component GROUP<br />
# A component does not have to belong to any component GROUP<br />
# There may be no component GROUP at all (using component grouping is '''not mandatory''')<br />
# There may be no component at all (using component install is '''not mandatory''')<br />
# Not all CPack generators honor component packaging, some of them just '''ignore''' the component specification<br />
<br />
=== Specificying components and groups ===<br />
First for each install rule like this one:<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rule does not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of every such rules.<br />
<br />
After that grouping and depencies may be specified by two ways:<br />
<br />
''FIXME TO BE CONTINUED'' (see CPack.cmake embedded documentation)<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators specific generator] the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP), RPM, DEB<br />
* For non-component-aware generators:<br />
** a single MONOLITHIC package file just as if no component were specified: Cygwin<br />
<br />
=== Controlling packaging of component-aware generators ===<br />
<br />
==== Forcing MONOLITHIC installers ====<br />
The component aware generators may be forced to ignore component if one set:<br />
set(CPACK_MONOLITHIC_INSTALL 1)<br />
If this variable is set at CMake time (inside a CMakeLists.txt) then all generators will be producing a single a.k.a. MONOLITHIC package file.<br />
Since CMake/CPack 2.8.4 the CPACK_MONOLITHIC_INSTALL var may be handled at CPack time if set inside CPACK_PROJECT_CONFIG_FILE.<br />
<br />
==== Enabling Component Packaging ====<br />
Some component-aware generators have backward-compatible behavior<br />
which makes them NOT to generate component install. <br />
In fact, this is currently the case for ArchiveGenerator and RPM.<br />
In that particular case if you want to change this default non-component-aware behavior<br />
you may set the specific variable CPACK_<GENNAME>_COMPONENT_INSTALL to ON.<br />
For example for enabling component for the RPM generator you'll have to:<br />
<br />
set(CPACK_RPM_COMPONENT_INSTALL ON)<br />
<br />
==== Controlling Differents Ways of packaging components ====<br />
For CPack generators which generates several packages the default behavior is to generate one package per COMPONENT GROUP.<br />
However, one can modify this default behavior by using:<br />
<br />
* Single package file containing all COMPONENTS (ignore COMPONENT GROUP and single file):<br />
<br />
set(CPACK_COMPONENTS_ALL_IN_ONE_PACKAGE 1)<br />
or<br />
set(CPACK_COMPONENTS_GROUPING "ALL_COMPONENTS_IN_ONE")<br />
<br />
* One package per COMPONENT (ignore COMPONENT GROUP but several files):<br />
<br />
set(CPACK_COMPONENTS_IGNORE_GROUPS 1)<br />
or<br />
set(CPACK_COMPONENTS_GROUPING "IGNORE")<br />
<br />
==== Controlling the package names ====<br />
The name of the package generated by CPack is controlled by several CPACK_xxx variables. And some name mangling rules.<br />
* CPACK_PACKAGE_FILE_NAME which is the name of package file (without extension) if it is not set by the user then CPack set it to "${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}"<br />
<br />
* CPACK_<GEN>_USE_DISPLAY_NAME_IN_FILENAME which may be set to ON or OFF indicates whether if component-aware CPack generators should mangle the package name after the DISPLAY name of the component (or component group) or simply use the name of the component.<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=38674CMake:Component Install With CPack2011-03-27T16:57:05Z<p>Erk: /* Controlling Differents Ways of packaging components */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure (see the list of supported [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators CPack generators]). Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging is based on differents<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# An object cannot belong to several COMPONENT<br />
# Each COMPONENT may only belong to a single component GROUP<br />
# Each COMPONENT may included in several INSTALL_TYPE<br />
# The name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# The name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT<br />
# A component GROUP may have a PARENT_GROUP which is a component GROUP<br />
# A component does not have to belong to any component GROUP<br />
# There may be no component GROUP at all (using component grouping is '''not mandatory''')<br />
# There may be no component at all (using component install is '''not mandatory''')<br />
# Not all CPack generators honor component packaging some of them just '''ignore''' the component specification<br />
<br />
=== Specificying components and groups ===<br />
First for each install rule like this one:<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rule does not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of every such rules.<br />
<br />
After that grouping and depencies may be specified by two ways:<br />
<br />
''FIXME TO BE CONTINUED'' (see CPack.cmake embedded documentation)<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators specific generator] the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP), RPM<br />
* For non-component-aware generators:<br />
** a single MONOLITHIC package file just as if no component were specified: DEB<br />
<br />
=== Controlling packaging of component-aware generators ===<br />
<br />
==== Forcing MONOLITHIC installers ====<br />
The component aware generators may be forced to ignore component if one set:<br />
set(CPACK_MONOLITHIC_INSTALL 1)<br />
If this variable is set at CMake time (inside a CMakeLists.txt) then all generators will be producing a single a.k.a. MONOLITHIC package file.<br />
Since CMake/CPack 2.8.4 the CPACK_MONOLITHIC_INSTALL var may be handled at CPack time if set inside CPACK_PROJECT_CONFIG_FILE.<br />
<br />
==== Enabling Component Packaging ====<br />
Some component-aware generators have backward-compatible behavior<br />
which makes them NOT to generate component install. <br />
In fact, this is currently the case for ArchiveGenerator and RPM.<br />
In that particular case if you want to change this default non-component-aware behavior<br />
you may set the specific variable CPACK_<GENNAME>_COMPONENT_INSTALL to ON.<br />
For example for enabling component for the RPM generator you'll have to:<br />
<br />
set(CPACK_RPM_COMPONENT_INSTALL ON)<br />
<br />
==== Controlling Differents Ways of packaging components ====<br />
For CPack generators which generates several packages the default behavior is to generate one package per COMPONENT GROUP.<br />
However, one can modify this default behavior by using:<br />
<br />
* Single package file containing all COMPONENTS (ignore COMPONENT GROUP and single file):<br />
<br />
set(CPACK_COMPONENTS_ALL_IN_ONE_PACKAGE 1)<br />
or<br />
set(CPACK_COMPONENTS_GROUPING "ALL_COMPONENTS_IN_ONE")<br />
<br />
* One package per COMPONENT (ignore COMPONENT GROUP but several files):<br />
<br />
set(CPACK_COMPONENTS_IGNORE_GROUPS 1)<br />
or<br />
set(CPACK_COMPONENTS_GROUPING "IGNORE")<br />
<br />
==== Controlling the package names ====<br />
The name of the package generated by CPack is controlled by several CPACK_xxx variables. And some name mangling rules.<br />
* CPACK_PACKAGE_FILE_NAME which is the name of package file (without extension) if it is not set by the user then CPack set it to "${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}"<br />
<br />
* CPACK_<GEN>_USE_DISPLAY_NAME_IN_FILENAME which may be set to ON or OFF indicates whether if component-aware CPack generators should mangle the package name after the DISPLAY name of the component (or component group) or simply use the name of the component.<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=38593CMake:Component Install With CPack2011-03-23T16:35:07Z<p>Erk: /* Controlling Differents Ways of packaging components */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure (see the list of supported [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators CPack generators]). Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging is based on differents<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# An object cannot belong to several COMPONENT<br />
# Each COMPONENT may only belong to a single component GROUP<br />
# Each COMPONENT may included in several INSTALL_TYPE<br />
# The name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# The name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT<br />
# A component GROUP may have a PARENT_GROUP which is a component GROUP<br />
# A component does not have to belong to any component GROUP<br />
# There may be no component GROUP at all (using component grouping is '''not mandatory''')<br />
# There may be no component at all (using component install is '''not mandatory''')<br />
# Not all CPack generators honor component packaging some of them just '''ignore''' the component specification<br />
<br />
=== Specificying components and groups ===<br />
First for each install rule like this one:<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rule does not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of every such rules.<br />
<br />
After that grouping and depencies may be specified by two ways:<br />
<br />
''FIXME TO BE CONTINUED'' (see CPack.cmake embedded documentation)<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators specific generator] the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP), RPM<br />
* For non-component-aware generators:<br />
** a single MONOLITHIC package file just as if no component were specified: DEB<br />
<br />
=== Controlling packaging of component-aware generators ===<br />
<br />
==== Forcing MONOLITHIC installers ====<br />
The component aware generators may be forced to ignore component if one set:<br />
set(CPACK_MONOLITHIC_INSTALL 1)<br />
If this variable is set at CMake time (inside a CMakeLists.txt) then all generators will be producing a single a.k.a. MONOLITHIC package file.<br />
Since CMake/CPack 2.8.4 the CPACK_MONOLITHIC_INSTALL var may be handled at CPack time if set inside CPACK_PROJECT_CONFIG_FILE.<br />
<br />
==== Enabling Component Packaging ====<br />
Some component-aware generators have backward-compatible behavior<br />
which makes them NOT to generate component install. <br />
In fact, this is currently the case for ArchiveGenerator and RPM.<br />
In that particular case if you want to change this default non-component-aware behavior<br />
you may set the specific variable CPACK_<GENNAME>_COMPONENT_INSTALL to ON.<br />
For example for enabling component for the RPM generator you'll have to:<br />
<br />
set(CPACK_RPM_COMPONENT_INSTALL ON)<br />
<br />
==== Controlling Differents Ways of packaging components ====<br />
For CPack generators which generates several packages the default behavior is to generate one package per COMPONENT GROUP.<br />
However, one can modify this default behavior by using:<br />
<br />
* Single package file containing all COMPONENTS (ignore COMPONENT GROUP and single file):<br />
<br />
set(CPACK_COMPONENTS_ALL_IN_ONE_PACKAGE 1)<br />
or<br />
set(CPACK_COMPONENTS_GROUPING "ALL_COMPONENTS_IN_ONE")<br />
<br />
* One package per COMPONENT (ignore COMPONENT GROUP but several files):<br />
<br />
set(CPACK_COMPONENTS_IGNORE_GROUPS 1)<br />
or<br />
set(CPACK_COMPONENTS_GROUPING "IGNORE")<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=37946CMake:Component Install With CPack2011-02-27T22:20:38Z<p>Erk: /* Rules */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure (see the list of supported [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators CPack generators]). Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging is based on differents<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# An object cannot belong to several COMPONENT<br />
# Each COMPONENT may only belong to a single component GROUP<br />
# Each COMPONENT may included in several INSTALL_TYPE<br />
# The name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# The name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT<br />
# A component GROUP may have a PARENT_GROUP which is a component GROUP<br />
# A component does not have to belong to any component GROUP<br />
# There may be no component GROUP at all (using component grouping is '''not mandatory''')<br />
# There may be no component at all (using component install is '''not mandatory''')<br />
# Not all CPack generators honor component packaging some of them just '''ignore''' the component specification<br />
<br />
=== Specificying components and groups ===<br />
First for each install rule like this one:<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rule does not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of every such rules.<br />
<br />
After that grouping and depencies may be specified by two ways:<br />
<br />
''FIXME TO BE CONTINUED'' (see CPack.cmake embedded documentation)<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators specific generator] the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP), RPM<br />
* For non-component-aware generators:<br />
** a single MONOLITHIC package file just as if no component were specified: DEB<br />
<br />
=== Controlling packaging of component-aware generators ===<br />
<br />
==== Forcing MONOLITHIC installers ====<br />
The component aware generators may be forced to ignore component if one set:<br />
set(CPACK_MONOLITHIC_INSTALL 1)<br />
If this variable is set at CMake time (inside a CMakeLists.txt) then all generators will be producing a single a.k.a. MONOLITHIC package file.<br />
Since CMake/CPack 2.8.4 the CPACK_MONOLITHIC_INSTALL var may be handled at CPack time if set inside CPACK_PROJECT_CONFIG_FILE.<br />
<br />
==== Enabling Component Packaging ====<br />
Some component-aware generators have backward-compatible behavior<br />
which makes them NOT to generate component install. <br />
In fact, this is currently the case for ArchiveGenerator and RPM.<br />
In that particular case if you want to change this default non-component-aware behavior<br />
you may set the specific variable CPACK_<GENNAME>_COMPONENT_INSTALL to ON.<br />
For example for enabling component for the RPM generator you'll have to:<br />
<br />
set(CPACK_RPM_COMPONENT_INSTALL ON)<br />
<br />
==== Controlling Differents Ways of packaging components ====<br />
For CPack generators which generates several packages the default behavior is to generate one package per COMPONENT GROUP.<br />
However, one can modify this default behavior by using:<br />
<br />
* Single package file containing all COMPONENT GROUPS:<br />
<br />
set(CPACK_COMPONENTS_ALL_GROUPS_IN_ONE_PACKAGE 1)<br />
or<br />
set(CPACK_COMPONENTS_GROUPING "ALL_GROUPS_IN_ONE")<br />
<br />
* Single package file containing all COMPONENTS (ignore COMPONENT GROUP and single file):<br />
<br />
set(CPACK_COMPONENTS_ALL_IN_ONE_PACKAGE 1)<br />
or<br />
set(CPACK_COMPONENTS_GROUPING "ALL_COMPONENTS_IN_ONE")<br />
<br />
* One package per COMPONENT (ignore COMPONENT GROUP but several files):<br />
<br />
set(CPACK_COMPONENTS_IGNORE_GROUPS 1)<br />
or<br />
set(CPACK_COMPONENTS_GROUPING "IGNORE")<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=37049CMake:Component Install With CPack2011-01-31T17:10:52Z<p>Erk: /* Controlling Differents Ways of packaging components */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure (see the list of supported [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators CPack generators]). Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging is based on differents<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# An object cannot belong to several COMPONENT<br />
# Each component may only belong to a single component GROUP<br />
# The name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# The name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT<br />
# A component GROUP may have a PARENT_GROUP which is a component GROUP<br />
# A component does not have to belong to any component GROUP<br />
# There may be no component GROUP at all (using component grouping is '''not mandatory''')<br />
# There may be no component at all (using component install is '''not mandatory''')<br />
# Not all CPack generators honor component packaging some of them just '''ignore''' the component specification<br />
<br />
=== Specificying components and groups ===<br />
First for each install rule like this one:<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rule does not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of every such rules.<br />
<br />
After that grouping and depencies may be specified by two ways:<br />
<br />
''FIXME TO BE CONTINUED'' (see CPack.cmake embedded documentation)<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators specific generator] the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP), RPM<br />
* For non-component-aware generators:<br />
** a single MONOLITHIC package file just as if no component were specified: DEB<br />
<br />
=== Controlling packaging of component-aware generators ===<br />
<br />
==== Forcing MONOLITHIC installers ====<br />
The component aware generators may be forced to ignore component if one set:<br />
set(CPACK_MONOLITHIC_INSTALL 1)<br />
If this variable is set at CMake time (inside a CMakeLists.txt) then all generators will be producing a single a.k.a. MONOLITHIC package file.<br />
Since CMake/CPack 2.8.4 the CPACK_MONOLITHIC_INSTALL var may be handled at CPack time if set inside CPACK_PROJECT_CONFIG_FILE.<br />
<br />
==== Enabling Component Packaging ====<br />
Some component-aware generators have backward-compatible behavior<br />
which makes them NOT to generate component install. <br />
In fact, this is currently the case for ArchiveGenerator and RPM.<br />
In that particular case if you want to change this default non-component-aware behavior<br />
you may set the specific variable CPACK_<GENNAME>_COMPONENT_INSTALL to ON.<br />
For example for enabling component for the RPM generator you'll have to:<br />
<br />
set(CPACK_RPM_COMPONENT_INSTALL ON)<br />
<br />
==== Controlling Differents Ways of packaging components ====<br />
For CPack generators which generates several packages the default behavior is to generate one package per COMPONENT GROUP.<br />
However, one can modify this default behavior by using:<br />
<br />
* Single package file containing all COMPONENT GROUPS:<br />
<br />
set(CPACK_COMPONENTS_ALL_GROUPS_IN_ONE_PACKAGE 1)<br />
<br />
* Single package file containing all COMPONENTS (ignore COMPONENT GROUP and single file):<br />
<br />
set(CPACK_COMPONENTS_ALL_IN_ONE_PACKAGE 1)<br />
<br />
* One package per COMPONENT (ignore COMPONENT GROUP but several files):<br />
<br />
set(CPACK_COMPONENTS_IGNORE_GROUPS 1)<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackConfiguration&diff=37048CMake:CPackConfiguration2011-01-31T16:48:25Z<p>Erk: </p>
<hr />
<div>The CPack behavior is controlled by the value of ''CPACK_XXXX'' variables.<br />
The value of thoses variables should usually be set inside ''CMakeLists.txt'' '''before''' the inclusion <br />
''INCLUDE(CPack)''.<br />
Some variables may be set/overriden on the command line when invoking CPack, like in:<br />
<br />
cpack -D CPACK_MONOLITHIC_INSTALL=1 -G NSIS<br />
<br />
The variables described hereafter are the '''generic''' ones used to adjust the behaviour of<br />
any CPack generator. However, some CPack generator have extra specific variables (CPACK_<GENERATOR-NAME>_XXXX) that may be used too control their specific features.<br />
If you seek CPack generators specific settings please go there:<br />
[http://www.cmake.org/Wiki/CMake:CPackPackageGenerators CPackPackageGenerators]<br />
<br />
=Basic settings=<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_GENERATOR || CPack generator to be used || STGZ;TGZ;TZ<br />
|- <br />
| CPACK_INCLUDE_TOPLEVEL_DIRECTORY || Controls whether CPack adds a top-level directory, usually of the form ProjectName-Version-OS, to the top of package tree. || 0 to disable, 1 to enable<br />
|-<br />
| 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;/<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_FILE || File used as a description of a project || /path/to/project/ReadMe.txt<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_SUMMARY || Description summary of a project || CMake is a build tool<br />
|-<br />
| CPACK_PACKAGE_EXECUTABLES || List of pairs of executables and labels. Used by the NSIS generator to create Start Menu shortcuts. || ccmake;CMake<br />
|-<br />
| CPACK_PACKAGE_FILE_NAME || Package file name without extension. Also a directory of installer || cmake-2.5.0-Linux-i686<br />
|-<br />
| CPACK_PACKAGE_INSTALL_DIRECTORY || Installation directory on the target system || CMake 2.5<br />
|-<br />
| CPACK_PACKAGE_INSTALL_REGISTRY_KEY || Registry key used when installing this project || CMake 2.5.0<br />
|-<br />
| CPACK_PACKAGE_NAME || Package name, defaults to the project name. || CMake<br />
|-<br />
| CPACK_PACKAGE_VENDOR || Package vendor name || Kitware<br />
|-<br />
| CPACK_PACKAGE_VERSION_MAJOR || Package Major Version || 2<br />
|- <br />
| CPACK_PACKAGE_VERSION_MINOR || Package Minor Version || 5<br />
|- <br />
| CPACK_PACKAGE_VERSION_PATCH || Package Patch Version || 0<br />
|- <br />
| 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. || ${PROJECT_BINARY_DIR}/CPackOptions.cmake<br />
|-<br />
| CPACK_SOURCE_GENERATOR || List of generators used for the source package || TGZ;TZ<br />
|- <br />
| CPACK_SOURCE_IGNORE_FILES || Pattern of files in the source tree that won't be packaged || /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*<br />
|- <br />
| CPACK_SOURCE_PACKAGE_FILE_NAME || Name of the source package || cmake-2.5.0<br />
|- <br />
| 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). || <br />
|- <br />
| 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<br />
|-<br />
| CPACK_SYSTEM_NAME || System name, defaults to the value of ${CMAKE_SYSTEM_NAME}. || Linux-i686<br />
|}<br />
<br />
=Advanced settings=<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_CMAKE_GENERATOR || What CMake generator should be used if the project is CMake project. Defaults to the value of CMAKE_GENERATOR. || Unix Makefiles<br />
|-<br />
| CPACK_RESOURCE_FILE_LICENSE || License file for the project, used by the STGZ, NSIS, and PackageMaker generators. || /home/andy/vtk/CMake/Copyright.txt<br />
|- <br />
| CPACK_RESOURCE_FILE_README || ReadMe file for the project, used by PackageMaker generator. || /home/andy/vtk/CMake/Templates/CPack.GenericDescription.txt<br />
|- <br />
| CPACK_RESOURCE_FILE_WELCOME || Welcome file for the project, used by PackageMaker generator. || /home/andy/vtk/CMake/Templates/CPack.GenericWelcome.txt<br />
|- <br />
| CPACK_PACKAGE_VERSION || Package full version, used internally. || 2.5.0<br />
|-<br />
| CPACK_TOPLEVEL_TAG || Directory for the installed files. || Linux-i686<br />
|-<br />
| CPACK_INSTALL_COMMANDS || Extra commands to install components. ||<br />
|-<br />
| CPACK_INSTALL_DIRECTORIES || Extra directories to install. ||<br />
|-<br />
| CPACK_MONOLITHIC_INSTALL || When set disables the component-based installer. ||<br />
|}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=37032CMake:Component Install With CPack2011-01-30T12:58:54Z<p>Erk: /* Component-Based Installers with CPack */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure (see the list of supported [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators CPack generators]). Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging is based on differents<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# An object cannot belong to several COMPONENT<br />
# Each component may only belong to a single component GROUP<br />
# The name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# The name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT<br />
# A component GROUP may have a PARENT_GROUP which is a component GROUP<br />
# A component does not have to belong to any component GROUP<br />
# There may be no component GROUP at all (using component grouping is '''not mandatory''')<br />
# There may be no component at all (using component install is '''not mandatory''')<br />
# Not all CPack generators honor component packaging some of them just '''ignore''' the component specification<br />
<br />
=== Specificying components and groups ===<br />
First for each install rule like this one:<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rule does not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of every such rules.<br />
<br />
After that grouping and depencies may be specified by two ways:<br />
<br />
''FIXME TO BE CONTINUED'' (see CPack.cmake embedded documentation)<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the specific generator the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP), RPM<br />
* For non-component-aware generators:<br />
** a single MONOLITHIC package file just as if no component were specified: DEB<br />
<br />
That said, component-aware generators may have backward-compatible behavior<br />
which makes them NOT to generate component install. <br />
In fact, this is currently the case for ArchiveGenerator and RPM.<br />
In that particular case if you want to change this default non-component-aware behavior<br />
you may set the specific variable CPACK_<GENNAME>_COMPONENT_INSTALL to ON.<br />
For example for enabling component for the RPM generator you'll have to:<br />
<br />
set(CPACK_RPM_COMPONENT_INSTALL ON)<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackConfiguration&diff=37031CMake:CPackConfiguration2011-01-30T12:56:31Z<p>Erk: </p>
<hr />
<div>The following variables can be set to adjust the behaviour of CPack:<br />
<br />
=Other source of informations=<br />
If you seek CPack generators specific settings please go there;<br />
[http://www.cmake.org/Wiki/CMake:CPackPackageGenerators CPackPackageGenerators]<br />
<br />
=Basic settings=<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_GENERATOR || CPack generator to be used || STGZ;TGZ;TZ<br />
|- <br />
| CPACK_INCLUDE_TOPLEVEL_DIRECTORY || Controls whether CPack adds a top-level directory, usually of the form ProjectName-Version-OS, to the top of package tree. || 0 to disable, 1 to enable<br />
|-<br />
| 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;/<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_FILE || File used as a description of a project || /path/to/project/ReadMe.txt<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_SUMMARY || Description summary of a project || CMake is a build tool<br />
|-<br />
| CPACK_PACKAGE_EXECUTABLES || List of pairs of executables and labels. Used by the NSIS generator to create Start Menu shortcuts. || ccmake;CMake<br />
|-<br />
| CPACK_PACKAGE_FILE_NAME || Package file name without extension. Also a directory of installer || cmake-2.5.0-Linux-i686<br />
|-<br />
| CPACK_PACKAGE_INSTALL_DIRECTORY || Installation directory on the target system || CMake 2.5<br />
|-<br />
| CPACK_PACKAGE_INSTALL_REGISTRY_KEY || Registry key used when installing this project || CMake 2.5.0<br />
|-<br />
| CPACK_PACKAGE_NAME || Package name, defaults to the project name. || CMake<br />
|-<br />
| CPACK_PACKAGE_VENDOR || Package vendor name || Kitware<br />
|-<br />
| CPACK_PACKAGE_VERSION_MAJOR || Package Major Version || 2<br />
|- <br />
| CPACK_PACKAGE_VERSION_MINOR || Package Minor Version || 5<br />
|- <br />
| CPACK_PACKAGE_VERSION_PATCH || Package Patch Version || 0<br />
|- <br />
| 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. || ${PROJECT_BINARY_DIR}/CPackOptions.cmake<br />
|-<br />
| CPACK_SOURCE_GENERATOR || List of generators used for the source package || TGZ;TZ<br />
|- <br />
| CPACK_SOURCE_IGNORE_FILES || Pattern of files in the source tree that won't be packaged || /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*<br />
|- <br />
| CPACK_SOURCE_PACKAGE_FILE_NAME || Name of the source package || cmake-2.5.0<br />
|- <br />
| 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). || <br />
|- <br />
| 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<br />
|-<br />
| CPACK_SYSTEM_NAME || System name, defaults to the value of ${CMAKE_SYSTEM_NAME}. || Linux-i686<br />
|}<br />
<br />
=Advanced settings=<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_CMAKE_GENERATOR || What CMake generator should be used if the project is CMake project. Defaults to the value of CMAKE_GENERATOR. || Unix Makefiles<br />
|-<br />
| CPACK_RESOURCE_FILE_LICENSE || License file for the project, used by the STGZ, NSIS, and PackageMaker generators. || /home/andy/vtk/CMake/Copyright.txt<br />
|- <br />
| CPACK_RESOURCE_FILE_README || ReadMe file for the project, used by PackageMaker generator. || /home/andy/vtk/CMake/Templates/CPack.GenericDescription.txt<br />
|- <br />
| CPACK_RESOURCE_FILE_WELCOME || Welcome file for the project, used by PackageMaker generator. || /home/andy/vtk/CMake/Templates/CPack.GenericWelcome.txt<br />
|- <br />
| CPACK_PACKAGE_VERSION || Package full version, used internally. || 2.5.0<br />
|-<br />
| CPACK_TOPLEVEL_TAG || Directory for the installed files. || Linux-i686<br />
|-<br />
| CPACK_INSTALL_COMMANDS || Extra commands to install components. ||<br />
|-<br />
| CPACK_INSTALL_DIRECTORIES || Extra directories to install. ||<br />
|}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37030CMake:CPackPackageGenerators2011-01-30T12:56:14Z<p>Erk: /* CPack RPM generators specific settings */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
CPack may generate several kind of package on behalf of various ''CPack Generators''. All generators share common properties explained below. Some if not all generators do have specific features or restriction which are explained in specific sections.<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Archive Generators==<br />
<br />
The archive generators is a family of CPack generators all derived from the same base class generator. Those generator are using the [http://code.google.com/p/libarchive/ libarchive] library in order to produce various archive file format. Those generators share common properties and features explained hereafter. Specific features are explained in corresponding specific section.<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
=== NSIS Generator Specifics settings ===<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_NSIS_MUI_ICON || The icon file (.ico) for the generated install program. Both this and CPACK_NSIS_MUI_UNIICON need to set for this to have any effect. || installer.ico<br />
|-<br />
| CPACK_NSIS_MUI_UNIICON || The icon file (.ico) for the generated uninstall program. Both this and CPACK_NSIS_MUI_ICON need to set for this to have any effect. || uninstaller.ico<br />
|-<br />
| CPACK_PACKAGE_ICON || A branding image that will be displayed on the top bar inside the installer. || installer.bmp<br />
|-<br />
| CPACK_NSIS_EXTRA_INSTALL_COMMANDS || Extra NSIS commands that will be added to the install Section. || ExecWait '\\\"$INSTDIR\\\\vcredist_x86.exe\\\" /q:a'<br />
|-<br />
| CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS || Extra NSIS commands that will be added to the uninstall Section. || <br />
|-<br />
| CPACK_NSIS_COMPRESSOR || The arguments that will be passed to the NSIS SetCompressor command. || /SOLID lzma<br />
|-<br />
| CPACK_NSIS_MODIFY_PATH || If this is set to "ON", then an extra page will appear in the installer that will allow the user to choose whether the program directory should be added to the system PATH variable. || ON<br />
|-<br />
| CPACK_NSIS_DISPLAY_NAME || Undocumented. || "${CPACK_PACKAGE_INSTALL_DIRECTORY} My Famous Project"<br />
|-<br />
| CPACK_NSIS_INSTALLED_ICON_NAME || Set the icon used for the Windows "Add or Remove Programs" tool. || "bin\\\\MyExecutable.exe"<br />
|-<br />
| CPACK_NSIS_HELP_LINK || Adds link to registry. URI. || "http:\\\\\\\\www.my-project-home-page.org"<br />
|-<br />
| CPACK_NSIS_URL_INFO_ABOUT || Adds link to registry and the vendor in add/remove programs' "Click here for support information" in program entry links here. || "http:\\\\\\\\www.my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CONTACT || Adds link to add/remove programs' "Click here for support information" in program entry. || "me@my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CREATE_ICONS_EXTRA || Additional NSIS commands for creating start menu shortcuts. || set(CPACK_NSIS_CREATE_ICONS "CreateShortCut '\$SMPROGRAMS\\\\$STARTMENU_FOLDER\\\\${PROJECT_NAME}.lnk' '\$INSTDIR\\\\${PROJECT_NAME}.exe'")<br />
|-<br />
| CPACK_NSIS_DELETE_ICONS_EXTRA || Undocumented. Possibly: Additional NSIS commands to uninstall start menu shortcuts. ||<br />
|-<br />
| CPACK_NSIS_MENU_LINKS || Used to override the Start Menu links. || "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/CMakeSetup.html" "CMakeSetup Help"<br />
|-<br />
|}<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
===Debian Generator specific settings===<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_MAINTAINER || The maintenainer informations || Firstname Lastname <email@example.com><br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_SUMMARY || Package short description || Here is my short description<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION || Package description || Here is my long description<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_DEPENDS || Package dependencies (use dpkg -s <packagename> to retrieve version) || libc6 (>= 2.7-18)<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA || This variable allow advanced user to add custom script to the control.tar.gz (inside the .deb archive) || ${CMAKE_CURRENT_SOURCE_DIR}/postinst<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_SECTION || Package section (see http://packages.debian.org/stable/) || Network<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_VERSION || Package version || ${CPACK_PACKAGE_VERSION}+lenny1<br />
|-<br />
|}<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
=== CPack RPM generators specific settings ===<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37029CMake:CPackPackageGenerators2011-01-30T12:55:31Z<p>Erk: /* NSIS */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
CPack may generate several kind of package on behalf of various ''CPack Generators''. All generators share common properties explained below. Some if not all generators do have specific features or restriction which are explained in specific sections.<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Archive Generators==<br />
<br />
The archive generators is a family of CPack generators all derived from the same base class generator. Those generator are using the [http://code.google.com/p/libarchive/ libarchive] library in order to produce various archive file format. Those generators share common properties and features explained hereafter. Specific features are explained in corresponding specific section.<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
=== NSIS Generator Specifics settings ===<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_NSIS_MUI_ICON || The icon file (.ico) for the generated install program. Both this and CPACK_NSIS_MUI_UNIICON need to set for this to have any effect. || installer.ico<br />
|-<br />
| CPACK_NSIS_MUI_UNIICON || The icon file (.ico) for the generated uninstall program. Both this and CPACK_NSIS_MUI_ICON need to set for this to have any effect. || uninstaller.ico<br />
|-<br />
| CPACK_PACKAGE_ICON || A branding image that will be displayed on the top bar inside the installer. || installer.bmp<br />
|-<br />
| CPACK_NSIS_EXTRA_INSTALL_COMMANDS || Extra NSIS commands that will be added to the install Section. || ExecWait '\\\"$INSTDIR\\\\vcredist_x86.exe\\\" /q:a'<br />
|-<br />
| CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS || Extra NSIS commands that will be added to the uninstall Section. || <br />
|-<br />
| CPACK_NSIS_COMPRESSOR || The arguments that will be passed to the NSIS SetCompressor command. || /SOLID lzma<br />
|-<br />
| CPACK_NSIS_MODIFY_PATH || If this is set to "ON", then an extra page will appear in the installer that will allow the user to choose whether the program directory should be added to the system PATH variable. || ON<br />
|-<br />
| CPACK_NSIS_DISPLAY_NAME || Undocumented. || "${CPACK_PACKAGE_INSTALL_DIRECTORY} My Famous Project"<br />
|-<br />
| CPACK_NSIS_INSTALLED_ICON_NAME || Set the icon used for the Windows "Add or Remove Programs" tool. || "bin\\\\MyExecutable.exe"<br />
|-<br />
| CPACK_NSIS_HELP_LINK || Adds link to registry. URI. || "http:\\\\\\\\www.my-project-home-page.org"<br />
|-<br />
| CPACK_NSIS_URL_INFO_ABOUT || Adds link to registry and the vendor in add/remove programs' "Click here for support information" in program entry links here. || "http:\\\\\\\\www.my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CONTACT || Adds link to add/remove programs' "Click here for support information" in program entry. || "me@my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CREATE_ICONS_EXTRA || Additional NSIS commands for creating start menu shortcuts. || set(CPACK_NSIS_CREATE_ICONS "CreateShortCut '\$SMPROGRAMS\\\\$STARTMENU_FOLDER\\\\${PROJECT_NAME}.lnk' '\$INSTDIR\\\\${PROJECT_NAME}.exe'")<br />
|-<br />
| CPACK_NSIS_DELETE_ICONS_EXTRA || Undocumented. Possibly: Additional NSIS commands to uninstall start menu shortcuts. ||<br />
|-<br />
| CPACK_NSIS_MENU_LINKS || Used to override the Start Menu links. || "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/CMakeSetup.html" "CMakeSetup Help"<br />
|-<br />
|}<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
===Debian Generator specific settings===<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_MAINTAINER || The maintenainer informations || Firstname Lastname <email@example.com><br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_SUMMARY || Package short description || Here is my short description<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION || Package description || Here is my long description<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_DEPENDS || Package dependencies (use dpkg -s <packagename> to retrieve version) || libc6 (>= 2.7-18)<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA || This variable allow advanced user to add custom script to the control.tar.gz (inside the .deb archive) || ${CMAKE_CURRENT_SOURCE_DIR}/postinst<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_SECTION || Package section (see http://packages.debian.org/stable/) || Network<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_VERSION || Package version || ${CPACK_PACKAGE_VERSION}+lenny1<br />
|-<br />
|}<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
=== CPack RPM generators specific variables ===<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackConfiguration&diff=37028CMake:CPackConfiguration2011-01-30T12:54:32Z<p>Erk: /* Other source of informations */</p>
<hr />
<div>The following variables can be set to adjust the behaviour of CPack:<br />
<br />
=Other source of informations=<br />
If you seek CPack generators specific settings please go there;<br />
[http://www.cmake.org/Wiki/CMake:CPackPackageGenerators CPackPackageGenerators]<br />
<br />
=Basic settings=<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_GENERATOR || CPack generator to be used || STGZ;TGZ;TZ<br />
|- <br />
| CPACK_INCLUDE_TOPLEVEL_DIRECTORY || Controls whether CPack adds a top-level directory, usually of the form ProjectName-Version-OS, to the top of package tree. || 0 to disable, 1 to enable<br />
|-<br />
| 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;/<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_FILE || File used as a description of a project || /path/to/project/ReadMe.txt<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_SUMMARY || Description summary of a project || CMake is a build tool<br />
|-<br />
| CPACK_PACKAGE_EXECUTABLES || List of pairs of executables and labels. Used by the NSIS generator to create Start Menu shortcuts. || ccmake;CMake<br />
|-<br />
| CPACK_PACKAGE_FILE_NAME || Package file name without extension. Also a directory of installer || cmake-2.5.0-Linux-i686<br />
|-<br />
| CPACK_PACKAGE_INSTALL_DIRECTORY || Installation directory on the target system || CMake 2.5<br />
|-<br />
| CPACK_PACKAGE_INSTALL_REGISTRY_KEY || Registry key used when installing this project || CMake 2.5.0<br />
|-<br />
| CPACK_PACKAGE_NAME || Package name, defaults to the project name. || CMake<br />
|-<br />
| CPACK_PACKAGE_VENDOR || Package vendor name || Kitware<br />
|-<br />
| CPACK_PACKAGE_VERSION_MAJOR || Package Major Version || 2<br />
|- <br />
| CPACK_PACKAGE_VERSION_MINOR || Package Minor Version || 5<br />
|- <br />
| CPACK_PACKAGE_VERSION_PATCH || Package Patch Version || 0<br />
|- <br />
| 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. || ${PROJECT_BINARY_DIR}/CPackOptions.cmake<br />
|-<br />
| CPACK_SOURCE_GENERATOR || List of generators used for the source package || TGZ;TZ<br />
|- <br />
| CPACK_SOURCE_IGNORE_FILES || Pattern of files in the source tree that won't be packaged || /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*<br />
|- <br />
| CPACK_SOURCE_PACKAGE_FILE_NAME || Name of the source package || cmake-2.5.0<br />
|- <br />
| 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). || <br />
|- <br />
| 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<br />
|-<br />
| CPACK_SYSTEM_NAME || System name, defaults to the value of ${CMAKE_SYSTEM_NAME}. || Linux-i686<br />
|}<br />
<br />
=Advanced settings=<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_CMAKE_GENERATOR || What CMake generator should be used if the project is CMake project. Defaults to the value of CMAKE_GENERATOR. || Unix Makefiles<br />
|-<br />
| CPACK_RESOURCE_FILE_LICENSE || License file for the project, used by the STGZ, NSIS, and PackageMaker generators. || /home/andy/vtk/CMake/Copyright.txt<br />
|- <br />
| CPACK_RESOURCE_FILE_README || ReadMe file for the project, used by PackageMaker generator. || /home/andy/vtk/CMake/Templates/CPack.GenericDescription.txt<br />
|- <br />
| CPACK_RESOURCE_FILE_WELCOME || Welcome file for the project, used by PackageMaker generator. || /home/andy/vtk/CMake/Templates/CPack.GenericWelcome.txt<br />
|- <br />
| CPACK_PACKAGE_VERSION || Package full version, used internally. || 2.5.0<br />
|-<br />
| CPACK_TOPLEVEL_TAG || Directory for the installed files. || Linux-i686<br />
|-<br />
| CPACK_INSTALL_COMMANDS || Extra commands to install components. ||<br />
|-<br />
| CPACK_INSTALL_DIRECTORIES || Extra directories to install. ||<br />
|}<br />
<br />
=Nullsoft Install System (NSIS) settings=<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_NSIS_MUI_ICON || The icon file (.ico) for the generated install program. Both this and CPACK_NSIS_MUI_UNIICON need to set for this to have any effect. || installer.ico<br />
|-<br />
| CPACK_NSIS_MUI_UNIICON || The icon file (.ico) for the generated uninstall program. Both this and CPACK_NSIS_MUI_ICON need to set for this to have any effect. || uninstaller.ico<br />
|-<br />
| CPACK_PACKAGE_ICON || A branding image that will be displayed on the top bar inside the installer. || installer.bmp<br />
|-<br />
| CPACK_NSIS_EXTRA_INSTALL_COMMANDS || Extra NSIS commands that will be added to the install Section. || ExecWait '\\\"$INSTDIR\\\\vcredist_x86.exe\\\" /q:a'<br />
|-<br />
| CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS || Extra NSIS commands that will be added to the uninstall Section. || <br />
|-<br />
| CPACK_NSIS_COMPRESSOR || The arguments that will be passed to the NSIS SetCompressor command. || /SOLID lzma<br />
|-<br />
| CPACK_NSIS_MODIFY_PATH || If this is set to "ON", then an extra page will appear in the installer that will allow the user to choose whether the program directory should be added to the system PATH variable. || ON<br />
|-<br />
| CPACK_NSIS_DISPLAY_NAME || Undocumented. || "${CPACK_PACKAGE_INSTALL_DIRECTORY} My Famous Project"<br />
|-<br />
| CPACK_NSIS_INSTALLED_ICON_NAME || Set the icon used for the Windows "Add or Remove Programs" tool. || "bin\\\\MyExecutable.exe"<br />
|-<br />
| CPACK_NSIS_HELP_LINK || Adds link to registry. URI. || "http:\\\\\\\\www.my-project-home-page.org"<br />
|-<br />
| CPACK_NSIS_URL_INFO_ABOUT || Adds link to registry and the vendor in add/remove programs' "Click here for support information" in program entry links here. || "http:\\\\\\\\www.my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CONTACT || Adds link to add/remove programs' "Click here for support information" in program entry. || "me@my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CREATE_ICONS_EXTRA || Additional NSIS commands for creating start menu shortcuts. || set(CPACK_NSIS_CREATE_ICONS "CreateShortCut '\$SMPROGRAMS\\\\$STARTMENU_FOLDER\\\\${PROJECT_NAME}.lnk' '\$INSTDIR\\\\${PROJECT_NAME}.exe'")<br />
|-<br />
| CPACK_NSIS_DELETE_ICONS_EXTRA || Undocumented. Possibly: Additional NSIS commands to uninstall start menu shortcuts. ||<br />
|-<br />
| CPACK_NSIS_MENU_LINKS || Used to override the Start Menu links. || "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/CMakeSetup.html" "CMakeSetup Help"<br />
|-<br />
|}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackConfiguration&diff=37027CMake:CPackConfiguration2011-01-30T12:53:30Z<p>Erk: </p>
<hr />
<div>The following variables can be set to adjust the behaviour of CPack:<br />
<br />
=Other source of informations=<br />
<br />
Another set of wiki pages contains informations about specific CPack generators<br />
[http://www.cmake.org/Wiki/CMake:CPackPackageGenerators CPackPackageGenerators]<br />
<br />
=Basic settings=<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_GENERATOR || CPack generator to be used || STGZ;TGZ;TZ<br />
|- <br />
| CPACK_INCLUDE_TOPLEVEL_DIRECTORY || Controls whether CPack adds a top-level directory, usually of the form ProjectName-Version-OS, to the top of package tree. || 0 to disable, 1 to enable<br />
|-<br />
| 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;/<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_FILE || File used as a description of a project || /path/to/project/ReadMe.txt<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_SUMMARY || Description summary of a project || CMake is a build tool<br />
|-<br />
| CPACK_PACKAGE_EXECUTABLES || List of pairs of executables and labels. Used by the NSIS generator to create Start Menu shortcuts. || ccmake;CMake<br />
|-<br />
| CPACK_PACKAGE_FILE_NAME || Package file name without extension. Also a directory of installer || cmake-2.5.0-Linux-i686<br />
|-<br />
| CPACK_PACKAGE_INSTALL_DIRECTORY || Installation directory on the target system || CMake 2.5<br />
|-<br />
| CPACK_PACKAGE_INSTALL_REGISTRY_KEY || Registry key used when installing this project || CMake 2.5.0<br />
|-<br />
| CPACK_PACKAGE_NAME || Package name, defaults to the project name. || CMake<br />
|-<br />
| CPACK_PACKAGE_VENDOR || Package vendor name || Kitware<br />
|-<br />
| CPACK_PACKAGE_VERSION_MAJOR || Package Major Version || 2<br />
|- <br />
| CPACK_PACKAGE_VERSION_MINOR || Package Minor Version || 5<br />
|- <br />
| CPACK_PACKAGE_VERSION_PATCH || Package Patch Version || 0<br />
|- <br />
| 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. || ${PROJECT_BINARY_DIR}/CPackOptions.cmake<br />
|-<br />
| CPACK_SOURCE_GENERATOR || List of generators used for the source package || TGZ;TZ<br />
|- <br />
| CPACK_SOURCE_IGNORE_FILES || Pattern of files in the source tree that won't be packaged || /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*<br />
|- <br />
| CPACK_SOURCE_PACKAGE_FILE_NAME || Name of the source package || cmake-2.5.0<br />
|- <br />
| 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). || <br />
|- <br />
| 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<br />
|-<br />
| CPACK_SYSTEM_NAME || System name, defaults to the value of ${CMAKE_SYSTEM_NAME}. || Linux-i686<br />
|}<br />
<br />
=Advanced settings=<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_CMAKE_GENERATOR || What CMake generator should be used if the project is CMake project. Defaults to the value of CMAKE_GENERATOR. || Unix Makefiles<br />
|-<br />
| CPACK_RESOURCE_FILE_LICENSE || License file for the project, used by the STGZ, NSIS, and PackageMaker generators. || /home/andy/vtk/CMake/Copyright.txt<br />
|- <br />
| CPACK_RESOURCE_FILE_README || ReadMe file for the project, used by PackageMaker generator. || /home/andy/vtk/CMake/Templates/CPack.GenericDescription.txt<br />
|- <br />
| CPACK_RESOURCE_FILE_WELCOME || Welcome file for the project, used by PackageMaker generator. || /home/andy/vtk/CMake/Templates/CPack.GenericWelcome.txt<br />
|- <br />
| CPACK_PACKAGE_VERSION || Package full version, used internally. || 2.5.0<br />
|-<br />
| CPACK_TOPLEVEL_TAG || Directory for the installed files. || Linux-i686<br />
|-<br />
| CPACK_INSTALL_COMMANDS || Extra commands to install components. ||<br />
|-<br />
| CPACK_INSTALL_DIRECTORIES || Extra directories to install. ||<br />
|}<br />
<br />
=Nullsoft Install System (NSIS) settings=<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_NSIS_MUI_ICON || The icon file (.ico) for the generated install program. Both this and CPACK_NSIS_MUI_UNIICON need to set for this to have any effect. || installer.ico<br />
|-<br />
| CPACK_NSIS_MUI_UNIICON || The icon file (.ico) for the generated uninstall program. Both this and CPACK_NSIS_MUI_ICON need to set for this to have any effect. || uninstaller.ico<br />
|-<br />
| CPACK_PACKAGE_ICON || A branding image that will be displayed on the top bar inside the installer. || installer.bmp<br />
|-<br />
| CPACK_NSIS_EXTRA_INSTALL_COMMANDS || Extra NSIS commands that will be added to the install Section. || ExecWait '\\\"$INSTDIR\\\\vcredist_x86.exe\\\" /q:a'<br />
|-<br />
| CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS || Extra NSIS commands that will be added to the uninstall Section. || <br />
|-<br />
| CPACK_NSIS_COMPRESSOR || The arguments that will be passed to the NSIS SetCompressor command. || /SOLID lzma<br />
|-<br />
| CPACK_NSIS_MODIFY_PATH || If this is set to "ON", then an extra page will appear in the installer that will allow the user to choose whether the program directory should be added to the system PATH variable. || ON<br />
|-<br />
| CPACK_NSIS_DISPLAY_NAME || Undocumented. || "${CPACK_PACKAGE_INSTALL_DIRECTORY} My Famous Project"<br />
|-<br />
| CPACK_NSIS_INSTALLED_ICON_NAME || Set the icon used for the Windows "Add or Remove Programs" tool. || "bin\\\\MyExecutable.exe"<br />
|-<br />
| CPACK_NSIS_HELP_LINK || Adds link to registry. URI. || "http:\\\\\\\\www.my-project-home-page.org"<br />
|-<br />
| CPACK_NSIS_URL_INFO_ABOUT || Adds link to registry and the vendor in add/remove programs' "Click here for support information" in program entry links here. || "http:\\\\\\\\www.my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CONTACT || Adds link to add/remove programs' "Click here for support information" in program entry. || "me@my-personal-home-page.com"<br />
|-<br />
| CPACK_NSIS_CREATE_ICONS_EXTRA || Additional NSIS commands for creating start menu shortcuts. || set(CPACK_NSIS_CREATE_ICONS "CreateShortCut '\$SMPROGRAMS\\\\$STARTMENU_FOLDER\\\\${PROJECT_NAME}.lnk' '\$INSTDIR\\\\${PROJECT_NAME}.exe'")<br />
|-<br />
| CPACK_NSIS_DELETE_ICONS_EXTRA || Undocumented. Possibly: Additional NSIS commands to uninstall start menu shortcuts. ||<br />
|-<br />
| CPACK_NSIS_MENU_LINKS || Used to override the Start Menu links. || "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/CMakeSetup.html" "CMakeSetup Help"<br />
|-<br />
|}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37026CMake:CPackPackageGenerators2011-01-30T12:53:15Z<p>Erk: /* CPack RPM generators specific variables */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
CPack may generate several kind of package on behalf of various ''CPack Generators''. All generators share common properties explained below. Some if not all generators do have specific features or restriction which are explained in specific sections.<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Archive Generators==<br />
<br />
The archive generators is a family of CPack generators all derived from the same base class generator. Those generator are using the [http://code.google.com/p/libarchive/ libarchive] library in order to produce various archive file format. Those generators share common properties and features explained hereafter. Specific features are explained in corresponding specific section.<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
===Debian Generator specific settings===<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_MAINTAINER || The maintenainer informations || Firstname Lastname <email@example.com><br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_SUMMARY || Package short description || Here is my short description<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION || Package description || Here is my long description<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_DEPENDS || Package dependencies (use dpkg -s <packagename> to retrieve version) || libc6 (>= 2.7-18)<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA || This variable allow advanced user to add custom script to the control.tar.gz (inside the .deb archive) || ${CMAKE_CURRENT_SOURCE_DIR}/postinst<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_SECTION || Package section (see http://packages.debian.org/stable/) || Network<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_VERSION || Package version || ${CPACK_PACKAGE_VERSION}+lenny1<br />
|-<br />
|}<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
=== CPack RPM generators specific variables ===<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37025CMake:CPackPackageGenerators2011-01-30T12:52:29Z<p>Erk: /* External references */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
CPack may generate several kind of package on behalf of various ''CPack Generators''. All generators share common properties explained below. Some if not all generators do have specific features or restriction which are explained in specific sections.<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Archive Generators==<br />
<br />
The archive generators is a family of CPack generators all derived from the same base class generator. Those generator are using the [http://code.google.com/p/libarchive/ libarchive] library in order to produce various archive file format. Those generators share common properties and features explained hereafter. Specific features are explained in corresponding specific section.<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
===Debian Generator specific settings===<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description || Example<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_MAINTAINER || The maintenainer informations || Firstname Lastname <email@example.com><br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION_SUMMARY || Package short description || Here is my short description<br />
|-<br />
| CPACK_PACKAGE_DESCRIPTION || Package description || Here is my long description<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_DEPENDS || Package dependencies (use dpkg -s <packagename> to retrieve version) || libc6 (>= 2.7-18)<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA || This variable allow advanced user to add custom script to the control.tar.gz (inside the .deb archive) || ${CMAKE_CURRENT_SOURCE_DIR}/postinst<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_SECTION || Package section (see http://packages.debian.org/stable/) || Network<br />
|-<br />
| CPACK_DEBIAN_PACKAGE_VERSION || Package version || ${CPACK_PACKAGE_VERSION}+lenny1<br />
|-<br />
|}<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37024CMake:CPackPackageGenerators2011-01-30T12:47:04Z<p>Erk: /* CPack Package Generators */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
CPack may generate several kind of package on behalf of various ''CPack Generators''. All generators share common properties explained below. Some if not all generators do have specific features or restriction which are explained in specific sections.<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Archive Generators==<br />
<br />
The archive generators is a family of CPack generators all derived from the same base class generator. Those generator are using the [http://code.google.com/p/libarchive/ libarchive] library in order to produce various archive file format. Those generators share common properties and features explained hereafter. Specific features are explained in corresponding specific section.<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37023CMake:CPackPackageGenerators2011-01-30T12:44:33Z<p>Erk: </p>
<hr />
<div>=CPack Package Generators=<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Archive Generators==<br />
<br />
The archive generators is a family of CPack generators all derived from the same base class generator. Those generator are using the [http://code.google.com/p/libarchive/ libarchive] library in order to produce various archive file format. Those generators share common properties and features explained hereafter. Specific features are explained in corresponding specific section.<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37022CMake:CPackPackageGenerators2011-01-30T12:43:42Z<p>Erk: </p>
<hr />
<div>=CPack Package Generators=<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Detail for each generator==<br />
Currently CPack features the following package generators:<br />
<br />
==Archive Generators==<br />
<br />
The archive generators is a family of CPack generators all derived from the same base class generator. Those generator are using the [http://code.google.com/p/libarchive/ libarchive] library in order to produce various archive file format. Those generators share common properties and features explained hereafter. Specific features are explained in corresponding specific section.<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37021CMake:CPackPackageGenerators2011-01-30T12:43:23Z<p>Erk: </p>
<hr />
<div>=CPack Package Generators=<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Detail for each generator==<br />
Currently CPack features the following package generators:<br />
<br />
==Archive Generators==<br />
<br />
The archive generators is a family of CPack generators all derived from the same base class generator. Those generator are using the [http://code.google.com/p/libarchive/ libarchive] library in order to produce various archive file format. Those generators share common properties and features explained hereafter. Specific features are explained in corresponding specific section.<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==TZ==<br />
<br />
Tar UNIX compress compressed packages.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37020CMake:CPackPackageGenerators2011-01-30T12:42:52Z<p>Erk: </p>
<hr />
<div>=CPack Package Generators=<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Detail for each generator==<br />
Currently CPack features the following package generators:<br />
<br />
==Archive Generators==<br />
<br />
The archive generators is a family of CPack generators all derived from the same base class generator. Those generator are using the [http://code.google.com/p/libarchive/ libarchive] library in order to produce various archive file format. Those generators share common properties and features explained hereafter. Specific features are explained in corresponding specific section.<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==TBZ2==<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package.<br />
<br />
==TZ==<br />
<br />
Tar UNIX compress compressed packages.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37019CMake:CPackPackageGenerators2011-01-30T12:42:14Z<p>Erk: /* Archive Generators */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Detail for each generator==<br />
Currently CPack features the following package generators:<br />
<br />
==Archive Generators==<br />
<br />
The archive generators is a family of CPack generators all derived from the same base class generator. Those generator are using the [http://code.google.com/p/libarchive/ libarchive] library in order to produce various archive file format. Those generators share common properties and features explained hereafter. Specific features are explained in corresponding specific section.<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
===TBZ2===<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package. <br />
<br />
===TZ===<br />
<br />
Tar UNIX compress compressed packages. <br />
<br />
===ZIP===<br />
<br />
ZIP compressed packages. CMake 2.4.x required zip, WinZip or 7Zip for creating the package. CMake 2.8.x built-in libarchive support does not need external programs in order to build ZIP.<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==ZIP==<br />
<br />
ZIP compressed packages. Requires zip, WinZip or 7Zip for creating the package. 7Zip support is only available in future version of CMake and can not be used with CMake Version earlier then 2.4.7.<br />
<br />
==TBZ2==<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package.<br />
<br />
==TZ==<br />
<br />
Tar UNIX compress compressed packages.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37018CMake:CPackPackageGenerators2011-01-30T12:38:22Z<p>Erk: /* STGZ */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Detail for each generator==<br />
Currently CPack features the following package generators:<br />
<br />
==Archive Generators==<br />
<br />
The archive generators is a family of CPack generators all derived from the same base class generator. Those generator are using the [http://code.google.com/p/libarchive/ libarchive] library in order to produce various archive file format. Those generators share common properties and features explained hereafter. Specific features are explained in corresponding specific section.<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
===STGZ===<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==ZIP==<br />
<br />
ZIP compressed packages. Requires zip, WinZip or 7Zip for creating the package. 7Zip support is only available in future version of CMake and can not be used with CMake Version earlier then 2.4.7.<br />
<br />
==TBZ2==<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package.<br />
<br />
==TZ==<br />
<br />
Tar UNIX compress compressed packages.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37017CMake:CPackPackageGenerators2011-01-30T12:37:24Z<p>Erk: /* Archive Generators */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Detail for each generator==<br />
Currently CPack features the following package generators:<br />
<br />
==Archive Generators==<br />
<br />
The archive generators is a family of CPack generators all derived from the same base class generator. Those generator are using the [http://code.google.com/p/libarchive/ libarchive] library in order to produce various archive file format. Those generators share common properties and features explained hereafter. Specific features are explained in corresponding specific section.<br />
<br />
===TGZ===<br />
<br />
Tar GZip compressed packages.<br />
<br />
==STGZ==<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==ZIP==<br />
<br />
ZIP compressed packages. Requires zip, WinZip or 7Zip for creating the package. 7Zip support is only available in future version of CMake and can not be used with CMake Version earlier then 2.4.7.<br />
<br />
==TBZ2==<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package.<br />
<br />
==TZ==<br />
<br />
Tar UNIX compress compressed packages.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37016CMake:CPackPackageGenerators2011-01-30T12:32:45Z<p>Erk: /* Overall usage (common to all generators) */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off [http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#CPack_Generator_specific_behavior component packaging] for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Detail for each generator==<br />
Currently CPack features the following package generators:<br />
<br />
==TGZ==<br />
<br />
Tar GZip compressed packages.<br />
<br />
==STGZ==<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==ZIP==<br />
<br />
ZIP compressed packages. Requires zip, WinZip or 7Zip for creating the package. 7Zip support is only available in future version of CMake and can not be used with CMake Version earlier then 2.4.7.<br />
<br />
==TBZ2==<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package.<br />
<br />
==TZ==<br />
<br />
Tar UNIX compress compressed packages.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=37015CMake:CPackPackageGenerators2011-01-30T12:27:22Z<p>Erk: /* Overall usage (common to all generators) */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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. For example it may be used to switch on/off component packaging for a specific generator.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only needs to contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake (usually found in the build tree)<br />
# 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...), then for each generator it:<br />
## sets CPACK_GENERATOR to the one currently being iterated over. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Detail for each generator==<br />
Currently CPack features the following package generators:<br />
<br />
==TGZ==<br />
<br />
Tar GZip compressed packages.<br />
<br />
==STGZ==<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==ZIP==<br />
<br />
ZIP compressed packages. Requires zip, WinZip or 7Zip for creating the package. 7Zip support is only available in future version of CMake and can not be used with CMake Version earlier then 2.4.7.<br />
<br />
==TBZ2==<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package.<br />
<br />
==TZ==<br />
<br />
Tar UNIX compress compressed packages.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=35435CMake:CPackPackageGenerators2010-12-12T09:22:23Z<p>Erk: /* CPack Package Generators */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
== Overall usage (common to all generators) ==<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only need contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake<br />
# 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<br />
## sets CPACK_GENERATOR to the one currently being iterated. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
==Detail for each generator==<br />
Currently CPack features the following package generators:<br />
<br />
==TGZ==<br />
<br />
Tar GZip compressed packages.<br />
<br />
==STGZ==<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==ZIP==<br />
<br />
ZIP compressed packages. Requires zip, WinZip or 7Zip for creating the package. 7Zip support is only available in future version of CMake and can not be used with CMake Version earlier then 2.4.7.<br />
<br />
==TBZ2==<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package.<br />
<br />
==TZ==<br />
<br />
Tar UNIX compress compressed packages.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=35434CMake:CPackPackageGenerators2010-12-12T09:19:55Z<p>Erk: /* CPack Package Generators */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only need contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake<br />
# 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<br />
## sets CPACK_GENERATOR to the one currently being iterated. 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.<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
Currently CPack features the following package generators:<br />
<br />
==TGZ==<br />
<br />
Tar GZip compressed packages.<br />
<br />
==STGZ==<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==ZIP==<br />
<br />
ZIP compressed packages. Requires zip, WinZip or 7Zip for creating the package. 7Zip support is only available in future version of CMake and can not be used with CMake Version earlier then 2.4.7.<br />
<br />
==TBZ2==<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package.<br />
<br />
==TZ==<br />
<br />
Tar UNIX compress compressed packages.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:CPackPackageGenerators&diff=35433CMake:CPackPackageGenerators2010-12-12T09:17:38Z<p>Erk: /* CPack Package Generators */</p>
<hr />
<div>=CPack Package Generators=<br />
<br />
Information about CPACK_xxx variables used for CPack configuration<br />
may be found there: [http://www.cmake.org/Wiki/CMake:CPackConfiguration CPackConfiguration]<br />
<br />
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.<br />
<br />
The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE. See the top level file [http://cmake.org/gitweb?p=cmake.git;a=blob;f=CMakeCPackOptions.cmake.in;hb=HEAD CMakeCPackOptions.cmake.in] for an example.<br />
<br />
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only need contain overrides.<br />
<br />
Here's how it works:<br />
# cpack runs<br />
# it includes CPackConfig.cmake<br />
# 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...)<br />
<br />
# foreach generator, it then<br />
## sets CPACK_GENERATOR to the one currently being iterated<br />
## includes the CPACK_PROJECT_CONFIG_FILE<br />
## produces the package for that generator<br />
<br />
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.<br />
<br />
Currently CPack features the following package generators:<br />
<br />
==TGZ==<br />
<br />
Tar GZip compressed packages.<br />
<br />
==STGZ==<br />
<br />
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).<br />
<br />
==NSIS==<br />
<br />
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.<br />
<br />
==ZIP==<br />
<br />
ZIP compressed packages. Requires zip, WinZip or 7Zip for creating the package. 7Zip support is only available in future version of CMake and can not be used with CMake Version earlier then 2.4.7.<br />
<br />
==TBZ2==<br />
<br />
Tar BZip2 compressed packages. Requires bzip2 for creating the package.<br />
<br />
==TZ==<br />
<br />
Tar UNIX compress compressed packages.<br />
<br />
==DragNDrop (OSX only)==<br />
<br />
Mac OSX Drag and Drop installer. Similar to the Bundle generator except that this generator doesn't create the bundle for you.<br />
To make a bundle, use the MACOSX_BUNDLE parameter in add_executable(), and to specify icon, plist, and other bundle properties, just set them with a set_target_properties() call. It also supports creating a folder that contains multiple bundles and other files.<br />
<br />
==PackageMaker (OSX only)==<br />
<br />
Mac OSX Package Maker packages. Requires Package Maker for creating the package.<br />
<br />
Some of the variables that you can use to customize the Package Maker generated package:<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| CPACK_PREFLIGHT_SCRIPT || This script is launched just after the user clicked on the "Install" button. || - <br />
|-<br />
| CPACK_POSTFLIGHT_SCRIPT || This script is launched after the postinstall / postupgrade script or when the package has been || -<br />
|-<br />
| CPACK_POSTUPGRADE_SCRIPT || This script is launched after the files in the package have been installed. (Isn't an option for a postinstall script missing? According to Apple documentation, postinstall is executed the first time a package is installed and postupgrade all subsequent times) || -<br />
|-<br />
| CPACK_OSX_PACKAGE_VERSION || Set to the minimum OS X version you support. Choices are currently 10.3, 10.4 and 10.5 || 10.3, unless you specified features that require a higher OS X version (CPACK_DOWNLOAD_SITE, CPACK_COMPONENTS_ALL)<br />
|}<br />
<br />
This is a useful site that describes where the scripts get executed and what the arguments to the scripts are. See section "What about scripts?". http://s.sudre.free.fr/Stuff/PackageMaker_Howto.html . In summary the arguments correspond to $0 Script path, $1 Package path, $2 Target location, and $3 Target Volume.<br />
<br />
==OSXX11 (OSX only)==<br />
<br />
Mac OSX X11 Bundle. Requires hdiutil for creating the package.<br />
<br />
== Bundle (OSX only) ==<br />
<br />
=== Overview ===<br />
<br />
The Bundle generator (introduced in CMake 2.6) creates a compressed disk image containing an OSX bundle, whose contents are populated with CMake INSTALL() commands. This makes it possible to create bundles of arbitrary complexity while minimizing differences with installation on other platforms. For example, a bundle created with the bundle generator can contain multiple executable files, libraries generated by the build, third-party dependencies, etc.<br />
<br />
'''''Important Note:''''' Do '''not''' use the MACOSX_BUNDLE property on executables that will be packaged using the bundle-generator! Specifying MACOSX_BUNDLE creates a separate bundle for each individual executable at build-time; the structure of these bundles becomes redundant when the bundle generator consolidates multiple executables into a single bundle.<br />
<br />
=== Bundle Layout ===<br />
<br />
<pre><br />
${CPACK_BUNDLE_NAME}/<br />
Contents/<br />
Info.plist (copied from ${CPACK_BUNDLE_PLIST})<br />
MacOS/<br />
${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})<br />
Resources/<br />
(file contents defined by CMake INSTALL() commands)<br />
</pre><br />
<br />
* CPACK_BUNDLE_PLIST is the name of a file that becomes the Info.plist for the bundle. This could be a hard-coded file included with the program sources, a file generated with CONFIGURE_FILE, etc. Rationale: Info.plist can become arbitrarily complex, applications need to be able to specify its contents directly.<br />
<br />
* The bundle's Resources/ directory is populated with the files installed with CMake INSTALL() commands. Rationale: integrate well with CMake and other package generators (such as NSIS). Makes it easy to incorporate external dependencies (Qt, GTK) into the bundle.<br />
<br />
* CPACK_BUNDLE_STARTUP_COMMAND is the name of a file that will be executed when the user opens the bundle. It could be a binary or a script. Rationale: for most non-trivial applications, simply running a binary is not enough. The following sample script demonstrates several common startup operations:<br />
** Starts X11 (required by GTK).<br />
** Updates DYLD_LIBRARY_PATH so that the application can locate libraries that are included in the bundle. This eliminates the need to run install_name_tool on libraries in the bundle, which is messy and error-prone. Useful for either Qt or GTK.<br />
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.<br />
** Sets-up some temporary files and environment variables required by (in this case) GTK.<br />
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).<br />
<br />
<pre><br />
#!/bin/sh<br />
#<br />
# Author: Aaron Voisine <aaron@voisine.org><br />
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net><br />
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com><br />
<br />
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"<br />
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"<br />
K3D_TEMP="/tmp/k3d/$UID"<br />
K3D_ETC="$K3D_TEMP/etc"<br />
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"<br />
<br />
echo "running $0"<br />
echo "K3D_BUNDLE: $K3D_BUNDLE"<br />
<br />
# Start X11 ...<br />
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null<br />
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then<br />
echo "rm -f ~/.xinitrc" > ~/.xinitrc<br />
sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc<br />
fi<br />
<br />
mkdir -p $K3D_TEMP<br />
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"<br />
#!/bin/sh<br />
mkdir -p "$K3D_TEMP"<br />
<br />
if [ "\$DISPLAY"x == "x" ]; then<br />
echo :0 > "$K3D_TEMP/display"<br />
else<br />
echo \$DISPLAY > "$K3D_TEMP/display"<br />
fi<br />
__END_OF_GETDISPLAY_SCRIPT__<br />
chmod +x "$K3D_TEMP/getdisplay.sh"<br />
rm -f $K3D_TEMP/display<br />
open-x11 $K3D_TEMP/getdisplay.sh || \<br />
open -a XDarwin $K3D_TEMP/getdisplay.sh || \<br />
echo ":0" > $K3D_TEMP/display<br />
<br />
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];<br />
do<br />
#echo "Waiting for display $K3D_TEMP/display"<br />
sleep 1;<br />
done<br />
export "DISPLAY=`cat $K3D_TEMP/display`"<br />
<br />
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11<br />
<br />
# Setup temporary runtime files<br />
rm -rf "$K3D_TEMP"<br />
<br />
# Because the bundle could be located anywhere at runtime, we have to<br />
# create temporary copies of the Pango configuration files that<br />
# reflect our current location<br />
mkdir -p "$K3D_ETC/pango"<br />
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"<br />
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"<br />
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"<br />
<br />
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"<br />
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"<br />
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"<br />
export "PATH=$K3D_RESOURCES/bin:$PATH"<br />
<br />
#export<br />
exec "$K3D_RESOURCES/bin/k3d" "--log-level=debug" "--plugins=$K3D_RESOURCES/lib/k3d/plugins" "--share=$K3D_RESOURCES/share/k3d" "--ui=$K3D_RESOURCES/lib/k3d/uiplugins/k3d-ngui.module"<br />
</pre><br />
<br />
* The bundle is then stored in a compressed disk image. Rationale: de-facto standard mechanism for distributing bundles.<br />
<br />
=== Required CMake Variables ===<br />
<br />
The prototype bundle generator uses the following variables:<br />
<br />
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).<br />
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).<br />
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).<br />
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).<br />
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.<br />
* CPACK_BUNDLE_STARTUP_COMMAND - path to a file that will be executed when the user opens the bundle. Could be a shell-script or a binary.<br />
<br />
=== Known Issues ===<br />
<br />
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]<br />
<br />
=== TODO ===<br />
<br />
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.<br />
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.<br />
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.<br />
* Add arbitrary files (such as background images, READMEs, etc) to the disk image - this use-case is distinct from adding files to the bundle with INSTALL().<br />
* Provide an option or alternative to CPACK_BUNDLE_STARTUP_COMMAND that simply executes one of the files installed in the bundle. Presumably, this should be a symlink to a binary or script.<br />
<br />
==CygwinBinary (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin package. Requires bzip2 for creating the package.<br />
<br />
==CygwinSource (Cygwin only)==<br />
<br />
Tar Bzip2 compressed Cygwin source package. Requires bzip2 for creating the package.<br />
<br />
==DEB (UNIX only)==<br />
<br />
Debian packages (2.0 version only, see the debian-binary file). In CMake cvs since July 2007, will be in 2.6.0. With CPack 2.4.x you can use the approach described in [[CMakeUserUseDebian]] (Requires only ar for creating the package). Warning: due to an incompatibility between GNU-ar and BSD-ar this is not a long-term recommended solution.<br />
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.<br />
<br />
Reference: [libapt-inst] Should support both BSD and SysV ar formats<br />
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593 <br />
<br />
Note:<br />
Only binary package are supported. source package do not really make sense since build process is cmake driven.<br />
<br />
Here are the variables needed for a binary package:<br />
<br />
=== control file (aka DEBIAN/control) for binary package ===<br />
<br />
Specific variables are needed to generate the control file for debian package. This file is created automatically using the following variables, some of which are mandatory and some are optional. <br />
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]<br />
<br />
'''package name'''<br />
<br />
* debian policy enforce lower case for package name<br />
* Package: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)<br />
<br />
'''version'''<br />
<br />
* Version: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION<br />
<br />
'''arch'''<br />
<br />
* Architecture: (mandatory)<br />
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386<br />
Notes:<br />
* should be set via: dpkg --print-architecture<br />
* There is no such thing as i686 architecture on debian, you should use i386 instead<br />
<br />
'''depends'''<br />
<br />
* Depends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS<br />
* eg.:<br />
SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")<br />
Notes:<br />
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help<br />
* TODO: automate 'objdump -p | grep NEEDED'<br />
<br />
'''maintaner'''<br />
<br />
* Maintainer: (mandatory)<br />
** valid email is required<br />
* if CPACK_DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead<br />
<br />
'''description'''<br />
<br />
* Description: (mandatory)<br />
* if CPACK_DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.<br />
<br />
'''section'''<br />
<br />
* Section: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_SECTION will default to 'devel'<br />
<br />
'''priority'''<br />
<br />
* Priority: (recommended)<br />
* if not set CPACK_DEBIAN_PACKAGE_PRIORITY will be set to "optional"<br />
<br />
'''recommends'''<br />
<br />
* Recommends:<br />
* You should set: CPACK_DEBIAN_PACKAGE_RECOMMENDS<br />
<br />
'''Suggests'''<br />
<br />
* Suggests:<br />
* You should set: CPACK_DEBIAN_PACKAGE_SUGGESTS<br />
<br />
'''Control Extra'''<br />
* Additional control files (optional)<br />
* In order to perform pre-, or post-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)<br />
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA <br />
* E.g.<br />
set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )<br />
<br />
=== Source (for reference only) ===<br />
<br />
Here are the variables needed for a source package (not implemented):<br />
<br />
* For debian source packages:<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]<br />
<br />
* .dsc<br />
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]<br />
<br />
Most of them are identical with the binary package, with exception:<br />
<br />
'''builds-depends'''<br />
<br />
* DEBIAN_PACKAGE_BUILDS_DEPENDS<br />
* eg.: <br />
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"<br />
<br />
=== External references ===<br />
<br />
* http://wiki.debian.org/HowToPackageForDebian<br />
* http://www.itk.org/Wiki/CMake:CPackConfiguration#Debian_settings<br />
<br />
==RPM (Unix Only)==<br />
<br />
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.<br />
If you use CMake 2.4.x (or you want to build source RPM)<br />
you may use the [[CMakeUserUseRPMTools]] module.<br />
<br />
''Note: CPack RPM generator does not [yet] support [[http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack#Ideas_for_Future_Development CPack Component]]. You may monitor the following feature request [[http://public.kitware.com/Bug/view.php?id=7645 #7645]] if you are interested in this.''<br />
<br />
=== CPack RPM usage ===<br />
The CPack RPM generator is not different from other CPack generator<br />
it's execution is controlled using:<br />
* generic CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]<br />
* specific CPACK_RPM_xxxx variables see generator specific wiki pages<br />
<br />
Since CMake/CPack 2.8.0, you should be able to have a detailed description of the<br />
CPACK_RPM_xxxx variables usage both on this page and from the CMake command line:<br />
<br />
cmake --help-module CPackRPM<br />
<br />
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile<br />
generator you usually launch:<br />
<br />
cd build_dir<br />
make package<br />
<br />
However if you want more command line control over the CPack run you may launch:<br />
<br />
cd build_dir<br />
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM<br />
<br />
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which <br />
may be used by CPack RPM generator.<br />
<br />
<br />
==== CPack RPM generators specific variables ====<br />
CPack RPM specific variables are used to generate an RPM spec file<br />
which will be processed by the ''rpmbuild'' tool.<br />
A specific variable may be<br />
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.<br />
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.<br />
** '''mandatory with default value''', the variable must be set but a default value is provided.<br />
** '''mandatory''', the variable must be set and no default value is provided.<br />
<br />
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):<br />
<br />
{| border="1" cellpadding="2"<br />
|-bgcolor="#abcdef"<br />
||Variable Name <br />
||Description <br />
||Default value <br />
|-<br />
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY <br />
|-<br />
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION<br />
|-<br />
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -<br />
|-<br />
| '''CPACK_RPM_PACKAGE_RELEASE''' || The RPM package release. This is the numbering of the RPM package itself, i.e. the version of the packaging and not the version of the content (see CPACK_RPM_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.|| 1<br />
|-<br />
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group (see /usr/share/doc/rpm-*/GROUPS ) || "unknown"<br />
|-<br />
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package vendor || CPACK_PACKAGE_VENDOR if set or "unknown" if not set<br />
|-<br />
| '''CPACK_RPM_PACKAGE_DESCRIPTION''' || The RPM package description || The content of CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available" if not set<br />
|-<br />
| ''CPACK_RPM_PACKAGE_REQUIRES'' || May be used to set RPM dependencies. see [[http://www.rpm.org/max-rpm/s1-rpm-depend-manual-dependencies.html RPM dependencies specification]]) for precise syntax. Note that you must enclose the complete requires string between quotes, for example:<br /> set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")|| - <br />
|-<br />
| ''CPACK_RPM_SPEC_INSTALL_POST'' || May be used to set an RPM post-install command inside the spec file. For example setting it to "/bin/true" may be used to prevent rpmbuild to strip binaries (see [[http://public.kitware.com/Bug/view.php?id=7435 Bug7435]])|| -<br />
|-<br />
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -<br />
|-<br />
| ''CPACK_RPM_USER_BINARY_SPECFILE'' || May be used to specify a user provided spec file instead of generating one. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE'' || May be used to generate a '''template''' for a user provided spec file. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679]]|| -<br />
|-<br />
| ''CPACK_RPM_<POST/PRE>_<UN>INSTALL_SCRIPT_FILE'' || The content of the specified files will be embedded in the RPM spec file in the appropriate sections. This is an feature which currently needs a patch see [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988]] || -<br />
|-<br />
| ''CPACK_RPM_PACKAGE_DEBUG'' || May be set when invoking cpack in order to trace debug informations during CPack RPM run. For example you may launch CPack like this ''cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM'' || -<br />
|}<br />
<br />
=== CPack RPM currently pending bugs/features ===<br />
Here the may-be-incomplete lists of pendings bugs/features request<br />
linked to CPackRPM:<br />
<br />
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]] this one will need more work since it depends on [[http://public.kitware.com/Bug/view.php?id=9900 Bug9900]]<br />
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-Fixed since 2.8.1]]<br />
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-Fixed since 2.8.0]]<br />
* RPM 4.6.x support <br />
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-Fixed since 2.8.1]]<br />
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-Fixed since 2.8.1]]<br />
* Support USER supplied "Provides" [[http://public.kitware.com/Bug/view.php?id=9584 Bug9584-Fixed since 2.8.1]]<br />
* Related bugs<br />
** Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-Fixed since 2.8.1]]<br />
** Symlink not packaged [[http://public.kitware.com/Bug/view.php?id=9927 Bug9927-Fixed since 2.8.1]]<br />
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-Fixed since 2.8.1]]<br />
* RPM 4.7.1 / Fedora 11 Issue, [[http://public.kitware.com/Bug/view.php?id=9872 Bug9872-Fixed since 2.8.1]]<br />
* RPM Generator, spaces in CPACK_PACKAGE_NAME cause error [[http://public.kitware.com/Bug/view.php?id=9932 Bug9932-Unfixable]]<br />
<br />
=== CPack RPM Historical Notes ===<br />
<br />
CPackRPM included along with CMake 2.8.1 is provided many new features and bug fixes<br />
--[[User:Erk|Erk]] 14:33, 20 February 2010 (UTC)<br />
<br />
The binary CPackRPM generator should now work for many RPM based distribution and rpmbuild version.<br />
[[User:Erk|Erk]] was granted CVS commit right for CPackRPM and he's maintaining and improving it as long<br />
as spare time is available --[[User:Erk|Erk]] 14:30, 20 February 2010 (UTC)<br />
<br />
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.<br />
The built-in CPack 2.6.x support for RPM is for '''binary package only''' but <br />
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.<br />
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))<br />
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .<br />
<br />
<br />
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.<br />
<br />
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=35423CMake:Component Install With CPack2010-12-11T23:13:05Z<p>Erk: /* CPack Generator specific behavior */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure. Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging is based on differents<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# An object cannot belong to several COMPONENT<br />
# Each component may only belong to a single component GROUP<br />
# The name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# The name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT<br />
# A component GROUP may have a PARENT_GROUP which is a component GROUP<br />
# A component does not have to belong to any component GROUP<br />
# There may be no component GROUP at all (using component grouping is '''not mandatory''')<br />
# There may be no component at all (using component install is '''not mandatory''')<br />
# Not all CPack generators honor component packaging some of them just '''ignore''' the component specification<br />
<br />
=== Specificying components and groups ===<br />
First for each install rule like this one:<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rule does not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of every such rules.<br />
<br />
After that grouping and depencies may be specified by two ways:<br />
<br />
''FIXME TO BE CONTINUED'' (see CPack.cmake embedded documentation)<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the specific generator the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP), RPM<br />
* For non-component-aware generators:<br />
** a single MONOLITHIC package file just as if no component were specified: DEB<br />
<br />
That said, component-aware generators may have backward-compatible behavior<br />
which makes them NOT to generate component install. <br />
In fact, this is currently the case for ArchiveGenerator and RPM.<br />
In that particular case if you want to change this default non-component-aware behavior<br />
you may set the specific variable CPACK_<GENNAME>_COMPONENT_INSTALL to ON.<br />
For example for enabling component for the RPM generator you'll have to:<br />
<br />
set(CPACK_RPM_COMPONENT_INSTALL ON)<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=35422CMake:Component Install With CPack2010-12-11T23:11:23Z<p>Erk: /* CPack Generator specific behavior */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure. Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging is based on differents<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# An object cannot belong to several COMPONENT<br />
# Each component may only belong to a single component GROUP<br />
# The name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# The name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT<br />
# A component GROUP may have a PARENT_GROUP which is a component GROUP<br />
# A component does not have to belong to any component GROUP<br />
# There may be no component GROUP at all (using component grouping is '''not mandatory''')<br />
# There may be no component at all (using component install is '''not mandatory''')<br />
# Not all CPack generators honor component packaging some of them just '''ignore''' the component specification<br />
<br />
=== Specificying components and groups ===<br />
First for each install rule like this one:<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rule does not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of every such rules.<br />
<br />
After that grouping and depencies may be specified by two ways:<br />
<br />
''FIXME TO BE CONTINUED'' (see CPack.cmake embedded documentation)<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the specific generator the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP), RPM<br />
* For non-component-aware generators:<br />
** a single package file just as if no component were specified: DEB<br />
<br />
That said, component-aware generators may have backward-compatible behavior<br />
which makes them NOT to generate component install. <br />
In fact, this is currently the case for ArchiveGenerator and RPM.<br />
In that particular case if you want to change this default non-component-aware behavior<br />
you may set the specific variable CPACK_<GENNAME>_COMPONENT_INSTALL to ON.<br />
For example for enabling component for the RPM generator you'll have to:<br />
<br />
set(CPACK_RPM_COMPONENT_INSTALL ON)<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=34192CMake:Component Install With CPack2010-11-13T13:32:25Z<p>Erk: /* Specification */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure. Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging is based on differents<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# An object cannot belong to several COMPONENT<br />
# Each component may only belong to a single component GROUP<br />
# The name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# The name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT<br />
# A component GROUP may have a PARENT_GROUP which is a component GROUP<br />
# A component does not have to belong to any component GROUP<br />
# There may be no component GROUP at all (using component grouping is '''not mandatory''')<br />
# There may be no component at all (using component install is '''not mandatory''')<br />
# Not all CPack generators honor component packaging some of them just '''ignore''' the component specification<br />
<br />
=== Specificying components and groups ===<br />
First for each install rule like this one:<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rule does not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of every such rules.<br />
<br />
After that grouping and depencies may be specified by two ways:<br />
<br />
''FIXME TO BE CONTINUED'' (see CPack.cmake embedded documentation)<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the specific generator the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP)<br />
* For non-component-aware generators:<br />
** a single package file just as if no component were specified: DEB, RPM<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=34191CMake:Component Install With CPack2010-11-13T13:25:34Z<p>Erk: /* Rules */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure. Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging is based on differents<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# An object cannot belong to several COMPONENT<br />
# Each component may only belong to a single component GROUP<br />
# The name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# The name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT<br />
# A component GROUP may have a PARENT_GROUP which is a component GROUP<br />
# A component does not have to belong to any component GROUP<br />
# There may be no component GROUP at all (using component grouping is '''not mandatory''')<br />
# There may be no component at all (using component install is '''not mandatory''')<br />
# Not all CPack generators honor component packaging some of them just '''ignore''' the component specification<br />
<br />
=== Specification ===<br />
First for each<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rules do not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of such rules.<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the specific generator the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP)<br />
* For non-component-aware generators:<br />
** a single package file just as if no component were specified: DEB, RPM<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=34183CMake:Component Install With CPack2010-11-13T12:20:49Z<p>Erk: /* Rules */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure. Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging is based on differents<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# An object cannot belong to several COMPONENT<br />
# Each component may only belong to a single component GROUP<br />
# The name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# The name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT<br />
# A component GROUP may have a PARENT_GROUP which is a component GROUP<br />
# A component does not have to belong to any component GROUP<br />
# There may be no component GROUP at all (using component grouping is not mandatory)<br />
# There may be no component at all (using component install is not mandatory)<br />
# Not all CPack generators honors component packaging some of them just ''ignore'' the component specification<br />
<br />
=== Specification ===<br />
First for each<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rules do not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of such rules.<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the specific generator the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP)<br />
* For non-component-aware generators:<br />
** a single package file just as if no component were specified: DEB, RPM<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=34182CMake:Component Install With CPack2010-11-13T12:17:37Z<p>Erk: /* Rules */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure. Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging is based on differents<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# a object cannot belong to several COMPONENT<br />
# each component may only belong to a single component GROUP<br />
# the name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# the name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT<br />
# a component GROUP may have a PARENT_GROUP<br />
<br />
=== Specification ===<br />
First for each<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rules do not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of such rules.<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the specific generator the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP)<br />
* For non-component-aware generators:<br />
** a single package file just as if no component were specified: DEB, RPM<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=34181CMake:Component Install With CPack2010-11-13T12:17:08Z<p>Erk: /* Principle of Component Packaging */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure. Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principles of CPack Component Packaging ==<br />
<br />
The principles of CPack component packaging is based on differents<br />
ways to ''group'' things together in order to define component content.<br />
<br />
=== Rules ===<br />
There are some basic rules about components:<br />
# a object cannot belong to several COMPONENT<br />
# each component may only belong to a single component GROUP<br />
# the name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)<br />
# the name of a component GROUP should be unique and cannot<br />
be the same as the name of a COMPONENT<br />
# a component GROUP may have a PARENT_GROUP<br />
<br />
=== Specification ===<br />
First for each<br />
INSTALL(...<br />
[COMPONENT component]<br />
...)<br />
<br />
the COMPONENT option should be specified with the name of the chosen component.<br />
This means that all objects (TARGETS, FILES, ...) concerned by this install rule<br />
will belong to the specified component.<br />
<br />
If some INSTALL rules do not specify the COMPONENT CMake will create a<br />
COMPONENT named ''Unspecified'' which contains the target of such rules.<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the specific generator the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP)<br />
* For non-component-aware generators:<br />
** a single package file just as if no component were specified: DEB, RPM<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erkhttps://public.kitware.com/Wiki/index.php?title=CMake:Component_Install_With_CPack&diff=34180CMake:Component Install With CPack2010-11-13T12:00:25Z<p>Erk: /* Step-by-step example Component-Based Installers with CPack */</p>
<hr />
<div>= Component-Based Installers with CPack =<br />
<br />
CPack builds binary installers for a variety of platforms using<br />
CMake's existing installation infrastructure. Augmented by a set of<br />
CPack-specific macros, a program built with CMake can easily be<br />
distributed via a user-friendly installer.<br />
<br />
By default, CPack's installers consider all of the files installed by<br />
a project as a single, monolithic unit: either the whole set of files<br />
is installed, or none of the files are installed. However, with many<br />
projects it makes sense for the installation to be subdivided into<br />
distinct, user-selectable components: some users may want to install<br />
only the comand-line tools for a project, while other users might want<br />
the GUI or the header files.<br />
<br />
This document describes how to configure CPack to generate<br />
component-based installers that allow users to select the set of<br />
project components that they wish to install.<br />
<br />
== Principle of Component Packaging ==<br />
<br />
== CPack Generator specific behavior ==<br />
<br />
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...<br />
Depending on the capacity of the specific generator the component packaging <br />
will produce:<br />
<br />
* For component-aware generators:<br />
** a single "component-aware" package file : NSIS, PackageMaker<br />
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP)<br />
* For non-component-aware generators:<br />
** a single package file just as if no component were specified: DEB, RPM<br />
<br />
= Step-by-step example Component-Based Installers =<br />
In this document, we<br />
will develop a simple installer for a simple library that has three<br />
components: a library binary, a sample application, and a C++ header<br />
file. When we have finished, these resulting installers will looks<br />
like the customizable installers below, shown for Mac OS X and<br />
Windows:<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg]]<br />
<br />
== Prerequisites ==<br />
<br />
To begin, you should be able to build graphical installers using CPack<br />
either on Windows (using the NullSoft Installation System, NSIS) or<br />
Mac OS X (using PackageMaker). Also, as of the time of this writing,<br />
the extensions to CPack required to build component-based installers <br />
are only available since CMake 2.6.1 (NSIS and PackageMaker)<br />
or CMake 2.8.3 (Archive Generator). Component support for other<br />
CPack generator should come sooner or later, check the release notes.<br />
<br />
As our primary example, we will use a simple library called "MyLib"<br />
that builds a single library (`mylib`) and an application based on<br />
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains<br />
the skeleton of such a library, with the following build and<br />
installation commands in `CMakeLists.txt`:<br />
<br />
cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)<br />
project(MyLib)<br />
<br />
add_library(mylib mylib.cpp)<br />
<br />
add_executable(mylibapp mylibapp.cpp)<br />
target_link_libraries(mylibapp mylib)<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin)<br />
install(FILES mylib.h<br />
DESTINATION include)<br />
<br />
You should be able to configure, build, and (optionally) install this<br />
project using CMake with its library, application, and header file.<br />
<br />
== Building Binary Installers with CPack ==<br />
<br />
To build binary installers with CPack, first add the following to the<br />
end of `CMakeLists.txt`:<br />
<br />
set(CPACK_PACKAGE_NAME "MyLib")<br />
set(CPACK_PACKAGE_VENDOR "CMake.org")<br />
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")<br />
set(CPACK_PACKAGE_VERSION "1.0.0")<br />
set(CPACK_PACKAGE_VERSION_MAJOR "1")<br />
set(CPACK_PACKAGE_VERSION_MINOR "0")<br />
set(CPACK_PACKAGE_VERSION_PATCH "0")<br />
set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")<br />
<br />
# This must always be last!<br />
include(CPack)<br />
<br />
More information about CPack and its configuration macros can be found<br />
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target<br />
in a CMake build. From here, makefile users can invove `make package`<br />
to build a binary installer (e.g., on Mac OS X) and Visual Studio<br />
users can build the PACKAGE target.<br />
<br />
Throughout this tutorial, we will be setting more `CPACK_` macros in<br />
`CMakeLists.txt` to communicate with CPack. It is very important that<br />
the SET commands for these macros come before the include of the<br />
`CPack` module!<br />
<br />
== Identifying Components ==<br />
<br />
The first step in building a component-based installation is to<br />
identify the set of installable components. In our example library, we<br />
have decided on three components: the library binary, the application,<br />
and the header file. This decision is arbitrary and project-specific,<br />
but be sure to identify the components that correspond to units of<br />
functionality important to your user rather than basing the components<br />
on the internal structure of your program.<br />
<br />
For each of these components, we need to identify which installed<br />
files are part of the component. For each INSTALL command in<br />
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which<br />
component the installed files will be associated with:<br />
<br />
install(TARGETS mylib <br />
ARCHIVE<br />
DESTINATION lib<br />
COMPONENT libraries)<br />
install(TARGETS mylibapp<br />
RUNTIME<br />
DESTINATION bin<br />
COMPONENT applications)<br />
install(FILES mylib.h<br />
DESTINATION include<br />
COMPONENT headers)<br />
<br />
Note that the COMPONENT argument to the INSTALL command is not new; it<br />
has been a part of CMake's INSTALL command to allow installation of<br />
only part of a project. If you are using any of the older installation<br />
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to<br />
convert them to INSTALL commands to add the COMPONENT argument.<br />
<br />
Finally, notify CPack of the names of all of the components in your<br />
project by setting the CPACK_COMPONENTS_ALL variables:<br />
<br />
set(CPACK_COMPONENTS_ALL applications libraries headers)<br />
<br />
At this point, you can build a component-based installer with CPack<br />
that will allow one to independently install the applications,<br />
libraries, and headers of MyLib.<br />
<br />
[[Image:CPackComponentBasicWindows.JPG]][[Image:CPackComponentBasicMac.jpg]]<br />
<br />
== Component Descriptions ==<br />
<br />
If you have built a binary installer at this point, you may have noted<br />
that the names of the actual components in the installer are not very<br />
descriptive: they just say "applications", "libraries", or "headers",<br />
as in the component names. We can improve on these names by setting<br />
several additional CPack variables:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")<br />
set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")<br />
set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")<br />
<br />
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}<br />
is the uppercase name of a component, is used to set a particular<br />
property of that component in the installer. Here, we set the<br />
DISPLAY_NAME property of each of our components, so that we get<br />
human-readable names. These names will be listed in the selection box<br />
rather than the internal component names "applications", "libraries",<br />
"headers". <br />
<br />
[[Image:CPackComponentNamesWindows.JPG]] [[Image:CPackComponentNamesMac.jpg]]<br />
<br />
There are several other properties associated with components,<br />
including the ability to make a component hidden, required, or<br />
disabled by default, to provide additional descriptive information,<br />
etc. We will encounter some of these other properties later; see the<br />
macro reference for a complete list.<br />
<br />
Of particular note is the DESCRIPTION property, which provides some<br />
descriptive text for the component. This descriptive text will show up<br />
in a separate "description" box in the installer, and will be updated<br />
either when the user's mouse hovers over the name of the corresponding<br />
component (Windows) or when the user clicks on a component (Mac OS<br />
X). Here, we add a description for each of our components:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION <br />
"An extremely useful application that makes use of MyLib")<br />
set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION<br />
"Static libraries used to build programs with MyLib")<br />
set(CPACK_COMPONENT_HEADERS_DESCRIPTION<br />
"C/C++ header files for use with MyLib")<br />
<br />
Generally, descriptions should provide enough information for the user<br />
to make a decision whether to include the component, but should not<br />
themselves be more than a few lines long (because the "Description"<br />
box in the installers tends to be small).<br />
<br />
[[Image:CPackComponentDescWindows.JPG]][[Image:CPackComponentDescMac.jpg]]<br />
<br />
== Intercomponent Dependencies ==<br />
<br />
With most projects, the various components are not completely<br />
independent. For example, an application component may depend on the<br />
shared libraries in another component to execute properly, such that<br />
installing the application component without the corresponding shared<br />
libraries would result in an unusable installation. CPack allows you<br />
to express the dependencies between components, so that a component<br />
will only be installed if all of the other components it depends on<br />
are also installed. <br />
<br />
To illustrate component dependencies, we will place a simple<br />
restriction on our component-based installer. Since we do not provide<br />
source code in our installer, the C++ header files we distribute can<br />
only actually be used if the user also installs the library binary to<br />
link her program against. Thus, the "headers" component depends on the<br />
availability of the "libraries" component. We can express this notion<br />
by setting the DEPENDS property for the HEADERS component as such:<br />
<br />
set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)<br />
<br />
The DEPENDS property for a component is actually at list, and as such a<br />
component can depend on several other components. By expressing all of<br />
the component dependencies in this manner, you can ensure that users<br />
will not be able to select an incomplete set of components at<br />
installation time.<br />
<br />
== Grouping Components ==<br />
<br />
When the number of components in your project grows large, you may<br />
need to provide additional organization for the list of components. To<br />
help with this organization, CPack includes the notion of component<br />
groups. A component group is, simply, a way to provide a name for a<br />
group of related components. Within the user interface, a component<br />
group has its own name, and underneath that group come all of the<br />
names of the components within the group. Users will have the option<br />
to (de-)select installation of all components in the group with a<br />
single click, or expand the group to select individual components.<br />
<br />
We will expand our example by categorizing its three components,<br />
"applications", "libraries", and "headers", into "Runtime" and<br />
"Development" groups. We place a component into a group by setting the<br />
GROUP property of the component to the name of the group as follows:<br />
<br />
set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")<br />
set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")<br />
set(CPACK_COMPONENT_HEADERS_GROUP "Development")<br />
<br />
Like components, component groups have various properties that can be<br />
customized, including the DISPLAY_NAME and DESCRIPTION. To customization<br />
a component group, set the appropriate CPack macro with the prefix<br />
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the<br />
uppercase name of the group to modify. For example, the following code<br />
adds a description to the "Development" group:<br />
<br />
set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION<br />
"All of the tools you'll ever need to develop software")<br />
<br />
Once you have customized the component groups to your liking, rebuild<br />
the binary installer to see the new organization: the MyLib<br />
application will show up under the new "Runtime" group, while the<br />
MyLib library and C++ header will show up under the new "Development"<br />
group. One can easily turn on/off all of the components within a group<br />
using the installer GUI. Some additional customizations of component<br />
groups are possible; please see the macro reference for a complete<br />
list.<br />
<br />
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg]]<br />
<br />
== Installation Types (NSIS Only) ==<br />
<br />
When a project contains a large number of components, it is common for<br />
a Windows installer to provide pre-selected sets of components based<br />
on specific user needs. For example, a user wanting to develop<br />
software against a library will want one set of components, while an<br />
end user might use an entirely different set. CPack supports this<br />
notion of pre-selected component sets via installation types. An<br />
installation type is, simply, a set of components. When the user<br />
selects an installation type, exactly that set of components is<br />
selected---then the user is permitted to further customize the<br />
installation as desired.<br />
<br />
For our simple example, we will create only two installation types: a<br />
"Full" installation type, which contains all of the components, and a<br />
"Developer" installation type, which includes only the libraries and<br />
headers. To do so, we first tell CPack which installation types we're<br />
using:<br />
<br />
set(CPACK_ALL_INSTALL_TYPES Full Developer)<br />
<br />
Like components and component groups, installation types have some<br />
properties (e.g., DISPLAY_NAME), which can be set via variables with<br />
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the<br />
uppercase name of the installation type. See the macro reference for<br />
additional information.<br />
<br />
Next, we set the INSTALL_TYPES property of each component to state<br />
which installation types will include that component:<br />
<br />
set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)<br />
set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)<br />
<br />
Components can be in any number of installation types. If you now<br />
rebuild the Windows installer, the components page will contain a<br />
combo box that allows you to select the installation type and<br />
therefore its corresponding set of components.<br />
<br />
[[Image:CPackComponentsFinalWindows.JPG]]<br />
<br />
== Next Steps ==<br />
<br />
From here, you should be able to turn your existing CPack-generated<br />
binary installers into component-based installers to provide your<br />
users with more-flexible installation options. The complete example<br />
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For<br />
a more advanced example of a component-based installer build with<br />
CPack, please visit the Boost-CMake project.<br />
<br />
= Macro Reference =<br />
<br />
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}<br />
refers to a component group, and ${INSTNAME} refers to an installation<br />
type, all of which are uppercase.<br />
<br />
{|<br />
|- bgcolor="#abcdef"<br />
! Variable Name || Description<br />
|-<br />
| CPACK_COMPONENTS_ALL || A list containing the names of all components that should be installed. The presence of this macro indicates that CPack should build a component-based installer. Files associated with any components not listed here or any installation commands not associated with any component will not be installed.<br />
|- <br />
|CPACK_COMPONENT_${COMPNAME}_DISPLAY_NAME || The displayed name of the component ${COMPNAME}, used in graphical installers to display the component name. This value can be any string.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DESCRIPTION || An extended description of the component ${COMPNAME}, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_HIDDEN || Flag that indicates that this component will be hidden in the graphical installer, and therefore cannot be selected or installed. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_REQUIRED || Flag that indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected.<br />
|-<br />
|CPACK_COMPONENT_${COMPNAME}_DISABLED || Flag that indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_DEPENDS || Lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_GROUP || Names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group.<br />
|-<br />
| CPACK_COMPONENT_${COMPNAME}_INSTALL_TYPES || Lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Only available with NSIS.<br />
|-<br />
|CPACK_COMPONENT_GROUP_${GROUPNAME}_DISPLAY_NAME || The displayed name of the component group ${GROUPNAME}, used in graphical installers to display the component group name. This value can be any string.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_DESCRIPTION || An extended description of the component group ${GROUPNAME}, used in graphical installers to give the user additional information about the components contained within this group. Descriptions can span multiple lines using "\n" as the line separator.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.<br />
|-<br />
| CPACK_COMPONENT_GROUP_${GROUPNAME}_EXPANDED || Flag indicating whether the group should start out "expanded", showing its components. Otherwise only the group name itself will be shown until the user clicks on the group. Only available with NSIS.<br />
|-<br />
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.<br />
|}<br />
<br />
<br />
<br />
= Ideas for Future Development =<br />
* Add support for other binary installer generators, such as RPM and Deb. The installer will then create a set of RPM or Deb files, with appropriate dependencies. A key question here is granularity: RPMs and Debs tend to have a coarser granularity than graphical installers.<br />
* CPack RPM generator component support: This is true that RPM has coarser granularity, however one may build 1 RPM by component and embbed appropriate dependencies between each generated RPM. For building several RPM at once you may either generate a spec file for each component or generate a single spec file which may contain sub-packages [[http://www.rpm.org/max-rpm/s1-rpm-subpack-spec-file-changes.html]]. --[[User:Erk|Erk]] 04:36, 28 August 2008 (EDT)<br />
<br />
* Graphviz output of components and their dependencies?<br />
<br />
{{CMake/Template/Footer}}</div>Erk