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>add_definitions — CMake 3.29.0-rc3 Documentation</title>

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

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

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

add_definitions

add_definitions¶

Add -D define flags to the compilation of source files.

add_definitions(-DFOO -DBAR ...)

Adds definitions to the compiler command line for targets in the current
directory, whether added before or after this command is invoked, and for
the ones in sub-directories added after. This command can be used to add any
flags, but it is intended to add preprocessor definitions.

Note

This command has been superseded by alternatives:

Use add_compile_definitions() to add preprocessor definitions.

Use include_directories() to add include directories.

Use add_compile_options() to add other options.

Flags beginning in -D or /D that look like preprocessor definitions are
automatically added to the COMPILE_DEFINITIONS directory
property for the current directory.  Definitions with non-trivial values
may be left in the set of flags instead of being converted for reasons of
backwards compatibility.  See documentation of the
directory,
target,
source file COMPILE_DEFINITIONS
properties for details on adding preprocessor definitions to specific
scopes and configurations.

See Also¶

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

Table of Contents

add_definitions

See Also

Previous topic

add_custom_target

Next topic

add_dependencies

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

add_definitions

        © 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>add_dependencies — CMake 3.29.0-rc3 Documentation</title>

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

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

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

add_dependencies

add_dependencies¶

Add a dependency between top-level targets.

add_dependencies(<target> [<target-dependency>]...)

Makes a top-level <target> depend on other top-level targets to
ensure that they build before <target> does.  A top-level target
is one created by one of the add_executable(),
add_library(), or add_custom_target() commands
(but not targets generated by CMake like install).

Dependencies added to an imported target
or an interface library are followed
transitively in its place since the target itself does not build.

New in version 3.3: Allow adding dependencies to interface libraries.

See Also¶

The DEPENDS option of add_custom_target() and
add_custom_command() commands for adding file-level
dependencies in custom rules.

The OBJECT_DEPENDS source file property to add
file-level dependencies to object files.

Table of Contents

add_dependencies

See Also

Previous topic

add_definitions

Next topic

add_executable

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

add_dependencies

        © 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>add_executable — CMake 3.29.0-rc3 Documentation</title>

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

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

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

add_executable

add_executable¶

Contents

add_executable

Normal Executables

Imported Executables

Alias Executables

See Also

Add an executable to the project using the specified source files.

Normal Executables¶

add_executable(<name> <options>... <sources>...)¶

Add an executable target called <name> to be built from the source
files listed in the command invocation.

The options are:

WIN32

Set the WIN32_EXECUTABLE target property automatically.
See documentation of that target property for details.

MACOSX_BUNDLE

Set the MACOSX_BUNDLE target property automatically.
See documentation of that target property for details.

EXCLUDE_FROM_ALL

Set the EXCLUDE_FROM_ALL target property automatically.
See documentation of that target property for details.

The <name> corresponds to the logical target name and must be globally
unique within a project.  The actual file name of the executable built is
constructed based on conventions of the native platform (such as
<name>.exe or just <name>).

New in version 3.1: Source arguments to add_executable may use "generator expressions" with
the syntax $<...>.  See the cmake-generator-expressions(7)
manual for available expressions.

New in version 3.11: The source files can be omitted if they are added later using
target_sources().

By default the executable file will be created in the build tree
directory corresponding to the source tree directory in which the
command was invoked.  See documentation of the
RUNTIME_OUTPUT_DIRECTORY target property to change this
location.  See documentation of the OUTPUT_NAME target property
to change the <name> part of the final file name.

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

See also HEADER_FILE_ONLY on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.

Imported Executables¶

add_executable(<name> IMPORTED [GLOBAL])¶

Add an IMPORTED executable target to reference
an executable file located outside the project.  The target name may be
referenced like any target built within the project, except that by
default it is visible only in the directory in which it is created,
and below.

The options are:

GLOBAL

Make the target name globally visible.

No rules are generated to build imported targets, and the IMPORTED
target property is True.  Imported executables are useful for convenient
reference from commands like add_custom_command().

Details about the imported executable are specified by setting properties
whose names begin in IMPORTED_.  The most important such property is
IMPORTED_LOCATION (and its per-configuration version
IMPORTED_LOCATION_<CONFIG>) which specifies the location of
the main executable file on disk.  See documentation of the IMPORTED_*
properties for more information.

Alias Executables¶

add_executable(<name> ALIAS <target>)¶

Creates an Alias Target, such that <name> can
be used to refer to <target> in subsequent commands.  The <name>
does not appear in the generated buildsystem as a make target.  The
<target> may not be an ALIAS.

New in version 3.11: An ALIAS can target a GLOBAL Imported Target

New in version 3.18: An ALIAS can target a non-GLOBAL Imported Target. Such alias is
scoped to the directory in which it is created and subdirectories.
The ALIAS_GLOBAL target property can be used to check if the
alias is global or not.

ALIAS targets can be used as targets to read properties
from, executables for custom commands and custom targets.  They can also be
tested for existence with the regular if(TARGET) subcommand.
The <name> may not be used to modify properties of <target>, that
is, it may not be used as the operand of set_property(),
set_target_properties(), target_link_libraries() etc.
An ALIAS target may not be installed or exported.

See Also¶

add_library()

Table of Contents

add_executable

Normal Executables

Imported Executables

Alias Executables

See Also

Previous topic

add_dependencies

Next topic

add_library

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

add_executable

        © 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>add_library — CMake 3.29.0-rc3 Documentation</title>

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

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

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

add_library

add_library¶

Contents

add_library

Normal Libraries

Object Libraries

Interface Libraries

Imported Libraries

Alias Libraries

See Also

Add a library to the project using the specified source files.

Normal Libraries¶

add_library(<name> [<type>] [EXCLUDE_FROM_ALL] <sources>...)¶

Add a library target called <name> to be built from the source files
listed in the command invocation.

The optional <type> specifies the type of library to be created:

STATIC

An archive of object files for use when linking other targets.

SHARED

A dynamic library that may be linked by other targets and loaded
at runtime.

MODULE

A plugin that may not be linked by other targets, but may be
dynamically loaded at runtime using dlopen-like functionality.

If no <type> is given the default is STATIC or SHARED
based on the value of the BUILD_SHARED_LIBS variable.

The options are:

EXCLUDE_FROM_ALL

Set the EXCLUDE_FROM_ALL target property automatically.
See documentation of that target property for details.

The <name> corresponds to the logical target name and must be globally
unique within a project.  The actual file name of the library built is
constructed based on conventions of the native platform (such as
lib<name>.a or <name>.lib).

New in version 3.1: Source arguments to add_library may use "generator expressions" with
the syntax $<...>.  See the cmake-generator-expressions(7)
manual for available expressions.

New in version 3.11: The source files can be omitted if they are added later using
target_sources().

For SHARED and MODULE libraries the
POSITION_INDEPENDENT_CODE target
property is set to ON automatically.
A SHARED library may be marked with the FRAMEWORK
target property to create an macOS Framework.

New in version 3.8: A STATIC library may be marked with the FRAMEWORK
target property to create a static Framework.

If a library does not export any symbols, it must not be declared as a
SHARED library.  For example, a Windows resource DLL or a managed C++/CLI
DLL that exports no unmanaged symbols would need to be a MODULE library.
This is because CMake expects a SHARED library to always have an
associated import library on Windows.

By default the library file will be created in the build tree directory
corresponding to the source tree directory in which the command was
invoked.  See documentation of the ARCHIVE_OUTPUT_DIRECTORY,
LIBRARY_OUTPUT_DIRECTORY, and
RUNTIME_OUTPUT_DIRECTORY target properties to change this
location.  See documentation of the OUTPUT_NAME target
property to change the <name> part of the final file name.

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

See also HEADER_FILE_ONLY on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.

