android_add_test_data

android_add_test_data(<test-name>
  [FILES <files>...] [FILES_DEST <device-dir>]
  [LIBS <libs>...]   [LIBS_DEST <device-dir>]
  [DEVICE_OBJECT_STORE <device-dir>]
  [DEVICE_TEST_DIR <device-dir>]
  [NO_LINK_REGEX <strings>...]
  )

The android_add_test_data function is used to copy files and libraries needed to run project-specific tests. On the host operating system, this is done at build time. For on-device testing, the files are loaded onto the device by the manufactured test at run time.

This function accepts the following named parameters:

check_c_compiler_flag

check_c_compiler_flag(<flag> <var>)

Check that the <flag> is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry named <var>.

check_compiler_flag

check_compiler_flag(<lang> <flag> <var>)

check_c_source_compiles

check_c_source_compiles(<code> <resultVar>
                        [FAIL_REGEX <regex1> [<regex2>...]])

Check that the source supplied in <code> can be compiled as a C source file and linked as an executable (so it must contain at least a main() function). The result will be stored in the internal cache variable specified by <resultVar>, with a boolean true value for success and boolean false for failure. If FAIL_REGEX is provided, then failure is determined by checking if anything in the output matches any of the specified regular expressions.

The underlying check is performed by the try_compile() command. The compile and link commands can be influenced by setting any of the following variables prior to calling check_c_source_compiles():

The check is only performed once, with the result cached in the variable named by <resultVar>. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the <code> changes. In order to force the check to be re-evaluated, the variable named by <resultVar> must be manually removed from the cache.

check_c_source_runs

check_c_source_runs(<code> <resultVar>)

Check that the source supplied in <code> can be compiled as a C source file, linked as an executable and then run. The <code> must contain at least a main() function. If the <code> could be built and run successfully, the internal cache variable specified by <resultVar> will be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message).

The underlying check is performed by the try_run() command. The compile and link commands can be influenced by setting any of the following variables prior to calling check_c_source_runs():

The check is only performed once, with the result cached in the variable named by <resultVar>. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the <code> changes. In order to force the check to be re-evaluated, the variable named by <resultVar> must be manually removed from the cache.

check_cxx_compiler_flag

check_cxx_compiler_flag(<flag> <var>)

Check that the <flag> is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry named <var>.

check_cxx_source_compiles

check_cxx_source_compiles(<code> <resultVar>
                          [FAIL_REGEX <regex1> [<regex2>...]])

Check that the source supplied in <code> can be compiled as a C++ source file and linked as an executable (so it must contain at least a main() function). The result will be stored in the internal cache variable specified by <resultVar>, with a boolean true value for success and boolean false for failure. If FAIL_REGEX is provided, then failure is determined by checking if anything in the output matches any of the specified regular expressions.

The underlying check is performed by the try_compile() command. The compile and link commands can be influenced by setting any of the following variables prior to calling check_cxx_source_compiles():

The check is only performed once, with the result cached in the variable named by <resultVar>. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the <code> changes. In order to force the check to be re-evaluated, the variable named by <resultVar> must be manually removed from the cache.

check_cxx_source_runs

check_cxx_source_runs(<code> <resultVar>)

Check that the source supplied in <code> can be compiled as a C++ source file, linked as an executable and then run. The <code> must contain at least a main() function. If the <code> could be built and run successfully, the internal cache variable specified by <resultVar> will be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message).

The underlying check is performed by the try_run() command. The compile and link commands can be influenced by setting any of the following variables prior to calling check_cxx_source_runs():

The check is only performed once, with the result cached in the variable named by <resultVar>. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the <code> changes. In order to force the check to be re-evaluated, the variable named by <resultVar> must be manually removed from the cache.

check_cxx_symbol_exists

check_cxx_symbol_exists(<symbol> <files> <variable>)

Check that the <symbol> is available after including given header <files> and store the result in a <variable>. Specify the list of files in one argument as a semicolon-separated list. check_cxx_symbol_exists() can be used to check for symbols as seen by the C++ compiler, as opposed to check_symbol_exists(), which always uses the C compiler.

If the header files define the symbol as a macro it is considered available and assumed to work. If the header files declare the symbol as a function or variable then the symbol must also be available for linking. If the symbol is a type, enum value, or C++ template it will not be recognized: consider using the CheckTypeSize or CheckSourceCompiles module instead.

CMAKE_REQUIRED_FLAGS

string of compile command line flags.

CMAKE_REQUIRED_DEFINITIONS

a ;-list of macros to define (-DFOO=bar).

CMAKE_REQUIRED_INCLUDES

a ;-list of header search paths to pass to the compiler.

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14: a ;-list of options to add to the link command.

CMAKE_REQUIRED_LIBRARIES

a ;-list of libraries to add to the link command. See policy CMP0075.

CMAKE_REQUIRED_QUIET

New in version 3.1: execute quietly without messages.

check_fortran_compiler_flag

check_fortran_compiler_flag(<flag> <var>)

Check that the <flag> is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry named <var>.

CHECK_FORTRAN_FUNCTION_EXISTS

CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>)

where

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14: A ;-list of options to add to the link command (see try_compile() for further details).

CMAKE_REQUIRED_LIBRARIES

A ;-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see try_compile() for further details).

check_fortran_source_compiles

check_fortran_source_compiles(<code> <resultVar>
    [FAIL_REGEX <regex>...]
    [SRC_EXT <extension>]
)

Checks that the source supplied in <code> can be compiled as a Fortran source file and linked as an executable. The <code> must be a Fortran program containing at least an end statement--for example:

check_fortran_source_compiles("character :: b; error stop b; end" F2018ESTOPOK SRC_EXT F90)

This command can help avoid costly build processes when a compiler lacks support for a necessary feature, or a particular vendor library is not compatible with the Fortran compiler version being used. This generate-time check may advise the user of such before the main build process. See also the check_fortran_source_runs() command to actually run the compiled code.

The result will be stored in the internal cache variable <resultVar>, with a boolean true value for success and boolean false for failure.

If FAIL_REGEX is provided, then failure is determined by checking if anything in the output matches any of the specified regular expressions.

By default, the test source file will be given a .F file extension. The SRC_EXT option can be used to override this with .<extension> instead-- .F90 is a typical choice.

The underlying check is performed by the try_compile() command. The compile and link commands can be influenced by setting any of the following variables prior to calling check_fortran_source_compiles():

The check is only performed once, with the result cached in the variable named by <resultVar>. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the <code> changes. In order to force the check to be re-evaluated, the variable named by <resultVar> must be manually removed from the cache.

check_fortran_source_runs

check_fortran_source_runs(<code> <resultVar>
    [SRC_EXT <extension>])

Check that the source supplied in <code> can be compiled as a Fortran source file, linked as an executable and then run. The <code> must be a Fortran program containing at least an end statement--for example:

check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK)

This command can help avoid costly build processes when a compiler lacks support for a necessary feature, or a particular vendor library is not compatible with the Fortran compiler version being used. Some of these failures only occur at runtime instead of linktime, and a trivial runtime example can catch the issue before the main build process.

If the <code> could be built and run successfully, the internal cache variable specified by <resultVar> will be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message).

By default, the test source file will be given a .F90 file extension. The SRC_EXT option can be used to override this with .<extension> instead.

The underlying check is performed by the try_run() command. The compile and link commands can be influenced by setting any of the following variables prior to calling check_fortran_source_runs():

The check is only performed once, with the result cached in the variable named by <resultVar>. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the <code> changes. In order to force the check to be re-evaluated, the variable named by <resultVar> must be manually removed from the cache.

check_function_exists

check_function_exists(<function> <variable>)

Checks that the <function> is provided by libraries on the system and store the result in a <variable>, which will be created as an internal cache variable.

CMAKE_REQUIRED_FLAGS

string of compile command line flags.

CMAKE_REQUIRED_DEFINITIONS

a ;-list of macros to define (-DFOO=bar).

CMAKE_REQUIRED_INCLUDES

a ;-list of header search paths to pass to the compiler.

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14: a ;-list of options to add to the link command.

CMAKE_REQUIRED_LIBRARIES

a ;-list of libraries to add to the link command. See policy CMP0075.

CMAKE_REQUIRED_QUIET

New in version 3.1: execute quietly without messages.

CHECK_INCLUDE_FILE_CXX

CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>])

Check if the given <include> file may be included in a CXX source file and store the result in an internal cache entry named <variable>. The optional third argument may be used to add compilation flags to the check (or use CMAKE_REQUIRED_FLAGS below).

CMAKE_REQUIRED_FLAGS

string of compile command line flags.

CMAKE_REQUIRED_DEFINITIONS

a ;-list of macros to define (-DFOO=bar).

CMAKE_REQUIRED_INCLUDES

