CMake:Component Install With CPack: Difference between revisions

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


CPack builds binary installers for a variety of platforms using
This page has moved [https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Component-Install-With-CPack here].
CMake's existing installation infrastructure (see the list of supported [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators CPack generators]). Augmented by a set of
CPack-specific macros, a program built with CMake can easily be
distributed via a user-friendly installer.
 
By default, CPack's installers consider all of the files installed by
a project as a single, monolithic unit: either the whole set of files
is installed, or none of the files are installed. However, with many
projects it makes sense for the installation to be subdivided into
distinct, user-selectable components: some users may want to install
only the comand-line tools for a project, while other users might want
the GUI or the header files.
 
This document describes how to configure CPack to generate
component-based installers that allow users to select the set of
project components that they wish to install.
 
== Principles of CPack Component Packaging ==
 
The principles of CPack component packaging is based on differents
ways to ''group'' things together in order to define component content.
 
=== Rules ===
There are some basic rules about components:
# An object cannot belong to several COMPONENT
# Each component may only belong to a single component GROUP
# The name of each COMPONENT should be unique (and different from ''Unspecified'' which is a reserved component name)
# The name of a component GROUP should be unique and cannot be the same as the name of a COMPONENT
# A component GROUP may have a PARENT_GROUP which is a component GROUP
# A component does not have to belong to any component GROUP
# There may be no component GROUP at all (using component grouping is '''not mandatory''')
# There may be no component at all (using component install is '''not mandatory''')
# Not all CPack generators honor component packaging some of them just '''ignore''' the component specification
 
=== Specificying components and groups ===
First for each install rule like this one:
  INSTALL(...
          [COMPONENT component]
          ...)
 
the COMPONENT option should be specified with the name of the chosen component.
This means that all objects (TARGETS, FILES, ...) concerned by this install rule
will belong to the specified component.
 
If some INSTALL rule does not specify the COMPONENT CMake will create a
COMPONENT named  ''Unspecified'' which contains the target of every such rules.
 
After that grouping and depencies may be specified by two ways:
 
''FIXME TO BE CONTINUED'' (see CPack.cmake embedded documentation)
 
== CPack Generator specific behavior ==
 
