code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakeBackwardCompatibilityCXX — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakeDependentOption" href="CMakeDependentOption.html" />
    <link rel="prev" title="CMakeAddFortranSubdirectory" href="CMakeAddFortranSubdirectory.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeBackwardCompatibilityCXX

CMakeBackwardCompatibilityCXX¶

define a bunch of backwards compatibility variables

CMAKE_ANSI_CXXFLAGS - flag for ansi c++
CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
include(TestForANSIStreamHeaders)
include(CheckIncludeFileCXX)
include(TestForSTDNamespace)
include(TestForANSIForScope)

Previous topic

CMakeAddFortranSubdirectory

Next topic

CMakeDependentOption

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeBackwardCompatibilityCXX

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakeDependentOption — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakeFindDependencyMacro" href="CMakeFindDependencyMacro.html" />
    <link rel="prev" title="CMakeBackwardCompatibilityCXX" href="CMakeBackwardCompatibilityCXX.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeDependentOption

CMakeDependentOption¶

Macro to provide an option dependent on other options.

This macro presents an option to the user only if a set of other
conditions are true.

cmake_dependent_option¶

cmake_dependent_option(<option> "<help_text>" <value> <depends> <force>)

Makes <option> available to the user if the
semicolon-separated list of conditions in
<depends> are all true.  Otherwise, a local variable named <option>
is set to <force>.

When <option> is available, the given <help_text> and initial
<value> are used. Otherwise, any value set by the user is preserved for
when <depends> is satisfied in the future.

Note that the <option> variable only has a value which satisfies the
<depends> condition within the scope of the caller because it is a local
variable.

Example invocation:

cmake_dependent_option(USE_FOO "Use Foo" ON "USE_BAR;NOT USE_ZOT" OFF)

If USE_BAR is true and USE_ZOT is false, this provides an option called
USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to OFF and
hides the option from the user. If the status of USE_BAR or USE_ZOT
ever changes, any value for the USE_FOO option is saved so that when the
option is re-enabled it retains its old value.

New in version 3.22: Full Condition Syntax is now supported.  See policy CMP0127.

Previous topic

CMakeBackwardCompatibilityCXX

Next topic

CMakeFindDependencyMacro

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeDependentOption

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakeDetermineVSServicePack — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakeExpandImportedTargets" href="CMakeExpandImportedTargets.html" />
    <link rel="prev" title="AddFileDependencies" href="AddFileDependencies.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeDetermineVSServicePack

CMakeDetermineVSServicePack¶

Deprecated since version 3.0: Do not use.

The functionality of this module has been superseded by the
CMAKE_<LANG>_COMPILER_VERSION variable that contains
the compiler version number.

Determine the Visual Studio service pack of the 'cl' in use.

Usage:

if(MSVC)
  include(CMakeDetermineVSServicePack)
  DetermineVSServicePack( my_service_pack )
  if( my_service_pack )
    message(STATUS "Detected: ${my_service_pack}")
  endif()
endif()

Function DetermineVSServicePack sets the given variable to one of the
following values or an empty string if unknown:

vc80, vc80sp1
vc90, vc90sp1
vc100, vc100sp1
vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4

Previous topic

AddFileDependencies

Next topic

CMakeExpandImportedTargets

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeDetermineVSServicePack

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakeExpandImportedTargets — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakeForceCompiler" href="CMakeForceCompiler.html" />
    <link rel="prev" title="CMakeDetermineVSServicePack" href="CMakeDetermineVSServicePack.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeExpandImportedTargets

CMakeExpandImportedTargets¶

Deprecated since version 3.4: Do not use.

This module was once needed to expand imported targets to the underlying
libraries they reference on disk for use with the try_compile()
and try_run() commands.  These commands now support imported
libraries in their LINK_LIBRARIES options (since CMake 2.8.11
for try_compile() and since CMake 3.2 for try_run()).

This module does not support the policy CMP0022 NEW
behavior or use of the INTERFACE_LINK_LIBRARIES property
because generator expressions
cannot be evaluated during configuration.

CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
                              [CONFIGURATION <config>])

CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
all imported targets contained in this list with their actual file
paths of the referenced libraries on disk, including the libraries
from their link interfaces.  If a CONFIGURATION is given, it uses the
respective configuration of the imported targets if it exists.  If no
CONFIGURATION is given, it uses the first configuration from
${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.

cmake_expand_imported_targets(expandedLibs
  LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
  CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )

Previous topic

CMakeDetermineVSServicePack

Next topic

CMakeForceCompiler

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeExpandImportedTargets

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakeFindDependencyMacro — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakeFindFrameworks" href="CMakeFindFrameworks.html" />
    <link rel="prev" title="CMakeDependentOption" href="CMakeDependentOption.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeFindDependencyMacro

CMakeFindDependencyMacro¶

find_dependency¶

The find_dependency() macro wraps a find_package() call for
a package dependency:

find_dependency(<dep> [...])

It is designed to be used in a
Package Configuration File
(<PackageName>Config.cmake).  find_dependency forwards the correct
parameters for QUIET and REQUIRED which were passed to
the original find_package() call.  Any additional arguments
specified are forwarded to find_package().

If the dependency could not be found it sets an informative diagnostic
message and calls return() to end processing of the calling
package configuration file and return to the find_package()
command that loaded it.

Note

The call to return() makes this macro unsuitable to call
from Find Modules.

Package Dependency Search Optimizations¶

If find_dependency is called with arguments identical to a previous
call in the same directory, perhaps due to diamond-shaped package
dependencies, the underlying call to find_package() is optimized
out.  This optimization is important to support large package dependency
graphs while avoiding a combinatorial explosion of repeated searches.
However, the heuristic cannot account for ambient variables that
affect package behavior, such as <PackageName>_USE_STATIC_LIBS,
offered by some packages.  Therefore package configuration files should
avoid setting such variables before their calls to find_dependency.

Changed in version 3.15: Previously, the underlying call to find_package() was always
optimized out if the package had already been found.  CMake 3.15
removed the optimization to support cases in which find_dependency
call arguments request different components.

Changed in version 3.26: The pre-3.15 optimization was restored, but with the above-described
heuristic to account for varying find_dependency call arguments.

Table of Contents

CMakeFindDependencyMacro

Package Dependency Search Optimizations

Previous topic

CMakeDependentOption

Next topic

CMakeFindFrameworks

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeFindDependencyMacro

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakeFindFrameworks — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakeFindPackageMode" href="CMakeFindPackageMode.html" />
    <link rel="prev" title="CMakeFindDependencyMacro" href="CMakeFindDependencyMacro.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeFindFrameworks

CMakeFindFrameworks¶

helper module to find OSX frameworks

This module reads hints about search locations from variables:

CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories

Previous topic

CMakeFindDependencyMacro

Next topic

CMakeFindPackageMode

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeFindFrameworks

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakeFindPackageMode — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakeGraphVizOptions" href="CMakeGraphVizOptions.html" />
    <link rel="prev" title="CMakeFindFrameworks" href="CMakeFindFrameworks.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeFindPackageMode

CMakeFindPackageMode¶

This file is executed by cmake when invoked with
--find-package.
It expects that the following variables are set using -D:

NAME

name of the package

COMPILER_ID

the CMake compiler ID for which the result is,
i.e. GNU/Intel/Clang/MSVC, etc.

LANGUAGE

language for which the result will be used,
i.e. C/CXX/Fortran/ASM

MODE

EXIST

only check for existence of the given package

COMPILE

print the flags needed for compiling an object file which uses
the given package

LINK

print the flags needed for linking when using the given package

QUIET

if TRUE, don't print anything

Previous topic

CMakeFindFrameworks

Next topic

CMakeGraphVizOptions

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeFindPackageMode

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakeForceCompiler — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakeParseArguments" href="CMakeParseArguments.html" />
    <link rel="prev" title="CMakeExpandImportedTargets" href="CMakeExpandImportedTargets.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeForceCompiler

CMakeForceCompiler¶

Deprecated since version 3.6: Do not use.

The macros provided by this module were once intended for use by
cross-compiling toolchain files when CMake was not able to automatically
detect the compiler identification.  Since the introduction of this module,
CMake's compiler identification capabilities have improved and can now be
taught to recognize any compiler.  Furthermore, the suite of information
CMake detects from a compiler is now too extensive to be provided by
toolchain files using these macros.

One common use case for this module was to skip CMake's checks for a
working compiler when using a cross-compiler that cannot link binaries
without special flags or custom linker scripts.  This case is now supported
by setting the CMAKE_TRY_COMPILE_TARGET_TYPE variable in the
toolchain file instead.

Macro CMAKE_FORCE_C_COMPILER has the following signature:

CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)