a ;-list of header search paths to pass to the compiler.

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14: a ;-list of options to add to the link command.

CMAKE_REQUIRED_LIBRARIES

a ;-list of libraries to add to the link command. See policy CMP0075.

CMAKE_REQUIRED_QUIET

New in version 3.1: execute quietly without messages.

CHECK_INCLUDE_FILE

CHECK_INCLUDE_FILE(<include> <variable> [<flags>])

Check if the given <include> file may be included in a C source file and store the result in an internal cache entry named <variable>. The optional third argument may be used to add compilation flags to the check (or use CMAKE_REQUIRED_FLAGS below).

CMAKE_REQUIRED_FLAGS

string of compile command line flags.

CMAKE_REQUIRED_DEFINITIONS

a ;-list of macros to define (-DFOO=bar).

CMAKE_REQUIRED_INCLUDES

a ;-list of header search paths to pass to the compiler.

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14: a ;-list of options to add to the link command.

CMAKE_REQUIRED_LIBRARIES

a ;-list of libraries to add to the link command. See policy CMP0075.

CMAKE_REQUIRED_QUIET

New in version 3.1: execute quietly without messages.

CHECK_INCLUDE_FILES

CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>])

Check if the given <includes> list may be included together in a source file and store the result in an internal cache entry named <variable>. Specify the <includes> argument as a ;-list of header file names.

If LANGUAGE is set, the specified compiler will be used to perform the check. Acceptable values are C and CXX. If not set, the C compiler will be used if enabled. If the C compiler is not enabled, the C++ compiler will be used if enabled.

CMAKE_REQUIRED_FLAGS

string of compile command line flags.

CMAKE_REQUIRED_DEFINITIONS

a ;-list of macros to define (-DFOO=bar).

CMAKE_REQUIRED_INCLUDES

a ;-list of header search paths to pass to the compiler.

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14: a ;-list of options to add to the link command.

CMAKE_REQUIRED_LIBRARIES

a ;-list of libraries to add to the link command. See policy CMP0075.

CMAKE_REQUIRED_QUIET

New in version 3.1: execute quietly without messages.

check_ipo_supported

check_ipo_supported([RESULT <result>] [OUTPUT <output>]
                    [LANGUAGES <lang>...])

Options are:

CHECK_LIBRARY_EXISTS

CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE)

LIBRARY  - the name of the library you are looking for
FUNCTION - the name of the function
LOCATION - location where the library should be found
VARIABLE - variable to store the result
           Will be created as an internal cache variable.

CMAKE_REQUIRED_FLAGS

string of compile command line flags.

CMAKE_REQUIRED_DEFINITIONS

list of macros to define (-DFOO=bar).

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14: list of options to pass to link command.

CMAKE_REQUIRED_LIBRARIES

list of libraries to link.

CMAKE_REQUIRED_QUIET

New in version 3.1: execute quietly without messages.

check_linker_flag

check_linker_flag(<lang> <flag> <var>)

check_objc_compiler_flag

check_objc_compiler_flag(<flag> <var>)

Check that the <flag> is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry named <var>.

check_objc_source_compiles

check_objc_source_compiles(<code> <resultVar>
                           [FAIL_REGEX <regex1> [<regex2>...]])

Check that the source supplied in <code> can be compiled as a Objectie-C source file and linked as an executable (so it must contain at least a main() function). The result will be stored in the internal cache variable specified by <resultVar>, with a boolean true value for success and boolean false for failure. If FAIL_REGEX is provided, then failure is determined by checking if anything in the output matches any of the specified regular expressions.

The underlying check is performed by the try_compile() command. The compile and link commands can be influenced by setting any of the following variables prior to calling check_objc_source_compiles():

The check is only performed once, with the result cached in the variable named by <resultVar>. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the <code> changes. In order to force the check to be re-evaluated, the variable named by <resultVar> must be manually removed from the cache.

check_objc_source_runs

check_objc_source_runs(<code> <resultVar>)

Check that the source supplied in <code> can be compiled as a Objective-C source file, linked as an executable and then run. The <code> must contain at least a main() function. If the <code> could be built and run successfully, the internal cache variable specified by <resultVar> will be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message).

The underlying check is performed by the try_run() command. The compile and link commands can be influenced by setting any of the following variables prior to calling check_objc_source_runs():

The check is only performed once, with the result cached in the variable named by <resultVar>. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the <code> changes. In order to force the check to be re-evaluated, the variable named by <resultVar> must be manually removed from the cache.

check_objcxx_compiler_flag

check_objcxx_compiler_flag(<flag> <var>)

Check that the <flag> is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry named <var>.

check_objcxx_source_compiles

check_objcxx_source_compiles(<code> <resultVar>
                             [FAIL_REGEX <regex1> [<regex2>...]])

Check that the source supplied in <code> can be compiled as a Objective-C++ source file and linked as an executable (so it must contain at least a main() function). The result will be stored in the internal cache variable specified by <resultVar>, with a boolean true value for success and boolean false for failure. If FAIL_REGEX is provided, then failure is determined by checking if anything in the output matches any of the specified regular expressions.

The underlying check is performed by the try_compile() command. The compile and link commands can be influenced by setting any of the following variables prior to calling check_objcxx_source_compiles():

The check is only performed once, with the result cached in the variable named by <resultVar>. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the <code> changes. In order to force the check to be re-evaluated, the variable named by <resultVar> must be manually removed from the cache.

check_objcxx_source_runs

check_objcxx_source_runs(<code> <resultVar>)

Check that the source supplied in <code> can be compiled as a Objective-C++ source file, linked as an executable and then run. The <code> must contain at least a main() function. If the <code> could be built and run successfully, the internal cache variable specified by <resultVar> will be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message).

The underlying check is performed by the try_run() command. The compile and link commands can be influenced by setting any of the following variables prior to calling check_objcxx_source_runs():

The check is only performed once, with the result cached in the variable named by <resultVar>. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the <code> changes. In order to force the check to be re-evaluated, the variable named by <resultVar> must be manually removed from the cache.

check_pie_supported

check_pie_supported([OUTPUT_VARIABLE <output>]
                    [LANGUAGES <lang>...])

Options are:

check_prototype_definition

check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)

FUNCTION - The name of the function (used to check if prototype exists)
PROTOTYPE- The prototype to check.
RETURN - The return value of the function.
HEADER - The header files required.
VARIABLE - The variable to store the result.
           Will be created as an internal cache variable.

Example:

check_prototype_definition(getpwent_r
 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
 "NULL"
 "unistd.h;pwd.h"
 SOLARIS_GETPWENT_R)

CMAKE_REQUIRED_FLAGS

string of compile command line flags.

CMAKE_REQUIRED_DEFINITIONS

list of macros to define (-DFOO=bar).

CMAKE_REQUIRED_INCLUDES

list of include directories.

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14: list of options to pass to link command.

CMAKE_REQUIRED_LIBRARIES

list of libraries to link.

CMAKE_REQUIRED_QUIET

New in version 3.1: execute quietly without messages.

check_source_compiles

check_source_compiles(<lang> <code> <resultVar>
                      [FAIL_REGEX <regex1> [<regex2>...]]
                      [SRC_EXT <extension>])

Check that the source supplied in <code> can be compiled as a source file for the requested language and linked as an executable (so it must contain at least a main() function). The result will be stored in the internal cache variable specified by <resultVar>, with a boolean true value for success and boolean false for failure. If FAIL_REGEX is provided, then failure is determined by checking if anything in the output matches any of the specified regular expressions.

By default, the test source file will be given a file extension that matches the requested language. The SRC_EXT option can be used to override this with .<extension> instead.

The underlying check is performed by the try_compile() command. The compile and link commands can be influenced by setting any of the following variables prior to calling check_source_compiles():

The check is only performed once, with the result cached in the variable named by <resultVar>. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the <code> changes. In order to force the check to be re-evaluated, the variable named by <resultVar> must be manually removed from the cache.

check_source_runs

check_source_runs(<lang> <code> <resultVar>
                  [SRC_EXT <extension>])

Check that the source supplied in <code> can be compiled as a source file for the requested language, linked as an executable and then run. The <code> must contain at least a main() function. If the <code> could be built and run successfully, the internal cache variable specified by <resultVar> will be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message).

By default, the test source file will be given a file extension that matches the requested language. The SRC_EXT option can be used to override this with .<extension> instead.

The underlying check is performed by the try_run() command. The compile and link commands can be influenced by setting any of the following variables prior to calling check_objc_source_runs():

The check is only performed once, with the result cached in the variable named by <resultVar>. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the <code> changes. In order to force the check to be re-evaluated, the variable named by <resultVar> must be manually removed from the cache.

CHECK_STRUCT_HAS_MEMBER

CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
                        [LANGUAGE <language>])

