CMAKE-COMMANDS(7) CMake CMAKE-COMMANDS(7)
NAME
cmake-commands - CMake Language Command Reference
SCRIPTING COMMANDS
These commands are always available.
break
Break from an enclosing foreach or while loop.
break()
Breaks from an enclosing foreach() or while() loop.
See also the continue() command.
cmake_host_system_information
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:
+--------------------------+----------------------------+
|Key | Description |
+--------------------------+----------------------------+
|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 | One if processor is 64Bit |
+--------------------------+----------------------------+
|HAS_FPU | One if processor has |
| | floating point unit |
+--------------------------+----------------------------+
|HAS_MMX | One if processor supports |
| | MMX instructions |
+--------------------------+----------------------------+
|HAS_MMX_PLUS | One if processor supports |
| | Ext. MMX instructions |
+--------------------------+----------------------------+
|HAS_SSE | One if processor supports |
| | SSE instructions |
+--------------------------+----------------------------+
|HAS_SSE2 | One if processor supports |
| | SSE2 instructions |
+--------------------------+----------------------------+
|HAS_SSE_FP | One if processor supports |
| | SSE FP instructions |
+--------------------------+----------------------------+
|HAS_SSE_MMX | One if processor supports |
| | SSE MMX instructions |
+--------------------------+----------------------------+
|HAS_AMD_3DNOW | One if processor supports |
| | 3DNow instructions |
+--------------------------+----------------------------+
|HAS_AMD_3DNOW_PLUS | One if processor supports |
| | 3DNow+ instructions |
+--------------------------+----------------------------+
|HAS_IA64 | One if IA64 processor emu- |
| | lating x86 |
+--------------------------+----------------------------+
|HAS_SERIAL_NUMBER | One if processor has se- |
| | rial number |
+--------------------------+----------------------------+
|PROCESSOR_SERIAL_NUMBER | Processor serial number |
+--------------------------+----------------------------+
|PROCESSOR_NAME | Human readable processor |
| | name |
+--------------------------+----------------------------+
|PROCESSOR_DESCRIPTION | Human readable full pro- |
| | cessor description |
+--------------------------+----------------------------+
|OS_NAME | See CMAKE_HOST_SYSTEM_NAME |
+--------------------------+----------------------------+
|OS_RELEASE | The OS sub-type e.g. on |
| | Windows Professional |
+--------------------------+----------------------------+
|OS_VERSION | The OS build ID |
+--------------------------+----------------------------+
|OS_PLATFORM | See CMAKE_HOST_SYSTEM_PRO- |
| | CESSOR |
+--------------------------+----------------------------+
FOOTNOTES
[1] One MiB (mebibyte) is equal to 1024x1024 bytes.
cmake_language
Call meta-operations on CMake commands.
Synopsis
cmake_language(CALL <command> [<args>...])
cmake_language(EVAL CODE <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> [<args>...])
Calls the named <command> with the given arguments (if any). For exam-
ple, 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:
o if / elseif / else / endif
o while / endwhile
o foreach / endforeach
o function / endfunction
o 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)
cmake_minimum_required
Require a minimum version of cmake.
cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
Sets the minimum required version of cmake for a project. Also updates
the policy settings as explained below.
<min> and the optional <max> are each CMake versions of the form ma-
jor.minor[.patch[.tweak]], and the ... is literal.
If the running version of CMake is lower than the <min> required ver-
sion it will stop processing the project and report an error. The op-
tional <max> version, if specified, must be at least the <min> version
and affects policy settings as described below. If the running version
of CMake is older than 3.12, the extra ... dots will be seen as ver-
sion component separators, resulting in the ...<max> part being ignored
and preserving the pre-3.12 behavior of basing policies on <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 er-
ror 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() com-
mand. It is important to establish version and policy settings be-
fore invoking other commands whose behavior they may affect. See
also policy CMP0000.
Calling cmake_minimum_required() inside a function() limits some ef-
fects to the function scope when invoked. Such calls should not be
made with the intention of having global effects.
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 implic-
itly 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 in-
vokes
cmake_policy(VERSION 2.4[...<max>])
which enables compatibility features for CMake 2.4 and lower.
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>)
This command is for use in macros or functions. It processes the argu-
ments 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().
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() com-
mand.
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 TAR-
GETS or FILES keywords of the install() command.
NOTE:
All keywords shall be unique. I.e. every keyword shall only be spec-
ified 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>_UN-
PARSED_ARGUMENTS that will be undefined if all arguments were recog-
nized. This can be checked afterwards to see whether your macro was
called with unrecognized parameters.
<one_value_keywords> and <multi_value_keywords> that were given no val-
ues 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 unde-
fined 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 inter-
preted 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.
cmake_policy
Manage CMake Policy settings. See the cmake-policies(7) manual for de-
fined policies.
As CMake evolves it is sometimes necessary to change existing behavior
in order to fix bugs or improve implementations of existing features.
The CMake Policy mechanism is designed to help keep existing projects
building as new versions of CMake introduce changes in behavior. Each
new policy (behavioral change) is given an identifier of the form
CMP<NNNN> where <NNNN> is an integer index. Documentation associated
with each policy describes the OLD and NEW behavior and the reason the
policy was introduced. Projects may set each policy to select the de-
sired behavior. When CMake needs to know which behavior to use it
checks for a setting specified by the project. If no setting is avail-
able the OLD behavior is assumed and a warning is produced requesting
that the policy be set.
Setting Policies by CMake Version
The cmake_policy command is used to set policies to OLD or NEW behav-
ior. While setting policies individually is supported, we encourage
projects to set policies based on CMake versions:
cmake_policy(VERSION <min>[...<max>])
<min> and the optional <max> are each CMake versions of the form ma-
jor.minor[.patch[.tweak]], and the ... is literal. The <min> version
must be at least 2.4 and at most the running version of CMake. The
<max> version, if specified, must be at least the <min> version but may
exceed the running version of CMake. If the running version of CMake
is older than 3.12, the extra ... dots will be seen as version compo-
nent separators, resulting in the ...<max> part being ignored and pre-
serving the pre-3.12 behavior of basing policies on <min>.
This specifies that the current CMake code is written for the given
range of CMake versions. All policies known to the running version of
CMake and introduced in the <min> (or <max>, if specified) version or
earlier will be set to use NEW behavior. All policies introduced in
later versions will be unset (unless the CMAKE_POLICY_DEFAULT_CMP<NNNN>
variable sets a default). This effectively requests behavior preferred
as of a given CMake version and tells newer CMake versions to warn
about their new policies.
Note that the cmake_minimum_required(VERSION) command implicitly calls
cmake_policy(VERSION) too.
Setting Policies Explicitly
cmake_policy(SET CMP<NNNN> NEW)
cmake_policy(SET CMP<NNNN> OLD)
Tell CMake to use the OLD or NEW behavior for a given policy. Projects
depending on the old behavior of a given policy may silence a policy
warning by setting the policy state to OLD. Alternatively one may fix
the project to work with the new behavior and set the policy state to
NEW.
NOTE:
The OLD behavior of a policy is deprecated by definition and may be
removed in a future version of CMake.
Checking Policy Settings
cmake_policy(GET CMP<NNNN> <variable>)
Check whether a given policy is set to OLD or NEW behavior. The output
<variable> value will be OLD or NEW if the policy is set, and empty
otherwise.
CMake Policy Stack
CMake keeps policy settings on a stack, so changes made by the
cmake_policy command affect only the top of the stack. A new entry on
the policy stack is managed automatically for each subdirectory to pro-
tect its parents and siblings. CMake also manages a new entry for
scripts loaded by include() and find_package() commands except when in-
voked with the NO_POLICY_SCOPE option (see also policy CMP0011). The
cmake_policy command provides an interface to manage custom entries on
the policy stack:
cmake_policy(PUSH)
cmake_policy(POP)
Each PUSH must have a matching POP to erase any changes. This is use-
ful to make temporary changes to policy settings. Calls to the
cmake_minimum_required(VERSION), cmake_policy(VERSION), or cmake_pol-
icy(SET) commands influence only the current top of the policy stack.
Commands created by the function() and macro() commands record policy
settings when they are created and use the pre-record policies when
they are invoked. If the function or macro implementation sets poli-
cies, the changes automatically propagate up through callers until they
reach the closest nested policy stack entry.
configure_file
Copy a file to another location and modify its contents.
configure_file(<input> <output>
[COPYONLY] [ESCAPE_QUOTES] [@ONLY]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Copies an <input> file to an <output> file and substitutes variable
values referenced as @VAR@ or ${VAR} in the input file content. Each
variable reference will be replaced with the current value of the vari-
able, or the empty string if the variable is not defined. Furthermore,
input lines of the form
#cmakedefine VAR ...
will be replaced with either
#define VAR ...
or
/* #undef VAR */
depending on whether VAR is set in CMake to any value not considered a
false constant by the if() command. The content on the line after the
variable name, if any, is processed as above. Input file lines of the
form #cmakedefine01 VAR will be replaced with either #define VAR 1 or
#define VAR 0 similarly. The result lines (with the exception of the
#undef comments) can be indented using spaces and/or tabs between the #
character and the cmakedefine or cmakedefine01 words. This whitespace
indentation will be preserved in the output lines:
# cmakedefine VAR
# cmakedefine01 VAR
will be replaced, if VAR is defined, with
# define VAR
# define VAR 1
If the input file is modified the build system will re-run CMake to
re-configure the file and generate the build system again. The gener-
ated file is modified and its timestamp updated on subsequent cmake
runs only if its content is changed.
The arguments are:
<input>
Path to the input file. A relative path is treated with respect
to the value of CMAKE_CURRENT_SOURCE_DIR. The input path must
be a file, not a directory.
<output>
Path to the output file or directory. A relative path is
treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
If the path names an existing directory the output file is
placed in that directory with the same file name as the input
file.
COPYONLY
Copy the file without replacing any variable references or other
content. This option may not be used with NEWLINE_STYLE.
ESCAPE_QUOTES
Escape any substituted quotes with backslashes (C-style).
@ONLY Restrict variable replacement to references of the form @VAR@.
This is useful for configuring scripts that use ${VAR} syntax.
NEWLINE_STYLE <style>
Specify the newline style for the output file. Specify UNIX or
LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new-
lines. This option may not be used with COPYONLY.
Example
Consider a source tree containing a foo.h.in file:
#cmakedefine FOO_ENABLE
#cmakedefine FOO_STRING "@FOO_STRING@"
An adjacent CMakeLists.txt may use configure_file to configure the
header:
option(FOO_ENABLE "Enable Foo" ON)
if(FOO_ENABLE)
set(FOO_STRING "foo")
endif()
configure_file(foo.h.in foo.h @ONLY)
This creates a foo.h in the build directory corresponding to this
source directory. If the FOO_ENABLE option is on, the configured file
will contain:
#define FOO_ENABLE
#define FOO_STRING "foo"
Otherwise it will contain:
/* #undef FOO_ENABLE */
/* #undef FOO_STRING */
One may then use the include_directories() command to specify the out-
put directory as an include directory:
include_directories(${CMAKE_CURRENT_BINARY_DIR})
so that sources may include the header as #include <foo.h>.
continue
Continue to the top of enclosing foreach or while loop.
continue()
The continue command allows a cmake script to abort the rest of a block
in a foreach() or while() loop, and start at the top of the next itera-
tion.
See also the break() command.
else
Starts the else portion of an if block.
else([<condition>])
See the if() command.
elseif
Starts an elseif portion of an if block.
elseif(<condition>)
See the if() command, especially for the syntax and logic of the <con-
dition>.
endforeach
Ends a list of commands in a foreach block.
endforeach([<loop_var>])
See the foreach() command.
The optional <loop_var> argument is supported for backward compatibil-
ity only. If used it must be a verbatim repeat of the <loop_var> argu-
ment of the opening foreach clause.
endfunction
Ends a list of commands in a function block.
endfunction([<name>])
See the function() command.
The optional <name> argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the <name> argument of
the opening function command.
endif
Ends a list of commands in an if block.
CMAKE-COMMANDS(7) CMake CMAKE-COMMANDS(7)
NAME
cmake-commands - CMake Language Command Reference
SCRIPTING COMMANDS
These commands are always available.
break
Break from an enclosing foreach or while loop.
break()
Breaks from an enclosing foreach() or while() loop.
See also the continue() command.
cmake_host_system_information
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:
+--------------------------+----------------------------+
|Key | Description |
+--------------------------+----------------------------+
|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 | One if processor is 64Bit |
+--------------------------+----------------------------+
|HAS_FPU | One if processor has |
| | floating point unit |
+--------------------------+----------------------------+
|HAS_MMX | One if processor supports |
| | MMX instructions |
+--------------------------+----------------------------+
|HAS_MMX_PLUS | One if processor supports |
| | Ext. MMX instructions |
+--------------------------+----------------------------+
|HAS_SSE | One if processor supports |
| | SSE instructions |
+--------------------------+----------------------------+
|HAS_SSE2 | One if processor supports |
| | SSE2 instructions |
+--------------------------+----------------------------+
|HAS_SSE_FP | One if processor supports |
| | SSE FP instructions |
+--------------------------+----------------------------+
|HAS_SSE_MMX | One if processor supports |
| | SSE MMX instructions |
+--------------------------+----------------------------+
|HAS_AMD_3DNOW | One if processor supports |
| | 3DNow instructions |
+--------------------------+----------------------------+
|HAS_AMD_3DNOW_PLUS | One if processor supports |
| | 3DNow+ instructions |
+--------------------------+----------------------------+
|HAS_IA64 | One if IA64 processor emu- |
| | lating x86 |
+--------------------------+----------------------------+
|HAS_SERIAL_NUMBER | One if processor has se- |
| | rial number |
+--------------------------+----------------------------+
|PROCESSOR_SERIAL_NUMBER | Processor serial number |
+--------------------------+----------------------------+
|PROCESSOR_NAME | Human readable processor |
| | name |
+--------------------------+----------------------------+
|PROCESSOR_DESCRIPTION | Human readable full pro- |
| | cessor description |
+--------------------------+----------------------------+
|OS_NAME | See CMAKE_HOST_SYSTEM_NAME |
+--------------------------+----------------------------+
|OS_RELEASE | The OS sub-type e.g. on |
| | Windows Professional |
+--------------------------+----------------------------+
|OS_VERSION | The OS build ID |
+--------------------------+----------------------------+
|OS_PLATFORM | See CMAKE_HOST_SYSTEM_PRO- |
| | CESSOR |
+--------------------------+----------------------------+
FOOTNOTES
[1] One MiB (mebibyte) is equal to 1024x1024 bytes.
cmake_language
Call meta-operations on CMake commands.
Synopsis
cmake_language(CALL <command> [<args>...])
cmake_language(EVAL CODE <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> [<args>...])
Calls the named <command> with the given arguments (if any). For exam-
ple, 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:
o if / elseif / else / endif
o while / endwhile
o foreach / endforeach
o function / endfunction
o 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)
cmake_minimum_required
Require a minimum version of cmake.
cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
Sets the minimum required version of cmake for a project. Also updates
the policy settings as explained below.
<min> and the optional <max> are each CMake versions of the form ma-
jor.minor[.patch[.tweak]], and the ... is literal.
If the running version of CMake is lower than the <min> required ver-
sion it will stop processing the project and report an error. The op-
tional <max> version, if specified, must be at least the <min> version
and affects policy settings as described below. If the running version
of CMake is older than 3.12, the extra ... dots will be seen as ver-
sion component separators, resulting in the ...<max> part being ignored
and preserving the pre-3.12 behavior of basing policies on <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 er-
ror 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() com-
mand. It is important to establish version and policy settings be-
fore invoking other commands whose behavior they may affect. See
also policy CMP0000.
Calling cmake_minimum_required() inside a function() limits some ef-
fects to the function scope when invoked. Such calls should not be
made with the intention of having global effects.
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 implic-
itly 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 in-
vokes
cmake_policy(VERSION 2.4[...<max>])
which enables compatibility features for CMake 2.4 and lower.
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>)
This command is for use in macros or functions. It processes the argu-
ments 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().
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() com-
mand.
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 TAR-
GETS or FILES keywords of the install() command.
NOTE:
All keywords shall be unique. I.e. every keyword shall only be spec-
ified 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>_UN-
PARSED_ARGUMENTS that will be undefined if all arguments were recog-
nized. This can be checked afterwards to see whether your macro was
called with unrecognized parameters.
<one_value_keywords> and <multi_value_keywords> that were given no val-
ues 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 unde-
fined 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 inter-
preted 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.
cmake_policy
Manage CMake Policy settings. See the cmake-policies(7) manual for de-
fined policies.
As CMake evolves it is sometimes necessary to change existing behavior
in order to fix bugs or improve implementations of existing features.
The CMake Policy mechanism is designed to help keep existing projects
building as new versions of CMake introduce changes in behavior. Each
new policy (behavioral change) is given an identifier of the form
CMP<NNNN> where <NNNN> is an integer index. Documentation associated
with each policy describes the OLD and NEW behavior and the reason the
policy was introduced. Projects may set each policy to select the de-
sired behavior. When CMake needs to know which behavior to use it
checks for a setting specified by the project. If no setting is avail-
able the OLD behavior is assumed and a warning is produced requesting
that the policy be set.
Setting Policies by CMake Version
The cmake_policy command is used to set policies to OLD or NEW behav-
ior. While setting policies individually is supported, we encourage
projects to set policies based on CMake versions:
cmake_policy(VERSION <min>[...<max>])
<min> and the optional <max> are each CMake versions of the form ma-
jor.minor[.patch[.tweak]], and the ... is literal. The <min> version
must be at least 2.4 and at most the running version of CMake. The
<max> version, if specified, must be at least the <min> version but may
exceed the running version of CMake. If the running version of CMake
is older than 3.12, the extra ... dots will be seen as version compo-
nent separators, resulting in the ...<max> part being ignored and pre-
serving the pre-3.12 behavior of basing policies on <min>.
This specifies that the current CMake code is written for the given
range of CMake versions. All policies known to the running version of
CMake and introduced in the <min> (or <max>, if specified) version or
earlier will be set to use NEW behavior. All policies introduced in
later versions will be unset (unless the CMAKE_POLICY_DEFAULT_CMP<NNNN>
variable sets a default). This effectively requests behavior preferred
as of a given CMake version and tells newer CMake versions to warn
about their new policies.
Note that the cmake_minimum_required(VERSION) command implicitly calls
cmake_policy(VERSION) too.
Setting Policies Explicitly
cmake_policy(SET CMP<NNNN> NEW)
cmake_policy(SET CMP<NNNN> OLD)
Tell CMake to use the OLD or NEW behavior for a given policy. Projects
depending on the old behavior of a given policy may silence a policy
warning by setting the policy state to OLD. Alternatively one may fix
the project to work with the new behavior and set the policy state to
NEW.
NOTE:
The OLD behavior of a policy is deprecated by definition and may be
removed in a future version of CMake.
Checking Policy Settings
cmake_policy(GET CMP<NNNN> <variable>)
Check whether a given policy is set to OLD or NEW behavior. The output
<variable> value will be OLD or NEW if the policy is set, and empty
otherwise.
CMake Policy Stack
CMake keeps policy settings on a stack, so changes made by the
cmake_policy command affect only the top of the stack. A new entry on
the policy stack is managed automatically for each subdirectory to pro-
tect its parents and siblings. CMake also manages a new entry for
scripts loaded by include() and find_package() commands except when in-
voked with the NO_POLICY_SCOPE option (see also policy CMP0011). The
cmake_policy command provides an interface to manage custom entries on
the policy stack:
cmake_policy(PUSH)
cmake_policy(POP)
Each PUSH must have a matching POP to erase any changes. This is use-
ful to make temporary changes to policy settings. Calls to the
cmake_minimum_required(VERSION), cmake_policy(VERSION), or cmake_pol-
icy(SET) commands influence only the current top of the policy stack.
Commands created by the function() and macro() commands record policy
settings when they are created and use the pre-record policies when
they are invoked. If the function or macro implementation sets poli-
cies, the changes automatically propagate up through callers until they
reach the closest nested policy stack entry.
configure_file
Copy a file to another location and modify its contents.
configure_file(<input> <output>
[COPYONLY] [ESCAPE_QUOTES] [@ONLY]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Copies an <input> file to an <output> file and substitutes variable
values referenced as @VAR@ or ${VAR} in the input file content. Each
variable reference will be replaced with the current value of the vari-
able, or the empty string if the variable is not defined. Furthermore,
input lines of the form
#cmakedefine VAR ...
will be replaced with either
#define VAR ...
or
/* #undef VAR */
depending on whether VAR is set in CMake to any value not considered a
false constant by the if() command. The content on the line after the
variable name, if any, is processed as above. Input file lines of the
form #cmakedefine01 VAR will be replaced with either #define VAR 1 or
#define VAR 0 similarly. The result lines (with the exception of the
#undef comments) can be indented using spaces and/or tabs between the #
character and the cmakedefine or cmakedefine01 words. This whitespace
indentation will be preserved in the output lines:
# cmakedefine VAR
# cmakedefine01 VAR
will be replaced, if VAR is defined, with
# define VAR
# define VAR 1
If the input file is modified the build system will re-run CMake to
re-configure the file and generate the build system again. The gener-
ated file is modified and its timestamp updated on subsequent cmake
runs only if its content is changed.
The arguments are:
<input>
Path to the input file. A relative path is treated with respect
to the value of CMAKE_CURRENT_SOURCE_DIR. The input path must
be a file, not a directory.
<output>
Path to the output file or directory. A relative path is
treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
If the path names an existing directory the output file is
placed in that directory with the same file name as the input
file.
COPYONLY
Copy the file without replacing any variable references or other
content. This option may not be used with NEWLINE_STYLE.
ESCAPE_QUOTES
Escape any substituted quotes with backslashes (C-style).
@ONLY Restrict variable replacement to references of the form @VAR@.
This is useful for configuring scripts that use ${VAR} syntax.
NEWLINE_STYLE <style>
Specify the newline style for the output file. Specify UNIX or
LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new-
lines. This option may not be used with COPYONLY.
Example
Consider a source tree containing a foo.h.in file:
#cmakedefine FOO_ENABLE
#cmakedefine FOO_STRING "@FOO_STRING@"
An adjacent CMakeLists.txt may use configure_file to configure the
header:
option(FOO_ENABLE "Enable Foo" ON)
if(FOO_ENABLE)
set(FOO_STRING "foo")
endif()
configure_file(foo.h.in foo.h @ONLY)
This creates a foo.h in the build directory corresponding to this
source directory. If the FOO_ENABLE option is on, the configured file
will contain:
#define FOO_ENABLE
#define FOO_STRING "foo"
Otherwise it will contain:
/* #undef FOO_ENABLE */
/* #undef FOO_STRING */
One may then use the include_directories() command to specify the out-
put directory as an include directory:
include_directories(${CMAKE_CURRENT_BINARY_DIR})
so that sources may include the header as #include <foo.h>.
continue
Continue to the top of enclosing foreach or while loop.
continue()
The continue command allows a cmake script to abort the rest of a block
in a foreach() or while() loop, and start at the top of the next itera-
tion.
See also the break() command.
else
Starts the else portion of an if block.
else([<condition>])
See the if() command.
elseif
Starts an elseif portion of an if block.
elseif(<condition>)
See the if() command, especially for the syntax and logic of the <con-
dition>.
endforeach
Ends a list of commands in a foreach block.
endforeach([<loop_var>])
See the foreach() command.
The optional <loop_var> argument is supported for backward compatibil-
ity only. If used it must be a verbatim repeat of the <loop_var> argu-
ment of the opening foreach clause.
endfunction
Ends a list of commands in a function block.
endfunction([<name>])
See the function() command.
The optional <name> argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the <name> argument of
the opening function command.
endif
Ends a list of commands in an if block.
CMAKE-COMMANDS(7) CMake CMAKE-COMMANDS(7)
NAME
cmake-commands - CMake Language Command Reference
SCRIPTING COMMANDS
These commands are always available.
break
Break from an enclosing foreach or while loop.
break()
Breaks from an enclosing foreach() or while() loop.
See also the continue() command.
cmake_host_system_information
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:
+--------------------------+----------------------------+
|Key | Description |
+--------------------------+----------------------------+
|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 | One if processor is 64Bit |
+--------------------------+----------------------------+
|HAS_FPU | One if processor has |
| | floating point unit |
+--------------------------+----------------------------+
|HAS_MMX | One if processor supports |
| | MMX instructions |
+--------------------------+----------------------------+
|HAS_MMX_PLUS | One if processor supports |
| | Ext. MMX instructions |
+--------------------------+----------------------------+
|HAS_SSE | One if processor supports |
| | SSE instructions |
+--------------------------+----------------------------+
|HAS_SSE2 | One if processor supports |
| | SSE2 instructions |
+--------------------------+----------------------------+
|HAS_SSE_FP | One if processor supports |
| | SSE FP instructions |
+--------------------------+----------------------------+
|HAS_SSE_MMX | One if processor supports |
| | SSE MMX instructions |
+--------------------------+----------------------------+
|HAS_AMD_3DNOW | One if processor supports |
| | 3DNow instructions |
+--------------------------+----------------------------+
|HAS_AMD_3DNOW_PLUS | One if processor supports |
| | 3DNow+ instructions |
+--------------------------+----------------------------+
|HAS_IA64 | One if IA64 processor emu- |
| | lating x86 |
+--------------------------+----------------------------+
|HAS_SERIAL_NUMBER | One if processor has se- |
| | rial number |
+--------------------------+----------------------------+
|PROCESSOR_SERIAL_NUMBER | Processor serial number |
+--------------------------+----------------------------+
|PROCESSOR_NAME | Human readable processor |
| | name |
+--------------------------+----------------------------+
|PROCESSOR_DESCRIPTION | Human readable full pro- |
| | cessor description |
+--------------------------+----------------------------+
|OS_NAME | See CMAKE_HOST_SYSTEM_NAME |
+--------------------------+----------------------------+
|OS_RELEASE | The OS sub-type e.g. on |
| | Windows Professional |
+--------------------------+----------------------------+
|OS_VERSION | The OS build ID |
+--------------------------+----------------------------+
|OS_PLATFORM | See CMAKE_HOST_SYSTEM_PRO- |
| | CESSOR |
+--------------------------+----------------------------+
FOOTNOTES
[1] One MiB (mebibyte) is equal to 1024x1024 bytes.
cmake_language
Call meta-operations on CMake commands.
Synopsis
cmake_language(CALL <command> [<args>...])
cmake_language(EVAL CODE <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> [<args>...])
Calls the named <command> with the given arguments (if any). For exam-
ple, 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:
o if / elseif / else / endif
o while / endwhile
o foreach / endforeach
o function / endfunction
o 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)
cmake_minimum_required
Require a minimum version of cmake.
cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
Sets the minimum required version of cmake for a project. Also updates
the policy settings as explained below.
<min> and the optional <max> are each CMake versions of the form ma-
jor.minor[.patch[.tweak]], and the ... is literal.
If the running version of CMake is lower than the <min> required ver-
sion it will stop processing the project and report an error. The op-
tional <max> version, if specified, must be at least the <min> version
and affects policy settings as described below. If the running version
of CMake is older than 3.12, the extra ... dots will be seen as ver-
sion component separators, resulting in the ...<max> part being ignored
and preserving the pre-3.12 behavior of basing policies on <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 er-
ror 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() com-
mand. It is important to establish version and policy settings be-
fore invoking other commands whose behavior they may affect. See
also policy CMP0000.
Calling cmake_minimum_required() inside a function() limits some ef-
fects to the function scope when invoked. Such calls should not be
made with the intention of having global effects.
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 implic-
itly 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 in-
vokes
cmake_policy(VERSION 2.4[...<max>])
which enables compatibility features for CMake 2.4 and lower.
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>)
This command is for use in macros or functions. It processes the argu-
ments 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().
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() com-
mand.
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 TAR-
GETS or FILES keywords of the install() command.
NOTE:
All keywords shall be unique. I.e. every keyword shall only be spec-
ified 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>_UN-
PARSED_ARGUMENTS that will be undefined if all arguments were recog-
nized. This can be checked afterwards to see whether your macro was
called with unrecognized parameters.
<one_value_keywords> and <multi_value_keywords> that were given no val-
ues 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 unde-
fined 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 inter-
preted 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.
cmake_policy
Manage CMake Policy settings. See the cmake-policies(7) manual for de-
fined policies.
As CMake evolves it is sometimes necessary to change existing behavior
in order to fix bugs or improve implementations of existing features.
The CMake Policy mechanism is designed to help keep existing projects
building as new versions of CMake introduce changes in behavior. Each
new policy (behavioral change) is given an identifier of the form
CMP<NNNN> where <NNNN> is an integer index. Documentation associated
with each policy describes the OLD and NEW behavior and the reason the
policy was introduced. Projects may set each policy to select the de-
sired behavior. When CMake needs to know which behavior to use it
checks for a setting specified by the project. If no setting is avail-
able the OLD behavior is assumed and a warning is produced requesting
that the policy be set.
Setting Policies by CMake Version
The cmake_policy command is used to set policies to OLD or NEW behav-
ior. While setting policies individually is supported, we encourage
projects to set policies based on CMake versions:
cmake_policy(VERSION <min>[...<max>])
<min> and the optional <max> are each CMake versions of the form ma-
jor.minor[.patch[.tweak]], and the ... is literal. The <min> version
must be at least 2.4 and at most the running version of CMake. The
<max> version, if specified, must be at least the <min> version but may
exceed the running version of CMake. If the running version of CMake
is older than 3.12, the extra ... dots will be seen as version compo-
nent separators, resulting in the ...<max> part being ignored and pre-
serving the pre-3.12 behavior of basing policies on <min>.
This specifies that the current CMake code is written for the given
range of CMake versions. All policies known to the running version of
CMake and introduced in the <min> (or <max>, if specified) version or
earlier will be set to use NEW behavior. All policies introduced in
later versions will be unset (unless the CMAKE_POLICY_DEFAULT_CMP<NNNN>
variable sets a default). This effectively requests behavior preferred
as of a given CMake version and tells newer CMake versions to warn
about their new policies.
Note that the cmake_minimum_required(VERSION) command implicitly calls
cmake_policy(VERSION) too.
Setting Policies Explicitly
cmake_policy(SET CMP<NNNN> NEW)
cmake_policy(SET CMP<NNNN> OLD)
Tell CMake to use the OLD or NEW behavior for a given policy. Projects
depending on the old behavior of a given policy may silence a policy
warning by setting the policy state to OLD. Alternatively one may fix
the projecth> [DIRECTORY] [RELEASE]
[GUARD <FUNCTION|FILE|PROCESS>]
[RESULT_VARIABLE <variable>]
[TIMEOUT <seconds>])
Lock a file specified by <path> if no DIRECTORY option present and file
<path>/cmake.lock otherwise. File will be locked for scope defined by GUARD
option (default value is PROCESS). RELEASE option can be used to unlock file
explicitly. If option TIMEOUT is not specified CMake will wait until lock suc-
ceed or until fatal error occurs. If TIMEOUT is set to 0 lock will be tried
once and result will be reported immediately. If TIMEOUT is not 0 CMake will
try to lock file for the period specified by <seconds> value. Any errors will
be interpreted as fatal if there is no RESULT_VARIABLE option. Otherwise re-
sult will be stored in <variable> and will be 0 on success or error message on
failure.
Note that lock is advisory - there is no guarantee that other processes will
respect this lock, i.e. lock synchronize two or more CMake instances sharing
some modifiable resources. Similar logic applied to DIRECTORY option - locking
parent directory doesnt prevent other LOCK commands to lock any child direc-
tory or file.
Trying to lock file twice is not allowed. Any intermediate directories and
file itself will be created if they not exist. GUARD and TIMEOUT options ig-
nored on RELEASE operation.
Archiving
file(ARCHIVE_CREATE OUTPUT <archive>
PATHS <paths>...
[FORMAT <format>]
[COMPRESSION <compression>]
[MTIME <mtime>]
[VERBOSE])
Creates the specified <archive> file with the files and directories
listed in <paths>. Note that <paths> must list actual files or direc-
tories, wildcards are not supported.
Use the FORMAT option to specify the archive format. Supported values
for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is
not given, the default format is paxr.
Some archive formats allow the type of compression to be specified.
The 7zip and zip archive formats already imply a specific type of com-
pression. The other formats use no compression by default, but can be
directed to do so with the COMPRESSION option. Valid values for <com-
pression> are None, BZip2, GZip, XZ, and Zstd.
NOTE:
With FORMAT set to raw only one file will be compressed with the
compression type specified by COMPRESSION.
The VERBOSE option enables verbose output for the archive operation.
To specify the modification time recorded in tarball entries, use the
MTIME option.
file(ARCHIVE_EXTRACT INPUT <archive>
[DESTINATION <dir>]
[PATTERNS <patterns>...]
[LIST_ONLY]
[VERBOSE])
Extracts or lists the content of the specified <archive>.
The directory where the content of the archive will be extracted to can
be specified using the DESTINATION option. If the directory does not
exist, it will be created. If DESTINATION is not given, the current
binary directory will be used.
If required, you may select which files and directories to list or ex-
tract from the archive using the specified <patterns>. Wildcards are
supported. If the PATTERNS option is not given, the entire archive
will be listed or extracted.
LIST_ONLY will list the files in the archive rather than extract them.
With VERBOSE, the command will produce verbose output.
find_file
A short-hand signature is:
find_file (<VAR> name1 [path1 path2 ...])
The general signature is:
find_file (
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[REQUIRED]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
This command is used to find a full path to named file. A cache entry
named by <VAR> is created to store the result of this command. If the
full path to a file is found the result is stored in the variable and
the search will not be repeated unless the variable is cleared. If
nothing is found, the result will be <VAR>-NOTFOUND. The REQUIRED op-
tion stops processing with an error message if nothing is found, other-
wise the search will be attempted again the next time find_file is in-
voked with the same variable.
Options include:
NAMES Specify one or more possible names for the full path to a file.
When using this to specify names with and without a version suf-
fix, we recommend specifying the unversioned name first so that
locally-built packages can be found before those provided by
distributions.
HINTS, PATHS
Specify directories to search in addition to the default loca-
tions. The ENV var sub-option reads paths from a system envi-
ronment variable.
PATH_SUFFIXES
Specify additional subdirectories to check below each directory
location otherwise considered.
DOC Specify the documentation string for the <VAR> cache entry.
REQUIRED
Stop processing with an error message if nothing is found.
If NO_DEFAULT_PATH is specified, then no additional paths are added to
the search. If NO_DEFAULT_PATH is not specified, the search process is
as follows:
1. If called from within a find module or any other script loaded by a
call to find_package(<PackageName>), search prefixes unique to the
current package being found. Specifically, look in the <Package-
Name>_ROOT CMake variable and the <PackageName>_ROOT environment
variable. The package root variables are maintained as a stack, so
if called from nested find modules or config packages, root paths
from the parents find module or config package will be searched af-
ter paths from the current module or package. In other words, the
search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack-
age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
variable and the <PackageName>_ROOT environment variable if called
from within a find module loaded by find_package(<PackageName>)
2. Search paths specified in cmake-specific cache variables. These are
intended to be used on the command line with a -DVAR=value. The
values are interpreted as semicolon-separated lists. This can be
skipped if NO_CMAKE_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_PATH to FALSE.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
o CMAKE_INCLUDE_PATH
o CMAKE_FRAMEWORK_PATH
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the users shell configuration, and
therefore use the hosts native path separator th> [DIRECTORY] [RE-
LEASE]
[GUARD <FUNCTION|FILE|PROCESS>]
[RESULT_VARIABLE <variable>]
[TIMEOUT <seconds>])
Lock a file specified by <path> if no DIRECTORY option present and file
<path>/cmake.lock otherwise. File will be locked for scope defined by GUARD
option (default value is PROCESS). RELEASE option can be used to unlock file
explicitly. If option TIMEOUT is not specified CMake will wait until lock suc-
ceed or until fatal error occurs. If TIMEOUT is set to 0 lock will be tried
once and result will be reported immediately. If TIMEOUT is not 0 CMake will
try to lock file for the period specified by <seconds> value. Any errors will
be interpreted as fatal if there is no RESULT_VARIABLE option. Otherwise re-
sult will be stored in <variable> and will be 0 on success or error message on
failure.
Note that lock is advisory - there is no guarantee that other processes will
respect this lock, i.e. lock synchronize two or more CMake instances sharing
some modifiable resources. Similar logic applied to DIRECTORY option - locking
parent directory doesnt prevent other LOCK commands to lock any child direc-
tory or file.
Trying to lock file twice is not allowed. Any intermediate directories and
file itself will be created if they not exist. GUARD and TIMEOUT options ig-
nored on RELEASE operation.
Archiving
file(ARCHIVE_CREATE OUTPUT <archive>
PATHS <paths>...
[FORMAT <format>]
[COMPRESSION <compression>]
[MTIME <mtime>]
[VERBOSE])
Creates the specified <archive> file with the files and directories
listed in <paths>. Note that <paths> must list actual files or direc-
tories, wildcards are not supported.
Use the FORMAT option to specify the archive format. Supported values
for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is
not given, the default format is paxr.
Some archive formats allow the type of compression to be specified.
The 7zip and zip archive formats already imply a specific type of com-
pression. The other formats use no compression by default, but can be
directed to do so with the COMPRESSION option. Valid values for <com-
pression> are None, BZip2, GZip, XZ, and Zstd.
NOTE:
With FORMAT set to raw only one file will be compressed with the
compression type specified by COMPRESSION.
The VERBOSE option enables verbose output for the archive operation.
To specify the modification time recorded in tarball entries, use the
MTIME option.
file(ARCHIVE_EXTRACT INPUT <archive>
[DESTINATION <dir>]
[PATTERNS <patterns>...]
[LIST_ONLY]
[VERBOSE])
Extracts or lists the content of the specified <archive>.
The directory where the content of the archive will be extracted to can
be specified using the DESTINATION option. If the directory does not
exist, it will be created. If DESTINATION is not given, the current
binary directory will be used.
If required, you may select which files and directories to list or ex-
tract from the archive using the specified <patterns>. Wildcards are
supported. If the PATTERNS option is not given, the entire archive
will be listed or extracted.
LIST_ONLY will list the files in the archive rather than extract them.
With VERBOSE, the command will produce verbose output.
find_file
A short-hand signature is:
find_file (<VAR> name1 [path1 path2 ...])
The general signature is:
find_file (
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[REQUIRED]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
This command is used to find a full path to named file. A cache entry
named by <VAR> is created to store the result of this command. If the
full path to a file is found the result is stored in the variable and
the search will not be repeated unless the variable is cleared. If
nothing is found, the result will be <VAR>-NOTFOUND. The REQUIRED op-
tion stops processing with an error message if nothing is found, other-
wise the search will be attempted again the next time find_file is in-
voked with the same variable.
Options include:
NAMES Specify one or more possible names for the full path to a file.
When using this to specify names with and without a version suf-
fix, we recommend specifying the unversioned name first so that
locally-built packages can be found before those provided by
distributions.
HINTS, PATHS
Specify directories to search in addition to the default loca-
tions. The ENV var sub-option reads paths from a system envi-
ronment variable.
PATH_SUFFIXES
Specify additional subdirectories to check below each directory
location otherwise considered.
DOC Specify the documentation string for the <VAR> cache entry.
REQUIRED
Stop processing with an error message if nothing is found.
If NO_DEFAULT_PATH is specified, then no additional paths are added to
the search. If NO_DEFAULT_PATH is not specified, the search process is
as follows:
1. If called from within a find module or any other script loaded by a
call to find_package(<PackageName>), search prefixes unique to the
current package being found. Specifically, look in the <Package-
Name>_ROOT CMake variable and the <PackageName>_ROOT environment
variable. The package root variables are maintained as a stack, so
if called from nested find modules or config packages, root paths
from the parents find module or config package will be searched af-
ter paths from the current module or package. In other words, the
search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack-
age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
variable and the <PackageName>_ROOT environment variable if called
from within a find module loaded by find_package(<PackageName>)
2. Search paths specified in cmake-specific cache variables. These are
intended to be used on the command line with a -DVAR=value. The
values are interpreted as semicolon-separated lists. This can be
skipped if NO_CMAKE_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_PATH to FALSE.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
o CMAKE_INCLUDE_PATH
o CMAKE_FRAMEWORK_PATH
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the users shell configuration, and
therefore use the hosts native path separator th> [DIRECTORY] [RE-
LEASE]
[GUARD <FUNCTION|FILE|PROCESS>]
[RESULT_VARIABLE <variable>]
[TIMEOUT <seconds>])
Lock a file specified by <path> if no DIRECTORY option present and file
<path>/cmake.lock otherwise. File will be locked for scope defined by GUARD
option (default value is PROCESS). RELEASE option can be used to unlock file
explicitly. If option TIMEOUT is not specified CMake will wait until lock suc-
ceed or until fatal error occurs. If TIMEOUT is set to 0 lock will be tried
once and result will be reported immediately. If TIMEOUT is not 0 CMake will
try to lock file for the period specified by <seconds> value. Any errors will
be interpreted as fatal if there is no RESULT_VARIABLE option. Otherwise re-
sult will be stored in <variable> and will be 0 on success or error message on
failure.
Note that lock is advisory - there is no guarantee that other processes will
respect this lock, i.e. lock synchronize two or more CMake instances sharing
some modifiable resources. Similar logic applied to DIRECTORY option - locking
parent directory doesnt prevent other LOCK commands to lock any child direc-
tory or file.
Trying to lock file twice is not allowed. Any intermediate directories and
file itself will be created if they not exist. GUARD and TIMEOUT options ig-
nored on RELEASE operation.
Archiving
file(ARCHIVE_CREATE OUTPUT <archive>
PATHS <paths>...
[FORMAT <format>]
[COMPRESSION <compression>]
[MTIME <mtime>]
[VERBOSE])
Creates the specified <archive> file with the files and directories
listed in <paths>. Note that <paths> must list actual files or direc-
tories, wildcards are not supported.
Use the FORMAT option to specify the archive format. Supported values
for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is
not given, the default format is paxr.
Some archive formats allow the type of compression to be specified.
The 7zip and zip archive formats already imply a specific type of com-
pression. The other formats use no compression by default, but can be
directed to do so with the COMPRESSION option. Valid values for <com-
pression> are None, BZip2, GZip, XZ, and Zstd.
NOTE:
With FORMAT set to raw only one file will be compressed with the
compression type specified by COMPRESSION.
The VERBOSE option enables verbose output for the archive operation.
To specify the modification time recorded in tarball entries, use the
MTIME option.
file(ARCHIVE_EXTRACT INPUT <archive>
[DESTINATION <dir>]
[PATTERNS <patterns>...]
[LIST_ONLY]
[VERBOSE])
Extracts or lists the content of the specified <archive>.
The directory where the content of the archive will be extracted to can
be specified using the DESTINATION option. If the directory does not
exist, it will be created. If DESTINATION is not given, the current
binary directory will be used.
If required, you may select which files and directories to list or ex-
tract from the archive using the specified <patterns>. Wildcards are
supported. If the PATTERNS option is not given, the entire archive
will be listed or extracted.
LIST_ONLY will list the files in the archive rather than extract them.
With VERBOSE, the command will produce verbose output.
find_file
A short-hand signature is:
find_file (<VAR> name1 [path1 path2 ...])
The general signature is:
find_file (
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[REQUIRED]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
This command is used to find a full path to named file. A cache entry
named by <VAR> is created to store the result of this command. If the
full path to a file is found the result is stored in the variable and
the search will not be repeated unless the variable is cleared. If
nothing is found, the result will be <VAR>-NOTFOUND. The REQUIRED op-
tion stops processing with an error message if nothing is found, other-
wise the search will be attempted again the next time find_file is in-
voked with the same variable.
Options include:
NAMES Specify one or more possible names for the full path to a file.
When using this to specify names with and without a version suf-
fix, we recommend specifying the unversioned name first so that
locally-built packages can be found before those provided by
distributions.
HINTS, PATHS
Specify directories to search in addition to the default loca-
tions. The ENV var sub-option reads paths from a system envi-
ronment variable.
PATH_SUFFIXES
Specify additional subdirectories to check below each directory
location otherwise considered.
DOC Specify the documentation string for the <VAR> cache entry.
REQUIRED
Stop processing with an error message if nothing is found.
If NO_DEFAULT_PATH is specified, then no additional paths are added to
the search. If NO_DEFAULT_PATH is not specified, the search process is
as follows:
1. If called from within a find module or any other script loaded by a
call to find_package(<PackageName>), search prefixes unique to the
current package being found. Specifically, look in the <Package-
Name>_ROOT CMake variable and the <PackageName>_ROOT environment
variable. The package root variables are maintained as a stack, so
if called from nested find modules or config packages, root paths
from the parents find module or config package will be searched af-
ter paths from the current module or package. In other words, the
search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack-
age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
variable and the <PackageName>_ROOT environment variable if called
from within a find module loaded by find_package(<PackageName>)
2. Search paths specified in cmake-specific cache variables. These are
intended to be used on the command line with a -DVAR=value. The
values are interpreted as semicolon-separated lists. This can be
skipped if NO_CMAKE_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_PATH to FALSE.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
o CMAKE_INCLUDE_PATH
o CMAKE_FRAMEWORK_PATH
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the users shell configuration, and
therefore use the hosts native path separator th> [DIRECTORY] [RE-
LEASE]
[GUARD <FUNCTION|FILE|PROCESS>]
[RESULT_VARIABLE <variable>]
[TIMEOUT <seconds>])
Lock a file specified by <path> if no DIRECTORY option present and file
<path>/cmake.lock otherwise. File will be locked for scope defined by GUARD
option (default value is PROCESS). RELEASE option can be used to unlock file
explicitly. If option TIMEOUT is not specified CMake will wait until lock suc-
ceed or until fatal error occurs. If TIMEOUT is set to 0 lock will be tried
once and result will be reported immediately. If TIMEOUT is not 0 CMake will
try to lock file for the period specified by <seconds> value. Any errors will
be interpreted as fatal if there is no RESULT_VARIABLE option. Otherwise re-
sult will be stored in <variable> and will be 0 on success or error message on
failure.
Note that lock is advisory - there is no guarantee that other processes will
respect this lock, i.e. lock synchronize two or more CMake instances sharing
some modifiable resources. Similar logic applied to DIRECTORY option - locking
parent directory doesnt prevent other LOCK commands to lock any child direc-
tory or file.
Trying to lock file twice is not allowed. Any intermediate directories and
file itself will be created if they not exist. GUARD and TIMEOUT options ig-
nored on RELEASE operation.
Archiving
file(ARCHIVE_CREATE OUTPUT <archive>
PATHS <paths>...
[FORMAT <format>]
[COMPRESSION <compression>]
[MTIME <mtime>]
[VERBOSE])
Creates the specified <archive> file with the files and directories
listed in <paths>. Note that <paths> must list actual files or direc-
tories, wildcards are not supported.
Use the FORMAT option to specify the archive format. Supported values
for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is
not given, the default format is paxr.
Some archive formats allow the type of compression to be specified.
The 7zip and zip archive formats already imply a specific type of com-
pression. The other formats use no compression by default, but can be
directed to do so with the COMPRESSION option. Valid values for <com-
pression> are None, BZip2, GZip, XZ, and Zstd.
NOTE:
With FORMAT set to raw only one file will be compressed with the
compression type specified by COMPRESSION.
The VERBOSE option enables verbose output for the archive operation.
To specify the modification time recorded in tarball entries, use the
MTIME option.
file(ARCHIVE_EXTRACT INPUT <archive>
[DESTINATION <dir>]
[PATTERNS <patterns>...]
[LIST_ONLY]
[VERBOSE])
Extracts or lists the content of the specified <archive>.
The directory where the content of the archive will be extracted to can
be specified using the DESTINATION option. If the directory does not
exist, it will be created. If DESTINATION is not given, the current
binary directory will be used.
If required, you may select which files and directories to list or ex-
tract from the archive using the specified <patterns>. Wildcards are
supported. If the PATTERNS option is not given, the entire archive
will be listed or extracted.
LIST_ONLY will list the files in the archive rather than extract them.
With VERBOSE, the command will produce verbose output.
find_file
A short-hand signature is:
find_file (<VAR> name1 [path1 path2 ...])
The general signature is:
find_file (
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[REQUIRED]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
This command is used to find a full path to named file. A cache entry
named by <VAR> is created to store the result of this command. If the
full path to a file is found the result is stored in the variable and
the search will not be repeated unless the variable is cleared. If
nothing is found, the result will be <VAR>-NOTFOUND. The REQUIRED op-
tion stops processing with an error message if nothing is found, other-
wise the search will be attempted again the next time find_file is in-
voked with the same variable.
Options include:
NAMES Specify one or more possible names for the full path to a file.
When using this to specify names with and without a version suf-
fix, we recommend specifying the unversioned name first so that
locally-built packages can be found before those provided by
distributions.
HINTS, PATHS
Specify directories to search in addition to the default loca-
tions. The ENV var sub-option reads paths from a system envi-
ronment variable.
PATH_SUFFIXES
Specify additional subdirectories to check below each directory
location otherwise considered.
DOC Specify the documentation string for the <VAR> cache entry.
REQUIRED
Stop processing with an error message if nothing is found.
If NO_DEFAULT_PATH is specified, then no additional paths are added to
the search. If NO_DEFAULT_PATH is not specified, the search process is
as follows:
1. If called from within a find module or any other script loaded by a
call to find_package(<PackageName>), search prefixes unique to the
current package being found. Specifically, look in the <Package-
Name>_ROOT CMake variable and the <PackageName>_ROOT environment
variable. The package root variables are maintained as a stack, so
if called from nested find modules or config packages, root paths
from the parents find module or config package will be searched af-
ter paths from the current module or package. In other words, the
search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack-
age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
variable and the <PackageName>_ROOT environment variable if called
from within a find module loaded by find_package(<PackageName>)
2. Search paths specified in cmake-specific cache variables. These are
intended to be used on the command line with a -DVAR=value. The
values are interpreted as semicolon-separated lists. This can be
skipped if NO_CMAKE_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_PATH to FALSE.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
o CMAKE_INCLUDE_PATH
o CMAKE_FRAMEWORK_PATH
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the users shell configuration, and
therefore use the hosts native path separator th> [DIRECTORY] [RE-
LEASE]
[GUARD <FUNCTION|FILE|PROCESS>]
[RESULT_VARIABLE <variable>]
[TIMEOUT <seconds>])
Lock a file specified by <path> if no DIRECTORY option present and file
<path>/cmake.lock otherwise. File will be locked for scope defined by GUARD
option (default value is PROCESS). RELEASE option can be used to unlock file
explicitly. If option TIMEOUT is not specified CMake will wait until lock suc-
ceed or until fatal error occurs. If TIMEOUT is set to 0 lock will be tried
once and result will be reported immediately. If TIMEOUT is not 0 CMake will
try to lock file for the period specified by <seconds> value. Any errors will
be interpreted as fatal if there is no RESULT_VARIABLE option. Otherwise re-
sult will be stored in <variable> and will be 0 on success or error message on
failure.
Note that lock is advisory - there is no guarantee that other processes will
respect this lock, i.e. lock synchronize two or more CMake instances sharing
some modifiable resources. Similar logic applied to DIRECTORY option - locking
parent directory doesnt prevent other LOCK commands to lock any child direc-
tory or file.
Trying to lock file twice is not allowed. Any intermediate directories and
file itself will be created if they not exist. GUARD and TIMEOUT options ig-
nored on RELEASE operation.
Archiving
file(ARCHIVE_CREATE OUTPUT <archive>
PATHS <paths>...
[FORMAT <format>]
[COMPRESSION <compression>]
[MTIME <mtime>]
[VERBOSE])
Creates the specified <archive> file with the files and directories
listed in <paths>. Note that <paths> must list actual files or direc-
tories, wildcards are not supported.
Use the FORMAT option to specify the archive format. Supported values
for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is
not given, the default format is paxr.
Some archive formats allow the type of compression to be specified.
The 7zip and zip archive formats already imply a specific type of com-
pression. The other formats use no compression by default, but can be
directed to do so with the COMPRESSION option. Valid values for <com-
pression> are None, BZip2, GZip, XZ, and Zstd.
NOTE:
With FORMAT set to raw only one file will be compressed with the
compression type specified by COMPRESSION.
The VERBOSE option enables verbose output for the archive operation.
To specify the modification time recorded in tarball entries, use the
MTIME option.
file(ARCHIVE_EXTRACT INPUT <archive>
[DESTINATION <dir>]
[PATTERNS <patterns>...]
[LIST_ONLY]
[VERBOSE])
Extracts or lists the content of the specified <archive>.
The directory where the content of the archive will be extracted to can
be specified using the DESTINATION option. If the directory does not
exist, it will be created. If DESTINATION is not given, the current
binary directory will be used.
If required, you may select which files and directories to list or ex-
tract from the archive using the specified <patterns>. Wildcards are
supported. If the PATTERNS option is not given, the entire archive
will be listed or extracted.
LIST_ONLY will list the files in the archive rather than extract them.
With VERBOSE, the command will produce verbose output.
find_file
A short-hand signature is:
find_file (<VAR> name1 [path1 path2 ...])
The general signature is:
find_file (
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[REQUIRED]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
This command is used to find a full path to named file. A cache entry
named by <VAR> is created to store the result of this command. If the
full path to a file is found the result is stored in the variable and
the search will not be repeated unless the variable is cleared. If
nothing is found, the result will be <VAR>-NOTFOUND. The REQUIRED op-
tion stops processing with an error message if nothing is found, other-
wise the search will be attempted again the next time find_file is in-
voked with the same variable.
Options include:
NAMES Specify one or more possible names for the full path to a file.
When using this to specify names with and without a version suf-
fix, we recommend specifying the unversioned name first so that
locally-built packages can be found before those provided by
distributions.
HINTS, PATHS
Specify directories to search in addition to the default loca-
tions. The ENV var sub-option reads paths from a system envi-
ronment variable.
PATH_SUFFIXES
Specify additional subdirectories to check below each directory
location otherwise considered.
DOC Specify the documentation string for the <VAR> cache entry.
REQUIRED
Stop processing with an error message if nothing is found.
If NO_DEFAULT_PATH is specified, then no additional paths are added to
the search. If NO_DEFAULT_PATH is not specified, the search process is
as follows:
1. If called from within a find module or any other script loaded by a
call to find_package(<PackageName>), search prefixes unique to the
current package being found. Specifically, look in the <Package-
Name>_ROOT CMake variable and the <PackageName>_ROOT environment
variable. The package root variables are maintained as a stack, so
if called from nested find modules or config packages, root paths
from the parents find module or config package will be searched af-
ter paths from the current module or package. In other words, the
search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack-
age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
variable and the <PackageName>_ROOT environment variable if called
from within a find module loaded by find_package(<PackageName>)
2. Search paths specified in cmake-specific cache variables. These are
intended to be used on the command line with a -DVAR=value. The
values are interpreted as semicolon-separated lists. This can be
skipped if NO_CMAKE_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_PATH to FALSE.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
o CMAKE_INCLUDE_PATH
o CMAKE_FRAMEWORK_PATH
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the users shell configuration, and
therefore use the hosts native path separator th> [DIRECTORY] [RE-
LEASE]
[GUARD <FUNCTION|FILE|PROCESS>]
[RESULT_VARIABLE <variable>]
[TIMEOUT <seconds>])
Lock a file specified by <path> if no DIRECTORY option present and file
<path>/cmake.lock otherwise. File will be locked for scope defined by GUARD
option (default value is PROCESS). RELEASE option can be used to unlock file
explicitly. If option TIMEOUT is not specified CMake will wait until lock suc-
ceed or until fatal error occurs. If TIMEOUT is set to 0 lock will be tried
once and result will be reported immediately. If TIMEOUT is not 0 CMake will
try to lock file for the period specified by <seconds> value. Any errors will
be interpreted as fatal if there is no RESULT_VARIABLE option. Otherwise re-
sult will be stored in <variable> and will be 0 on success or error message on
failure.
Note that lock is advisory - there is no guarantee that other processes will
respect this lock, i.e. lock synchronize two or more CMake instances sharing
some modifiable resources. Similar logic applied to DIRECTORY option - locking
parent directory doesnt prevent other LOCK commands to lock any child direc-
tory or file.
Trying to lock file twice is not allowed. Any intermediate directories and
file itself will be created if they not exist. GUARD and TIMEOUT options ig-
nored on RELEASE operation.
Archiving
file(ARCHIVE_CREATE OUTPUT <archive>
PATHS <paths>...
[FORMAT <format>]
[COMPRESSION <compression>]
[MTIME <mtime>]
[VERBOSE])
Creates the specified <archive> file with the files and directories
listed in <paths>. Note that <paths> must list actual files or direc-
tories, wildcards are not supported.
Use the FORMAT option to specify the archive format. Supported values
for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is
not given, the default format is paxr.
Some archive formats allow the type of compression to be specified.
The 7zip and zip archive formats already imply a specific type of com-
pression. The other formats use no compression by default, but can be
directed to do so with the COMPRESSION option. Valid values for <com-
pression> are None, BZip2, GZip, XZ, and Zstd.
NOTE:
With FORMAT set to raw only one file will be compressed with the
compression type specified by COMPRESSION.
The VERBOSE option enables verbose output for the archive operation.
To specify the modification time recorded in tarball entries, use the
MTIME option.
file(ARCHIVE_EXTRACT INPUT <archive>
[DESTINATION <dir>]
[PATTERNS <patterns>...]
[LIST_ONLY]
[VERBOSE])
Extracts or lists the content of the specified <archive>.
The directory where the content of the archive will be extracted to can
be specified using the DESTINATION option. If the directory does not
exist, it will be created. If DESTINATION is not given, the current
binary directory will be used.
If required, you may select which files and directories to list or ex-
tract from the archive using the specified <patterns>. Wildcards are
supported. If the PATTERNS option is not given, the entire archive
will be listed or extracted.
LIST_ONLY will list the files in the archive rather than extract them.
With VERBOSE, the command will produce verbose output.
find_file
A short-hand signature is:
find_file (<VAR> name1 [path1 path2 ...])
The general signature is:
find_file (
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[REQUIRED]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
This command is used to find a full path to named file. A cache entry
named by <VAR> is created to store the result of this command. If the
full path to a file is found the result is stored in the variable and
the search will not be repeated unless the variable is cleared. If
nothing is found, the result will be <VAR>-NOTFOUND. The REQUIRED op-
tion stops processing with an error message if nothing is found, other-
wise the search will be attempted again the next time find_file is in-
voked with the same variable.
Options include:
NAMES Specify one or more possible names for the full path to a file.
When using this to specify names with and without a version suf-
fix, we recommend specifying the unversioned name first so that
locally-built packages can be found before those provided by
distributions.
HINTS, PATHS
Specify directories to search in addition to the default loca-
tions. The ENV var sub-option reads paths from a system envi-
ronment variable.
PATH_SUFFIXES
Specify additional subdirectories to check below each directory
location otherwise considered.
DOC Specify the documentation string for the <VAR> cache entry.
REQUIRED
Stop processing with an error message if nothing is found.
If NO_DEFAULT_PATH is specified, then no additional paths are added to
the search. If NO_DEFAULT_PATH is not specified, the search process is
as follows:
1. If called from within a find module or any other script loaded by a
call to find_package(<PackageName>), search prefixes unique to the
current package being found. Specifically, look in the <Package-
Name>_ROOT CMake variable and the <PackageName>_ROOT environment
variable. The package root variables are maintained as a stack, so
if called from nested find modules or config packages, root paths
from the parents find module or config package will be searched af-
ter paths from the current module or package. In other words, the
search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack-
age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
variable and the <PackageName>_ROOT environment variable if called
from within a find module loaded by find_package(<PackageName>)
2. Search paths specified in cmake-specific cache variables. These are
intended to be used on the command line with a -DVAR=value. The
values are interpreted as semicolon-separated lists. This can be
skipped if NO_CMAKE_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_PATH to FALSE.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
o CMAKE_INCLUDE_PATH
o CMAKE_FRAMEWORK_PATH
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the users shell configuration, and
therefore use the hosts native path separator th> [DIRECTORY] [RE-
LEASE]
[GUARD <FUNCTION|FILE|PROCESS>]
[RESULT_VARIABLE <variable>]
[TIMEOUT <seconds>])
Lock a file specified by <path> if no DIRECTORY option present and file
<path>/cmake.lock otherwise. File will be locked for scope defined by GUARD
option (default value is PROCESS). RELEASE option can be used to unlock file
explicitly. If option TIMEOUT is not specified CMake will wait until lock suc-
ceed or until fatal error occurs. If TIMEOUT is set to 0 lock will be tried
once and result will be reported immediately. If TIMEOUT is not 0 CMake will
try to lock file for the period specified by <seconds> value. Any errors will
be interpreted as fatal if there is no RESULT_VARIABLE option. Otherwise re-
sult will be stored in <variable> and will be 0 on success or error message on
failure.
Note that lock is advisory - there is no guarantee that other processes will
respect this lock, i.e. lock synchronize two or more CMake instances sharing
some modifiable resources. Similar logic applied to DIRECTORY option - locking
parent directory doesnt prevent other LOCK commands to lock any child direc-
tory or file.
Trying to lock file twice is not allowed. Any intermediate directories and
file itself will be created if they not exist. GUARD and TIMEOUT options ig-
nored on RELEASE operation.
Archiving
file(ARCHIVE_CREATE OUTPUT <archive>
PATHS <paths>...
[FORMAT <format>]
[COMPRESSION <compression>]
[MTIME <mtime>]
[VERBOSE])
Creates the specified <archive> file with the files and directories
listed in <paths>. Note that <paths> must list actual files or direc-
tories, wildcards are not supported.
Use the FORMAT option to specify the archive format. Supported values
for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is
not given, the default format is paxr.
Some archive formats allow the type of compression to be specified.
The 7zip and zip archive formats already imply a specific type of com-
pression. The other formats use no compression by default, but can be
directed to do so with the COMPRESSION option. Valid values for <com-
pression> are None, BZip2, GZip, XZ, and Zstd.
NOTE:
With FORMAT set to raw only one file will be compressed with the
compression type specified by COMPRESSION.
The VERBOSE option enables verbose output for the archive operation.
To specify the modification time recorded in tarball entries, use the
MTIME option.
file(ARCHIVE_EXTRACT INPUT <archive>
[DESTINATION <dir>]
[PATTERNS <patterns>...]
[LIST_ONLY]
[VERBOSE])
Extracts or lists the content of the specified <archive>.
The directory where the content of the archive will be extracted to can
be specified using the DESTINATION option. If the directory does not
exist, it will be created. If DESTINATION is not given, the current
binary directory will be used.
If required, you may select which files and directories to list or ex-
tract from the archive using the specified <patterns>. Wildcards are
supported. If the PATTERNS option is not given, the entire archive
will be listed or extracted.
LIST_ONLY will list the files in the archive rather than extract them.
With VERBOSE, the command will produce verbose output.
find_file
A short-hand signature is:
find_file (<VAR> name1 [path1 path2 ...])
The general signature is:
find_file (
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[REQUIRED]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
This command is used to find a full path to named file. A cache entry
named by <VAR> is created to store the result of this command. If the
full path to a file is found the result is stored in the variable and
the search will not be repeated unless the variable is cleared. If
nothing is found, the result will be <VAR>-NOTFOUND. The REQUIRED op-
tion stops processing with an error message if nothing is found, other-
wise the search will be attempted again the next time find_file is in-
voked with the same variable.
Options include:
NAMES Specify one or more possible names for the full path to a file.
When using this to specify names with and without a version suf-
fix, we recommend specifying the unversioned name first so that
locally-built packages can be found before those provided by
distributions.
HINTS, PATHS
Specify directories to search in addition to the default loca-
tions. The ENV var sub-option reads paths from a system envi-
ronment variable.
PATH_SUFFIXES
Specify additional subdirectories to check below each directory
location otherwise considered.
DOC Specify the documentation string for the <VAR> cache entry.
REQUIRED
Stop processing with an error message if nothing is found.
If NO_DEFAULT_PATH is specified, then no additional paths are added to
the search. If NO_DEFAULT_PATH is not specified, the search process is
as follows:
1. If called from within a find module or any other script loaded by a
call to find_package(<PackageName>), search prefixes unique to the
current package being found. Specifically, look in the <Package-
Name>_ROOT CMake variable and the <PackageName>_ROOT environment
variable. The package root variables are maintained as a stack, so
if called from nested find modules or config packages, root paths
from the parents find module or config package will be searched af-
ter paths from the current module or package. In other words, the
search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack-
age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
variable and the <PackageName>_ROOT environment variable if called
from within a find module loaded by find_package(<PackageName>)
2. Search paths specified in cmake-specific cache variables. These are
intended to be used on the command line with a -DVAR=value. The
values are interpreted as semicolon-separated lists. This can be
skipped if NO_CMAKE_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_PATH to FALSE.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
o CMAKE_INCLUDE_PATH
o CMAKE_FRAMEWORK_PATH
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the users shell configuration, and
therefore use the hosts native path separator th> [DIRECTORY] [RE-
LEASE]
[GUARD <FUNCTION|FILE|PROCESS>]
[RESULT_VARIABLE <variable>]
[TIMEOUT <seconds>])
Lock a file specified by <path> if no DIRECTORY option present and file
<path>/cmake.lock otherwise. File will be locked for scope defined by GUARD
option (default value is PROCESS). RELEASE option can be used to unlock file
explicitly. If option TIMEOUT is not specified CMake will wait until lock suc-
ceed or until fatal error occurs. If TIMEOUT is set to 0 lock will be tried
once and result will be reported immediately. If TIMEOUT is not 0 CMake will
try to lock file for the period specified by <seconds> value. Any errors will
be interpreted as fatal if there is no RESULT_VARIABLE option. Otherwise re-
sult will be stored in <variable> and will be 0 on success or error message on
failure.
Note that lock is advisory - there is no guarantee that other processes will
respect this lock, i.e. lock synchronize two or more CMake instances sharing
some modifiable resources. Similar logic applied to DIRECTORY option - locking
parent directory doesnt prevent other LOCK commands to lock any child direc-
tory or file.
Trying to lock file twice is not allowed. Any intermediate directories and
file itself will be created if they not exist. GUARD and TIMEOUT options ig-
nored on RELEASE operation.
Archiving
file(ARCHIVE_CREATE OUTPUT <archive>
PATHS <paths>...
[FORMAT <format>]
[COMPRESSION <compression>]
[MTIME <mtime>]
[VERBOSE])
Creates the specified <archive> file with the files and directories
listed in <paths>. Note that <paths> must list actual files or direc-
tories, wildcards are not supported.
Use the FORMAT option to specify the archive format. Supported values
for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is
not given, the default format is paxr.
Some archive formats allow the type of compression to be specified.
The 7zip and zip archive formats already imply a specific type of com-
pression. The other formats use no compression by default, but can be
directed to do so with the COMPRESSION option. Valid values for <com-
pression> are None, BZip2, GZip, XZ, and Zstd.
NOTE:
With FORMAT set to raw only one file will be compressed with the
compression type specified by COMPRESSION.
The VERBOSE option enables verbose output for the archive operation.
To specify the modification time recorded in tarball entries, use the
MTIME option.
file(ARCHIVE_EXTRACT INPUT <archive>
[DESTINATION <dir>]
[PATTERNS <patterns>...]
[LIST_ONLY]
[VERBOSE])
Extracts or lists the content of the specified <archive>.
The directory where the content of the archive will be extracted to can
be specified using the DESTINATION option. If the directory does not
exist, it will be created. If DESTINATION is not given, the current
binary directory will be used.
If required, you may select which files and directories to list or ex-
tract from the archive using the specified <patterns>. Wildcards are
supported. If the PATTERNS option is not given, the entire archive
will be listed or extracted.
LIST_ONLY will list the files in the archive rather than extract them.
With VERBOSE, the command will produce verbose output.
find_file
A short-hand signature is:
find_file (<VAR> name1 [path1 path2 ...])
The general signature is:
find_file (
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[REQUIRED]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
This command is used to find a full path to named file. A cache entry
named by <VAR> is created to store the result of this command. If the
full path to a file is found the result is stored in the variable and
the search will not be repeated unless the variable is cleared. If
nothing is found, the result will be <VAR>-NOTFOUND. The REQUIRED op-
tion stops processing with an error message if nothing is found, other-
wise the search will be attempted again the next time find_file is in-
voked with the same variable.
Options include:
NAMES Specify one or more possible names for the full path to a file.
When using this to specify names with and without a version suf-
fix, we recommend specifying the unversioned name first so that
locally-built packages can be found before those provided by
distributions.
HINTS, PATHS
Specify directories to search in addition to the default loca-
tions. The ENV var sub-option reads paths from a system envi-
ronment variable.
PATH_SUFFIXES
Specify additional subdirectories to check below each directory
location otherwise considered.
DOC Specify the documentation string for the <VAR> cache entry.
REQUIRED
Stop processing with an error message if nothing is found.
If NO_DEFAULT_PATH is specified, then no additional paths are added to
the search. If NO_DEFAULT_PATH is not specified, the search process is
as follows:
1. If called from within a find module or any other script loaded by a
call to find_package(<PackageName>), search prefixes unique to the
current package being found. Specifically, look in the <Package-
Name>_ROOT CMake variable and the <PackageName>_ROOT environment
variable. The package root variables are maintained as a stack, so
if called from nested find modules or config packages, root paths
from the parents find module or config package will be searched af-
ter paths from the current module or package. In other words, the
search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack-
age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
variable and the <PackageName>_ROOT environment variable if called
from within a find module loaded by find_package(<PackageName>)
2. Search paths specified in cmake-specific cache variables. These are
intended to be used on the command line with a -DVAR=value. The
values are interpreted as semicolon-separated lists. This can be
skipped if NO_CMAKE_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_PATH to FALSE.
o <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
<prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
o CMAKE_INCLUDE_PATH
o CMAKE_FRAMEWORK_PATH
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the users shell configuration, and
therefore use the hosts native path separator th> [DIRECTORY] [RE-
LEASE]
[GUARD <FUNCTION|FILE|PROCESS>]
[RESULT_VARIABLE <variable>]
[TIMEOUT <seconds>])
Lock a file specified by <path>iga)
foreach(num IN ZIP_LISTS English Bahasa)
message(STATUS "num_0=${num_0}, num_1=${num_1}") endforeach()
foreach(en ba IN ZIP_LISTS English Bahasa)
message(STATUS "en=${en}, ba=${ba}") endforeach()
yields
-- num_0=one, num_1=satu
-- num_0=two, num_1=dua
-- num_0=three, num_1=tiga
-- num_0=four, num_1=
-- en=one, ba=satu
-- en=two, ba=dua
-- en=three, ba=tiga
-- en=four, ba=
function
Start recording a function for later invocation as a command.
function(<name> [<arg1> ...])
<commands>
endfunction()
Defines a function named <name> that takes arguments named <arg1>,
The <commands> in the function definition are recorded; they are not
executed until the function is invoked.
Per legacy, the endfunction() command admits an optional <name> argu-
ment. If used, it must be a verbatim repeat of the argument of the
opening function command.
A function opens a new scope: see set(var PARENT_SCOPE) for details.
See the cmake_policy() command documentation for the behavior of poli-
cies inside functions.
See the macro() command documentation for differences between CMake
functions and macros.
Invocation
The function invocation is case-insensitive. A function defined as
function(foo)
<commands>
endfunction()
can be invoked through any of
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the case
chosen in the function definition. Typically functions use all-lower-
case names.
The cmake_language(CALL ...) command can also be used to invoke the
function.
Arguments
When the function is invoked, the recorded <commands> are first modi-
fied by replacing formal parameters (${arg1}, ) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
ARGC variable which will be set to the number of arguments passed into
the function as well as ARGV0, ARGV1, ARGV2, which will have the ac-
tual values of the arguments passed in. This facilitates creating
functions with optional arguments.
Furthermore, ARGV holds the list of all arguments given to the function
and ARGN holds the list of arguments past the last expected argument.
Referencing to ARGV# arguments beyond ARGC have undefined behavior.
Checking that ARGC is greater than # is the only way to ensure that
ARGV# was passed to the function as an extra argument.
get_cmake_property
Get a global property of the CMake instance.
get_cmake_property(<var> <property>)
Gets a global property from the CMake instance. The value of the
<property> is stored in the variable <var>. If the property is not
found, <var> will be set to NOTFOUND. See the cmake-properties(7) man-
ual for available properties.
See also the get_property() command GLOBAL option.
In addition to global properties, this command (for historical reasons)
also supports the VARIABLES and MACROS directory properties. It also
supports a special COMPONENTS global property that lists the components
given to the install() command.
get_directory_property
Get a property of DIRECTORY scope.
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Stores a property of directory scope in the named <variable>. The DI-
RECTORY argument specifies another directory from which to retrieve the
property value instead of the current directory. The specified direc-
tory must have already been traversed by CMake.
If the property is not defined for the nominated directory scope, an
empty string is returned. In the case of INHERITED properties, if the
property is not found for the nominated directory scope, the search
will chain to a parent scope as described for the define_property()
command.
get_directory_property(<variable> [DIRECTORY <dir>]
DEFINITION <var-name>)
Get a variable definition from a directory. This form is useful to get
a variable definition from another directory.
See also the more general get_property() command.
get_filename_component
Get a specific component of a full filename.
get_filename_component(<var> <FileName> <mode> [CACHE])
Sets <var> to a component of <FileName>, where <mode> is one of:
DIRECTORY = Directory without file name
NAME = File name without directory
EXT = File name longest extension (.b.c from d/a.b.c)
NAME_WE = File name without directory or longest extension
LAST_EXT = File name last extension (.c from d/a.b.c)
NAME_WLE = File name without directory or last extension
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
Sets <var> to the absolute path of <FileName>, where <mode> is one of:
ABSOLUTE = Full path to file
REALPATH = Full path to existing file with symlinks resolved
If the provided <FileName> is a relative path, it is evaluated relative
to the given base directory <dir>. If no base directory is provided,
the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
The program in <FileName> will be found in the system search path or
left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
command-line arguments present in the <FileName> string are split from
the program name and stored in <arg_var>. This is used to separate a
program name from its arguments in a command line string.
get_property
Get a property.
get_property(<variable>
<GLOBAL |
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
[DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
VARIABLE >
PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
Gets one property from one object in a scope.
The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the prop-
erty. It must be one of the following:
GLOBAL Scope is unique and does not accept a name.
DIRECTORY
Scope defaults to the current directory but another directory
(already processed by CMake) may be named by the full or rela-
tive path <dir>. See also the get_directory_property() command.
TARGET Scope mutiga)
foreach(num IN ZIP_LISTS English Bahasa)
message(STATUS "num_0=${num_0}, num_1=${num_1}") endfore-
ach()
foreach(en ba IN ZIP_LISTS English Bahasa)
message(STATUS "en=${en}, ba=${ba}") endforeach()
yields
-- num_0=one, num_1=satu
-- num_0=two, num_1=dua
-- num_0=three, num_1=tiga
-- num_0=four, num_1=
-- en=one, ba=satu
-- en=two, ba=dua
-- en=three, ba=tiga
-- en=four, ba=
function
Start recording a function for later invocation as a command.
function(<name> [<arg1> ...])
<commands>
endfunction()
Defines a function named <name> that takes arguments named <arg1>,
The <commands> in the function definition are recorded; they are not
executed until the function is invoked.
Per legacy, the endfunction() command admits an optional <name> argu-
ment. If used, it must be a verbatim repeat of the argument of the
opening function command.
A function opens a new scope: see set(var PARENT_SCOPE) for details.
See the cmake_policy() command documentation for the behavior of poli-
cies inside functions.
See the macro() command documentation for differences between CMake
functions and macros.
Invocation
The function invocation is case-insensitive. A function defined as
function(foo)
<commands>
endfunction()
can be invoked through any of
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the case
chosen in the function definition. Typically functions use all-lower-
case names.
The cmake_language(CALL ...) command can also be used to invoke the
function.
Arguments
When the function is invoked, the recorded <commands> are first modi-
fied by replacing formal parameters (${arg1}, ) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
ARGC variable which will be set to the number of arguments passed into
the function as well as ARGV0, ARGV1, ARGV2, which will have the ac-
tual values of the arguments passed in. This facilitates creating
functions with optional arguments.
Furthermore, ARGV holds the list of all arguments given to the function
and ARGN holds the list of arguments past the last expected argument.
Referencing to ARGV# arguments beyond ARGC have undefined behavior.
Checking that ARGC is greater than # is the only way to ensure that
ARGV# was passed to the function as an extra argument.
get_cmake_property
Get a global property of the CMake instance.
get_cmake_property(<var> <property>)
Gets a global property from the CMake instance. The value of the
<property> is stored in the variable <var>. If the property is not
found, <var> will be set to NOTFOUND. See the cmake-properties(7) man-
ual for available properties.
See also the get_property() command GLOBAL option.
In addition to global properties, this command (for historical reasons)
also supports the VARIABLES and MACROS directory properties. It also
supports a special COMPONENTS global property that lists the components
given to the install() command.
get_directory_property
Get a property of DIRECTORY scope.
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Stores a property of directory scope in the named <variable>. The DI-
RECTORY argument specifies another directory from which to retrieve the
property value instead of the current directory. The specified direc-
tory must have already been traversed by CMake.
If the property is not defined for the nominated directory scope, an
empty string is returned. In the case of INHERITED properties, if the
property is not found for the nominated directory scope, the search
will chain to a parent scope as described for the define_property()
command.
get_directory_property(<variable> [DIRECTORY <dir>]
DEFINITION <var-name>)
Get a variable definition from a directory. This form is useful to get
a variable definition from another directory.
See also the more general get_property() command.
get_filename_component
Get a specific component of a full filename.
get_filename_component(<var> <FileName> <mode> [CACHE])
Sets <var> to a component of <FileName>, where <mode> is one of:
DIRECTORY = Directory without file name
NAME = File name without directory
EXT = File name longest extension (.b.c from d/a.b.c)
NAME_WE = File name without directory or longest extension
LAST_EXT = File name last extension (.c from d/a.b.c)
NAME_WLE = File name without directory or last extension
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
Sets <var> to the absolute path of <FileName>, where <mode> is one of:
ABSOLUTE = Full path to file
REALPATH = Full path to existing file with symlinks resolved
If the provided <FileName> is a relative path, it is evaluated relative
to the given base directory <dir>. If no base directory is provided,
the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
The program in <FileName> will be found in the system search path or
left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
command-line arguments present in the <FileName> string are split from
the program name and stored in <arg_var>. This is used to separate a
program name from its arguments in a command line string.
get_property
Get a property.
get_property(<variable>
<GLOBAL |
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
[DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
VARIABLE >
PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
Gets one property from one object in a scope.
The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the prop-
erty. It must be one of the following:
GLOBAL Scope is unique and does not accept a name.
DIRECTORY
Scope defaults to the current directory but another directory
(already processed by CMake) may be named by the full or rela-
tive path <dir>. See also the get_directory_property() command.
TARGET Scope mutiga)
foreach(num IN ZIP_LISTS English Bahasa)
message(STATUS "num_0=${num_0}, num_1=${num_1}") endfore-
ach()
foreach(en ba IN ZIP_LISTS English Bahasa)
message(STATUS "en=${en}, ba=${ba}") endforeach()
yields
-- num_0=one, num_1=satu
-- num_0=two, num_1=dua
-- num_0=three, num_1=tiga
-- num_0=four, num_1=
-- en=one, ba=satu
-- en=two, ba=dua
-- en=three, ba=tiga
-- en=four, ba=
function
Start recording a function for later invocation as a command.
function(<name> [<arg1> ...])
<commands>
endfunction()
Defines a function named <name> that takes arguments named <arg1>,
The <commands> in the function definition are recorded; they are not
executed until the function is invoked.
Per legacy, the endfunction() command admits an optional <name> argu-
ment. If used, it must be a verbatim repeat of the argument of the
opening function command.
A function opens a new scope: see set(var PARENT_SCOPE) for details.
See the cmake_policy() command documentation for the behavior of poli-
cies inside functions.
See the macro() command documentation for differences between CMake
functions and macros.
Invocation
The function invocation is case-insensitive. A function defined as
function(foo)
<commands>
endfunction()
can be invoked through any of
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the case
chosen in the function definition. Typically functions use all-lower-
case names.
The cmake_language(CALL ...) command can also be used to invoke the
function.
Arguments
When the function is invoked, the recorded <commands> are first modi-
fied by replacing formal parameters (${arg1}, ) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
ARGC variable which will be set to the number of arguments passed into
the function as well as ARGV0, ARGV1, ARGV2, which will have the ac-
tual values of the arguments passed in. This facilitates creating
functions with optional arguments.
Furthermore, ARGV holds the list of all arguments given to the function
and ARGN holds the list of arguments past the last expected argument.
Referencing to ARGV# arguments beyond ARGC have undefined behavior.
Checking that ARGC is greater than # is the only way to ensure that
ARGV# was passed to the function as an extra argument.
get_cmake_property
Get a global property of the CMake instance.
get_cmake_property(<var> <property>)
Gets a global property from the CMake instance. The value of the
<property> is stored in the variable <var>. If the property is not
found, <var> will be set to NOTFOUND. See the cmake-properties(7) man-
ual for available properties.
See also the get_property() command GLOBAL option.
In addition to global properties, this command (for historical reasons)
also supports the VARIABLES and MACROS directory properties. It also
supports a special COMPONENTS global property that lists the components
given to the install() command.
get_directory_property
Get a property of DIRECTORY scope.
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Stores a property of directory scope in the named <variable>. The DI-
RECTORY argument specifies another directory from which to retrieve the
property value instead of the current directory. The specified direc-
tory must have already been traversed by CMake.
If the property is not defined for the nominated directory scope, an
empty string is returned. In the case of INHERITED properties, if the
property is not found for the nominated directory scope, the search
will chain to a parent scope as described for the define_property()
command.
get_directory_property(<variable> [DIRECTORY <dir>]
DEFINITION <var-name>)
Get a variable definition from a directory. This form is useful to get
a variable definition from another directory.
See also the more general get_property() command.
get_filename_component
Get a specific component of a full filename.
get_filename_component(<var> <FileName> <mode> [CACHE])
Sets <var> to a component of <FileName>, where <mode> is one of:
DIRECTORY = Directory without file name
NAME = File name without directory
EXT = File name longest extension (.b.c from d/a.b.c)
NAME_WE = File name without directory or longest extension
LAST_EXT = File name last extension (.c from d/a.b.c)
NAME_WLE = File name without directory or last extension
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
Sets <var> to the absolute path of <FileName>, where <mode> is one of:
ABSOLUTE = Full path to file
REALPATH = Full path to existing file with symlinks resolved
If the provided <FileName> is a relative path, it is evaluated relative
to the given base directory <dir>. If no base directory is provided,
the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
The program in <FileName> will be found in the system search path or
left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
command-line arguments present in the <FileName> string are split from
the program name and stored in <arg_var>. This is used to separate a
program name from its arguments in a command line string.
get_property
Get a property.
get_property(<variable>
<GLOBAL |
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
[DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
VARIABLE >
PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
Gets one property from one object in a scope.
The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the prop-
erty. It must be one of the following:
GLOBAL Scope is unique and does not accept a name.
DIRECTORY
Scope defaults to the current directory but another directory
(already processed by CMake) may be named by the full or rela-
tive path <dir>. See also the get_directory_property() command.
TARGET Scope mutiga)
foreach(num IN ZIP_LISTS English Bahasa)
message(STATUS "num_0=${num_0}, num_1=${num_1}") endfore-
ach()
foreach(en ba IN ZIP_LISTS English Bahasa)
message(STATUS "en=${en}, ba=${ba}") endforeach()
yields
-- num_0=one, num_1=satu
-- num_0=two, num_1=dua
-- num_0=three, num_1=tiga
-- num_0=four, num_1=
-- en=one, ba=satu
-- en=two, ba=dua
-- en=three, ba=tiga
-- en=four, ba=
function
Start recording a function for later invocation as a command.
function(<name> [<arg1> ...])
<commands>
endfunction()
Defines a function named <name> that takes arguments named <arg1>,
The <commands> in the function definition are recorded; they are not
executed until the function is invoked.
Per legacy, the endfunction() command admits an optional <name> argu-
ment. If used, it must be a verbatim repeat of the argument of the
opening function command.
A function opens a new scope: see set(var PARENT_SCOPE) for details.
See the cmake_policy() command documentation for the behavior of poli-
cies inside functions.
See the macro() command documentation for differences between CMake
functions and macros.
Invocation
The function invocation is case-insensitive. A function defined as
function(foo)
<commands>
endfunction()
can be invoked through any of
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the case
chosen in the function definition. Typically functions use all-lower-
case names.
The cmake_language(CALL ...) command can also be used to invoke the
function.
Arguments
When the function is invoked, the recorded <commands> are first modi-
fied by replacing formal parameters (${arg1}, ) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
ARGC variable which will be set to the number of arguments passed into
the function as well as ARGV0, ARGV1, ARGV2, which will have the ac-
tual values of the arguments passed in. This facilitates creating
functions with optional arguments.
Furthermore, ARGV holds the list of all arguments given to the function
and ARGN holds the list of arguments past the last expected argument.
Referencing to ARGV# arguments beyond ARGC have undefined behavior.
Checking that ARGC is greater than # is the only way to ensure that
ARGV# was passed to the function as an extra argument.
get_cmake_property
Get a global property of the CMake instance.
get_cmake_property(<var> <property>)
Gets a global property from the CMake instance. The value of the
<property> is stored in the variable <var>. If the property is not
found, <var> will be set to NOTFOUND. See the cmake-properties(7) man-
ual for available properties.
See also the get_property() command GLOBAL option.
In addition to global properties, this command (for historical reasons)
also supports the VARIABLES and MACROS directory properties. It also
supports a special COMPONENTS global property that lists the components
given to the install() command.
get_directory_property
Get a property of DIRECTORY scope.
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Stores a property of directory scope in the named <variable>. The DI-
RECTORY argument specifies another directory from which to retrieve the
property value instead of the current directory. The specified direc-
tory must have already been traversed by CMake.
If the property is not defined for the nominated directory scope, an
empty string is returned. In the case of INHERITED properties, if the
property is not found for the nominated directory scope, the search
will chain to a parent scope as described for the define_property()
command.
get_directory_property(<variable> [DIRECTORY <dir>]
DEFINITION <var-name>)
Get a variable definition from a directory. This form is useful to get
a variable definition from another directory.
See also the more general get_property() command.
get_filename_component
Get a specific component of a full filename.
get_filename_component(<var> <FileName> <mode> [CACHE])
Sets <var> to a component of <FileName>, where <mode> is one of:
DIRECTORY = Directory without file name
NAME = File name without directory
EXT = File name longest extension (.b.c from d/a.b.c)
NAME_WE = File name without directory or longest extension
LAST_EXT = File name last extension (.c from d/a.b.c)
NAME_WLE = File name without directory or last extension
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
Sets <var> to the absolute path of <FileName>, where <mode> is one of:
ABSOLUTE = Full path to file
REALPATH = Full path to existing file with symlinks resolved
If the provided <FileName> is a relative path, it is evaluated relative
to the given base directory <dir>. If no base directory is provided,
the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
The program in <FileName> will be found in the system search path or
left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
command-line arguments present in the <FileName> string are split from
the program name and stored in <arg_var>. This is used to separate a
program name from its arguments in a command line string.
get_property
Get a property.
get_property(<variable>
<GLOBAL |
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
[DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
VARIABLE >
PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
Gets one property from one object in a scope.
The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the prop-
erty. It must be one of the following:
GLOBAL Scope is unique and does not accept a name.
DIRECTORY
Scope defaults to the current directory but another directory
(already processed by CMake) may be named by the full or rela-
tive path <dir>. See also the get_directory_property() command.
TARGET Scope mutiga)
foreach(num IN ZIP_LISTS English Bahasa)
message(STATUS "num_0=${num_0}, num_1=${num_1}") endfore-
ach()
foreach(en ba IN ZIP_LISTS English Bahasa)
message(STATUS "en=${en}, ba=${ba}") endforeach()
yields
-- num_0=one, num_1=satu
-- num_0=two, num_1=dua
-- num_0=three, num_1=tiga
-- num_0=four, num_1=
-- en=one, ba=satu
-- en=two, ba=dua
-- en=three, ba=tiga
-- en=four, ba=
function
Start recording a function for later invocation as a command.
function(<name> [<arg1> ...])
<commands>
endfunction()
Defines a function named <name> that takes arguments named <arg1>,
The <commands> in the function definition are recorded; they are not
executed until the function is invoked.
Per legacy, the endfunction() command admits an optional <name> argu-
ment. If used, it must be a verbatim repeat of the argument of the
opening function command.
A function opens a new scope: see set(var PARENT_SCOPE) for details.
See the cmake_policy() command documentation for the behavior of poli-
cies inside functions.
See the macro() command documentation for differences between CMake
functions and macros.
Invocation
The function invocation is case-insensitive. A function defined as
function(foo)
<commands>
endfunction()
can be invoked through any of
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the case
chosen in the function definition. Typically functions use all-lower-
case names.
The cmake_language(CALL ...) command can also be used to invoke the
function.
Arguments
When the function is invoked, the recorded <commands> are first modi-
fied by replacing formal parameters (${arg1}, ) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
ARGC variable which will be set to the number of arguments passed into
the function as well as ARGV0, ARGV1, ARGV2, which will have the ac-
tual values of the arguments passed in. This facilitates creating
functions with optional arguments.
Furthermore, ARGV holds the list of all arguments given to the function
and ARGN holds the list of arguments past the last expected argument.
Referencing to ARGV# arguments beyond ARGC have undefined behavior.
Checking that ARGC is greater than # is the only way to ensure that
ARGV# was passed to the function as an extra argument.
get_cmake_property
Get a global property of the CMake instance.
get_cmake_property(<var> <property>)
Gets a global property from the CMake instance. The value of the
<property> is stored in the variable <var>. If the property is not
found, <var> will be set to NOTFOUND. See the cmake-properties(7) man-
ual for available properties.
See also the get_property() command GLOBAL option.
In addition to global properties, this command (for historical reasons)
also supports the VARIABLES and MACROS directory properties. It also
supports a special COMPONENTS global property that lists the components
given to the install() command.
get_directory_property
Get a property of DIRECTORY scope.
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Stores a property of directory scope in the named <variable>. The DI-
RECTORY argument specifies another directory from which to retrieve the
property value instead of the current directory. The specified direc-
tory must have already been traversed by CMake.
If the property is not defined for the nominated directory scope, an
empty string is returned. In the case of INHERITED properties, if the
property is not found for the nominated directory scope, the search
will chain to a parent scope as described for the define_property()
command.
get_directory_property(<variable> [DIRECTORY <dir>]
DEFINITION <var-name>)
Get a variable definition from a directory. This form is useful to get
a variable definition from another directory.
See also the more general get_property() command.
get_filename_component
Get a specific component of a full filename.
get_filename_component(<var> <FileName> <mode> [CACHE])
Sets <var> to a component of <FileName>, where <mode> is one of:
DIRECTORY = Directory without file name
NAME = File name without directory
EXT = File name longest extension (.b.c from d/a.b.c)
NAME_WE = File name without directory or longest extension
LAST_EXT = File name last extension (.c from d/a.b.c)
NAME_WLE = File name without directory or last extension
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
Sets <var> to the absolute path of <FileName>, where <mode> is one of:
ABSOLUTE = Full path to file
REALPATH = Full path to existing file with symlinks resolved
If the provided <FileName> is a relative path, it is evaluated relative
to the given base directory <dir>. If no base directory is provided,
the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
The program in <FileName> will be found in the system search path or
left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
command-line arguments present in the <FileName> string are split from
the program name and stored in <arg_var>. This is used to separate a
program name from its arguments in a command line string.
get_property
Get a property.
get_property(<variable>
<GLOBAL |
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
[DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
VARIABLE >
PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
Gets one property from one object in a scope.
The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the prop-
erty. It must be one of the following:
GLOBAL Scope is unique and does not accept a name.
DIRECTORY
Scope defaults to the current directory but another directory
(already processed by CMake) may be named by the full or rela-
tive path <dir>. See also the get_directory_property() command.
TARGET Scope mutiga)
foreach(num IN ZIP_LISTS English Bahasa)
message(STATUS "num_0=${num_0}, num_1=${num_1}") endfore-
ach()
foreach(en ba IN ZIP_LISTS English Bahasa)
message(STATUS "en=${en}, ba=${ba}") endforeach()
yields
-- num_0=one, num_1=satu
-- num_0=two, num_1=dua
-- num_0=three, num_1=tiga
-- num_0=four, num_1=
-- en=one, ba=satu
-- en=two, ba=dua
-- en=three, ba=tiga
-- en=four, ba=
function
Start recording a function for later invocation as a command.
function(<name> [<arg1> ...])
<commands>
endfunction()
Defines a function named <name> that takes arguments named <arg1>,
The <commands> in the function definition are recorded; they are not
executed until the function is invoked.
Per legacy, the endfunction() command admits an optional <name> argu-
ment. If used, it must be a verbatim repeat of the argument of the
opening function command.
A function opens a new scope: see set(var PARENT_SCOPE) for details.
See the cmake_policy() command documentation for the behavior of poli-
cies inside functions.
See the macro() command documentation for differences between CMake
functions and macros.
Invocation
The function invocation is case-insensitive. A function defined as
function(foo)
<commands>
endfunction()
can be invoked through any of
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the case
chosen in the function definition. Typically functions use all-lower-
case names.
The cmake_language(CALL ...) command can also be used to invoke the
function.
Arguments
When the function is invoked, the recorded <commands> are first modi-
fied by replacing formal parameters (${arg1}, ) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
ARGC variable which will be set to the number of arguments passed into
the function as well as ARGV0, ARGV1, ARGV2, which will have the ac-
tual values of the arguments passed in. This facilitates creating
functions with optional arguments.
Furthermore, ARGV holds the list of all arguments given to the function
and ARGN holds the list of arguments past the last expected argument.
Referencing to ARGV# arguments beyond ARGC have undefined behavior.
Checking that ARGC is greater than # is the only way to ensure that
ARGV# was passed to the function as an extra argument.
get_cmake_property
Get a global property of the CMake instance.
get_cmake_property(<var> <property>)
Gets a global property from the CMake instance. The value of the
<property> is stored in the variable <var>. If the property is not
found, <var> will be set to NOTFOUND. See the cmake-properties(7) man-
ual for available properties.
See also the get_property() command GLOBAL option.
In addition to global properties, this command (for historical reasons)
also supports the VARIABLES and MACROS directory properties. It also
supports a special COMPONENTS global property that lists the components
given to the install() command.
get_directory_property
Get a property of DIRECTORY scope.
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Stores a property of directory scope in the named <variable>. The DI-
RECTORY argument specifies another directory from which to retrieve the
property value instead of the current directory. The specified direc-
tory must have already been traversed by CMake.
If the property is not defined for the nominated directory scope, an
empty string is returned. In the case of INHERITED properties, if the
property is not found for the nominated directory scope, the search
will chain to a parent scope as described for the define_property()
command.
get_directory_property(<variable> [DIRECTORY <dir>]
DEFINITION <var-name>)
Get a variable definition from a directory. This form is useful to get
a variable definition from another directory.
See also the more general get_property() command.
get_filename_component
Get a specific component of a full filename.
get_filename_component(<var> <FileName> <mode> [CACHE])
Sets <var> to a component of <FileName>, where <mode> is one of:
DIRECTORY = Directory without file name
NAME = File name without directory
EXT = File name longest extension (.b.c from d/a.b.c)
NAME_WE = File name without directory or longest extension
LAST_EXT = File name last extension (.c from d/a.b.c)
NAME_WLE = File name without directory or last extension
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
Sets <var> to the absolute path of <FileName>, where <mode> is one of:
ABSOLUTE = Full path to file
REALPATH = Full path to existing file with symlinks resolved
If the provided <FileName> is a relative path, it is evaluated relative
to the given base directory <dir>. If no base directory is provided,
the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
The program in <FileName> will be found in the system search path or
left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
command-line arguments present in the <FileName> string are split from
the program name and stored in <arg_var>. This is used to separate a
program name from its arguments in a command line string.
get_property
Get a property.
get_property(<variable>
<GLOBAL |
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
[DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
VARIABLE >
PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
Gets one property from one object in a scope.
The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the prop-
erty. It must be one of the following:
GLOBAL Scope is unique and does not accept a name.
DIRECTORY
Scope defaults to the current directory but another directory
(already processed by CMake) may be named by the full or rela-
tive path <dir>. See also the get_directory_property() command.
TARGET Scope mutiga)
foreach(num IN ZIP_LISTS English Bahasa)
message(STATUS "num_0=${num_0}, num_1=${num_1}") endfore-
ach()
foreach(en ba IN ZIP_LISTS English Bahasa)
message(STATUS "en=${en}, ba=${ba}") endforeach()
yields
-- num_0=one, num_1=satu
-- num_0=two, num_1=dua
-- num_0=three, num_1=tiga
-- num_0=four, num_1=
-- en=one, ba=satu
-- en=two, ba=dua
-- en=three, ba=tiga
-- en=four, ba=
function
Start recording a function for later invocation as a command.
function(<name> [<arg1> ...])
<commands>
endfunction()
Defines a function named <name> that takes arguments named <arg1>,
The <commands> in the function definition are recorded; they are not
executed until the function is invoked.
Per legacy, the endfunction() command admits an optional <name> argu-
ment. If used, it must be a verbatim repeat of the argument of the
opening function command.
A function opens a new scope: see set(var PARENT_SCOPE) for details.
See the cmake_policy() command documentation for the behavior of poli-
cies inside functions.
See the macro() command documentation for differences between CMake
functions and macros.
Invocation
The function invocation is case-insensitive. A function defined as
function(foo)
<commands>
endfunction()
can be invoked through any of
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the case
chosen in the function definition. Typically functions use all-lower-
case names.
The cmake_language(CALL ...) command can also be used to invoke the
function.
Arguments
When the function is invoked, the recorded <commands> are first modi-
fied by replacing formal parameters (${arg1}, ) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
ARGC variable which will be set to the number of arguments passed into
the function as well as ARGV0, ARGV1, ARGV2, which will have the ac-
tual values of the arguments passed in. This facilitates creating
functions with optional arguments.
Furthermore, ARGV holds the list of all arguments given to the function
and ARGN holds the list of arguments past the last expected argument.
Referencing to ARGV# arguments beyond ARGC have undefined behavior.
Checking that ARGC is greater than # is the only way to ensure that
ARGV# was passed to the function as an extra argument.
get_cmake_property
Get a global property of the CMake instance.
get_cmake_property(<var> <property>)
Gets a global property from the CMake instance. The value of the
<property> is stored in the variable <var>. If the property is not
found, <var> will be set to NOTFOUND. See the cmake-properties(7) man-
ual for available properties.
See also the get_property() command GLOBAL option.
In addition to global properties, this command (for historical reasons)
also supports the VARIABLES and MACROS directory properties. It also
supports a special COMPONENTS global property that lists the components
given to the install() command.
get_directory_property
Get a property of DIRECTORY scope.
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Stores a property of directory scope in the named <variable>. The DI-
RECTORY argument specifies another directory from which to retrieve the
property value instead of the current directory. The specified direc-
tory must have already been traversed by CMake.
If the property is not defined for the nominated directory scope, an
empty string is returned. In the case of INHERITED properties, if the
property is not found for the nominated directory scope, the search
will chain to a parent scope as described for the define_property()
command.
get_directory_property(<variable> [DIRECTORY <dir>]
DEFINITION <var-name>)
Get a variable definition from a directory. This form is useful to get
a variable definition from another directory.
See also the more general get_property() command.
get_filename_component
Get a specific component of a full filename.
get_filename_component(<var> <FileName> <mode> [CACHE])
Sets <var> to a component of <FileName>, where <mode> is one of:
DIRECTORY = Directory without file name
NAME = File name without directory
EXT = File name longest extension (.b.c from d/a.b.c)
NAME_WE = File name without directory or longest extension
LAST_EXT = File name last extension (.c from d/a.b.c)
NAME_WLE = File name without directory or last extension
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
Sets <var> to the absolute path of <FileName>, where <mode> is one of:
ABSOLUTE = Full path to file
REALPATH = Full path to existing file with symlinks resolved
If the provided <FileName> is a relative path, it is evaluated relative
to the given base directory <dir>. If no base directory is provided,
the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
The program in <FileName> will be found in the system search path or
left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
command-line arguments present in the <FileName> string are split from
the program name and stored in <arg_var>. This is used to separate a
program name from its arguments in a command line string.
get_property
Get a property.
get_property(<variable>
<GLOBAL |
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
[DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
VARIABLE >
PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
Gets one property from one object in a scope.
The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the prop-
erty. It must be one of the following:
GLOBAL Scope is unique and does not accept a name.
DIRECTORY
Scope defaults to the current directory but another directory
(already processed by CMake) may be named by the full or rela-
tive path <dir>. See also the get_directory_property() command.
TARGET Scope mutiga)
foreach(num IN ZIP_LISTS English Bahasa)
message(STATUS "num_0=${num_0}, num_1=${num_1}") endfore-
ach()
foreach(en ba IN ZIP_LISTS English Bahasa)
message(STATUS "en=${en}, ba=${ba}") endforeach()
yields
-- num_0=one, num_1=satu
-- num_0=two, num_1=dua
-- num_0=three, num_1=tiga
-- num_0=four, num_1=
-- en=one, ba=satu
-- en=two, ba=dua
-- en=three, ba=tiga
-- en=four, ba=
function
Start recording a function for later invocation as a command.
function(<name> [<arg1> ...])
<commands>
endfunction()
Defines a function named <name> that takes arguments named <arg1>,
The <commands> in the function definition are recorded; they are not
executed until the function is invoked.
Per legacy, the endfunction() command admits an optional <name> argu-
ment. If used, it must be a verbatim repeat of the argument of the
opening function command.
A function opens a new scope: see set(var PARENT_SCOPE) for details.
See the cmake_policy() command documentation for the behavior of poli-
cies inside functions.
See the macro() command documentation for differences between CMake
functions and macros.
Invocation
The function invocation is case-insensitive. A function defined as
function(foo)
<commands>
endfunction()
can be invoked through any of
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the case
chosen in the function definition. Typically functions use all-lower-
case names.
The cmake_language(CALL ...) command can also be used to invoke the
function.
Arguments
When the function is invoked, the recorded <commands> are first modi-
fied by replacing formal parameters (${arg1}, ) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
ARGC variable which will be set to the number of arguments passed into
the function as well as ARGV0, ARGV1, ARGV2, which will have the ac-
tual values of the arguments passed in. This facilitates creating
functions with optional arguments.
Furthermore, ARGV holds the list of all arguments given to the function
and ARGN holds the list of arguments past the last expected argument.
Referencing to ARGV# arguments beyond ARGC have undefined behavior.
Checking that ARGC is greater than # is the only way to ensure that
ARGV# was passed to the function as an extra argument.
get_cmake_property
Get a global property of the CMake instance.
get_cmake_property(<var> <property>)
Gets a global property from the CMake instance. The value of the
<property> is stored in the variable <var>. If the property is not
found, <var> will be set to NOTFOUND. See the cmake-properties(7) man-
ual for available properties.
See also the get_property() command GLOBAL option.
In addition to global properties, this command (for historical reasons)
also supports the VARIABLES and MACROS directory properties. It also
supports a special COMPONENTS global property that lists the components
given to the install() command.
get_directory_property
Get a property of DIRECTORY scope.
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Stores a property of directory scope in the named <variable>. The DI-
RECTORY argument specifies another directory from which to retrieve the
property value instead of the current directory. The specified direc-
tory must have already been traversed by CMake.
If the property is not defined for the nominated directory scope, an
empty string is returned. In the case of INHERITED properties, if the
property is not found for the nominated directory scope, the search
will chain to a parent scope as described for the define_property()
command.
get_directory_property(<variable> [DIRECTORY <dir>]
DEFINITION <var-name>)
Get a variable definition from a directory. This form is useful to get
a variable definition from another directory.
See also the more general get_property() command.
get_filename_component
Get a specific component of a full filename.
get_filename_component(<var> <FileName> <mode> [CACHE])
Sets <var> to a component of <FileName>, where <mode> is one of:
DIRECTORY = Directory without file name
NAME = File name without directory
EXT = File name longest extension (.b.c from d/a.b.c)
NAME_WE = File name without directory or longest extension
LAST_EXT = File name last extension (.c from d/a.b.c)
NAME_WLE = File name without directory or last extension
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
Sets <var> to the absolute path of <FileName>, where <mode> is one of:
ABSOLUTE = Full path to file
REALPATH = Full path to existing file with symlinks resolved
If the provided <FileName> is a relative path, it is evaluated relative
to the given base directory <dir>. If no base directory is provided,
the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
Paths are returned with forward slashes and have no trailing slashes.
If the optional CACHE argument is specified, the result variable is
added to the cache.
get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
The program in <FileName> will be found in the system search path or
left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
command-line arguments present in the <FileName> string are split from
the program name and stored in <arg_var>. This is used to separate a
program name from its arguments in a command line string.
get_property
Get a property.
get_property(<variable>
<GLOBAL |
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
[DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
VARIABLE >
PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
Gets one property from one object in a scope.
The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the prop-
erty. It must be one of the following:
GLOBAL Scope is unique and does not accept a name.
DIRECTORY
Scope defaults to the current directory but another directory
(already processed by CMake) may be named by the full or rela-
tive path <dir>. See also the get_directory_property() command.
TARGET Scope mutiga)
foreach(num IN ZIP_LISTS English Bahasa)
message(STATUS "num_0=${num_0}, num_1=${num_1}") endfore-
ach()
foreach(en ba IN ZIP_LISTS English Bahasa)
message(STATUS "en=${en}, ba=${ba}") endforeac_expression>
for the match in the output. All <input> arguments are concate-
nated before matching.
The <replacement_expression> may refer to parenthesis-delimited
subexpressions of the match using \1, \2, , \9. Note that two
backslashes (\\1) are required in CMake code to get a backslash
through argument parsing.
Regex Specification
The following characters have special meaning in regular expressions:
^ Matches at beginning of input
$ Matches at end of input
. Matches any single character
\<char>
Matches the single character specified by <char>. Use this to
match special regex characters, e.g. \. for a literal . or \\
for a literal backslash \. Escaping a non-special character is
unnecessary but allowed, e.g. \a matches a.
[ ] Matches any character(s) inside the brackets
[^ ] Matches any character(s) not inside the brackets
- Inside brackets, specifies an inclusive range between characters
on either side e.g. [a-f] is [abcdef] To match a literal - using
brackets, make it the first or the last character e.g. [+*/-]
matches basic mathematical operators.
* Matches preceding pattern zero or more times
+ Matches preceding pattern one or more times
? Matches preceding pattern zero or once only
| Matches a pattern on either side of the |
() Saves a matched subexpression, which can be referenced in the
REGEX REPLACE operation. Additionally it is saved by all regular
expression-related commands, including e.g. if(MATCHES), in the
variables CMAKE_MATCH_<n> for <n> 0..9.
*, + and ? have higher precedence than concatenation. | has lower
precedence than concatenation. This means that the regular expression
^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
matches ab but not abd.
CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
to construct literal tabs, carriage returns, newlines, and backslashes
(respectively) to pass in a regex. For example:
o The quoted argument "[ \t\r\n]" specifies a regex that matches any
single whitespace character.
o The quoted argument "[/\\]" specifies a regex that matches a single
forward slash / or backslash \.
o The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
single word character in the C locale.
o The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
the exact string (a+b). Each \\ is parsed in a quoted argument as
just \, so the regex itself is actually \(\a\+\b\). This can alter-
natively be specified in a bracket argument without having to escape
the backslashes, e.g. [[\(\a\+\b\)]].
Manipulation
string(APPEND <string_variable> [<input>...])
Append all the <input> arguments to the string.
string(PREPEND <string_variable> [<input>...])
Prepend all the <input> arguments to the string.
string(CONCAT <output_variable> [<input>...])
Concatenate all the <input> arguments together and store the result in
the named <output_variable>.
string(JOIN <glue> <output_variable> [<input>...])
Join all the <input> arguments together using the <glue> string and
store the result in the named <output_variable>.
To join a lists elements, prefer to use the JOIN operator from the
list() command. This allows for the elements to have special charac-
ters like ; in them.
string(TOLOWER <string> <output_variable>)
Convert <string> to lower characters.
string(TOUPPER <string> <output_variable>)
Convert <string> to upper characters.
string(LENGTH <string> <output_variable>)
Store in an <output_variable> a given strings length in bytes. Note
that this means if <string> contains multi-byte characters, the result
stored in <output_variable> will not be the number of characters.
string(SUBSTRING <string> <begin> <length> <output_variable>)
Store in an <output_variable> a substring of a given <string>. If
<length> is -1 the remainder of the string starting at <begin> will be
returned. If <string> is shorter than <length> then the end of the
string is used instead.
Both <begin> and <length> are counted in bytes, so care must be exer-
cised if <string> could contain multi-byte characters.
NOTE:
CMake 3.1 and below reported an error if <length> pointed past the
end of <string>.
string(STRIP <string> <output_variable>)
Store in an <output_variable> a substring of a given <string> with
leading and trailing spaces removed.
string(GENEX_STRIP <string> <output_variable>)
Strip any generator expressions from the input <string> and store the
result in the <output_variable>.
string(REPEAT <string> <count> <output_variable>)
Produce the output string as the input <string> repeated <count> times.
Comparison
string(COMPARE LESS <string1> <string2> <output_variable>)
string(COMPARE GREATER <string1> <string2> <output_variable>)
string(COMPARE EQUAL <string1> <string2> <output_variable>)
string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
Compare the strings and store true or false in the <output_variable>.
Hashing
string(<HASH> <output_variable> <input>)
Compute a cryptographic hash of the <input> string. The supported
<HASH> algorithm names are:
MD5 Message-Digest Algorithm 5, RFC 1321.
SHA1 US Secure Hash Algorithm 1, RFC 3174.
SHA224 US Secure Hash Algorithms, RFC 4634.
SHA256 US Secure Hash Algorithms, RFC 4634.
SHA384 US Secure Hash Algorithms, RFC 4634.
SHA512 US Secure Hash Algorithms, RFC 4634.
SHA3_224
Keccak SHA-3.
SHA3_256
Keccak SHA-3.
SHA3_384
Keccak SHA-3.
SHA3_512
Keccak SHA-3.
Generation
string(ASCII <number> [<number> ...] <output_variable>)
Convert all numbers into corresponding ASCII characters.
string(HEX <string> <output_variable>)
Convert each byte in the input <string> to its hexadecimal representa-
tion and store the concatenated hex digits in the <output_variable>.
Letters in the output (a through f) are in lowercase.
string(CONFIGURE <string> <output_variable>
[@ONLY] [ESCAPE_QUOT_expression> for the match in the output.
All <input> arguments are concatenated before matching.
The <replacement_expression> may refer to parenthesis-delimited
subexpressions of the match using \1, \2, , \9. Note that
two backslashes (\\1) are required in CMake code to get a backslash
through argument parsing.
Regex Specification
The following characters have special meaning in regular expressions:
^ Matches at beginning of input
$ Matches at end of input
. Matches any single character
\<char>
Matches the single character specified by <char>. Use this to
match special regex characters, e.g. \. for a literal . or \\
for a literal backslash \. Escaping a non-special character is
unnecessary but allowed, e.g. \a matches a.
[ ] Matches any character(s) inside the brackets
[^ ] Matches any character(s) not inside the brackets
- Inside brackets, specifies an inclusive range between characters
on either side e.g. [a-f] is [abcdef] To match a literal - using
brackets, make it the first or the last character e.g. [+*/-]
matches basic mathematical operators.
* Matches preceding pattern zero or more times
+ Matches preceding pattern one or more times
? Matches preceding pattern zero or once only
| Matches a pattern on either side of the |
() Saves a matched subexpression, which can be referenced in the
REGEX REPLACE operation. Additionally it is saved by all regular
expression-related commands, including e.g. if(MATCHES), in the
variables CMAKE_MATCH_<n> for <n> 0..9.
*, + and ? have higher precedence than concatenation. | has lower
precedence than concatenation. This means that the regular expression
^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
matches ab but not abd.
CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
to construct literal tabs, carriage returns, newlines, and backslashes
(respectively) to pass in a regex. For example:
o The quoted argument "[ \t\r\n]" specifies a regex that matches any
single whitespace character.
o The quoted argument "[/\\]" specifies a regex that matches a single
forward slash / or backslash \.
o The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
single word character in the C locale.
o The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
the exact string (a+b). Each \\ is parsed in a quoted argument as
just \, so the regex itself is actually \(\a\+\b\). This can alter-
natively be specified in a bracket argument without having to escape
the backslashes, e.g. [[\(\a\+\b\)]].
Manipulation
string(APPEND <string_variable> [<input>...])
Append all the <input> arguments to the string.
string(PREPEND <string_variable> [<input>...])
Prepend all the <input> arguments to the string.
string(CONCAT <output_variable> [<input>...])
Concatenate all the <input> arguments together and store the result in
the named <output_variable>.
string(JOIN <glue> <output_variable> [<input>...])
Join all the <input> arguments together using the <glue> string and
store the result in the named <output_variable>.
To join a lists elements, prefer to use the JOIN operator from the
list() command. This allows for the elements to have special charac-
ters like ; in them.
string(TOLOWER <string> <output_variable>)
Convert <string> to lower characters.
string(TOUPPER <string> <output_variable>)
Convert <string> to upper characters.
string(LENGTH <string> <output_variable>)
Store in an <output_variable> a given strings length in bytes. Note
that this means if <string> contains multi-byte characters, the result
stored in <output_variable> will not be the number of characters.
string(SUBSTRING <string> <begin> <length> <output_variable>)
Store in an <output_variable> a substring of a given <string>. If
<length> is -1 the remainder of the string starting at <begin> will be
returned. If <string> is shorter than <length> then the end of the
string is used instead.
Both <begin> and <length> are counted in bytes, so care must be exer-
cised if <string> could contain multi-byte characters.
NOTE:
CMake 3.1 and below reported an error if <length> pointed past the
end of <string>.
string(STRIP <string> <output_variable>)
Store in an <output_variable> a substring of a given <string> with
leading and trailing spaces removed.
string(GENEX_STRIP <string> <output_variable>)
Strip any generator expressions from the input <string> and store the
result in the <output_variable>.
string(REPEAT <string> <count> <output_variable>)
Produce the output string as the input <string> repeated <count> times.
Comparison
string(COMPARE LESS <string1> <string2> <output_variable>)
string(COMPARE GREATER <string1> <string2> <output_variable>)
string(COMPARE EQUAL <string1> <string2> <output_variable>)
string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
Compare the strings and store true or false in the <output_variable>.
Hashing
string(<HASH> <output_variable> <input>)
Compute a cryptographic hash of the <input> string. The supported
<HASH> algorithm names are:
MD5 Message-Digest Algorithm 5, RFC 1321.
SHA1 US Secure Hash Algorithm 1, RFC 3174.
SHA224 US Secure Hash Algorithms, RFC 4634.
SHA256 US Secure Hash Algorithms, RFC 4634.
SHA384 US Secure Hash Algorithms, RFC 4634.
SHA512 US Secure Hash Algorithms, RFC 4634.
SHA3_224
Keccak SHA-3.
SHA3_256
Keccak SHA-3.
SHA3_384
Keccak SHA-3.
SHA3_512
Keccak SHA-3.
Generation
string(ASCII <number> [<number> ...] <output_variable>)
Convert all numbers into corresponding ASCII characters.
string(HEX <string> <output_variable>)
Convert each byte in the input <string> to its hexadecimal representa-
tion and store the concatenated hex digits in the <output_variable>.
Letters in the output (a through f) are in lowercase.
string(CONFIGURE <string> <output_variable>
[@ONLY] [ESCAPE_QUOT_expression> for the match in the output.
All <input> arguments are concatenated before matching.
The <replacement_expression> may refer to parenthesis-delimited
subexpressions of the match using \1, \2, , \9. Note that
two backslashes (\\1) are required in CMake code to get a backslash
through argument parsing.
Regex Specification
The following characters have special meaning in regular expressions:
^ Matches at beginning of input
$ Matches at end of input
. Matches any single character
\<char>
Matches the single character specified by <char>. Use this to
match special regex characters, e.g. \. for a literal . or \\
for a literal backslash \. Escaping a non-special character is
unnecessary but allowed, e.g. \a matches a.
[ ] Matches any character(s) inside the brackets
[^ ] Matches any character(s) not inside the brackets
- Inside brackets, specifies an inclusive range between characters
on either side e.g. [a-f] is [abcdef] To match a literal - using
brackets, make it the first or the last character e.g. [+*/-]
matches basic mathematical operators.
* Matches preceding pattern zero or more times
+ Matches preceding pattern one or more times
? Matches preceding pattern zero or once only
| Matches a pattern on either side of the |
() Saves a matched subexpression, which can be referenced in the
REGEX REPLACE operation. Additionally it is saved by all regular
expression-related commands, including e.g. if(MATCHES), in the
variables CMAKE_MATCH_<n> for <n> 0..9.
*, + and ? have higher precedence than concatenation. | has lower
precedence than concatenation. This means that the regular expression
^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
matches ab but not abd.
CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
to construct literal tabs, carriage returns, newlines, and backslashes
(respectively) to pass in a regex. For example:
o The quoted argument "[ \t\r\n]" specifies a regex that matches any
single whitespace character.
o The quoted argument "[/\\]" specifies a regex that matches a single
forward slash / or backslash \.
o The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
single word character in the C locale.
o The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
the exact string (a+b). Each \\ is parsed in a quoted argument as
just \, so the regex itself is actually \(\a\+\b\). This can alter-
natively be specified in a bracket argument without having to escape
the backslashes, e.g. [[\(\a\+\b\)]].
Manipulation
string(APPEND <string_variable> [<input>...])
Append all the <input> arguments to the string.
string(PREPEND <string_variable> [<input>...])
Prepend all the <input> arguments to the string.
string(CONCAT <output_variable> [<input>...])
Concatenate all the <input> arguments together and store the result in
the named <output_variable>.
string(JOIN <glue> <output_variable> [<input>...])
Join all the <input> arguments together using the <glue> string and
store the result in the named <output_variable>.
To join a lists elements, prefer to use the JOIN operator from the
list() command. This allows for the elements to have special charac-
ters like ; in them.
string(TOLOWER <string> <output_variable>)
Convert <string> to lower characters.
string(TOUPPER <string> <output_variable>)
Convert <string> to upper characters.
string(LENGTH <string> <output_variable>)
Store in an <output_variable> a given strings length in bytes. Note
that this means if <string> contains multi-byte characters, the result
stored in <output_variable> will not be the number of characters.
string(SUBSTRING <string> <begin> <length> <output_variable>)
Store in an <output_variable> a substring of a given <string>. If
<length> is -1 the remainder of the string starting at <begin> will be
returned. If <string> is shorter than <length> then the end of the
string is used instead.
Both <begin> and <length> are counted in bytes, so care must be exer-
cised if <string> could contain multi-byte characters.
NOTE:
CMake 3.1 and below reported an error if <length> pointed past the
end of <string>.
string(STRIP <string> <output_variable>)
Store in an <output_variable> a substring of a given <string> with
leading and trailing spaces removed.
string(GENEX_STRIP <string> <output_variable>)
Strip any generator expressions from the input <string> and store the
result in the <output_variable>.
string(REPEAT <string> <count> <output_variable>)
Produce the output string as the input <string> repeated <count> times.
Comparison
string(COMPARE LESS <string1> <string2> <output_variable>)
string(COMPARE GREATER <string1> <string2> <output_variable>)
string(COMPARE EQUAL <string1> <string2> <output_variable>)
string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
Compare the strings and store true or false in the <output_variable>.
Hashing
string(<HASH> <output_variable> <input>)
Compute a cryptographic hash of the <input> string. The supported
<HASH> algorithm names are:
MD5 Message-Digest Algorithm 5, RFC 1321.
SHA1 US Secure Hash Algorithm 1, RFC 3174.
SHA224 US Secure Hash Algorithms, RFC 4634.
SHA256 US Secure Hash Algorithms, RFC 4634.
SHA384 US Secure Hash Algorithms, RFC 4634.
SHA512 US Secure Hash Algorithms, RFC 4634.
SHA3_224
Keccak SHA-3.
SHA3_256
Keccak SHA-3.
SHA3_384
Keccak SHA-3.
SHA3_512
Keccak SHA-3.
Generation
string(ASCII <number> [<number> ...] <output_variable>)
Convert all numbers into corresponding ASCII characters.
string(HEX <string> <output_variable>)
Convert each byte in the input <string> to its hexadecimal representa-
tion and store the concatenated hex digits in the <output_variable>.
Letters in the output (a through f) are in lowercase.
string(CONFIGURE <string> <output_variable>
[@ONLY] [ESCAPE_QUOT_expression> for the match in the output.
All <input> arguments are concatenated before matching.
The <replacement_expression> may refer to parenthesis-delimited
subexpressions of the match using \1, \2, , \9. Note that
two backslashes (\\1) are required in CMake code to get a backslash
through argument parsing.
Regex Specification
The following characters have special meaning in regular expressions:
^ Matches at beginning of input
$ Matches at end of input
. Matches any single character
\<char>
Matches the single character specified by <char>. Use this to
match special regex characters, e.g. \. for a literal . or \\
for a literal backslash \. Escaping a non-special character is
unnecessary but allowed, e.g. \a matches a.
[ ] Matches any character(s) inside the brackets
[^ ] Matches any character(s) not inside the brackets
- Inside brackets, specifies an inclusive range between characters
on either side e.g. [a-f] is [abcdef] To match a literal - using
brackets, make it the first or the last character e.g. [+*/-]
matches basic mathematical operators.
* Matches preceding pattern zero or more times
+ Matches preceding pattern one or more times
? Matches preceding pattern zero or once only
| Matches a pattern on either side of the |
() Saves a matched subexpression, which can be referenced in the
REGEX REPLACE operation. Additionally it is saved by all regular
expression-related commands, including e.g. if(MATCHES), in the
variables CMAKE_MATCH_<n> for <n> 0..9.
*, + and ? have higher precedence than concatenation. | has lower
precedence than concatenation. This means that the regular expression
^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
matches ab but not abd.
CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
to construct literal tabs, carriage returns, newlines, and backslashes
(respectively) to pass in a regex. For example:
o The quoted argument "[ \t\r\n]" specifies a regex that matches any
single whitespace character.
o The quoted argument "[/\\]" specifies a regex that matches a single
forward slash / or backslash \.
o The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
single word character in the C locale.
o The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
the exact string (a+b). Each \\ is parsed in a quoted argument as
just \, so the regex itself is actually \(\a\+\b\). This can alter-
natively be specified in a bracket argument without having to escape
the backslashes, e.g. [[\(\a\+\b\)]].
Manipulation
string(APPEND <string_variable> [<input>...])
Append all the <input> arguments to the string.
string(PREPEND <string_variable> [<input>...])
Prepend all the <input> arguments to the string.
string(CONCAT <output_variable> [<input>...])
Concatenate all the <input> arguments together and store the result in
the named <output_variable>.
string(JOIN <glue> <output_variable> [<input>...])
Join all the <input> arguments together using the <glue> string and
store the result in the named <output_variable>.
To join a lists elements, prefer to use the JOIN operator from the
list() command. This allows for the elements to have special charac-
ters like ; in them.
string(TOLOWER <string> <output_variable>)
Convert <string> to lower characters.
string(TOUPPER <string> <output_variable>)
Convert <string> to upper characters.
string(LENGTH <string> <output_variable>)
Store in an <output_variable> a given strings length in bytes. Note
that this means if <string> contains multi-byte characters, the result
stored in <output_variable> will not be the number of characters.
string(SUBSTRING <string> <begin> <length> <output_variable>)
Store in an <output_variable> a substring of a given <string>. If
<length> is -1 the remainder of the string starting at <begin> will be
returned. If <string> is shorter than <length> then the end of the
string is used instead.
Both <begin> and <length> are counted in bytes, so care must be exer-
cised if <string> could contain multi-byte characters.
NOTE:
CMake 3.1 and below reported an error if <length> pointed past the
end of <string>.
string(STRIP <string> <output_variable>)
Store in an <output_variable> a substring of a given <string> with
leading and trailing spaces removed.
string(GENEX_STRIP <string> <output_variable>)
Strip any generator expressions from the input <string> and store the
result in the <output_variable>.
string(REPEAT <string> <count> <output_variable>)
Produce the output string as the input <string> repeated <count> times.
Comparison
string(COMPARE LESS <string1> <string2> <output_variable>)
string(COMPARE GREATER <string1> <string2> <output_variable>)
string(COMPARE EQUAL <string1> <string2> <output_variable>)
string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
Compare the strings and store true or false in the <output_variable>.
Hashing
string(<HASH> <output_variable> <input>)
Compute a cryptographic hash of the <input> string. The supported
<HASH> algorithm names are:
MD5 Message-Digest Algorithm 5, RFC 1321.
SHA1 US Secure Hash Algorithm 1, RFC 3174.
SHA224 US Secure Hash Algorithms, RFC 4634.
SHA256 US Secure Hash Algorithms, RFC 4634.
SHA384 US Secure Hash Algorithms, RFC 4634.
SHA512 US Secure Hash Algorithms, RFC 4634.
SHA3_224
Keccak SHA-3.
SHA3_256
Keccak SHA-3.
SHA3_384
Keccak SHA-3.
SHA3_512
Keccak SHA-3.
Generation
string(ASCII <number> [<number> ...] <output_variable>)
Convert all numbers into corresponding ASCII characters.
string(HEX <string> <output_variable>)
Convert each byte in the input <string> to its hexadecimal representa-
tion and store the concatenated hex digits in the <output_variable>.
Letters in the output (a through f) are in lowercase.
string(CONFIGURE <string> <output_variable>
[@ONLY] [ESCAPE_QUOT_expression> for the match in the output.
All <input> arguments are concatenated before matching.
The <replacement_expression> may refer to parenthesis-delimited
subexpressions of the match using \1, \2, , \9. Note that
two backslashes (\\1) are required in CMake code to get a backslash
through argument parsing.
Regex Specification
The following characters have special meaning in regular expressions:
^ Matches at beginning of input
$ Matches at end of input
. Matches any single character
\<char>
Matches the single character specified by <char>. Use this to
match special regex characters, e.g. \. for a literal . or \\
for a literal backslash \. Escaping a non-special character is
unnecessary but allowed, e.g. \a matches a.
[ ] Matches any character(s) inside the brackets
[^ ] Matches any character(s) not inside the brackets
- Inside brackets, specifies an inclusive range between characters
on either side e.g. [a-f] is [abcdef] To match a literal - using
brackets, make it the first or the last character e.g. [+*/-]
matches basic mathematical operators.
* Matches preceding pattern zero or more times
+ Matches preceding pattern one or more times
? Matches preceding pattern zero or once only
| Matches a pattern on either side of the |
() Saves a matched subexpression, which can be referenced in the
REGEX REPLACE operation. Additionally it is saved by all regular
expression-related commands, including e.g. if(MATCHES), in the
variables CMAKE_MATCH_<n> for <n> 0..9.
*, + and ? have higher precedence than concatenation. | has lower
precedence than concatenation. This means that the regular expression
^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
matches ab but not abd.
CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
to construct literal tabs, carriage returns, newlines, and backslashes
(respectively) to pass in a regex. For example:
o The quoted argument "[ \t\r\n]" specifies a regex that matches any
single whitespace character.
o The quoted argument "[/\\]" specifies a regex that matches a single
forward slash / or backslash \.
o The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
single word character in the C locale.
o The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
the exact string (a+b). Each \\ is parsed in a quoted argument as
just \, so the regex itself is actually \(\a\+\b\). This can alter-
natively be specified in a bracket argument without having to escape
the backslashes, e.g. [[\(\a\+\b\)]].
Manipulation
string(APPEND <string_variable> [<input>...])
Append all the <input> arguments to the string.
string(PREPEND <string_variable> [<input>...])
Prepend all the <input> arguments to the string.
string(CONCAT <output_variable> [<input>...])
Concatenate all the <input> arguments together and store the result in
the named <output_variable>.
string(JOIN <glue> <output_variable> [<input>...])
Join all the <input> arguments together using the <glue> string and
store the result in the named <output_variable>.
To join a lists elements, prefer to use the JOIN operator from the
list() command. This allows for the elements to have special charac-
ters like ; in them.
string(TOLOWER <string> <output_variable>)
Convert <string> to lower characters.
string(TOUPPER <string> <output_variable>)
Convert <string> to upper characters.
string(LENGTH <string> <output_variable>)
Store in an <output_variable> a given strings length in bytes. Note
that this means if <string> contains multi-byte characters, the result
stored in <output_variable> will not be the number of characters.
string(SUBSTRING <string> <begin> <length> <output_variable>)
Store in an <output_variable> a substring of a given <string>. If
<length> is -1 the remainder of the string starting at <begin> will be
returned. If <string> is shorter than <length> then the end of the
string is used instead.
Both <begin> and <length> are counted in bytes, so care must be exer-
cised if <string> could contain multi-byte characters.
NOTE:
CMake 3.1 and below reported an error if <length> pointed past the
end of <string>.
string(STRIP <string> <output_variable>)
Store in an <output_variable> a substring of a given <string> with
leading and trailing spaces removed.
string(GENEX_STRIP <string> <output_variable>)
Strip any generator expressions from the input <string> and store the
result in the <output_variable>.
string(REPEAT <string> <count> <output_variable>)
Produce the output string as the input <string> repeated <count> times.
Comparison
string(COMPARE LESS <string1> <string2> <output_variable>)
string(COMPARE GREATER <string1> <string2> <output_variable>)
string(COMPARE EQUAL <string1> <string2> <output_variable>)
string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
Compare the strings and store true or false in the <output_variable>.
Hashing
string(<HASH> <output_variable> <input>)
Compute a cryptographic hash of the <input> string. The supported
<HASH> algorithm names are:
MD5 Message-Digest Algorithm 5, RFC 1321.
SHA1 US Secure Hash Algorithm 1, RFC 3174.
SHA224 US Secure Hash Algorithms, RFC 4634.
SHA256 US Secure Hash Algorithms, RFC 4634.
SHA384 US Secure Hash Algorithms, RFC 4634.
SHA512 US Secure Hash Algorithms, RFC 4634.
SHA3_224
Keccak SHA-3.
SHA3_256
Keccak SHA-3.
SHA3_384
Keccak SHA-3.
SHA3_512
Keccak SHA-3.
Generation
string(ASCII <number> [<number> ...] <output_variable>)
Convert all numbers into corresponding ASCII characters.
string(HEX <string> <output_variable>)
Convert each byte in the input <string> to its hexadecimal representa-
tion and store the concatenated hex digits in the <output_variable>.
Letters in the output (a through f) are in lowercase.
string(CONFIGURE <string> <output_variable>
[@ONLY] [ESCAPE_QUOT_expression> for the match in the output.
All <input> arguments are concatenated before matching.
The <replacement_expression> may refer to parenthesis-delimited
subexpressions of the match using \1, \2, , \9. Note that
two backslashes (\\1) are required in CMake code to get a backslash
through argument parsing.
Regex Specification
The following characters have special meaning in regular expressions:
^ Matches at beginning of input
$ Matches at end of input
. Matches any single character
\<char>
Matches the single character specified by <char>. Use this to
match special regex characters, e.g. \. for a literal . or \\
for a literal backslash \. Escaping a non-special character is
unnecessary but allowed, e.g. \a matches a.
[ ] Matches any character(s) inside the brackets
[^ ] Matches any character(s) not inside the brackets
- Inside brackets, specifies an inclusive range between characters
on either side e.g. [a-f] is [abcdef] To match a literal - using
brackets, make it the first or the last character e.g. [+*/-]
matches basic mathematical operators.
* Matches preceding pattern zero or more times
+ Matches preceding pattern one or more times
? Matches preceding pattern zero or once only
| Matches a pattern on either side of the |
() Saves a matched subexpression, which can be referenced in the
REGEX REPLACE operation. Additionally it is saved by all regular
expression-related commands, including e.g. if(MATCHES), in the
variables CMAKE_MATCH_<n> for <n> 0..9.
*, + and ? have higher precedence than concatenation. | has lower
precedence than concatenation. This means that the regular expression
^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
matches ab but not abd.
CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
to construct literal tabs, carriage returns, newlines, and backslashes
(respectively) to pass in a regex. For example:
o The quoted argument "[ \t\r\n]" specifies a regex that matches any
single whitespace character.
o The quoted argument "[/\\]" specifies a regex that matches a single
forward slash / or backslash \.
o The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
single word character in the C locale.
o The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
the exact string (a+b). Each \\ is parsed in a quoted argument as
just \, so the regex itself is actually \(\a\+\b\). This can alter-
natively be specified in a bracket argument without having to escape
the backslashes, e.g. [[\(\a\+\b\)]].
Manipulation
string(APPEND <string_variable> [<input>...])
Append all the <input> arguments to the string.
string(PREPEND <string_variable> [<input>...])
Prepend all the <input> arguments to the string.
string(CONCAT <output_variable> [<input>...])
Concatenate all the <input> arguments together and store the result in
the named <output_variable>.
string(JOIN <glue> <output_variable> [<input>...])
Join all the <input> arguments together using the <glue> string and
store the result in the named <output_variable>.
To join a lists elements, prefer to use the JOIN operator from the
list() command. This allows for the elements to have special charac-
ters like ; in them.
string(TOLOWER <string> <output_variable>)
Convert <string> to lower characters.
string(TOUPPER <string> <output_variable>)
Convert <string> to upper characters.
string(LENGTH <string> <output_variable>)
Store in an <output_variable> a given strings length in bytes. Note
that this means if <string> contains multi-byte characters, the result
stored in <output_variable> will not be the number of characters.
string(SUBSTRING <string> <begin> <length> <output_variable>)
Store in an <output_variable> a substring of a given <string>. If
<length> is -1 the remainder of the string starting at <begin> will be
returned. If <string> is shorter than <length> then the end of the
string is used instead.
Both <begin> and <length> are counted in bytes, so care must be exer-
cised if <string> could contain multi-byte characters.
NOTE:
CMake 3.1 and below reported an error if <length> pointed past the
end of <string>.
string(STRIP <string> <output_variable>)
Store in an <output_variable> a substring of a given <string> with
leading and trailing spaces removed.
string(GENEX_STRIP <string> <output_variable>)
Strip any generator expressions from the input <string> and store the
result in the <output_variable>.
string(REPEAT <string> <count> <output_variable>)
Produce the output string as the input <string> repeated <count> times.
Comparison
string(COMPARE LESS <string1> <string2> <output_variable>)
string(COMPARE GREATER <string1> <string2> <output_variable>)
string(COMPARE EQUAL <string1> <string2> <output_variable>)
string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
Compare the strings and store true or false in the <output_variable>.
Hashing
string(<HASH> <output_variable> <input>)
Compute a cryptographic hash of the <input> string. The supported
<HASH> algorithm names are:
MD5 Message-Digest Algorithm 5, RFC 1321.
SHA1 US Secure Hash Algorithm 1, RFC 3174.
SHA224 US Secure Hash Algorithms, RFC 4634.
SHA256 US Secure Hash Algorithms, RFC 4634.
SHA384 US Secure Hash Algorithms, RFC 4634.
SHA512 US Secure Hash Algorithms, RFC 4634.
SHA3_224
Keccak SHA-3.
SHA3_256
Keccak SHA-3.
SHA3_384
Keccak SHA-3.
SHA3_512
Keccak SHA-3.
Generation
string(ASCII <number> [<number> ...] <output_variable>)
Convert all numbers into corresponding ASCII characters.
string(HEX <string> <output_variable>)
Convert each byte in the input <string> to its hexadecimal representa-
tion and store the concatenated hex digits in the <output_variable>.
Letters in the output (a through f) are in lowercase.
string(CONFIGURE <string> <output_variable>
[@ONLY] [ESCAPE_QUOT_expression> for the match in the output.
All <input> arguments are concatenated before matching.
The <replacement_expression> may refer to parenthesis-delimited
subexpressions of the match using \1, \2, , \9. Note that
two backslashes (\\1) are required in CMake code to get a backslash
through argument parsing.
Regex Specification
The following characters have special meaning in regular expressions:
^ Matches at beginning of input
$ Matches at end of input
. Matches any single character
\<char>
Matches the single character specified by <char>. Use this to
match special regex characters, e.g. \. for a literal . or \\
for a literal backslash \. Escaping a non-special character is
unnecessary but allowed, e.g. \a matches a.
[ ] Matches any character(s) inside the brackets
[^ ] Matches any character(s) not inside the brackets
- Inside brackets, specifies an inclusive range between characters
on either side e.g. [a-f] is [abcdef] To match a literal - using
brackets, make it the first or the last character e.g. [+*/-]
matches basic mathematical operators.
* Matches preceding pattern zero or more times
+ Matches preceding pattern one or more times
? Matches preceding pattern zero or once only
| Matches a pattern on either side of the |
() Saves a matched subexpression, which can be referenced in the
REGEX REPLACE operation. Additionally it is saved by all regular
expression-related commands, including e.g. if(MATCHES), in the
variables CMAKE_MATCH_<n> for <n> 0..9.
*, + and ? have higher precedence than concatenation. | has lower
precedence than concatenation. This means that the regular expression
^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
matches ab but not abd.
CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
to construct literal tabs, carriage returns, newlines, and backslashes
(respectively) to pass in a regex. For example:
o The quoted argument "[ \t\r\n]" specifies a regex that matches any
single whitespace character.
o The quoted argument "[/\\]" specifies a regex that matches a single
forward slash / or backslash \.
o The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
single word character in the C locale.
o The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
the exact string (a+b). Each \\ is parsed in a quoted argument as
just \, so the regex itself is actually \(\a\+\b\). This can alter-
natively be specified in a bracket argument without having to escape
the backslashes, e.g. [[\(\a\+\b\)]].
Manipulation
string(APPEND <string_variable> [<input>...])
Append all the <input> arguments to the string.
string(PREPEND <string_variable> [<input>...])
Prepend all the <input> arguments to the string.
string(CONCAT <output_variable> [<input>...])
Concatenate all the <input> arguments together and store the result in
the named <output_variable>.
string(JOIN <glue> <output_variable> [<input>...])
Join all the <input> arguments together using the <glue> string and
store the result in the named <output_variable>.
To join a lists elements, prefer to use the JOIN operator from the
list() command. This allows for the elements to have special charac-
ters like ; in them.
string(TOLOWER <string> <output_variable>)
Convert <string> to lower characters.
string(TOUPPER <string> <output_variable>)
Convert <string> to upper characters.
string(LENGTH <string> <output_variable>)
Store in an <output_variable> a given strings length in bytes. Note
that this means if <string> contains multi-byte characters, the result
stored in <output_variable> will not be the number of characters.
string(SUBSTRING <string> <begin> <length> <output_variable>)
Store in an <output_variable> a substring of a given <string>. If
<length> is -1 the remainder of the string starting at <begin> will be
returned. If <string> is shorter than <length> then the end of the
string is used instead.
Both <begin> and <length> are counted in bytes, so care must be exer-
cised if <string> could contain multi-byte characters.
NOTE:
CMake 3.1 and below reported an error if <length> pointed past the
end of <string>.
string(STRIP <string> <output_variable>)
Store in an <output_variable> a substring of a given <string> with
leading and trailing spaces removed.
string(GENEX_STRIP <string> <output_variable>)
Strip any generator expressions from the input <string> and store the
result in the <output_variable>.
string(REPEAT <string> <count> <output_variable>)
Produce the output string as the input <string> repeated <count> times.
Comparison
string(COMPARE LESS <string1> <string2> <output_variable>)
string(COMPARE GREATER <string1> <string2> <output_variable>)
string(COMPARE EQUAL <string1> <string2> <output_variable>)
string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
Compare the strings and store true or false in the <output_variable>.
Hashing
string(<HASH> <output_variable> <input>)
Compute a cryptographic hash of the <input> string. The supported
<HASH> algorithm names are:
MD5 Message-Digest Algorithm 5, RFC 1321.
SHA1 US Secure Hash Algorithm 1, RFC 3174.
SHA224 US Secure Hash Algorithms, RFC 4634.
SHA256 US Secure Hash Algorithms, RFC 4634.
SHA384 US Secure Hash Algorithms, RFC 4634.
SHA512 US Secure Hash Algorithms, RFC 4634.
SHA3_224
Keccak SHA-3.
SHA3_256
Keccak SHA-3.
SHA3_384
Keccak SHA-3.
SHA3_512
Keccak SHA-3.
Generation
string(ASCII <number> [<number> ...] <output_variable>)
Convert all numbers into corresponding ASCII characters.
string(HEX <string> <output_variable>)
Convert each byte in the input <string> to its hexadecimal representa-
tion and store the concatenated hex digits in the <output_variable>.
Letters in the output (a through f) are in lowercase.
string(CONFIGURE <string> <output_variable>
[@ONLY] [ESCAPE_QUOT_expression> for the match in the output.
All <input> arguments are concatenated before matching.
The <replacement_expression> may refer to parenthesis-delimited
subexpressions of the match using \1, \2, , \9. Note that
two backslashes (\\1) are required in CMake code to get a backslash
through argument parsing.
Regex Specification
The following characters have special meaning in regular expressions:
^ Matches at beginning of input
$ Matches at end of input
. Matches any single character
\<char>
Matches the single character specified by <char>. Use this to
match special regex characters, e.g. \. for a literal . or \\
for a literal backslash \. Escaping a non-special character is
unnecessary but allowed, e.g. \a matches a.
[ ] Matches any character(s) inside the brackets
[^ ] Matches any character(s) not inside the brackets
- Inside brackets, specifies an inclusive range between characters
on either side e.g. [a-f] is [abcdef] To match a literal - using
brackets, make it the first or the last character e.g. [+*/-]
matches basic mathematical operators.
* Matches preceding pattern zero or more times
+ Matches preceding pattern one or more times
? Matches preceding pattern zero or once only
| Matches a pattern on either side of the |
() Saves a matched subexpression, which can be referenced in the
REGEX REPLACE operation. Additionally it is saved by all regular
expression-related commands, including e.g. if(MATCHES), in the
variables CMAKE_MATCH_<n> for <n> 0..9.
*, + and ? have higher precedence than concatenation. | has lower
precedence than concatenation. This means that the regular expression
^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
matches ab but not abd.
CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
to construct literal tabs, carriage returns, newlines, and backslashes
(respectively) to pass in a regex. For example:
o The quoted argument "[ \t\r\n]" specifies a regex that matches any
single whitespace character.
o The quoted argument "[/\\]" specifies a regex that matches a single
forward slash / or backslash \.
o The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
single word character in the C locale.
o The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
the exact string (a+b). Each \\ is parsed in a quoted argument as
just \, so the regex itself is actually \(\a\+\b\). This can alter-
natively be specified in a bracket argument without having to escape
the backslashes, e.g. [[\(\a\+\b\)]].
Manipulation
string(APPEND <string_variable> [<input>...])
Append all the <input> arguments to the string.
string(PREPEND <string_variable> [<input>...])
Prepend all the <input> arguments to the string.
string(CONCAT <output_variable> [<input>...])
Concatenate all the <input> arguments together and store the result in
the named <output_variable>.
string(JOIN <glue> <output_variable> [<input>...])
Join all the <input> arguments together using the <glue> string and
store the result in the named <output_variable>.
To join a lists elements, prefer to use the JOIN operator from the
list() command. This allows for the elements to have special charac-
ters like ; in them.
string(TOLOWER <string> <output_variable>)
Convert <string> to lower characters.
string(TOUPPER <string> <output_variable>)
Convert <string> to upper characters.
string(LENGTH <string> <output_variable>)
Store in an <output_variable> a given strings length in bytes. Note
that this means if <string> contains multi-byte characters, the result
stored in <output_variable> will not be the number of characters.
string(SUBSTRING <string> <begin> <length> <output_variable>)
Store in an <output_variable> a substring of a given <string>. If
<length> is -1 the remainder of the string starting at <begin> will be
returned. If <string> is shorter than <length> then the end of the
string is used instead.
Both <begin> and <length> are counted in bytes, so care must be exer-
cised if <string> could contain multi-byte characters.
NOTE:
CMake 3.1 and below reported an error if <length> pointed past the
end of <string>.
string(STRIP <string> <output_variable>)
Store in an <output_variable> a substring of a given <string> with
leading and trailing spaces removed.
string(GENEX_STRIP <string> <output_variable>)
Strip any generator expressions from the input <string> and store the
result in the <output_variable>.
string(REPEAT <string> <count> <output_variable>)
Produce the output string as the input <string> repeated <count> times.
Comparison
string(COMPARE LESS <string1> <string2> <output_variable>)
string(COMPARE GREATER <string1> <string2> <output_variable>)
string(COMPARE EQUAL <string1> <string2> <output_variable>)
string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
Compare the strings and store true or false in the <output_variable>.
Hashing
string(<HASH> <output_variable> <input>)
Compute a cryptographic hash of the <input> string. The supported
<HASH> algorithm names are:
MD5 Message-Digest Algorithm 5, RFC 1321.
SHA1 US Secure Hash Algorithm 1, RFC 3174.
SHA224 US Secure Hash Algorithms, RFC 4634.
SHA256 US Secure Hash Algorithms, RFC 4634.
SHA384 US Secure Hash Algorithms, RFC 4634.
SHA512 US Secure Hash Algorithms, RFC 4634.
SHA3_224
Keccak SHA-3.
SHA3_256
Keccak SHA-3.
SHA3_384
Keccak SHA-3.
SHA3_512
Keccak SHA-3.
Generation
string(ASCII <number> [<number> ...] <output_variable>)
Convert all numbers into corresponding ASCII characters.
string(HEX <string> <output_variable>)
Convert each byte in the input <string> to its hexadecimal representa-
tion and store the concatenated hex digits in the <output_variable>.
Letters in the output (a through f) are in lowercase.
string(CONFIGURE <string> <output_variable>
[@ONLY] [ESCAPE_QUOT_expression> for the match in the output.
All <input> arguments are concatenated before matching.
The <replacement_expression> may refer to parenthesis-deli
Note that unlike set_property() and get_property() no
actual scope needs to be given; only the kind of scope is important.
The required PROPERTY option is immediately followed by the name of
the property being defined.
If the INHERITED option is given, then the get_property() command
will chain up to the next higher scope when the requested property is not set
in the scope given to the command.
o DIRECTORY scope chains to its parent directorys scope, continuing the
walk up parent directories until a directory has the property set or there
are no more parents. If still not found at the top level directory, it
chains to the GLOBAL scope.
o TARGET, SOURCE and TEST properties chain to DIRECTORY scope,
including further chaining up the directories, etc. as needed.
Note that this scope chaining behavior only applies to calls to
get_property(), get_directory_property(),
get_target_property(), get_source_file_property() and
get_test_property(). There is no inheriting behavior when setting
properties, so using APPEND or APPEND_STRING with the
set_property() command will not consider inherited values when working
out the contents to append to.
The BRIEF_DOCS and FULL_DOCS options are followed by strings to be
associated with the property as its brief and full documentation.
Corresponding options to the get_property() command will retrieve
the documentation.
enable_language
Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
enable_language(<lang> [OPTIONAL] )
Enables support for the named language in CMake. This is the same as
the project() command but does not create any of the extra variables
that are created by the project command. Example languages are CXX, C,
CUDA, OBJC, OBJCXX, Fortran, and ASM.
If enabling ASM, enable it last so that CMake can check whether compil-
ers for other languages like C work for assembly too.
This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or in-
directly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The OPTIONAL keyword is a placeholder for future implementation and
does not currently work. Instead you can use the CheckLanguage module
to verify support before enabling.
enable_testing
Enable testing for current directory and below.
enable_testing()
Enables testing for this directory and below.
This command should be in the source directory root because ctest ex-
pects to find a test file in the build directory root.
This command is automatically invoked when the CTest module is in-
cluded, except if the BUILD_TESTING option is turned off.
See also the add_test() command.
export
Export targets from the build tree for use by outside projects.
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
Creates a file <filename> that may be included by outside projects to
import targets from the current projects build tree. This is useful
during cross-compiling to build utility executables that can run on the
host platform in one project and then import them into another project
being compiled for the target platform. If the NAMESPACE option is
given the <namespace> string will be prepended to all target names
written to the file.
Target installations are associated with the export <export-name> using
the EXPORT option of the install(TARGETS) command.
The file created by this command is specific to the build tree and
should never be installed. See the install(EXPORT) command to export
targets from an installation tree.
The properties set on the generated IMPORTED targets will have the same
values as the final values of the input TARGETS.
export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
This signature is similar to the EXPORT signature, but targets are
listed explicitly rather than specified as an export-name. If the AP-
PEND option is given the generated code will be appended to the file
instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key-
word, if present, causes the contents of the properties matching (IM-
PORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when pol-
icy CMP0022 is NEW. If a library target is included in the export but
a target to which it links is not included the behavior is unspecified.
NOTE:
Object Libraries under Xcode have special handling if multiple ar-
chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
they will be exported as Interface Libraries with no object files
available to clients. This is sufficient to satisfy transitive us-
age requirements of other targets that link to the object libraries
in their implementation.
export(PACKAGE <PackageName>)
Store the current build directory in the CMake user package registry
for package <PackageName>. The find_package() command may consider the
directory while searching for package <PackageName>. This helps depen-
dent projects find and use a package from the current projects build
tree without help from the user. Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (<PackageName>Config.cmake) that works with
the build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package reg-
istry.
By default the export(PACKAGE) command does nothing (see policy
CMP0090) because populating the user package registry has effects out-
side the source and build trees. Set the CMAKE_EXPORT_PACKAGE_REGISTRY
variable to add build directories to the CMake user package registry.
export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
This signature exports cmake built targets to the android ndk build
system by creating an Android.mk file that references the prebuilt tar-
gets. The Android NDK supports the use of prebuilt libraries, both
static and shared. This allows cmake to build the libraries of a
project and make them available to an ndk build system complete with
transitive dependencies, include flags and defines required to use the
libraries. The signature takes a list of targets and puts them in the
Android.mk file specified by the <filename> given. This signature can
only be used if policy CMP0022 is NEW for all targets given. A error
will be issued if that policy is set to OLD for one of the targets.
fltk_wrap_ui
Create FLTK user interfaces Wrappers.
fltk_wrap_ui(resultingLibraryName source1
source2 ... sourceN )
Produce .h and .cxx files for all the .fl and .fld files listed. The
resulting .h and .cxx files will be added to a variable named result-
ingLibraryName_FLTK_UI_SRCS which should be added to your library.
get_source_file_property
Get a property for a source file.
get_source_file_property(<variable> <file>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>]
<property>)
Note that unlike set_property() and get_property() no actual scope
needs to be given; only the kind of scope is important.
The required PROPERTY option is immediately followed by the name of
the property being defined.
If the INHERITED option is given, then the get_property() command
will chain up to the next higher scope when the requested property
is not set in the scope given to the command.
o DIRECTORY scope chains to its parent directorys scope, continuing the
walk up parent directories until a directory has the property set or
there are no more parents. If still not found at the top level di-
rectory, it chains to the GLOBAL scope.
o TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ-
ing further chaining up the directories, etc. as needed.
Note that this scope chaining behavior only applies to calls to
get_property(), get_directory_property(), get_target_property(),
get_source_file_property() and get_test_property(). There is no inher-
iting behavior when setting properties, so using APPEND or AP-
PEND_STRING with the set_property() command will not consider inherited
values when working out the contents to append to.
The BRIEF_DOCS and FULL_DOCS options are followed by strings to be as-
sociated with the property as its brief and full documentation. Corre-
sponding options to the get_property() command will retrieve the docu-
mentation.
enable_language
Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
enable_language(<lang> [OPTIONAL] )
Enables support for the named language in CMake. This is the same as
the project() command but does not create any of the extra variables
that are created by the project command. Example languages are CXX, C,
CUDA, OBJC, OBJCXX, Fortran, and ASM.
If enabling ASM, enable it last so that CMake can check whether compil-
ers for other languages like C work for assembly too.
This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or in-
directly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The OPTIONAL keyword is a placeholder for future implementation and
does not currently work. Instead you can use the CheckLanguage module
to verify support before enabling.
enable_testing
Enable testing for current directory and below.
enable_testing()
Enables testing for this directory and below.
This command should be in the source directory root because ctest ex-
pects to find a test file in the build directory root.
This command is automatically invoked when the CTest module is in-
cluded, except if the BUILD_TESTING option is turned off.
See also the add_test() command.
export
Export targets from the build tree for use by outside projects.
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
Creates a file <filename> that may be included by outside projects to
import targets from the current projects build tree. This is useful
during cross-compiling to build utility executables that can run on the
host platform in one project and then import them into another project
being compiled for the target platform. If the NAMESPACE option is
given the <namespace> string will be prepended to all target names
written to the file.
Target installations are associated with the export <export-name> using
the EXPORT option of the install(TARGETS) command.
The file created by this command is specific to the build tree and
should never be installed. See the install(EXPORT) command to export
targets from an installation tree.
The properties set on the generated IMPORTED targets will have the same
values as the final values of the input TARGETS.
export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
This signature is similar to the EXPORT signature, but targets are
listed explicitly rather than specified as an export-name. If the AP-
PEND option is given the generated code will be appended to the file
instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key-
word, if present, causes the contents of the properties matching (IM-
PORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when pol-
icy CMP0022 is NEW. If a library target is included in the export but
a target to which it links is not included the behavior is unspecified.
NOTE:
Object Libraries under Xcode have special handling if multiple ar-
chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
they will be exported as Interface Libraries with no object files
available to clients. This is sufficient to satisfy transitive us-
age requirements of other targets that link to the object libraries
in their implementation.
export(PACKAGE <PackageName>)
Store the current build directory in the CMake user package registry
for package <PackageName>. The find_package() command may consider the
directory while searching for package <PackageName>. This helps depen-
dent projects find and use a package from the current projects build
tree without help from the user. Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (<PackageName>Config.cmake) that works with
the build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package reg-
istry.
By default the export(PACKAGE) command does nothing (see policy
CMP0090) because populating the user package registry has effects out-
side the source and build trees. Set the CMAKE_EXPORT_PACKAGE_REGISTRY
variable to add build directories to the CMake user package registry.
export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
This signature exports cmake built targets to the android ndk build
system by creating an Android.mk file that references the prebuilt tar-
gets. The Android NDK supports the use of prebuilt libraries, both
static and shared. This allows cmake to build the libraries of a
project and make them available to an ndk build system complete with
transitive dependencies, include flags and defines required to use the
libraries. The signature takes a list of targets and puts them in the
Android.mk file specified by the <filename> given. This signature can
only be used if policy CMP0022 is NEW for all targets given. A error
will be issued if that policy is set to OLD for one of the targets.
fltk_wrap_ui
Create FLTK user interfaces Wrappers.
fltk_wrap_ui(resultingLibraryName source1
source2 ... sourceN )
Produce .h and .cxx files for all the .fl and .fld files listed. The
resulting .h and .cxx files will be added to a variable named result-
ingLibraryName_FLTK_UI_SRCS which should be added to your library.
get_source_file_property
Get a property for a source file.
get_source_file_property(<variable> <file>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>]
<property>)
Note that unlike set_property() and get_property() no actual scope
needs to be given; only the kind of scope is important.
The required PROPERTY option is immediately followed by the name of
the property being defined.
If the INHERITED option is given, then the get_property() command
will chain up to the next higher scope when the requested property
is not set in the scope given to the command.
o DIRECTORY scope chains to its parent directorys scope, continuing the
walk up parent directories until a directory has the property set or
there are no more parents. If still not found at the top level di-
rectory, it chains to the GLOBAL scope.
o TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ-
ing further chaining up the directories, etc. as needed.
Note that this scope chaining behavior only applies to calls to
get_property(), get_directory_property(), get_target_property(),
get_source_file_property() and get_test_property(). There is no inher-
iting behavior when setting properties, so using APPEND or AP-
PEND_STRING with the set_property() command will not consider inherited
values when working out the contents to append to.
The BRIEF_DOCS and FULL_DOCS options are followed by strings to be as-
sociated with the property as its brief and full documentation. Corre-
sponding options to the get_property() command will retrieve the docu-
mentation.
enable_language
Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
enable_language(<lang> [OPTIONAL] )
Enables support for the named language in CMake. This is the same as
the project() command but does not create any of the extra variables
that are created by the project command. Example languages are CXX, C,
CUDA, OBJC, OBJCXX, Fortran, and ASM.
If enabling ASM, enable it last so that CMake can check whether compil-
ers for other languages like C work for assembly too.
This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or in-
directly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The OPTIONAL keyword is a placeholder for future implementation and
does not currently work. Instead you can use the CheckLanguage module
to verify support before enabling.
enable_testing
Enable testing for current directory and below.
enable_testing()
Enables testing for this directory and below.
This command should be in the source directory root because ctest ex-
pects to find a test file in the build directory root.
This command is automatically invoked when the CTest module is in-
cluded, except if the BUILD_TESTING option is turned off.
See also the add_test() command.
export
Export targets from the build tree for use by outside projects.
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
Creates a file <filename> that may be included by outside projects to
import targets from the current projects build tree. This is useful
during cross-compiling to build utility executables that can run on the
host platform in one project and then import them into another project
being compiled for the target platform. If the NAMESPACE option is
given the <namespace> string will be prepended to all target names
written to the file.
Target installations are associated with the export <export-name> using
the EXPORT option of the install(TARGETS) command.
The file created by this command is specific to the build tree and
should never be installed. See the install(EXPORT) command to export
targets from an installation tree.
The properties set on the generated IMPORTED targets will have the same
values as the final values of the input TARGETS.
export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
This signature is similar to the EXPORT signature, but targets are
listed explicitly rather than specified as an export-name. If the AP-
PEND option is given the generated code will be appended to the file
instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key-
word, if present, causes the contents of the properties matching (IM-
PORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when pol-
icy CMP0022 is NEW. If a library target is included in the export but
a target to which it links is not included the behavior is unspecified.
NOTE:
Object Libraries under Xcode have special handling if multiple ar-
chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
they will be exported as Interface Libraries with no object files
available to clients. This is sufficient to satisfy transitive us-
age requirements of other targets that link to the object libraries
in their implementation.
export(PACKAGE <PackageName>)
Store the current build directory in the CMake user package registry
for package <PackageName>. The find_package() command may consider the
directory while searching for package <PackageName>. This helps depen-
dent projects find and use a package from the current projects build
tree without help from the user. Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (<PackageName>Config.cmake) that works with
the build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package reg-
istry.
By default the export(PACKAGE) command does nothing (see policy
CMP0090) because populating the user package registry has effects out-
side the source and build trees. Set the CMAKE_EXPORT_PACKAGE_REGISTRY
variable to add build directories to the CMake user package registry.
export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
This signature exports cmake built targets to the android ndk build
system by creating an Android.mk file that references the prebuilt tar-
gets. The Android NDK supports the use of prebuilt libraries, both
static and shared. This allows cmake to build the libraries of a
project and make them available to an ndk build system complete with
transitive dependencies, include flags and defines required to use the
libraries. The signature takes a list of targets and puts them in the
Android.mk file specified by the <filename> given. This signature can
only be used if policy CMP0022 is NEW for all targets given. A error
will be issued if that policy is set to OLD for one of the targets.
fltk_wrap_ui
Create FLTK user interfaces Wrappers.
fltk_wrap_ui(resultingLibraryName source1
source2 ... sourceN )
Produce .h and .cxx files for all the .fl and .fld files listed. The
resulting .h and .cxx files will be added to a variable named result-
ingLibraryName_FLTK_UI_SRCS which should be added to your library.
get_source_file_property
Get a property for a source file.
get_source_file_property(<variable> <file>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>]
<property>)
Note that unlike set_property() and get_property() no actual scope
needs to be given; only the kind of scope is important.
The required PROPERTY option is immediately followed by the name of
the property being defined.
If the INHERITED option is given, then the get_property() command
will chain up to the next higher scope when the requested property
is not set in the scope given to the command.
o DIRECTORY scope chains to its parent directorys scope, continuing the
walk up parent directories until a directory has the property set or
there are no more parents. If still not found at the top level di-
rectory, it chains to the GLOBAL scope.
o TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ-
ing further chaining up the directories, etc. as needed.
Note that this scope chaining behavior only applies to calls to
get_property(), get_directory_property(), get_target_property(),
get_source_file_property() and get_test_property(). There is no inher-
iting behavior when setting properties, so using APPEND or AP-
PEND_STRING with the set_property() command will not consider inherited
values when working out the contents to append to.
The BRIEF_DOCS and FULL_DOCS options are followed by strings to be as-
sociated with the property as its brief and full documentation. Corre-
sponding options to the get_property() command will retrieve the docu-
mentation.
enable_language
Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
enable_language(<lang> [OPTIONAL] )
Enables support for the named language in CMake. This is the same as
the project() command but does not create any of the extra variables
that are created by the project command. Example languages are CXX, C,
CUDA, OBJC, OBJCXX, Fortran, and ASM.
If enabling ASM, enable it last so that CMake can check whether compil-
ers for other languages like C work for assembly too.
This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or in-
directly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The OPTIONAL keyword is a placeholder for future implementation and
does not currently work. Instead you can use the CheckLanguage module
to verify support before enabling.
enable_testing
Enable testing for current directory and below.
enable_testing()
Enables testing for this directory and below.
This command should be in the source directory root because ctest ex-
pects to find a test file in the build directory root.
This command is automatically invoked when the CTest module is in-
cluded, except if the BUILD_TESTING option is turned off.
See also the add_test() command.
export
Export targets from the build tree for use by outside projects.
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
Creates a file <filename> that may be included by outside projects to
import targets from the current projects build tree. This is useful
during cross-compiling to build utility executables that can run on the
host platform in one project and then import them into another project
being compiled for the target platform. If the NAMESPACE option is
given the <namespace> string will be prepended to all target names
written to the file.
Target installations are associated with the export <export-name> using
the EXPORT option of the install(TARGETS) command.
The file created by this command is specific to the build tree and
should never be installed. See the install(EXPORT) command to export
targets from an installation tree.
The properties set on the generated IMPORTED targets will have the same
values as the final values of the input TARGETS.
export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
This signature is similar to the EXPORT signature, but targets are
listed explicitly rather than specified as an export-name. If the AP-
PEND option is given the generated code will be appended to the file
instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key-
word, if present, causes the contents of the properties matching (IM-
PORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when pol-
icy CMP0022 is NEW. If a library target is included in the export but
a target to which it links is not included the behavior is unspecified.
NOTE:
Object Libraries under Xcode have special handling if multiple ar-
chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
they will be exported as Interface Libraries with no object files
available to clients. This is sufficient to satisfy transitive us-
age requirements of other targets that link to the object libraries
in their implementation.
export(PACKAGE <PackageName>)
Store the current build directory in the CMake user package registry
for package <PackageName>. The find_package() command may consider the
directory while searching for package <PackageName>. This helps depen-
dent projects find and use a package from the current projects build
tree without help from the user. Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (<PackageName>Config.cmake) that works with
the build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package reg-
istry.
By default the export(PACKAGE) command does nothing (see policy
CMP0090) because populating the user package registry has effects out-
side the source and build trees. Set the CMAKE_EXPORT_PACKAGE_REGISTRY
variable to add build directories to the CMake user package registry.
export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
This signature exports cmake built targets to the android ndk build
system by creating an Android.mk file that references the prebuilt tar-
gets. The Android NDK supports the use of prebuilt libraries, both
static and shared. This allows cmake to build the libraries of a
project and make them available to an ndk build system complete with
transitive dependencies, include flags and defines required to use the
libraries. The signature takes a list of targets and puts them in the
Android.mk file specified by the <filename> given. This signature can
only be used if policy CMP0022 is NEW for all targets given. A error
will be issued if that policy is set to OLD for one of the targets.
fltk_wrap_ui
Create FLTK user interfaces Wrappers.
fltk_wrap_ui(resultingLibraryName source1
source2 ... sourceN )
Produce .h and .cxx files for all the .fl and .fld files listed. The
resulting .h and .cxx files will be added to a variable named result-
ingLibraryName_FLTK_UI_SRCS which should be added to your library.
get_source_file_property
Get a property for a source file.
get_source_file_property(<variable> <file>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>]
<property>)
Note that unlike set_property() and get_property() no actual scope
needs to be given; only the kind of scope is important.
The required PROPERTY option is immediately followed by the name of
the property being defined.
If the INHERITED option is given, then the get_property() command
will chain up to the next higher scope when the requested property
is not set in the scope given to the command.
o DIRECTORY scope chains to its parent directorys scope, continuing the
walk up parent directories until a directory has the property set or
there are no more parents. If still not found at the top level di-
rectory, it chains to the GLOBAL scope.
o TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ-
ing further chaining up the directories, etc. as needed.
Note that this scope chaining behavior only applies to calls to
get_property(), get_directory_property(), get_target_property(),
get_source_file_property() and get_test_property(). There is no inher-
iting behavior when setting properties, so using APPEND or AP-
PEND_STRING with the set_property() command will not consider inherited
values when working out the contents to append to.
The BRIEF_DOCS and FULL_DOCS options are followed by strings to be as-
sociated with the property as its brief and full documentation. Corre-
sponding options to the get_property() command will retrieve the docu-
mentation.
enable_language
Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
enable_language(<lang> [OPTIONAL] )
Enables support for the named language in CMake. This is the same as
the project() command but does not create any of the extra variables
that are created by the project command. Example languages are CXX, C,
CUDA, OBJC, OBJCXX, Fortran, and ASM.
If enabling ASM, enable it last so that CMake can check whether compil-
ers for other languages like C work for assembly too.
This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or in-
directly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The OPTIONAL keyword is a placeholder for future implementation and
does not currently work. Instead you can use the CheckLanguage module
to verify support before enabling.
enable_testing
Enable testing for current directory and below.
enable_testing()
Enables testing for this directory and below.
This command should be in the source directory root because ctest ex-
pects to find a test file in the build directory root.
This command is automatically invoked when the CTest module is in-
cluded, except if the BUILD_TESTING option is turned off.
See also the add_test() command.
export
Export targets from the build tree for use by outside projects.
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
Creates a file <filename> that may be included by outside projects to
import targets from the current projects build tree. This is useful
during cross-compiling to build utility executables that can run on the
host platform in one project and then import them into another project
being compiled for the target platform. If the NAMESPACE option is
given the <namespace> string will be prepended to all target names
written to the file.
Target installations are associated with the export <export-name> using
the EXPORT option of the install(TARGETS) command.
The file created by this command is specific to the build tree and
should never be installed. See the install(EXPORT) command to export
targets from an installation tree.
The properties set on the generated IMPORTED targets will have the same
values as the final values of the input TARGETS.
export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
This signature is similar to the EXPORT signature, but targets are
listed explicitly rather than specified as an export-name. If the AP-
PEND option is given the generated code will be appended to the file
instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key-
word, if present, causes the contents of the properties matching (IM-
PORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when pol-
icy CMP0022 is NEW. If a library target is included in the export but
a target to which it links is not included the behavior is unspecified.
NOTE:
Object Libraries under Xcode have special handling if multiple ar-
chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
they will be exported as Interface Libraries with no object files
available to clients. This is sufficient to satisfy transitive us-
age requirements of other targets that link to the object libraries
in their implementation.
export(PACKAGE <PackageName>)
Store the current build directory in the CMake user package registry
for package <PackageName>. The find_package() command may consider the
directory while searching for package <PackageName>. This helps depen-
dent projects find and use a package from the current projects build
tree without help from the user. Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (<PackageName>Config.cmake) that works with
the build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package reg-
istry.
By default the export(PACKAGE) command does nothing (see policy
CMP0090) because populating the user package registry has effects out-
side the source and build trees. Set the CMAKE_EXPORT_PACKAGE_REGISTRY
variable to add build directories to the CMake user package registry.
export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
This signature exports cmake built targets to the android ndk build
system by creating an Android.mk file that references the prebuilt tar-
gets. The Android NDK supports the use of prebuilt libraries, both
static and shared. This allows cmake to build the libraries of a
project and make them available to an ndk build system complete with
transitive dependencies, include flags and defines required to use the
libraries. The signature takes a list of targets and puts them in the
Android.mk file specified by the <filename> given. This signature can
only be used if policy CMP0022 is NEW for all targets given. A error
will be issued if that policy is set to OLD for one of the targets.
fltk_wrap_ui
Create FLTK user interfaces Wrappers.
fltk_wrap_ui(resultingLibraryName source1
source2 ... sourceN )
Produce .h and .cxx files for all the .fl and .fld files listed. The
resulting .h and .cxx files will be added to a variable named result-
ingLibraryName_FLTK_UI_SRCS which should be added to your library.
get_source_file_property
Get a property for a source file.
get_source_file_property(<variable> <file>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>]
<property>)
Note that unlike set_property() and get_property() no actual scope
needs to be given; only the kind of scope is important.
The required PROPERTY option is immediately followed by the name of
the property being defined.
If the INHERITED option is given, then the get_property() command
will chain up to the next higher scope when the requested property
is not set in the scope given to the command.
o DIRECTORY scope chains to its parent directorys scope, continuing the
walk up parent directories until a directory has the property set or
there are no more parents. If still not found at the top level di-
rectory, it chains to the GLOBAL scope.
o TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ-
ing further chaining up the directories, etc. as needed.
Note that this scope chaining behavior only applies to calls to
get_property(), get_directory_property(), get_target_property(),
get_source_file_property() and get_test_property(). There is no inher-
iting behavior when setting properties, so using APPEND or AP-
PEND_STRING with the set_property() command will not consider inherited
values when working out the contents to append to.
The BRIEF_DOCS and FULL_DOCS options are followed by strings to be as-
sociated with the property as its brief and full documentation. Corre-
sponding options to the get_property() command will retrieve the docu-
mentation.
enable_language
Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
enable_language(<lang> [OPTIONAL] )
Enables support for the named language in CMake. This is the same as
the project() command but does not create any of the extra variables
that are created by the project command. Example languages are CXX, C,
CUDA, OBJC, OBJCXX, Fortran, and ASM.
If enabling ASM, enable it last so that CMake can check whether compil-
ers for other languages like C work for assembly too.
This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or in-
directly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The OPTIONAL keyword is a placeholder for future implementation and
does not currently work. Instead you can use the CheckLanguage module
to verify support before enabling.
enable_testing
Enable testing for current directory and below.
enable_testing()
Enables testing for this directory and below.
This command should be in the source directory root because ctest ex-
pects to find a test file in the build directory root.
This command is automatically invoked when the CTest module is in-
cluded, except if the BUILD_TESTING option is turned off.
See also the add_test() command.
export
Export targets from the build tree for use by outside projects.
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
Creates a file <filename> that may be included by outside projects to
import targets from the current projects build tree. This is useful
during cross-compiling to build utility executables that can run on the
host platform in one project and then import them into another project
being compiled for the target platform. If the NAMESPACE option is
given the <namespace> string will be prepended to all target names
written to the file.
Target installations are associated with the export <export-name> using
the EXPORT option of the install(TARGETS) command.
The file created by this command is specific to the build tree and
should never be installed. See the install(EXPORT) command to export
targets from an installation tree.
The properties set on the generated IMPORTED targets will have the same
values as the final values of the input TARGETS.
export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
This signature is similar to the EXPORT signature, but targets are
listed explicitly rather than specified as an export-name. If the AP-
PEND option is given the generated code will be appended to the file
instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key-
word, if present, causes the contents of the properties matching (IM-
PORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when pol-
icy CMP0022 is NEW. If a library target is included in the export but
a target to which it links is not included the behavior is unspecified.
NOTE:
Object Libraries under Xcode have special handling if multiple ar-
chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
they will be exported as Interface Libraries with no object files
available to clients. This is sufficient to satisfy transitive us-
age requirements of other targets that link to the object libraries
in their implementation.
export(PACKAGE <PackageName>)
Store the current build directory in the CMake user package registry
for package <PackageName>. The find_package() command may consider the
directory while searching for package <PackageName>. This helps depen-
dent projects find and use a package from the current projects build
tree without help from the user. Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (<PackageName>Config.cmake) that works with
the build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package reg-
istry.
By default the export(PACKAGE) command does nothing (see policy
CMP0090) because populating the user package registry has effects out-
side the source and build trees. Set the CMAKE_EXPORT_PACKAGE_REGISTRY
variable to add build directories to the CMake user package registry.
export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
This signature exports cmake built targets to the android ndk build
system by creating an Android.mk file that references the prebuilt tar-
gets. The Android NDK supports the use of prebuilt libraries, both
static and shared. This allows cmake to build the libraries of a
project and make them available to an ndk build system complete with
transitive dependencies, include flags and defines required to use the
libraries. The signature takes a list of targets and puts them in the
Android.mk file specified by the <filename> given. This signature can
only be used if policy CMP0022 is NEW for all targets given. A error
will be issued if that policy is set to OLD for one of the targets.
fltk_wrap_ui
Create FLTK user interfaces Wrappers.
fltk_wrap_ui(resultingLibraryName source1
source2 ... sourceN )
Produce .h and .cxx files for all the .fl and .fld files listed. The
resulting .h and .cxx files will be added to a variable named result-
ingLibraryName_FLTK_UI_SRCS which should be added to your library.
get_source_file_property
Get a property for a source file.
get_source_file_property(<variable> <file>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>]
<property>)
Note that unlike set_property() and get_property() no actual scope
needs to be given; only the kind of scope is important.
The required PROPERTY option is immediately followed by the name of
the property being defined.
If the INHERITED option is given, then the get_property() command
will chain up to the next higher scope when the requested property
is not set in the scope given to the command.
o DIRECTORY scope chains to its parent directorys scope, continuing the
walk up parent directories until a directory has the property set or
there are no more parents. If still not found at the top level di-
rectory, it chains to the GLOBAL scope.
o TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ-
ing further chaining up the directories, etc. as needed.
Note that this scope chaining behavior only applies to calls to
get_property(), get_directory_property(), get_target_property(),
get_source_file_property() and get_test_property(). There is no inher-
iting behavior when setting properties, so using APPEND or AP-
PEND_STRING with the set_property() command will not consider inherited
values when working out the contents to append to.
The BRIEF_DOCS and FULL_DOCS options are followed by strings to be as-
sociated with the property as its brief and full documentation. Corre-
sponding options to the get_property() command will retrieve the docu-
mentation.
enable_language
Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
enable_language(<lang> [OPTIONAL] )
Enables support for the named language in CMake. This is the same as
the project() command but does not create any of the extra variables
that are created by the project command. Example languages are CXX, C,
CUDA, OBJC, OBJCXX, Fortran, and ASM.
If enabling ASM, enable it last so that CMake can check whether compil-
ers for other languages like C work for assembly too.
This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or in-
directly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The OPTIONAL keyword is a placeholder for future implementation and
does not currently work. Instead you can use the CheckLanguage module
to verify support before enabling.
enable_testing
Enable testing for current directory and below.
enable_testing()
Enables testing for this directory and below.
This command should be in the source directory root because ctest ex-
pects to find a test file in the build directory root.
This command is automatically invoked when the CTest module is in-
cluded, except if the BUILD_TESTING option is turned off.
See also the add_test() command.
export
Export targets from the build tree for use by outside projects.
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
Creates a file <filename> that may be included by outside projects to
import targets from the current projects build tree. This is useful
during cross-compiling to build utility executables that can run on the
host platform in one project and then import them into another project
being compiled for the target platform. If the NAMESPACE option is
given the <namespace> string will be prepended to all target names
written to the file.
Target installations are associated with the export <export-name> using
the EXPORT option of the install(TARGETS) command.
The file created by this command is specific to the build tree and
should never be installed. See the install(EXPORT) command to export
targets from an installation tree.
The properties set on the generated IMPORTED targets will have the same
values as the final values of the input TARGETS.
export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
This signature is similar to the EXPORT signature, but targets are
listed explicitly rather than specified as an export-name. If the AP-
PEND option is given the generated code will be appended to the file
instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key-
word, if present, causes the contents of the properties matching (IM-
PORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when pol-
icy CMP0022 is NEW. If a library target is included in the export but
a target to which it links is not included the behavior is unspecified.
NOTE:
Object Libraries under Xcode have special handling if multiple ar-
chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
they will be exported as Interface Libraries with no object files
available to clients. This is sufficient to satisfy transitive us-
age requirements of other targets that link to the object libraries
in their implementation.
export(PACKAGE <PackageName>)
Store the current build directory in the CMake user package registry
for package <PackageName>. The find_package() command may consider the
directory while searching for package <PackageName>. This helps depen-
dent projects find and use a package from the current projects build
tree without help from the user. Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (<PackageName>Config.cmake) that works with
the build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package reg-
istry.
By default the export(PACKAGE) command does nothing (see policy
CMP0090) because populating the user package registry has effects out-
side the source and build trees. Set the CMAKE_EXPORT_PACKAGE_REGISTRY
variable to add build directories to the CMake user package registry.
export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
This signature exports cmake built targets to the android ndk build
system by creating an Android.mk file that references the prebuilt tar-
gets. The Android NDK supports the use of prebuilt libraries, both
static and shared. This allows cmake to build the libraries of a
project and make them available to an ndk build system complete with
transitive dependencies, include flags and defines required to use the
libraries. The signature takes a list of targets and puts them in the
Android.mk file specified by the <filename> given. This signature can
only be used if policy CMP0022 is NEW for all targets given. A error
will be issued if that policy is set to OLD for one of the targets.
fltk_wrap_ui
Create FLTK user interfaces Wrappers.
fltk_wrap_ui(resultingLibraryName source1
source2 ... sourceN )
Produce .h and .cxx files for all the .fl and .fld files listed. The
resulting .h and .cxx files will be added to a variable named result-
ingLibraryName_FLTK_UI_SRCS which should be added to your library.
get_source_file_property
Get a property for a source file.
get_source_file_property(<variable> <file>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>]
<property>)
Note that unlike set_property() and get_property() no actual scope
needs to be given; only the kind of scope is important.
The required PROPERTY option is immediately followed by the name of
the property being defined.
If the INHERITED option is given, then the get_property() command
will chain up to the next higher scope when the requested property
is not set in the scope given to the command.
o DIRECTORY scope chains to its parent directorys scope, continuing the
walk up parent directories until a directory has the property set or
there are no more parents. If still not found at the top level di-
rectory, it chains to the GLOBAL scope.
o TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ-
ing further chaining up the directories, etc. as needed.
Note that this scope chaining behavior only applies to calls to
get_property(), get_directory_property(), get_target_property(),
get_source_file_property() and get_test_property(). There is no inher-
iting behavior when setting properties, so using APPEND or AP-
PEND_STRING with the set_property() command will not consider inherited
values when working out the contents to append to.
The BRIEF_DOCS and FULL_DOCS options are followed by strings to be as-
sociated with the property as its brief and full documentation. Corre-
sponding options to the get_property() command will retrieve the docu-
mentation.
enable_language
Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
enable_language(<lang> [OPTIONAL] )
Enables support for the named language in CMake. This is the same as
the project() command but does not create any of the extra variables
that are created by the project command. Example languages are CXX, C,
CUDA, OBJC, OBJCXX, Fortran, and ASM.
If enabling ASM, enable it last so that CMake can check whether compil-
ers for other languages like C work for assembly too.
This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or in-
directly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The OPTIONAL keyword is a placeholder for future implementation and
does not currently work. Instead you can use the CheckLanguage module
to verify support before enabling.
enable_testing
Enable testing for current directory and below.
enable_testing()
Enables testing for this directory and below.
This command should be in the source directory root because ctest ex-
pects to find a test file in the build directory root.
This command is automatically invoked when the CTest module is in-
cluded, except if the BUILD_TESTING option is turned off.
See also the add_test() command.
export
Export targets from the build tree for use by outside projects.
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
Creates a file <filename> that may be included by outside projects to
import targets from the current projects build tree. This is useful
during cross-compiling to build utility executables that can run on the
host platform in one project and then import them into another project
being compiled for the target platform. If the NAMESPACE option is
given the <namespace> string will be prepended to all target names
written to the file.
Target installations are associated with the export <export-name> using
the EXPORT option of the install(TARGETS) command.
The file created by this command is specific to the build tree and
should never be installed. See the install(EXPORT) command to export
targets from an installation tree.
The properties set on the generated IMPORTED targets will have the same
values as the final values of the input TARGETS.
export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
This signature is similar to the EXPORT signature, but targets are
listed explicitly rather than specified as an export-name. If the AP-
PEND option is given the generated code will be appended to the file
instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key-
word, if present, causes the contents of the properties matching (IM-
PORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when pol-
icy CMP0022 is NEW. If a library target is included in the export but
a target to which it links is not included the behavior is unspecified.
NOTE:
Object Libraries under Xcode have special handling if multiple ar-
chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
they will be exported as Interface Libraries with no object files
available to clients. This is sufficient to satisfy transitive us-
age requirements of other targets that link to the object libraries
in their implementation.
export(PACKAGE <PackageName>)
Store the current build directory in the CMake user package registry
for package <PackageName>. The find_package() command may consider the
directory while searching for package <PackageName>. This helps depen-
dent projects find and use a package from the current projects build
tree without help from the user. Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (<PackageName>Config.cmake) that works with
the build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package reg-
istry.
By default the export(PACKAGE) command does nothing (see policy
CMP0090) because populating the user package registry has effects out-
side the source and build trees. Set the CMAKE_EXPORT_PACKAGE_REGISTRY
variable to add build directories to the CMake user package registry.
export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
This signature exports cmake built targets to the android ndk build
system by creating an Android.mk file that references the prebuilt tar-
gets. The Android NDK supports the use of prebuilt libraries, both
static and shared. This allows cmake to build the libraries of a
project and make them available to an ndk build system complete with
transitive dependencies, include flags and defines required to use the
libraries. The signature takes a list of targets and puts them in the
Android.mk file specified by the <filename> given. This signature can
only be used if policy CMP0022 is NEW for all targets given. A error
will be issued if that policy is set to OLD for one of the targets.
fltk_wrap_ui
Create FLTK user interfaces Wrappers.
fltk_wrap_ui(resultingLibraryName source1
source2 ... sourceN )
Produce .h and .cxx files for all the .fl and .fld files listed. The
resulting .h and .cxx files will be added to a variable named result-
ingLibraryName_FLTK_UI_SRCS which should be added to your library.
get_source_file_property
Get a property for a source file.
get_source_file_property(<variable> <file>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>]
<property>)
Note that unlike set_property() and get_property() no actual scope
needs to be given; only the kind of scope is important.
The required PROPERTY option is immediately followed by the na lead-
ing -D on an item will be removed. Empty items are ignored. For
example, the following are all equivalent:
target_compile_definitions(foo PUBLIC FOO)
target_compile_definitions(foo PUBLIC -DFOO) # -D removed
target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
target_compile_features
Add expected compiler features to a target.
target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
Specifies compiler features required when compiling a given target. If
the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
then an error will be reported by CMake. If the use of the feature re-
quires an additional compiler flag, such as -std=gnu++11, the flag will
be added automatically.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the features. PRIVATE and PUBLIC items will populate the COM-
PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
populate the INTERFACE_COMPILE_FEATURES property of <target>. (IM-
PORTED targets only support INTERFACE items.) Repeated calls for the
same <target> append items.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
Arguments to target_compile_features may use generator expressions with
the syntax $<...>. See the cmake-generator-expressions(7) manual for
available expressions. See the cmake-compile-features(7) manual for
information on compile features and a list of supported compilers.
target_compile_options
Add compile options to a target.
target_compile_options(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
properties. These options are used when compiling the given <target>,
which must have been created by a command such as add_executable() or
add_library() and must not be an ALIAS target.
Arguments
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
(IMPORTED targets only support INTERFACE items.) The following argu-
ments specify compile options. Repeated calls for the same <target>
append items in the order called.
Arguments to target_compile_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.
The final set of compile or link options used for a target is construc-
ted by accumulating options from the current target and the usage re-
quirements of its dependencies. The set of options is de-duplicated to
avoid repetition. While beneficial for individual options, the de-du-
plication step can break up option groups. For example, -D A -D B be-
comes -D 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:-D A" "SHELL:-D B" becomes -D A
-D B.
See Also
This command can be used to add any options. However, for adding pre-
processor definitions and include directories it is recommended to use
the more specific commands target_compile_definitions() and target_in-
clude_directories().
For directory-wide settings, there is the command add_compile_op-
tions().
For file-specific settings, there is the source file property COM-
PILE_OPTIONS.
target_include_directories
Add include directories to a target.
target_include_directories(<target> [SYSTEM] [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specifies include directories to use when compiling a given target.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER-
FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
<target>. (IMPORTED targets only support INTERFACE items.) The fol-
lowing arguments specify include directories.
Specified include directories may be absolute paths or relative paths.
Repeated calls for the same <target> append items in the order called.
If SYSTEM is specified, the compiler will be told the directories are
meant as system include directories on some platforms (signalling this
setting might achieve effects such as the compiler skipping warnings,
or these fixed-install system files not being considered in dependency
calculations - see compiler docs). If SYSTEM is used together with
PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
property will be populated with the specified directories.
Arguments to target_include_directories 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.
Include directories usage requirements commonly differ between the
build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN-
TERFACE generator expressions can be used to describe separate usage
requirements based on the usage location. Relative paths are allowed
within the INSTALL_INTERFACE expression and are interpreted relative to
the installation prefix. For example:
target_include_directories(mylib PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
Creating Relocatable Packages
Note that it is not advisable to populate the INSTALL_INTERFACE of the
INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
include directories of dependencies. That would hard-code into in-
stalled packages the include directory paths for dependencies as found
on the machine the package was made on.
The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
suitable for specifying the required include directories for headers
provided with the target itself, not those provided by the transitive
dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
Those dependencies should themselves be targets that specify their own
header locations in INTERFACE_INCLUDE_DIRECTORIES.
See the Creating Relocatable Packages section of the cmake-packages(7)
man leading -D on an item will be removed. Empty items are ignored.
For example, the following are all equivalent:
target_compile_definitions(foo PUBLIC FOO)
target_compile_definitions(foo PUBLIC -DFOO) # -D removed
target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
target_compile_features
Add expected compiler features to a target.
target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
Specifies compiler features required when compiling a given target. If
the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
then an error will be reported by CMake. If the use of the feature re-
quires an additional compiler flag, such as -std=gnu++11, the flag will
be added automatically.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the features. PRIVATE and PUBLIC items will populate the COM-
PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
populate the INTERFACE_COMPILE_FEATURES property of <target>. (IM-
PORTED targets only support INTERFACE items.) Repeated calls for the
same <target> append items.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
Arguments to target_compile_features may use generator expressions with
the syntax $<...>. See the cmake-generator-expressions(7) manual for
available expressions. See the cmake-compile-features(7) manual for
information on compile features and a list of supported compilers.
target_compile_options
Add compile options to a target.
target_compile_options(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
properties. These options are used when compiling the given <target>,
which must have been created by a command such as add_executable() or
add_library() and must not be an ALIAS target.
Arguments
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
(IMPORTED targets only support INTERFACE items.) The following argu-
ments specify compile options. Repeated calls for the same <target>
append items in the order called.
Arguments to target_compile_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.
The final set of compile or link options used for a target is construc-
ted by accumulating options from the current target and the usage re-
quirements of its dependencies. The set of options is de-duplicated to
avoid repetition. While beneficial for individual options, the de-du-
plication step can break up option groups. For example, -D A -D B be-
comes -D 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:-D A" "SHELL:-D B" becomes -D A
-D B.
See Also
This command can be used to add any options. However, for adding pre-
processor definitions and include directories it is recommended to use
the more specific commands target_compile_definitions() and target_in-
clude_directories().
For directory-wide settings, there is the command add_compile_op-
tions().
For file-specific settings, there is the source file property COM-
PILE_OPTIONS.
target_include_directories
Add include directories to a target.
target_include_directories(<target> [SYSTEM] [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specifies include directories to use when compiling a given target.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER-
FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
<target>. (IMPORTED targets only support INTERFACE items.) The fol-
lowing arguments specify include directories.
Specified include directories may be absolute paths or relative paths.
Repeated calls for the same <target> append items in the order called.
If SYSTEM is specified, the compiler will be told the directories are
meant as system include directories on some platforms (signalling this
setting might achieve effects such as the compiler skipping warnings,
or these fixed-install system files not being considered in dependency
calculations - see compiler docs). If SYSTEM is used together with
PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
property will be populated with the specified directories.
Arguments to target_include_directories 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.
Include directories usage requirements commonly differ between the
build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN-
TERFACE generator expressions can be used to describe separate usage
requirements based on the usage location. Relative paths are allowed
within the INSTALL_INTERFACE expression and are interpreted relative to
the installation prefix. For example:
target_include_directories(mylib PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
Creating Relocatable Packages
Note that it is not advisable to populate the INSTALL_INTERFACE of the
INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
include directories of dependencies. That would hard-code into in-
stalled packages the include directory paths for dependencies as found
on the machine the package was made on.
The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
suitable for specifying the required include directories for headers
provided with the target itself, not those provided by the transitive
dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
Those dependencies should themselves be targets that specify their own
header locations in INTERFACE_INCLUDE_DIRECTORIES.
See the Creating Relocatable Packages section of the cmake-packages(7)
man leading -D on an item will be removed. Empty items are ignored.
For example, the following are all equivalent:
target_compile_definitions(foo PUBLIC FOO)
target_compile_definitions(foo PUBLIC -DFOO) # -D removed
target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
target_compile_features
Add expected compiler features to a target.
target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
Specifies compiler features required when compiling a given target. If
the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
then an error will be reported by CMake. If the use of the feature re-
quires an additional compiler flag, such as -std=gnu++11, the flag will
be added automatically.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the features. PRIVATE and PUBLIC items will populate the COM-
PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
populate the INTERFACE_COMPILE_FEATURES property of <target>. (IM-
PORTED targets only support INTERFACE items.) Repeated calls for the
same <target> append items.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
Arguments to target_compile_features may use generator expressions with
the syntax $<...>. See the cmake-generator-expressions(7) manual for
available expressions. See the cmake-compile-features(7) manual for
information on compile features and a list of supported compilers.
target_compile_options
Add compile options to a target.
target_compile_options(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
properties. These options are used when compiling the given <target>,
which must have been created by a command such as add_executable() or
add_library() and must not be an ALIAS target.
Arguments
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
(IMPORTED targets only support INTERFACE items.) The following argu-
ments specify compile options. Repeated calls for the same <target>
append items in the order called.
Arguments to target_compile_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.
The final set of compile or link options used for a target is construc-
ted by accumulating options from the current target and the usage re-
quirements of its dependencies. The set of options is de-duplicated to
avoid repetition. While beneficial for individual options, the de-du-
plication step can break up option groups. For example, -D A -D B be-
comes -D 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:-D A" "SHELL:-D B" becomes -D A
-D B.
See Also
This command can be used to add any options. However, for adding pre-
processor definitions and include directories it is recommended to use
the more specific commands target_compile_definitions() and target_in-
clude_directories().
For directory-wide settings, there is the command add_compile_op-
tions().
For file-specific settings, there is the source file property COM-
PILE_OPTIONS.
target_include_directories
Add include directories to a target.
target_include_directories(<target> [SYSTEM] [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specifies include directories to use when compiling a given target.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER-
FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
<target>. (IMPORTED targets only support INTERFACE items.) The fol-
lowing arguments specify include directories.
Specified include directories may be absolute paths or relative paths.
Repeated calls for the same <target> append items in the order called.
If SYSTEM is specified, the compiler will be told the directories are
meant as system include directories on some platforms (signalling this
setting might achieve effects such as the compiler skipping warnings,
or these fixed-install system files not being considered in dependency
calculations - see compiler docs). If SYSTEM is used together with
PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
property will be populated with the specified directories.
Arguments to target_include_directories 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.
Include directories usage requirements commonly differ between the
build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN-
TERFACE generator expressions can be used to describe separate usage
requirements based on the usage location. Relative paths are allowed
within the INSTALL_INTERFACE expression and are interpreted relative to
the installation prefix. For example:
target_include_directories(mylib PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
Creating Relocatable Packages
Note that it is not advisable to populate the INSTALL_INTERFACE of the
INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
include directories of dependencies. That would hard-code into in-
stalled packages the include directory paths for dependencies as found
on the machine the package was made on.
The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
suitable for specifying the required include directories for headers
provided with the target itself, not those provided by the transitive
dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
Those dependencies should themselves be targets that specify their own
header locations in INTERFACE_INCLUDE_DIRECTORIES.
See the Creating Relocatable Packages section of the cmake-packages(7)
man leading -D on an item will be removed. Empty items are ignored.
For example, the following are all equivalent:
target_compile_definitions(foo PUBLIC FOO)
target_compile_definitions(foo PUBLIC -DFOO) # -D removed
target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
target_compile_features
Add expected compiler features to a target.
target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
Specifies compiler features required when compiling a given target. If
the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
then an error will be reported by CMake. If the use of the feature re-
quires an additional compiler flag, such as -std=gnu++11, the flag will
be added automatically.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the features. PRIVATE and PUBLIC items will populate the COM-
PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
populate the INTERFACE_COMPILE_FEATURES property of <target>. (IM-
PORTED targets only support INTERFACE items.) Repeated calls for the
same <target> append items.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
Arguments to target_compile_features may use generator expressions with
the syntax $<...>. See the cmake-generator-expressions(7) manual for
available expressions. See the cmake-compile-features(7) manual for
information on compile features and a list of supported compilers.
target_compile_options
Add compile options to a target.
target_compile_options(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
properties. These options are used when compiling the given <target>,
which must have been created by a command such as add_executable() or
add_library() and must not be an ALIAS target.
Arguments
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
(IMPORTED targets only support INTERFACE items.) The following argu-
ments specify compile options. Repeated calls for the same <target>
append items in the order called.
Arguments to target_compile_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.
The final set of compile or link options used for a target is construc-
ted by accumulating options from the current target and the usage re-
quirements of its dependencies. The set of options is de-duplicated to
avoid repetition. While beneficial for individual options, the de-du-
plication step can break up option groups. For example, -D A -D B be-
comes -D 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:-D A" "SHELL:-D B" becomes -D A
-D B.
See Also
This command can be used to add any options. However, for adding pre-
processor definitions and include directories it is recommended to use
the more specific commands target_compile_definitions() and target_in-
clude_directories().
For directory-wide settings, there is the command add_compile_op-
tions().
For file-specific settings, there is the source file property COM-
PILE_OPTIONS.
target_include_directories
Add include directories to a target.
target_include_directories(<target> [SYSTEM] [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specifies include directories to use when compiling a given target.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER-
FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
<target>. (IMPORTED targets only support INTERFACE items.) The fol-
lowing arguments specify include directories.
Specified include directories may be absolute paths or relative paths.
Repeated calls for the same <target> append items in the order called.
If SYSTEM is specified, the compiler will be told the directories are
meant as system include directories on some platforms (signalling this
setting might achieve effects such as the compiler skipping warnings,
or these fixed-install system files not being considered in dependency
calculations - see compiler docs). If SYSTEM is used together with
PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
property will be populated with the specified directories.
Arguments to target_include_directories 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.
Include directories usage requirements commonly differ between the
build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN-
TERFACE generator expressions can be used to describe separate usage
requirements based on the usage location. Relative paths are allowed
within the INSTALL_INTERFACE expression and are interpreted relative to
the installation prefix. For example:
target_include_directories(mylib PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
Creating Relocatable Packages
Note that it is not advisable to populate the INSTALL_INTERFACE of the
INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
include directories of dependencies. That would hard-code into in-
stalled packages the include directory paths for dependencies as found
on the machine the package was made on.
The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
suitable for specifying the required include directories for headers
provided with the target itself, not those provided by the transitive
dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
Those dependencies should themselves be targets that specify their own
header locations in INTERFACE_INCLUDE_DIRECTORIES.
See the Creating Relocatable Packages section of the cmake-packages(7)
man leading -D on an item will be removed. Empty items are ignored.
For example, the following are all equivalent:
target_compile_definitions(foo PUBLIC FOO)
target_compile_definitions(foo PUBLIC -DFOO) # -D removed
target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
target_compile_features
Add expected compiler features to a target.
target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
Specifies compiler features required when compiling a given target. If
the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
then an error will be reported by CMake. If the use of the feature re-
quires an additional compiler flag, such as -std=gnu++11, the flag will
be added automatically.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the features. PRIVATE and PUBLIC items will populate the COM-
PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
populate the INTERFACE_COMPILE_FEATURES property of <target>. (IM-
PORTED targets only support INTERFACE items.) Repeated calls for the
same <target> append items.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
Arguments to target_compile_features may use generator expressions with
the syntax $<...>. See the cmake-generator-expressions(7) manual for
available expressions. See the cmake-compile-features(7) manual for
information on compile features and a list of supported compilers.
target_compile_options
Add compile options to a target.
target_compile_options(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
properties. These options are used when compiling the given <target>,
which must have been created by a command such as add_executable() or
add_library() and must not be an ALIAS target.
Arguments
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
(IMPORTED targets only support INTERFACE items.) The following argu-
ments specify compile options. Repeated calls for the same <target>
append items in the order called.
Arguments to target_compile_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.
The final set of compile or link options used for a target is construc-
ted by accumulating options from the current target and the usage re-
quirements of its dependencies. The set of options is de-duplicated to
avoid repetition. While beneficial for individual options, the de-du-
plication step can break up option groups. For example, -D A -D B be-
comes -D 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:-D A" "SHELL:-D B" becomes -D A
-D B.
See Also
This command can be used to add any options. However, for adding pre-
processor definitions and include directories it is recommended to use
the more specific commands target_compile_definitions() and target_in-
clude_directories().
For directory-wide settings, there is the command add_compile_op-
tions().
For file-specific settings, there is the source file property COM-
PILE_OPTIONS.
target_include_directories
Add include directories to a target.
target_include_directories(<target> [SYSTEM] [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specifies include directories to use when compiling a given target.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER-
FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
<target>. (IMPORTED targets only support INTERFACE items.) The fol-
lowing arguments specify include directories.
Specified include directories may be absolute paths or relative paths.
Repeated calls for the same <target> append items in the order called.
If SYSTEM is specified, the compiler will be told the directories are
meant as system include directories on some platforms (signalling this
setting might achieve effects such as the compiler skipping warnings,
or these fixed-install system files not being considered in dependency
calculations - see compiler docs). If SYSTEM is used together with
PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
property will be populated with the specified directories.
Arguments to target_include_directories 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.
Include directories usage requirements commonly differ between the
build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN-
TERFACE generator expressions can be used to describe separate usage
requirements based on the usage location. Relative paths are allowed
within the INSTALL_INTERFACE expression and are interpreted relative to
the installation prefix. For example:
target_include_directories(mylib PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
Creating Relocatable Packages
Note that it is not advisable to populate the INSTALL_INTERFACE of the
INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
include directories of dependencies. That would hard-code into in-
stalled packages the include directory paths for dependencies as found
on the machine the package was made on.
The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
suitable for specifying the required include directories for headers
provided with the target itself, not those provided by the transitive
dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
Those dependencies should themselves be targets that specify their own
header locations in INTERFACE_INCLUDE_DIRECTORIES.
See the Creating Relocatable Packages section of the cmake-packages(7)
man leading -D on an item will be removed. Empty items are ignored.
For example, the following are all equivalent:
target_compile_definitions(foo PUBLIC FOO)
target_compile_definitions(foo PUBLIC -DFOO) # -D removed
target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
target_compile_features
Add expected compiler features to a target.
target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
Specifies compiler features required when compiling a given target. If
the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
then an error will be reported by CMake. If the use of the feature re-
quires an additional compiler flag, such as -std=gnu++11, the flag will
be added automatically.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the features. PRIVATE and PUBLIC items will populate the COM-
PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
populate the INTERFACE_COMPILE_FEATURES property of <target>. (IM-
PORTED targets only support INTERFACE items.) Repeated calls for the
same <target> append items.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
Arguments to target_compile_features may use generator expressions with
the syntax $<...>. See the cmake-generator-expressions(7) manual for
available expressions. See the cmake-compile-features(7) manual for
information on compile features and a list of supported compilers.
target_compile_options
Add compile options to a target.
target_compile_options(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
properties. These options are used when compiling the given <target>,
which must have been created by a command such as add_executable() or
add_library() and must not be an ALIAS target.
Arguments
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
(IMPORTED targets only support INTERFACE items.) The following argu-
ments specify compile options. Repeated calls for the same <target>
append items in the order called.
Arguments to target_compile_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.
The final set of compile or link options used for a target is construc-
ted by accumulating options from the current target and the usage re-
quirements of its dependencies. The set of options is de-duplicated to
avoid repetition. While beneficial for individual options, the de-du-
plication step can break up option groups. For example, -D A -D B be-
comes -D 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:-D A" "SHELL:-D B" becomes -D A
-D B.
See Also
This command can be used to add any options. However, for adding pre-
processor definitions and include directories it is recommended to use
the more specific commands target_compile_definitions() and target_in-
clude_directories().
For directory-wide settings, there is the command add_compile_op-
tions().
For file-specific settings, there is the source file property COM-
PILE_OPTIONS.
target_include_directories
Add include directories to a target.
target_include_directories(<target> [SYSTEM] [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specifies include directories to use when compiling a given target.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER-
FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
<target>. (IMPORTED targets only support INTERFACE items.) The fol-
lowing arguments specify include directories.
Specified include directories may be absolute paths or relative paths.
Repeated calls for the same <target> append items in the order called.
If SYSTEM is specified, the compiler will be told the directories are
meant as system include directories on some platforms (signalling this
setting might achieve effects such as the compiler skipping warnings,
or these fixed-install system files not being considered in dependency
calculations - see compiler docs). If SYSTEM is used together with
PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
property will be populated with the specified directories.
Arguments to target_include_directories 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.
Include directories usage requirements commonly differ between the
build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN-
TERFACE generator expressions can be used to describe separate usage
requirements based on the usage location. Relative paths are allowed
within the INSTALL_INTERFACE expression and are interpreted relative to
the installation prefix. For example:
target_include_directories(mylib PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
Creating Relocatable Packages
Note that it is not advisable to populate the INSTALL_INTERFACE of the
INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
include directories of dependencies. That would hard-code into in-
stalled packages the include directory paths for dependencies as found
on the machine the package was made on.
The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
suitable for specifying the required include directories for headers
provided with the target itself, not those provided by the transitive
dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
Those dependencies should themselves be targets that specify their own
header locations in INTERFACE_INCLUDE_DIRECTORIES.
See the Creating Relocatable Packages section of the cmake-packages(7)
man leading -D on an item will be removed. Empty items are ignored.
For example, the following are all equivalent:
target_compile_definitions(foo PUBLIC FOO)
target_compile_definitions(foo PUBLIC -DFOO) # -D removed
target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
target_compile_features
Add expected compiler features to a target.
target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
Specifies compiler features required when compiling a given target. If
the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
then an error will be reported by CMake. If the use of the feature re-
quires an additional compiler flag, such as -std=gnu++11, the flag will
be added automatically.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the features. PRIVATE and PUBLIC items will populate the COM-
PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
populate the INTERFACE_COMPILE_FEATURES property of <target>. (IM-
PORTED targets only support INTERFACE items.) Repeated calls for the
same <target> append items.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
Arguments to target_compile_features may use generator expressions with
the syntax $<...>. See the cmake-generator-expressions(7) manual for
available expressions. See the cmake-compile-features(7) manual for
information on compile features and a list of supported compilers.
target_compile_options
Add compile options to a target.
target_compile_options(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
properties. These options are used when compiling the given <target>,
which must have been created by a command such as add_executable() or
add_library() and must not be an ALIAS target.
Arguments
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
(IMPORTED targets only support INTERFACE items.) The following argu-
ments specify compile options. Repeated calls for the same <target>
append items in the order called.
Arguments to target_compile_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.
The final set of compile or link options used for a target is construc-
ted by accumulating options from the current target and the usage re-
quirements of its dependencies. The set of options is de-duplicated to
avoid repetition. While beneficial for individual options, the de-du-
plication step can break up option groups. For example, -D A -D B be-
comes -D 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:-D A" "SHELL:-D B" becomes -D A
-D B.
See Also
This command can be used to add any options. However, for adding pre-
processor definitions and include directories it is recommended to use
the more specific commands target_compile_definitions() and target_in-
clude_directories().
For directory-wide settings, there is the command add_compile_op-
tions().
For file-specific settings, there is the source file property COM-
PILE_OPTIONS.
target_include_directories
Add include directories to a target.
target_include_directories(<target> [SYSTEM] [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specifies include directories to use when compiling a given target.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER-
FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
<target>. (IMPORTED targets only support INTERFACE items.) The fol-
lowing arguments specify include directories.
Specified include directories may be absolute paths or relative paths.
Repeated calls for the same <target> append items in the order called.
If SYSTEM is specified, the compiler will be told the directories are
meant as system include directories on some platforms (signalling this
setting might achieve effects such as the compiler skipping warnings,
or these fixed-install system files not being considered in dependency
calculations - see compiler docs). If SYSTEM is used together with
PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
property will be populated with the specified directories.
Arguments to target_include_directories 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.
Include directories usage requirements commonly differ between the
build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN-
TERFACE generator expressions can be used to describe separate usage
requirements based on the usage location. Relative paths are allowed
within the INSTALL_INTERFACE expression and are interpreted relative to
the installation prefix. For example:
target_include_directories(mylib PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
Creating Relocatable Packages
Note that it is not advisable to populate the INSTALL_INTERFACE of the
INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
include directories of dependencies. That would hard-code into in-
stalled packages the include directory paths for dependencies as found
on the machine the package was made on.
The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
suitable for specifying the required include directories for headers
provided with the target itself, not those provided by the transitive
dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
Those dependencies should themselves be targets that specify their own
header locations in INTERFACE_INCLUDE_DIRECTORIES.
See the Creating Relocatable Packages section of the cmake-packages(7)
man leading -D on an item will be removed. Empty items are ignored.
For example, the following are all equivalent:
target_compile_definitions(foo PUBLIC FOO)
target_compile_definitions(foo PUBLIC -DFOO) # -D removed
target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
target_compile_features
Add expected compiler features to a target.
target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
Specifies compiler features required when compiling a given target. If
the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
then an error will be reported by CMake. If the use of the feature re-
quires an additional compiler flag, such as -std=gnu++11, the flag will
be added automatically.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the features. PRIVATE and PUBLIC items will populate the COM-
PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
populate the INTERFACE_COMPILE_FEATURES property of <target>. (IM-
PORTED targets only support INTERFACE items.) Repeated calls for the
same <target> append items.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
Arguments to target_compile_features may use generator expressions with
the syntax $<...>. See the cmake-generator-expressions(7) manual for
available expressions. See the cmake-compile-features(7) manual for
information on compile features and a list of supported compilers.
target_compile_options
Add compile options to a target.
target_compile_options(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
properties. These options are used when compiling the given <target>,
which must have been created by a command such as add_executable() or
add_library() and must not be an ALIAS target.
Arguments
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
(IMPORTED targets only support INTERFACE items.) The following argu-
ments specify compile options. Repeated calls for the same <target>
append items in the order called.
Arguments to target_compile_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.
The final set of compile or link options used for a target is construc-
ted by accumulating options from the current target and the usage re-
quirements of its dependencies. The set of options is de-duplicated to
avoid repetition. While beneficial for individual options, the de-du-
plication step can break up option groups. For example, -D A -D B be-
comes -D 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:-D A" "SHELL:-D B" becomes -D A
-D B.
See Also
This command can be used to add any options. However, for adding pre-
processor definitions and include directories it is recommended to use
the more specific commands target_compile_definitions() and target_in-
clude_directories().
For directory-wide settings, there is the command add_compile_op-
tions().
For file-specific settings, there is the source file property COM-
PILE_OPTIONS.
target_include_directories
Add include directories to a target.
target_include_directories(<target> [SYSTEM] [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specifies include directories to use when compiling a given target.
The named <target> must have been created by a command such as add_exe-
cutable() or add_library() and must not be an ALIAS target.
If BEFORE is specified, the content will be prepended to the property
instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
scope of the following arguments. PRIVATE and PUBLIC items will popu-
late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER-
FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
<target>. (IMPORTED targets only support INTERFACE items.) The fol-
lowing arguments specify include directories.
Specified include directories may be absolute paths or relative paths.
Repeated calls for the same <target> append items in the order called.
If SYSTEM is specified, the compiler will be told the directories are
meant as system include directories on some platforms (signalling this
setting might achieve effects such as the compiler skipping warnings,
or these fixed-install system files not being considered in dependency
calculations - see compiler docs). If SYSTEM is used together with
PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
property will be populated with the specified directories.
Arguments to target_include_directories 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.
Include directories usage requirements commonly differ between the
build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN-
TERFACE generator expressions can be used to describe separate usage
requirements based on the usage location. Relative paths are allowed
within the INSTALL_INTERFACE expression and are interpreted relative to
the installation prefix. For example:
target_include_directories(mylib PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
Creating Relocatable Packages
Note that it is not advisable to populate the INSTALL_INTERFACE of the
INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
include directories of dependencies. That would hard-code into in-
stalled packages the include directory paths for dependencies as found
on the machine the package was made on.
The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
suitable for specifying the required include directories for headers
provided with the target itself, not those provided by the transitive
dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
Those dependencies should themselves be targets that specify their own
header locations in INTERFACE_INCLUDE_DIRECTORIES.
See the Creating Relocatable Packages section of the cmake-packages(7)
man leading -D on an item will be removed. Empty items are ignored.
For example, the following are all equivalent:
tathe last ctest_start() call.
Append semantics are defined by the dashboard server in use.
This does not cause results to be appended to a .xml file
produced by a previous call to this command.
START <start-number>
Specify the beginning of a range of test numbers.
END <end-number>
Specify the end of a range of test numbers.
STRIDE <stride-number>
Specify the stride by which to step across a range of test numbers.
EXCLUDE <exclude-regex>
Specify a regular expression matching test names to exclude.
INCLUDE <include-regex>
Specify a regular expression matching test names to include.
Tests not matching this expression are excluded.
EXCLUDE_LABEL <label-exclude-regex>
Specify a regular expression matching test labels to exclude.
INCLUDE_LABEL <label-include-regex>
Specify a regular expression matching test labels to include.
Tests not matching this expression are excluded.
EXCLUDE_FIXTURE <regex>
If a test in the set of tests to be executed requires a particular fixture,
that fixtures setup and cleanup tests would normally be added to the test
set automatically. This option prevents adding setup or cleanup tests for
fixtures matching the <regex>. Note that all other fixture behavior is
retained, including test dependencies and skipping tests that have fixture
setup tests that fail.
EXCLUDE_FIXTURE_SETUP <regex>
Same as EXCLUDE_FIXTURE except only matching setup tests are excluded.
EXCLUDE_FIXTURE_CLEANUP <regex>
Same as EXCLUDE_FIXTURE except only matching cleanup tests are excluded.
PARALLEL_LEVEL <level>
Specify a positive number representing the number of tests to
be run in parallel.
RESOURCE_SPEC_FILE <file>
Specify a
resource specification file. See
ctest-resource-allocation for more information.
TEST_LOAD <threshold>
While running tests in parallel, try not to start tests when they
may cause the CPU load to pass above a given threshold. If not
specified the CTEST_TEST_LOAD variable will be checked,
and then the --test-load command-line argument to ctest(1).
See also the TestLoad setting in the CTest Test Step.
REPEAT <mode>:<n>
Run tests repeatedly based on the given <mode> up to <n> times.
The modes are:
UNTIL_FAIL
Require each test to run <n> times without failing in order to pass.
This is useful in finding sporadic failures in test cases.
UNTIL_PASS
Allow each test to run up to <n> times in order to pass.
Repeats tests if they fail for any reason.
This is useful in tolerating sporadic failures in test cases.
AFTER_TIMEOUT
Allow each test to run up to <n> times in order to pass.
Repeats tests only if they timeout.
This is useful in tolerating sporadic timeouts in test cases
on busy machines.
SCHEDULE_RANDOM <ON|OFF>
Launch tests in a random order. This may be useful for detecting
implicit test dependencies.
STOP_ON_FAILURE
Stop the execution of the tests once one has failed.
STOP_TIME <time-of-day>
Specify a time of day at which the tests should all stop running.
RETURN_VALUE <result-var>
Store in the <result-var> variable 0 if all tests passed.
Store non-zero if anything went wrong.
CAPTURE_CMAKE_ERROR <result-var>
Store in the <result-var> variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
QUIET Suppress any CTest-specific non-error messages that would have otherwise
been printed to the console. Output from the underlying test command is not
affected. Summary info detailing the percentage of passing tests is also
unaffected by the QUIET option.
See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE
and CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
ctest_update
Perform the CTest Update Step as a Dashboard Client.
ctest_update([SOURCE <source-dir>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[QUIET])
Update the source tree from version control and record results in Up-
date.xml for submission with the ctest_submit() command.
The options are:
SOURCE <source-dir>
Specify the source directory. If not given, the
CTEST_SOURCE_DIRECTORY variable is used.
RETURN_VALUE <result-var>
Store in the <result-var> variable the number of files updated
or -1 on error.
CAPTURE_CMAKE_ERROR <result-var>
Store in the <result-var> variable -1 if there are any errors
running the command and prevent ctest from returning non-zero if
an error occurs.
QUIET Tell CTest to suppress most non-error messages that it would
have otherwise printed to the console. CTest will still report
the new revision of the repository and any conflicting files
that were found.
The update always follows the version control branch currently checked
out in the source directory. See the CTest Update Step documentation
for information about variables that change the behavior of ctest_up-
date().
ctest_upload
Upload files to a dashboard server as a Dashboard Client.
ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
The options are:
FILES <file>...
Specify a list of files to be sent along with the build results
to the dashboard server.
QUIET Suppress any CTest-specific non-error output that would have
been printed to the console otherwise.
CAPTURE_CMAKE_ERROR <result-var>
Store in the <result-var> variable -1 if there are any errors
running the command and prevent ctest from returning non-zero if
an error occurs.
DEPRECATED COMMANDS
These commands are deprecated and are only made available to maintain
backward compatibility. The documentation of each command states the
CMake version in which it was deprecated. Do not use these commands in
new code.
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.
exec_program
Deprecated since version 3.0: Use the execute_process() command in-
stead.
Run an executable program during the processing of the CMakeList.txt
file.
exec_program(Executable [directory in which to run]
[ARGS <arguments to executable>]
[OUTPUT_VARIABLE <var>]
[RETURN_VALUE <var>])
The executable is run in the optionally specified directory. The exe-
cutable can include arguments if it is double quoted, but it is better
to use the optional ARGS argument to specify arguments to the program.
This is because cmake will then be able to escape spaces in the exe-
cutable path. An optional argument OUTPUT_VARIABLE specifies a vari-
able in which to store the output. To capture the return value of the
execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is specified,
then no output will go to the stdout/stderr of the console running
cmake.
export_library_dependencies
Disallowed since version 3.0. See CMake Policy CMP0033.
Use install(EXPORT) or export() command.
This command generates an old-style library dependencies file.
Projects requiring CMake 2.6 or later shthe last ctest_start() call.
Append semantics are defined by the dashboard server in use. This does
not cause results to be appended to a .xml file produced by a previous
call to this command.
START <start-number>
Specify the beginning of a range of test numbers.
END <end-number>
Specify the end of a range of test numbers.
STRIDE <stride-number>
Specify the stride by which to step across a range of test num-
bers.
EXCLUDE <exclude-regex>
Specify a regular expression matching test names to exclude.
INCLUDE <include-regex>
Specify a regular expression matching test names to include.
Tests not matching this expression are excluded.
EXCLUDE_LABEL <label-exclude-regex>
Specify a regular expression matching test labels to exclude.
INCLUDE_LABEL <label-include-regex>
Specify a regular expression matching test labels to include.
Tests not matching this expression are excluded.
EXCLUDE_FIXTURE <regex>
If a test in the set of tests to be executed requires a particu-
lar fixture, that fixtures setup and cleanup tests would nor-
mally be added to the test set automatically. This option pre-
vents adding setup or cleanup tests for fixtures matching the
<regex>. Note that all other fixture behavior is retained, in-
cluding test dependencies and skipping tests that have fixture
setup tests that fail.
EXCLUDE_FIXTURE_SETUP <regex>
Same as EXCLUDE_FIXTURE except only matching setup tests are ex-
cluded.
EXCLUDE_FIXTURE_CLEANUP <regex>
Same as EXCLUDE_FIXTURE except only matching cleanup tests are
excluded.
PARALLEL_LEVEL <level>
Specify a positive number representing the number of tests to be
run in parallel.
RESOURCE_SPEC_FILE <file>
Specify a resource specification file. See ctest-resource-allo-
cation for more information.
TEST_LOAD <threshold>
While running tests in parallel, try not to start tests when
they may cause the CPU load to pass above a given threshold. If
not specified the CTEST_TEST_LOAD variable will be checked, and
then the --test-load command-line argument to ctest(1). See
also the TestLoad setting in the CTest Test Step.
REPEAT <mode>:<n>
Run tests repeatedly based on the given <mode> up to <n> times.
The modes are:
UNTIL_FAIL
Require each test to run <n> times without failing in or-
der to pass. This is useful in finding sporadic failures
in test cases.
UNTIL_PASS
Allow each test to run up to <n> times in order to pass.
Repeats tests if they fail for any reason. This is use-
ful in tolerating sporadic failures in test cases.
AFTER_TIMEOUT
Allow each test to run up to <n> times in order to pass.
Repeats tests only if they timeout. This is useful in
tolerating sporadic timeouts in test cases on busy ma-
chines.
SCHEDULE_RANDOM <ON|OFF>
Launch tests in a random order. This may be useful for detect-
ing implicit test dependencies.
STOP_ON_FAILURE
Stop the execution of the tests once one has failed.
STOP_TIME <time-of-day>
Specify a time of day at which the tests should all stop run-
ning.
RETURN_VALUE <result-var>
Store in the <result-var> variable 0 if all tests passed. Store
non-zero if anything went wrong.
CAPTURE_CMAKE_ERROR <result-var>
Store in the <result-var> variable -1 if there are any errors
running the command and prevent ctest from returning non-zero if
an error occurs.
QUIET Suppress any CTest-specific non-error messages that would have
otherwise been printed to the console. Output from the underly-
ing test command is not affected. Summary info detailing the
percentage of passing tests is also unaffected by the QUIET op-
tion.
See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE and
CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
ctest_update
Perform the CTest Update Step as a Dashboard Client.
ctest_update([SOURCE <source-dir>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[QUIET])
Update the source tree from version control and record results in Up-
date.xml for submission with the ctest_submit() command.
The options are:
SOURCE <source-dir>
Specify the source directory. If not given, the
CTEST_SOURCE_DIRECTORY variable is used.
RETURN_VALUE <result-var>
Store in the <result-var> variable the number of files updated
or -1 on error.
CAPTURE_CMAKE_ERROR <result-var>
Store in the <result-var> variable -1 if there are any errors
running the command and prevent ctest from returning non-zero if
an error occurs.
QUIET Tell CTest to suppress most non-error messages that it would
have otherwise printed to the console. CTest will still report
the new revision of the repository and any conflicting files
that were found.
The update always follows the version control branch currently checked
out in the source directory. See the CTest Update Step documentation
for information about variables that change the behavior of ctest_up-
date().
ctest_upload
Upload files to a dashboard server as a Dashboard Client.
ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
The options are:
FILES <file>...
Specify a list of files to be sent along with the build results
to the dashboard server.
QUIET Suppress any CTest-specific non-error output that would have
been printed to the console otherwise.
CAPTURE_CMAKE_ERROR <result-var>
Store in the <result-var> variable -1 if there are any errors
running the command and prevent ctest from returning non-zero if
an error occurs.
DEPRECATED COMMANDS
These commands are deprecated and are only made available to maintain
backward compatibility. The documentation of each command states the
CMake version in which it was deprecated. Do not use these commands in
new code.
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.
exec_program
Deprecated since version 3.0: Use the execute_process() command in-
stead.
Run an executable program during the processing of the CMakeList.txt
file.
exec_program(Executable [directory in which to run]
[ARGS <arguments to executable>]
[OUTPUT_VARIABLE <var>]
[RETURN_VALUE <var>])
The executable is run in the optionally specified directory. The exe-
cutable can include arguments if it is double quoted, but it is better
to use the optional ARGS argument to specify arguments to the program.
This is because cmake will then be able to escape spaces in the exe-
cutable path. An optional argument OUTPUT_VARIABLE specifies a vari-
able in which to store the output. To capture the return value of the
execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is specified,
then no output will go to the stdout/stderr of the console running
cmake.
export_library_dependencies
Disallowed since version 3.0. See CMake Policy CMP0033.
Use install(EXPORT) or export() command.
This command generates an old-style library dependencies file.
Projects requiring CMake 2.6 or later shthe last ctest_start() call.
Append semantics are defined by the dashboard server in use. This does
not cause results to be appended to a .xml file produced by a previous
call to this command.
START <start-number>
Specify the beginning of a range of test numbers.
END <end-number>
Specify the end of a range of test numbers.
STRIDE <stride-number>
Specify the stride by which to step across a range of test num-
bers.
EXCLUDE <exclude-regex>
Specify a regular expression matching test names to exclude.
INCLUDE <include-regex>
Specify a regular expression matching test names to include.
Tests not matching this expression are excluded.
EXCLUDE_LABEL <label-exclude-regex>
Specify a regular expression matching test labels to exclude.
INCLUDE_LABEL <label-include-regex>
Specify a regular expression matching test labels to include.
Tests not matching this expression are excluded.
EXCLUDE_FIXTURE <regex>
If a test in the set of tests to be executed requires a particu-
lar fixture, that fixtures setup and cleanup tests would nor-
mally be added to the test set automatically. This option pre-
vents adding setup or cleanup tests for fixtures matching the
<regex>. Note that all other fixture behavior is retained, in-
cluding test dependencies and skipping tests that have fixture
setup tests that fail.
EXCLUDE_FIXTURE_SETUP <regex>
Same as EXCLUDE_FIXTURE except only matching setup tests are ex-
cluded.
EXCLUDE_FIXTURE_CLEANUP <regex>
Same as EXCLUDE_FIXTURE except only matching cleanup tests are
excluded.
PARALLEL_LEVEL <level>
Specify a positive number representing the number of tests to be
run in parallel.
RESOURCE_SPEC_FILE <file>
Specify a resource specification file. See ctest-resource-allo-
cation for more information.
TEST_LOAD <threshold>
While running tests in parallel, try not to start tests when
they may cause the CPU load to pass above a given threshold. If
not specified the CTEST_TEST_LOAD variable will be checked, and
then the --test-load command-line argument to ctest(1). See
also the TestLoad setting in the CTest Test Step.
REPEAT <mode>:<n>
Run tests repeatedly based on the given <mode> up to <n> times.
The modes are:
UNTIL_FAIL
Require each test to run <n> times without failing in or-
der to pass. This is useful in finding sporadic failures
in test cases.
UNTIL_PASS
Allow each test to run up to <n> times in order to pass.
Repeats tests if they fail for any reason. This is use-
ful in tolerating sporadic failures in test cases.
AFTER_TIMEOUT
Allow each test to run up to <n> times in order to pass.
Repeats tests only if they timeout. This is useful in
tolerating sporadic timeouts in test cases on busy ma-
chines.
SCHEDULE_RANDOM <ON|OFF>
Launch tests in a random order. This may be useful for detect-
ing implicit test dependencies.
STOP_ON_FAILURE
Stop the execution of the tests once one has failed.
STOP_TIME <time-of-day>
Specify a time of day at which the tests should all stop run-
ning.
RETURN_VALUE <result-var>
Store in the <result-var> variable 0 if all tests passed. Store
non-zero if anything went wrong.
CAPTURE_CMAKE_ERROR <result-var>
Store in the <result-var> variable -1 if there are any errors
running the command and prevent ctest from returning non-zero if
an error occurs.
QUIET Suppress any CTest-specific non-error messages that would have
otherwise been printed to the console. Output from the underly-
ing test command is not affected. Summary info detailing the
percentage of passing tests is also unaffected by the QUIET op-
tion.
See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE and
CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
ctest_update
Perform the CTest Update Step as a Dashboard Client.
ctest_update([SOURCE <source-dir>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[QUIET])
Update the source tree from version control and record results in Up-
date.xml for submission with the ctest_submit() command.
The options are:
SOURCE <source-dir>
Specify the source directory. If not given, the
CTEST_SOURCE_DIRECTORY variable is used.
RETURN_VALUE <result-var>
Store in the <result-var> variable the number of files updated
or -1 on error.
CAPTURE_CMAKE_ERROR <result-var>
Store in the <result-var> variable -1 if there are any errors
running the command and prevent ctest from returning non-zero if
an error occurs.
QUIET Tell CTest to suppress most non-error messages that it would
have otherwise printed to the console. CTest will still report
the new
3.18.4 September 13, 2021 CMAKE-COMMANDS(7)
Czas wygenerowania: 0.00940 sek.
Created with the man page lookup class by Andrew Collington.
Based on a C man page viewer by Vadim Pavlov
Unicode soft-hyphen fix (as used by RedHat) by Dan Edwards
Some optimisations by Eli Argon
Caching idea and code contribution by James Richardson
Copyright © 2003-2025 Linux.pl
Hosted by Hosting Linux.pl