CPack comes with several binary Generators: NSIS, PackageMaker, TGZ, ZIP, RPM, DEB...
Depending on the capacity of the [http://www.cmake.org/Wiki/CMake:CPackPackageGenerators specific generator] the component packaging
will produce:
 
* For component-aware generators:
** a single "component-aware" package file : NSIS, PackageMaker
** possibly multiple package files: ArchiveGenerator (TBZ2, TGZ, STGZ, TZ, ZIP), RPM
* For non-component-aware generators:
** a single MONOLITHIC package file just as if no component were specified: DEB
 
=== Controlling packaging of component-aware generators ===
 
==== Forcing MONOLITHIC installers ====
The component aware generators may be forced to ignore component if one set:
  set(CPACK_MONOLITHIC_INSTALL 1)
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.
Since CMake/CPack 2.8.4 the CPACK_MONOLITHIC_INSTALL var may be handled at CPack time if set inside  CPACK_PROJECT_CONFIG_FILE.
 
==== Enabling Component Packaging ====
Some component-aware generators have backward-compatible behavior
which makes them NOT to generate component install.
In fact, this is currently the case for ArchiveGenerator and RPM.
In that particular case if you want to change this default non-component-aware behavior
you may set the specific variable CPACK_<GENNAME>_COMPONENT_INSTALL to ON.
For example for enabling component for the RPM generator you'll have to:
 
  set(CPACK_RPM_COMPONENT_INSTALL ON)
 
==== Controlling Differents Ways of packaging components ====
For CPack generators which generates several packages the default behavior is to generate one package per COMPONENT GROUP.
However, one can modify this default behavior by using:
 
* Single package file containing all COMPONENT GROUPS:
 
  set(CPACK_COMPONENTS_ALL_GROUPS_IN_ONE_PACKAGE 1)
or
  set(CPACK_COMPONENTS_GROUPING "ALL_GROUPS_IN_ONE")
 
* Single package file containing all COMPONENTS (ignore COMPONENT GROUP and single file):
 
  set(CPACK_COMPONENTS_ALL_IN_ONE_PACKAGE 1)
or
  set(CPACK_COMPONENTS_GROUPING "ALL_COMPONENTS_IN_ONE")
 
* One package per COMPONENT (ignore COMPONENT GROUP but several files):
 
  set(CPACK_COMPONENTS_IGNORE_GROUPS 1)
or
  set(CPACK_COMPONENTS_GROUPING "IGNORE")
 
= Step-by-step example Component-Based Installers =
In this document, we
will develop a simple installer for a simple library that has three
components: a library binary, a sample application, and a C++ header
file. When we have finished, these resulting installers will looks
like the customizable installers below, shown for Mac OS X and
Windows:
 
[[Image:CPackComponentsFinalWindows.JPG]] [[Image:CPackComponentsFinalMac.jpg‎]]
 
== Prerequisites ==
 
To begin, you should be able to build graphical installers using CPack
either on Windows (using the NullSoft Installation System, NSIS) or
Mac OS X (using PackageMaker). Also, as of the time of this writing,
the extensions to CPack required to build component-based installers
are only available since CMake 2.6.1 (NSIS and PackageMaker)
or CMake 2.8.3 (Archive Generator). Component support for other
CPack generator should come sooner or later, check the release notes.
 
As our primary example, we will use a simple library called "MyLib"
that builds a single library (`mylib`) and an application based on
that library (`mylibapp`). The file [[Image:ComponentExampleStart.zip]] contains
the skeleton of such a library, with the following build and
installation commands in `CMakeLists.txt`:
 
  cmake_minimum_required(VERSION 2.6.0 FATAL_ERROR)
  project(MyLib)
 
  add_library(mylib mylib.cpp)
 
  add_executable(mylibapp mylibapp.cpp)
  target_link_libraries(mylibapp mylib)
 
  install(TARGETS mylib
    ARCHIVE
    DESTINATION lib)
  install(TARGETS mylibapp
    RUNTIME
    DESTINATION bin)
  install(FILES mylib.h
    DESTINATION include)
 
You should be able to configure, build, and (optionally) install this
project using CMake with its library, application, and header file.
 
== Building Binary Installers with CPack ==
 
To build binary installers with CPack, first add the following to the
end of `CMakeLists.txt`:
 
  set(CPACK_PACKAGE_NAME "MyLib")
  set(CPACK_PACKAGE_VENDOR "CMake.org")
  set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MyLib - CPack Component Installation Example")
  set(CPACK_PACKAGE_VERSION "1.0.0")
  set(CPACK_PACKAGE_VERSION_MAJOR "1")
  set(CPACK_PACKAGE_VERSION_MINOR "0")
  set(CPACK_PACKAGE_VERSION_PATCH "0")
  set(CPACK_PACKAGE_INSTALL_DIRECTORY "CPack Component Example")
 
  # This must always be last!
  include(CPack)
 
More information about CPack and its configuration macros can be found
[[CMake:CPackConfiguration|here]], but this boilerplate suffices to enable the packaging target
in a CMake build. From here, makefile users can invove `make package`
to build a binary installer (e.g., on Mac OS X) and Visual Studio
users can build the PACKAGE target.
 
Throughout this tutorial, we will be setting more `CPACK_` macros in
`CMakeLists.txt` to communicate with CPack. It is very important that
the SET commands for these macros come before the include of the
`CPack` module!
 
== Identifying Components ==
 
The first step in building a component-based installation is to
identify the set of installable components. In our example library, we
have decided on three components: the library binary, the application,
and the header file. This decision is arbitrary and project-specific,
but be sure to identify the components that correspond to units of
functionality important to your user rather than basing the components
on the internal structure of your program.
 
For each of these components, we need to identify which installed
files are part of the component. For each INSTALL command in
`CMakeLists.txt`, add an appropriate COMPONENT argument stating which
component the installed files will be associated with:
 
  install(TARGETS mylib
    ARCHIVE
    DESTINATION lib
    COMPONENT libraries)
  install(TARGETS mylibapp
    RUNTIME
    DESTINATION bin
    COMPONENT applications)
  install(FILES mylib.h
    DESTINATION include
    COMPONENT headers)
 
Note that the COMPONENT argument to the INSTALL command is not new; it
has been a part of CMake's INSTALL command to allow installation of
only part of a project. If you are using any of the older installation
commands (INSTALL_TARGETS, INSTALL_FILES , etc.), you will need to
convert them to INSTALL commands to add the COMPONENT argument.
 
Finally, notify CPack of the names of all of the components in your
project by setting the CPACK_COMPONENTS_ALL variables:
 
  set(CPACK_COMPONENTS_ALL applications libraries headers)
 
At this point, you can build a component-based installer with CPack
that will allow one to independently install the applications,
libraries, and headers of MyLib.
 
[[Image:CPackComponentBasicWindows.JPG‎]][[Image:CPackComponentBasicMac.jpg‎]]
 
== Component Descriptions ==
 
If you have built a binary installer at this point, you may have noted
that the names of the actual components in the installer are not very
descriptive: they just say "applications", "libraries", or "headers",
as in the component names. We can improve on these names by setting
several additional CPack variables:
 
  set(CPACK_COMPONENT_APPLICATIONS_DISPLAY_NAME "MyLib Application")
  set(CPACK_COMPONENT_LIBRARIES_DISPLAY_NAME "Libraries")
  set(CPACK_COMPONENT_HEADERS_DISPLAY_NAME "C++ Headers")
 
Any macro prefixed with CPACK_COMPONENT_${COMPNAME}, where ${COMPNAME}
is the uppercase name of a component, is used to set a particular
property of that component in the installer. Here, we set the
DISPLAY_NAME property of each of our components, so that we get
human-readable names. These names will be listed in the selection box
rather than the internal component names "applications", "libraries",
"headers".
 
[[Image:CPackComponentNamesWindows.JPG‎]] [[Image:CPackComponentNamesMac.jpg]]
 
There are several other properties associated with components,
including the ability to make a component hidden, required, or
disabled by default, to provide additional descriptive information,
etc. We will encounter some of these other properties later; see the
macro reference for a complete list.
 
Of particular note is the DESCRIPTION property, which provides some
descriptive text for the component. This descriptive text will show up
in a separate "description" box in the installer, and will be updated
either when the user's mouse hovers over the name of the corresponding
component (Windows) or when the user clicks on a component (Mac OS
X). Here, we add a description for each of our components:
 
  set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION
    "An extremely useful application that makes use of MyLib")
  set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION
    "Static libraries used to build programs with MyLib")
  set(CPACK_COMPONENT_HEADERS_DESCRIPTION
    "C/C++ header files for use with MyLib")
 