<struct> - the name of the struct or class you are interested in
<member> - the member which existence you want to check
<header> - the header(s) where the prototype should be declared
<variable> - variable to store the result
<language> - the compiler to use (C or CXX)

CMAKE_REQUIRED_FLAGS

string of compile command line flags.

CMAKE_REQUIRED_DEFINITIONS

list of macros to define (-DFOO=bar).

CMAKE_REQUIRED_INCLUDES

list of include directories.

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14: list of options to pass to link command.

CMAKE_REQUIRED_LIBRARIES

list of libraries to link.

CMAKE_REQUIRED_QUIET

New in version 3.1: execute quietly without messages.

check_symbol_exists

check_symbol_exists(<symbol> <files> <variable>)

Check that the <symbol> is available after including given header <files> and store the result in a <variable>. Specify the list of files in one argument as a semicolon-separated list. <variable> will be created as an internal cache variable.

CMAKE_REQUIRED_FLAGS

string of compile command line flags.

CMAKE_REQUIRED_DEFINITIONS

a ;-list of macros to define (-DFOO=bar).

CMAKE_REQUIRED_INCLUDES

a ;-list of header search paths to pass to the compiler.

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14: a ;-list of options to add to the link command.

CMAKE_REQUIRED_LIBRARIES

a ;-list of libraries to add to the link command. See policy CMP0075.

CMAKE_REQUIRED_QUIET

New in version 3.1: execute quietly without messages.

CHECK_TYPE_SIZE

CHECK_TYPE_SIZE(TYPE VARIABLE [BUILTIN_TYPES_ONLY]
                              [LANGUAGE <language>])

Check if the type exists and determine its size. On return, HAVE_${VARIABLE} holds the existence of the type, and ${VARIABLE} holds one of the following:

<size> = type has non-zero size <size>
"0"    = type has arch-dependent size (see below)
""     = type does not exist

Both HAVE_${VARIABLE} and ${VARIABLE} will be created as internal cache variables.

Furthermore, the variable ${VARIABLE}_CODE holds C preprocessor code to define the macro ${VARIABLE} to the size of the type, or leave the macro undefined if the type does not exist.

The variable ${VARIABLE} may be 0 when CMAKE_OSX_ARCHITECTURES has multiple architectures for building OS X universal binaries. This indicates that the type size varies across architectures. In this case ${VARIABLE}_CODE contains C preprocessor tests mapping from each architecture macro to the corresponding type size. The list of architecture macros is stored in ${VARIABLE}_KEYS, and the value for each key is stored in ${VARIABLE}-${KEY}.

If the BUILTIN_TYPES_ONLY option is not given, the macro checks for headers <sys/types.h>, <stdint.h>, and <stddef.h>, and saves results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and HAVE_STDDEF_H. The type size check automatically includes the available headers, thus supporting checks of types defined in the headers.

If LANGUAGE is set, the specified compiler will be used to perform the check. Acceptable values are C and CXX.

CMAKE_REQUIRED_FLAGS

string of compile command line flags.

CMAKE_REQUIRED_DEFINITIONS

list of macros to define (-DFOO=bar).

CMAKE_REQUIRED_INCLUDES

list of include directories.

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14: list of options to pass to link command.

CMAKE_REQUIRED_LIBRARIES

list of libraries to link.

CMAKE_REQUIRED_QUIET

New in version 3.1: execute quietly without messages.

CMAKE_EXTRA_INCLUDE_FILES

list of extra headers to include.

CHECK_VARIABLE_EXISTS

CHECK_VARIABLE_EXISTS(VAR VARIABLE)

VAR      - the name of the variable
VARIABLE - variable to store the result
           Will be created as an internal cache variable.

This macro is only for C variables.

CMAKE_REQUIRED_FLAGS

string of compile command line flags.

CMAKE_REQUIRED_DEFINITIONS

list of macros to define (-DFOO=bar).

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14: list of options to pass to link command.

CMAKE_REQUIRED_LIBRARIES

list of libraries to link.

CMAKE_REQUIRED_QUIET

New in version 3.1: execute quietly without messages.

cmake_dependent_option

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

Makes <option> available to the user if <depends> is true. When <option> is available, the given <help_text> and initial <value> are used. If the <depends> condition is not true, <option> will not be presented and will always have the value given by <force>. Any value set by the user is preserved for when the option is presented again. In case <depends> is a semicolon-separated list, all elements must be true in order to initialize <option> with <value>.

find_dependency

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

find_dependency(<dep> [...])

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

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

NOTE:

NAME

name of the package

COMPILER_ID

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

LANGUAGE

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

MODE

QUIET

if TRUE, don't print anything

• a foo.dot file, showing all dependencies in the project
• a foo.dot.<target> file for each target, showing on which other targets it depends
• a foo.dot.<target>.dependers file for each target, showing which other targets depend on it

GRAPHVIZ_GRAPH_NAME

The graph name.

GRAPHVIZ_GRAPH_HEADER

The header written at the top of the Graphviz files.

GRAPHVIZ_NODE_PREFIX

The prefix for each node in the Graphviz files.

GRAPHVIZ_EXECUTABLES

Set to FALSE to exclude executables from the generated graphs.

GRAPHVIZ_STATIC_LIBS

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

GRAPHVIZ_SHARED_LIBS

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

GRAPHVIZ_MODULE_LIBS

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

GRAPHVIZ_INTERFACE_LIBS

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

GRAPHVIZ_OBJECT_LIBS

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

GRAPHVIZ_UNKNOWN_LIBS

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

GRAPHVIZ_EXTERNAL_LIBS

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

GRAPHVIZ_CUSTOM_TARGETS

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

GRAPHVIZ_IGNORE_TARGETS

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

GRAPHVIZ_GENERATE_PER_TARGET

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

GRAPHVIZ_GENERATE_DEPENDERS

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

configure_package_config_file

Create a config file for a project:

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

1.

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

2.

insert a line containing only the string @PACKAGE_INIT@

3.

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

4.

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

write_basic_package_version_file

Create a version file for a project:

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

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

CPACK_PACKAGE_NAME

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

CPACK_PACKAGE_VENDOR

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

CPACK_PACKAGE_DIRECTORY

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

CPACK_PACKAGE_VERSION_MAJOR

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

CPACK_PACKAGE_VERSION_MINOR

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

CPACK_PACKAGE_VERSION_PATCH

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

CPACK_PACKAGE_DESCRIPTION

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

CPACK_PACKAGE_DESCRIPTION_FILE

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

CPACK_PACKAGE_DESCRIPTION_SUMMARY

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

CPACK_PACKAGE_HOMEPAGE_URL

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

CPACK_PACKAGE_FILE_NAME

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

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

CPACK_PACKAGE_INSTALL_DIRECTORY

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

CPACK_PACKAGE_ICON

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

CPACK_PACKAGE_CHECKSUM

New in version 3.7.

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

${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}

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

CPACK_PROJECT_CONFIG_FILE

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

CPACK_RESOURCE_FILE_LICENSE

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

CPACK_RESOURCE_FILE_README

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

CPACK_RESOURCE_FILE_WELCOME

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

CPACK_MONOLITHIC_INSTALL

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

CPACK_GENERATOR

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

CPACK_OUTPUT_CONFIG_FILE

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

CPACK_PACKAGE_EXECUTABLES

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

CPACK_STRIP_FILES

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

CPACK_VERBATIM_VARIABLES

New in version 3.4.

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

CPACK_THREADS

New in version 3.20.

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

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

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

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

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

By default CPACK_THREADS is set to 1.

Currently only xz compression may take advantage of multiple cores. Other compression methods ignore this value and use only one thread.

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

CPACK_SOURCE_PACKAGE_FILE_NAME

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

CPACK_SOURCE_STRIP_FILES

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

CPACK_SOURCE_GENERATOR

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

CPACK_SOURCE_OUTPUT_CONFIG_FILE

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

CPACK_SOURCE_IGNORE_FILES

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

CPACK_CMAKE_GENERATOR

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

CPACK_INSTALL_CMAKE_PROJECTS

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

CPACK_SYSTEM_NAME

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

CPACK_PACKAGE_VERSION

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

CPACK_TOPLEVEL_TAG

Directory for the installed files.

CPACK_INSTALL_COMMANDS

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

CPACK_INSTALL_SCRIPTS

New in version 3.16.

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

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

CPACK_PRE_BUILD_SCRIPTS

New in version 3.19.

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

CPACK_POST_BUILD_SCRIPTS

New in version 3.19.

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

CPACK_PACKAGE_FILES

New in version 3.19.

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

CPACK_INSTALLED_DIRECTORIES

Extra directories to install.

CPACK_PACKAGE_INSTALL_REGISTRY_KEY

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

CPACK_CREATE_DESKTOP_LINKS

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