Object Libraries¶

add_library(<name> OBJECT <sources>...)¶

Add an Object Library to compile source files
without archiving or linking their object files into a library.

Other targets created by add_library or add_executable()
may reference the objects using an expression of the
form $<TARGET_OBJECTS:objlib> as a source, where
objlib is the object library name.  For example:

add_library(... $<TARGET_OBJECTS:objlib> ...)
add_executable(... $<TARGET_OBJECTS:objlib> ...)

will include objlib's object files in a library and an executable
along with those compiled from their own sources.  Object libraries
may contain only sources that compile, header files, and other files
that would not affect linking of a normal library (e.g. .txt).
They may contain custom commands generating such sources, but not
PRE_BUILD, PRE_LINK, or POST_BUILD commands.  Some native build
systems (such as Xcode) may not like targets that have only object files, so
consider adding at least one real source file to any target that references
$<TARGET_OBJECTS:objlib>.

New in version 3.12: Object libraries can be linked to with target_link_libraries().

Interface Libraries¶

add_library(<name> INTERFACE)¶

Add an Interface Library target that may
specify usage requirements for dependents but does not compile sources
and does not produce a library artifact on disk.

An interface library with no source files is not included as a target
in the generated buildsystem.  However, it may have
properties set on it and it may be installed and exported.
Typically, INTERFACE_* properties are populated on an interface
target using the commands:

set_property(),

target_link_libraries(INTERFACE),

target_link_options(INTERFACE),

target_include_directories(INTERFACE),

target_compile_options(INTERFACE),

target_compile_definitions(INTERFACE), and

target_sources(INTERFACE),

and then it is used as an argument to target_link_libraries()
like any other target.

New in version 3.15: An interface library can have PUBLIC_HEADER and
PRIVATE_HEADER properties.  The headers specified by those
properties can be installed using the install(TARGETS) command.

add_library(<name> INTERFACE [EXCLUDE_FROM_ALL] <sources>...)¶

New in version 3.19.

Add an Interface Library target with
source files (in addition to usage requirements and properties as
documented by the above signature).
Source files may be listed directly in the add_library call
or added later by calls to target_sources() with the
PRIVATE or PUBLIC keywords.

If an interface library has source files (i.e. the SOURCES
target property is set), or header sets (i.e. the HEADER_SETS
target property is set), it will appear in the generated buildsystem
as a build target much like a target defined by the
add_custom_target() command.  It does not compile any sources,
but does contain build rules for custom commands created by the
add_custom_command() command.

The options are:

EXCLUDE_FROM_ALL

Set the EXCLUDE_FROM_ALL target property automatically.
See documentation of that target property for details.

Note

In most command signatures where the INTERFACE keyword appears,
the items listed after it only become part of that target's usage
requirements and are not part of the target's own settings.  However,
in this signature of add_library, the INTERFACE keyword refers
to the library type only.  Sources listed after it in the add_library
call are PRIVATE to the interface library and do not appear in its
INTERFACE_SOURCES target property.

Imported Libraries¶

add_library(<name> <type> IMPORTED [GLOBAL])¶

Add an IMPORTED library target called <name>.
The target name may be referenced like any target built within the project,
except that by default it is visible only in the directory in which it is
created, and below.

The <type> must be one of:

STATIC, SHARED, MODULE, UNKNOWN

References a library file located outside the project.  The
IMPORTED_LOCATION target property (or its per-configuration
variant IMPORTED_LOCATION_<CONFIG>) specifies the
location of the main library file on disk:

For a SHARED library on most non-Windows platforms, the main library
file is the .so or .dylib file used by both linkers and dynamic
loaders.  If the referenced library file has a SONAME (or on macOS,
has a LC_ID_DYLIB starting in @rpath/), the value of that field
should be set in the IMPORTED_SONAME target property.
If the referenced library file does not have a SONAME, but the
platform supports it, then  the IMPORTED_NO_SONAME target
property should be set.

For a SHARED library on Windows, the IMPORTED_IMPLIB
target property (or its per-configuration variant
IMPORTED_IMPLIB_<CONFIG>) specifies the location of the
DLL import library file (.lib or .dll.a) on disk, and the
IMPORTED_LOCATION is the location of the .dll runtime
library (and is optional, but needed by the TARGET_RUNTIME_DLLS
generator expression).

Additional usage requirements may be specified in INTERFACE_*
properties.

An UNKNOWN library type is typically only used in the implementation
of Find Modules.  It allows the path to an imported library
(often found using the find_library() command) to be used
without having to know what type of library it is.  This is especially
useful on Windows where a static library and a DLL's import library
both have the same file extension.

OBJECT

References a set of object files located outside the project.
The IMPORTED_OBJECTS target property (or its per-configuration
variant IMPORTED_OBJECTS_<CONFIG>) specifies the locations of
object files on disk.
Additional usage requirements may be specified in INTERFACE_*
properties.

INTERFACE

Does not reference any library or object files on disk, but may
specify usage requirements in INTERFACE_* properties.

The options are:

GLOBAL

Make the target name globally visible.

No rules are generated to build imported targets, and the IMPORTED
target property is True.  Imported libraries are useful for convenient
reference from commands like target_link_libraries().

Details about the imported library are specified by setting properties whose
names begin in IMPORTED_ and INTERFACE_.  See documentation of
such properties for more information.

Alias Libraries¶

add_library(<name> ALIAS <target>)¶

Creates an Alias Target, such that <name> can be
used to refer to <target> in subsequent commands.  The <name> does
not appear in the generated buildsystem as a make target.  The <target>
may not be an ALIAS.

New in version 3.11: An ALIAS can target a GLOBAL Imported Target

New in version 3.18: An ALIAS can target a non-GLOBAL Imported Target. Such alias is
scoped to the directory in which it is created and below.
The ALIAS_GLOBAL target property can be used to check if the
alias is global or not.

ALIAS targets can be used as linkable targets and as targets to
read properties from.  They can also be tested for existence with the
regular if(TARGET) subcommand.  The <name> may not be used
to modify properties of <target>, that is, it may not be used as the
operand of set_property(), set_target_properties(),
target_link_libraries() etc.  An ALIAS target may not be
installed or exported.

See Also¶

add_executable()

Table of Contents

add_library

Normal Libraries

Object Libraries

Interface Libraries

Imported Libraries

Alias Libraries

See Also

Previous topic

add_executable

Next topic

add_link_options

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

add_library

        © 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>add_link_options — CMake 3.29.0-rc3 Documentation</title>

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

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

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

add_link_options

add_link_options¶

New in version 3.13.

Add options to the link step for executable, shared library or module
library targets in the current directory and below that are added after
this command is invoked.

add_link_options(<option> ...)

This command can be used to add any link options, but alternative commands
exist to add libraries (target_link_libraries() or
link_libraries()).  See documentation of the
directory and
target LINK_OPTIONS properties.

Note

This command cannot be used to add options for static library targets,
since they do not use a linker.  To add archiver or MSVC librarian flags,
see the STATIC_LIBRARY_OPTIONS target property.

Arguments to add_link_options may use generator expressions
with the syntax $<...>. See the cmake-generator-expressions(7)
manual for available expressions.  See the cmake-buildsystem(7) manual
for more on defining buildsystem properties.

Host And Device Specific Link Options¶

New in version 3.18: When a device link step is involved, which is controlled by
CUDA_SEPARABLE_COMPILATION and
CUDA_RESOLVE_DEVICE_SYMBOLS properties and policy CMP0105,
the raw options will be delivered to the host and device link steps (wrapped in
-Xcompiler or equivalent for device link). Options wrapped with
$<DEVICE_LINK:...> generator expression will be used
only for the device link step. Options wrapped with $<HOST_LINK:...>
generator expression will be used only for the host link step.