Generally, descriptions should provide enough information for the user
to make a decision whether to include the component, but should not
themselves be more than a few lines long (because the "Description"
box in the installers tends to be small).
 
[[Image:CPackComponentDescWindows.JPG‎]][[Image:CPackComponentDescMac.jpg‎]]
 
== Intercomponent Dependencies ==
 
With most projects, the various components are not completely
independent. For example, an application component may depend on the
shared libraries in another component to execute properly, such that
installing the application component without the corresponding shared
libraries would result in an unusable installation. CPack allows you
to express the dependencies between components, so that a component
will only be installed if all of the other components it depends on
are also installed.
 
To illustrate component dependencies, we will place a simple
restriction on our component-based installer. Since we do not provide
source code in our installer, the C++ header files we distribute can
only actually be used if the user also installs the library binary to
link her program against. Thus, the "headers" component depends on the
availability of the "libraries" component. We can express this notion
by setting the DEPENDS property for the HEADERS component as such:
 
  set(CPACK_COMPONENT_HEADERS_DEPENDS libraries)
 
The DEPENDS property for a component is actually at list, and as such a
component can depend on several other components. By expressing all of
the component dependencies in this manner, you can ensure that users
will not be able to select an incomplete set of components at
installation time.
 
== Grouping Components ==
 
When the number of components in your project grows large, you may
need to provide additional organization for the list of components. To
help with this organization, CPack includes the notion of component
groups. A component group is, simply, a way to provide a name for a
group of related components. Within the user interface, a component
group has its own name, and underneath that group come all of the
names of the components within the group. Users will have the option
to (de-)select installation of all components in the group with a
single click, or expand the group to select individual components.
 