CPACK_BINARY_<GENNAME>

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

CPACK_COMPONENTS_ALL

The list of component to install.

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

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

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

CPACK_<GENNAME>_COMPONENT_INSTALL

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

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

CPACK_COMPONENTS_GROUPING

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

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

CPACK_COMPONENT_<compName>_DISPLAY_NAME

The name to be displayed for a component.

CPACK_COMPONENT_<compName>_DESCRIPTION

The description of a component.

CPACK_COMPONENT_<compName>_GROUP

The group of a component.

CPACK_COMPONENT_<compName>_DEPENDS

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

CPACK_COMPONENT_<compName>_HIDDEN

True if this component is hidden from the user.

CPACK_COMPONENT_<compName>_REQUIRED

True if this component is required.

CPACK_COMPONENT_<compName>_DISABLED

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

cpack_add_component

cpack_add_component_group

cpack_add_install_type

cpack_configure_downloads

cpack_ifw_configure_component

Sets the arguments specific to the CPack IFW generator.

cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL]
                    [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
                    [NAME <name>]
                    [DISPLAY_NAME <display_name>] # Note: Internationalization supported
                    [DESCRIPTION <description>] # Note: Internationalization supported
                    [UPDATE_TEXT <update_text>]
                    [VERSION <version>]
                    [RELEASE_DATE <release_date>]
                    [SCRIPT <script>]
                    [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
                    [DEPENDS|DEPENDENCIES <com_id> ...]
                    [AUTO_DEPEND_ON <comp_id> ...]
                    [LICENSES <display_name> <file_path> ...]
                    [DEFAULT <value>]
                    [USER_INTERFACES <file_path> <file_path> ...]
                    [TRANSLATIONS <file_path> <file_path> ...]
                    [REPLACES <comp_id> ...]
                    [CHECKABLE <value>])

This command should be called after cpack_add_component() command.

cpack_ifw_configure_component_group

Sets the arguments specific to the CPack IFW generator.

cpack_ifw_configure_component_group(<groupname> [VIRTUAL]
                    [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
                    [NAME <name>]
                    [DISPLAY_NAME <display_name>] # Note: Internationalization supported
                    [DESCRIPTION <description>] # Note: Internationalization supported
                    [UPDATE_TEXT <update_text>]
                    [VERSION <version>]
                    [RELEASE_DATE <release_date>]
                    [SCRIPT <script>]
                    [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
                    [DEPENDS|DEPENDENCIES <com_id> ...]
                    [AUTO_DEPEND_ON <comp_id> ...]
                    [LICENSES <display_name> <file_path> ...]
                    [DEFAULT <value>]
                    [USER_INTERFACES <file_path> <file_path> ...]
                    [TRANSLATIONS <file_path> <file_path> ...]
                    [REPLACES <comp_id> ...]
                    [CHECKABLE <value>])

This command should be called after cpack_add_component_group() command.

cpack_ifw_add_repository

Add QtIFW specific remote repository to binary installer.

cpack_ifw_add_repository(<reponame> [DISABLED]
                    URL <url>
                    [USERNAME <username>]
                    [PASSWORD <password>]
                    [DISPLAY_NAME <display_name>])

This command will also add the <reponame> repository to a variable CPACK_IFW_REPOSITORIES_ALL.

cpack_ifw_update_repository

New in version 3.6.

Update QtIFW specific repository from remote repository.

cpack_ifw_update_repository(<reponame>
                    [[ADD|REMOVE] URL <url>]|
                     [REPLACE OLD_URL <old_url> NEW_URL <new_url>]]
                    [USERNAME <username>]
                    [PASSWORD <password>]
                    [DISPLAY_NAME <display_name>])

This command will also add the <reponame> repository to a variable CPACK_IFW_REPOSITORIES_ALL.

cpack_ifw_add_package_resources

New in version 3.7.

Add additional resources in the installer binary.

cpack_ifw_add_package_resources(<file_path> <file_path> ...)

This command will also add the specified files to a variable CPACK_IFW_PACKAGE_RESOURCES.

cpack_ifw_configure_file

Copy a file to another location and modify its contents.

cpack_ifw_configure_file(<input> <output>)

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 variable, or the empty string if the variable is not defined.

• csharp_set_windows_forms_properties()
• csharp_set_designer_cs_properties()
• csharp_set_xaml_cs_properties()

• csharp_get_filename_keys()
• csharp_get_filename_key_base()
• csharp_get_dependentupon_name()

csharp_set_windows_forms_properties

Sets source file properties for use of Windows Forms. Use this, if your CSharp target uses Windows Forms:

csharp_set_windows_forms_properties([<file1> [<file2> [...]]])

In the list of all given files for all files ending with .Designer.cs and .resx is searched. For every designer or resource file a file with the same base name but only .cs as extension is searched. If this is found, the VS_CSHARP_<tagname> properties are set as follows:

csharp_set_designer_cs_properties

Sets source file properties of .Designer.cs files depending on sibling filenames. Use this, if your CSharp target does not use Windows Forms (for Windows Forms use csharp_set_designer_cs_properties() instead):

csharp_set_designer_cs_properties([<file1> [<file2> [...]]])

In the list of all given files for all files ending with .Designer.cs is searched. For every designer file all files with the same base name but different extensions are searched. If a match is found, the source file properties of the designer file are set depending on the extension of the matched file:

csharp_set_xaml_cs_properties

Sets source file properties for use of Windows Presentation Foundation (WPF) and XAML. Use this, if your CSharp target uses WPF/XAML:

csharp_set_xaml_cs_properties([<file1> [<file2> [...]]])

In the list of all given files for all files ending with .xaml.cs is searched. For every xaml-cs file, a file with the same base name but extension .xaml is searched. If a match is found, the source file properties of the .xaml.cs file are set:

csharp_get_filename_keys

Helper function which computes a list of key values to identify source files independently of relative/absolute paths given in cmake and eliminates case sensitivity:

csharp_get_filename_keys(OUT [<file1> [<file2> [...]]])

In some way the function applies a canonicalization to the source names. This is necessary to find file matches if the files have been added to the target with different directory prefixes:

add_library(lib
  myfile.cs
  ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs)
set_source_files_properties(myfile.Designer.cs PROPERTIES
  VS_CSHARP_DependentUpon myfile.cs)
# this will fail, because in cmake
#  - ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs
#  - myfile.Designer.cs
# are not the same source file. The source file property is not set.

csharp_get_filename_key_base

Returns the full filepath and name without extension of a key. KEY is expected to be a key from csharp_get_filename_keys. In BASE the value of KEY without the file extension is returned:

csharp_get_filename_key_base(BASE KEY)

csharp_get_dependentupon_name

Computes a string which can be used as value for the source file property VS_CSHARP_<tagname> with target being DependentUpon:

csharp_get_dependentupon_name(NAME FILE)

Actually this is only the filename without any path given at the moment.

• data.json defines the source and build directories for use by CDash.
• Labels.json indicates any LABELS that have been set on the source files.
• The uncovered directory holds any uncovered files found by CTEST_EXTRA_COVERAGE_GLOB.

ctest_coverage_collect_gcov

ctest_coverage_collect_gcov(TARBALL <tarfile>
  [SOURCE <source_dir>][BUILD <build_dir>]
  [GCOV_COMMAND <gcov_command>]
  [GCOV_OPTIONS <options>...]
  )

Run gcov and package a tar file for CDash. The options are:

New in version 3.3: Added support for the CTEST_CUSTOM_COVERAGE_EXCLUDE variable.

ExternalData_Expand_Arguments

The ExternalData_Expand_Arguments function evaluates DATA{} references in its arguments and constructs a new list of arguments:

ExternalData_Expand_Arguments(
  <target>   # Name of data management target
  <outVar>   # Output variable
  [args...]  # Input arguments, DATA{} allowed
  )

It replaces each DATA{} reference in an argument with the full path of a real data file on disk that will exist after the <target> builds.

ExternalData_Add_Test

The ExternalData_Add_Test function wraps around the CMake add_test() command but supports DATA{} references in its arguments:

ExternalData_Add_Test(
  <target>   # Name of data management target
  ...        # Arguments of add_test(), DATA{} allowed
  )

It passes its arguments through ExternalData_Expand_Arguments and then invokes the add_test() command using the results.

ExternalData_Add_Target

The ExternalData_Add_Target function creates a custom target to manage local instances of data files stored externally:

ExternalData_Add_Target(
  <target>                  # Name of data management target
  [SHOW_PROGRESS <ON|OFF>]  # Show progress during the download
  )

It creates custom commands in the target as necessary to make data files available for each DATA{} reference previously evaluated by other functions provided by this module. Data files may be fetched from one of the URL templates specified in the ExternalData_URL_TEMPLATES variable, or may be found locally in one of the paths specified in the ExternalData_OBJECT_STORES variable.

New in version 3.20: The SHOW_PROGRESS argument may be passed to suppress progress information during the download of objects. If not provided, it defaults to OFF for Ninja and Ninja Multi-Config generators and ON otherwise.

Typically only one target is needed to manage all external data within a project. Call this function once at the end of configuration after all data references have been processed.

ExternalData_BINARY_ROOT

The ExternalData_BINARY_ROOT variable may be set to the directory to hold the real data files named by expanded DATA{} references. The default is CMAKE_BINARY_DIR. The directory layout will mirror that of content links under ExternalData_SOURCE_ROOT.

ExternalData_CUSTOM_SCRIPT_<key>

New in version 3.2.

Specify a full path to a .cmake custom fetch script identified by <key> in entries of the ExternalData_URL_TEMPLATES list. See Custom Fetch Scripts.

ExternalData_LINK_CONTENT

The ExternalData_LINK_CONTENT variable may be set to the name of a supported hash algorithm to enable automatic conversion of real data files referenced by the DATA{} syntax into content links. For each such <file> a content link named <file><ext> is created. The original file is renamed to the form .ExternalData_<algo>_<hash> to stage it for future transmission to one of the locations in the list of URL templates (by means outside the scope of this module). The data fetch rule created for the content link will use the staged object if it cannot be found using any URL template.

ExternalData_NO_SYMLINKS

New in version 3.3.

The real data files named by expanded DATA{} references may be made available under ExternalData_BINARY_ROOT using symbolic links on some platforms. The ExternalData_NO_SYMLINKS variable may be set to disable use of symbolic links and enable use of copies instead.

ExternalData_OBJECT_STORES

The ExternalData_OBJECT_STORES variable may be set to a list of local directories that store objects using the layout <dir>/%(algo)/%(hash). These directories will be searched first for a needed object. If the object is not available in any store then it will be fetched remotely using the URL templates and added to the first local store listed. If no stores are specified the default is a location inside the build tree.

ExternalData_SERIES_PARSE

ExternalData_SERIES_PARSE_PREFIX

ExternalData_SERIES_PARSE_NUMBER

ExternalData_SERIES_PARSE_SUFFIX

ExternalData_SERIES_MATCH

See Referencing File Series.

ExternalData_SOURCE_ROOT

The ExternalData_SOURCE_ROOT variable may be set to the highest source directory containing any path named by a DATA{} reference. The default is CMAKE_SOURCE_DIR. ExternalData_SOURCE_ROOT and CMAKE_SOURCE_DIR must refer to directories within a single source distribution (e.g. they come together in one tarball).

ExternalData_TIMEOUT_ABSOLUTE

The ExternalData_TIMEOUT_ABSOLUTE variable sets the download absolute timeout, in seconds, with a default of 300 seconds. Set to 0 to disable enforcement.

ExternalData_TIMEOUT_INACTIVITY

The ExternalData_TIMEOUT_INACTIVITY variable sets the download inactivity timeout, in seconds, with a default of 60 seconds. Set to 0 to disable enforcement.

ExternalData_URL_ALGO_<algo>_<key>

New in version 3.3.

Specify a custom URL component to be substituted for URL template placeholders of the form %(algo:<key>), where <key> is a valid C identifier, when fetching an object referenced via hash algorithm <algo>. If not defined, the default URL component is just <algo> for any <key>.

ExternalData_URL_TEMPLATES

The ExternalData_URL_TEMPLATES may be set to provide a list of URL templates using the placeholders %(algo) and %(hash) in each template. Data fetch rules try each URL template in order by substituting the hash algorithm name for %(algo) and the hash value for %(hash). Alternatively one may use %(algo:<key>) with ExternalData_URL_ALGO_<algo>_<key> variables to gain more flexibility in remote URLs.

ExternalData_CUSTOM_LOCATION

When a custom fetch script is loaded, this variable is set to the location part of the URL, which will contain the substituted hash algorithm name and content hash value.

ExternalData_CUSTOM_FILE

When a custom fetch script is loaded, this variable is set to the full path to a file in which the script must store the fetched content. The name of the file is unspecified and should not be interpreted in any way.

ExternalData_CUSTOM_ERROR

When a custom fetch script fails to fetch the requested content, it must set this variable to a short one-line message describing the reason for failure.

ExternalProject_Add

The ExternalProject_Add() function creates a custom target to drive download, update/patch, configure, build, install and test steps of an external project:

ExternalProject_Add(<name> [<option>...])

The individual steps within the process can be driven independently if required (e.g. for CDash submission) and extra custom steps can be defined, along with the ability to control the step dependencies. The directory structure used for the management of the external project can also be customized. The function supports a large number of options which can be used to tailor the external project behavior.

TMP_DIR      = <prefix>/tmp
STAMP_DIR    = <prefix>/src/<name>-stamp
DOWNLOAD_DIR = <prefix>/src
SOURCE_DIR   = <prefix>/src/<name>
BINARY_DIR   = <prefix>/src/<name>-build
INSTALL_DIR  = <prefix>
LOG_DIR      = <STAMP_DIR>

TMP_DIR      = <base>/tmp/<name>
STAMP_DIR    = <base>/Stamp/<name>
DOWNLOAD_DIR = <base>/Download/<name>
SOURCE_DIR   = <base>/Source/<name>
BINARY_DIR   = <base>/Build/<name>
INSTALL_DIR  = <base>/Install/<name>
LOG_DIR      = <STAMP_DIR>

ExternalProject_Add(example
  ... # Download options, etc.
  BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
  COMMAND       ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
  COMMAND       ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
)

It should also be noted that each build step is created via a call to ExternalProject_Add_Step(). See that command's documentation for the automatic substitutions that are supported for some options.

ExternalProject_Get_Property

The ExternalProject_Get_Property() function retrieves external project target properties:

ExternalProject_Get_Property(<name> <prop1> [<prop2>...])

The function stores property values in variables of the same name. Property names correspond to the keyword argument names of ExternalProject_Add(). For example, the source directory might be retrieved like so:

ExternalProject_Get_property(myExtProj SOURCE_DIR)
message("Source dir of myExtProj = ${SOURCE_DIR}")

ExternalProject_Add_Step

The ExternalProject_Add_Step() function specifies an additional custom step for an external project defined by an earlier call to ExternalProject_Add():

ExternalProject_Add_Step(<name> <step> [<option>...])

<name> is the same as the name passed to the original call to ExternalProject_Add(). The specified <step> must not be one of the pre-defined steps (mkdir, download, update, patch, configure, build, install or test). The supported options are:

The command line, comment, working directory and byproducts of every standard and custom step are processed to replace the tokens <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>, <INSTALL_DIR> <TMP_DIR>, <DOWNLOAD_DIR> and <DOWNLOADED_FILE> with their corresponding property values defined in the original call to ExternalProject_Add().

New in version 3.3: Token replacement is extended to byproducts.

New in version 3.11: The <DOWNLOAD_DIR> substitution token.

ExternalProject_Add_StepTargets

The ExternalProject_Add_StepTargets() function generates targets for the steps listed. The name of each created target will be of the form <name>-<step>:

ExternalProject_Add_StepTargets(<name> <step1> [<step2>...])

Creating a target for a step allows it to be used as a dependency of another target or to be triggered manually. Having targets for specific steps also allows them to be driven independently of each other by specifying targets on build command lines. For example, you may be submitting to a sub-project based dashboard where you want to drive the configure portion of the build, then submit to the dashboard, followed by the build portion, followed by tests. If you invoke a custom target that depends on a step halfway through the step dependency chain, then all the previous steps will also run to ensure everything is up to date.

Internally, ExternalProject_Add() calls ExternalProject_Add_Step() to create each step. If any STEP_TARGETS were specified, then ExternalProject_Add_StepTargets() will also be called after ExternalProject_Add_Step(). Even if a step is not mentioned in the STEP_TARGETS option, ExternalProject_Add_StepTargets() can still be called later to manually define a target for the step.

The STEP_TARGETS option for ExternalProject_Add() is generally the easiest way to ensure targets are created for specific steps of interest. For custom steps, ExternalProject_Add_StepTargets() must be called explicitly if a target should also be created for that custom step. An alternative to these two options is to populate the EP_STEP_TARGETS directory property. It acts as a default for the step target options and can save having to repeatedly specify the same set of step targets when multiple external projects are being defined.

New in version 3.19: If CMP0114 is set to NEW, step targets are fully responsible for holding the custom commands implementing their steps. The primary target created by ExternalProject_Add depends on the step targets, and the step targets depend on each other. The target-level dependencies match the file-level dependencies used by the custom commands for each step. The targets for steps created with ExternalProject_Add_Step()'s INDEPENDENT option do not depend on the external targets specified by ExternalProject_Add()'s DEPENDS option. The predefined steps mkdir, download, update, and patch are independent.

If CMP0114 is not NEW, the following deprecated behavior is available:

ExternalProject_Add_StepDependencies

New in version 3.2.

The ExternalProject_Add_StepDependencies() function can be used to add dependencies to a step. The dependencies added must be targets CMake already knows about (these can be ordinary executable or library targets, custom targets or even step targets of another external project):

ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])