It sets CMAKE_C_COMPILER to
the given compiler and the cmake internal variable
CMAKE_C_COMPILER_ID to the given
compiler-id.  It also bypasses the check for working compiler and basic
compiler information tests.

Macro CMAKE_FORCE_CXX_COMPILER has the following signature:

CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)

It sets CMAKE_CXX_COMPILER to
the given compiler and the cmake internal variable
CMAKE_CXX_COMPILER_ID to the given
compiler-id.  It also bypasses the check for working compiler and basic
compiler information tests.

Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:

CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)

It sets CMAKE_Fortran_COMPILER to
the given compiler and the cmake internal variable
CMAKE_Fortran_COMPILER_ID to the given
compiler-id.  It also bypasses the check for working compiler and basic
compiler information tests.

So a simple toolchain file could look like this:

include (CMakeForceCompiler)
set(CMAKE_SYSTEM_NAME Generic)
CMAKE_FORCE_C_COMPILER   (chc12 MetrowerksHicross)
CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)

Previous topic

CMakeExpandImportedTargets

Next topic

CMakeParseArguments

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeForceCompiler

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakeGraphVizOptions — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakePackageConfigHelpers" href="CMakePackageConfigHelpers.html" />
    <link rel="prev" title="CMakeFindPackageMode" href="CMakeFindPackageMode.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeGraphVizOptions

CMakeGraphVizOptions¶

The builtin Graphviz support of CMake.

Generating Graphviz files¶

CMake can generate Graphviz files showing the
dependencies between the targets in a project, as well as external libraries
which are linked against.

When running CMake with the --graphviz=foo.dot option, it produces:

a foo.dot file, showing all dependencies in the project

a foo.dot.<target> file for each target, showing on which other targets
it depends

a foo.dot.<target>.dependers file for each target, showing which other
targets depend on it

Those .dot files can be converted to images using the dot command from the
Graphviz package:

dot -Tpng -o foo.png foo.dot

New in version 3.10: The different dependency types PUBLIC, INTERFACE and PRIVATE
are represented as solid, dashed and dotted edges.

Variables specific to the Graphviz support¶

The resulting graphs can be huge.  The look and content of the generated graphs
can be controlled using the file CMakeGraphVizOptions.cmake.  This file is
first searched in CMAKE_BINARY_DIR, and then in
CMAKE_SOURCE_DIR.  If found, the variables set in it are used to
adjust options for the generated Graphviz files.

GRAPHVIZ_GRAPH_NAME¶

The graph name.

Mandatory: NO

Default: value of CMAKE_PROJECT_NAME

GRAPHVIZ_GRAPH_HEADER¶

The header written at the top of the Graphviz files.

Mandatory: NO

Default: "node [ fontsize = "12" ];"

GRAPHVIZ_NODE_PREFIX¶

The prefix for each node in the Graphviz files.

Mandatory: NO

Default: "node"

GRAPHVIZ_EXECUTABLES¶

Set to FALSE to exclude executables from the generated graphs.

Mandatory: NO

Default: TRUE

GRAPHVIZ_STATIC_LIBS¶

Set to FALSE to exclude static libraries from the generated graphs.

Mandatory: NO

Default: TRUE

GRAPHVIZ_SHARED_LIBS¶

Set to FALSE to exclude shared libraries from the generated graphs.

Mandatory: NO

Default: TRUE

GRAPHVIZ_MODULE_LIBS¶

Set to FALSE to exclude module libraries from the generated graphs.

Mandatory: NO

Default: TRUE

GRAPHVIZ_INTERFACE_LIBS¶

Set to FALSE to exclude interface libraries from the generated graphs.

Mandatory: NO

Default: TRUE

GRAPHVIZ_OBJECT_LIBS¶

Set to FALSE to exclude object libraries from the generated graphs.

Mandatory: NO

Default: TRUE

GRAPHVIZ_UNKNOWN_LIBS¶

Set to FALSE to exclude unknown libraries from the generated graphs.

Mandatory: NO

Default: TRUE

GRAPHVIZ_EXTERNAL_LIBS¶

Set to FALSE to exclude external libraries from the generated graphs.

Mandatory: NO

Default: TRUE

GRAPHVIZ_CUSTOM_TARGETS¶

Set to TRUE to include custom targets in the generated graphs.

Mandatory: NO

Default: FALSE

GRAPHVIZ_IGNORE_TARGETS¶

A list of regular expressions for names of targets to exclude from the
generated graphs.

Mandatory: NO

Default: empty

GRAPHVIZ_GENERATE_PER_TARGET¶

Set to FALSE to not generate per-target graphs foo.dot.<target>.

Mandatory: NO

Default: TRUE

GRAPHVIZ_GENERATE_DEPENDERS¶

Set to FALSE to not generate depender graphs foo.dot.<target>.dependers.

Mandatory: NO

Default: TRUE

Table of Contents

CMakeGraphVizOptions

Generating Graphviz files

Variables specific to the Graphviz support

Previous topic

CMakeFindPackageMode

Next topic

CMakePackageConfigHelpers

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeGraphVizOptions

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakePackageConfigHelpers — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakePrintHelpers" href="CMakePrintHelpers.html" />
    <link rel="prev" title="CMakeGraphVizOptions" href="CMakeGraphVizOptions.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakePackageConfigHelpers

CMakePackageConfigHelpers¶

Helpers functions for creating config files that can be included by other
projects to find and use a package.

Generating a Package Configuration File¶

configure_package_config_file¶

Create a config file for a project:

configure_package_config_file(<input> <output>
  INSTALL_DESTINATION <path>
  [PATH_VARS <var1> <var2> ... <varN>]
  [NO_SET_AND_CHECK_MACRO]
  [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
  [INSTALL_PREFIX <path>]
  )

configure_package_config_file() should be used instead of the plain
configure_file() command when creating the <PackageName>Config.cmake
or <PackageName>-config.cmake file for installing a project or library.
It helps making the resulting package relocatable by avoiding hardcoded paths
in the installed Config.cmake file.

In a FooConfig.cmake file there may be code like this to make the install
destinations know to the using project:

set(FOO_INCLUDE_DIR   "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
set(FOO_DATA_DIR   "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
set(FOO_ICONS_DIR   "@CMAKE_INSTALL_PREFIX@/share/icons" )
#...logic to determine installedPrefix from the own location...
set(FOO_CONFIG_DIR  "${installedPrefix}/@CONFIG_INSTALL_DIR@" )

All 4 options shown above are not sufficient, since the first 3 hardcode the
absolute directory locations, and the 4th case works only if the logic to
determine the installedPrefix is correct, and if CONFIG_INSTALL_DIR
contains a relative path, which in general cannot be guaranteed.  This has the
effect that the resulting FooConfig.cmake file would work poorly under
Windows and OSX, where users are used to choose the install location of a
binary package at install time, independent from how
CMAKE_INSTALL_PREFIX was set at build/cmake time.

Using configure_package_config_file helps.  If used correctly, it makes
the resulting FooConfig.cmake file relocatable.  Usage:

write a FooConfig.cmake.in file as you are used to

insert a line containing only the string @PACKAGE_INIT@

instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use
set(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@") (this must be after the
@PACKAGE_INIT@ line)

instead of using the normal configure_file(), use
configure_package_config_file()

The <input> and <output> arguments are the input and output file, the
same way as in configure_file().

The <path> given to INSTALL_DESTINATION must be the destination where
the FooConfig.cmake file will be installed to.  This path can either be
absolute, or relative to the INSTALL_PREFIX path.

The variables <var1> to <varN> given as PATH_VARS are the
variables which contain install destinations.  For each of them the macro will
create a helper variable PACKAGE_<var...>.  These helper variables must be
used in the FooConfig.cmake.in file for setting the installed location.
They are calculated by configure_package_config_file so that they are
always relative to the installed location of the package.  This works both for
relative and also for absolute locations.  For absolute locations it works
only if the absolute location is a subdirectory of INSTALL_PREFIX.

New in version 3.1: If the INSTALL_PREFIX argument is passed, this is used as base path to
calculate all the relative paths.  The <path> argument must be an absolute
path.  If this argument is not passed, the CMAKE_INSTALL_PREFIX
variable will be used instead.  The default value is good when generating a
FooConfig.cmake file to use your package from the install tree.  When
generating a FooConfig.cmake file to use your package from the build tree this
option should be used.

By default configure_package_config_file also generates two helper macros,
set_and_check() and check_required_components() into the
FooConfig.cmake file.

set_and_check() should be used instead of the normal set() command for
setting directories and file locations.  Additionally to setting the variable
it also checks that the referenced file or directory actually exists and fails
with a FATAL_ERROR otherwise.  This makes sure that the created
FooConfig.cmake file does not contain wrong references.
When using the NO_SET_AND_CHECK_MACRO, this macro is not generated
into the FooConfig.cmake file.

check_required_components(<PackageName>) should be called at the end of
the FooConfig.cmake file. This macro checks whether all requested,
non-optional components have been found, and if this is not the case, sets
the Foo_FOUND variable to FALSE, so that the package is considered to
be not found.  It does that by testing the Foo_<Component>_FOUND
variables for all requested required components.  This macro should be
called even if the package doesn't provide any components to make sure
users are not specifying components erroneously.  When using the
NO_CHECK_REQUIRED_COMPONENTS_MACRO option, this macro is not generated
into the FooConfig.cmake file.

For an example see below the documentation for
write_basic_package_version_file().

Generating a Package Version File¶

write_basic_package_version_file¶

Create a version file for a project:

write_basic_package_version_file(<filename>
  [VERSION <major.minor.patch>]
  COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
  [ARCH_INDEPENDENT] )

Writes a file for use as <PackageName>ConfigVersion.cmake file to
<filename>.  See the documentation of find_package() for
details on this.

<filename> is the output filename, it should be in the build tree.
<major.minor.patch> is the version number of the project to be installed.

If no VERSION is given, the PROJECT_VERSION variable is used.
If this hasn't been set, it errors out.

The COMPATIBILITY mode AnyNewerVersion means that the installed
package version will be considered compatible if it is newer or exactly the
same as the requested version.  This mode should be used for packages which
are fully backward compatible, also across major versions.
If SameMajorVersion is used instead, then the behavior differs from
AnyNewerVersion in that the major version number must be the same as
requested, e.g.  version 2.0 will not be considered compatible if 1.0 is
requested.  This mode should be used for packages which guarantee backward
compatibility within the same major version.
If SameMinorVersion is used, the behavior is the same as
SameMajorVersion, but both major and minor version must be the same as
requested, e.g version 0.2 will not be compatible if 0.1 is requested.
If ExactVersion is used, then the package is only considered compatible if
the requested version matches exactly its own version number (not considering
the tweak version).  For example, version 1.2.3 of a package is only
considered compatible to requested version 1.2.3.  This mode is for packages
without compatibility guarantees.
If your project has more elaborated version matching rules, you will need to
write your own custom ConfigVersion.cmake file instead of using this
macro.

New in version 3.11: The SameMinorVersion compatibility mode.

New in version 3.14: If ARCH_INDEPENDENT is given, the installed package version will be
considered compatible even if it was built for a different architecture than
the requested architecture.  Otherwise, an architecture check will be performed,
and the package will be considered compatible only if the architecture matches
exactly.  For example, if the package is built for a 32-bit architecture, the
package is only considered compatible if it is used on a 32-bit architecture,
unless ARCH_INDEPENDENT is given, in which case the package is considered
compatible on any architecture.

Note

ARCH_INDEPENDENT is intended for header-only libraries or similar
packages with no binaries.

New in version 3.19: The version file generated by AnyNewerVersion, SameMajorVersion and
SameMinorVersion arguments of COMPATIBILITY handle the version range
if any is specified (see find_package() command for the details).
ExactVersion mode is incompatible with version ranges and will display an
author warning if one is specified.

Internally, this macro executes configure_file() to create the
resulting version file.  Depending on the COMPATIBILITY, the corresponding
BasicConfigVersion-<COMPATIBILITY>.cmake.in file is used.
Please note that these files are internal to CMake and you should not call
configure_file() on them yourself, but they can be used as starting
point to create more sophisticated custom ConfigVersion.cmake files.

Generating an Apple Platform Selection File¶

generate_apple_platform_selection_file¶

New in version 3.29.

Create an Apple platform selection file:

generate_apple_platform_selection_file(<filename>
  INSTALL_DESTINATION <path>
  [INSTALL_PREFIX <path>]
  [MACOS_INCLUDE_FILE <file>]
  [IOS_INCLUDE_FILE <file>]
  [IOS_SIMULATOR_INCLUDE_FILE <file>]
  [TVOS_INCLUDE_FILE <file>]
  [TVOS_SIMULATOR_INCLUDE_FILE <file>]
  [WATCHOS_INCLUDE_FILE <file>]
  [WATCHOS_SIMULATOR_INCLUDE_FILE <file>]
  [VISIONOS_INCLUDE_FILE <file>]
  [VISIONOS_SIMULATOR_INCLUDE_FILE <file>]
  )

Write a file that includes an Apple-platform-specific .cmake file,
e.g., for use as <PackageName>Config.cmake.  This can be used in
conjunction with the XCFRAMEWORK_LOCATION argument of
export(SETUP) to export packages in a way that a project
built for any Apple platform can use them.

INSTALL_DESTINATION <path>

Path to which the generated file will be installed by the caller, e.g.,
via install(FILES).  The path may be either relative to the
INSTALL_PREFIX or absolute.

INSTALL_PREFIX <path>

Path prefix to which the package will be installed by the caller.
The <path> argument must be an absolute path.  If this argument
is not passed, the CMAKE_INSTALL_PREFIX variable will be
used instead.

MACOS_INCLUDE_FILE <file>

File to include if the platform is macOS.

IOS_INCLUDE_FILE <file>

File to include if the platform is iOS.

IOS_SIMULATOR_INCLUDE_FILE <file>

File to include if the platform is iOS Simulator.

TVOS_INCLUDE_FILE <file>

File to include if the platform is tvOS.

TVOS_SIMULATOR_INCLUDE_FILE <file>

File to include if the platform is tvOS Simulator.

WATCHOS_INCLUDE_FILE <file>

File to include if the platform is watchOS.

WATCHOS_SIMULATOR_INCLUDE_FILE <file>

File to include if the platform is watchOS Simulator.

VISIONOS_INCLUDE_FILE <file>

File to include if the platform is visionOS.

VISIONOS_SIMULATOR_INCLUDE_FILE <file>

File to include if the platform is visionOS Simulator.

If any of the optional include files is not specified, and the consuming
project is built for its corresponding platform, an error will be thrown
when including the generated file.

generate_apple_architecture_selection_file¶

New in version 3.29.

Create an Apple architecture selection file:

generate_apple_architecture_selection_file(<filename>
  INSTALL_DESTINATION <path>
  [INSTALL_PREFIX <path>]
  [SINGLE_ARCHITECTURES <archs>
   SINGLE_ARCHITECTURE_INCLUDE_FILES <files>]
  [UNIVERSAL_ARCHITECTURES <archs>
   UNIVERSAL_INCLUDE_FILE <file>]
  )

Write a file that includes an Apple-architecture-specific .cmake file
based on CMAKE_OSX_ARCHITECTURES, e.g., for inclusion from an
Apple-specific <PackageName>Config.cmake file.

INSTALL_DESTINATION <path>

Path to which the generated file will be installed by the caller, e.g.,
via install(FILES).  The path may be either relative to the
INSTALL_PREFIX or absolute.

INSTALL_PREFIX <path>

Path prefix to which the package will be installed by the caller.
The <path> argument must be an absolute path.  If this argument
is not passed, the CMAKE_INSTALL_PREFIX variable will be
used instead.

SINGLE_ARCHITECTURES <archs>

A semicolon-separated list of
architectures provided by entries of
SINGLE_ARCHITECTURE_INCLUDE_FILES.

SINGLE_ARCHITECTURE_INCLUDE_FILES <files>

A semicolon-separated list of
architecture-specific files.  One of them will be loaded
when CMAKE_OSX_ARCHITECTURES contains a single
architecture matching the corresponding entry of
SINGLE_ARCHITECTURES.

UNIVERSAL_ARCHITECTURES <archs>

A semicolon-separated list of
architectures provided by the UNIVERSAL_INCLUDE_FILE.

UNIVERSAL_INCLUDE_FILE <file>

A file to load when CMAKE_OSX_ARCHITECTURES contains
a (non-strict) subset of the UNIVERSAL_ARCHITECTURES and
does not match any one of the SINGLE_ARCHITECTURES.

Example Generating Package Files¶

Example using both configure_package_config_file() and
write_basic_package_version_file():

CMakeLists.txt:

include(GNUInstallDirs)
set(INCLUDE_INSTALL_DIR ${CMAKE_INSTALL_INCLUDEDIR}/Foo
    CACHE PATH "Location of header files" )
set(SYSCONFIG_INSTALL_DIR ${CMAKE_INSTALL_SYSCONFDIR}/foo
    CACHE PATH "Location of configuration files" )
#...
include(CMakePackageConfigHelpers)
configure_package_config_file(FooConfig.cmake.in
  ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
  INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Foo
  PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
write_basic_package_version_file(
  ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
  VERSION 1.2.3
  COMPATIBILITY SameMajorVersion )
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
              ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Foo )

FooConfig.cmake.in:

set(FOO_VERSION x.y.z)
...
@PACKAGE_INIT@
...
set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")

check_required_components(Foo)

Table of Contents

CMakePackageConfigHelpers

Generating a Package Configuration File

Generating a Package Version File

Generating an Apple Platform Selection File

Example Generating Package Files

Previous topic

CMakeGraphVizOptions

Next topic

CMakePrintHelpers

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakePackageConfigHelpers

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakeParseArguments — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Dart" href="Dart.html" />
    <link rel="prev" title="CMakeForceCompiler" href="CMakeForceCompiler.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeParseArguments

CMakeParseArguments¶

This module once implemented the cmake_parse_arguments() command
that is now implemented natively by CMake.  It is now an empty placeholder
for compatibility with projects that include it to get the command from
CMake 3.4 and lower.

Previous topic

CMakeForceCompiler

Next topic

Dart

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeParseArguments

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakePrintHelpers — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakePrintSystemInformation" href="CMakePrintSystemInformation.html" />
    <link rel="prev" title="CMakePackageConfigHelpers" href="CMakePackageConfigHelpers.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakePrintHelpers

CMakePrintHelpers¶

Convenience functions for printing properties and variables, useful
e.g. for debugging.

cmake_print_properties(<TARGETS       [<target1> ...] |
                        SOURCES       [<source1> ...] |
                        DIRECTORIES   [<dir1> ...]    |
                        TESTS         [<test1> ...]   |
                        CACHE_ENTRIES [<entry1> ...]  >
                       PROPERTIES [<prop1> ...]         )

This function prints the values of the properties of the given targets,
source files, directories, tests or cache entries.  Exactly one of the
scope keywords must be used.  The scope keyword and its arguments must
come before the PROPERTIES keyword, in the arguments list.

Example:

cmake_print_properties(TARGETS foo bar PROPERTIES
                       LOCATION INTERFACE_INCLUDE_DIRECTORIES)

This will print the LOCATION and INTERFACE_INCLUDE_DIRECTORIES properties for
both targets foo and bar.

cmake_print_variables(var1 var2 ..  varN)

This function will print the name of each variable followed by its value.
Example:

cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)

Gives:

-- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""

Previous topic

CMakePackageConfigHelpers

Next topic

CMakePrintSystemInformation

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakePrintHelpers

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakePrintSystemInformation — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakePushCheckState" href="CMakePushCheckState.html" />
    <link rel="prev" title="CMakePrintHelpers" href="CMakePrintHelpers.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakePrintSystemInformation

CMakePrintSystemInformation¶

Print system information.

This module serves diagnostic purposes. Just include it in a
project to see various internal CMake variables.

Previous topic

CMakePrintHelpers

Next topic

CMakePushCheckState

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakePrintSystemInformation

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakePushCheckState — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakeVerifyManifest" href="CMakeVerifyManifest.html" />
    <link rel="prev" title="CMakePrintSystemInformation" href="CMakePrintSystemInformation.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakePushCheckState

CMakePushCheckState¶

This module defines three macros: CMAKE_PUSH_CHECK_STATE()
CMAKE_POP_CHECK_STATE() and CMAKE_RESET_CHECK_STATE() These macros can
be used to save, restore and reset (i.e., clear contents) the state of
the variables CMAKE_REQUIRED_FLAGS, CMAKE_REQUIRED_DEFINITIONS,
CMAKE_REQUIRED_LINK_OPTIONS, CMAKE_REQUIRED_LIBRARIES,
CMAKE_REQUIRED_INCLUDES and CMAKE_EXTRA_INCLUDE_FILES used by the
various Check-files coming with CMake, like e.g. check_function_exists()
etc.
The variable contents are pushed on a stack, pushing multiple times is
supported.  This is useful e.g.  when executing such tests in a Find-module,
where they have to be set, but after the Find-module has been executed they
should have the same value as they had before.

CMAKE_PUSH_CHECK_STATE() macro receives optional argument RESET.
Whether it's specified, CMAKE_PUSH_CHECK_STATE() will set all
CMAKE_REQUIRED_* variables to empty values, same as
CMAKE_RESET_CHECK_STATE() call will do.

Usage:

cmake_push_check_state(RESET)
set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
check_function_exists(...)
cmake_reset_check_state()
set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
check_function_exists(...)
cmake_pop_check_state()

Previous topic

CMakePrintSystemInformation

Next topic

CMakeVerifyManifest

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakePushCheckState

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMakeVerifyManifest — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CPack" href="CPack.html" />
    <link rel="prev" title="CMakePushCheckState" href="CMakePushCheckState.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeVerifyManifest

CMakeVerifyManifest¶

CMakeVerifyManifest.cmake

This script is used to verify that embedded manifests and side by side
manifests for a project match.  To run this script, cd to a directory
and run the script with cmake -P.  On the command line you can pass in
versions that are OK even if not found in the .manifest files.  For
example, cmake -Dallow_versions=8.0.50608.0
-PCmakeVerifyManifest.cmake could be used to allow an embedded manifest
of 8.0.50608.0 to be used in a project even if that version was not
found in the .manifest file.

Previous topic

CMakePushCheckState

Next topic

CPack

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CMakeVerifyManifest

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CPack — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CPackComponent" href="CPackComponent.html" />
    <link rel="prev" title="CMakeVerifyManifest" href="CMakeVerifyManifest.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPack

CPack¶

Configure generators for binary installers and source packages.

Introduction¶

The CPack module generates the configuration files CPackConfig.cmake
and CPackSourceConfig.cmake. They are intended for use in a subsequent
run of  the cpack program where they steer the generation
of installers or/and source packages.

Depending on the CMake generator, the CPack module may also add two new build
targets, package and package_source. See the packaging targets
section below for details.

The generated binary installers will contain all files that have been installed
via CMake's install() command (and the deprecated commands
install_files(), install_programs(), and
install_targets()). Note that the DESTINATION option of the
install() command must be a relative path; otherwise installed files
are ignored by CPack.

Certain kinds of binary installers can be configured such that users can select
individual application components to install.  See the CPackComponent
module for further details.

Source packages (configured through CPackSourceConfig.cmake and generated
by the CPack Archive Generator) will contain all source files in
the project directory except those specified in
CPACK_SOURCE_IGNORE_FILES.

CPack Generators¶

The CPACK_GENERATOR variable has different meanings in different
contexts.  In a CMakeLists.txt file, CPACK_GENERATOR is a
list of generators: and when cpack is run with no other
arguments, it will iterate over that list and produce one package for each
generator.  In a CPACK_PROJECT_CONFIG_FILE,
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.
If set, the CPACK_PROJECT_CONFIG_FILE is included automatically
on a per-generator basis.  It only need contain overrides.

Here's how it works:

cpack runs

it includes CPackConfig.cmake

it iterates over the generators given by the -G command
line option, or if no such option was specified, over the list of generators
given by the CPACK_GENERATOR variable set in the CPackConfig.cmake
input file.

foreach generator, it then

sets CPACK_GENERATOR to the one currently being iterated

includes the CPACK_PROJECT_CONFIG_FILE

produces the package for that generator

This is the key: For each generator listed in CPACK_GENERATOR in
CPackConfig.cmake, cpack will reset CPACK_GENERATOR
internally to the one currently being used and then include the
CPACK_PROJECT_CONFIG_FILE.

For a list of available generators, see cpack-generators(7).

Targets package and package_source¶

If CMake is run with the Makefile, Ninja, or Xcode generator, then
include(CPack) generates a target package. This makes it possible
to build a binary installer from CMake, Make, or Ninja: Instead of cpack,
one may call cmake --build . --target package or make package or
ninja package. The VS generator creates an uppercase target PACKAGE.

If CMake is run with the Makefile or Ninja generator, then include(CPack)
also generates a target package_source. To build a source package,
instead of cpack -G TGZ --config CPackSourceConfig.cmake one may call
cmake --build . --target package_source, make package_source,
or ninja package_source.

Variables common to all CPack Generators¶

Before including this CPack module in your CMakeLists.txt file, there
are a variety of variables that can be set to customize the resulting
installers.  The most commonly-used variables are:

CPACK_PACKAGE_NAME¶

The name of the package (or application).  If not specified, it defaults to
the project name.

CPACK_PACKAGE_VENDOR¶

The name of the package vendor. (e.g., "Kitware").  The default is "Humanity".

CPACK_PACKAGE_DIRECTORY¶

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

CPACK_PACKAGE_VERSION_MAJOR¶

Package major version.  This variable will always be set, but its default
value depends on whether or not version details were given to the
project() command in the top level CMakeLists.txt file.  If version
details were given, the default value will be
CMAKE_PROJECT_VERSION_MAJOR.  If no version details were given,
a default version of 0.1.1 will be assumed, leading to
CPACK_PACKAGE_VERSION_MAJOR having a default value of 0.

CPACK_PACKAGE_VERSION_MINOR¶

Package minor version.  The default value is determined based on whether or
not version details were given to the project() command in the top
level CMakeLists.txt file.  If version details were given, the default
value will be CMAKE_PROJECT_VERSION_MINOR, but if no minor
version component was specified then CPACK_PACKAGE_VERSION_MINOR will be
left unset.  If no project version was given at all, a default version of
0.1.1 will be assumed, leading to CPACK_PACKAGE_VERSION_MINOR having a
default value of 1.

CPACK_PACKAGE_VERSION_PATCH¶

Package patch version.  The default value is determined based on whether or
not version details were given to the project() command in the top
level CMakeLists.txt file.  If version details were given, the default
value will be CMAKE_PROJECT_VERSION_PATCH, but if no patch
version component was specified then CPACK_PACKAGE_VERSION_PATCH will be
left unset.  If no project version was given at all, a default version of
0.1.1 will be assumed, leading to CPACK_PACKAGE_VERSION_PATCH having a
default value of 1.

CPACK_PACKAGE_DESCRIPTION¶

A description of the project, used in places such as the introduction
screen of CPack-generated Windows installers.  If not set, the value of
this variable is populated from the file named by
CPACK_PACKAGE_DESCRIPTION_FILE.

CPACK_PACKAGE_DESCRIPTION_FILE¶

A text file used to describe the project when
CPACK_PACKAGE_DESCRIPTION is not explicitly set.  The default
value for CPACK_PACKAGE_DESCRIPTION_FILE points to a built-in template
file Templates/CPack.GenericDescription.txt.

CPACK_PACKAGE_DESCRIPTION_SUMMARY¶

Short description of the project (only a few words).  If the
CMAKE_PROJECT_DESCRIPTION variable is set, it is used as the
default value, otherwise the default will be a string generated by CMake
based on CMAKE_PROJECT_NAME.

CPACK_PACKAGE_HOMEPAGE_URL¶

Project homepage URL.  The default value is taken from the
CMAKE_PROJECT_HOMEPAGE_URL variable, which is set by the top
level project() command, or else the default will be empty if no
URL was provided to project().

CPACK_PACKAGE_FILE_NAME¶

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

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

CPACK_PACKAGE_INSTALL_DIRECTORY¶

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

CPACK_PACKAGE_ICON¶

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

CPACK_PACKAGE_CHECKSUM¶

New in version 3.7.

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

${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}

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

CPACK_PROJECT_CONFIG_FILE¶

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

CPACK_RESOURCE_FILE_LICENSE¶

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

CPACK_RESOURCE_FILE_README¶

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

CPACK_RESOURCE_FILE_WELCOME¶

Welcome file to be embedded in the installer.  It welcomes users to this
installer.  Typically used in the graphical installers on Windows and Mac
OS X.

CPACK_MONOLITHIC_INSTALL¶

Disables the component-based installation mechanism.  When set, the
component specification is ignored and all installed items are put in a
single "MONOLITHIC" package.  Some CPack generators do monolithic
packaging by default and may be asked to do component packaging by
setting CPACK_<GENNAME>_COMPONENT_INSTALL to TRUE.

CPACK_GENERATOR¶

List of CPack generators to use.  If not specified, CPack will create a
set of options following the naming pattern
CPACK_BINARY_<GENNAME> (e.g. CPACK_BINARY_NSIS) allowing
the user to enable/disable individual generators.  If the -G
option is given on the cpack command line, it will override
this variable and any CPACK_BINARY_<GENNAME> options.

CPACK_OUTPUT_CONFIG_FILE¶

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

CPACK_PACKAGE_EXECUTABLES¶

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

CPACK_STRIP_FILES¶

List of files to be stripped.  Starting with CMake 2.6.0,
CPACK_STRIP_FILES will be a boolean variable which enables
stripping of all files (a list of files evaluates to TRUE in CMake,
so this change is compatible).

CPACK_VERBATIM_VARIABLES¶

New in version 3.4.

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

CPACK_THREADS¶

New in version 3.20.

Number of threads to use when performing parallelized operations, such
as compressing the installer package.

Some compression methods used by CPack generators such as Debian or Archive
may take advantage of multiple CPU cores to speed up compression.
CPACK_THREADS can be set to specify how many threads will be
used for compression.

A positive integer can be used to specify an exact desired thread count.

When given a negative integer CPack will use the absolute value
as the upper limit but may choose a lower value based on
the available hardware concurrency.

Given 0 CPack will try to use all available CPU cores.

By default CPACK_THREADS is set to 1.

The following compression methods may take advantage of multiple cores:

xz

Supported if CMake is built with a liblzma that supports
parallel compression.

New in version 3.21: Official CMake binaries available on cmake.org now ship
with a liblzma that supports parallel compression.
Older versions did not.

zstd

New in version 3.24.

Supported if CMake is built with libarchive 3.6 or higher.
Official CMake binaries available on cmake.org support it.

Other compression methods ignore this value and use only one thread.

Variables for Source Package Generators¶

The following CPack variables are specific to source packages, and
will not affect binary packages:

CPACK_SOURCE_PACKAGE_FILE_NAME¶

The name of the source package.  For example cmake-2.6.1.

CPACK_SOURCE_STRIP_FILES¶

List of files in the source tree that will be stripped.  Starting with
CMake 2.6.0, CPACK_SOURCE_STRIP_FILES will be a boolean
variable which enables stripping of all files (a list of files evaluates
to TRUE in CMake, so this change is compatible).

CPACK_SOURCE_GENERATOR¶

List of generators used for the source packages.  As with
CPACK_GENERATOR, if this is not specified then CPack will
create a set of options (e.g. CPACK_SOURCE_ZIP) allowing
users to select which packages will be generated.

CPACK_SOURCE_OUTPUT_CONFIG_FILE¶

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

CPACK_SOURCE_IGNORE_FILES¶

Pattern of files in the source tree that won't be packaged when building
a source package.  This is a list of regular expression patterns (that
must be properly escaped), e.g.,
/CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*

Variables for Advanced Use¶

The following variables are for advanced uses of CPack:

CPACK_CMAKE_GENERATOR¶

What CMake generator should be used if the project is a CMake
project.  Defaults to the value of CMAKE_GENERATOR.  Few users
will want to change this setting.

CPACK_INSTALL_CMAKE_PROJECTS¶

List of four values that specify what project to install.  The four values
are: Build directory, Project Name, Project Component, Directory.  If
omitted, CPack will build an installer that installs everything.

CPACK_SYSTEM_NAME¶

System name, defaults to the value of CMAKE_SYSTEM_NAME,
except on Windows where it will be win32 or win64.

CPACK_PACKAGE_VERSION¶

Package full version, used internally.  By default, this is built from
CPACK_PACKAGE_VERSION_MAJOR,
CPACK_PACKAGE_VERSION_MINOR, and
CPACK_PACKAGE_VERSION_PATCH.

CPACK_TOPLEVEL_TAG¶

Directory for the installed files.

CPACK_INSTALL_COMMANDS¶

Extra commands to install components.  The environment variable
CMAKE_INSTALL_PREFIX is set to the temporary install directory
during execution.

CPACK_INSTALL_SCRIPTS¶

New in version 3.16.

Extra CMake scripts executed by CPack during its local staging
installation.  They are executed before installing the files to be packaged.
The scripts are not called by a standalone install (e.g.: make install).
For every script, the following variables will be set:
CMAKE_CURRENT_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR
and CMAKE_INSTALL_PREFIX (which is set to the staging install
directory).  The singular form CMAKE_INSTALL_SCRIPT is supported as
an alternative variable for historical reasons, but its value is ignored if
CMAKE_INSTALL_SCRIPTS is set and a warning will be issued.

See also CPACK_PRE_BUILD_SCRIPTS and
CPACK_POST_BUILD_SCRIPTS which can be used to specify scripts
to be executed later in the packaging process.

CPACK_PRE_BUILD_SCRIPTS¶

New in version 3.19.

List of CMake scripts to execute after CPack has installed the files to
be packaged into a staging directory and before producing the package(s)
from those files. See also CPACK_INSTALL_SCRIPTS and
CPACK_POST_BUILD_SCRIPTS.

CPACK_POST_BUILD_SCRIPTS¶

New in version 3.19.

List of CMake scripts to execute after CPack has produced the resultant
packages and before copying them back to the build directory.
See also CPACK_INSTALL_SCRIPTS,
CPACK_PRE_BUILD_SCRIPTS and CPACK_PACKAGE_FILES.

CPACK_PACKAGE_FILES¶

New in version 3.19.

List of package files created in the staging directory, with each file
provided as a full absolute path.  This variable is populated by CPack
just before invoking the post-build scripts listed in
CPACK_POST_BUILD_SCRIPTS.  It is the preferred way for the
post-build scripts to know the set of package files to operate on.
Projects should not try to set this variable themselves.

CPACK_INSTALLED_DIRECTORIES¶

Extra directories to install.

CPACK_PACKAGE_INSTALL_REGISTRY_KEY¶

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

CPACK_CREATE_DESKTOP_LINKS¶

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

CPACK_BINARY_<GENNAME><a class="headerlink" href="#variable:CPACK_BINARY_<GENNAME>" title="Permalink to this definition">¶

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

CPACK_READELF_EXECUTABLE¶

New in version 3.25.

Specify the readelf executable path used by CPack.
The default value will be CMAKE_READELF when set.  Otherwise,
the default value will be empty and CPack will use find_program()
to determine the readelf path when needed.

CPACK_OBJCOPY_EXECUTABLE¶

New in version 3.25.

Specify the objcopy executable path used by CPack.
The default value will be CMAKE_OBJCOPY when set.  Otherwise,
the default value will be empty and CPack will use find_program()
to determine the objcopy path when needed.

CPACK_OBJDUMP_EXECUTABLE¶

New in version 3.25.

Specify the objdump executable path used by CPack.
The default value will be CMAKE_OBJDUMP when set.  Otherwise,
the default value will be empty and CPack will use find_program()
to determine the objdump path when needed.

Table of Contents

CPack

Introduction

CPack Generators

Targets package and package_source

Variables common to all CPack Generators

Variables for Source Package Generators

Variables for Advanced Use

Previous topic

CMakeVerifyManifest

Next topic

CPackComponent

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPack

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CPackArchive — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CPackBundle" href="CPackBundle.html" />
    <link rel="prev" title="FindwxWindows" href="FindwxWindows.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackArchive

CPackArchive¶

New in version 3.9.

The documentation for the CPack Archive generator has moved here: CPack Archive Generator

Previous topic

FindwxWindows

Next topic

CPackBundle

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackArchive

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CPackBundle — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CPackCygwin" href="CPackCygwin.html" />
    <link rel="prev" title="CPackArchive" href="CPackArchive.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackBundle

CPackBundle¶

The documentation for the CPack Bundle generator has moved here: CPack Bundle Generator

Previous topic

CPackArchive

Next topic

CPackCygwin

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackBundle

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CPackComponent — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CPackIFW" href="CPackIFW.html" />
    <link rel="prev" title="CPack" href="CPack.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackComponent

CPackComponent¶

Configure components for binary installers and source packages.

Contents

CPackComponent

Introduction

Variables

Commands

Add component

Add component group

Add installation type

Configure downloads

Introduction¶

This module is automatically included by CPack.

Certain binary installers (especially the graphical installers) generated
by CPack allow users to select individual application components to install.
This module allows developers to configure the packaging of such components.

Contents is assigned to components by the COMPONENT
argument of CMake's install() command.  Components can be
annotated with user-friendly names and descriptions, inter-component
dependencies, etc., and grouped in various ways to customize the
resulting installer, using the commands described below.

To specify different groupings for different CPack generators use
a CPACK_PROJECT_CONFIG_FILE.

Variables¶

The following variables influence the component-specific packaging:

CPACK_COMPONENTS_ALL¶

The list of component to install.

The default value of this variable is computed by CPack and contains all
components defined by the project.  The user may set it to only include the
specified components.

Instead of specifying all the desired components, it is possible to obtain a
list of all defined components and then remove the unwanted ones from the
list. The get_cmake_property() command can be used to obtain the
COMPONENTS property, then the list(REMOVE_ITEM) command can be
used to remove the unwanted ones. For example, to use all defined components
except foo and bar:

get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")

CPACK_<GENNAME>_COMPONENT_INSTALL<a class="headerlink" href="#variable:CPACK_<GENNAME>_COMPONENT_INSTALL" title="Permalink to this definition">¶

Enable/Disable component install for CPack generator <GENNAME>.

Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc...) has a legacy
default behavior.  e.g.  RPM builds monolithic whereas NSIS builds
component.  One can change the default behavior by setting this variable to
0/1 or OFF/ON.

