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>target_sources — 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="try_compile" href="try_compile.html" />
    <link rel="prev" title="target_precompile_headers" href="target_precompile_headers.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

target_sources

target_sources¶

New in version 3.1.

Add sources to a target.

target_sources(<target>
  <INTERFACE|PUBLIC|PRIVATE> [items1...]
  [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

Specifies sources to use when building a target and/or its dependents.
The named <target> must have been created by a command such as
add_executable() or add_library() or
add_custom_target() and must not be an
ALIAS target.  The <items> may use
generator expressions.

New in version 3.20: <target> can be a custom target.

The INTERFACE, PUBLIC and PRIVATE keywords are required to
specify the scope of the source file paths
(<items>) that follow them.  PRIVATE and PUBLIC items will
populate the SOURCES property of <target>, which are used when
building the target itself. PUBLIC and INTERFACE items will populate the
INTERFACE_SOURCES property of <target>, which are used
when building dependents.  A target created by add_custom_target()
can only have PRIVATE scope.

Repeated calls for the same <target> append items in the order called.

New in version 3.3: Allow exporting targets with INTERFACE_SOURCES.

New in version 3.11: Allow setting INTERFACE items on
IMPORTED targets.

Changed in version 3.13: Relative source file paths are interpreted as being relative to the current
source directory (i.e. CMAKE_CURRENT_SOURCE_DIR).
See policy CMP0076.

A path that begins with a generator expression is left unmodified.
When a target's SOURCE_DIR property differs from
CMAKE_CURRENT_SOURCE_DIR, use absolute paths in generator
expressions to ensure the sources are correctly assigned to the target.

# WRONG: starts with generator expression, but relative path used
target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:dbgsrc.cpp>")

# CORRECT: absolute path used inside the generator expression
target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>")

See the cmake-buildsystem(7) manual for more on defining
buildsystem properties.

File Sets¶

New in version 3.23.

target_sources(<target>
  [<INTERFACE|PUBLIC|PRIVATE>
   [FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]...
  ]...)

Adds a file set to a target, or adds files to an existing file set. Targets
have zero or more named file sets. Each file set has a name, a type, a scope of
INTERFACE, PUBLIC, or PRIVATE, one or more base directories, and
files within those directories. The acceptable types include:

HEADERS

Sources intended to be used via a language's #include mechanism.

CXX_MODULES

New in version 3.28.

Sources which contain C++ interface module or partition units (i.e., those
using the export keyword). This file set type may not have an
INTERFACE scope except on IMPORTED targets.

The optional default file sets are named after their type. The target may not
be a custom target or FRAMEWORK target.

Files in a PRIVATE or PUBLIC file set are marked as source files for
the purposes of IDE integration. Additionally, files in HEADERS file sets
have their HEADER_FILE_ONLY property set to TRUE. Files in an
INTERFACE or PUBLIC file set can be installed with the
install(TARGETS) command, and exported with the
install(EXPORT) and export() commands.

Each target_sources(FILE_SET) entry starts with INTERFACE, PUBLIC, or
PRIVATE and accepts the following arguments:

FILE_SET <set>

The name of the file set to create or add to. It must contain only letters,
numbers and underscores. Names starting with a capital letter are reserved
for built-in file sets predefined by CMake. The only predefined set names
are those matching the acceptable types. All other set names must not start
with a capital letter or
underscore.

TYPE <type>

Every file set is associated with a particular type of file. Only types
specified above may be used and it is an error to specify anything else. As
a special case, if the name of the file set is one of the types, the type
does not need to be specified and the TYPE <type> arguments can be
omitted. For all other file set names, TYPE is required.

BASE_DIRS <dirs>...

An optional list of base directories of the file set. Any relative path
is treated as relative to the current source directory
(i.e. CMAKE_CURRENT_SOURCE_DIR). If no BASE_DIRS are
specified when the file set is first created, the value of
CMAKE_CURRENT_SOURCE_DIR is added. This argument supports
generator expressions.

No two base directories for a file set may be sub-directories of each other.
This requirement must be met across all base directories added to a file set,
not just those within a single call to target_sources().

FILES <files>...

An optional list of files to add to the file set. Each file must be in
one of the base directories, or a subdirectory of one of the base
directories. This argument supports
generator expressions.

If relative paths are specified, they are considered relative to
CMAKE_CURRENT_SOURCE_DIR at the time target_sources() is
called. An exception to this is a path starting with $<. Such paths
are treated as relative to the target's source directory after evaluation
of generator expressions.

The following target properties are set by target_sources(FILE_SET),
but they should not generally be manipulated directly:

For file sets of type HEADERS:

HEADER_SETS

INTERFACE_HEADER_SETS

HEADER_SET

HEADER_SET_<NAME>

HEADER_DIRS

HEADER_DIRS_<NAME>

For file sets of type CXX_MODULES:

CXX_MODULE_SETS

INTERFACE_CXX_MODULE_SETS

CXX_MODULE_SET

CXX_MODULE_SET_<NAME>

CXX_MODULE_DIRS

CXX_MODULE_DIRS_<NAME>

Target properties related to include directories are also modified by
target_sources(FILE_SET) as follows:

INCLUDE_DIRECTORIES

If the TYPE is HEADERS, and the scope of the file set is PRIVATE
or PUBLIC, all of the BASE_DIRS of the file set are wrapped in
$<BUILD_INTERFACE> and appended to this property.

INTERFACE_INCLUDE_DIRECTORIES

If the TYPE is HEADERS, and the scope of the file set is
INTERFACE or PUBLIC, all of the BASE_DIRS of the file set are
wrapped in $<BUILD_INTERFACE> and appended to this property.

See Also¶

add_executable()

add_library()

target_compile_definitions()

target_compile_features()

target_compile_options()

target_include_directories()

target_link_libraries()

target_link_directories()

target_link_options()

target_precompile_headers()

Table of Contents

target_sources

File Sets

See Also

Previous topic

target_precompile_headers

Next topic

try_compile

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-commands(7) »

target_sources

        © 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>try_compile — 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="try_run" href="try_run.html" />
    <link rel="prev" title="target_sources" href="target_sources.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

try_compile

try_compile¶

Contents

try_compile

Try Compiling Whole Projects

Try Compiling Source Files

Options

Other Behavior Settings

See Also

Try building some code.

Try Compiling Whole Projects¶

try_compile(<compileResultVar> PROJECT <projectName>
            SOURCE_DIR <srcdir>
            [BINARY_DIR <bindir>]
            [TARGET <targetName>]
            [LOG_DESCRIPTION <text>]
            [NO_CACHE]
            [NO_LOG]
            [CMAKE_FLAGS <flags>...]
            [OUTPUT_VARIABLE <var>])

New in version 3.25.

Try building a project.  Build success returns TRUE and build failure
returns FALSE in <compileResultVar>.

In this form, <srcdir> should contain a complete CMake project with a
CMakeLists.txt file and all sources.  The <bindir> and <srcdir>
will not be deleted after this command is run.  Specify <targetName> to
build a specific target instead of the all or ALL_BUILD target.  See
below for the meaning of other options.

Changed in version 3.24: CMake variables describing platform settings, and those listed by the
CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable, are propagated
into the project's build configuration.  See policy CMP0137.
Previously this was only done by the
source file signature.

New in version 3.26: This command records a
configure-log try_compile event
if the NO_LOG option is not specified.

This command supports an alternate signature for CMake older than 3.25.
The signature above is recommended for clarity.

try_compile(<compileResultVar> <bindir> <srcdir>
            <projectName> [<targetName>]
            [CMAKE_FLAGS <flags>...]
            [OUTPUT_VARIABLE <var>])

Try Compiling Source Files¶

try_compile(<compileResultVar>
            [SOURCES_TYPE <type>]
            <SOURCES <srcfile...>                 |
             SOURCE_FROM_CONTENT <name> <content> |
             SOURCE_FROM_VAR <name> <var>         |
             SOURCE_FROM_FILE <name> <path>       >...
            [LOG_DESCRIPTION <text>]
            [NO_CACHE]
            [NO_LOG]
            [CMAKE_FLAGS <flags>...]
            [COMPILE_DEFINITIONS <defs>...]
            [LINK_OPTIONS <options>...]
            [LINK_LIBRARIES <libs>...]
            [LINKER_LANGUAGE <lang>]
            [OUTPUT_VARIABLE <var>]
            [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
            [<LANG>_STANDARD <std>]
            [<LANG>_STANDARD_REQUIRED <bool>]
            [<LANG>_EXTENSIONS <bool>]
            )

New in version 3.25.

Try building an executable or static library from one or more source files
(which one is determined by the CMAKE_TRY_COMPILE_TARGET_TYPE
variable). Build success returns TRUE and build failure returns FALSE
in <compileResultVar>.

In this form, one or more source files must be provided. Additionally, one of
SOURCES and/or SOURCE_FROM_* must precede other keywords.

If CMAKE_TRY_COMPILE_TARGET_TYPE is unset or is set to
EXECUTABLE, the sources must include a definition for main and CMake
will create a CMakeLists.txt file to build the source(s) as an executable.
If CMAKE_TRY_COMPILE_TARGET_TYPE is set to STATIC_LIBRARY,
a static library will be built instead and no definition for main is
required.  For an executable, the generated CMakeLists.txt file would
contain something like the following:

add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
include_directories(${INCLUDE_DIRECTORIES})
link_directories(${LINK_DIRECTORIES})
add_executable(cmTryCompileExec <srcfile>...)
target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})

CMake automatically generates, for each try_compile operation, a
unique directory under ${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch
with an unspecified name.  These directories are cleaned automatically unless
--debug-trycompile is passed to cmake.
Such directories from previous runs are also unconditionally cleaned at the
beginning of any cmake execution.

This command supports an alternate signature for CMake older than 3.25.
The signature above is recommended for clarity.

try_compile(<compileResultVar> <bindir> <srcfile|SOURCES srcfile...>
            [CMAKE_FLAGS <flags>...]
            [COMPILE_DEFINITIONS <defs>...]
            [LINK_OPTIONS <options>...]
            [LINK_LIBRARIES <libs>...]
            [OUTPUT_VARIABLE <var>]
            [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
            [<LANG>_STANDARD <std>]
            [<LANG>_STANDARD_REQUIRED <bool>]
            [<LANG>_EXTENSIONS <bool>]
            )

In this version, try_compile will use <bindir>/CMakeFiles/CMakeTmp for
its operation, and all such files will be cleaned automatically.
For debugging, --debug-trycompile can be
passed to cmake to avoid this clean.  However, multiple sequential
try_compile operations, if given the same <bindir>, will reuse this
single output directory, such that you can only debug one such try_compile
call at a time.  Use of the newer signature is recommended to simplify
debugging of multiple try_compile operations.

Options¶

The options for the above signatures are:

CMAKE_FLAGS <flags>...

Specify flags of the form -DVAR:TYPE=VALUE to be passed
to the cmake(1) command-line used to drive the test build.
The above example shows how values for variables
INCLUDE_DIRECTORIES, LINK_DIRECTORIES, and LINK_LIBRARIES
are used.

COMPILE_DEFINITIONS <defs>...

Specify -Ddefinition arguments to pass to add_definitions()
in the generated test project.

COPY_FILE <fileName>

Copy the built executable or static library to the given <fileName>.

COPY_FILE_ERROR <var>

Use after COPY_FILE to capture into variable <var> any error
message encountered while trying to copy the file.

LINK_LIBRARIES <libs>...

Specify libraries to be linked in the generated project.
The list of libraries may refer to system libraries and to
Imported Targets from the calling project.

If this option is specified, any -DLINK_LIBRARIES=... value
given to the CMAKE_FLAGS option will be ignored.

New in version 3.29: Alias targets to imported libraries are also supported.

LINK_OPTIONS <options>...

New in version 3.14.

Specify link step options to pass to target_link_options() or to
set the STATIC_LIBRARY_OPTIONS target property in the generated
project, depending on the CMAKE_TRY_COMPILE_TARGET_TYPE variable.

LINKER_LANGUAGE <lang>`

New in version 3.29.

Specify the LINKER_LANGUAGE target property of the generated
project.  When using multiple source files with different languages, set
this to the language of the source file containing the program entry point,
e.g., main.

LOG_DESCRIPTION <text>

New in version 3.26.

Specify a non-empty text description of the purpose of the check.
This is recorded in the cmake-configure-log(7) entry.

NO_CACHE

New in version 3.25.

The result will be stored in a normal variable rather than a cache entry.

The result variable is normally cached so that a simple pattern can be used
to avoid repeating the test on subsequent executions of CMake:

if(NOT DEFINED RESULTVAR)
  # ...(check-specific setup code)...
  try_compile(RESULTVAR ...)
  # ...(check-specific logging and cleanup code)...
endif()

If the guard variable and result variable are not the same (for example, if
the test is part of a larger inspection), NO_CACHE may be useful to avoid
leaking the intermediate result variable into the cache.

NO_LOG

New in version 3.26.

Do not record a cmake-configure-log(7) entry for this call.

OUTPUT_VARIABLE <var>

Store the output from the build process in the given variable.

SOURCE_FROM_CONTENT <name> <content>

New in version 3.25.

Write <content> to a file named <name> in the operation directory.
This can be used to bypass the need to separately write a source file when
the contents of the file are dynamically specified. The specified <name>
is not allowed to contain path components.

SOURCE_FROM_CONTENT may be specified multiple times.

SOURCE_FROM_FILE <name> <path>

New in version 3.25.

Copy <path> to a file named <name> in the operation directory. This
can be used to consolidate files into the operation directory, which may be
useful if a source which already exists (i.e. as a stand-alone file in a
project's source repository) needs to refer to other file(s) created by
SOURCE_FROM_*. (Otherwise, SOURCES is usually more convenient.) The
specified <name> is not allowed to contain path components.

SOURCE_FROM_VAR <name> <var>

New in version 3.25.

Write the contents of <var> to a file named <name> in the operation
directory. This is the same as SOURCE_FROM_CONTENT, but takes the
contents from the specified CMake variable, rather than directly, which may
be useful when passing arguments through a function which wraps
try_compile. The specified <name> is not allowed to contain path
components.

SOURCE_FROM_VAR may be specified multiple times.

SOURCES_TYPE <type>

New in version 3.28.

Sources may be classified using the SOURCES_TYPE argument. Once
specified, all subsequent sources specified will be treated as that type
until another SOURCES_TYPE is given. Available types are:

NORMAL

Sources are not added to any FILE_SET in the generated project.

CXX_MODULE

New in version 3.28.

Sources are added to a FILE_SET of type CXX_MODULES in the
generated project.

The default type of sources is NORMAL.

<LANG>_STANDARD <std>

New in version 3.8.

Specify the C_STANDARD, CXX_STANDARD,
OBJC_STANDARD, OBJCXX_STANDARD,
or CUDA_STANDARD target property of the generated project.

<LANG>_STANDARD_REQUIRED <bool>

New in version 3.8.

Specify the C_STANDARD_REQUIRED,
CXX_STANDARD_REQUIRED, OBJC_STANDARD_REQUIRED,
OBJCXX_STANDARD_REQUIRED,or CUDA_STANDARD_REQUIRED
target property of the generated project.

<LANG>_EXTENSIONS <bool>

New in version 3.8.

Specify the C_EXTENSIONS, CXX_EXTENSIONS,
OBJC_EXTENSIONS, OBJCXX_EXTENSIONS,
or CUDA_EXTENSIONS target property of the generated project.

Other Behavior Settings¶

New in version 3.4: If set, the following variables are passed in to the generated
try_compile CMakeLists.txt to initialize compile target properties with
default values:

CMAKE_CUDA_RUNTIME_LIBRARY

CMAKE_ENABLE_EXPORTS

CMAKE_LINK_SEARCH_START_STATIC

CMAKE_LINK_SEARCH_END_STATIC

CMAKE_MSVC_RUNTIME_LIBRARY

CMAKE_POSITION_INDEPENDENT_CODE

CMAKE_WATCOM_RUNTIME_LIBRARY

If CMP0056 is set to NEW, then
CMAKE_EXE_LINKER_FLAGS is passed in as well.

Changed in version 3.14: If CMP0083 is set to NEW, then in order to obtain correct
behavior at link time, the check_pie_supported() command from the
CheckPIESupported module must be called before using the
try_compile command.

The current settings of CMP0065 and CMP0083 are propagated
through to the generated test project.

Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
configuration:

For multi-config generators, this selects which configuration to build.

For single-config generators, this sets CMAKE_BUILD_TYPE in
the test project.

New in version 3.6: Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to specify
the type of target used for the source file signature.

New in version 3.6: Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable to specify
variables that must be propagated into the test project.  This variable is
meant for use only in toolchain files and is only honored by the
try_compile() command for the source files form, not when given a whole
project.

Changed in version 3.8: If CMP0067 is set to NEW, or any of the <LANG>_STANDARD,
<LANG>_STANDARD_REQUIRED, or <LANG>_EXTENSIONS options are used,
then the language standard variables are honored:

CMAKE_C_STANDARD

CMAKE_C_STANDARD_REQUIRED

CMAKE_C_EXTENSIONS

CMAKE_CXX_STANDARD

CMAKE_CXX_STANDARD_REQUIRED

CMAKE_CXX_EXTENSIONS

CMAKE_OBJC_STANDARD

CMAKE_OBJC_STANDARD_REQUIRED

CMAKE_OBJC_EXTENSIONS

CMAKE_OBJCXX_STANDARD

CMAKE_OBJCXX_STANDARD_REQUIRED

CMAKE_OBJCXX_EXTENSIONS

CMAKE_CUDA_STANDARD

CMAKE_CUDA_STANDARD_REQUIRED

CMAKE_CUDA_EXTENSIONS

Their values are used to set the corresponding target properties in
the generated project (unless overridden by an explicit option).

Changed in version 3.14: For the Green Hills MULTI generator, the GHS toolset and target
system customization cache variables are also propagated into the test
project.

New in version 3.24: The CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES variable may be
set to disable passing platform variables into the test project.

New in version 3.25: If CMP0141 is set to NEW, one can use
CMAKE_MSVC_DEBUG_INFORMATION_FORMAT to specify the MSVC debug
information format.

See Also¶

try_run()

Table of Contents

try_compile

Try Compiling Whole Projects

Try Compiling Source Files

Options

Other Behavior Settings

See Also

Previous topic

target_sources

Next topic

try_run

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-commands(7) »

try_compile

        © 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>try_run — 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="ctest_build" href="ctest_build.html" />
    <link rel="prev" title="try_compile" href="try_compile.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

try_run

try_run¶

Contents

try_run

Try Compiling and Running Source Files

Options

Other Behavior Settings

Behavior when Cross Compiling

Try compiling and then running some code.

Try Compiling and Running Source Files¶

try_run(<runResultVar> <compileResultVar>
        [SOURCES_TYPE <type>]
        <SOURCES <srcfile...>                 |
         SOURCE_FROM_CONTENT <name> <content> |
         SOURCE_FROM_VAR <name> <var>         |
         SOURCE_FROM_FILE <name> <path>       >...
        [LOG_DESCRIPTION <text>]
        [NO_CACHE]
        [NO_LOG]
        [CMAKE_FLAGS <flags>...]
        [COMPILE_DEFINITIONS <defs>...]
        [LINK_OPTIONS <options>...]
        [LINK_LIBRARIES <libs>...]
        [COMPILE_OUTPUT_VARIABLE <var>]
        [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
        [<LANG>_STANDARD <std>]
        [<LANG>_STANDARD_REQUIRED <bool>]
        [<LANG>_EXTENSIONS <bool>]
        [RUN_OUTPUT_VARIABLE <var>]
        [RUN_OUTPUT_STDOUT_VARIABLE <var>]
        [RUN_OUTPUT_STDERR_VARIABLE <var>]
        [WORKING_DIRECTORY <var>]
        [ARGS <args>...]
        )

New in version 3.25.

Try building an executable from one or more source files.  Build success
returns TRUE and build failure returns FALSE in <compileResultVar>.
If the build succeeds, this runs the executable and stores the exit code in
<runResultVar>.  If the executable was built, but failed to run, then
<runResultVar> will be set to FAILED_TO_RUN.  See command
try_compile() for documentation of options common to both commands,
and for information on how the test project is constructed to build the source
file.

One or more source files must be provided. Additionally, one of SOURCES
and/or SOURCE_FROM_* must precede other keywords.

New in version 3.26: This command records a
configure-log try_run event
if the NO_LOG option is not specified.

This command supports an alternate signature for CMake older than 3.25.
The signature above is recommended for clarity.

try_run(<runResultVar> <compileResultVar>
        <bindir> <srcfile|SOURCES srcfile...>
        [CMAKE_FLAGS <flags>...]
        [COMPILE_DEFINITIONS <defs>...]
        [LINK_OPTIONS <options>...]
        [LINK_LIBRARIES <libs>...]
        [LINKER_LANGUAGE <lang>]
        [COMPILE_OUTPUT_VARIABLE <var>]
        [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
        [<LANG>_STANDARD <std>]
        [<LANG>_STANDARD_REQUIRED <bool>]
        [<LANG>_EXTENSIONS <bool>]
        [RUN_OUTPUT_VARIABLE <var>]
        [OUTPUT_VARIABLE <var>]
        [WORKING_DIRECTORY <var>]
        [ARGS <args>...]
        )

Options¶

The options specific to try_run are:

COMPILE_OUTPUT_VARIABLE <var>

Report the compile step build output in a given variable.

OUTPUT_VARIABLE <var>

Report the compile build output and the output from running the executable
in the given variable.  This option exists for legacy reasons and is only
supported by the old try_run signature.
Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE instead.

RUN_OUTPUT_VARIABLE <var>

Report the output from running the executable in a given variable.

RUN_OUTPUT_STDOUT_VARIABLE <var>

New in version 3.25.

Report the output of stdout from running the executable in a given variable.

RUN_OUTPUT_STDERR_VARIABLE <var>

New in version 3.25.

Report the output of stderr from running the executable in a given variable.

WORKING_DIRECTORY <var>

New in version 3.20.

Run the executable in the given directory. If no WORKING_DIRECTORY is
specified, the executable will run in <bindir> or the current build
directory.

ARGS <args>...

Additional arguments to pass to the executable when running it.

Other Behavior Settings¶

Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
configuration:

For multi-config generators, this selects which configuration to build.

For single-config generators, this sets CMAKE_BUILD_TYPE in
the test project.

Behavior when Cross Compiling¶

New in version 3.3: Use CMAKE_CROSSCOMPILING_EMULATOR when running cross-compiled binaries.

When cross compiling, the executable compiled in the first step
usually cannot be run on the build host.  The try_run command checks
the CMAKE_CROSSCOMPILING variable to detect whether CMake is in
cross-compiling mode.  If that is the case, it will still try to compile
the executable, but it will not try to run the executable unless the
CMAKE_CROSSCOMPILING_EMULATOR variable is set.  Instead it
will create cache variables which must be filled by the user or by
presetting them in some CMake script file to the values the executable
would have produced if it had been run on its actual target platform.
These cache entries are:

<runResultVar>

Exit code if the executable were to be run on the target platform.

<runResultVar>__TRYRUN_OUTPUT

Output from stdout and stderr if the executable were to be run on
the target platform.  This is created only if the
RUN_OUTPUT_VARIABLE or OUTPUT_VARIABLE option was used.

In order to make cross compiling your project easier, use try_run
only if really required.  If you use try_run, use the
RUN_OUTPUT_STDOUT_VARIABLE, RUN_OUTPUT_STDERR_VARIABLE,
RUN_OUTPUT_VARIABLE or OUTPUT_VARIABLE options only if really
required.  Using them will require that when cross-compiling, the cache
variables will have to be set manually to the output of the executable.
You can also "guard" the calls to try_run with an if()
block checking the CMAKE_CROSSCOMPILING variable and
provide an easy-to-preset alternative for this case.

Table of Contents

try_run

Try Compiling and Running Source Files

Options

Other Behavior Settings

Behavior when Cross Compiling

Previous topic

try_compile

Next topic

ctest_build

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-commands(7) »

try_run

        © 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>unset — 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="variable_watch" href="variable_watch.html" />
    <link rel="prev" title="string" href="string.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

unset

unset¶

Unset a variable, cache variable, or environment variable.

Unset Normal Variable or Cache Entry¶

unset(<variable> [CACHE | PARENT_SCOPE])

Removes a normal variable from the current scope, causing it
to become undefined.  If CACHE is present, then a cache variable
is removed instead of a normal variable.

If PARENT_SCOPE is present then the variable is removed from the scope
above the current scope.  See the same option in the set() command
for further details.

Note

When evaluating Variable References of the form ${VAR}, CMake
first searches for a normal variable with that name.  If no such normal
variable exists, CMake will then search for a cache entry with that name.
Because of this, unsetting a normal variable can expose a cache variable
that was previously hidden.  To force a variable reference of the form
${VAR} to return an empty string, use set(<variable> ""), which
clears the normal variable but leaves it defined.

Unset Environment Variable¶

unset(ENV{<variable>})

Removes <variable> from the currently available
Environment Variables.
Subsequent calls of $ENV{<variable>} will return the empty string.

This command affects only the current CMake process, not the process
from which CMake was called, nor the system environment at large,
nor the environment of subsequent build or test processes.

See Also¶

set()

Table of Contents

unset

Unset Normal Variable or Cache Entry

Unset Environment Variable

See Also

Previous topic

string

Next topic

variable_watch

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-commands(7) »

unset

        © 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>use_mangled_mesa — 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="utility_source" href="utility_source.html" />
    <link rel="prev" title="subdirs" href="subdirs.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

use_mangled_mesa

use_mangled_mesa¶

Disallowed since version 3.0.  See CMake Policy CMP0030.

Copy mesa headers for use in combination with system GL.

use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)

The path to mesa includes, should contain gl_mangle.h.  The mesa
headers are copied to the specified output directory.  This allows
mangled mesa headers to override other GL headers by being added to
the include directory path earlier.

Previous topic

subdirs

Next topic

utility_source

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-commands(7) »

use_mangled_mesa

        © 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>utility_source — 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="variable_requires" href="variable_requires.html" />
    <link rel="prev" title="use_mangled_mesa" href="use_mangled_mesa.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

utility_source

utility_source¶

Disallowed since version 3.0.  See CMake Policy CMP0034.

Specify the source tree of a third-party utility.

utility_source(cache_entry executable_name
               path_to_source [file1 file2 ...])

When a third-party utility's source is included in the distribution,
this command specifies its location and name.  The cache entry will
not be set unless the path_to_source and all listed files exist.  It
is assumed that the source tree of the utility will have been built
before it is needed.

When cross compiling CMake will print a warning if a utility_source()
command is executed, because in many cases it is used to build an
executable which is executed later on.  This doesn't work when cross
compiling, since the executable can run only on their target platform.
So in this case the cache entry has to be adjusted manually so it
points to an executable which is runnable on the build host.

Previous topic

use_mangled_mesa

Next topic

variable_requires

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-commands(7) »

utility_source

        © 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>variable_requires — 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="write_file" href="write_file.html" />
    <link rel="prev" title="utility_source" href="utility_source.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

variable_requires

variable_requires¶

Disallowed since version 3.0.  See CMake Policy CMP0035.

Use the if() command instead.

Assert satisfaction of an option's required variables.

variable_requires(TEST_VARIABLE RESULT_VARIABLE
                  REQUIRED_VARIABLE1
                  REQUIRED_VARIABLE2 ...)

The first argument (TEST_VARIABLE) is the name of the variable to be
tested, if that variable is false nothing else is done.  If
TEST_VARIABLE is true, then the next argument (RESULT_VARIABLE)
is a variable that is set to true if all the required variables are set.
The rest of the arguments are variables that must be true or not set
to NOTFOUND to avoid an error.  If any are not true, an error is
reported.

Previous topic

utility_source

Next topic

write_file

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-commands(7) »

variable_requires

        © 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>variable_watch — 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="while" href="while.html" />
    <link rel="prev" title="unset" href="unset.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

variable_watch

variable_watch¶

Watch the CMake variable for change.

variable_watch(<variable> [<command>])

If the specified <variable> changes and no <command> is given,
a message will be printed to inform about the change.

If <command> is given, this command will be executed instead.
The command will receive the following arguments:
COMMAND(<variable> <access> <value> <current_list_file> <stack>)

<variable>

Name of the variable being accessed.

<access>

One of READ_ACCESS, UNKNOWN_READ_ACCESS, MODIFIED_ACCESS,
UNKNOWN_MODIFIED_ACCESS, or REMOVED_ACCESS.  The UNKNOWN_
values are only used when the variable has never been set.  Once set,
they are never used again during the same CMake run, even if the
variable is later unset.

<value>

The value of the variable.  On a modification, this is the new
(modified) value of the variable.  On removal, the value is empty.

<current_list_file>

Full path to the file doing the access.

<stack>

List of absolute paths of all files currently on the stack of file
inclusion, with the bottom-most file first and the currently
processed file (that is, current_list_file) last.

Note that for some accesses such as list(APPEND), the watcher
is executed twice, first with a read access and then with a write one.
Also note that an if(DEFINED) query on the variable does not
register as an access and the watcher is not executed.

Only non-cache variables can be watched using this command.  Access to
cache variables is never watched.  However, the existence of a cache
variable var causes accesses to the non-cache variable var to
not use the UNKNOWN_ prefix, even if a non-cache variable var
has never existed.

Previous topic

unset

Next topic

while

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-commands(7) »

variable_watch

        © 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>while — 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="add_compile_definitions" href="add_compile_definitions.html" />
    <link rel="prev" title="variable_watch" href="variable_watch.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

while

while¶

Evaluate a group of commands while a condition is true

while(<condition>)
  <commands>
endwhile()

All commands between while and the matching endwhile() are recorded
without being invoked.  Once the endwhile() is evaluated, the
recorded list of commands is invoked as long as the <condition> is true.

The <condition> has the same syntax and is evaluated using the same logic
as described at length for the if() command.

The commands break() and continue() provide means to
escape from the normal control flow.

Per legacy, the endwhile() command admits
an optional <condition> argument.
If used, it must be a verbatim repeat of the argument of the opening
while command.

See Also¶

break()

continue()

foreach()

endwhile()

Table of Contents

while

See Also

Previous topic

variable_watch

Next topic

add_compile_definitions

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-commands(7) »

while

        © 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>write_file — 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="cmake-compile-features(7)" href="../manual/cmake-compile-features.7.html" />
    <link rel="prev" title="variable_requires" href="variable_requires.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

write_file

write_file¶

Deprecated since version 3.0: Use the file(WRITE) command instead.

write_file(filename "message to write"... [APPEND])

The first argument is the file name, the rest of the arguments are
messages to write.  If the argument APPEND is specified, then the
message will be appended.

NOTE 1: file(WRITE)  and file(APPEND)  do exactly
the same as this one but add some more functionality.

NOTE 2: When using write_file the produced file cannot be used as an
input to CMake (CONFIGURE_FILE, source file ...) because it will lead
to an infinite loop.  Use configure_file() if you want to
generate input files to CMake.

Previous topic

variable_requires

Next topic

cmake-compile-features(7)

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-commands(7) »

write_file

        © 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 Archive Generator — 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 Bundle Generator" href="bundle.html" />
    <link rel="prev" title="cpack-generators(7)" href="../manual/cpack-generators.7.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cpack-generators(7) »

CPack Archive Generator

CPack Archive Generator¶

CPack generator for packaging files into an archive, which can have
any of the following formats:

7Z - 7zip - (.7z)

TBZ2 (.tar.bz2)

TGZ (.tar.gz)

TXZ (.tar.xz)

TZ (.tar.Z)

TZST (.tar.zst)

ZIP (.zip)

New in version 3.1: 7Z and TXZ formats support.

New in version 3.16: TZST format support.

When this generator is called from CPackSourceConfig.cmake (or through
the package_source target), then the generated archive will contain all
files in the project directory, except those specified in
CPACK_SOURCE_IGNORE_FILES.  The following is one example of
packaging all source files of a project:

set(CPACK_SOURCE_GENERATOR "TGZ")
set(CPACK_SOURCE_IGNORE_FILES
  \\.git/
  build/
  ".*~$"
)
set(CPACK_VERBATIM_VARIABLES YES)
include(CPack)

When this generator is called from CPackConfig.cmake (or through the
package target), then the generated archive will contain all files
that have been installed via CMake's install() command (and the
deprecated commands install_files(), install_programs(),
and install_targets()).

Variables specific to CPack Archive generator¶

CPACK_ARCHIVE_FILE_NAME¶

CPACK_ARCHIVE_<component>_FILE_NAME<a class="headerlink" href="#variable:CPACK_ARCHIVE_<component>_FILE_NAME" title="Permalink to this definition">¶

Package file name without extension.

Default:

The default is <CPACK_PACKAGE_FILE_NAME>[-<component>], with spaces
replaced by '-'.

The extension is determined from the archive format (see list above) and
automatically appended to the file name. Note that <component> is all
uppercase in the variable name.

New in version 3.9: Per-component CPACK_ARCHIVE_<component>_FILE_NAME variables.

CPACK_ARCHIVE_FILE_EXTENSION¶

New in version 3.25.

Package file extension.

Default:

Default values are given in the list above.

CPACK_ARCHIVE_COMPONENT_INSTALL¶

Enable component packaging.

Default:

OFF

If enabled (ON) multiple packages are generated. By default a single package
containing files of all components is generated.

Variables used by CPack Archive generator¶

These variables are used by the Archive generator, but are also available to
CPack generators which are essentially archives at their core. These include:

CPack Cygwin Generator

CPack FreeBSD Generator

CPACK_ARCHIVE_THREADS¶

The number of threads to use when performing the compression.

New in version 3.18.

Default:

1

If set to 0, the number of available cores on the machine will be used instead.
The default is 1 which limits compression to a single thread. Note that
not all compression modes support threading in all environments. Currently,
only the XZ compression may support it.

See also the CPACK_THREADS variable.

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.

Table of Contents

CPack Archive Generator

Variables specific to CPack Archive generator

Variables used by CPack Archive generator

Previous topic

cpack-generators(7)

Next topic

CPack Bundle Generator

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 »

cpack-generators(7) »

CPack Archive Generator

        © 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 Bundle Generator — 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 Cygwin Generator" href="cygwin.html" />
    <link rel="prev" title="CPack Archive Generator" href="archive.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cpack-generators(7) »

CPack Bundle Generator

CPack Bundle Generator¶

CPack Bundle generator (macOS) specific options

Variables specific to CPack Bundle generator¶

Installers built on macOS using the Bundle generator use the
aforementioned DragNDrop (CPACK_DMG_xxx) variables, plus the following
Bundle-specific parameters (CPACK_BUNDLE_xxx).

CPACK_BUNDLE_NAME¶

The name of the generated bundle. This appears in the macOS Finder as the
bundle name. Required.

CPACK_BUNDLE_PLIST¶

Path to an macOS Property List (.plist) file that will be used
for the generated bundle. This
assumes that the caller has generated or specified their own Info.plist
file. Required.

CPACK_BUNDLE_ICON¶

Path to an macOS icon file that will be used as the icon for the generated
bundle. This is the icon that appears in the macOS Finder for the bundle, and
in the macOS dock when the bundle is opened. Required.

CPACK_BUNDLE_STARTUP_COMMAND¶

Path to a startup script. This is a path to an executable or script that
will be run whenever an end-user double-clicks the generated bundle in the
macOS Finder. Optional.

CPACK_BUNDLE_APPLE_CERT_APP¶

New in version 3.2.

The name of your Apple supplied code signing certificate for the application.
The name usually takes the form Developer ID Application: [Name] or
3rd Party Mac Developer Application: [Name]. If this variable is not set
the application will not be signed.

CPACK_BUNDLE_APPLE_ENTITLEMENTS¶

New in version 3.2.

The name of the Property List (.plist) file that contains your Apple
entitlements for sandboxing your application. This file is required
for submission to the macOS App Store.

CPACK_BUNDLE_APPLE_CODESIGN_FILES¶

New in version 3.2.

A list of additional files that you wish to be signed. You do not need to
list the main application folder, or the main executable. You should
list any frameworks and plugins that are included in your app bundle.

CPACK_BUNDLE_APPLE_CODESIGN_PARAMETER¶

New in version 3.3.

Additional parameter that will passed to codesign.
Default value: --deep -f

CPACK_COMMAND_CODESIGN¶

New in version 3.2.

Path to the codesign(1) command used to sign applications with an
Apple cert. This variable can be used to override the automatically
detected command (or specify its location if the auto-detection fails
to find it).

Table of Contents

CPack Bundle Generator

Variables specific to CPack Bundle generator

Previous topic

CPack Archive Generator

Next topic

CPack Cygwin Generator

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 »

cpack-generators(7) »

CPack Bundle Generator

        © 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 Cygwin Generator — 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 DEB Generator" href="deb.html" />
    <link rel="prev" title="CPack Bundle Generator" href="bundle.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cpack-generators(7) »

CPack Cygwin Generator

CPack Cygwin Generator¶

Cygwin CPack generator (Cygwin).

Variables affecting the CPack Cygwin generator¶

New in version 3.18: CPACK_ARCHIVE_THREADS

Variables specific to CPack Cygwin generator¶

The
following variable is specific to installers build on and/or for
Cygwin:

CPACK_CYGWIN_PATCH_NUMBER¶

The Cygwin patch number.  FIXME: This documentation is incomplete.

CPACK_CYGWIN_PATCH_FILE¶

The Cygwin patch file.  FIXME: This documentation is incomplete.

CPACK_CYGWIN_BUILD_SCRIPT¶

The Cygwin build script.  FIXME: This documentation is incomplete.

Table of Contents

CPack Cygwin Generator

Variables affecting the CPack Cygwin generator

Variables specific to CPack Cygwin generator

Previous topic

CPack Bundle Generator

Next topic

CPack DEB Generator

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 »

cpack-generators(7) »

CPack Cygwin Generator

        © 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 DEB Generator — 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 DragNDrop Generator" href="dmg.html" />
    <link rel="prev" title="CPack Cygwin Generator" href="cygwin.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cpack-generators(7) »

CPack DEB Generator

CPack DEB Generator¶

The built in (binary) CPack DEB generator (Unix only)

Variables specific to CPack Debian (DEB) generator¶

The CPack DEB generator may be used to create DEB package using CPack.
The CPack DEB generator is a CPack generator thus it uses the
CPACK_XXX variables used by CPack.

The CPack DEB generator should work on any Linux host but it will produce
better deb package when Debian specific tools dpkg-xxx are usable on
the build system.

The CPack DEB generator has specific features which are controlled by the
specifics CPACK_DEBIAN_XXX variables.

CPACK_DEBIAN_<COMPONENT>_XXXX variables may be used in order to have
component specific values.  Note however that <COMPONENT> refers to
the grouping name written in upper case. It may be either a component name
or a component GROUP name.

Here are some CPack DEB generator wiki resources that are here for historic
reasons and are no longer maintained but may still prove useful:

https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/Configuration

https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/PackageGenerators#deb-unix-only

List of CPack DEB generator specific variables:

CPACK_DEB_COMPONENT_INSTALL¶

Enable component packaging for CPackDEB

Mandatory:

No

Default:

OFF

If enabled (ON) multiple packages are generated. By default a single package
containing files of all components is generated.

CPACK_DEBIAN_PACKAGE_NAME¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME" title="Permalink to this definition">¶

Set Package control field (variable is automatically transformed to lower
case).

Mandatory:

Yes

Default:

CPACK_PACKAGE_NAME for non-component based
installations

CPACK_DEBIAN_PACKAGE_NAME suffixed with -<COMPONENT>
for component-based installations.

New in version 3.5: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME variables.

See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source

CPACK_DEBIAN_FILE_NAME¶

CPACK_DEBIAN_<COMPONENT>_FILE_NAME<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_FILE_NAME" title="Permalink to this definition">¶

New in version 3.6.

Package file name.

Mandatory:

Yes

Default:

<CPACK_PACKAGE_FILE_NAME>[-<component>].deb

This may be set to:

DEB-DEFAULT

Tell CPack to automatically generate the package file name in deb format:

<PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb

This setting recommended as the preferred behavior, but for backward
compatibility with the CPack DEB generator in CMake prior to version 3.6,
this is not the default.   Without this, duplicate names may occur.
Duplicate files get overwritten and it is up to the packager to set
the variables in a manner that will prevent such errors.

<file-name>[.deb]

Use the given file name.

Changed in version 3.29: The .deb suffix will be automatically added if the file name does
not end in .deb or .ipk.  Previously the suffix was required.

<file-name>.ipk

New in version 3.10.

Use the given file name.
The .ipk suffix is used by the OPKG packaging system.

CPACK_DEBIAN_PACKAGE_EPOCH¶

New in version 3.10.

The Debian package epoch

Mandatory:

No

Default:

None

Optional number that should be incremented when changing versioning schemas
or fixing mistakes in the version numbers of older packages.

CPACK_DEBIAN_PACKAGE_VERSION¶

The Debian package version

Mandatory:

Yes

Default:

CPACK_PACKAGE_VERSION

This variable may contain only alphanumerics (A-Za-z0-9) and the characters
. + - ~ (full stop, plus, hyphen, tilde) and should start with a digit. If
CPACK_DEBIAN_PACKAGE_RELEASE is not set then hyphens are not
allowed.

Note

For backward compatibility with CMake 3.9 and lower a failed test of this
variable's content is not a hard error when both
CPACK_DEBIAN_PACKAGE_RELEASE and
CPACK_DEBIAN_PACKAGE_EPOCH variables are not set. An author
warning is reported instead.

CPACK_DEBIAN_PACKAGE_RELEASE¶

New in version 3.6.

The Debian package release - Debian revision number.

Mandatory:

No

Default:

None

This is the numbering of the DEB package itself, i.e. the version of the
packaging and not the version of the content (see
CPACK_DEBIAN_PACKAGE_VERSION). One may change the default value
if the previous packaging was buggy and/or you want to put here a fancy Linux
distro specific numbering.

CPACK_DEBIAN_PACKAGE_ARCHITECTURE¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE" title="Permalink to this definition">¶

The Debian package architecture

Mandatory:

Yes

Default:

Output of dpkg --print-architecture (or i386
if dpkg is not found)

New in version 3.6: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE variables.

CPACK_DEBIAN_PACKAGE_DEPENDS¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS" title="Permalink to this definition">¶

Sets the Debian dependencies of this package.

Mandatory:

No

Default:

An empty string for non-component based installations

CPACK_DEBIAN_PACKAGE_DEPENDS for component-based
installations.

New in version 3.3: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS variables.

Note

If CPACK_DEBIAN_PACKAGE_SHLIBDEPS or
more specifically CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS
is set for this component, the discovered dependencies will be appended
to CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS instead of
CPACK_DEBIAN_PACKAGE_DEPENDS. If
CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS is an empty string,
only the automatically discovered dependencies will be set for this
component.

Example:

set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)")

CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS¶

New in version 3.6.

Sets inter-component dependencies if listed with
CPACK_COMPONENT_<compName>_DEPENDS variables.

Mandatory:

No

Default:

None

CPACK_DEBIAN_PACKAGE_MAINTAINER¶

The Debian package maintainer

Mandatory:

Yes

Default:

CPACK_PACKAGE_CONTACT

CPACK_DEBIAN_PACKAGE_DESCRIPTION¶

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

The Debian package description

Mandatory:

Yes

Default:

CPACK_DEBIAN_<COMPONENT>_DESCRIPTION (component
based installers only) if set, or CPACK_DEBIAN_PACKAGE_DESCRIPTION if set, or

CPACK_COMPONENT_<compName>_DESCRIPTION (component
based installers only) if set, or CPACK_PACKAGE_DESCRIPTION if set, or

content of the file specified in CPACK_PACKAGE_DESCRIPTION_FILE if set

If after that description is not set, CPACK_PACKAGE_DESCRIPTION_SUMMARY going to be
used if set. Otherwise, CPACK_PACKAGE_DESCRIPTION_SUMMARY will be added as the first
line of description as defined in Debian Policy Manual.

New in version 3.3: Per-component CPACK_COMPONENT_<compName>_DESCRIPTION variables.

New in version 3.16: Per-component CPACK_DEBIAN_<COMPONENT>_DESCRIPTION variables.

New in version 3.16: The CPACK_PACKAGE_DESCRIPTION_FILE variable.

CPACK_DEBIAN_PACKAGE_SECTION¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION" title="Permalink to this definition">¶

Set Section control field e.g. admin, devel, doc, ...

Mandatory:

Yes

Default:

devel

New in version 3.5: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION variables.

See https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections

CPACK_DEBIAN_ARCHIVE_TYPE¶

New in version 3.7.

Deprecated since version 3.14.

The archive format used for creating the Debian package.

Mandatory:

Yes

Default:

gnutar

Possible value is: gnutar

Note

This variable previously defaulted to the paxr value, but dpkg
has never supported that tar format. For backwards compatibility the
paxr value will be mapped to gnutar and a deprecation message
will be emitted.

CPACK_DEBIAN_COMPRESSION_TYPE¶

New in version 3.1.

The compression used for creating the Debian package.

Mandatory:

Yes

Default:

gzip

Possible values are:

lzma

Lempel–Ziv–Markov chain algorithm

xz

XZ Utils compression

bzip2

bzip2 Burrows–Wheeler algorithm

gzip

GNU Gzip compression

zstd

New in version 3.22.

Zstandard compression

CPACK_DEBIAN_PACKAGE_PRIORITY¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY" title="Permalink to this definition">¶

Set Priority control field e.g. required, important, standard, optional,
extra

Mandatory:

Yes

Default:

optional

New in version 3.5: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY variables.

See https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities

CPACK_DEBIAN_PACKAGE_HOMEPAGE¶

The URL of the web site for this package, preferably (when applicable) the
site from which the original source can be obtained and any additional
upstream documentation or information may be found.

Mandatory:

No

Default:

CMAKE_PROJECT_HOMEPAGE_URL

New in version 3.12: The CMAKE_PROJECT_HOMEPAGE_URL variable.

Note

The content of this field is a simple URL without any surrounding
characters such as <>.

CPACK_DEBIAN_PACKAGE_SHLIBDEPS¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS" title="Permalink to this definition">¶

May be set to ON in order to use dpkg-shlibdeps to generate
better package dependency list.

Mandatory:

No

Default:

CPACK_DEBIAN_PACKAGE_SHLIBDEPS if set or

OFF

Note

You may need set CMAKE_INSTALL_RPATH to an appropriate value
if you use this feature, because if you don't dpkg-shlibdeps
may fail to find your own shared libs.
See https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/RPATH-handling

Note

You can also set CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS
to an appropriate value if you use this feature, in order to please
dpkg-shlibdeps. However, you should only do this for private
shared libraries that could not get resolved otherwise.

New in version 3.3: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS variables.

New in version 3.6: Correct handling of $ORIGIN in CMAKE_INSTALL_RPATH.

CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS¶

New in version 3.20.

May be set to a list of directories that will be given to dpkg-shlibdeps
via its -l option. These will be searched by dpkg-shlibdeps in order
to find private shared library dependencies.

Mandatory:

No

Default:

None

Note

You should prefer to set CMAKE_INSTALL_RPATH to an appropriate
value if you use dpkg-shlibdeps. The current option is really only
needed for private shared library dependencies.

CPACK_DEBIAN_PACKAGE_DEBUG¶

May be set when invoking cpack in order to trace debug information
during the CPack DEB generator run.

Mandatory:

No

Default:

None

CPACK_DEBIAN_PACKAGE_PREDEPENDS¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS" title="Permalink to this definition">¶

Sets the Pre-Depends field of the Debian package.
Like Depends, except that it
also forces dpkg to complete installation of the packages named
before even starting the installation of the package which declares the
pre-dependency.

Mandatory:

No

Default:

An empty string for non-component based installations

CPACK_DEBIAN_PACKAGE_PREDEPENDS for component-based
installations.

New in version 3.4: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS variables.

See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps

CPACK_DEBIAN_PACKAGE_ENHANCES¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES" title="Permalink to this definition">¶

Sets the Enhances field of the Debian package.
Similar to Suggests but works
in the opposite direction: declares that a package can enhance the
functionality of another package.

Mandatory:

No

Default:

An empty string for non-component based installations

CPACK_DEBIAN_PACKAGE_ENHANCES for component-based
installations.

New in version 3.4: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES variables.

See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps

CPACK_DEBIAN_PACKAGE_BREAKS¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS" title="Permalink to this definition">¶

Sets the Breaks field of the Debian package.
When a binary package (P) declares that it breaks other packages (B),
dpkg will not allow the package (P) which declares Breaks be
unpacked unless the packages that will be broken (B) are deconfigured
first.
As long as the package (P) is configured, the previously deconfigured
packages (B) cannot be reconfigured again.

Mandatory:

No

Default:

An empty string for non-component based installations

CPACK_DEBIAN_PACKAGE_BREAKS for component-based
installations.

New in version 3.4: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS variables.

See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-breaks

CPACK_DEBIAN_PACKAGE_CONFLICTS¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS" title="Permalink to this definition">¶

Sets the Conflicts field of the Debian package.
When one binary package declares a conflict with another using a Conflicts
field, dpkg will not allow them to be unpacked on the system at
the same time.

Mandatory:

No

Default:

An empty string for non-component based installations

CPACK_DEBIAN_PACKAGE_CONFLICTS for component-based
installations.

New in version 3.4: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS variables.

See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts

Note

This is a stronger restriction than
Breaks, which prevents the
broken package from being configured while the breaking package is in
the "Unpacked" state but allows both packages to be unpacked at the same
time.

CPACK_DEBIAN_PACKAGE_PROVIDES¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES" title="Permalink to this definition">¶

Sets the Provides field of the Debian package.
A virtual package is one which appears in the Provides control field of
another package.

Mandatory:

No

Default:

An empty string for non-component based installations

CPACK_DEBIAN_PACKAGE_PROVIDES for component-based
installations.

New in version 3.4: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES variables.

See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual

CPACK_DEBIAN_PACKAGE_REPLACES¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES" title="Permalink to this definition">¶

Sets the Replaces field of the Debian package.
Packages can declare in their control file that they should overwrite
files in certain other packages, or completely replace other packages.

Mandatory:

No

Default:

An empty string for non-component based installations

CPACK_DEBIAN_PACKAGE_REPLACES for component-based
installations.

New in version 3.4: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES variables.

See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps

CPACK_DEBIAN_PACKAGE_RECOMMENDS¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS" title="Permalink to this definition">¶

Sets the Recommends field of the Debian package.
Allows packages to declare a strong, but not absolute, dependency on other
packages.

Mandatory:

No

Default:

An empty string for non-component based installations

CPACK_DEBIAN_PACKAGE_RECOMMENDS for component-based
installations.

New in version 3.4: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS variables.

See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps

CPACK_DEBIAN_PACKAGE_SUGGESTS¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS" title="Permalink to this definition">¶

Sets the Suggests field of the Debian package.
Allows packages to declare a suggested package install grouping.

Mandatory:

No

Default:

An empty string for non-component based installations

CPACK_DEBIAN_PACKAGE_SUGGESTS for component-based
installations.

New in version 3.4: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS variables.

See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps

CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS¶

New in version 3.6.

Mandatory:

No

Default:

OFF

Allows to generate shlibs control file automatically. Compatibility is defined by
CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY variable value.

Note

Libraries are only considered if they have both library name and version
set. This can be done by setting SOVERSION property with
set_target_properties() command.

CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY¶

New in version 3.6.

Compatibility policy for auto-generated shlibs control file.

Mandatory:

No

Default:

=

Defines compatibility policy for auto-generated shlibs control file.
Possible values: =, >=

See https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-sharedlibs-shlibdeps

CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA" title="Permalink to this definition">¶

This variable allow advanced user to add custom script to the
control.tar.gz.
Typical usage is for conffiles, postinst, postrm, prerm.

Mandatory:

No

Default:

None

Usage:

set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
    "${CMAKE_CURRENT_SOURCE_DIR}/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm")

New in version 3.4: Per-component CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA variables.

CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION" title="Permalink to this definition">¶

New in version 3.4.

This variable indicates if the Debian policy on control files should be
strictly followed.

Mandatory:

No

Default:

FALSE

Usage:

set(CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION TRUE)

This overrides the permissions on the original files, following the rules
set by Debian policy
https://www.debian.org/doc/debian-policy/ch-files.html#s-permissions-owners

Note

The original permissions of the files will be used in the final
package unless this variable is set to TRUE.
In particular, the scripts should have the proper executable
flag prior to the generation of the package.

CPACK_DEBIAN_PACKAGE_SOURCE¶

CPACK_DEBIAN_<COMPONENT>_PACKAGE_SOURCE<a class="headerlink" href="#variable:CPACK_DEBIAN_<COMPONENT>_PACKAGE_SOURCE" title="Permalink to this definition">¶

New in version 3.5.

Sets the Source field of the binary Debian package.
When the binary package name is not the same as the source package name
(in particular when several components/binaries are generated from one
source) the source from which the binary has been generated should be
indicated with the field Source.

Mandatory:

No

Default:

An empty string for non-component based installations

CPACK_DEBIAN_PACKAGE_SOURCE for component-based
installations.

See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source

Note

This value is not interpreted. It is possible to pass an optional
revision number of the referenced source package as well.

Packaging of debug information¶

New in version 3.13.

Dbgsym packages contain debug symbols for debugging packaged binaries.

Dbgsym packaging has its own set of variables:

CPACK_DEBIAN_DEBUGINFO_PACKAGE¶

CPACK_DEBIAN_<component>_DEBUGINFO_PACKAGE<a class="headerlink" href="#variable:CPACK_DEBIAN_<component>_DEBUGINFO_PACKAGE" title="Permalink to this definition">¶

Enable generation of dbgsym .ddeb package(s).

Mandatory:

No

Default:

OFF

Note

Setting this also strips the ELF files in the generated non-dbgsym package,
which results in debuginfo only being available in the dbgsym package.

Note

Binaries must contain debug symbols before packaging so use either Debug
or RelWithDebInfo for CMAKE_BUILD_TYPE variable value.

Additionally, if CPACK_STRIP_FILES is set, the files will be stripped before
they get to the DEB generator, so will not contain debug symbols and
a dbgsym package will not get built. Do not use with CPACK_STRIP_FILES.

Building Debian packages on Windows¶

New in version 3.10.

To communicate UNIX file permissions from the install stage
to the CPack DEB generator the cmake_mode_t NTFS
alternate data stream (ADT) is used.

When a filesystem without ADT support is used only owner read/write
permissions can be preserved.

Reproducible packages¶

New in version 3.13.

The environment variable SOURCE_DATE_EPOCH may be set to a UNIX
timestamp, defined as the number of seconds, excluding leap seconds,
since 01 Jan 1970 00:00:00 UTC.  If set, the CPack DEB generator will
use its value for timestamps in the package.

Table of Contents

CPack DEB Generator

Variables specific to CPack Debian (DEB) generator

Packaging of debug information

Building Debian packages on Windows

Reproducible packages

Previous topic

CPack Cygwin Generator

Next topic

CPack DragNDrop Generator

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 »

cpack-generators(7) »

CPack DEB Generator

        © 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 DragNDrop Generator — 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 External Generator" href="external.html" />
    <link rel="prev" title="CPack DEB Generator" href="deb.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cpack-generators(7) »

CPack DragNDrop Generator

CPack DragNDrop Generator¶

The DragNDrop CPack generator (macOS) creates a DMG image.

Variables specific to CPack DragNDrop generator¶

The following variables are specific to the DragNDrop installers built
on macOS:

CPACK_DMG_VOLUME_NAME¶

The volume name of the generated disk image.

Default:

CPACK_PACKAGE_FILE_NAME

CPACK_DMG_FORMAT¶

The disk image format.

Default:

UDZO

Common values are UDRO (UDIF read-only), UDZO (UDIF
zlib-compressed) or UDBZ (UDIF bzip2-compressed). Refer to hdiutil(1) for
more information on other available formats.

CPACK_DMG_DS_STORE¶

Path to a custom .DS_Store file. This .DS_Store file can be used to
specify the Finder window position/geometry and layout (such as hidden
toolbars, placement of the icons etc.). This file has to be generated by
the Finder (either manually or through AppleScript) using a normal folder
from which the .DS_Store file can then be extracted.

CPACK_DMG_DS_STORE_SETUP_SCRIPT¶

New in version 3.5.

Path to a custom AppleScript file.  This AppleScript is used to generate
a .DS_Store file which specifies the Finder window position/geometry and
layout (such as hidden toolbars, placement of the icons etc.).
By specifying a custom AppleScript there is no need to use
CPACK_DMG_DS_STORE, as the .DS_Store that is generated by the AppleScript
will be packaged.

CPACK_DMG_BACKGROUND_IMAGE¶

Default:

Path to an image file to be used as the background.  This file will be
copied to .background/background.<ext>, where <ext> is the original image file
extension.  The background image is installed into the image before
CPACK_DMG_DS_STORE_SETUP_SCRIPT is executed or CPACK_DMG_DS_STORE is
installed.  By default no background image is set.

CPACK_DMG_DISABLE_APPLICATIONS_SYMLINK¶

New in version 3.6.

Default behavior is to include a symlink to /Applications in the DMG.
Set this option to ON to avoid adding the symlink.

CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE¶

New in version 3.23.

Default:

OFF

Control whether CPACK_RESOURCE_FILE_LICENSE, if set to a
non-default value, is used as the license agreement provided when
mounting the DMG.  If CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE is
not set, cpack(1) defaults to off.

In a CMake project that uses the CPack module to generate
CPackConfig.cmake, CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE
must be explicitly enabled by the project to activate the SLA.
See policy CMP0133.

Note

This option was added in response to macOS 12.0's deprecation of
the hdiutil udifrez command to make its use optional.
CPack 3.22 and below always use CPACK_RESOURCE_FILE_LICENSE,
if set to a non-default value, as the DMG license.

CPACK_DMG_SLA_DIR¶

New in version 3.5.

Directory where license and menu files for different languages are stored.
Setting this causes CPack to look for a <language>.menu.txt and
<language>.license.txt or <language>.license.rtf file for every
language defined in CPACK_DMG_SLA_LANGUAGES.  If both this variable and
CPACK_RESOURCE_FILE_LICENSE are set, CPack will only look for the menu
files and use the same license file for all languages.  If both
<language>.license.txt and <language>.license.rtf exist, the .txt
file will be used.

New in version 3.17: RTF support.

CPACK_DMG_SLA_LANGUAGES¶

New in version 3.5.

Languages for which a license agreement is provided when mounting the
generated DMG. A menu file consists of 9 lines of text. The first line is
is the name of the language itself, uppercase, in English (e.g. German).
The other lines are translations of the following strings:

Agree

Disagree

Print

Save...

You agree to the terms of the License Agreement when you click the
"Agree" button.

Software License Agreement

This text cannot be saved. The disk may be full or locked, or the file
may be locked.

Unable to print. Make sure you have selected a printer.

For every language in this list, CPack will try to find files
<language>.menu.txt and <language>.license.txt in the directory
specified by the CPACK_DMG_SLA_DIR variable.

CPACK_DMG_<component>_FILE_NAME<a class="headerlink" href="#variable:CPACK_DMG_<component>_FILE_NAME" title="Permalink to this definition">¶

New in version 3.17.

File name when packaging <component> as its own DMG
(CPACK_COMPONENTS_GROUPING set to IGNORE).

Default:

CPACK_PACKAGE_FILE_NAME-<component>

CPACK_DMG_FILESYSTEM¶

New in version 3.21.

Default:

HFS+

The filesystem format. Common values are APFS and HFS+.
See man hdiutil for a full list of supported formats.

CPACK_COMMAND_HDIUTIL¶

Path to the hdiutil(1) command used to operate on disk image files on
macOS. This variable can be used to override the automatically detected
command (or specify its location if the auto-detection fails to find it).

CPACK_COMMAND_SETFILE¶

Path to the SetFile(1) command used to set extended attributes on files and
directories on macOS. This variable can be used to override the
automatically detected command (or specify its location if the
auto-detection fails to find it).

CPACK_COMMAND_REZ¶

Path to the Rez(1) command used to compile resources on macOS. This
variable can be used to override the automatically detected command (or
specify its location if the auto-detection fails to find it).

Table of Contents

CPack DragNDrop Generator

Variables specific to CPack DragNDrop generator

Previous topic

CPack DEB Generator

Next topic

CPack External Generator

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 »

cpack-generators(7) »

CPack DragNDrop Generator

        © 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 External Generator — 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 FreeBSD Generator" href="freebsd.html" />
    <link rel="prev" title="CPack DragNDrop Generator" href="dmg.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cpack-generators(7) »

CPack External Generator

CPack External Generator¶

New in version 3.13.

CPack provides many generators to create packages for a variety of platforms
and packaging systems. The intention is for CMake/CPack to be a complete
end-to-end solution for building and packaging a software project. However, it
may not always be possible to use CPack for the entire packaging process, due
to either technical limitations or policies that require the use of certain
tools. For this reason, CPack provides the "External" generator, which allows
external packaging software to take advantage of some of the functionality
provided by CPack, such as component installation and the dependency graph.

Integration with External Packaging Tools¶

The CPack External generator generates a .json file containing the
CPack internal metadata, which gives external software information
on how to package the software. External packaging software may itself
invoke CPack, consume the generated metadata,
install and package files as required.

Alternatively CPack can invoke an external packaging software
through an optional custom CMake script in
CPACK_EXTERNAL_PACKAGE_SCRIPT instead.

Staging of installation files may also optionally be
taken care of by the generator when enabled through the
CPACK_EXTERNAL_ENABLE_STAGING variable.

JSON Format¶

The JSON metadata file contains a list of CPack components and component groups,
the various options passed to cpack_add_component() and
cpack_add_component_group(), the dependencies between the components
and component groups, and various other options passed to CPack.

The JSON's root object will always provide two fields:
formatVersionMajor and formatVersionMinor, which are always integers
that describe the output format of the generator. Backwards-compatible changes
to the output format (for example, adding a new field that didn't exist before)
cause the minor version to be incremented, and backwards-incompatible changes
(for example, deleting a field or changing its meaning) cause the major version
to be incremented and the minor version reset to 0. The format version is
always of the format major.minor. In other words, it always has exactly two
parts, separated by a period.

You can request one or more specific versions of the output format as described
below with CPACK_EXTERNAL_REQUESTED_VERSIONS. The output format will
have a major version that exactly matches the requested major version, and a
minor version that is greater than or equal to the requested minor version. If
no version is requested with CPACK_EXTERNAL_REQUESTED_VERSIONS, the
latest known major version is used by default. Currently, the only supported
format is 1.0, which is described below.

Version 1.0¶

In addition to the standard format fields, format version 1.0 provides the
following fields in the root:

components

The components field is an object with component names as the keys and
objects describing the components as the values. The component objects have
the following fields:

name

The name of the component. This is always the same as the key in the
components object.

displayName

The value of the DISPLAY_NAME field passed to
cpack_add_component().

description

The value of the DESCRIPTION field passed to
cpack_add_component().

isHidden

True if HIDDEN was passed to cpack_add_component(), false if
it was not.

isRequired

True if REQUIRED was passed to cpack_add_component(), false if
it was not.

isDisabledByDefault

True if DISABLED was passed to cpack_add_component(), false if
it was not.

group

Only present if GROUP was passed to cpack_add_component(). If
so, this field is a string value containing the component's group.

dependencies

An array of components the component depends on. This contains the values
in the DEPENDS argument passed to cpack_add_component(). If no
DEPENDS argument was passed, this is an empty list.

installationTypes

An array of installation types the component is part of. This contains the
values in the INSTALL_TYPES argument passed to
cpack_add_component(). If no INSTALL_TYPES argument was
passed, this is an empty list.

isDownloaded

True if DOWNLOADED was passed to cpack_add_component(), false
if it was not.

archiveFile

The name of the archive file passed with the ARCHIVE_FILE argument to
cpack_add_component(). If no ARCHIVE_FILE argument was passed,
this is an empty string.

componentGroups

The componentGroups field is an object with component group names as the
keys and objects describing the component groups as the values. The component
group objects have the following fields:

name

The name of the component group. This is always the same as the key in the
componentGroups object.

displayName

The value of the DISPLAY_NAME field passed to
cpack_add_component_group().

description

The value of the DESCRIPTION field passed to
cpack_add_component_group().

parentGroup

Only present if PARENT_GROUP was passed to
cpack_add_component_group(). If so, this field is a string value
containing the component group's parent group.

isExpandedByDefault

True if EXPANDED was passed to cpack_add_component_group(),
false if it was not.

isBold

True if BOLD_TITLE was passed to cpack_add_component_group(),
false if it was not.

components

An array of names of components that are direct members of the group
(components that have this group as their GROUP). Components of
subgroups are not included.

subgroups

An array of names of component groups that are subgroups of the group
(groups that have this group as their PARENT_GROUP).

installationTypes

The installationTypes field is an object with installation type names as
the keys and objects describing the installation types as the values. The
installation type objects have the following fields:

name

The name of the installation type. This is always the same as the key in
the installationTypes object.

displayName

The value of the DISPLAY_NAME field passed to
cpack_add_install_type().

index

The integer index of the installation type in the list.

projects

The projects field is an array of objects describing CMake projects which
comprise the CPack project. The values in this field are derived from
CPACK_INSTALL_CMAKE_PROJECTS. In most cases, this will be only a
single project. The project objects have the following fields:

projectName

The project name passed to CPACK_INSTALL_CMAKE_PROJECTS.

component

The name of the component or component set which comprises the project.

directory

The build directory of the CMake project. This is the directory which
contains the cmake_install.cmake script.

subDirectory

The subdirectory to install the project into inside the CPack package.

packageName

The package name given in CPACK_PACKAGE_NAME. Only present if
this option is set.

packageVersion

The package version given in CPACK_PACKAGE_VERSION. Only present
if this option is set.

packageDescriptionFile

The package description file given in
CPACK_PACKAGE_DESCRIPTION_FILE. Only present if this option is
set.

packageDescriptionSummary

The package description summary given in
CPACK_PACKAGE_DESCRIPTION_SUMMARY. Only present if this option is
set.

buildConfig

The build configuration given to CPack with the cpack -C option.
Only present if this option is set.

defaultDirectoryPermissions

The default directory permissions given in
CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS. Only present if this
option is set.

setDestdir

True if CPACK_SET_DESTDIR is true, false if it is not.

packagingInstallPrefix

The install prefix given in CPACK_PACKAGING_INSTALL_PREFIX. Only
present if CPACK_SET_DESTDIR is true.

stripFiles

True if CPACK_STRIP_FILES is true, false if it is not.

warnOnAbsoluteInstallDestination

True if CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION is true, false
if it is not.

errorOnAbsoluteInstallDestination

True if CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION is true,
false if it is not.

Variables specific to CPack External generator¶

CPACK_EXTERNAL_REQUESTED_VERSIONS¶

This variable is used to request a specific version of the CPack External
generator. It is a list of major.minor values, separated by semicolons.

If this variable is set to a non-empty value, the CPack External generator
will iterate through each item in the list to search for a version that it
knows how to generate. Requested versions should be listed in order of
descending preference by the client software, as the first matching version
in the list will be generated.

The generator knows how to generate the version if it has a versioned
generator whose major version exactly matches the requested major version,
and whose minor version is greater than or equal to the requested minor
version. For example, if CPACK_EXTERNAL_REQUESTED_VERSIONS contains 1.0, and
the CPack External generator knows how to generate 1.1, it will generate 1.1.
If the generator doesn't know how to generate a version in the list, it skips
the version and looks at the next one. If it doesn't know how to generate any
of the requested versions, an error is thrown.

If this variable is not set, or is empty, the CPack External generator will
generate the highest major and minor version that it knows how to generate.

If an invalid version is encountered in CPACK_EXTERNAL_REQUESTED_VERSIONS (one
that doesn't match major.minor, where major and minor are
integers), it is ignored.

CPACK_EXTERNAL_ENABLE_STAGING¶

This variable can be set to true to enable optional installation
into a temporary staging area which can then be picked up
and packaged by an external packaging tool.
The top level directory used by CPack for the current packaging
task is contained in CPACK_TOPLEVEL_DIRECTORY.
It is automatically cleaned up on each run before packaging is initiated
and can be used for custom temporary files required by
the external packaging tool.
It also contains the staging area CPACK_TEMPORARY_DIRECTORY
into which CPack performs the installation when staging is enabled.

CPACK_EXTERNAL_PACKAGE_SCRIPT¶

This variable can optionally specify the full path to
a CMake script file to be run as part of the CPack invocation.
It is invoked after (optional) staging took place and may
run an external packaging tool. The script has access to
the variables defined by the CPack config file.

CPACK_EXTERNAL_BUILT_PACKAGES¶

New in version 3.19.

The CPACK_EXTERNAL_PACKAGE_SCRIPT script may set this list variable to the
full paths of generated package files.  CPack will copy these files from the
staging directory back to the top build directory and possibly produce
checksum files if the CPACK_PACKAGE_CHECKSUM is set.

Table of Contents

CPack External Generator

Integration with External Packaging Tools

JSON Format

Version 1.0

Variables specific to CPack External generator

Previous topic

CPack DragNDrop Generator

Next topic

CPack FreeBSD Generator

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 »

cpack-generators(7) »

CPack External Generator

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