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>cmake_path — 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_policy" href="cmake_policy.html" />
    <link rel="prev" title="cmake_parse_arguments" href="cmake_parse_arguments.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

cmake_path

cmake_path¶

New in version 3.20.

This command is for the manipulation of paths.  Only syntactic aspects of
paths are handled, there is no interaction of any kind with any underlying
file system.  The path may represent a non-existing path or even one that
is not allowed to exist on the current file system or platform.
For operations that do interact with the filesystem, see the file()
command.

Note

The cmake_path command handles paths in the format of the build system
(i.e. the host platform), not the target system.  When cross-compiling,
if the path contains elements that are not representable on the host
platform (e.g. a drive letter when the host is not Windows), the results
will be unpredictable.

Synopsis¶

Conventions

Path Structure And Terminology

Normalization

Decomposition
  cmake_path(GET <path-var> ROOT_NAME <out-var>)
  cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
  cmake_path(GET <path-var> ROOT_PATH <out-var>)
  cmake_path(GET <path-var> FILENAME <out-var>)
  cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
  cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
  cmake_path(GET <path-var> RELATIVE_PART <out-var>)
  cmake_path(GET <path-var> PARENT_PATH <out-var>)

Query
  cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
  cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
  cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
  cmake_path(HAS_FILENAME <path-var> <out-var>)
  cmake_path(HAS_EXTENSION <path-var> <out-var>)
  cmake_path(HAS_STEM <path-var> <out-var>)
  cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
  cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
  cmake_path(IS_ABSOLUTE <path-var> <out-var>)
  cmake_path(IS_RELATIVE <path-var> <out-var>)
  cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
  cmake_path(COMPARE <input1> <OP> <input2> <out-var>)

Modification
  cmake_path(SET <path-var> [NORMALIZE] <input>)
  cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
  cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
  cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
  cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
  cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>])
  cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>])

Generation
  cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
  cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>])
  cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>])

Native Conversion
  cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
  cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
  cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])

Hashing
  cmake_path(HASH <path-var> <out-var>)

Conventions¶

The following conventions are used in this command's documentation:

<path-var>

Always the name of a variable.  For commands that expect a <path-var>
as input, the variable must exist and it is expected to hold a single path.

<input>

A string literal which may contain a path, path fragment, or multiple paths
with a special separator depending on the command.  See the description of
each command to see how this is interpreted.

<input>...

Zero or more string literal arguments.

<out-var>

The name of a variable into which the result of a command will be written.

Path Structure And Terminology¶

A path has the following structure (all components are optional, with some
constraints):

root-name root-directory-separator (item-name directory-separator)* filename

root-name

Identifies the root on a filesystem with multiple roots (such as "C:"
or "//myserver"). It is optional.

root-directory-separator

A directory separator that, if present, indicates that this path is
absolute.  If it is missing and the first element other than the
root-name is an item-name, then the path is relative.

item-name

A sequence of characters that aren't directory separators.  This name may
identify a file, a hard link, a symbolic link, or a directory.  Two special
cases are recognized:

The item name consisting of a single dot character . is a
directory name that refers to the current directory.

The item name consisting of two dot characters .. is a
directory name that refers to the parent directory.

The (...)* pattern shown above is to indicate that there can be zero
or more item names, with multiple items separated by a
directory-separator.  The ()* characters are not part of the path.

directory-separator

The only recognized directory separator is a forward slash character /.
If this character is repeated, it is treated as a single directory
separator.  In other words, /usr///////lib is the same as /usr/lib.

filename

A path has a filename if it does not end with a directory-separator.
The filename is effectively the last item-name of the path, so it
can also be a hard link, symbolic link or a directory.

A filename can have an extension.  By default, the extension is
defined as the sub-string beginning at the left-most period (including
the period) and until the end of the filename.  In commands that
accept a LAST_ONLY keyword, LAST_ONLY changes the interpretation
to the sub-string beginning at the right-most period.

The following exceptions apply to the above interpretation:

If the first character in the filename is a period, that period is
ignored (i.e. a filename like ".profile" is treated as having
no extension).

If the filename is either . or .., it has no extension.

The stem is the part of the filename before the extension.

Some commands refer to a root-path.  This is the concatenation of
root-name and root-directory-separator, either or both of which can
be empty.  A relative-part refers to the full path with any root-path
removed.

Creating A Path Variable¶

While a path can be created with care using an ordinary set()
command, it is recommended to use cmake_path(SET)
instead, as it automatically converts the path to the required form where
required.  The cmake_path(APPEND) subcommand may
be another suitable alternative where a path needs to be constructed by
joining fragments.  The following example compares the three methods for
constructing the same path:

set(path1 "${CMAKE_CURRENT_SOURCE_DIR}/data")

cmake_path(SET path2 "${CMAKE_CURRENT_SOURCE_DIR}/data")

cmake_path(APPEND path3 "${CMAKE_CURRENT_SOURCE_DIR}" "data")

Modification and Generation sub-commands can either store the result
in-place, or in a separate variable named after an OUTPUT_VARIABLE
keyword.  All other sub-commands store the result in a mandatory <out-var>
variable.

Normalization¶

Some sub-commands support normalizing a path.  The algorithm used to
normalize a path is as follows:

If the path is empty, stop (the normalized form of an empty path is
also an empty path).