CPACK_COMPONENTS_GROUPING¶

Specify how components are grouped for multi-package component-aware CPack
generators.

Some generators like RPM or ARCHIVE (TGZ, ZIP, ...) may generate
several packages files when there are components, depending
on the value of this variable:

ONE_PER_GROUP (default): create one package per component group

IGNORE : create one package per component (ignore the groups)

ALL_COMPONENTS_IN_ONE : create a single package with all requested
components

CPACK_COMPONENT_<compName>_DISPLAY_NAME<a class="headerlink" href="#variable:CPACK_COMPONENT_<compName>_DISPLAY_NAME" title="Permalink to this definition">¶

The name to be displayed for a component.

CPACK_COMPONENT_<compName>_DESCRIPTION<a class="headerlink" href="#variable:CPACK_COMPONENT_<compName>_DESCRIPTION" title="Permalink to this definition">¶

The description of a component.

CPACK_COMPONENT_<compName>_GROUP<a class="headerlink" href="#variable:CPACK_COMPONENT_<compName>_GROUP" title="Permalink to this definition">¶

The group of a component.

CPACK_COMPONENT_<compName>_DEPENDS<a class="headerlink" href="#variable:CPACK_COMPONENT_<compName>_DEPENDS" title="Permalink to this definition">¶

The dependencies (list of components) on which this component depends.