This function takes care to set both target and file level dependencies and will ensure that parallel builds will not break. It should be used instead of add_dependencies() whenever adding a dependency for some of the step targets generated by the ExternalProject module.

FeatureSummary_PKG_TYPES

FeatureSummary_REQUIRED_PKG_TYPES

FeatureSummary_DEFAULT_PKG_TYPE

FeatureSummary_<TYPE>_DESCRIPTION

feature_summary

feature_summary( [FILENAME <file>]
                 [APPEND]
                 [VAR <variable_name>]
                 [INCLUDE_QUIET_PACKAGES]
                 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
                 [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
                 [QUIET_ON_EMPTY]
                 WHAT (ALL
                      | PACKAGES_FOUND | PACKAGES_NOT_FOUND
                      | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
                      | ENABLED_FEATURES | DISABLED_FEATURES)
               )

The feature_summary() macro can be used to print information about enabled or disabled packages or features of a project. By default, only the names of the features/packages will be printed and their required version when one was specified. Use set_package_properties() to add more useful information, like e.g. a download URL for the respective package or their purpose in the project.

The WHAT option is the only mandatory option. Here you specify what information will be printed:

For each package type <TYPE> defined by the FeatureSummary_PKG_TYPES global property, the following information can also be used:

Changed in version 3.1: With the exception of the ALL value, these values can be combined in order to customize the output. For example:

feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)