Replace each directory-separator, which may consist of multiple
separators, with a single / (/a///b  --> /a/b).

Remove each solitary period (.) and any immediately following
directory-separator (/a/./b/. --> /a/b).

Remove each item-name (other than ..) that is immediately
followed by a directory-separator and a .., along with any
immediately following directory-separator (/a/b/../c --> a/c).

If there is a root-directory, remove any .. and any
directory-separators immediately following them.  The parent of the
root directory is treated as still the root directory (/../a --> /a).

If the last item-name is .., remove any trailing
directory-separator (../ --> ..).

If the path is empty by this stage, add a dot (normal form of ./
is .).

Decomposition¶

The following forms of the GET subcommand each retrieve a different
component or group of components from a path.  See
Path Structure And Terminology for the meaning of each path component.

cmake_path(GET <path-var> ROOT_NAME <out-var>)
cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
cmake_path(GET <path-var> ROOT_PATH <out-var>)
cmake_path(GET <path-var> FILENAME <out-var>)
cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
cmake_path(GET <path-var> RELATIVE_PART <out-var>)
cmake_path(GET <path-var> PARENT_PATH <out-var>)

If a requested component is not present in the path, an empty string will be
stored in <out-var>.  For example, only Windows systems have the concept
of a root-name, so when the host machine is non-Windows, the ROOT_NAME
subcommand will always return an empty string.

For PARENT_PATH, if the HAS_RELATIVE_PART subcommand returns false,
the result is a copy of <path-var>.  Note that this implies that a root
directory is considered to have a parent, with that parent being itself.
Where HAS_RELATIVE_PART returns true, the result will essentially be
<path-var> with one less element.

Root examples¶

set(path "c:/a")

cmake_path(GET path ROOT_NAME rootName)
cmake_path(GET path ROOT_DIRECTORY rootDir)
cmake_path(GET path ROOT_PATH rootPath)

message("Root name is \"${rootName}\"")
message("Root directory is \"${rootDir}\"")
message("Root path is \"${rootPath}\"")

Root name is "c:"
Root directory is "/"
Root path is "c:/"

Filename examples¶

set(path "/a/b")
cmake_path(GET path FILENAME filename)
message("First filename is \"${filename}\"")

# Trailing slash means filename is empty
set(path "/a/b/")
cmake_path(GET path FILENAME filename)
message("Second filename is \"${filename}\"")

First filename is "b"
Second filename is ""

Extension and stem examples¶

set(path "name.ext1.ext2")

cmake_path(GET path EXTENSION fullExt)
cmake_path(GET path STEM fullStem)
message("Full extension is \"${fullExt}\"")
message("Full stem is \"${fullStem}\"")

# Effect of LAST_ONLY
cmake_path(GET path EXTENSION LAST_ONLY lastExt)
cmake_path(GET path STEM LAST_ONLY lastStem)
message("Last extension is \"${lastExt}\"")
message("Last stem is \"${lastStem}\"")

# Special cases
set(dotPath "/a/.")
set(dotDotPath "/a/..")
set(someMorePath "/a/.some.more")
cmake_path(GET dotPath EXTENSION dotExt)
cmake_path(GET dotPath STEM dotStem)
cmake_path(GET dotDotPath EXTENSION dotDotExt)
cmake_path(GET dotDotPath STEM dotDotStem)
cmake_path(GET dotMorePath EXTENSION someMoreExt)
cmake_path(GET dotMorePath STEM someMoreStem)
message("Dot extension is \"${dotExt}\"")
message("Dot stem is \"${dotStem}\"")
message("Dot-dot extension is \"${dotDotExt}\"")
message("Dot-dot stem is \"${dotDotStem}\"")
message(".some.more extension is \"${someMoreExt}\"")
message(".some.more stem is \"${someMoreStem}\"")

Full extension is ".ext1.ext2"
Full stem is "name"
Last extension is ".ext2"
Last stem is "name.ext1"
Dot extension is ""
Dot stem is "."
Dot-dot extension is ""
Dot-dot stem is ".."
.some.more extension is ".more"
.some.more stem is ".some"

Relative part examples¶

set(path "c:/a/b")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")

set(path "c/d")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")

set(path "/")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")

Relative part is "a/b"
Relative part is "c/d"
Relative part is ""

Path traversal examples¶

set(path "c:/a/b")
cmake_path(GET path PARENT_PATH result)
message("Parent path is \"${result}\"")

set(path "c:/")
cmake_path(GET path PARENT_PATH result)
message("Parent path is \"${result}\"")

Parent path is "c:/a"
Parent path is "c:/"

Query¶

Each of the GET subcommands has a corresponding HAS_...
subcommand which can be used to discover whether a particular path
component is present.  See Path Structure And Terminology for the
meaning of each path component.

cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
cmake_path(HAS_FILENAME <path-var> <out-var>)
cmake_path(HAS_EXTENSION <path-var> <out-var>)
cmake_path(HAS_STEM <path-var> <out-var>)
cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
cmake_path(HAS_PARENT_PATH <path-var> <out-var>)

Each of the above follows the predictable pattern of setting <out-var>
to true if the path has the associated component, or false otherwise.
Note the following special cases:

For HAS_ROOT_PATH, a true result will only be returned if at least one
of root-name or root-directory is non-empty.

For HAS_PARENT_PATH, the root directory is also considered to have a
parent, which will be itself.  The result is true except if the path
consists of just a filename.

cmake_path(IS_ABSOLUTE <path-var> <out-var>)

Sets <out-var> to true if <path-var> is absolute.  An absolute path
is a path that unambiguously identifies the location of a file without
reference to an additional starting location.  On Windows, this means the
path must have both a root-name and a root-directory-separator to be
considered absolute.  On other platforms, just a root-directory-separator
is sufficient.  Note that this means on Windows, IS_ABSOLUTE can be
false while HAS_ROOT_DIRECTORY can be true.

cmake_path(IS_RELATIVE <path-var> <out-var>)

This will store the opposite of IS_ABSOLUTE in <out-var>.

cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)

Checks if <path-var> is the prefix of <input>.

When the NORMALIZE option is specified, <path-var> and <input>
are normalized before the check.

set(path "/a/b/c")
cmake_path(IS_PREFIX path "/a/b/c/d" result) # result = true
cmake_path(IS_PREFIX path "/a/b" result)     # result = false
cmake_path(IS_PREFIX path "/x/y/z" result)   # result = false

set(path "/a/b")
cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result)   # result = true

cmake_path(COMPARE <input1> EQUAL <input2> <out-var>)
cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)

Compares the lexical representations of two paths provided as string literals.
No normalization is performed on either path, except multiple consecutive
directory separators are effectively collapsed into a single separator.
Equality is determined according to the following pseudo-code logic:

if(NOT <input1>.root_name() STREQUAL <input2>.root_name())
  return FALSE

if(<input1>.has_root_directory() XOR <input2>.has_root_directory())
  return FALSE

Return FALSE if a relative portion of <input1> is not lexicographically
equal to the relative portion of <input2>. This comparison is performed path
component-wise. If all of the components compare equal, then return TRUE.

Note

Unlike most other cmake_path() subcommands, the COMPARE subcommand
takes literal strings as input, not the names of variables.

Modification¶

cmake_path(SET <path-var> [NORMALIZE] <input>)

Assign the <input> path to <path-var>.  If <input> is a native
path, it is converted into a cmake-style path with forward-slashes
(/). On Windows, the long filename marker is taken into account.

When the NORMALIZE option is specified, the path is normalized after the conversion.

For example:

set(native_path "c:\\a\\b/..\\c")
cmake_path(SET path "${native_path}")
message("CMake path is \"${path}\"")

cmake_path(SET path NORMALIZE "${native_path}")
message("Normalized CMake path is \"${path}\"")

Output:

CMake path is "c:/a/b/../c"
Normalized CMake path is "c:/a/c"

cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])

Append all the <input> arguments to the <path-var> using / as
the directory-separator.  Depending on the <input>, the previous
contents of <path-var> may be discarded.  For each <input> argument,
the following algorithm (pseudo-code) applies:

# <path> is the contents of <path-var>

if(<input>.is_absolute() OR
   (<input>.has_root_name() AND
    NOT <input>.root_name() STREQUAL <path>.root_name()))
  replace <path> with <input>
  return()
endif()

if(<input>.has_root_directory())
  remove any root-directory and the entire relative path from <path>
elseif(<path>.has_filename() OR
       (NOT <path-var>.has_root_directory() OR <path>.is_absolute()))
  append directory-separator to <path>
endif()

append <input> omitting any root-name to <path>

cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])

Append all the <input> arguments to the <path-var> without adding any
directory-separator.

cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])

Removes the filename component (as returned by
GET ... FILENAME) from <path-var>.  After removal,
any trailing directory-separator is left alone, if present.

If OUTPUT_VARIABLE is not given, then after this function returns,
HAS_FILENAME returns false for <path-var>.

For example:

set(path "/a/b")
cmake_path(REMOVE_FILENAME path)
message("First path is \"${path}\"")

# filename is now already empty, the following removes nothing
cmake_path(REMOVE_FILENAME path)
message("Second path is \"${result}\"")

Output:

First path is "/a/"
Second path is "/a/"

cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])

Replaces the filename component from <path-var>
with <input>.  If <path-var> has no filename component (i.e.
HAS_FILENAME returns false), the path is unchanged.  The operation is
equivalent to the following:

cmake_path(HAS_FILENAME path has_filename)
if(has_filename)
  cmake_path(REMOVE_FILENAME path)
  cmake_path(APPEND path input);
endif()

cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY]
                                       [OUTPUT_VARIABLE <out-var>])

Removes the extension, if any, from <path-var>.

cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input>
                             [OUTPUT_VARIABLE <out-var>])

Replaces the extension with <input>.  Its effect
is equivalent to the following:

cmake_path(REMOVE_EXTENSION path)
if(NOT "input" MATCHES "^\\.")
  cmake_path(APPEND_STRING path ".")
endif()
cmake_path(APPEND_STRING path "input")

Generation¶

cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])

Normalize <path-var> according the steps described in Normalization.

cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>]
                                    [OUTPUT_VARIABLE <out-var>])

Modifies <path-var> to make it relative to the BASE_DIRECTORY argument.
If BASE_DIRECTORY is not specified, the default base directory will be
CMAKE_CURRENT_SOURCE_DIR.

For reference, the algorithm used to compute the relative path is the same
as that used by C++
std::filesystem::path::lexically_relative.

cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE]
                                    [OUTPUT_VARIABLE <out-var>])

If <path-var> is a relative path (IS_RELATIVE is true), it is evaluated
relative to the given base directory specified by BASE_DIRECTORY option.
If BASE_DIRECTORY is not specified, the default base directory will be
CMAKE_CURRENT_SOURCE_DIR.

When the NORMALIZE option is specified, the path is normalized after the path computation.

Because cmake_path() does not access the filesystem, symbolic links are
not resolved and any leading tilde is not expanded.  To compute a real path
with symbolic links resolved and leading tildes expanded, use the
file(REAL_PATH) command instead.

Native Conversion¶

For commands in this section, native refers to the host platform, not the
target platform when cross-compiling.

cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)

Converts a cmake-style <path-var> into a native path with
platform-specific slashes (\ on Windows hosts and / elsewhere).

When the NORMALIZE option is specified, the path is normalized before the conversion.

cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])

Converts a native <input> path into a cmake-style path with forward
slashes (/).  On Windows hosts, the long filename marker is taken into
account.  The input can be a single path or a system search path like
$ENV{PATH}.  A search path will be converted to a cmake-style list
separated by ; characters (on non-Windows platforms, this essentially
means : separators are replaced with ;).  The result of the
conversion is stored in the <out-var> variable.

When the NORMALIZE option is specified, the path is normalized before the conversion.

Note

Unlike most other cmake_path() subcommands, the CONVERT subcommand
takes a literal string as input, not the name of a variable.

cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])

Converts a cmake-style <input> path into a native path with
platform-specific slashes (\ on Windows hosts and / elsewhere).
The input can be a single path or a cmake-style list.  A list will be
converted into a native search path (;-separated on Windows,
:-separated on other platforms).  The result of the conversion is
stored in the <out-var> variable.

When the NORMALIZE option is specified, the path is normalized before the conversion.

Note

Unlike most other cmake_path() subcommands, the CONVERT subcommand
takes a literal string as input, not the name of a variable.

For example:

set(paths "/a/b/c" "/x/y/z")
cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths)
message("Native path list is \"${native_paths}\"")

Output on Windows:

Native path list is "\a\b\c;\x\y\z"

Output on all other platforms:

Native path list is "/a/b/c:/x/y/z"

Hashing¶

cmake_path(HASH <path-var> <out-var>)

Compute a hash value of <path-var> such that for two paths p1 and
p2 that compare equal (COMPARE ... EQUAL), the hash
value of p1 is equal to the hash value of p2.  The path is always
normalized before the hash is computed.

Table of Contents

cmake_path

Synopsis

Conventions

Path Structure And Terminology

Creating A Path Variable

Normalization

Decomposition

Root examples

Filename examples

Extension and stem examples

Relative part examples

Path traversal examples

Query

Modification

Generation

Native Conversion

Hashing

Previous topic

cmake_parse_arguments

Next topic

cmake_policy

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

cmake_path

        © 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>cmake_policy — 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="configure_file" href="configure_file.html" />
    <link rel="prev" title="cmake_path" href="cmake_path.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

cmake_policy

cmake_policy¶

Manage CMake Policy settings.  See the cmake-policies(7)
manual for defined policies.

As CMake evolves it is sometimes necessary to change existing behavior
in order to fix bugs or improve implementations of existing features.
The CMake Policy mechanism is designed to help keep existing projects
building as new versions of CMake introduce changes in behavior.  Each
new policy (behavioral change) is given an identifier of the form
CMP<NNNN> where <NNNN> is an integer index.  Documentation
associated with each policy describes the OLD and NEW behavior
and the reason the policy was introduced.  Projects may set each policy
to select the desired behavior.  When CMake needs to know which behavior
to use it checks for a setting specified by the project.  If no
setting is available the OLD behavior is assumed and a warning is
produced requesting that the policy be set.

Setting Policies by CMake Version¶

The cmake_policy command is used to set policies to OLD or NEW
behavior.  While setting policies individually is supported, we
encourage projects to set policies based on CMake versions:

cmake_policy(VERSION <min>[...<max>])¶

New in version 3.12: The optional <max> version.

<min> and the optional <max> are each CMake versions of the form
major.minor[.patch[.tweak]], and the ... is literal.  The <min>
version must be at least 2.4 and at most the running version of CMake.
The <max> version, if specified, must be at least the <min> version
but may exceed the running version of CMake.  If the running version of
CMake is older than 3.12, the extra ... dots will be seen as version
component separators, resulting in the ...<max> part being ignored and
preserving the pre-3.12 behavior of basing policies on <min>.

This specifies that the current CMake code is written for the given
range of CMake versions.  All policies known to the running version of CMake
and introduced in the <min> (or <max>, if specified) version
or earlier will be set to use NEW behavior.  All policies
introduced in later versions will be unset (unless the
CMAKE_POLICY_DEFAULT_CMP<NNNN> variable sets a default).
This effectively requests behavior preferred as of a given CMake
version and tells newer CMake versions to warn about their new policies.

Note that the cmake_minimum_required(VERSION)
command implicitly calls cmake_policy(VERSION) too.

Changed in version 3.27: Compatibility with versions of CMake older than 3.5 is deprecated.
Calls to cmake_minimum_required(VERSION) or
cmake_policy(VERSION) that do not specify at least
3.5 as their policy version (optionally via ...<max>)
will produce a deprecation warning in CMake 3.27 and above.

Changed in version 3.19: Compatibility with versions of CMake older than 2.8.12 is deprecated.
Calls to cmake_minimum_required(VERSION) or
cmake_policy(VERSION) that do not specify at least
2.8.12 as their policy version (optionally via ...<max>)
will produce a deprecation warning in CMake 3.19 and above.

Setting Policies Explicitly¶

cmake_policy(SET CMP<NNNN> NEW|OLD)¶

Tell CMake to use the OLD or NEW behavior for a given policy.
Projects depending on the old behavior of a given policy may silence a
policy warning by setting the policy state to OLD.  Alternatively
one may fix the project to work with the new behavior and set the
policy state to NEW.

Note

The OLD behavior of a policy is
deprecated by definition
and may be removed in a future version of CMake.

Checking Policy Settings¶

cmake_policy(GET CMP<NNNN> <variable>)¶

Check whether a given policy is set to OLD or NEW behavior.
The output <variable> value will be OLD or NEW if the
policy is set, and empty otherwise.

CMake Policy Stack¶

CMake keeps policy settings on a stack, so changes made by the
cmake_policy command affect only the top of the stack.  A new entry on
the policy stack is managed automatically for each subdirectory to
protect its parents and siblings.  CMake also manages a new entry for
scripts loaded by include() and find_package() commands
except when invoked with the NO_POLICY_SCOPE option
(see also policy CMP0011).
The cmake_policy command provides an interface to manage custom
entries on the policy stack:

cmake_policy(PUSH)¶

Create a new entry on the policy stack.

cmake_policy(POP)¶

Remove the last policy stack entry created with cmake_policy(PUSH).

Each PUSH must have a matching POP to erase any changes.
This is useful to make temporary changes to policy settings.
Calls to the cmake_minimum_required(VERSION),
cmake_policy(VERSION), or cmake_policy(SET) commands
influence only the current top of the policy stack.

New in version 3.25: The block(SCOPE_FOR POLICIES) command offers a more flexible
and more secure way to manage the policy stack. The pop action is done
automatically when leaving the block scope, so there is no need to
precede each return() with a call to cmake_policy(POP).

# stack management with cmake_policy()
function(my_func)
  cmake_policy(PUSH)
  cmake_policy(SET ...)
  if (<cond1>)
    ...
    cmake_policy(POP)
    return()
  elseif(<cond2>)
    ...
    cmake_policy(POP)
    return()
  endif()
  ...
  cmake_policy(POP)
endfunction()

# stack management with block()/endblock()
function(my_func)
  block(SCOPE_FOR POLICIES)
    cmake_policy(SET ...)
    if (<cond1>)
      ...
      return()
    elseif(<cond2>)
      ...
      return()
    endif()
    ...
  endblock()
endfunction()

Commands created by the function() and macro()
commands record policy settings when they are created and
use the pre-record policies when they are invoked.  If the function or
macro implementation sets policies, the changes automatically
propagate up through callers until they reach the closest nested
policy stack entry.

See Also¶

cmake_minimum_required()

Table of Contents

cmake_policy

Setting Policies by CMake Version

Setting Policies Explicitly

Checking Policy Settings

CMake Policy Stack

See Also

Previous topic

cmake_path

Next topic

configure_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) »

cmake_policy

        © 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>configure_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="continue" href="continue.html" />
    <link rel="prev" title="cmake_policy" href="cmake_policy.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

configure_file

configure_file¶

Contents

configure_file

Options

Transformations

Example

See Also

Copy a file to another location and modify its contents.