CPACK_COMPONENT_<compName>_HIDDEN<a class="headerlink" href="#variable:CPACK_COMPONENT_<compName>_HIDDEN" title="Permalink to this definition">¶

True if this component is hidden from the user.

CPACK_COMPONENT_<compName>_REQUIRED<a class="headerlink" href="#variable:CPACK_COMPONENT_<compName>_REQUIRED" title="Permalink to this definition">¶

True if this component is required.

CPACK_COMPONENT_<compName>_DISABLED<a class="headerlink" href="#variable:CPACK_COMPONENT_<compName>_DISABLED" title="Permalink to this definition">¶

True if this component is not selected to be installed by default.

Commands¶

Add component¶

cpack_add_component¶

Describe an installation component.

cpack_add_component(compname
                    [DISPLAY_NAME name]
                    [DESCRIPTION description]
                    [HIDDEN | REQUIRED | DISABLED ]
                    [GROUP group]
                    [DEPENDS comp1 comp2 ... ]
                    [INSTALL_TYPES type1 type2 ... ]
                    [DOWNLOADED]
                    [ARCHIVE_FILE filename]
                    [PLIST filename])

compname is the name of an installation component, as defined by the
COMPONENT argument of one or more CMake install() commands.
With the cpack_add_component command one can set a name, a description,
and other attributes of an installation component.
One can also assign a component to a component group.