If a FILENAME is given, the information is printed into this file. If APPEND is used, it is appended to this file, otherwise the file is overwritten if it already existed. If the VAR option is used, the information is "printed" into the specified variable. If FILENAME is not used, the information is printed to the terminal. Using the DESCRIPTION option a description or headline can be set which will be printed above the actual content. If only one type of package was requested, no title is printed, unless it is explicitly set using either DESCRIPTION to use a custom string, or DEFAULT_DESCRIPTION to use a default title for the requested type. If INCLUDE_QUIET_PACKAGES is given, packages which have been searched with find_package(... QUIET) will also be listed. By default they are skipped. If FATAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if a package which is marked as one of the package types listed in the FeatureSummary_REQUIRED_PKG_TYPES global property has not been found. The default value for the FeatureSummary_REQUIRED_PKG_TYPES global property is REQUIRED.

New in version 3.9: The DEFAULT_DESCRIPTION option.

The FeatureSummary_DEFAULT_PKG_TYPE global property can be modified to change the default package type assigned when not explicitly assigned by the user.

New in version 3.8: If the QUIET_ON_EMPTY option is used, if only one type of package was requested, and no packages belonging to that category were found, then no output (including the DESCRIPTION) is printed or added to the VAR variable.

Example 1, append everything to a file:

include(FeatureSummary)
feature_summary(WHAT ALL
                FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)

Example 2, print the enabled features into the variable enabledFeaturesText, including QUIET packages:

include(FeatureSummary)
feature_summary(WHAT ENABLED_FEATURES
                INCLUDE_QUIET_PACKAGES
                DESCRIPTION "Enabled Features:"
                VAR enabledFeaturesText)
message(STATUS "${enabledFeaturesText}")

Example 3, change default package types and print only the categories that are not empty:

include(FeatureSummary)
set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
find_package(FOO)
set_package_properties(FOO PROPERTIES TYPE BUILD)
feature_summary(WHAT BUILD_PACKAGES_FOUND
                Description "Build tools found:"
                QUIET_ON_EMPTY)
feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
                Description "Build tools not found:"
                QUIET_ON_EMPTY)

set_package_properties

set_package_properties(<name> PROPERTIES
                       [ URL <url> ]
                       [ DESCRIPTION <description> ]
                       [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
                       [ PURPOSE <purpose> ]
                      )

Use this macro to set up information about the named package, which can then be displayed via FEATURE_SUMMARY(). This can be done either directly in the Find-module or in the project which uses the module after the find_package() call. The features for which information can be set are added automatically by the find_package() command.

Example for setting the info for a package:

find_package(LibXml2)
set_package_properties(LibXml2 PROPERTIES
                       DESCRIPTION "A XML processing library."
                       URL "http://xmlsoft.org/")
# or
set_package_properties(LibXml2 PROPERTIES
                       TYPE RECOMMENDED
                       PURPOSE "Enables HTML-import in MyWordProcessor")
# or
set_package_properties(LibXml2 PROPERTIES
                       TYPE OPTIONAL
                       PURPOSE "Enables odt-export in MyWordProcessor")
find_package(DBUS)
set_package_properties(DBUS PROPERTIES
  TYPE RUNTIME
  PURPOSE "Necessary to disable the screensaver during a presentation")

add_feature_info

add_feature_info(<name> <enabled> <description>)

Use this macro to add information about a feature with the given <name>. <enabled> contains whether this feature is enabled or not. It can be a variable or a list of conditions. <description> is a text describing the feature. The information can be displayed using feature_summary() for ENABLED_FEATURES and DISABLED_FEATURES respectively.

Changed in version 3.8: <enabled> can be a list of conditions.

Example for setting the info for a feature:

option(WITH_FOO "Help for foo" ON)
add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")

set_package_info

set_package_info(<name> <description> [ <url> [<purpose>] ])

Use this macro to set up information about the named package, which can then be displayed via feature_summary(). This can be done either directly in the Find-module or in the project which uses the module after the find_package() call. The features for which information can be set are added automatically by the find_package() command.

set_feature_info

set_feature_info(<name> <description> [<url>])

Does the same as:

set_package_info(<name> <description> <url>)

print_enabled_features

print_enabled_features()

Does the same as

feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")

print_disabled_features

print_disabled_features()

Does the same as

feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")

FetchContent_Declare

FetchContent_Declare(<name> <contentOptions>...)

The FetchContent_Declare() function records the options that describe how to populate the specified content. If such details have already been recorded earlier in this project (regardless of where in the project hierarchy), this and all later calls for the same content <name> are ignored. This "first to record, wins" approach is what allows hierarchical projects to have parent projects override content details of child projects.

The content <name> can be any string without spaces, but good practice would be to use only letters, numbers and underscores. The name will be treated case-insensitively and it should be obvious for the content it represents, often being the name of the child project or the value given to its top level project() command (if it is a CMake project). For well-known public projects, the name should generally be the official name of the project. Choosing an unusual name makes it unlikely that other projects needing that same content will use the same name, leading to the content being populated multiple times.

The <contentOptions> can be any of the download, update or patch options that the ExternalProject_Add() command understands. The configure, build, install and test steps are explicitly disabled and therefore options related to them will be ignored. The SOURCE_SUBDIR option is an exception, see FetchContent_MakeAvailable() for details on how that affects behavior.

In most cases, <contentOptions> will just be a couple of options defining the download method and method-specific details like a commit tag or archive hash. For example:

FetchContent_Declare(
  googletest
  GIT_REPOSITORY https://github.com/google/googletest.git
  GIT_TAG        703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
)
FetchContent_Declare(
  myCompanyIcons
  URL      https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
  URL_HASH MD5=5588a7b18261c20068beabfb4f530b87
)
FetchContent_Declare(
  myCompanyCertificates
  SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs
  SVN_REVISION   -r12345
)

Where contents are being fetched from a remote location and you do not control that server, it is advisable to use a hash for GIT_TAG rather than a branch or tag name. A commit hash is more secure and helps to confirm that the downloaded contents are what you expected.

Changed in version 3.14: Commands for the download, update or patch steps can access the terminal. This may be needed for things like password prompts or real-time display of command progress.

New in version 3.22: The CMAKE_TLS_VERIFY, CMAKE_TLS_CAINFO, CMAKE_NETRC and CMAKE_NETRC_FILE variables now provide the defaults for their corresponding content options, just like they do for ExternalProject_Add(). Previously, these variables were ignored by the FetchContent module.

FetchContent_MakeAvailable

New in version 3.14.

FetchContent_MakeAvailable(<name1> [<name2>...])

This command ensures that each of the named dependencies are populated and potentially added to the build by the time it returns. It iterates over the list, and for each dependency, the following logic is applied:

Projects should aim to declare the details of all dependencies they might use before they call FetchContent_MakeAvailable() for any of them. This ensures that if any of the dependencies are also sub-dependencies of one or more of the others, the main project still controls the details that will be used (because it will declare them first before the dependencies get a chance to). In the following code samples, assume that the uses_other dependency also uses FetchContent to add the other dependency internally:

# WRONG: Should declare all details first
FetchContent_Declare(uses_other ...)
FetchContent_MakeAvailable(uses_other)
FetchContent_Declare(other ...)    # Will be ignored, uses_other beat us to it
FetchContent_MakeAvailable(other)  # Would use details declared by uses_other

# CORRECT: All details declared first, so they will take priority
FetchContent_Declare(uses_other ...)
FetchContent_Declare(other ...)
FetchContent_MakeAvailable(uses_other other)

FetchContent_Populate

NOTE:

FetchContent_Populate(<name>)

In most cases, the only argument given to FetchContent_Populate() is the <name>. When used this way, the command assumes the content details have been recorded by an earlier call to FetchContent_Declare(). The details are stored in a global property, so they are unaffected by things like variable or directory scope. Therefore, it doesn't matter where in the project the details were previously declared, as long as they have been declared before the call to FetchContent_Populate(). Those saved details are then used to construct a call to ExternalProject_Add() in a private sub-build to perform the content population immediately. The implementation of ExternalProject_Add() ensures that if the content has already been populated in a previous CMake run, that content will be reused rather than repopulating them again. For the common case where population involves downloading content, the cost of the download is only paid once.

An internal global property records when a particular content population request has been processed. If FetchContent_Populate() is called more than once for the same content name within a configure run, the second call will halt with an error. Projects can and should check whether content population has already been processed with the FetchContent_GetProperties() command before calling FetchContent_Populate().

FetchContent_Populate() will set three variables in the scope of the caller:

The main use case for the <lowercaseName>_SOURCE_DIR and <lowercaseName>_BINARY_DIR variables is to call add_subdirectory() immediately after population:

FetchContent_Populate(FooBar)
add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})