We will expand our example by categorizing its three components,
"applications", "libraries", and "headers", into "Runtime" and
"Development" groups. We place a component into a group by setting the
GROUP property of the component to the name of the group as follows:
 
  set(CPACK_COMPONENT_APPLICATIONS_GROUP "Runtime")
  set(CPACK_COMPONENT_LIBRARIES_GROUP "Development")
  set(CPACK_COMPONENT_HEADERS_GROUP "Development")
 
Like components, component groups have various properties that can be
customized, including the DISPLAY_NAME and DESCRIPTION. To customization
a component group, set the appropriate CPack macro with the prefix
CPACK_COMPONENT_GROUP_${GROUPNAME}, where ${GROUPNAME} is the
uppercase name of the group to modify. For example, the following code
adds a description to the "Development" group:
 
  set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION
    "All of the tools you'll ever need to develop software")
 
Once you have customized the component groups to your liking, rebuild
the binary installer to see the new organization: the MyLib
application will show up under the new "Runtime" group, while the
MyLib library and C++ header will show up under the new "Development"
group. One can easily turn on/off all of the components within a group
using the installer GUI. Some additional customizations of component
groups are possible; please see the macro reference for a complete
list.
 
[[Image:CPackComponentGroupsWindows.JPG]][[Image:CPackComponentGroupsMac.jpg‎]]
 
== Installation Types (NSIS Only) ==
 
When a project contains a large number of components, it is common for
a Windows installer to provide pre-selected sets of components based
on specific user needs. For example, a user wanting to develop
software against a library will want one set of components, while an
end user might use an entirely different set. CPack supports this
notion of pre-selected component sets via installation types. An
installation type is, simply, a set of components. When the user
selects an installation type, exactly that set of components is
selected---then the user is permitted to further customize the
installation as desired.
 
For our simple example, we will create only two installation types: a
"Full" installation type, which contains all of the components, and a
"Developer" installation type, which includes only the libraries and
headers. To do so, we first tell CPack which installation types we're
using:
 
  set(CPACK_ALL_INSTALL_TYPES Full Developer)
 
Like components and component groups, installation types have some
properties (e.g., DISPLAY_NAME), which can be set via variables with
prefix CPACK_INSTALL_TYPE_${INSTNAME}, where ${INSTNAME} is the
uppercase name of the installation type. See the macro reference for
additional information.
 
Next, we set the INSTALL_TYPES property of each component to state
which installation types will include that component:
 
  set(CPACK_COMPONENT_LIBRARIES_INSTALL_TYPES Developer Full)
  set(CPACK_COMPONENT_HEADERS_INSTALL_TYPES Developer Full)
  set(CPACK_COMPONENT_APPLICATIONS_INSTALL_TYPES Full)
 
Components can be in any number of installation types. If you now
rebuild the Windows installer, the components page will contain a
combo box that allows you to select the installation type and
therefore its corresponding set of components.
 
[[Image:CPackComponentsFinalWindows.JPG‎]]
 
== Next Steps ==
 
From here, you should be able to turn your existing CPack-generated
binary installers into component-based installers to provide your
users with more-flexible installation options. The complete example
constructed by this tutorial is available as [[Image:ComponentExample.zip]]. For
a more advanced example of a component-based installer build with
CPack, please visit the Boost-CMake project.
 
= Macro Reference =
 
In this reference, ${COMPNAME} refers to a component, ${GROUPNAME}
refers to a component group, and ${INSTNAME} refers to an installation
type, all of which are uppercase.
 
{|
|- bgcolor="#abcdef"
! Variable Name || Description
|-
| 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.
|-
|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.
|-
|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.
|-
|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.
|-
|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.
|-
|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.
|-
| 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.
|-
| 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.
|-
| 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.
|-
|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.
|-
| 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.
|-
| CPACK_COMPONENT_GROUP_${GROUPNAME}_BOLD_TITLE || Flag indicating whether the group title should be in bold. Only available with NSIS.
|-
| 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.
|-
| CPACK_INSTALL_TYPE_${INSTNAME}_DISPLAY_NAME || The displayed name of the installation type. This value can be any string.
|}
 
 
 
= Ideas for Future Development =
* 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.
* 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)
 
* Graphviz output of components and their dependencies?
 
{{CMake/Template/Footer}}

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.