configure_file(<input> <output>
               [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
                FILE_PERMISSIONS <permissions>...]
               [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
               [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

Copies an <input> file to an <output> file while performing
transformations of the input file content.

If the input file is modified the build system will re-run CMake to
re-configure the file and generate the build system again.
The generated file is modified and its timestamp updated on subsequent
cmake runs only if its content is changed.

Options¶

The options are:

<input>

Path to the input file.  A relative path is treated with respect to
the value of CMAKE_CURRENT_SOURCE_DIR.  The input path
must be a file, not a directory.

<output>

Path to the output file or directory.  A relative path is treated
with respect to the value of CMAKE_CURRENT_BINARY_DIR.
If the path names an existing directory the output file is placed
in that directory with the same file name as the input file.
If the path contains non-existent directories, they are created.

NO_SOURCE_PERMISSIONS

New in version 3.19.

Do not transfer the permissions of the input file to the output file.
The copied file permissions default to the standard 644 value
(-rw-r--r--).

USE_SOURCE_PERMISSIONS

New in version 3.20.

Transfer the permissions of the input file to the output file.
This is already the default behavior if none of the three permissions-related
keywords are given (NO_SOURCE_PERMISSIONS, USE_SOURCE_PERMISSIONS
or FILE_PERMISSIONS).  The USE_SOURCE_PERMISSIONS keyword mostly
serves as a way of making the intended behavior clearer at the call site.

FILE_PERMISSIONS <permissions>...

New in version 3.20.

Ignore the input file's permissions and use the specified <permissions>
for the output file instead.

COPYONLY

Copy the file without replacing any variable references or other
content.  This option may not be used with NEWLINE_STYLE.

ESCAPE_QUOTES

Escape any substituted quotes with backslashes (C-style).

@ONLY

Restrict variable replacement to references of the form @VAR@.
This is useful for configuring scripts that use ${VAR} syntax.

NEWLINE_STYLE <style>

Specify the newline style for the output file.  Specify
UNIX or LF for \n newlines, or specify
DOS, WIN32, or CRLF for \r\n newlines.
This option may not be used with COPYONLY.

Transformations¶

Variables referenced in the input
file content as @VAR@, ${VAR}, $CACHE{VAR}, and
environment variables
referenced as $ENV{VAR}, will each be replaced with the current value
of the variable, or the empty string if the variable is not defined.
Furthermore, input lines of the form

#cmakedefine VAR ...

will be replaced with either

#define VAR ...

or

/* #undef VAR */

depending on whether VAR is set in CMake to any value not considered
a false constant by the if() command.  The "..." content on the
line after the variable name, if any, is processed as above.

Unlike lines of the form #cmakedefine VAR ..., in lines of the form
#cmakedefine01 VAR, VAR itself will expand to VAR 0 or VAR 1
rather than being assigned the value .... Therefore, input lines of the form

#cmakedefine01 VAR

will be replaced with either

#define VAR 0

or

#define VAR 1

Input lines of the form #cmakedefine01 VAR ... will expand
as #cmakedefine01 VAR ... 0 or #cmakedefine01 VAR ... 1,
which may lead to undefined behavior.

New in version 3.10: The result lines (with the exception of the #undef comments) can be
indented using spaces and/or tabs between the # character
and the cmakedefine or cmakedefine01 words. This whitespace
indentation will be preserved in the output lines:

#  cmakedefine VAR
#  cmakedefine01 VAR

will be replaced, if VAR is defined, with

#  define VAR
#  define VAR 1

Example¶

Consider a source tree containing a foo.h.in file:

#cmakedefine FOO_ENABLE
#cmakedefine FOO_STRING "@FOO_STRING@"

An adjacent CMakeLists.txt may use configure_file to
configure the header:

option(FOO_ENABLE "Enable Foo" ON)
if(FOO_ENABLE)
  set(FOO_STRING "foo")
endif()
configure_file(foo.h.in foo.h @ONLY)

This creates a foo.h in the build directory corresponding to
this source directory.  If the FOO_ENABLE option is on, the
configured file will contain:

#define FOO_ENABLE
#define FOO_STRING "foo"

Otherwise it will contain:

/* #undef FOO_ENABLE */
/* #undef FOO_STRING */

One may then use the target_include_directories() command to
specify the output directory as an include directory:

target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}")

so that sources may include the header as #include <foo.h>.

See Also¶

file(GENERATE)

Table of Contents

configure_file

Options

Transformations

Example

See Also

Previous topic

cmake_policy

Next topic

continue

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

configure_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>continue — 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="else" href="else.html" />
    <link rel="prev" title="configure_file" href="configure_file.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

continue

continue¶

New in version 3.2.

Continue to the top of enclosing foreach or while loop.

continue()

The continue() command allows a cmake script to abort the rest of the
current iteration of a foreach() or while() loop, and start
at the top of the next iteration.

See also the break() command.

Previous topic

configure_file

Next topic

else

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

continue

        © 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>create_test_sourcelist — 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="define_property" href="define_property.html" />
    <link rel="prev" title="cmake_file_api" href="cmake_file_api.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

create_test_sourcelist

create_test_sourcelist¶

Create a test driver program that links together many small tests into a
single executable.  This is useful when building static executables with
large libraries to shrink the total required size.

create_test_sourcelist(<sourceListName> <driverName> <test>... <options>...)¶

Generate a test driver source file from a list of individual test sources
and provide a combined list of sources that can be built as an executable.

The options are:

<sourceListName>

The name of a variable in which to store the list of source files needed
to build the test driver.  The list will contain the <test>... sources
and the generated <driverName> source.

Changed in version 3.29: The test driver source is listed by absolute path in the build tree.
Previously it was listed only as <driverName>.

<driverName>

Name of the test driver source file to be generated into the build tree.
The source file will contain a main() program entry point that
dispatches to whatever test is named on the command line.

<test>...

Test source files to be added to the driver binary.  Each test source
file must have a function in it that is the same name as the file with the
extension removed.  For example, a foo.cxx test source might contain:

int foo(int argc, char** argv)

EXTRA_INCLUDE <header>

Specify a header file to #include in the generated test driver source.

FUNCTION <function>

Specify a function to be called with pointers to argc and argv.
The function may be provided in the EXTRA_INCLUDE header:

void function(int* pargc, char*** pargv)

This can be used to add extra command line processing to each test.

Additionally, some CMake variables affect test driver generation:

CMAKE_TESTDRIVER_BEFORE_TESTMAIN¶

Code to be placed directly before calling each test's function.

CMAKE_TESTDRIVER_AFTER_TESTMAIN¶

Code to be placed directly after the call to each test's function.

Previous topic

cmake_file_api

Next topic

define_property

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

create_test_sourcelist

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

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_build

ctest_build¶

Perform the CTest Build Step as a Dashboard Client.

ctest_build([BUILD <build-dir>] [APPEND]
            [CONFIGURATION <config>]
            [PARALLEL_LEVEL <parallel>]
            [FLAGS <flags>]
            [PROJECT_NAME <project-name>]
            [TARGET <target-name>]
            [NUMBER_ERRORS <num-err-var>]
            [NUMBER_WARNINGS <num-warn-var>]
            [RETURN_VALUE <result-var>]
            [CAPTURE_CMAKE_ERROR <result-var>]
            )

Build the project and store results in Build.xml
for submission with the ctest_submit() command.

The CTEST_BUILD_COMMAND variable may be set to explicitly
specify the build command line.  Otherwise the build command line is
computed automatically based on the options given.

The options are:

BUILD <build-dir>

Specify the top-level build directory.  If not given, the
CTEST_BINARY_DIRECTORY variable is used.

APPEND

Mark Build.xml for append to results previously submitted to a
dashboard server since the last ctest_start() call.
Append semantics are defined by the dashboard server in use.
This does not cause results to be appended to a .xml file
produced by a previous call to this command.

CONFIGURATION <config>

Specify the build configuration (e.g. Debug).  If not
specified the CTEST_BUILD_CONFIGURATION variable will be checked.
Otherwise the -C <cfg> option given to the
ctest(1) command will be used, if any.

PARALLEL_LEVEL <parallel>

New in version 3.21.

Specify the parallel level of the underlying build system.  If not
specified, the CMAKE_BUILD_PARALLEL_LEVEL environment
variable will be checked.

FLAGS <flags>

Pass additional arguments to the underlying build command.
If not specified the CTEST_BUILD_FLAGS variable will be checked.
This can, e.g., be used to trigger a parallel build using the
-j option of make. See the ProcessorCount module
for an example.

PROJECT_NAME <project-name>

Ignored since CMake 3.0.

Changed in version 3.14: This value is no longer required.

TARGET <target-name>

Specify the name of a target to build.  If not specified the
CTEST_BUILD_TARGET variable will be checked.  Otherwise the
default target will be built.  This is the "all" target
(called ALL_BUILD in Visual Studio Generators).

NUMBER_ERRORS <num-err-var>

Store the number of build errors detected in the given variable.

NUMBER_WARNINGS <num-warn-var>

Store the number of build warnings detected in the given variable.

RETURN_VALUE <result-var>

Store the return value of the native build tool in the given variable.

CAPTURE_CMAKE_ERROR <result-var>

New in version 3.7.

Store in the <result-var> variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.

QUIET

New in version 3.3.

Suppress any CTest-specific non-error output that would have been
printed to the console otherwise.  The summary of warnings / errors,
as well as the output from the native build tool is unaffected by
this option.

Previous topic

try_run

Next topic

ctest_configure

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

ctest_build

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

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_configure

ctest_configure¶

Perform the CTest Configure Step as a Dashboard Client.

ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
                [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
                [CAPTURE_CMAKE_ERROR <result-var>])

Configure the project build tree and record results in Configure.xml
for submission with the ctest_submit() command.

The options are:

BUILD <build-dir>

Specify the top-level build directory.  If not given, the
CTEST_BINARY_DIRECTORY variable is used.

SOURCE <source-dir>

Specify the source directory.  If not given, the
CTEST_SOURCE_DIRECTORY variable is used.

APPEND

Mark Configure.xml for append to results previously submitted to a
dashboard server since the last ctest_start() call.
Append semantics are defined by the dashboard server in use.
This does not cause results to be appended to a .xml file
produced by a previous call to this command.

OPTIONS <options>

Specify command-line arguments to pass to the configuration tool.

RETURN_VALUE <result-var>

Store in the <result-var> variable the return value of the native
configuration tool.

CAPTURE_CMAKE_ERROR <result-var>

New in version 3.7.

Store in the <result-var> variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.

QUIET

New in version 3.3.

Suppress any CTest-specific non-error messages that would have
otherwise been printed to the console.  Output from the underlying
configure command is not affected.

Previous topic

ctest_build

Next topic

ctest_coverage

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

ctest_configure

        © 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>ctest_coverage — 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_empty_binary_directory" href="ctest_empty_binary_directory.html" />
    <link rel="prev" title="ctest_configure" href="ctest_configure.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_coverage

ctest_coverage¶

Perform the CTest Coverage Step as a Dashboard Client.

ctest_coverage([BUILD <build-dir>] [APPEND]
               [LABELS <label>...]
               [RETURN_VALUE <result-var>]
               [CAPTURE_CMAKE_ERROR <result-var>]
               [QUIET]
               )

Collect coverage tool results and stores them in Coverage.xml
for submission with the ctest_submit() command.

The options are:

BUILD <build-dir>

Specify the top-level build directory.  If not given, the
CTEST_BINARY_DIRECTORY variable is used.

APPEND

Mark Coverage.xml for append to results previously submitted to a
dashboard server since the last ctest_start() call.
Append semantics are defined by the dashboard server in use.
This does not cause results to be appended to a .xml file
produced by a previous call to this command.

LABELS

Filter the coverage report to include only source files labeled
with at least one of the labels specified.

RETURN_VALUE <result-var>

Store in the <result-var> variable 0 if coverage tools
ran without error and non-zero otherwise.

CAPTURE_CMAKE_ERROR <result-var>

New in version 3.7.

Store in the <result-var> variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.

QUIET

New in version 3.3.

Suppress any CTest-specific non-error output that would have been
printed to the console otherwise.  The summary indicating how many
lines of code were covered is unaffected by this option.

Previous topic

ctest_configure

Next topic

ctest_empty_binary_directory

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

ctest_coverage

        © 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>ctest_empty_binary_directory — 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_memcheck" href="ctest_memcheck.html" />
    <link rel="prev" title="ctest_coverage" href="ctest_coverage.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_empty_binary_directory

ctest_empty_binary_directory¶

empties the binary directory

ctest_empty_binary_directory(<directory>)

Removes a binary directory.  This command will perform some checks
prior to deleting the directory in an attempt to avoid malicious or
accidental directory deletion.

Previous topic

ctest_coverage

Next topic

ctest_memcheck

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

ctest_empty_binary_directory

        © 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>ctest_memcheck — 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_read_custom_files" href="ctest_read_custom_files.html" />
    <link rel="prev" title="ctest_empty_binary_directory" href="ctest_empty_binary_directory.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_memcheck

ctest_memcheck¶

Perform the CTest MemCheck Step as a Dashboard Client.

ctest_memcheck([BUILD <build-dir>] [APPEND]
               [START <start-number>]
               [END <end-number>]
               [STRIDE <stride-number>]
               [EXCLUDE <exclude-regex>]
               [INCLUDE <include-regex>]
               [EXCLUDE_LABEL <label-exclude-regex>]
               [INCLUDE_LABEL <label-include-regex>]
               [EXCLUDE_FIXTURE <regex>]
               [EXCLUDE_FIXTURE_SETUP <regex>]
               [EXCLUDE_FIXTURE_CLEANUP <regex>]
               [PARALLEL_LEVEL <level>]
               [RESOURCE_SPEC_FILE <file>]
               [TEST_LOAD <threshold>]
               [SCHEDULE_RANDOM <ON|OFF>]
               [STOP_ON_FAILURE]
               [STOP_TIME <time-of-day>]
               [RETURN_VALUE <result-var>]
               [CAPTURE_CMAKE_ERROR <result-var>]
               [REPEAT <mode>:<n>]
               [OUTPUT_JUNIT <file>]
               [DEFECT_COUNT <defect-count-var>]
               [QUIET]
               )

Run tests with a dynamic analysis tool and store results in
MemCheck.xml for submission with the ctest_submit()
command.

Most options are the same as those for the ctest_test() command.

The options unique to this command are:

DEFECT_COUNT <defect-count-var>

New in version 3.8.

Store in the <defect-count-var> the number of defects found.

Previous topic

ctest_empty_binary_directory

Next topic

ctest_read_custom_files

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

ctest_memcheck

        © 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>ctest_read_custom_files — 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_run_script" href="ctest_run_script.html" />
    <link rel="prev" title="ctest_memcheck" href="ctest_memcheck.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_read_custom_files

ctest_read_custom_files¶

read CTestCustom files.

ctest_read_custom_files(<directory>...)

Read all the CTestCustom.ctest or CTestCustom.cmake files from the
given directory.

By default, invoking ctest(1) without a script will read custom
files from the binary directory.

Previous topic

ctest_memcheck

Next topic

ctest_run_script

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

ctest_read_custom_files

        © 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>ctest_run_script — 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_sleep" href="ctest_sleep.html" />
    <link rel="prev" title="ctest_read_custom_files" href="ctest_read_custom_files.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_run_script

ctest_run_script¶

runs a ctest -S script

ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
            script_file_name2 ... [RETURN_VALUE var])

Runs a script or scripts much like if it was run from ctest -S.
If no argument is provided then the current script is run using the current
settings of the variables.  If NEW_PROCESS is specified then each
script will be run in a separate process.If RETURN_VALUE is specified
the return value of the last script run will be put into var.

Previous topic

ctest_read_custom_files

Next topic

ctest_sleep

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

ctest_run_script

        © 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>ctest_sleep — 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_start" href="ctest_start.html" />
    <link rel="prev" title="ctest_run_script" href="ctest_run_script.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_sleep

ctest_sleep¶

sleeps for some amount of time

ctest_sleep(<seconds>)

Sleep for given number of seconds.

ctest_sleep(<time1> <duration> <time2>)

Sleep for t=(time1 + duration - time2) seconds if t > 0.

Previous topic

ctest_run_script

Next topic

ctest_start

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

ctest_sleep

        © 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>ctest_start — 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_submit" href="ctest_submit.html" />
    <link rel="prev" title="ctest_sleep" href="ctest_sleep.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_start

ctest_start¶

Starts the testing for a given model

ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])

ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])

Starts the testing for a given model.  The command should be called
after the binary directory is initialized.

The parameters are as follows:

<model>

Set the dashboard model. Must be one of Experimental, Continuous, or
Nightly. This parameter is required unless APPEND is specified.

<source>

Set the source directory. If not specified, the value of
CTEST_SOURCE_DIRECTORY is used instead.

<binary>

Set the binary directory. If not specified, the value of
CTEST_BINARY_DIRECTORY is used instead.

GROUP <group>

If GROUP is used, the submissions will go to the specified group on the
CDash server. If no GROUP is specified, the name of the model is used by
default.

Changed in version 3.16: This replaces the deprecated option TRACK. Despite the name
change its behavior is unchanged.

APPEND

If APPEND is used, the existing TAG is used rather than creating a new
one based on the current time stamp. If you use APPEND, you can omit the
<model> and GROUP <group> parameters, because they will be read from
the generated TAG file. For example:

ctest_start(Experimental GROUP GroupExperimental)

Later, in another ctest -S script:

ctest_start(APPEND)

When the second script runs ctest_start(APPEND), it will read the
Experimental model and GroupExperimental group from the TAG file
generated by the first ctest_start() command. Please note that if you
call ctest_start(APPEND) and specify a different model or group than
in the first ctest_start() command, a warning will be issued, and the
new model and group will be used.

QUIET

New in version 3.3.

If QUIET is used, CTest will suppress any non-error messages that it
otherwise would have printed to the console.

The parameters for ctest_start() can be issued in any order, with the
exception that <model>, <source>, and <binary> have to appear
in that order with respect to each other. The following are all valid and
equivalent:

ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)

ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)

ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)

However, for the sake of readability, it is recommended that you order your
parameters in the order listed at the top of this page.

If the CTEST_CHECKOUT_COMMAND variable (or the
CTEST_CVS_CHECKOUT variable) is set, its content is treated as
command-line.  The command is invoked with the current working directory set
to the parent of the source directory, even if the source directory already
exists.  This can be used to create the source tree from a version control
repository.

Previous topic

ctest_sleep

Next topic

ctest_submit

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

ctest_start

        © 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>ctest_submit — 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_test" href="ctest_test.html" />
    <link rel="prev" title="ctest_start" href="ctest_start.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_submit

ctest_submit¶

Perform the CTest Submit Step as a Dashboard Client.

ctest_submit([PARTS <part>...] [FILES <file>...]
             [SUBMIT_URL <url>]
             [BUILD_ID <result-var>]
             [HTTPHEADER <header>]
             [RETRY_COUNT <count>]
             [RETRY_DELAY <delay>]
             [RETURN_VALUE <result-var>]
             [CAPTURE_CMAKE_ERROR <result-var>]
             [QUIET]
             )

Submit results to a dashboard server.
By default all available parts are submitted.

The options are:

PARTS <part>...

Specify a subset of parts to submit.  Valid part names are:

Start      = nothing
Update     = ctest_update results, in Update.xml
Configure  = ctest_configure results, in Configure.xml
Build      = ctest_build results, in Build.xml
Test       = ctest_test results, in Test.xml
Coverage   = ctest_coverage results, in Coverage.xml
MemCheck   = ctest_memcheck results, in DynamicAnalysis.xml and
             DynamicAnalysis-Test.xml
Notes      = Files listed by CTEST_NOTES_FILES, in Notes.xml
ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
Upload     = Files prepared for upload by ctest_upload(), in Upload.xml
Submit     = nothing
Done       = Build is complete, in Done.xml

FILES <file>...

Specify an explicit list of specific files to be submitted.
Each individual file must exist at the time of the call.

SUBMIT_URL <url>

New in version 3.14.

The http or https URL of the dashboard server to send the submission
to.  If not given, the CTEST_SUBMIT_URL variable is used.

BUILD_ID <result-var>

New in version 3.15.

Store in the <result-var> variable the ID assigned to this build by
CDash.

HTTPHEADER <HTTP-header>

New in version 3.9.

Specify HTTP header to be included in the request to CDash during submission.
For example, CDash can be configured to only accept submissions from
authenticated clients. In this case, you should provide a bearer token in your
header:

ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")

This suboption can be repeated several times for multiple headers.

RETRY_COUNT <count>

Specify how many times to retry a timed-out submission.

RETRY_DELAY <delay>

Specify how long (in seconds) to wait after a timed-out submission
before attempting to re-submit.

RETURN_VALUE <result-var>

Store in the <result-var> variable 0 for success and
non-zero on failure.

CAPTURE_CMAKE_ERROR <result-var>

New in version 3.13.

Store in the <result-var> variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.

QUIET

New in version 3.3.

Suppress all non-error messages that would have otherwise been
printed to the console.

Submit to CDash Upload API¶

New in version 3.2.

ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
             [SUBMIT_URL <url>]
             [BUILD_ID <result-var>]
             [HTTPHEADER <header>]
             [RETRY_COUNT <count>]
             [RETRY_DELAY <delay>]
             [RETURN_VALUE <result-var>]
             [QUIET])

This second signature is used to upload files to CDash via the CDash
file upload API. The API first sends a request to upload to CDash along
with a content hash of the file. If CDash does not already have the file,
then it is uploaded. Along with the file, a CDash type string is specified
to tell CDash which handler to use to process the data.

This signature interprets options in the same way as the first one.

New in version 3.8: Added the RETRY_COUNT, RETRY_DELAY, QUIET options.

New in version 3.9: Added the HTTPHEADER option.

New in version 3.13: Added the RETURN_VALUE option.

New in version 3.14: Added the SUBMIT_URL option.

New in version 3.15: Added the BUILD_ID option.

Table of Contents

ctest_submit

Submit to CDash Upload API

Previous topic

ctest_start

Next topic

ctest_test

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

ctest_submit

        © 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>ctest_test — 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_update" href="ctest_update.html" />
    <link rel="prev" title="ctest_submit" href="ctest_submit.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_test

ctest_test¶

Perform the CTest Test Step as a Dashboard Client.

ctest_test([BUILD <build-dir>] [APPEND]
           [START <start-number>]
           [END <end-number>]
           [STRIDE <stride-number>]
           [EXCLUDE <exclude-regex>]
           [INCLUDE <include-regex>]
           [EXCLUDE_LABEL <label-exclude-regex>]
           [INCLUDE_LABEL <label-include-regex>]
           [EXCLUDE_FROM_FILE <filename>]
           [INCLUDE_FROM_FILE <filename>]
           [EXCLUDE_FIXTURE <regex>]
           [EXCLUDE_FIXTURE_SETUP <regex>]
           [EXCLUDE_FIXTURE_CLEANUP <regex>]
           [PARALLEL_LEVEL <level>]
           [RESOURCE_SPEC_FILE <file>]
           [TEST_LOAD <threshold>]
           [SCHEDULE_RANDOM <ON|OFF>]
           [STOP_ON_FAILURE]
           [STOP_TIME <time-of-day>]
           [RETURN_VALUE <result-var>]
           [CAPTURE_CMAKE_ERROR <result-var>]
           [REPEAT <mode>:<n>]
           [OUTPUT_JUNIT <file>]
           [QUIET]
           )

Run tests in the project build tree and store results in
Test.xml for submission with the ctest_submit() command.

The options are:

BUILD <build-dir>

Specify the top-level build directory.  If not given, the
CTEST_BINARY_DIRECTORY variable is used.

APPEND

Mark Test.xml for append to results previously submitted to a
dashboard server since the last ctest_start() call.
Append semantics are defined by the dashboard server in use.
This does not cause results to be appended to a .xml file
produced by a previous call to this command.

START <start-number>

Specify the beginning of a range of test numbers.

END <end-number>

Specify the end of a range of test numbers.

STRIDE <stride-number>

Specify the stride by which to step across a range of test numbers.

EXCLUDE <exclude-regex>

Specify a regular expression matching test names to exclude.

INCLUDE <include-regex>

Specify a regular expression matching test names to include.
Tests not matching this expression are excluded.

EXCLUDE_LABEL <label-exclude-regex>

Specify a regular expression matching test labels to exclude.

INCLUDE_LABEL <label-include-regex>

Specify a regular expression matching test labels to include.
Tests not matching this expression are excluded.

EXCLUDE_FROM_FILE <filename>

New in version 3.29.

Do NOT run tests listed with their exact name in the given file.

INCLUDE_FROM_FILE <filename>

New in version 3.29.

Only run the tests listed with their exact name in the given file.

EXCLUDE_FIXTURE <regex>

New in version 3.7.

If a test in the set of tests to be executed requires a particular fixture,
that fixture's setup and cleanup tests would normally be added to the test
set automatically. This option prevents adding setup or cleanup tests for
fixtures matching the <regex>. Note that all other fixture behavior is
retained, including test dependencies and skipping tests that have fixture
setup tests that fail.

EXCLUDE_FIXTURE_SETUP <regex>

New in version 3.7.

Same as EXCLUDE_FIXTURE except only matching setup tests are excluded.

EXCLUDE_FIXTURE_CLEANUP <regex>

New in version 3.7.

Same as EXCLUDE_FIXTURE except only matching cleanup tests are excluded.

PARALLEL_LEVEL <level>

Specify a positive number representing the number of tests to
be run in parallel.

RESOURCE_SPEC_FILE <file>

New in version 3.16.

Specify a
resource specification file. See
Resource Allocation for more information.

TEST_LOAD <threshold>

New in version 3.4.

While running tests in parallel, try not to start tests when they
may cause the CPU load to pass above a given threshold.  If not
specified the CTEST_TEST_LOAD variable will be checked,
and then the --test-load command-line
argument to ctest(1). See also the TestLoad setting
in the CTest Test Step.

REPEAT <mode>:<n>

New in version 3.17.

Run tests repeatedly based on the given <mode> up to <n> times.
The modes are:

UNTIL_FAIL

Require each test to run <n> times without failing in order to pass.
This is useful in finding sporadic failures in test cases.

UNTIL_PASS

Allow each test to run up to <n> times in order to pass.
Repeats tests if they fail for any reason.
This is useful in tolerating sporadic failures in test cases.

AFTER_TIMEOUT

Allow each test to run up to <n> times in order to pass.
Repeats tests only if they timeout.
This is useful in tolerating sporadic timeouts in test cases
on busy machines.

SCHEDULE_RANDOM <ON|OFF>

Launch tests in a random order.  This may be useful for detecting
implicit test dependencies.

STOP_ON_FAILURE

New in version 3.18.

Stop the execution of the tests once one has failed.

STOP_TIME <time-of-day>

Specify a time of day at which the tests should all stop running.

RETURN_VALUE <result-var>

Store in the <result-var> variable 0 if all tests passed.
Store non-zero if anything went wrong.

CAPTURE_CMAKE_ERROR <result-var>

New in version 3.7.

Store in the <result-var> variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.

OUTPUT_JUNIT <file>

New in version 3.21.

Write test results to <file> in JUnit XML format. If <file> is a
relative path, it will be placed in the build directory. If <file>
already exists, it will be overwritten. Note that the resulting JUnit XML
file is not uploaded to CDash because it would be redundant with
CTest's Test.xml file.

QUIET

New in version 3.3.

Suppress any CTest-specific non-error messages that would have otherwise
been printed to the console.  Output from the underlying test command is not
affected.  Summary info detailing the percentage of passing tests is also
unaffected by the QUIET option.

See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE,
CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE and
CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION variables, along with their
corresponding ctest(1) command line options
--test-output-size-passed,
--test-output-size-failed, and
--test-output-truncation.

Additional Test Measurements¶

CTest can parse the output of your tests for extra measurements to report
to CDash.

When run as a Dashboard Client, CTest will include these custom
measurements in the Test.xml file that gets uploaded to CDash.

Check the CDash test measurement documentation
for more information on the types of test measurements that CDash recognizes.

The following example demonstrates how to output a variety of custom test
measurements.

std::cout <<
  "<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>"
  << std::endl;

std::cout <<
  "<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>"
  << std::endl;

std::cout <<
  "<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</CTestMeasurement>"
  << std::endl;

std::cout <<
  "<CTestMeasurement type=\"text/preformatted\" name=\"Console Output\">" <<
  "line 1.\n" <<
  "  \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" <<
  "line 3. Not bold or indented...\n" <<
  "</CTestMeasurement>" << std::endl;

Image Measurements¶

The following example demonstrates how to upload test images to CDash.

std::cout <<
  "<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" <<
  "/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl;

std::cout <<
  "<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" <<
  "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl;

std::cout <<
  "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\">" <<
  "/dir/to/img.png</CTestMeasurementFile>"
  << std::endl;

Images will be displayed together in an interactive comparison mode on CDash
if they are provided with two or more of the following names.

TestImage

ValidImage

BaselineImage

DifferenceImage2

By convention, TestImage is the image generated by your test, and
ValidImage (or BaselineImage) is basis of comparison used to determine
if the test passed or failed.

If another image name is used it will be displayed by CDash as a static image
separate from the interactive comparison UI.

Attached Files¶

New in version 3.21.

The following example demonstrates how to upload non-image files to CDash.

std::cout <<
  "<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" <<
  "/dir/to/data1.csv</CTestMeasurementFile>\n"                   <<
  "<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" <<
  "/dir/to/data2.csv</CTestMeasurementFile>"                     << std::endl;

If the name of the file to upload is known at configure time, you can use the
ATTACHED_FILES or ATTACHED_FILES_ON_FAIL test
properties instead.

Custom Details¶

New in version 3.21.

The following example demonstrates how to specify a custom value for the
Test Details field displayed on CDash.

std::cout <<
  "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl;

Additional Labels¶

New in version 3.22.

The following example demonstrates how to add additional labels to a test
at runtime.

std::cout <<
  "<CTestLabel>Custom Label 1</CTestLabel>\n" <<
  "<CTestLabel>Custom Label 2</CTestLabel>"   << std::endl;

Use the LABELS test property instead for labels that can be
determined at configure time.

Table of Contents

ctest_test

Additional Test Measurements

Image Measurements

Attached Files

Custom Details

Additional Labels

Previous topic

ctest_submit

Next topic

ctest_update

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

ctest_test

        © 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>ctest_update — 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_upload" href="ctest_upload.html" />
    <link rel="prev" title="ctest_test" href="ctest_test.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_update

ctest_update¶

Perform the CTest Update Step as a Dashboard Client.

ctest_update([SOURCE <source-dir>]
             [RETURN_VALUE <result-var>]
             [CAPTURE_CMAKE_ERROR <result-var>]
             [QUIET])

Update the source tree from version control and record results in
Update.xml for submission with the ctest_submit() command.

The options are:

SOURCE <source-dir>

Specify the source directory.  If not given, the
CTEST_SOURCE_DIRECTORY variable is used.

RETURN_VALUE <result-var>

Store in the <result-var> variable the number of files
updated or -1 on error.

CAPTURE_CMAKE_ERROR <result-var>

New in version 3.13.

Store in the <result-var> variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.

QUIET

New in version 3.3.

Tell CTest to suppress most non-error messages that it would
have otherwise printed to the console.  CTest will still report
the new revision of the repository and any conflicting files
that were found.

The update always follows the version control branch currently checked
out in the source directory.  See the CTest Update Step
documentation for information about variables that change the behavior
of ctest_update().

Previous topic

ctest_test

Next topic

ctest_upload

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

ctest_update

        © 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>ctest_upload — 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="build_name" href="build_name.html" />
    <link rel="prev" title="ctest_update" href="ctest_update.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

ctest_upload

ctest_upload¶

Upload files to a dashboard server as a Dashboard Client.

ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])

The options are:

FILES <file>...

Specify a list of files to be sent along with the build results to the
dashboard server.

QUIET

New in version 3.3.

Suppress any CTest-specific non-error output that would have been
printed to the console otherwise.

CAPTURE_CMAKE_ERROR <result-var>

New in version 3.7.

Store in the <result-var> variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.

Previous topic

ctest_update

Next topic

build_name

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

ctest_upload

        © 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>define_property — 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="enable_language" href="enable_language.html" />
    <link rel="prev" title="create_test_sourcelist" href="create_test_sourcelist.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

define_property

define_property¶

Define and document custom properties.

define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
                 TEST | VARIABLE | CACHED_VARIABLE>
                 PROPERTY <name> [INHERITED]
                 [BRIEF_DOCS <brief-doc> [docs...]]
                 [FULL_DOCS <full-doc> [docs...]]
                 [INITIALIZE_FROM_VARIABLE <variable>])

Defines one property in a scope for use with the set_property() and
get_property() commands. It is mainly useful for defining the way
a property is initialized or inherited. Historically, the command also
associated documentation with a property, but that is no longer considered a
primary use case.

The first argument determines the kind of scope in which the property should
be used.  It must be one of the following:

GLOBAL    = associated with the global namespace
DIRECTORY = associated with one directory
TARGET    = associated with one target
SOURCE    = associated with one source file
TEST      = associated with a test named with add_test
VARIABLE  = documents a CMake language variable
CACHED_VARIABLE = documents a CMake cache variable

Note that unlike set_property() and get_property() no
actual scope needs to be given; only the kind of scope is important.

The required PROPERTY option is immediately followed by the name of
the property being defined.

If the INHERITED option is given, then the get_property() command
will chain up to the next higher scope when the requested property is not set
in the scope given to the command.

DIRECTORY scope chains to its parent directory's scope, continuing the
walk up parent directories until a directory has the property set or there
are no more parents.  If still not found at the top level directory, it
chains to the GLOBAL scope.

TARGET, SOURCE and TEST properties chain to DIRECTORY scope,
including further chaining up the directories, etc. as needed.

Note that this scope chaining behavior only applies to calls to
get_property(), get_directory_property(),
get_target_property(), get_source_file_property() and
get_test_property().  There is no inheriting behavior when setting
properties, so using APPEND or APPEND_STRING with the
set_property() command will not consider inherited values when working
out the contents to append to.

The BRIEF_DOCS and FULL_DOCS options are followed by strings to be
associated with the property as its brief and full documentation.
CMake does not use this documentation other than making it available to the
project via corresponding options to the get_property() command.

Changed in version 3.23: The BRIEF_DOCS and FULL_DOCS options are optional.

New in version 3.23: The INITIALIZE_FROM_VARIABLE option specifies a variable from which the
property should be initialized. It can only be used with target properties.
The <variable> name must end with the property name and must not begin
with CMAKE_ or _CMAKE_. The property name must contain at least one
underscore. It is recommended that the property name have a prefix specific
to the project.

Property Redefinition¶

Once a property is defined for a particular type of scope, it cannot be
redefined. Attempts to redefine an existing property by calling
define_property() with the same scope type and property name
will be silently ignored. Defining the same property name for two different
kinds of scope is valid.

get_property() can be used to determine whether a property is
already defined for a particular kind of scope, and if so, to examine its
definition. For example:

# Initial definition
define_property(TARGET PROPERTY MY_NEW_PROP
  BRIEF_DOCS "My new custom property"
)

# Later examination
get_property(my_new_prop_exists
  TARGET NONE
  PROPERTY MY_NEW_PROP
  DEFINED
)

if(my_new_prop_exists)
  get_property(my_new_prop_docs
    TARGET NONE
    PROPERTY MY_NEW_PROP
    BRIEF_DOCS
  )
  # ${my_new_prop_docs} is now set to "My new custom property"
endif()

See Also¶

get_property()

set_property()

Table of Contents

define_property

Property Redefinition

See Also

Previous topic

create_test_sourcelist

Next topic

enable_language

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

define_property

        © 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>else — 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="elseif" href="elseif.html" />
    <link rel="prev" title="continue" href="continue.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

else

else¶

Starts the else portion of an if block.

else([<condition>])

See the if() command.

Previous topic

continue

Next topic

elseif

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

else

        © 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>elseif — 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="endblock" href="endblock.html" />
    <link rel="prev" title="else" href="else.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

elseif

elseif¶

Starts an elseif portion of an if block.

elseif(<condition>)

See the if() command, especially for the syntax and logic
of the <condition>.

Previous topic

else

Next topic

endblock

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

elseif

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