Option De-duplication¶

The final set of options used for a target is constructed by
accumulating options from the current target and the usage requirements of
its dependencies.  The set of options is de-duplicated to avoid repetition.

New in version 3.12: While beneficial for individual options, the de-duplication step can break
up option groups.  For example, -option A -option B becomes
-option A B.  One may specify a group of options using shell-like
quoting along with a SHELL: prefix.  The SHELL: prefix is dropped,
and the rest of the option string is parsed using the
separate_arguments() UNIX_COMMAND mode. For example,
"SHELL:-option A" "SHELL:-option B" becomes -option A -option B.

Handling Compiler Driver Differences¶

To pass options to the linker tool, each compiler driver has its own syntax.
The LINKER: prefix and , separator can be used to specify, in a portable
way, options to pass to the linker tool. LINKER: is replaced by the
appropriate driver option and , by the appropriate driver separator.
The driver prefix and driver separator are given by the values of the
CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.

For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
Clang and -Wl,-z,defs for GNU GCC.

The LINKER: prefix can be specified as part of a SHELL: prefix
expression.

The LINKER: prefix supports, as an alternative syntax, specification of
arguments using the SHELL: prefix and space as separator. The previous
example then becomes "LINKER:SHELL:-z defs".

Note

Specifying the SHELL: prefix anywhere other than at the beginning of the
LINKER: prefix is not supported.

See Also¶

link_libraries()

target_link_libraries()

target_link_options()

CMAKE_<LANG>_FLAGS and CMAKE_<LANG>_FLAGS_<CONFIG>
add language-wide flags passed to all invocations of the compiler.
This includes invocations that drive compiling and those that drive linking.

Table of Contents

add_link_options

Host And Device Specific Link Options

Option De-duplication

Handling Compiler Driver Differences

See Also

Previous topic

add_library

Next topic

add_subdirectory

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

add_link_options

        © 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>add_subdirectory — CMake 3.29.0-rc3 Documentation</title>

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

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

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

add_subdirectory

add_subdirectory¶

Add a subdirectory to the build.

add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM])

Adds a subdirectory to the build.  The source_dir specifies the
directory in which the source CMakeLists.txt and code files are
located.  If it is a relative path, it will be evaluated with respect
to the current directory (the typical usage), but it may also be an
absolute path.  The binary_dir specifies the directory in which to
place the output files.  If it is a relative path, it will be evaluated
with respect to the current output directory, but it may also be an
absolute path.  If binary_dir is not specified, the value of
source_dir, before expanding any relative path, will be used (the
typical usage).  The CMakeLists.txt file in the specified source
directory will be processed immediately by CMake before processing in
the current input file continues beyond this command.

If the EXCLUDE_FROM_ALL argument is provided then targets in the
subdirectory will not be included in the ALL target of the parent
directory by default, and will be excluded from IDE project files.
Users must explicitly build targets in the subdirectory.  This is
meant for use when the subdirectory contains a separate part of the
project that is useful but not necessary, such as a set of examples.
Typically the subdirectory should contain its own project()
command invocation so that a full build system will be generated in the
subdirectory (such as a Visual Studio IDE solution file).  Note that
inter-target dependencies supersede this exclusion.  If a target built by
the parent project depends on a target in the subdirectory, the dependee
target will be included in the parent project build system to satisfy
the dependency.

New in version 3.25: If the SYSTEM argument is provided, the SYSTEM directory
property of the subdirectory will be set to true.  This property is
used to initialize the SYSTEM property of each non-imported
target created in that subdirectory.

Previous topic

add_link_options

Next topic

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

add_subdirectory

        © 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>add_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="aux_source_directory" href="aux_source_directory.html" />
    <link rel="prev" title="add_subdirectory" href="add_subdirectory.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

add_test

add_test¶

Add a test to the project to be run by ctest(1).

add_test(NAME <name> COMMAND <command> [<arg>...]
         [CONFIGURATIONS <config>...]
         [WORKING_DIRECTORY <dir>]
         [COMMAND_EXPAND_LISTS])

Adds a test called <name>.  The test name may contain arbitrary
characters, expressed as a Quoted Argument or Bracket Argument
if necessary.  See policy CMP0110.

CMake only generates tests if the enable_testing() command has been
invoked.  The CTest module invokes enable_testing automatically
unless BUILD_TESTING is set to OFF.

Tests added with the add_test(NAME) signature support using
generator expressions
in test properties set by set_property(TEST) or
set_tests_properties(). Test properties may only be set in the
directory the test is created in.

add_test options are:

COMMAND

Specify the test command-line.

If <command> specifies an executable target created by
add_executable():

It will automatically be replaced by the location of the executable
created at build time.

New in version 3.3: The target's CROSSCOMPILING_EMULATOR, if set, will be
used to run the command on the host:

<emulator> <command>

Changed in version 3.29: The emulator is used only when
cross-compiling.
See policy CMP0158.

New in version 3.29: The target's TEST_LAUNCHER, if set, will be
used to launch the command:

<launcher> <command>

If the CROSSCOMPILING_EMULATOR is also set, both are used:

<launcher> <emulator> <command>

The command may be specified using
generator expressions.

CONFIGURATIONS

Restrict execution of the test only to the named configurations.

WORKING_DIRECTORY

Set the test property WORKING_DIRECTORY in which to execute the
test. If not specified, the test will be run in
CMAKE_CURRENT_BINARY_DIR. The working directory may be specified
using generator expressions.

COMMAND_EXPAND_LISTS

New in version 3.16.

Lists in COMMAND arguments will be expanded, including those created with
generator expressions.

If the test command exits with code 0 the test passes. Non-zero exit code
is a "failed" test. The test property WILL_FAIL inverts this
logic. Note that system-level test failures such as segmentation faults or
heap errors will still fail the test even if WILL_FALL is true. Output
written to stdout or stderr is captured by ctest(1) and only
affects the pass/fail status via the PASS_REGULAR_EXPRESSION,
FAIL_REGULAR_EXPRESSION, or SKIP_REGULAR_EXPRESSION
test properties.

New in version 3.16: Added SKIP_REGULAR_EXPRESSION property.

Example usage:

add_test(NAME mytest
         COMMAND testDriver --config $<CONFIG>
                            --exe $<TARGET_FILE:myexe>)

This creates a test mytest whose command runs a testDriver tool
passing the configuration name and the full path to the executable
file produced by target myexe.

The command syntax above is recommended over the older, less flexible form:

add_test(<name> <command> [<arg>...])

Add a test called <name> with the given command-line.

Unlike the above NAME signature, target names are not supported
in the command-line.  Furthermore, tests added with this signature do not
support generator expressions
in the command-line or test properties.

Previous topic

add_subdirectory

Next topic

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

add_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>aux_source_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="build_command" href="build_command.html" />
    <link rel="prev" title="add_test" href="add_test.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

aux_source_directory

aux_source_directory¶

Find all source files in a directory.

aux_source_directory(<dir> <variable>)

Collects the names of all the source files in the specified directory
and stores the list in the <variable> provided.  This command is
intended to be used by projects that use explicit template
instantiation.  Template instantiation files can be stored in a
Templates subdirectory and collected automatically using this
command to avoid manually listing all instantiations.

It is tempting to use this command to avoid writing the list of source
files for a library or executable target.  While this seems to work,
there is no way for CMake to generate a build system that knows when a
new source file has been added.  Normally the generated build system
knows when it needs to rerun CMake because the CMakeLists.txt file is
modified to add a new source.  When the source is just added to the
directory without modifying this file, one would have to manually
rerun CMake to generate a build system incorporating the new file.

Previous topic

add_test

Next topic

build_command

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

aux_source_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>block — 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="break" href="break.html" />
    <link rel="prev" title="cmake-commands(7)" href="../manual/cmake-commands.7.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