DISPLAY_NAME is the displayed name of the component, used in graphical
installers to display the component name.  This value can be any
string.

DESCRIPTION is an extended description of the component, used in
graphical installers to give the user additional information about the
component.  Descriptions can span multiple lines using \n as the
line separator.  Typically, these descriptions should be no more than
a few lines long.

HIDDEN indicates that this component will be hidden in the graphical
installer, so that the user cannot directly change whether it is
installed or not.

REQUIRED 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.  (Typically, required components are
shown grayed out).

DISABLED indicates that this component should be disabled (unselected)
by default.  The user is free to select this component for
installation, unless it is also HIDDEN.

DEPENDS lists the components on which this component depends.  If this
component is selected, then each of the components listed must also be
selected.  The dependency information is encoded within the installer
itself, so that users cannot install inconsistent sets of components.

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.  Component groups are described with the
cpack_add_component_group command, detailed below.

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.  Installation types are
described with the cpack_add_install_type command, detailed below.

DOWNLOADED indicates that this component should be downloaded
on-the-fly by the installer, rather than packaged in with the
installer itself.  For more information, see the
cpack_configure_downloads command.

ARCHIVE_FILE provides a name for the archive file created by CPack to
be used for downloaded components.  If not supplied, CPack will create
a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of
the component.  See cpack_configure_downloads for more information.