The values of the three variables can also be retrieved from anywhere in the project hierarchy using the FetchContent_GetProperties() command.

The FetchContent_Populate() command also supports a syntax allowing the content details to be specified directly rather than using any saved details. This is more low-level and use of this form is generally to be avoided in favor of using saved content details as outlined above. Nevertheless, in certain situations it can be useful to invoke the content population as an isolated operation (typically as part of implementing some other higher level feature or when using CMake in script mode):

FetchContent_Populate(
  <name>
  [QUIET]
  [SUBBUILD_DIR <subBuildDir>]
  [SOURCE_DIR <srcDir>]
  [BINARY_DIR <binDir>]
  ...
)

This form has a number of key differences to that where only <name> is provided:

The <lowercaseName>_SOURCE_DIR and <lowercaseName>_BINARY_DIR variables are still returned to the caller, but since these locations are not stored as global properties when this form is used, they are only available to the calling scope and below rather than the entire project hierarchy. No <lowercaseName>_POPULATED variable is set in the caller's scope with this form.

The supported options for FetchContent_Populate() are the same as those for FetchContent_Declare(). Those few options shown just above are either specific to FetchContent_Populate() or their behavior is slightly modified from how ExternalProject_Add() treats them:

In addition to the above explicit options, any other unrecognized options are passed through unmodified to ExternalProject_Add() to perform the download, patch and update steps. The following options are explicitly prohibited (they are disabled by the FetchContent_Populate() command):

If using FetchContent_Populate() within CMake's script mode, be aware that the implementation sets up a sub-build which therefore requires a CMake generator and build tool to be available. If these cannot be found by default, then the CMAKE_GENERATOR and/or CMAKE_MAKE_PROGRAM variables will need to be set appropriately on the command line invoking the script.

New in version 3.18: Added support for the DOWNLOAD_NO_EXTRACT option.

FetchContent_GetProperties

When using saved content details, a call to FetchContent_MakeAvailable() or FetchContent_Populate() records information in global properties which can be queried at any time. This information includes the source and binary directories associated with the content and also whether or not the content population has been processed during the current configure run.

FetchContent_GetProperties(
  <name>
  [SOURCE_DIR <srcDirVar>]
  [BINARY_DIR <binDirVar>]
  [POPULATED <doneVar>]
)

The SOURCE_DIR, BINARY_DIR and POPULATED options can be used to specify which properties should be retrieved. Each option accepts a value which is the name of the variable in which to store that property. Most of the time though, only <name> is given, in which case the call will then set the same variables as a call to FetchContent_MakeAvailable(name) or FetchContent_Populate(name).

This command is rarely needed when using FetchContent_MakeAvailable(). It is more commonly used as part of implementing the following pattern with FetchContent_Populate(), which ensures that the relevant variables will always be defined regardless of whether or not the population has been performed elsewhere in the project already:

# Check if population has already been performed
FetchContent_GetProperties(depname)
if(NOT depname_POPULATED)
  # Fetch the content using previously declared details
  FetchContent_Populate(depname)
  # Set custom variables, policies, etc.
  # ...
  # Bring the populated content into the build
  add_subdirectory(${depname_SOURCE_DIR} ${depname_BINARY_DIR})
endif()

FETCHCONTENT_BASE_DIR

In most cases, the saved details do not specify any options relating to the directories to use for the internal sub-build, final source and build areas. It is generally best to leave these decisions up to the FetchContent module to handle on the project's behalf. The FETCHCONTENT_BASE_DIR cache variable controls the point under which all content population directories are collected, but in most cases, developers would not need to change this. The default location is ${CMAKE_BINARY_DIR}/_deps, but if developers change this value, they should aim to keep the path short and just below the top level of the build tree to avoid running into path length problems on Windows.

FETCHCONTENT_QUIET

The logging output during population can be quite verbose, making the configure stage quite noisy. This cache option (ON by default) hides all population output unless an error is encountered. If experiencing problems with hung downloads, temporarily switching this option off may help diagnose which content population is causing the issue.

FETCHCONTENT_FULLY_DISCONNECTED

When this option is enabled, no attempt is made to download or update any content. It is assumed that all content has already been populated in a previous run or the source directories have been pointed at existing contents the developer has provided manually (using options described further below). When the developer knows that no changes have been made to any content details, turning this option ON can significantly speed up the configure stage. It is OFF by default.

FETCHCONTENT_UPDATES_DISCONNECTED

This is a less severe download/update control compared to FETCHCONTENT_FULLY_DISCONNECTED. Instead of bypassing all download and update logic, FETCHCONTENT_UPDATES_DISCONNECTED only disables the update stage. Therefore, if content has not been downloaded previously, it will still be downloaded when this option is enabled. This can speed up the configure stage, but not as much as FETCHCONTENT_FULLY_DISCONNECTED. It is OFF by default.

FETCHCONTENT_SOURCE_DIR_<uppercaseName>

If this is set, no download or update steps are performed for the specified content and the <lowercaseName>_SOURCE_DIR variable returned to the caller is pointed at this location. This gives developers a way to have a separate checkout of the content that they can modify freely without interference from the build. The build simply uses that existing source, but it still defines <lowercaseName>_BINARY_DIR to point inside its own build area. Developers are strongly encouraged to use this mechanism rather than editing the sources populated in the default location, as changes to sources in the default location can be lost when content population details are changed by the project.

FETCHCONTENT_UPDATES_DISCONNECTED_<uppercaseName>

This is the per-content equivalent of FETCHCONTENT_UPDATES_DISCONNECTED. If the global option or this option is ON, then updates will be disabled for the named content. Disabling updates for individual content can be useful for content whose details rarely change, while still leaving other frequently changing content with updates enabled.

• projB and projC define different content details for projD, but projA also defines a set of content details for projD. Because projA will define them first, the details from projB and projC will not be used. The override details defined by projA are not required to match either of those from projB or projC, but it is up to the higher level project to ensure that the details it does define still make sense for the child projects.
• In the projA call to FetchContent_MakeAvailable(), projD is listed ahead of projB and projC to ensure that projA is in control of how projD is populated.
• While projA defines content details for projE, it does not need to explicitly call FetchContent_MakeAvailable(projE) or FetchContent_Populate(projD) itself. Instead, it leaves that to the child projB. For higher level projects, it is often enough to just define the override content details and leave the actual population to the child projects. This saves repeating the same thing at each level of the project hierarchy unnecessarily.

find_package_handle_standard_args

This command handles the REQUIRED, QUIET and version-related arguments of find_package(). It also sets the <PackageName>_FOUND variable. The package is considered found if all variables listed contain valid results, e.g. valid filepaths.

There are two signatures:

find_package_handle_standard_args(<PackageName>
  (DEFAULT_MSG|<custom-failure-message>)
  <required-var>...
  )
find_package_handle_standard_args(<PackageName>
  [FOUND_VAR <result-var>]
  [REQUIRED_VARS <required-var>...]
  [VERSION_VAR <version-var>]
  [HANDLE_VERSION_RANGE]
  [HANDLE_COMPONENTS]
  [CONFIG_MODE]
  [NAME_MISMATCHED]
  [REASON_FAILURE_MESSAGE <reason-failure-message>]
  [FAIL_MESSAGE <custom-failure-message>]
  )