block

block¶

New in version 3.25.

Evaluate a group of commands with a dedicated variable and/or policy scope.

block([SCOPE_FOR [POLICIES] [VARIABLES] ] [PROPAGATE <var-name>...])
  <commands>
endblock()

All commands between block() and the matching endblock() are
recorded without being invoked.  Once the endblock() is evaluated, the
recorded list of commands is invoked inside the requested scopes, then the
scopes created by the block() command are removed.

SCOPE_FOR

Specify which scopes must be created.

POLICIES

Create a new policy scope. This is equivalent to
cmake_policy(PUSH) with an automatic
cmake_policy(POP) when leaving the block scope.

VARIABLES

Create a new variable scope.

If SCOPE_FOR is not specified, this is equivalent to:

block(SCOPE_FOR VARIABLES POLICIES)

PROPAGATE

When a variable scope is created by the block() command, this
option sets or unsets the specified variables in the parent scope. This is
equivalent to set(PARENT_SCOPE) or unset(PARENT_SCOPE)
commands.

set(var1 "INIT1")
set(var2 "INIT2")

block(PROPAGATE var1 var2)
  set(var1 "VALUE1")
  unset(var2)
endblock()

# Now var1 holds VALUE1, and var2 is unset

This option is only allowed when a variable scope is created. An error will
be raised in the other cases.

When the block() is inside a foreach() or while()
command, the break() and continue() commands can be used
inside the block.

while(TRUE)
  block()
     ...
     # the break() command will terminate the while() command
     break()
  endblock()
endwhile()

See Also¶

endblock()

return()

cmake_policy()

Table of Contents

block

See Also

Previous topic

cmake-commands(7)

Next topic

break

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

block

        © 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>break — 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_host_system_information" href="cmake_host_system_information.html" />
    <link rel="prev" title="block" href="block.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

break

break¶

Break from an enclosing foreach or while loop.

break()

Breaks from an enclosing foreach() or while() loop.

See also the continue() command.

Previous topic

block

Next topic

cmake_host_system_information

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

break

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

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

build_command

build_command¶

Get a command line to build the current project.
This is mainly intended for internal use by the CTest module.

build_command(<variable>
              [CONFIGURATION <config>]
              [PARALLEL_LEVEL <parallel>]
              [TARGET <target>]
              [PROJECT_NAME <projname>] # legacy, causes warning
             )

Sets the given <variable> to a command-line string of the form:

<cmake> --build . [--config <config>] [--parallel <parallel>] [--target <target>...] [-- -i]

where <cmake> is the location of the cmake(1) command-line
tool, and <config>, <parallel> and <target> are the values
provided to the CONFIGURATION, PARALLEL_LEVEL and TARGET
options, if any.  The trailing -- -i option is added for
Makefile Generators if policy CMP0061 is not set to
NEW.

When invoked, this cmake --build command line will launch the
underlying build system tool.

New in version 3.21: The PARALLEL_LEVEL argument can be used to set the
--parallel flag.

build_command(<cachevariable> <makecommand>)

This second signature is deprecated, but still available for backwards
compatibility.  Use the first signature instead.

It sets the given <cachevariable> to a command-line string as
above but without the --target option.
The <makecommand> is ignored but should be the full path to
devenv, nmake, make or one of the end user build tools
for legacy invocations.

Note

In CMake versions prior to 3.0 this command returned a command
line that directly invokes the native build tool for the current
generator.  Their implementation of the PROJECT_NAME option
had no useful effects, so CMake now warns on use of the option.

Previous topic

aux_source_directory

Next topic

cmake_file_api

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

build_command

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

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

build_name

build_name¶

Disallowed since version 3.0.  See CMake Policy CMP0036.

Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.

build_name(variable)

Sets the specified variable to a string representing the platform and
compiler settings.  These values are now available through the
CMAKE_SYSTEM and
CMAKE_CXX_COMPILER variables.

Previous topic

ctest_upload

Next topic

exec_program

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

build_name

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

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

cmake_file_api

cmake_file_api¶

New in version 3.27.

Enables interacting with the CMake file API.

cmake_file_api(QUERY ...)¶

The QUERY subcommand adds a file API query for the current CMake
invocation.

cmake_file_api(
  QUERY
  API_VERSION <version>
  [CODEMODEL <versions>...]
  [CACHE <versions>...]
  [CMAKEFILES <versions>...]
  [TOOLCHAINS <versions>...]
)

The API_VERSION must always be given.  Currently, the only supported
value for <version> is 1.  See API v1 for details of the
reply content and location.

Each of the optional keywords CODEMODEL, CACHE, CMAKEFILES and
TOOLCHAINS correspond to one of the object kinds that can be requested
by the project.  The configureLog object kind cannot be set with this
command, since it must be set before CMake starts reading the top level
CMakeLists.txt file.

For each of the optional keywords, the <versions> list must contain one
or more version values of the form major or major.minor, where
major and minor are integers.  Projects should list the versions they
accept in their preferred order, as only the first supported value from the
list will be selected.  The command will ignore versions with a major
version higher than any major version it supports for that object kind.
It will raise an error if it encounters an invalid version number, or if none
of the requested versions is supported.

For each type of object kind requested, a query equivalent to a shared,
stateless query will be added internally.  No query file will be created in
the file system.  The reply will be written to the file system at
generation time.

It is not an error to add a query for the same thing more than once, whether
from query files or from multiple calls to cmake_file_api(QUERY).
The final set of queries will be a merged combination of all queries
specified on disk and queries submitted by the project.

Example¶

A project may want to use replies from the file API at build time to implement
some form of verification task.  Instead of relying on something outside of
CMake to create a query file, the project can use cmake_file_api(QUERY)
to request the required information for the current run.  It can then create
a custom command to run at build time, knowing that the requested information
should always be available.

cmake_file_api(
  QUERY
  API_VERSION 1
  CODEMODEL 2.3
  TOOLCHAINS 1
)

add_custom_target(verify_project
  COMMAND ${CMAKE_COMMAND}
    -D BUILD_DIR=${CMAKE_BINARY_DIR}
    -D CONFIG=$<CONFIG>
    -P ${CMAKE_CURRENT_SOURCE_DIR}/verify_project.cmake
)

Table of Contents

cmake_file_api

Example

Previous topic

build_command

Next topic

create_test_sourcelist

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_file_api

        © 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_host_system_information — 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_language" href="cmake_language.html" />
    <link rel="prev" title="break" href="break.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

cmake_host_system_information

cmake_host_system_information¶

Query various host system information.

Synopsis¶

Query host system specific information
  cmake_host_system_information(RESULT <variable> QUERY <key> ...)

Query Windows registry
  cmake_host_system_information(RESULT <variable> QUERY WINDOWS_REGISTRY <key> ...)

Query host system specific information¶

cmake_host_system_information(RESULT <variable> QUERY <key> ...)

Queries system information of the host system on which cmake runs.
One or more <key> can be provided to select the information to be
queried.  The list of queried values is stored in <variable>.

<key> can be one of the following values:

NUMBER_OF_LOGICAL_CORES

Number of logical cores

NUMBER_OF_PHYSICAL_CORES

Number of physical cores

HOSTNAME

Hostname

FQDN

Fully qualified domain name

TOTAL_VIRTUAL_MEMORY

Total virtual memory in MiB [1]

AVAILABLE_VIRTUAL_MEMORY

Available virtual memory in MiB [1]

TOTAL_PHYSICAL_MEMORY

Total physical memory in MiB [1]

AVAILABLE_PHYSICAL_MEMORY

Available physical memory in MiB [1]

IS_64BIT

New in version 3.10.

One if processor is 64Bit

HAS_FPU

New in version 3.10.

One if processor has floating point unit

HAS_MMX

New in version 3.10.