PLIST gives a filename that is passed to pkgbuild with the
--component-plist argument when using the productbuild generator.

Add component group¶

cpack_add_component_group¶

Describes a group of related CPack installation components.

cpack_add_component_group(groupname
                         [DISPLAY_NAME name]
                         [DESCRIPTION description]
                         [PARENT_GROUP parent]
                         [EXPANDED]
                         [BOLD_TITLE])

The cpack_add_component_group describes a group of installation
components, which will be placed together within the listing of
options.  Typically, component groups allow the user to
select/deselect all of the components within a single group via a
single group-level option.  Use component groups to reduce the
complexity of installers with many options.  groupname is an arbitrary
name used to identify the group in the GROUP argument of the
cpack_add_component command, which is used to place a component in a
group.  The name of the group must not conflict with the name of any
component.

DISPLAY_NAME is the displayed name of the component group, used in
graphical installers to display the component group name.  This value
can be any string.

DESCRIPTION is an extended description of the component group, used in
graphical installers to give the user additional information about the
components within that group.  Descriptions can span multiple lines
using \n as the line separator.  Typically, these descriptions
should be no more than a few lines long.

PARENT_GROUP, if supplied, names the parent group of this group.
Parent groups are used to establish a hierarchy of groups, providing
an arbitrary hierarchy of groups.