The <PackageName>_FOUND variable will be set to TRUE if all the variables <required-var>... are valid and any optional constraints are satisfied, and FALSE otherwise. A success or failure message may be displayed based on the results and on whether the REQUIRED and/or QUIET option was given to the find_package() call.

The options are:

find_package_check_version

New in version 3.19.

Helper function which can be used to check if a <version> is valid against version-related arguments of find_package().

find_package_check_version(<version> <result-var>
  [HANDLE_VERSION_RANGE]
  [RESULT_MESSAGE_VARIABLE <message-var>]
  )

The <result-var> will hold a boolean value giving the result of the check.

The options are:

FortranCInterface_GLOBAL_FOUND

Global subroutines and functions.

FortranCInterface_MODULE_FOUND

Module subroutines and functions (declared by "MODULE PROCEDURE").

FortranCInterface_GLOBAL_PREFIX

Prefix for a global symbol without an underscore.

FortranCInterface_GLOBAL_SUFFIX

Suffix for a global symbol without an underscore.

FortranCInterface_GLOBAL_CASE

The case for a global symbol without an underscore, either UPPER or LOWER.

FortranCInterface_GLOBAL__PREFIX

Prefix for a global symbol with an underscore.

FortranCInterface_GLOBAL__SUFFIX

Suffix for a global symbol with an underscore.

FortranCInterface_GLOBAL__CASE

The case for a global symbol with an underscore, either UPPER or LOWER.

FortranCInterface_MODULE_PREFIX

Prefix for a module symbol without an underscore.

FortranCInterface_MODULE_MIDDLE

Middle of a module symbol without an underscore that appears between the name of the module and the name of the symbol.

FortranCInterface_MODULE_SUFFIX

Suffix for a module symbol without an underscore.

FortranCInterface_MODULE_CASE

The case for a module symbol without an underscore, either UPPER or LOWER.

FortranCInterface_MODULE__PREFIX

Prefix for a module symbol with an underscore.

FortranCInterface_MODULE__MIDDLE

Middle of a module symbol with an underscore that appears between the name of the module and the name of the symbol.

FortranCInterface_MODULE__SUFFIX

Suffix for a module symbol with an underscore.

FortranCInterface_MODULE__CASE

The case for a module symbol with an underscore, either UPPER or LOWER.

FortranCInterface_HEADER

The FortranCInterface_HEADER function is provided to generate a C header file containing macros to mangle symbol names:

FortranCInterface_HEADER(<file>
                         [MACRO_NAMESPACE <macro-ns>]
                         [SYMBOL_NAMESPACE <ns>]
                         [SYMBOLS [<module>:]<function> ...])

It generates in <file> definitions of the following macros:

#define FortranCInterface_GLOBAL (name,NAME) ...
#define FortranCInterface_GLOBAL_(name,NAME) ...
#define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
#define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...

These macros mangle four categories of Fortran symbols, respectively:

If mangling for a category is not known, its macro is left undefined. All macros require raw names in both lower case and upper case.

The options are:

<function>          ==> #define <ns><function> ...
<module>:<function> ==> #define <ns><module>_<function> ...

FortranCInterface_VERIFY

The FortranCInterface_VERIFY function is provided to verify that the Fortran and C/C++ compilers work together:

FortranCInterface_VERIFY([CXX] [QUIET])

It tests whether a simple test executable using Fortran and C (and C++ when the CXX option is given) compiles and links successfully. The result is stored in the cache entry FortranCInterface_VERIFIED_C (or FortranCInterface_VERIFIED_CXX if CXX is given) as a boolean. If the check fails and QUIET is not given the function terminates with a fatal error message describing the problem. The purpose of this check is to stop a build early for incompatible compiler combinations. The test is built in the Release configuration.

BINDIR

user executables (bin)

SBINDIR

system admin executables (sbin)

LIBEXECDIR

program executables (libexec)

SYSCONFDIR

read-only single-machine data (etc)

SHAREDSTATEDIR

modifiable architecture-independent data (com)

LOCALSTATEDIR

modifiable single-machine data (var)

RUNSTATEDIR

New in version 3.9: run-time variable data (LOCALSTATEDIR/run)

LIBDIR

object code libraries (lib or lib64 or lib/<multiarch-tuple> on Debian)

INCLUDEDIR

C header files (include)

OLDINCLUDEDIR

C header files for non-gcc (/usr/include)

DATAROOTDIR

read-only architecture-independent data root (share)

DATADIR

read-only architecture-independent data (DATAROOTDIR)

INFODIR

info documentation (DATAROOTDIR/info)

LOCALEDIR

locale-dependent data (DATAROOTDIR/locale)

MANDIR

man documentation (DATAROOTDIR/man)

DOCDIR

documentation root (DATAROOTDIR/doc/PROJECT_NAME)

GNUInstallDirs_get_absolute_install_dir

GNUInstallDirs_get_absolute_install_dir(absvar var dirname)

New in version 3.7.

Set the given variable absvar to the absolute path contained within the variable var. This is to allow the computation of an absolute path, accounting for all the special cases documented above. While this macro is used to compute the various CMAKE_INSTALL_FULL_<dir> variables, it is exposed publicly to allow users who create additional path variables to also compute absolute paths where necessary, using the same logic. dirname is the directory name to get, e.g. BINDIR.

Changed in version 3.20: Added the <dirname> parameter. Previous versions of CMake passed this value through the variable ${dir}.

gtest_add_tests

Automatically add tests with CTest by scanning source code for Google Test macros:

gtest_add_tests(TARGET target
                [SOURCES src1...]
                [EXTRA_ARGS arg1...]
                [WORKING_DIRECTORY dir]
                [TEST_PREFIX prefix]
                [TEST_SUFFIX suffix]
                [SKIP_DEPENDENCY]
                [TEST_LIST outVar]
)

gtest_add_tests attempts to identify tests by scanning source files. Although this is generally effective, it uses only a basic regular expression match, which can be defeated by atypical test declarations, and is unable to fully "split" parameterized tests. Additionally, it requires that CMake be re-run to discover any newly added, removed or renamed tests (by default, this means that CMake is re-run when any test source file is changed, but see SKIP_DEPENDENCY). However, it has the advantage of declaring tests at CMake time, which somewhat simplifies setting additional properties on tests, and always works in a cross-compiling environment.

The options are:

Usage example:

include(GoogleTest)
add_executable(FooTest FooUnitTest.cxx)
gtest_add_tests(TARGET      FooTest
                TEST_SUFFIX .noArgs
                TEST_LIST   noArgsTests
)
gtest_add_tests(TARGET      FooTest
                EXTRA_ARGS  --someArg someValue
                TEST_SUFFIX .withArgs
                TEST_LIST   withArgsTests
)
set_tests_properties(${noArgsTests}   PROPERTIES TIMEOUT 10)
set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)

For backward compatibility, the following form is also supported:

gtest_add_tests(exe args files...)

include(GoogleTest)
set(FooTestArgs --foo 1 --bar 2)
add_executable(FooTest FooUnitTest.cxx)
gtest_add_tests(FooTest "${FooTestArgs}" AUTO)

gtest_discover_tests

Automatically add tests with CTest by querying the compiled test executable for available tests:

gtest_discover_tests(target
                     [EXTRA_ARGS arg1...]
                     [WORKING_DIRECTORY dir]
                     [TEST_PREFIX prefix]
                     [TEST_SUFFIX suffix]
                     [TEST_FILTER expr]
                     [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
                     [PROPERTIES name1 value1...]
                     [TEST_LIST var]
                     [DISCOVERY_TIMEOUT seconds]
                     [XML_OUTPUT_DIR dir]
                     [DISCOVERY_MODE <POST_BUILD|PRE_TEST>]
)

New in version 3.10.

gtest_discover_tests() sets up a post-build command on the test executable that generates the list of tests by parsing the output from running the test with the --gtest_list_tests argument. Compared to the source parsing approach of gtest_add_tests(), this ensures that the full list of tests, including instantiations of parameterized tests, is obtained. Since test discovery occurs at build time, it is not necessary to re-run CMake when the list of tests changes. However, it requires that CROSSCOMPILING_EMULATOR is properly set in order to function in a cross-compiling environment.

Additionally, setting properties on tests is somewhat less convenient, since the tests are not available at CMake time. Additional test properties may be assigned to the set of tests as a whole using the PROPERTIES option. If more fine-grained test control is needed, custom content may be provided through an external CTest script using the TEST_INCLUDE_FILES directory property. The set of discovered tests is made accessible to such a script via the <target>_TESTS variable.

The options are: