CMake:CPackPackageGenerators: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
(Replace content with link to new CMake community wiki)
 
(70 intermediate revisions by 15 users not shown)
Line 1: Line 1:
=CPack Package Generators=
{{CMake/Template/Moved}}


Information about CPACK_xxx variables used for CPack configuration
This page has moved [https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators here].
may be found there: [http://www.itk.org/Wiki/CMake:CPackConfiguration CPackConfiguration]
 
Currently CPack features the following package generators:
 
==TGZ==
 
Tar GZip compressed packages.
 
==STGZ==
 
Self extracting Tar GZip compressed packages (needs /bin/sh, tar, gunzip and tail for extracting).
 
==NSIS==
 
Nullsoft Installer. Requires [http://nsis.sourceforge.net/ NSIS] for creating the package.
 
==ZIP==
 
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.
 
==TBZ2==
 
Tar BZip2 compressed packages. Requires bzip2 for creating the package.
 
==TZ==
 
Tar UNIX compress compressed packages.
 
==DragNDrop (OSX only)==
 
Mac OSX Drag and Drop installer.  Similar to the Bundle generator except that this generator doesn't create the bundle for you.
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.
 
==PackageMaker (OSX only)==
 
Mac OSX Package Maker packages. Requires Package Maker for creating the package.
 
==OSXX11 (OSX only)==
 
Mac OSX X11 Bundle. Requires hdiutil for creating the package.
 
== Bundle (OSX only) ==
 
=== Overview ===
 
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.
 
'''''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.
 
=== Bundle Layout ===
 
<pre>
${CPACK_BUNDLE_NAME}/
  Contents/
    Info.plist (copied from ${CPACK_BUNDLE_PLIST})
    MacOS/
      ${CPACK_BUNDLE_NAME} (copied from ${CPACK_BUNDLE_STARTUP_COMMAND})
    Resources/
      (file contents defined by CMake INSTALL() commands)
</pre>
 
* 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.
 
* 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.
 
* 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:
** Starts X11 (required by GTK).
** 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.
** Updates PATH so the "main" application can easily run "child" binaries included in the bundle.
** Sets-up some temporary files and environment variables required by (in this case) GTK.
** Passes information to the application via the command line (in this case, paths to several application resources located in the bundle).
 
<pre>
#!/bin/sh
#
# Author: Aaron Voisine <aaron@voisine.org>
# Inkscape Modifications: Michael Wybrow <mjwybrow@users.sourceforge.net>
# K-3D Modifications: Timothy M. Shead <tshead@k-3d.com>
 
K3D_BUNDLE="`echo "$0" | sed -e 's/\/Contents\/MacOS\/K-3D//'`"
K3D_RESOURCES="$K3D_BUNDLE/Contents/Resources"
K3D_TEMP="/tmp/k3d/$UID"
K3D_ETC="$K3D_TEMP/etc"
K3D_PANGO_RC_FILE="$K3D_ETC/pango/pangorc"
 
echo "running $0"
echo "K3D_BUNDLE: $K3D_BUNDLE"
 
# Start X11 ...
ps -wx -ocommand | grep -e '[X]11.app' > /dev/null
if [ "$?" != "0" -a ! -f ~/.xinitrc ]; then
    echo "rm -f ~/.xinitrc" > ~/.xinitrc
    sed 's/xterm/# xterm/' /usr/X11R6/lib/X11/xinit/xinitrc >> ~/.xinitrc
fi
 
mkdir -p $K3D_TEMP
cat << __END_OF_GETDISPLAY_SCRIPT__ > "$K3D_TEMP/getdisplay.sh"
#!/bin/sh
mkdir -p "$K3D_TEMP"
 
if [ "\$DISPLAY"x == "x" ]; then
    echo :0 > "$K3D_TEMP/display"
else
    echo \$DISPLAY > "$K3D_TEMP/display"
fi
__END_OF_GETDISPLAY_SCRIPT__
chmod +x "$K3D_TEMP/getdisplay.sh"
rm -f $K3D_TEMP/display
open-x11 $K3D_TEMP/getdisplay.sh || \
open -a XDarwin $K3D_TEMP/getdisplay.sh || \
echo ":0" > $K3D_TEMP/display
 
while [ "$?" == "0" -a ! -f $K3D_TEMP/display ];
do
  #echo "Waiting for display $K3D_TEMP/display"
  sleep 1;
done
export "DISPLAY=`cat $K3D_TEMP/display`"
 
ps -wx -ocommand | grep -e '[X]11' > /dev/null || exit 11
 
# Setup temporary runtime files
rm -rf "$K3D_TEMP"
 
# Because the bundle could be located anywhere at runtime, we have to
# create temporary copies of the Pango configuration files that
# reflect our current location
mkdir -p "$K3D_ETC/pango"
sed -e 's|/opt/local/etc|'"$K3D_ETC|g" "$K3D_RESOURCES/etc/pango/pangorc" > "$K3D_ETC/pango/pangorc"
sed -e 's|/opt/local|\"'"$K3D_RESOURCES|g" -e "s/\.so/.so\"/g" "$K3D_RESOURCES/etc/pango/pango.modules" > "$K3D_ETC/pango/pango.modules"
cp -f "$K3D_RESOURCES/etc/pango/pangox.aliases" "$K3D_ETC/pango/pangox.aliases"
 
export "DYLD_LIBRARY_PATH=$K3D_RESOURCES/lib"
export "FONTCONFIG_PATH=$K3D_RESOURCES/etc/fonts"
export "PANGO_RC_FILE=$K3D_PANGO_RC_FILE"
export "PATH=$K3D_RESOURCES/bin:$PATH"
 
#export
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"
</pre>
 
* The bundle is then stored in a compressed disk image.  Rationale: de-facto standard mechanism for distributing bundles.
 
=== Required CMake Variables ===
 
The prototype bundle generator uses the following variables:
 
* CPACK_PACKAGE_FILE_NAME - provides the name of the final compressed disk image (the name of the file that is distributed).
* CPACK_PACKAGE_ICON - provides the icon for the mounted disk image (appears after the user mounts the disk image).
* CPACK_BUNDLE_NAME - provides the bundle name (displayed in the finder underneath the bundle icon).
* CPACK_BUNDLE_ICON - provides the bundle icon (displayed in the /Applications folder, on the dock, etc).
* CPACK_BUNDLE_PLIST - path to a file that will become the bundle plist.
* 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.
 
=== Known Issues ===
 
* [http://public.kitware.com/Bug/view.php?id=7523 0007523: CPack OSX bundle generator can fail when assigning a custom volume icon.]
 
=== TODO ===
 
* Detect attempts to use the bundle generator with MACOSX_BUNDLE.
* Generate a default Info.plist file if CPACK_BUNDLE_PLIST is not defined.
* Support fixing-up binaries with install_name_tool, eliminating the need to run a script that sets DYLD_LIBRARY_PATH.
* 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().
* 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.
 
==CygwinBinary (Cygwin only)==
 
Tar Bzip2 compressed Cygwin package.  Requires bzip2 for creating the package.
 
==CygwinSource (Cygwin only)==
 
Tar Bzip2 compressed Cygwin source package.  Requires bzip2 for creating the package.
 
==DEB (UNIX only)==
 
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.
Instead you should switch to the solution implemented in 2.6.x where a BSD-ar implementation was integrated in CPack.
 
Reference: [libapt-inst] Should support both BSD and SysV ar formats
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=161593
 
Note:
Only binary package are supported. source package do not really make sense since build process is cmake driven.
 
Here are the variables needed for a binary package:
 
=== control file (aka DEBIAN/control) for binary package ===
 
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.
See also: [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-binarycontrolfiles]
 
'''package name'''
 
* debian policy enforce lower case for package name
* Package: (mandatory)
* if CPACK_DEBIAN_PACKAGE_NAME is not set CPACK_PACKAGE_NAME (lower case will be used)
 
'''version'''
 
* Version: (mandatory)
* if CPACK_DEBIAN_PACKAGE_VERSION is not set CPACK_PACKAGE_VERSION
 
'''arch'''
 
* Architecture: (mandatory)
* if not set CPACK_DEBIAN_PACKAGE_ARCHITECTURE will be set to i386
Notes:
* should be set via: dpkg --print-architecture
* There is no such thing as i686 architecture on debian, you should use i386 instead
 
'''depends'''
 
* Depends:
* You should set: CPACK_DEBIAN_PACKAGE_DEPENDS
* eg.:
    SET(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libgcc1 (>= 1:3.4.2-12)")
Notes:
* have a look at GET_PROPERTY(result GLOBAL ENABLED_FEATURES), this returns the successful FIND_PACKAGE() calls, maybe this can help
* TODO: automate 'objdump -p | grep NEEDED'
 
'''maintaner'''
 
* Maintainer: (mandatory)
** valid email is required
* if DEBIAN_PACKAGE_MAINTAINER is not set, CPACK_PACKAGE_CONTACT will be used instead
 
'''description'''
 
* Description: (mandatory)
* if DEBIAN_PACKAGE_DESCRIPTION is not set CPACK_PACKAGE_DESCRIPTION_SUMMARY will be used instead.
 
'''section'''
 
* Section: (recommended)
* if not set DEBIAN_PACKAGE_SECTION will default to 'devel'
 
'''priority'''
 
* Priority: (recommended)
* if not set DEBIAN_PACKAGE_PRIORITY will be set to "optional"
 
'''recommends'''
 
* Recommends:
* You should set: DEBIAN_PACKAGE_RECOMMENDS
 
'''Suggests'''
 
* Suggests:
* You should set: DEBIAN_PACKAGE_SUGGESTS
 
'''Control Extra'''
* Additional control files (optional)
* In order to perform pre-, or pose-install configuration, certain files can be provided in the DEBIAN/ folder in the debian package (postinst, preinst, postrm, prerm)
* You should set: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
* E.g.
    set( CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/postinst;${CMAKE_CURRENT_SOURCE_DIR}/CMake/debian/prerm;" )
 
=== Source (for reference only) ===
 
Here are the variables needed for a source package (not implemented):
 
* For debian source packages:
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles debian/control]
 
* .dsc
* see also [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-debiansourcecontrolfiles]
 
Most of them are identical with the binary package, with exception:
 
'''builds-depends'''
 
* DEBIAN_PACKAGE_BUILDS_DEPENDS
* eg.:
"debhelper (>> 5.0.0), libncurses5-dev, tcl8.4"
 
=== External references ===
 
* http://wiki.debian.org/HowToPackageForDebian
 
==RPM (Unix Only)==
 
Binary RPM packages are supported by CMake (more precisely by CPack) since CMake 2.6.0.
If you use CMake 2.4.x (or you want to build source RPM)
you may use the [[CMakeUserUseRPMTools]] module.
 
''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.''
 
=== CPack RPM usage ===
The CPack RPM generator is not different from other CPack generator
it's execution is controlled using:
* generic  CPACK_xxxx variables see [[CMake:CPackConfiguration|CPack variables]]
* specific CPACK_RPM_xxxx variables see generator specific wiki pages
 
If you use [[CMake:Packaging_With_CPack#Using_CPack_with_CMake|CPack with CMake]] with the Makefile
generator you usually launch:
 
  cd build_dir
  make package
 
However if you want more command line control over the CPack run you may launch:
 
  cd build_dir
  cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -D CPACK_RPM_SPEC_INSTALL_POST="/bin/true" -G RPM
 
this will launch CPack with additionnal CPACK_RPM_xxxx variables definitions which
may be used by CPack RPM generator.
 
 
==== CPack RPM generators specific variables ====
CPack RPM specific variables are used to generate an RPM spec file
which will be processed by the ''rpmbuild'' tool.
A specific variable may be
* ''optional'', the variable may or may not be set and its value is not needed for building a valid spec file.
* '''mandatory''', the variable must be set because we need a value for building a valid spec file.
** '''mandatory with default value''', the variable must be set but a default value is provided.
** '''mandatory''', the variable must be set and no default value is provided.
 
Here is the list of CPack RPM specific variables (''some variable are not yet supported because there are some patches pending''):
 
{| border="1" cellpadding="2"
|-bgcolor="#abcdef"
  ||Variable Name
  ||Description
  ||Default value
|-
| '''CPACK_RPM_PACKAGE_SUMMARY''' || The RPM package summary || CPACK_PACKAGE_DESCRIPTION_SUMMARY
|-
| '''CPACK_RPM_PACKAGE_NAME''' || The RPM package name || CPACK_PACKAGE_NAME
|-
| '''CPACK_RPM_PACKAGE_VERSION''' || The RPM package version || CPACK_PACKAGE_VERSION
|-
| ''CPACK_RPM_PACKAGE_ARCHITECTURE'' || The RPM package architecture. This may be set to "noarch" if you know you are building a noarch package. || -
|-
| '''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
|-
| '''CPACK_RPM_PACKAGE_LICENSE''' || The RPM package license policy. || "unknown"
|-
| '''CPACK_RPM_PACKAGE_GROUP''' || The RPM package group || "unknown"
|-
| '''CPACK_RPM_PACKAGE_VENDOR''' || The RPM package group || CPACK_PACKAGE_VENDOR if set or "unknown" if not set
|-
| '''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
|-
| ''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.|| -
|-
| ''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]])|| -
|-
| ''CPACK_RPM_SPEC_MORE_DEFINE'' || May be used to add any %define lines to the generated spec file.|| -
|-
| ''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]]|| -
|-
| ''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]]|| -
|-
| ''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]] || -
|-
| ''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'' || -
|}
 
=== CPack RPM currently pending bugs/features ===
Here the may-be-incomplete lists of pendings bugs/features request
linked to CPackRPM:
 
* Support for COMPONENT [[http://public.kitware.com/Bug/view.php?id=7645 Bug7645-PreliminaryPatchUnderway]]
* RPM Post/Pre (un)install script support [[http://public.kitware.com/Bug/view.php?id=8988 Bug8988-PatchWillNeedUpdateFor2-8]]
* Builtin documentation with ''cmake --help-module CPackRPM'' [[http://public.kitware.com/Bug/view.php?id=9029 Bug9029-InCVS-2-8]]
* RPM 4.6.x support
** Fedora Core 10 fix, [[http://public.kitware.com/Bug/view.php?id=8967 Bug8967-InCVS-2-8]]
** Mandriva 2009.1 fix, [[http://public.kitware.com/Bug/view.php?id=9031 Bug9031-InCVS-2-8]]
* Do not include include directories in %file section [[http://public.kitware.com/Bug/view.php?id=9654 Bug9654-PatchProposed]]
* Support of USER specified spec file [[http://public.kitware.com/Bug/view.php?id=9679 Bug9679-PendingWithPatch]]
 
=== CPack RPM Historical Notes ===
The built-in CPack support for RPM is based on the work done in the [[CMakeUserUseRPMTools|RPM]] module.
The builtin CPack 2.6.x support for RPM is for '''binary package only''' but
the binary RPM package built faster using CPack than [[CMakeUserUseRPMTools]] module.
This restriction is due to both a lack of time of the implementor (--[[User:Erk|Erk]] 05:01, 7 September 2007 (EDT))
and some [[CMakeUserUseRPMTools#CPack_Built-in_RPM_support_design_issues|design issues]] in current CPack .
 
The [[CMakeUserUseRPMTools]] module should be usable both with CMake 2.4.x and forthcoming CMake 2.6.x.
 
For an enhanced version of these modules, take a look at this discussion http://www.cmake.org/pipermail/cmake/2007-July/014945.html.

Latest revision as of 15:40, 30 April 2018


The CMake community Wiki has moved to the Kitware GitLab Instance.

This page has moved here.