One if processor supports MMX instructions

HAS_MMX_PLUS

New in version 3.10.

One if processor supports Ext. MMX instructions

HAS_SSE

New in version 3.10.

One if processor supports SSE instructions

HAS_SSE2

New in version 3.10.

One if processor supports SSE2 instructions

HAS_SSE_FP

New in version 3.10.

One if processor supports SSE FP instructions

HAS_SSE_MMX

New in version 3.10.

One if processor supports SSE MMX instructions

HAS_AMD_3DNOW

New in version 3.10.

One if processor supports 3DNow instructions

HAS_AMD_3DNOW_PLUS

New in version 3.10.

One if processor supports 3DNow+ instructions

HAS_IA64

New in version 3.10.

One if IA64 processor emulating x86

HAS_SERIAL_NUMBER

New in version 3.10.

One if processor has serial number

PROCESSOR_SERIAL_NUMBER

New in version 3.10.

Processor serial number

PROCESSOR_NAME

New in version 3.10.

Human readable processor name

PROCESSOR_DESCRIPTION

New in version 3.10.

Human readable full processor description

OS_NAME

New in version 3.10.

See CMAKE_HOST_SYSTEM_NAME

OS_RELEASE

New in version 3.10.

The OS sub-type e.g. on Windows Professional

OS_VERSION

New in version 3.10.

The OS build ID

OS_PLATFORM

New in version 3.10.

See CMAKE_HOST_SYSTEM_PROCESSOR

MSYSTEM_PREFIX

New in version 3.28.

Available only on Windows hosts.  In a MSYS or MinGW development
environment that sets the MSYSTEM environment variable, this
is its installation prefix.  Otherwise, this is the empty string.

DISTRIB_INFO

New in version 3.22.

Read /etc/os-release file and define the given <variable>
into a list of read variables

DISTRIB_<name>

New in version 3.22.

Get the <name> variable (see man 5 os-release) if it exists in the
/etc/os-release file

Example:

cmake_host_system_information(RESULT PRETTY_NAME QUERY DISTRIB_PRETTY_NAME)
message(STATUS "${PRETTY_NAME}")

cmake_host_system_information(RESULT DISTRO QUERY DISTRIB_INFO)

foreach(VAR IN LISTS DISTRO)
  message(STATUS "${VAR}=`${${VAR}}`")
endforeach()

Output:

-- Ubuntu 20.04.2 LTS
-- DISTRO_BUG_REPORT_URL=`https://bugs.launchpad.net/ubuntu/`
-- DISTRO_HOME_URL=`https://www.ubuntu.com/`
-- DISTRO_ID=`ubuntu`
-- DISTRO_ID_LIKE=`debian`
-- DISTRO_NAME=`Ubuntu`
-- DISTRO_PRETTY_NAME=`Ubuntu 20.04.2 LTS`
-- DISTRO_PRIVACY_POLICY_URL=`https://www.ubuntu.com/legal/terms-and-policies/privacy-policy`
-- DISTRO_SUPPORT_URL=`https://help.ubuntu.com/`
-- DISTRO_UBUNTU_CODENAME=`focal`
-- DISTRO_VERSION=`20.04.2 LTS (Focal Fossa)`
-- DISTRO_VERSION_CODENAME=`focal`
-- DISTRO_VERSION_ID=`20.04`

If /etc/os-release file is not found, the command tries to gather OS
identification via fallback scripts.  The fallback script can use various
distribution-specific files to collect OS identification data and map it
into man 5 os-release variables.

Fallback Interface Variables¶

CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS¶

In addition to the scripts shipped with CMake, a user may append full
paths to his script(s) to the this list.  The script filename has the
following format: NNN-<name>.cmake, where NNN is three digits
used to apply collected scripts in a specific order.

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

Variables collected by the user provided fallback script
ought to be assigned to CMake variables using this naming
convention.  Example, the ID variable from the manual becomes
CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID.

CMAKE_GET_OS_RELEASE_FALLBACK_RESULT¶

The fallback script ought to store names of all assigned
CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname> variables in this list.

Example:

# Try to detect some old distribution
# See also
# - http://linuxmafia.com/faq/Admin/release-files.html
#
if(NOT EXISTS "${CMAKE_SYSROOT}/etc/foobar-release")
  return()
endif()
# Get the first string only
file(
    STRINGS "${CMAKE_SYSROOT}/etc/foobar-release" CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT
    LIMIT_COUNT 1
  )
#
# Example:
#
#   Foobar distribution release 1.2.3 (server)
#
if(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT MATCHES "Foobar distribution release ([0-9\.]+) .*")
  set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME Foobar)
  set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME "${CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT}")
  set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID foobar)
  set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION ${CMAKE_MATCH_1})
  set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID ${CMAKE_MATCH_1})
  list(
      APPEND CMAKE_GET_OS_RELEASE_FALLBACK_RESULT
      CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME
      CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME
      CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID
      CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION
      CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID
    )
endif()
unset(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT)

Footnotes

[1]
(1,2,3,4)

One MiB (mebibyte) is equal to 1024x1024 bytes.

Query Windows registry¶

New in version 3.24.

cmake_host_system_information(RESULT <variable>
                              QUERY WINDOWS_REGISTRY <key> [VALUE_NAMES|SUBKEYS|VALUE <name>]
                              [VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
                              [SEPARATOR <separator>]
                              [ERROR_VARIABLE <result>])

Performs query operations on local computer registry subkey. Returns a list of
subkeys or value names that are located under the specified subkey in the
registry or the data of the specified value name. The result of the queried
entity is stored in <variable>.

Note

Querying registry for any other platforms than Windows, including
CYGWIN, will always returns an empty string and sets an error message in
the variable specified with sub-option ERROR_VARIABLE.

<key> specify the full path of a subkey on the local computer. The
<key> must include a valid root key. Valid root keys for the local computer
are:

HKLM or HKEY_LOCAL_MACHINE

HKCU or HKEY_CURRENT_USER

HKCR or HKEY_CLASSES_ROOT

HKU or HKEY_USERS

HKCC or HKEY_CURRENT_CONFIG

And, optionally, the path to a subkey under the specified root key. The path
separator can be the slash or the backslash. <key> is not case sensitive.
For example:

cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM")
cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKCU\\SOFTWARE\\Kitware")

VALUE_NAMES

Request the list of value names defined under <key>. If a default value
is defined, it will be identified with the special name (default).

SUBKEYS

Request the list of subkeys defined under <key>.

VALUE <name>

Request the data stored in value named <name>. If VALUE is not
specified or argument is the special name (default), the content of the
default value, if any, will be returned.

# query default value for HKLM/SOFTWARE/Kitware key
cmake_host_system_information(RESULT result
                              QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")

# query default value for HKLM/SOFTWARE/Kitware key using special value name
cmake_host_system_information(RESULT result
                              QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware"
                              VALUE "(default)")

Supported types are:

REG_SZ.

REG_EXPAND_SZ. The returned data is expanded.

REG_MULTI_SZ. The returned is expressed as a CMake list. See also
SEPARATOR sub-option.

REG_DWORD.

REG_QWORD.

For all other types, an empty string is returned.

VIEW

Specify which registry views must be queried. When not specified, BOTH
view is used.

64

Query the 64bit registry. On 32bit Windows, returns always an empty
string.

32

Query the 32bit registry.

64_32

For VALUE sub-option or default value, query the registry using view
64, and if the request failed, query the registry using view 32.
For VALUE_NAMES and SUBKEYS sub-options, query both views (64
and 32) and merge the results (sorted and duplicates removed).

32_64

For VALUE sub-option or default value, query the registry using view
32, and if the request failed, query the registry using view 64.
For VALUE_NAMES and SUBKEYS sub-options, query both views (32
and 64) and merge the results (sorted and duplicates removed).

HOST

Query the registry matching the architecture of the host: 64 on 64bit
Windows and 32 on 32bit Windows.

TARGET

Query the registry matching the architecture specified by
CMAKE_SIZEOF_VOID_P variable. If not defined, fallback to
HOST view.

BOTH

Query both views (32 and 64). The order depends of the following
rules: If CMAKE_SIZEOF_VOID_P variable is defined. Use the
following view depending of the content of this variable:

8: 64_32

4: 32_64

If CMAKE_SIZEOF_VOID_P variable is not defined, rely on
architecture of the host:

64bit: 64_32

32bit: 32

SEPARATOR

Specify the separator character for REG_MULTI_SZ type. When not
specified, the character \0 is used.

ERROR_VARIABLE <result>

Returns any error raised during query operation. In case of success, the
variable holds an empty string.

Table of Contents

cmake_host_system_information

Synopsis

Query host system specific information

Fallback Interface Variables

Query Windows registry

Previous topic

break

Next topic

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

cmake_host_system_information

        © 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_language — 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_minimum_required" href="cmake_minimum_required.html" />
    <link rel="prev" title="cmake_host_system_information" href="cmake_host_system_information.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

cmake_language

cmake_language¶

New in version 3.18.

Call meta-operations on CMake commands.

Synopsis¶

cmake_language(CALL <command> [<arg>...])
cmake_language(EVAL CODE <code>...)
cmake_language(DEFER <options>... CALL <command> [<arg>...])
cmake_language(SET_DEPENDENCY_PROVIDER <command> SUPPORTED_METHODS <methods>...)
cmake_language(GET_MESSAGE_LOG_LEVEL <out-var>)
cmake_language(EXIT <exit-code>)

Introduction¶

This command will call meta-operations on built-in CMake commands or
those created via the macro() or function() commands.

cmake_language does not introduce a new variable or policy scope.

Calling Commands¶

cmake_language(CALL <command> [<arg>...])¶

Calls the named <command> with the given arguments (if any).
For example, the code:

set(message_command "message")
cmake_language(CALL ${message_command} STATUS "Hello World!")

is equivalent to

message(STATUS "Hello World!")

Note

To ensure consistency of the code, the following commands are not allowed:

if / elseif / else / endif

block / endblock

while / endwhile

foreach / endforeach

function / endfunction

macro / endmacro

Evaluating Code¶

cmake_language(EVAL CODE <code>...)¶

Evaluates the <code>... as CMake code.

For example, the code:

set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")

cmake_language(EVAL CODE "
  if (${condition})
    message(STATUS TRUE)
  else()
    message(STATUS FALSE)
  endif()"
)

is equivalent to

set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")

file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
  if (${condition})
    message(STATUS TRUE)
  else()
    message(STATUS FALSE)
  endif()"
)

include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)

Deferring Calls¶

New in version 3.19.

cmake_language(DEFER <options>... CALL <command> [<arg>...])¶

Schedules a call to the named <command> with the given arguments (if any)
to occur at a later time.  By default, deferred calls are executed as if
written at the end of the current directory's CMakeLists.txt file,
except that they run even after a return() call.  Variable
references in arguments are evaluated at the time the deferred call is
executed.

The options are:

DIRECTORY <dir>

Schedule the call for the end of the given directory instead of the
current directory.  The <dir> may reference either a source
directory or its corresponding binary directory.  Relative paths are
treated as relative to the current source directory.

The given directory must be known to CMake, being either the top-level
directory or one added by add_subdirectory().  Furthermore,
the given directory must not yet be finished processing.  This means
it can be the current directory or one of its ancestors.

ID <id>

Specify an identification for the deferred call.
The <id> may not be empty and may not begin with a capital letter A-Z.
The <id> may begin with an underscore (_) only if it was generated
automatically by an earlier call that used ID_VAR to get the id.

ID_VAR <var>

Specify a variable in which to store the identification for the
deferred call.  If ID <id> is not given, a new identification
will be generated and the generated id will start with an underscore (_).

The currently scheduled list of deferred calls may be retrieved:

cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)

This will store in <var> a semicolon-separated list of deferred call ids.  The ids are for the directory scope in which
the calls have been deferred to (i.e. where they will be executed), which can
be different to the scope in which they were created.  The DIRECTORY
option can be used to specify the scope for which to retrieve the call ids.
If that option is not given, the call ids for the current directory scope
will be returned.

Details of a specific call may be retrieved from its id:

cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)

This will store in <var> a semicolon-separated list in which the first element is the name of the command to be
called, and the remaining elements are its unevaluated arguments (any
contained ; characters are included literally and cannot be distinguished
from multiple arguments).  If multiple calls are scheduled with the same id,
this retrieves the first one.  If no call is scheduled with the given id in
the specified DIRECTORY scope (or the current directory scope if no
DIRECTORY option is given), this stores an empty string in the variable.

Deferred calls may be canceled by their id:

cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)

This cancels all deferred calls matching any of the given ids in the specified
DIRECTORY scope (or the current directory scope if no DIRECTORY option
is given).  Unknown ids are silently ignored.

Deferred Call Examples¶

For example, the code:

cmake_language(DEFER CALL message "${deferred_message}")
cmake_language(DEFER ID_VAR id CALL message "Canceled Message")
cmake_language(DEFER CANCEL_CALL ${id})
message("Immediate Message")
set(deferred_message "Deferred Message")

prints:

Immediate Message
Deferred Message

The Canceled Message is never printed because its command is
canceled.  The deferred_message variable reference is not evaluated
until the call site, so it can be set after the deferred call is scheduled.

In order to evaluate variable references immediately when scheduling a
deferred call, wrap it using cmake_language(EVAL).  However, note that
arguments will be re-evaluated in the deferred call, though that can be
avoided by using bracket arguments.  For example:

set(deferred_message "Deferred Message 1")
set(re_evaluated [[${deferred_message}]])
cmake_language(EVAL CODE "
  cmake_language(DEFER CALL message [[${deferred_message}]])
  cmake_language(DEFER CALL message \"${re_evaluated}\")
")
message("Immediate Message")
set(deferred_message "Deferred Message 2")

also prints:

Immediate Message
Deferred Message 1
Deferred Message 2

Dependency Providers¶

New in version 3.24.

Note

A high-level introduction to this feature can be found in the
Using Dependencies Guide.

cmake_language(SET_DEPENDENCY_PROVIDER <command> SUPPORTED_METHODS <methods>...)¶

When a call is made to find_package() or
FetchContent_MakeAvailable(), the call may be forwarded to a
dependency provider which then has the opportunity to fulfill the request.
If the request is for one of the <methods> specified when the provider
was set, CMake calls the provider's <command> with a set of
method-specific arguments.  If the provider does not fulfill the request,
or if the provider doesn't support the request's method, or no provider
is set, the built-in find_package() or
FetchContent_MakeAvailable() implementation is used to fulfill
the request in the usual way.

One or more of the following values can be specified for the <methods>
when setting the provider:

FIND_PACKAGE

The provider command accepts find_package() requests.

FETCHCONTENT_MAKEAVAILABLE_SERIAL

The provider command accepts FetchContent_MakeAvailable()
requests.  It expects each dependency to be fed to the provider command
one at a time, not the whole list in one go.

Only one provider can be set at any point in time.  If a provider is already
set when cmake_language(SET_DEPENDENCY_PROVIDER) is called, the new
provider replaces the previously set one.  The specified <command> must
already exist when cmake_language(SET_DEPENDENCY_PROVIDER) is called.
As a special case, providing an empty string for the <command> and no
<methods> will discard any previously set provider.

The dependency provider can only be set while processing one of the files
specified by the CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable.
Thus, dependency providers can only be set as part of the first call to
project().  Calling cmake_language(SET_DEPENDENCY_PROVIDER)
outside of that context will result in an error.

Note

The choice of dependency provider should always be under the user's control.
As a convenience, a project may choose to provide a file that users can
list in their CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable, but
the use of such a file should always be the user's choice.

Provider commands¶

Providers define a single <command> to accept requests.  The name of
the command should be specific to that provider, not something overly
generic that another provider might also use.  This enables users to compose
different providers in their own custom provider.  The recommended form is
xxx_provide_dependency(), where xxx is the provider-specific part
(e.g. vcpkg_provide_dependency(), conan_provide_dependency(),
ourcompany_provide_dependency(), and so on).

xxx_provide_dependency(<method> [<method-specific-args>...])

Because some methods expect certain variables to be set in the calling scope,
the provider command should typically be implemented as a macro rather than a
function.  This ensures it does not introduce a new variable scope.

The arguments CMake passes to the dependency provider depend on the type of
request.  The first argument is always the method, and it will only ever
be one of the <methods> that was specified when setting the provider.

FIND_PACKAGE

The <method-specific-args> will be everything passed to the
find_package() call that requested the dependency.  The first of
these <method-specific-args> will therefore always be the name of the
dependency.  Dependency names are case-sensitive for this method because
find_package() treats them case-sensitively too.

If the provider command fulfills the request, it must set the same variable
that find_package() expects to be set.  For a dependency named
depName, the provider must set depName_FOUND to true if it fulfilled
the request.  If the provider returns without setting this variable, CMake
will assume the request was not fulfilled and will fall back to the
built-in implementation.

If the provider needs to call the built-in find_package()
implementation as part of its processing, it can do so by including the
BYPASS_PROVIDER keyword as one of the arguments.

FETCHCONTENT_MAKEAVAILABLE_SERIAL

The <method-specific-args> will be everything passed to the
FetchContent_Declare() call that corresponds to the requested
dependency, with the following exceptions:

If SOURCE_DIR or BINARY_DIR were not part of the original
declared arguments, they will be added with their default values.

If FETCHCONTENT_TRY_FIND_PACKAGE_MODE is set to NEVER,
any FIND_PACKAGE_ARGS will be omitted.

The OVERRIDE_FIND_PACKAGE keyword is always omitted.

The first of the <method-specific-args> will always be the name of the
dependency.  Dependency names are case-insensitive for this method because
FetchContent also treats them case-insensitively.

If the provider fulfills the request, it should call
FetchContent_SetPopulated(), passing the name of the dependency as
the first argument.  The SOURCE_DIR and BINARY_DIR arguments to that
command should only be given if the provider makes the dependency's source
and build directories available in exactly the same way as the built-in
FetchContent_MakeAvailable() command.

If the provider returns without calling FetchContent_SetPopulated()
for the named dependency, CMake will assume the request was not fulfilled
and will fall back to the built-in implementation.

Note that empty arguments may be significant for this method (e.g. an empty
string following a GIT_SUBMODULES keyword).  Therefore, if forwarding
these arguments on to another command, extra care must be taken to avoid such
arguments being silently dropped.

If FETCHCONTENT_SOURCE_DIR_<uppercaseDepName> is set, then the
dependency provider will never see requests for the <depName> dependency
for this method. When the user sets such a variable, they are explicitly
overriding where to get that dependency from and are taking on the
responsibility that their overriding version meets any requirements for that
dependency and is compatible with whatever else in the project uses it.
Depending on the value of FETCHCONTENT_TRY_FIND_PACKAGE_MODE
and whether the OVERRIDE_FIND_PACKAGE option was given to
FetchContent_Declare(), having
FETCHCONTENT_SOURCE_DIR_<uppercaseDepName> set may also prevent the
dependency provider from seeing requests for a find_package(depName)
call too.

Provider Examples¶

This first example only intercepts find_package() calls.  The
provider command runs an external tool which copies the relevant artifacts
into a provider-specific directory, if that tool knows about the dependency.
It then relies on the built-in implementation to then find those artifacts.
FetchContent_MakeAvailable() calls would not go through the provider.

mycomp_provider.cmake¶

# Always ensure we have the policy settings this provider expects
cmake_minimum_required(VERSION 3.24)

set(MYCOMP_PROVIDER_INSTALL_DIR ${CMAKE_BINARY_DIR}/mycomp_packages
  CACHE PATH "The directory this provider installs packages to"
)
# Tell the built-in implementation to look in our area first, unless
# the find_package() call uses NO_..._PATH options to exclude it
list(APPEND CMAKE_MODULE_PATH ${MYCOMP_PROVIDER_INSTALL_DIR}/cmake)
list(APPEND CMAKE_PREFIX_PATH ${MYCOMP_PROVIDER_INSTALL_DIR})

macro(mycomp_provide_dependency method package_name)
  execute_process(
    COMMAND some_tool ${package_name} --installdir ${MYCOMP_PROVIDER_INSTALL_DIR}
    COMMAND_ERROR_IS_FATAL ANY
  )
endmacro()

cmake_language(
  SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
  SUPPORTED_METHODS FIND_PACKAGE
)

The user would then typically use the above file like so:

cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/mycomp_provider.cmake ...

The next example demonstrates a provider that accepts both methods, but
only handles one specific dependency.  It enforces providing Google Test
using FetchContent, but leaves all other dependencies to be
fulfilled by CMake's built-in implementation.  It accepts a few different
names, which demonstrates one way of working around projects that hard-code
an unusual or undesirable way of adding this particular dependency to the
build.  The example also demonstrates how to use the list() command
to preserve variables that may be overwritten by a call to
FetchContent_MakeAvailable().

mycomp_provider.cmake¶

cmake_minimum_required(VERSION 3.24)

# Because we declare this very early, it will take precedence over any
# details the project might declare later for the same thing
include(FetchContent)
FetchContent_Declare(
  googletest
  GIT_REPOSITORY https://github.com/google/googletest.git
  GIT_TAG        e2239ee6043f73722e7aa812a459f54a28552929 # release-1.11.0
)

# Both FIND_PACKAGE and FETCHCONTENT_MAKEAVAILABLE_SERIAL methods provide
# the package or dependency name as the first method-specific argument.
macro(mycomp_provide_dependency method dep_name)
  if("${dep_name}" MATCHES "^(gtest|googletest)$")
    # Save our current command arguments in case we are called recursively
    list(APPEND mycomp_provider_args ${method} ${dep_name})

    # This will forward to the built-in FetchContent implementation,
    # which detects a recursive call for the same thing and avoids calling
    # the provider again if dep_name is the same as the current call.
    FetchContent_MakeAvailable(googletest)

    # Restore our command arguments
    list(POP_BACK mycomp_provider_args dep_name method)

    # Tell the caller we fulfilled the request
    if("${method}" STREQUAL "FIND_PACKAGE")
      # We need to set this if we got here from a find_package() call
      # since we used a different method to fulfill the request.
      # This example assumes projects only use the gtest targets,
      # not any of the variables the FindGTest module may define.
      set(${dep_name}_FOUND TRUE)
    elseif(NOT "${dep_name}" STREQUAL "googletest")
      # We used the same method, but were given a different name to the
      # one we populated with. Tell the caller about the name it used.
      FetchContent_SetPopulated(${dep_name}
        SOURCE_DIR "${googletest_SOURCE_DIR}"
        BINARY_DIR "${googletest_BINARY_DIR}"
      )
    endif()
  endif()
endmacro()

cmake_language(
  SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
  SUPPORTED_METHODS
    FIND_PACKAGE
    FETCHCONTENT_MAKEAVAILABLE_SERIAL
)

The final example demonstrates how to modify arguments to a
find_package() call.  It forces all such calls to have the
QUIET keyword.  It uses the BYPASS_PROVIDER keyword to prevent
calling the provider command recursively for the same dependency.

mycomp_provider.cmake¶

cmake_minimum_required(VERSION 3.24)

macro(mycomp_provide_dependency method)
  find_package(${ARGN} BYPASS_PROVIDER QUIET)
endmacro()

cmake_language(
  SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
  SUPPORTED_METHODS FIND_PACKAGE
)

Getting current message log level¶

New in version 3.25.

cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)¶

Writes the current message() logging level
into the given <output_variable>.

See message() for the possible logging levels.

The current message logging level can be set either using the
--log-level
command line option of the cmake(1) program or using
the CMAKE_MESSAGE_LOG_LEVEL variable.

If both the command line option and the variable are set, the command line
option takes precedence. If neither are set, the default logging level
is returned.

Terminating Scripts¶

New in version 3.29.

cmake_language(EXIT <exit-code>)¶

Terminate the current cmake -P script and exit with <exit-code>.

This command works only in script mode.

The <exit-code> should be non-negative.
If <exit-code> is negative then the behavior
is unspecified (e.g., on Windows the error code -1
becomes 0xffffffff, and on Linux it becomes 255).

Table of Contents

cmake_language

Synopsis

Introduction

Calling Commands

Evaluating Code

Deferring Calls

Deferred Call Examples

Dependency Providers

Provider commands

Provider Examples

Getting current message log level

Terminating Scripts

Previous topic

cmake_host_system_information

Next topic

cmake_minimum_required

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_language

        © 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_minimum_required — 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_parse_arguments" href="cmake_parse_arguments.html" />
    <link rel="prev" title="cmake_language" href="cmake_language.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

cmake_minimum_required

cmake_minimum_required¶

Require a minimum version of cmake.

cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR])

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

Sets the minimum required version of cmake for a project.
Also updates the policy settings as explained below.

<min> and the optional <policy_max> are each CMake versions of the
form major.minor[.patch[.tweak]], and the ... is literal.

If the running version of CMake is lower than the <min> required
version it will stop processing the project and report an error.
The optional <policy_max> version, if specified, must be at least the
<min> version and affects policy settings as described in Policy Settings.
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 command will set the value of the
CMAKE_MINIMUM_REQUIRED_VERSION variable to <min>.

The FATAL_ERROR option is accepted but ignored by CMake 2.6 and
higher.  It should be specified so CMake versions 2.4 and lower fail
with an error instead of just a warning.

Note

Call the cmake_minimum_required() command at the beginning of
the top-level CMakeLists.txt file even before calling the
project() command.  It is important to establish version
and policy settings before invoking other commands whose behavior
they may affect.  See also policy CMP0000.

Calling cmake_minimum_required() inside a function()
limits some effects to the function scope when invoked.  For example,
the CMAKE_MINIMUM_REQUIRED_VERSION variable won't be set
in the calling scope.  Functions do not introduce their own policy
scope though, so policy settings of the caller will be affected
(see below).  Due to this mix of things that do and do not affect the
calling scope, calling cmake_minimum_required() inside a function
is generally discouraged.

Policy Settings¶

The cmake_minimum_required(VERSION) command implicitly invokes the
cmake_policy(VERSION) command to specify that the current
project 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.  This effectively requests behavior preferred
as of a given CMake version and tells newer CMake versions to warn
about their new policies.

When a <min> version higher than 2.4 is specified the command
implicitly invokes

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

which sets CMake policies based on the range of versions specified.
When a <min> version 2.4 or lower is given the command implicitly
invokes

cmake_policy(VERSION 2.4[...<max>])

which enables compatibility features for CMake 2.4 and lower.

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.

See Also¶

cmake_policy()

Table of Contents

cmake_minimum_required

Policy Settings

See Also

Previous topic

cmake_language

Next topic

cmake_parse_arguments

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_minimum_required

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

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

cmake_parse_arguments

cmake_parse_arguments¶

Parse function or macro arguments.

cmake_parse_arguments(<prefix> <options> <one_value_keywords>
                      <multi_value_keywords> <args>...)

cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
                      <one_value_keywords> <multi_value_keywords>)

New in version 3.5: This command is implemented natively.  Previously, it has been defined in the
module CMakeParseArguments.

This command is for use in macros or functions.
It processes the arguments given to that macro or function,
and defines a set of variables which hold the values of the
respective options.

The first signature reads processes arguments passed in the <args>....
This may be used in either a macro() or a function().

New in version 3.7: The PARSE_ARGV signature is only for use in a function()
body.  In this case the arguments that are parsed come from the
ARGV# variables of the calling function.  The parsing starts with
the <N>-th argument, where <N> is an unsigned integer.
This allows for the values to have special characters like ; in them.

The <options> argument contains all options for the respective macro,
i.e.  keywords which can be used when calling the macro without any value
following, like e.g.  the OPTIONAL keyword of the install()
command.

The <one_value_keywords> argument contains all keywords for this macro
which are followed by one value, like e.g. DESTINATION keyword of the
install() command.

The <multi_value_keywords> argument contains all keywords for this
macro which can be followed by more than one value, like e.g. the
TARGETS or FILES keywords of the install() command.

Changed in version 3.5: All keywords shall be unique. I.e. every keyword shall only be specified
once in either <options>, <one_value_keywords> or
<multi_value_keywords>. A warning will be emitted if uniqueness is
violated.

When done, cmake_parse_arguments will consider for each of the
keywords listed in <options>, <one_value_keywords> and
<multi_value_keywords> a variable composed of the given <prefix>
followed by "_" and the name of the respective keyword.  These
variables will then hold the respective value from the argument list
or be undefined if the associated option could not be found.
For the <options> keywords, these will always be defined,
to TRUE or FALSE, whether the option is in the argument list or not.

All remaining arguments are collected in a variable
<prefix>_UNPARSED_ARGUMENTS that will be undefined if all arguments
were recognized. This can be checked afterwards to see
whether your macro was called with unrecognized parameters.

New in version 3.15: <one_value_keywords> and <multi_value_keywords> that were given no
values at all are collected in a variable
<prefix>_KEYWORDS_MISSING_VALUES that will be undefined if all keywords
received values. This can be checked to see if there were keywords without
any values given.

Consider the following example macro, my_install(), which takes similar
arguments to the real install() command:

macro(my_install)
    set(options OPTIONAL FAST)
    set(oneValueArgs DESTINATION RENAME)
    set(multiValueArgs TARGETS CONFIGURATIONS)
    cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
                          "${multiValueArgs}" ${ARGN} )

    # ...

Assume my_install() has been called like this:

my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)

After the cmake_parse_arguments call the macro will have set or undefined
the following variables:

MY_INSTALL_OPTIONAL = TRUE
MY_INSTALL_FAST = FALSE # was not used in call to my_install
MY_INSTALL_DESTINATION = "bin"
MY_INSTALL_RENAME <UNDEFINED> # was not used
MY_INSTALL_TARGETS = "foo;bar"
MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
         # No value for "CONFIGURATIONS" given

You can then continue and process these variables.

Keywords terminate lists of values, e.g. if directly after a
one_value_keyword another recognized keyword follows, this is
interpreted as the beginning of the new option.  E.g.
my_install(TARGETS foo DESTINATION OPTIONAL) would result in
MY_INSTALL_DESTINATION set to "OPTIONAL", but as OPTIONAL
is a keyword itself MY_INSTALL_DESTINATION will be empty (but added
to MY_INSTALL_KEYWORDS_MISSING_VALUES) and MY_INSTALL_OPTIONAL will
therefore be set to TRUE.

See Also¶

function()

macro()

Table of Contents

cmake_parse_arguments

See Also

Previous topic

cmake_minimum_required

Next topic

cmake_path

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_parse_arguments

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