EXPANDED indicates that, by default, the group should show up as
"expanded", so that the user immediately sees all of the components
within the group.  Otherwise, the group will initially show up as a
single entry.

BOLD_TITLE indicates that the group title should appear in bold, to
call the user's attention to the group.

Add installation type¶

cpack_add_install_type¶

Add a new installation type containing
a set of predefined component selections to the graphical installer.

cpack_add_install_type(typename
                       [DISPLAY_NAME name])

The cpack_add_install_type command identifies a set of preselected
components that represents a common use case for an application.  For
example, a "Developer" install type might include an application along
with its header and library files, while an "End user" install type
might just include the application's executable.  Each component
identifies itself with one or more install types via the INSTALL_TYPES
argument to cpack_add_component.

DISPLAY_NAME is the displayed name of the install type, which will
typically show up in a drop-down box within a graphical installer.
This value can be any string.

Configure downloads¶

cpack_configure_downloads¶

Configure CPack to download
selected components on-the-fly as part of the installation process.

cpack_configure_downloads(site
                          [UPLOAD_DIRECTORY dirname]
                          [ALL]
                          [ADD_REMOVE|NO_ADD_REMOVE])

The cpack_configure_downloads command configures installation-time
downloads of selected components.  For each downloadable component,
CPack will create an archive containing the contents of that
component, which should be uploaded to the given site.  When the user
selects that component for installation, the installer will download
and extract the component in place.  This feature is useful for
creating small installers that only download the requested components,
saving bandwidth.  Additionally, the installers are small enough that
they will be installed as part of the normal installation process, and
the "Change" button in Windows Add/Remove Programs control panel will
allow one to add or remove parts of the application after the original
installation.  On Windows, the downloaded-components functionality
requires the ZipDLL plug-in for NSIS, available at:

http://nsis.sourceforge.net/ZipDLL_plug-in

On macOS, installers that download components on-the-fly can only
be built and installed on system using macOS 10.5 or later.

The site argument is a URL where the archives for downloadable
components will reside, e.g.,
https://cmake.org/files/v3.25/ All of the archives
produced by CPack should be uploaded to that location.

UPLOAD_DIRECTORY is the local directory where CPack will create the
various archives for each of the components.  The contents of this
directory should be uploaded to a location accessible by the URL given
in the site argument.  If omitted, CPack will use the directory
CPackUploads inside the CMake binary directory to store the generated
archives.

The ALL flag indicates that all components be downloaded.  Otherwise,
only those components explicitly marked as DOWNLOADED or that have a
specified ARCHIVE_FILE will be downloaded.  Additionally, the ALL
option implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).

ADD_REMOVE indicates that CPack should install a copy of the installer
that can be called from Windows' Add/Remove Programs dialog (via the
"Modify" button) to change the set of installed components.
NO_ADD_REMOVE turns off this behavior.  This option is ignored on Mac
OS X.

Table of Contents

CPackComponent

Introduction

Variables

Commands

Add component

Add component group

Add installation type

Configure downloads

Previous topic

CPack

Next topic

CPackIFW

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackComponent

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CPackCygwin — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CPackDeb" href="CPackDeb.html" />
    <link rel="prev" title="CPackBundle" href="CPackBundle.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackCygwin

CPackCygwin¶

The documentation for the CPack Cygwin generator has moved here: CPack Cygwin Generator

Previous topic

CPackBundle

Next topic

CPackDeb

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackCygwin

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CPackDMG — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CPackFreeBSD" href="CPackFreeBSD.html" />
    <link rel="prev" title="CPackDeb" href="CPackDeb.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackDMG

CPackDMG¶

The documentation for the CPack DragNDrop generator has moved here: CPack DragNDrop Generator

Previous topic

CPackDeb

Next topic

CPackFreeBSD

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackDMG

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CPackDeb — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CPackDMG" href="CPackDMG.html" />
    <link rel="prev" title="CPackCygwin" href="CPackCygwin.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackDeb

CPackDeb¶

The documentation for the CPack DEB generator has moved here: CPack DEB Generator

Previous topic

CPackCygwin

Next topic

CPackDMG

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackDeb

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CPackFreeBSD — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CPackNSIS" href="CPackNSIS.html" />
    <link rel="prev" title="CPackDMG" href="CPackDMG.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackFreeBSD

CPackFreeBSD¶

New in version 3.10.

The documentation for the CPack FreeBSD generator has moved here: CPack FreeBSD Generator

Previous topic

CPackDMG

Next topic

CPackNSIS

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CPackFreeBSD

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.