CMAKE-MODULES(7) CMake CMAKE-MODULES(7) NAME cmake-modules - CMake Modules Reference The modules listed here are part of the CMake distribution. Projects may provide further modules; their location(s) can be specified in the CMAKE_MODULE_PATH <#variable:CMAKE_MODULE_PATH> variable. UTILITY MODULES These modules are loaded using the include() <#command:include> command. AndroidTestUtilities Added in version 3.7. This module provides a command to create a test that pushes data needed for testing an Android device behavior onto a connected Android device. Load this module in a CMake project with: include(AndroidTestUtilities) Commands This module provides the following command: android_add_test_data Creates a test that automatically loads specified data onto an Android device: android_add_test_data( [FILES ...] [FILES_DEST ] [LIBS ...] [LIBS_DEST ] DEVICE_OBJECT_STORE DEVICE_TEST_DIR [NO_LINK_REGEX ...] ) This command accepts files and libraries needed to run project-specific tests as well as separate destinations for each. It will create a test that loads the files into a device object store and link to them from the specified destination. The files are only uploaded if they are not already in the object store. On the host operating system, files and libraries are copied at build time. For on-device testing, the files are loaded onto the device by the manufactured test at run time. This command accepts the following named parameters: FILES ... Zero or more files needed for testing. FILES_DEST Absolute path where the data files are expected to be. LIBS ... Zero or more libraries needed for testing. LIBS_DEST Absolute path where the libraries are expected to be. DEVICE_OBJECT_STORE Absolute path to the on-device location where the data files are initially stored. DEVICE_TEST_DIR Absolute path to the root directory of the on-device test location. NO_LINK_REGEX ... A list of regular expression patterns matching file names to be copied from the object store to the test directory, instead of being symlinked. Examples The following example shows how to use this module to create a test named example_setup_test that prepares data during the build phase. This test can then be run using ctest(1) <#manual:ctest(1)> to load the data onto the Android device. CMakeLists.txt include(AndroidTestUtilities) android_add_test_data( example_setup_test FILES data/protobuffer.p data/file.txt LIBS libs/library_1 libs/library_2 DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA" DEVICE_TEST_DIR "/data/local/tests/example" ) BundleUtilities This module provides utility commands for assembling standalone, bundle-style applications with CMake, such as macOS .app bundles or similar directory-based application bundles on other operating systems. Load this module in a CMake installation with: include(BundleUtilities) Note: Do not use this module at configure time (from CMakeLists.txt). Instead, include it and invoke its commands from an install(CODE) <# code> or install(SCRIPT) <#script>. Commands This module provides the following commands: o fixup_bundle() o copy_and_fixup_bundle() o verify_app() o get_bundle_main_executable() o get_dotapp_dir() o get_bundle_and_executable() o get_bundle_all_executables() o get_item_key() o get_item_rpaths() o clear_bundle_keys() o set_bundle_key_values() o get_bundle_keys() o copy_resolved_item_into_bundle() o copy_resolved_framework_into_bundle() o fixup_bundle_item() o verify_bundle_prerequisites() o verify_bundle_symlinks() fixup_bundle Prepares a bundle for distribution by fixing up its internal dependencies: fixup_bundle( [IGNORE_ITEM ...]) This command modifies the bundle in-place to make it self-contained and portable, so that it can be drag-n-drop copied to another machine and run there, assuming all of the system libraries are compatible. This command collects all dependencies (keys) for the executables and libraries in the bundle. For each dependency, it copies the required files into the bundle and adjusts them according to their own prerequisites. Once complete, it clears the collected keys and invokes the verify_app() command to ensure the final bundle is truly standalone. The arguments are: The path to the bundle to fix. This can be an .app directory or direct path to an executable. A list of libraries that must be fixed up, but that cannot be automatically determined by the otool output analysis (i.e. plugins). If plugins are passed to this command as this parameter, they should be installed or copied into the bundle before calling this command. A list of paths where libraries might be found. These paths are searched first when a target without any path info is given. Then standard system locations are also searched: PATH, Framework locations, /usr/lib, etc. IGNORE_ITEM ... Added in version 3.6. Optional list of file names to ignore (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"). copy_and_fixup_bundle Copies the bundle and fixes up the new copied bundle in-place: copy_and_fixup_bundle( ) This command makes a copy of the bundle at location and then fixes up the new copied bundle in-place at . The arguments are: The directory of the bundle being copied. The destination directory of the bundle copy. A list of libraries that must be fixed up, but that cannot be automatically determined by the otool output analysis (i.e. plugins). If plugins are passed to this command as this parameter, they should be installed or copied into the bundle before calling this command. A list of paths where libraries might be found. These paths are searched first when a target without any path info is given. Then standard system locations are also searched: PATH, Framework locations, /usr/lib, etc. verify_app Verifies that an application bundle appears valid based on running analysis tools on it: verify_app( [IGNORE_ITEM ...]) If the application fails verification, a message(FATAL_ERROR) <# command:message> is issued, halting the installation process. The arguments are: The path to the application to verify. This can be a .app directory or a standalone executable. IGNORE_ITEM ... Added in version 3.6. Optional list of file names to ignore (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"). get_bundle_main_executable Retrieves the main executable within a given application bundle: get_bundle_main_executable( ) The result is stored in a variable and will contain a full path name of the bundle's main executable file, or an error: prefixed string if it could not be determined. get_dotapp_dir Locates the enclosing .app directory for the given executable: get_dotapp_dir( ) This command retrieves the nearest parent dir whose name ends with .app given the full path to an executable and stores it to the variable. If there is no such parent dir, then it simply retrieves the directory containing the executable. The retrieved directory may or may not exist. get_bundle_and_executable Takes either a .app directory name or the name of an executable nested inside a .app directory and retrieves the path to the .app directory and the path to its main executable: get_bundle_and_executable( ) The arguments are: The name of the application being processed. Variable name in which to store the resulting path to the .app directory. In case of any error, this variable will contain an error message prefixed with string error:. Variable name in which to store the resulting main executable. In case of any error, this variable will contain an error message prefixed with string error:. Variable name in which the boolean result is stored whether this command was successful or not. get_bundle_all_executables Gets all executables of a given bundle: get_bundle_all_executables( ) This command scans bundle recursively for all executable files and stores them into a variable . get_item_key Generates a unique key for the given item: get_item_key( ) Given file name, this command generates key that should be unique considering the set of libraries that need copying or fixing up to make a bundle standalone. This is essentially the file name including extension with . replaced by _. This key is used as a prefix for CMake variables so that a set of variables can be associated with a given item based on its key. get_item_rpaths Gets RPATHS (run-time search paths) for the given item: get_item_rpaths( ) This command gets RPATHS of the file name and stores them to the variable with provided name . clear_bundle_keys Clears all variables associated with keys: clear_bundle_keys() This command loops over the list of keys, clearing all the variables associated with each key. After the loop, it clears the list of keys itself. This command should be called after the get_bundle_keys() command, when done working with a list of keys. set_bundle_key_values Adds a key to the list of keys: set_bundle_key_values( [] ) This command adds the key to the list (if necessary) for the given item. If added, also set all the variables associated with that key. The arguments are: Variable name holding the name of the key to be added to the list for the given item. The path to the top level loading path used for @loader_path replacement on Apple operating systems. When resolving item, @loader_path references will be resolved relative to the directory of the given context value (presumably another library). The item for which to add the key. The path to the top level executable used for @executable_path replacement on Apple operating systems. A list of paths where libraries might be found. These paths are searched first when a target without any path info is given. Then standard system locations are also searched: PATH, Framework locations, /usr/lib, etc. If set to 1 library symlink structure will be preserved. Optional run-time search paths for an executable file or library to help find files. get_bundle_keys Gets bundle keys: get_bundle_keys( [IGNORE_ITEM ...]) This command loops over all the executable and library files within bundle (and given as extra ) and accumulate a list of keys representing them. It sets values associated with each key such that they can be looped over all of them and copies prerequisite libs into the bundle and then does appropriate install_name_tool fixups. The arguments are: The path to the bundle to fix. This can be an .app directory or direct path to an executable. A list of libraries that must be fixed up, but that cannot be automatically determined by the otool output analysis (i.e. plugins). If plugins are passed to this command as this parameter, they should be installed or copied into the bundle before calling this command. A list of paths where libraries might be found. These paths are searched first when a target without any path info is given. Then standard system locations are also searched: PATH, Framework locations, /usr/lib, etc. Variable name holding a list of keys that represent all executable and library files within the bundle. IGNORE_ITEM ... Added in version 3.6. Optional list of file names to ignore (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"). copy_resolved_item_into_bundle Copies a resolved item into the bundle if necessary: copy_resolved_item_into_bundle( ) Copy is not necessary, if the is "the same as" the . copy_resolved_framework_into_bundle Copies a resolved framework into the bundle if necessary: copy_resolved_framework_into_bundle( ) Copy is not necessary, if the is "the same as" the . The following variables can be set before invoking this command: BU_COPY_FULL_FRAMEWORK_CONTENTS By default, this variable is not set. If full frameworks should be embedded in the bundles, set this variable to boolean true before calling the fixup_bundle() command. By default, this command copies the framework dylib itself plus the framework Resources directory. fixup_bundle_item Fixes up bundle item: fixup_bundle_item( ) This command gets the direct/non-system prerequisites of the and for each prerequisite, it changes the way it is referenced to the value of the _EMBEDDED_ITEM keyed variable for that prerequisite. Most likely changing to an @executable_path style reference. This command requires that the be inside the bundle already. In other words, if plugins are passed to fixup_bundle() command as its parameter, they should be installed or copied into the bundle before calling the fixup_bundle() command. Also, it changes the id of the item being fixed up to its own _EMBEDDED_ITEM value. Changes are accumulated in a local variable and one call is made to install_name_tool command-line tool at the end of this command with all the changes at once. The arguments are: The bundle item to be fixed up. The path to the top level executable used for @executable_path replacement on Apple operating systems. A list of paths where libraries might be found. These paths are searched first when a target without any path info is given. Then standard system locations are also searched: PATH, Framework locations, /usr/lib, etc. The following variables can be set before invoking this command: BU_CHMOD_BUNDLE_ITEMS If this variable is set to boolean true value then bundle items will be marked writable before install_name_tool tool tries to change them. verify_bundle_prerequisites Verifies that the sum of all prerequisites of all files inside the bundle are contained within the bundle or are system libraries, presumed to exist everywhere: verify_bundle_prerequisites( [IGNORE_ITEM ...] ) The arguments are: Name of the bundle being verified. Name of the variable in which to store a boolean result of whether a verification was successful. Name of the variable holding any informational messages produced by the verification. IGNORE_ITEM ... Added in version 3.6. Optional list of file names to ignore (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"). verify_bundle_symlinks Verifies that any symlinks found in the specified bundle point to other files that are already also in the bundle: verify_bundle_symlinks( ) Anything that points to an external file causes this command to fail the verification. The arguments are: Name of the bundle being verified. Name of the variable in which to store a boolean result of whether a verification was successful. Name of the variable holding any informational messages produced by the verification. Examples Using this module inside the installation code that is executed at the installation phase: CMakeLists.txt # ... install(CODE " include(BundleUtilities) set(BU_CHMOD_BUNDLE_ITEMS TRUE) fixup_bundle( \"${fixup_exe}\" \"${plugins}\" \"${bin_dir};${library_dir};${binary_dir}\" ) ") CheckCCompilerFlag This module provides a command to check whether the C compiler supports a given flag. Load this module in a CMake project with: include(CheckCCompilerFlag) Commands This module provides the following command: check_c_compiler_flag Checks once whether the C compiler supports a given flag: check_c_compiler_flag( ) This command checks once that the is accepted by the C compiler without producing a diagnostic message. Multiple flags can be specified in one argument as a string using a semicolon-separated list <#cmake-language-lists>. The result of the check is stored in the internal cache variable specified by , with boolean true for success and boolean false for failure. A successful result only indicates that the compiler did not report an error when given the flag. Whether the flag has any effect, or the intended one, is outside the scope of this module. Note: Since the underlying try_compile() <#command:try_compile> command also uses flags from variables like CMAKE__FLAGS <#variable:CMAKE__FLAGS>, unknown or unsupported flags in those variables may result in a false negative for this check. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_TRY_COMPILE_TARGET_TYPE <# variable:CMAKE_TRY_COMPILE_TARGET_TYPE> Internally, the try_compile() <#command:try_compile> command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to EXECUTABLE (the default), the check compiles and links the test source code as an executable program. If set to STATIC_LIBRARY, the test source code is compiled but not linked. Examples The following example demonstrates how to use this module to check support for the C compiler flag -fno-optimize-strlen, which disables optimizations related to the strlen() C function in GCC and Clang compilers. The result of the check is stored in the internal cache variable HAVE_FNO_OPTIMIZE_STRLEN, and the flag is conditionally enabled using the target_compile_options() <# command:target_compile_options> command. The $ <#genex:COMPILE_LANGUAGE:languages> generator expression ensures that the flag is added only to C source files. include(CheckCCompilerFlag) check_c_compiler_flag(-fno-optimize-strlen HAVE_FNO_OPTIMIZE_STRLEN) if(HAVE_FNO_OPTIMIZE_STRLEN) target_compile_options( example PRIVATE $<$:-fno-optimize-strlen> ) endif() See Also o The CheckCompilerFlag <#module:CheckCompilerFlag> module for a more general command to check whether a compiler flag is supported. CheckCompilerFlag Added in version 3.19. This module provides a command to check whether the compiler supports a given flag. Load this module in a CMake project with: include(CheckCompilerFlag) Commands This module provides the following command: check_compiler_flag Checks once whether the compiler supports a given flag: check_compiler_flag( ) This command checks once that the is accepted by the compiler without producing a diagnostic message. The result of the check is stored in the internal cache variable specified by . The arguments are: The language of the compiler used for the check. Supported languages are: C, CXX, CUDA, Fortran, HIP, ISPC, OBJC, and OBJCXX, and Swift. Added in version 3.21: Support for HIP language. Added in version 3.26: Support for Swift language. Compiler flag(s) to check. Multiple flags can be specified in one argument as a string using a semicolon-separated list <#cmake-language-lists>. Variable name of an internal cache variable to store the result of the check, with boolean true for success and boolean false for failure. A successful result only indicates that the compiler did not report an error when given the flag. Whether the flag has any effect, or the intended one, is outside the scope of this module. Note: Since the underlying try_compile() <#command:try_compile> command also uses flags from variables like CMAKE__FLAGS <#variable:CMAKE__FLAGS>, unknown or unsupported flags in those variables may result in a false negative for this check. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_TRY_COMPILE_TARGET_TYPE <# variable:CMAKE_TRY_COMPILE_TARGET_TYPE> Internally, the try_compile() <#command:try_compile> command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to EXECUTABLE (the default), the check compiles and links the test source code as an executable program. If set to STATIC_LIBRARY, the test source code is compiled but not linked. Examples The following example demonstrates how to use this module to check support for the C compiler flag -fno-optimize-strlen, which disables optimizations related to the strlen() C function in GCC and Clang compilers. The result of the check is stored in the internal cache variable HAVE_FNO_OPTIMIZE_STRLEN, and the flag is conditionally enabled using the target_compile_options() <# command:target_compile_options> command. The $ <#genex:COMPILE_LANGUAGE:languages> generator expression ensures that the flag is added only to C source files. include(CheckCompilerFlag) check_compiler_flag(C -fno-optimize-strlen HAVE_FNO_OPTIMIZE_STRLEN) if(HAVE_FNO_OPTIMIZE_STRLEN) target_compile_options( example PRIVATE $<$:-fno-optimize-strlen> ) endif() See Also o The CheckLinkerFlag <#module:CheckLinkerFlag> module to check whether a linker flag is supported by the compiler. CheckCSourceCompiles This module provides a command to check whether a C source can be built. Load this module in a CMake project with: include(CheckCSourceCompiles) Commands This module provides the following command: check_c_source_compiles Checks once whether the given C source code can be built: check_c_source_compiles( [FAIL_REGEX ...]) This command checks once that the source supplied in can be compiled (and linked into an executable). The result of the check is stored in the internal cache variable specified by . The arguments are: C source code to check. This must be an entire program, as written in a file containing the body block. All symbols used in the source code are expected to be declared as usual in their corresponding headers. Variable name of an internal cache variable to store the result of the check, with boolean true for success and boolean false for failure. FAIL_REGEX ... If one or more regular expression patterns are provided, then failure is determined by checking if anything in the compiler output matches any of the specified regular expressions. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_TRY_COMPILE_TARGET_TYPE <# variable:CMAKE_TRY_COMPILE_TARGET_TYPE> Internally, the try_compile() <#command:try_compile> command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to EXECUTABLE (the default), the check compiles and links the test source code as an executable program. If set to STATIC_LIBRARY, the test source code is compiled but not linked. Examples Checking whether C source code containing SSE2 intrinsic can be compiled and linked: include(CheckCSourceCompiles) check_c_source_compiles(" #include int main(void) { __m128d a = _mm_setzero_pd(); (void)a; return 0; } " PROJECT_HAVE_SSE2_INTRINSICS) See Also o The CheckSourceCompiles <#module:CheckSourceCompiles> module for a more general command to check whether source can be built. o The CheckSourceRuns <#module:CheckSourceRuns> module to check whether source can be built and run. CheckCSourceRuns This module provides a command to check whether a C source can be built and run. Load this module in a CMake project with: include(CheckCSourceRuns) Commands This module provides the following command: check_c_source_runs Checks once whether the given C source code compiles and links into an executable that can subsequently be run: check_c_source_runs( ) The C source supplied in must contain at least a main() function. The result of the check is stored in the internal cache variable specified by . If the code builds and runs with exit code 0, success is indicated by a boolean true value. Failure to build or run is indicated by a boolean false value, such as an empty string or an error message. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples The following example demonstrates how to use this module to check whether the C source code is supported and operational at runtime. The result of the check is stored in the internal cache variable HAVE_NORETURN. include(CheckCSourceRuns) check_c_source_runs(" #include #include noreturn void f(){ exit(0); } int main(void) { f(); return 1; } " HAVE_NORETURN) See Also o The CheckSourceRuns <#module:CheckSourceRuns> module for a more general command syntax. o The CheckSourceCompiles <#module:CheckSourceCompiles> module to check whether a source code can be built. CheckCXXCompilerFlag This module provides a command to check whether the C++ compiler supports a given flag. Load this module in a CMake project with: include(CheckCXXCompilerFlag) Commands This module provides the following command: check_cxx_compiler_flag Checks once whether the C++ compiler supports a given flag: check_cxx_compiler_flag( ) This command checks once that the is accepted by the CXX compiler without producing a diagnostic message. Multiple flags can be specified in one argument as a string using a semicolon-separated list <#cmake-language-lists>. The result of the check is stored in the internal cache variable specified by , with boolean true for success and boolean false for failure. A successful result only indicates that the compiler did not report an error when given the flag. Whether the flag has any effect, or the intended one, is outside the scope of this module. Note: Since the underlying try_compile() <#command:try_compile> command also uses flags from variables like CMAKE__FLAGS <#variable:CMAKE__FLAGS>, unknown or unsupported flags in those variables may result in a false negative for this check. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_TRY_COMPILE_TARGET_TYPE <# variable:CMAKE_TRY_COMPILE_TARGET_TYPE> Internally, the try_compile() <#command:try_compile> command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to EXECUTABLE (the default), the check compiles and links the test source code as an executable program. If set to STATIC_LIBRARY, the test source code is compiled but not linked. Examples The following example demonstrates how to use this module to check the C++ compiler flag -fsycl. The result of the check is stored in the internal cache variable HAVE_FSYCL_FLAG, and the flag is conditionally enabled using the target_compile_options() <# command:target_compile_options> command. The $ <#genex:COMPILE_LANGUAGE:languages> generator expression ensures that the flag is added only to CXX source files. include(CheckCXXCompilerFlag) check_cxx_compiler_flag(-fsycl HAVE_FSYCL_FLAG) if(HAVE_FSYCL_FLAG) target_compile_options( example PRIVATE $<$:-fsycl> ) endif() See Also o The CheckCompilerFlag <#module:CheckCompilerFlag> module for a more general command to check whether a compiler flag is supported. CheckCXXSourceCompiles This module provides a command to check whether a C++ source can be built. Load this module in a CMake project with: include(CheckCXXSourceCompiles) Commands This module provides the following command: check_cxx_source_compiles Checks once whether the given C++ source code can be built: check_cxx_source_compiles( [FAIL_REGEX ...]) This command checks once that the source supplied in can be compiled (and linked into an executable). The result of the check is stored in the internal cache variable specified by . The arguments are: C++ source code to check. This must be an entire program, as written in a file containing the body block. All symbols used in the source code are expected to be declared as usual in their corresponding headers. Variable name of an internal cache variable to store the result of the check, with boolean true for success and boolean false for failure. FAIL_REGEX ... If one or more regular expression patterns are provided, then failure is determined by checking if anything in the compiler output matches any of the specified regular expressions. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_TRY_COMPILE_TARGET_TYPE <# variable:CMAKE_TRY_COMPILE_TARGET_TYPE> Internally, the try_compile() <#command:try_compile> command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to EXECUTABLE (the default), the check compiles and links the test source code as an executable program. If set to STATIC_LIBRARY, the test source code is compiled but not linked. Examples The following example demonstrates how to check whether the C++ compiler supports a specific language feature. In this case, the check verifies if the compiler supports C++11 lambda expressions. The result is stored in the internal cache variable HAVE_CXX11_LAMBDAS: include(CheckCXXSourceCompiles) check_cxx_source_compiles(" int main() { auto lambda = []() { return 42; }; return lambda(); } " HAVE_CXX11_LAMBDAS) See Also o The CheckSourceCompiles <#module:CheckSourceCompiles> module for a more general command to check whether source can be built. o The CheckSourceRuns <#module:CheckSourceRuns> module to check whether source can be built and run. CheckCXXSourceRuns This module provides a command to check whether a C++ source can be built and run. Load this module in a CMake project with: include(CheckCXXSourceRuns) Commands This module provides the following command: check_cxx_source_runs Checks once whether the given C++ source code compiles and links into an executable that can subsequently be run: check_cxx_source_runs( ) The C++ source supplied in must contain at least a main() function. The result of the check is stored in the internal cache variable specified by . If the code builds and runs with exit code 0, success is indicated by a boolean true value. Failure to build or run is indicated by a boolean false value, such as an empty string or an error message. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples The following example demonstrates how to check whether the C++ standard library is functional and std::vector works at runtime. If the source compiles, links, and runs successfully, internal cache variable HAVE_WORKING_STD_VECTOR will be set to boolean true value. Code is supplied using Bracket Argument <#bracket-argument> for easier embedded quotes handling: include(CheckCXXSourceRuns) check_cxx_source_runs([[ #include #include int main() { std::vector v = {1, 2, 3}; if (v.size() != 3) return 1; std::cout << "Vector works correctly." << std::endl; return 0; } ]] HAVE_WORKING_STD_VECTOR) See Also o The CheckSourceRuns <#module:CheckSourceRuns> module for a more general command syntax. o The CheckSourceCompiles <#module:CheckSourceCompiles> module to check whether a source code can be built. CheckCXXSymbolExists This module provides a command to check whether a C++ symbol exists. Load this module in a CMake project with: include(CheckCXXSymbolExists) Commands This module provides the following command: check_cxx_symbol_exists Checks once whether a symbol exists as a function, variable, or preprocessor macro in C++: check_cxx_symbol_exists( ) This command checks whether the is available after including the specified header file(s) , and stores the result in the internal cache variable . Multiple header files can be specified in one argument as a string using a semicolon-separated list <#cmake-language-lists>. If the header files define the symbol as a macro, it is considered available and assumed to work. If the symbol is declared as a function or variable, the check also ensures that it links successfully (i.e., the symbol must exist in a linked library or object file). Symbols that are types, enum values, or C++ templates are not recognized. For those, consider using the CheckTypeSize <# module:CheckTypeSize> or CheckSourceCompiles <# module:CheckSourceCompiles> module instead. This command is intended to check symbols as they appear in C++. For C symbols, use the CheckSymbolExists <# module:CheckSymbolExists> module instead. Note: This command is unreliable for symbols that are (potentially) overloaded functions. Since there is no reliable way to predict whether a given function in the system environment may be defined as an overloaded function or may be an overloaded function on other systems or will become so in the future, it is generally advised to use the CheckSourceCompiles <#module:CheckSourceCompiles> module for checking any function symbol (unless it is certain the checked function is not overloaded on other systems or will not be so in the future). Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples The following example demonstrates how to check for the presence of a preprocessor macro SEEK_SET and the C++ function std::fopen() from the header using this module: include(CheckCXXSymbolExists) # Check for macro SEEK_SET check_cxx_symbol_exists(SEEK_SET "cstdio" HAVE_SEEK_SET) # Check for function std::fopen check_cxx_symbol_exists(std::fopen "cstdio" HAVE_STD_FOPEN) See Also o The CheckSymbolExists <#module:CheckSymbolExists> module to check whether a C symbol exists. CheckFortranCompilerFlag Added in version 3.3. This module provides a command to check whether the Fortran compiler supports a given flag. Load this module in a CMake project with: include(CheckFortranCompilerFlag) Commands This module provides the following command: check_fortran_compiler_flag Checks once whether the Fortran compiler supports a given flag: check_fortran_compiler_flag( ) This command checks once that the is accepted by the Fortran compiler without producing a diagnostic message. Multiple flags can be specified in one argument as a string using a semicolon-separated list <#cmake-language-lists>. The result of the check is stored in the internal cache variable specified by , with boolean true for success and boolean false for failure. A successful result only indicates that the compiler did not report an error when given the flag. Whether the flag has any effect, or the intended one, is outside the scope of this module. Note: Since the underlying try_compile() <#command:try_compile> command also uses flags from variables like CMAKE__FLAGS <#variable:CMAKE__FLAGS>, unknown or unsupported flags in those variables may result in a false negative for this check. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_TRY_COMPILE_TARGET_TYPE <# variable:CMAKE_TRY_COMPILE_TARGET_TYPE> Internally, the try_compile() <#command:try_compile> command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to EXECUTABLE (the default), the check compiles and links the test source code as an executable program. If set to STATIC_LIBRARY, the test source code is compiled but not linked. Examples The following example demonstrates how to use this module to check the Fortran compiler flag -fallow-argument-mismatch. The result of the check is stored in the internal cache variable HAVE_FORTRAN_FLAG, and the flag is conditionally enabled using the target_compile_options() <# command:target_compile_options> command. The $ <#genex:COMPILE_LANGUAGE:languages> generator expression ensures that the flag is added only to Fortran source files. include(CheckFortranCompilerFlag) check_fortran_compiler_flag(-fallow-argument-mismatch HAVE_FORTRAN_FLAG) if(HAVE_FORTRAN_FLAG) target_compile_options( example PRIVATE $<$:-fallow-argument-mismatch> ) endif() See Also o The CheckCompilerFlag <#module:CheckCompilerFlag> module for a more general command to check whether a compiler flag is supported. CheckFortranFunctionExists This module provides a command to check whether a Fortran function exists. Load this module in a CMake project with: include(CheckFortranFunctionExists) Commands This module provides the following command: check_fortran_function_exists Checks once whether a Fortran function exists: check_fortran_function_exists( ) The name of the Fortran function. The name of the variable in which to store the check result. This variable will be created as an internal cache variable. Note: This command does not detect functions provided by Fortran modules. In general, it is recommended to use CheckSourceCompiles <#module:CheckSourceCompiles> instead to determine whether a Fortran function or subroutine is available. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). Examples Example: Isolated Check With Linked Libraries In the following example, this module is used in combination with the CMakePushCheckState <#module:CMakePushCheckState> module to temporarily modify the required linked libraries (via CMAKE_REQUIRED_LIBRARIES) and verify whether the Fortran function dgesv is available for linking. The result is stored in the internal cache variable PROJECT_HAVE_DGESV: include(CheckFortranFunctionExists) include(CMakePushCheckState) find_package(LAPACK) if(TARGET LAPACK::LAPACK) cmake_push_check_state(RESET) set(CMAKE_REQUIRED_LIBRARIES LAPACK::LAPACK) check_fortran_function_exists(dgesv PROJECT_HAVE_DGESV) cmake_pop_check_state() endif() See Also o The CheckFunctionExists <#module:CheckFunctionExists> module to check whether a C function exists. o The CheckSourceCompiles <#module:CheckSourceCompiles> module to check whether source code can be compiled. CheckFortranSourceCompiles Added in version 3.1. This module provides a command to check whether a Fortran source can be built. Load this module in a CMake project with: include(CheckFortranSourceCompiles) Commands This module provides the following command: check_fortran_source_compiles Checks once whether the given Fortran source code can be built: check_fortran_source_compiles( [FAIL_REGEX ...] [SRC_EXT ] ) This command checks once that the source supplied in can be compiled (and linked into an executable). The result of the check is stored in the internal cache variable specified by . The arguments are: Fortran source code to check. This must be an entire program, as written in a file containing the body block. All symbols used in the source code are expected to be declared as usual in their corresponding headers. Variable name of an internal cache variable to store the result of the check, with boolean true for success and boolean false for failure. FAIL_REGEX ... If this option is provided with one or more regular expressions, then failure is determined by checking if anything in the compiler output matches any of the specified regular expressions. SRC_EXT Added in version 3.7. By default, the test source file used for the check will be given a .F file extension. This option can be used to override this with . instead - .F90 is a typical choice. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_TRY_COMPILE_TARGET_TYPE <# variable:CMAKE_TRY_COMPILE_TARGET_TYPE> Internally, the try_compile() <#command:try_compile> command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to EXECUTABLE (the default), the check compiles and links the test source code as an executable program. If set to STATIC_LIBRARY, the test source code is compiled but not linked. Examples Checking whether the Fortran compiler supports the pure procedure attribute: include(CheckFortranSourceCompiles) check_fortran_source_compiles(" pure subroutine foo() end subroutine program test call foo() end " HAVE_PURE SRC_EXT "F90") See Also o The CheckSourceCompiles <#module:CheckSourceCompiles> module for a more general command to check whether source can be built. o The CheckSourceRuns <#module:CheckSourceRuns> module to check whether source can be built and run. CheckFortranSourceRuns Added in version 3.14. This module provides a command to check whether a Fortran source can be built and run. Load this module in a CMake project with: include(CheckFortranSourceRuns) Commands This module provides the following command: check_fortran_source_runs Checks once whether the given Fortran source compiles and links into an executable that can subsequently be run. check_fortran_source_runs( [SRC_EXT ]) The Fortran source supplied in must contain a Fortran program unit. The result of the check is stored in the internal cache variable specified by . If the code builds and runs with exit code 0, success is indicated by a boolean true value. Failure to build or run is indicated by a boolean false value, such as an empty string or an error message. The options are: SRC_EXT By default, the internal test source file used for the check will be given a .F90 file extension. This option can be used to change the extension to . instead. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples The following example shows how to use this module to check whether a Fortran source code runs and store the result of the check in an internal cache variable HAVE_COARRAY: include(CheckFortranSourceRuns) check_fortran_source_runs([[ program test real :: x[*] call co_sum(x) end program ]] HAVE_COARRAY) See Also o The CheckSourceRuns <#module:CheckSourceRuns> module for a more general command syntax. o The CheckSourceCompiles <#module:CheckSourceCompiles> module to check whether a source code can be built. CheckFunctionExists This module provides a command to check whether a C function exists. Load this module in a CMake project with: include(CheckFunctionExists) Commands This module provides the following command: check_function_exists Checks once whether a C function can be linked from system libraries: check_function_exists( ) This command checks whether the is provided by libraries on the system, and stores the result in an internal cache variable . Note: Prefer using CheckSymbolExists <#module:CheckSymbolExists> or CheckSourceCompiles <#module:CheckSourceCompiles> instead of this command, for the following reasons: o check_function_exists() can't detect functions that are inlined in headers or defined as preprocessor macros. o check_function_exists() can't detect anything in the 32-bit versions of the Win32 API, because of a mismatch in calling conventions. o check_function_exists() only verifies linking, it does not verify that the function is declared in system headers. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples Example: Basic Usage In the following example, a check is performed to determine whether the linker sees the C function fopen(), and the result is stored in the HAVE_FOPEN internal cache variable: include(CheckFunctionExists) check_function_exists(fopen HAVE_FOPEN) Example: Missing Declaration As noted above, the CheckSymbolExists <#module:CheckSymbolExists> module is preferred for checking C functions, since it also verifies whether the function is declared or defined as a macro. In the following example, this module is used to check an edge case where a function may not be declared in system headers. For instance, on macOS, the fdatasync() function may be available in the C library, but its declaration is not provided in the unistd.h system header. CMakeLists.txt include(CheckFunctionExists) include(CheckSymbolExists) check_symbol_exists(fdatasync "unistd.h" HAVE_FDATASYNC) # Check if fdatasync() is available in the C library. if(NOT HAVE_FDATASYNC) check_function_exists(fdatasync HAVE_FDATASYNC_WITHOUT_DECL) endif() In such a case, the project can provide its own declaration if missing: example.c #ifdef HAVE_FDATASYNC_WITHOUT_DECL extern int fdatasync(int); #endif See Also o The CheckSymbolExists <#module:CheckSymbolExists> module to check whether a C symbol exists. o The CheckSourceCompiles <#module:CheckSourceCompiles> module to check whether a source code can be compiled. o The CheckFortranFunctionExists <#module:CheckFortranFunctionExists> module to check whether a Fortran function exists. CheckIncludeFile This module provides a command to check C header file. Load this module in a CMake project with: include(CheckIncludeFile) Commands This module provides the following command: check_include_file Checks once whether a header file exists and can be included in C code: check_include_file( []) The arguments are: A header file to be checked. The name of the variable to store the result of the check. This variable will be created as an internal cache variable. (Optional) A semicolon-separated list <#cmake-language- lists> of additional compilation flags to be added to the check. Alternatively, flags can be also specified with the CMAKE_REQUIRED_FLAGS variable below. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Added in version 3.12: The CMAKE_REQUIRED_LIBRARIES variable, if policy CMP0075 <#policy:CMP0075> is set to NEW. Examples Example: Checking C Header Checking whether the C header exists and storing the check result in the HAVE_UNISTD_H cache variable: include(CheckIncludeFile) check_include_file(unistd.h HAVE_UNISTD_H) Example: Isolated Check In the following example, this module is used in combination with the CMakePushCheckState <#module:CMakePushCheckState> module to temporarily modify the required compile definitions (via CMAKE_REQUIRED_DEFINITIONS) and verify whether the C header is available. The result is stored in the internal cache variable HAVE_UCONTEXT_H. For example, on macOS, the ucontext API is deprecated, and headers may be hidden unless certain feature macros are defined. In particular, defining _XOPEN_SOURCE (without a value) can expose the necessary symbols without enabling broader POSIX or SUS (Single Unix Specification) features (values 500 or greater). include(CheckIncludeFile) include(CMakePushCheckState) cmake_push_check_state(RESET) if(CMAKE_SYSTEM_NAME STREQUAL "Darwin") set(CMAKE_REQUIRED_DEFINITIONS -D_XOPEN_SOURCE) endif() check_include_file(ucontext.h HAVE_UCONTEXT_H) cmake_pop_check_state() See Also o The CheckIncludeFileCXX <#module:CheckIncludeFileCXX> module to check for single C++ header. o The CheckIncludeFiles <#module:CheckIncludeFiles> module to check for one or more C or C++ headers at once. CheckIncludeFileCXX This module provides a command to check a C++ header file. Load this module in a CMake project with: include(CheckIncludeFileCXX) Commands This module provides the following command: check_include_file_cxx Checks once whether a header file exists and can be included in C++ code: check_include_file_cxx( []) The arguments are: A header file to be checked. The name of the variable to store the result of the check. This variable will be created as an internal cache variable. (Optional) A semicolon-separated list <#cmake-language- lists> of additional compilation flags to be added to the check. Alternatively, flags can be also specified with the CMAKE_REQUIRED_FLAGS variable below. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Added in version 3.12: The CMAKE_REQUIRED_LIBRARIES variable, if policy CMP0075 <#policy:CMP0075> is set to NEW. Examples Checking whether the C++23 header exists and storing the check result in the HAVE_STDFLOAT_HEADER cache variable: include(CheckIncludeFileCXX) check_include_file_cxx(stdfloat HAVE_STDFLOAT_HEADER) See Also o The CheckIncludeFile <#module:CheckIncludeFile> module to check for single C header. o The CheckIncludeFiles <#module:CheckIncludeFiles> module to check for one or more C or C++ headers at once. CheckIncludeFiles This module provides a command to check one or more C/C++ header files. Load this module in a CMake project with: include(CheckIncludeFiles) Commands This module provides the following command: check_include_files Checks once whether one or more header files exist and can be included together in C or C++ code: check_include_files( [LANGUAGE ]) The arguments are: A semicolon-separated list <#cmake-language-lists> of header files to be checked. The name of the variable to store the result of the check. This variable will be created as an internal cache variable. LANGUAGE Added in version 3.11. If set, the specified compiler will be used to perform the check. Acceptable values are C and CXX. If this option is not given, the C compiler will be used if enabled. If the C compiler is not enabled, the C++ compiler will be used if enabled. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Added in version 3.12: The CMAKE_REQUIRED_LIBRARIES variable, if policy CMP0075 <#policy:CMP0075> is set to NEW. Examples Checking one or more C headers and storing the check result in cache variables: include(CheckIncludeFiles) check_include_files(sys/socket.h HAVE_SYS_SOCKET_H) if(HAVE_SYS_SOCKET_H) # The header on Darwin and BSD-like systems is not self-contained # and also requires check_include_files("sys/socket.h;net/if.h" HAVE_NET_IF_H) else() check_include_files(net/if.h HAVE_NET_IF_H) endif() The LANGUAGE option can be used to specify which compiler to use. For example, checking multiple C++ headers, when both C and CXX languages are enabled in the project: include(CheckIncludeFiles) check_include_files("header_1.hpp;header_2.hpp" HAVE_HEADERS LANGUAGE CXX) See Also o The CheckIncludeFile <#module:CheckIncludeFile> module to check for a single C header. o The CheckIncludeFileCXX <#module:CheckIncludeFileCXX> module to check for a single C++ header. CheckIPOSupported Added in version 3.9. This module provides a command to check whether the compiler supports interprocedural optimization (IPO/LTO). Load this module in a CMake project with: include(CheckIPOSupported) Interprocedural optimization is a compiler technique that performs optimizations across translation units (i.e., across source files), allowing the compiler to analyze and optimize the entire program as a whole rather than file-by-file. This can improve performance by enabling more aggressive inlining and dead code elimination. When these optimizations are applied at link time, the process is typically referred to as link-time optimization (LTO), which is a common form of IPO. In CMake, interprocedural optimization can be enabled on a per-target basis using the INTERPROCEDURAL_OPTIMIZATION <# prop_tgt:INTERPROCEDURAL_OPTIMIZATION> target property, or for all targets in the current scope using the CMAKE_INTERPROCEDURAL_OPTIMIZATION <# variable:CMAKE_INTERPROCEDURAL_OPTIMIZATION> variable. Use this module before enabling the interprocedural optimization on targets to ensure the compiler supports IPO/LTO. Commands This module provides the following command: check_ipo_supported Checks whether the compiler supports interprocedural optimization (IPO/LTO): check_ipo_supported( [RESULT ] [OUTPUT ] [LANGUAGES ...] ) Options are: RESULT Set variable to YES if IPO is supported by the compiler and NO otherwise. If this option is not given then the command will issue a fatal error if IPO is not supported. OUTPUT Set variable with details about any error. LANGUAGES ... Specify languages whose compilers to check. The following languages are supported: o C o CXX o CUDA Added in version 3.25. o Fortran If this option is not given, the default languages are picked from the current ENABLED_LANGUAGES <# prop_gbl:ENABLED_LANGUAGES> global property. Note: To use check_ipo_supported(), policy CMP0069 <# policy:CMP0069> must be set to NEW; otherwise, a fatal error will occur. Added in version 3.13: Support for Visual Studio Generators <# visual-studio-generators>. Added in version 3.24: The check uses the caller's CMAKE__FLAGS <#variable:CMAKE__FLAGS> and CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> values. See policy CMP0138 <#policy:CMP0138>. Examples Checking whether the compiler supports IPO and emitting a fatal error if it is not supported: include(CheckIPOSupported) check_ipo_supported() # fatal error if IPO is not supported set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) The following example demonstrates how to use this module to enable IPO for the target only when supported by the compiler and to issue a warning if it is not. Additionally, projects may want to provide a configuration option to control when IPO is enabled. For example: option(FOO_ENABLE_IPO "Enable IPO/LTO") if(FOO_ENABLE_IPO) include(CheckIPOSupported) check_ipo_supported(RESULT result OUTPUT output) if(result) set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) else() message(WARNING "IPO is not supported: ${output}") endif() endif() CheckLanguage This module provides a command to check whether a language can be enabled using the enable_language() <#command:enable_language> or project() <#command:project> commands. Load this module in a CMake project with: include(CheckLanguage) This module is useful when a project does not always require a specific language but may need to enable it for certain parts. Commands This module provides the following command: check_language Checks whether a language can be enabled in a CMake project: check_language() This command attempts to enable the language in a test project and records the results in the following cache variables: CMAKE__COMPILER <#variable:CMAKE__COMPILER> If the language can be enabled, this variable is set to the compiler that was found. If the language cannot be enabled, this variable is set to NOTFOUND. If this variable is already set, either explicitly or cached by a previous call, the check is skipped. CMAKE__HOST_COMPILER <# variable:CMAKE__HOST_COMPILER> This variable is set when is CUDA or HIP. If the check detects an explicit host compiler that is required for compilation, this variable will be set to that compiler. If the check detects that no explicit host compiler is needed, this variable will be cleared. If this variable is already set, its value is preserved only if CMAKE__COMPILER <# variable:CMAKE__COMPILER> is also set. Otherwise, the check runs and overwrites CMAKE__HOST_COMPILER <#variable:CMAKE__HOST_COMPILER> with a new result. Note that CMAKE__HOST_COMPILER <# variable:CMAKE__HOST_COMPILER> documents it should not be set without also setting CMAKE__COMPILER <# variable:CMAKE__COMPILER> to a NVCC compiler. CMAKE__PLATFORM <#variable:CMAKE_HIP_PLATFORM> This variable is set to the detected GPU platform when is HIP. If this variable is already set, its value is always preserved. Only compatible values will be considered for CMAKE__COMPILER <#variable:CMAKE__COMPILER>. Examples The following example checks for the availability of the Fortran language and enables it if possible: include(CheckLanguage) check_language(Fortran) if(CMAKE_Fortran_COMPILER) enable_language(Fortran) else() message(STATUS "No Fortran support") endif() CheckLibraryExists This module provides a command to check whether a C library exists. Load this module in a CMake project with: include(CheckLibraryExists) Commands This module provides the following command: check_library_exists Checks once whether a specified library exists and a given C function is available: check_library_exists( ) This command attempts to link a test executable that uses the specified C to verify that it is provided by either a system or user-provided . The arguments are: The name of the library, a full path to a library file, or an Imported Target <#imported-targets>. The name of a function that should be available in the system or user-provided library . The directory containing the library file. It is added to the link search path during the check. If this is an empty string, only the default library search paths are used. The name of the variable in which to store the check result. This variable will be created as an internal cache variable. Note: This command is intended for performing basic sanity checks to verify that a library provides the expected functionality, or that the correct library is being located. However, it only verifies that a function symbol can be linked successfully - it does not ensure that the function is declared in library headers, nor can it detect functions that are inlined or defined as preprocessor macros. For more robust detection of function availability, prefer using CheckSymbolExists <#module:CheckSymbolExists> or CheckSourceCompiles <#module:CheckSourceCompiles>. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples Checking if the curl library exists in the default paths and has the curl_easy_perform() function: include(CheckLibraryExists) check_library_exists(curl curl_easy_perform "" HAVE_LIBRARY_CURL) To check if library exists in specific non-standard location and has a specified function: include(CheckLibraryExists) check_library_exists(curl curl_easy_perform "/opt/curl/lib" HAVE_LIBRARY_CURL) Also Imported Targets <#imported-targets> (for example, from the find_package() call) can be used: find_package(CURL) # ... if(TARGET CURL::libcurl) include(CheckLibraryExists) check_library_exists(CURL::libcurl curl_easy_perform "" HAVE_LIBRARY_CURL) endif() See Also o The CheckSymbolExists <#module:CheckSymbolExists> module to check whether a C symbol exists. CheckLinkerFlag Added in version 3.18. This module provides a command to check whether a given link flag is supported by the compiler. Load this module in a CMake project with: include(CheckLinkerFlag) Commands This module provides the following command: check_linker_flag Checks once whether the compiler supports a given link flag: check_linker_flag( ) This command checks once whether the linker flag is accepted by the compiler without producing a diagnostic message. The arguments are: The language of the compiler used for the check. Supported languages are C, CXX, CUDA, Fortran, HIP, OBJC, OBJCXX, and Swift. Added in version 3.19: Support for CUDA language. Added in version 3.21: Support for HIP language. Added in version 3.26: Support for Swift language. Linker flag(s) to check. Multiple flags can be specified in one argument as a string using a semicolon-separated list <#cmake-language-lists>. The underlying implementation uses the LINK_OPTIONS <# prop_tgt:LINK_OPTIONS> target property to test the specified flag. The LINKER: (and SHELL:) prefixes may be used, as described in the Handling Compiler Driver Differences section. The name of the variable to store the check result. This variable will be created as an internal cache variable. This command temporarily sets the CMAKE_REQUIRED_LINK_OPTIONS variable and calls the check_source_compiles() <# command:check_source_compiles> command from the CheckSourceCompiles <#module:CheckSourceCompiles> module. A successful result only indicates that the compiler did not report an error when given the link flag. Whether the flag has any effect, or the intended one, is outside the scope of this module. Note: Since the underlying try_compile() <#command:try_compile> command also uses flags from variables like CMAKE__FLAGS <#variable:CMAKE__FLAGS>, unknown or unsupported flags in those variables may result in a false negative for this check. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Handling Compiler Driver Differences To pass options to the linker tool, each compiler driver has its own syntax. The LINKER: prefix and , separator can be used to specify, in a portable way, options to pass to the linker tool. LINKER: is replaced by the appropriate driver option and , by the appropriate driver separator. The driver prefix and driver separator are given by the values of the CMAKE__LINKER_WRAPPER_FLAG <# variable:CMAKE__LINKER_WRAPPER_FLAG> and CMAKE__LINKER_WRAPPER_FLAG_SEP <# variable:CMAKE__LINKER_WRAPPER_FLAG_SEP> variables. For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for Clang and -Wl,-z,defs for GNU GCC. The LINKER: prefix can be specified as part of a SHELL: prefix expression. The LINKER: prefix supports, as an alternative syntax, specification of arguments using the SHELL: prefix and space as separator. The previous example then becomes "LINKER:SHELL:-z defs". Note: Specifying the SHELL: prefix anywhere other than at the beginning of the LINKER: prefix is not supported. Examples Example: Checking Linker Flag The following example shows how to use this module to check the -z relro linker flag, which is supported on many Unix-like systems to enable read-only relocations for improved binary security. If the flag is supported by the linker, it is conditionally added to the executable target using the target_link_options() <#command:target_link_options>. The LINKER: prefix is used to pass the flag to the linker in a portable and compiler-independent way. include(CheckLinkerFlag) check_linker_flag(C "LINKER:-z,relro" HAVE_Z_RELRO) add_executable(example main.c) if(HAVE_Z_RELRO) target_link_options(example PRIVATE "LINKER:-z,relro") endif() Example: Checking Multiple Flags In the following example, multiple linker flags are checked simultaneously: include(CheckLinkerFlag) check_linker_flag(C "LINKER:-z,relro;LINKER:-z,now" HAVE_FLAGS) add_executable(example main.c) if(HAVE_FLAGS) target_link_options(example PRIVATE LINKER:-z,relro LINKER:-z,now) endif() See Also o The CMAKE_LINKER_TYPE <#variable:CMAKE_LINKER_TYPE> variable to specify the linker, which will be used also by this module. o The CheckCompilerFlag <#module:CheckCompilerFlag> module to check whether a compiler flag is supported. CheckOBJCCompilerFlag Added in version 3.16. This module provides a command to check whether the Objective-C compiler supports a given flag. Load this module in a CMake project with: include(CheckOBJCCompilerFlag) Commands This module provides the following command: check_objc_compiler_flag Checks once whether the Objective-C compiler supports a given flag: check_objc_compiler_flag( ) This command checks once that the is accepted by the OBJC compiler without producing a diagnostic message. Multiple flags can be specified in one argument as a string using a semicolon-separated list <#cmake-language-lists>. The result of the check is stored in the internal cache variable specified by , with boolean true for success and boolean false for failure. A successful result only indicates that the compiler did not report an error when given the flag. Whether the flag has any effect, or the intended one, is outside the scope of this module. Note: Since the underlying try_compile() <#command:try_compile> command also uses flags from variables like CMAKE__FLAGS <#variable:CMAKE__FLAGS>, unknown or unsupported flags in those variables may result in a false negative for this check. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_TRY_COMPILE_TARGET_TYPE <# variable:CMAKE_TRY_COMPILE_TARGET_TYPE> Internally, the try_compile() <#command:try_compile> command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to EXECUTABLE (the default), the check compiles and links the test source code as an executable program. If set to STATIC_LIBRARY, the test source code is compiled but not linked. Examples The following example demonstrates how to use this module to check the Objective-C compiler flag -fobjc-arc. The result of the check is stored in the internal cache variable HAVE_OBJC_ARC, and the flag is conditionally enabled using the target_compile_options() <# command:target_compile_options> command. The $ <#genex:COMPILE_LANGUAGE:languages> generator expression ensures that the flag is added only to OBJC source files. include(CheckOBJCCompilerFlag) check_objc_compiler_flag(-fobjc-arc HAVE_OBJC_ARC) if(HAVE_OBJC_ARC) target_compile_options( example PRIVATE $<$:-fobjc-arc> ) endif() See Also o The CheckCompilerFlag <#module:CheckCompilerFlag> module for a more general command to check whether a compiler flag is supported. CheckOBJCSourceCompiles Added in version 3.16. This module provides a command to check whether an Objective-C source can be built. Load this module in a CMake project with: include(CheckOBJCSourceCompiles) Commands This module provides the following command: check_objc_source_compiles Checks once whether the given Objective-C source code can be built: check_objc_source_compiles( [FAIL_REGEX ...]) This command checks once that the source supplied in can be compiled (and linked into an executable). The result of the check is stored in the internal cache variable specified by . The arguments are: Source code to check. This must be an entire program, as written in a file containing the body block. All symbols used in the source code are expected to be declared as usual in their corresponding headers. Variable name of an internal cache variable to store the result of the check, with boolean true for success and boolean false for failure. FAIL_REGEX ... If this option is provided with one or more regular expressions, then failure is determined by checking if anything in the compiler output matches any of the specified regular expressions. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_TRY_COMPILE_TARGET_TYPE <# variable:CMAKE_TRY_COMPILE_TARGET_TYPE> Internally, the try_compile() <#command:try_compile> command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to EXECUTABLE (the default), the check compiles and links the test source code as an executable program. If set to STATIC_LIBRARY, the test source code is compiled but not linked. Examples In the following example, this module is used to check whether the provided Objective-C source code compiles and links. Result of the check is stored in the internal cache variable HAVE_WORKING_CODE. include(CheckOBJCSourceCompiles) check_objc_source_compiles(" #import int main() { NSObject *foo; return 0; } " HAVE_WORKING_CODE) See Also o The CheckSourceCompiles <#module:CheckSourceCompiles> module for a more general command to check whether source can be built. o The CheckSourceRuns <#module:CheckSourceRuns> module to check whether source can be built and run. CheckOBJCSourceRuns Added in version 3.16. This module provides a command to check whether an Objective-C source can be built and run. Load this module in a CMake project with: include(CheckOBJCSourceRuns) Commands This module provides the following command: check_objc_source_runs Checks once whether the given Objective-C source code compiles and links into an executable that can subsequently be run: check_objc_source_runs( ) The Objective-C source supplied in must contain at least a main() function. The result of the check is stored in the internal cache variable specified by . If the code builds and runs with exit code 0, success is indicated by a boolean true value. Failure to build or run is indicated by a boolean false value, such as an empty string or an error message. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples In the following example, this module is used to check whether the provided Objective-C source code builds and runs. Result of the check is stored in an internal cache variable HAVE_WORKING_CODE. include(CheckOBJCSourceRuns) check_objc_source_runs(" #import int main() { NSObject *foo; return 0; } " HAVE_WORKING_CODE) See Also o The CheckSourceRuns <#module:CheckSourceRuns> module for a more general command syntax. o The CheckSourceCompiles <#module:CheckSourceCompiles> module to check whether a source code can be built. CheckOBJCXXCompilerFlag Added in version 3.16. This module provides a command to check whether the Objective-C++ compiler supports a given flag. Load this module in a CMake project with: include(CheckOBJCXXCompilerFlag) Commands This module provides the following command: check_objcxx_compiler_flag Checks once whether the Objective-C++ compiler supports a given flag: check_objcxx_compiler_flag( ) This command checks once that the is accepted by the OBJCXX compiler without producing a diagnostic message. Multiple flags can be specified in one argument as a string using a semicolon-separated list <#cmake-language-lists>. The result of the check is stored in the internal cache variable specified by , with boolean true for success and boolean false for failure. A successful result only indicates that the compiler did not report an error when given the flag. Whether the flag has any effect, or the intended one, is outside the scope of this module. Note: Since the underlying try_compile() <#command:try_compile> command also uses flags from variables like CMAKE__FLAGS <#variable:CMAKE__FLAGS>, unknown or unsupported flags in those variables may result in a false negative for this check. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_TRY_COMPILE_TARGET_TYPE <# variable:CMAKE_TRY_COMPILE_TARGET_TYPE> Internally, the try_compile() <#command:try_compile> command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to EXECUTABLE (the default), the check compiles and links the test source code as an executable program. If set to STATIC_LIBRARY, the test source code is compiled but not linked. Examples The following example demonstrates how to use this module to check the Objective-C++ compiler flag -fobjc-arc. The result of the check is stored in the internal cache variable HAVE_OBJC_ARC, and the flag is conditionally enabled using the target_compile_options() <# command:target_compile_options> command. The $ <#genex:COMPILE_LANGUAGE:languages> generator expression ensures that the flag is added only to OBJCXX source files. include(CheckOBJCXXCompilerFlag) check_objcxx_compiler_flag(-fobjc-arc HAVE_OBJC_ARC) if(HAVE_OBJC_ARC) target_compile_options( example PRIVATE $<$:-fobjc-arc> ) endif() See Also o The CheckCompilerFlag <#module:CheckCompilerFlag> module for a more general command to check whether a compiler flag is supported. CheckOBJCXXSourceCompiles Added in version 3.16. This module provides a command to check whether an Objective-C++ source can be built. Load this module in a CMake project with: include(CheckOBJCXXSourceCompiles) Commands This module provides the following command: check_objcxx_source_compiles Checks once whether the given Objective-C++ source code can be built: check_objcxx_source_compiles( [FAIL_REGEX ...]) This command checks once that the source supplied in can be compiled (and linked into an executable). The result of the check is stored in the internal cache variable specified by . The arguments are: Objective-C++ source code to check. This must be an entire program, as written in a file containing the body block. All symbols used in the source code are expected to be declared as usual in their corresponding headers. Variable name of an internal cache variable to store the result of the check, with boolean true for success and boolean false for failure. FAIL_REGEX ... If this option is provided with one or more regular expressions, then failure is determined by checking if anything in the compiler output matches any of the specified regular expressions. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_TRY_COMPILE_TARGET_TYPE <# variable:CMAKE_TRY_COMPILE_TARGET_TYPE> Internally, the try_compile() <#command:try_compile> command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to EXECUTABLE (the default), the check compiles and links the test source code as an executable program. If set to STATIC_LIBRARY, the test source code is compiled but not linked. Examples In the following example, this module is used to check whether the provided Objective-C++ source code can be compiled and linked. Result of the check is stored in the internal cache variable HAVE_WORKING_CODE. include(CheckOBJCXXSourceCompiles) check_objcxx_source_compiles(" #include #import int main() { std::vector v; NSObject *foo; return 0; } " HAVE_WORKING_CODE) See Also o The CheckSourceCompiles <#module:CheckSourceCompiles> module for a more general command to check whether source can be built. o The CheckSourceRuns <#module:CheckSourceRuns> module to check whether source can be built and run. CheckOBJCXXSourceRuns Added in version 3.16. This module provides a command to check whether an Objective-C++ source can be built and run. Load this module in a CMake project with: include(CheckOBJCXXSourceRuns) Commands This module provides the following command: check_objcxx_source_runs Checks once whether the given Objective-C++ source code compiles and links into an executable that can subsequently be run: check_objcxx_source_runs( ) The Objective-C++ source supplied in must contain at least a main() function. The result of the check is stored in the internal cache variable specified by . If the code builds and runs with exit code 0, success is indicated by a boolean true value. Failure to build or run is indicated by a boolean false value, such as an empty string or an error message. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples In the following example, this module is used to check whether the provided Objective-C++ source code builds and runs. Result of the check is stored in an internal cache variable HAVE_WORKING_CODE. include(CheckOBJCXXSourceRuns) check_objcxx_source_runs(" #include #import int main() { std::vector v; NSObject *foo; return 0; } " HAVE_WORKING_CODE) See Also o The CheckSourceRuns <#module:CheckSourceRuns> module for a more general command syntax. o The CheckSourceCompiles <#module:CheckSourceCompiles> module to check whether a source code can be built. CheckPIESupported Added in version 3.14. This module provides a command to check whether the linker supports Position Independent Code (PIE) or No Position Independent Code (NO_PIE) for executables. Load this module in a CMake project with: include(CheckPIESupported) When setting the POSITION_INDEPENDENT_CODE <# prop_tgt:POSITION_INDEPENDENT_CODE> target property, PIC-related compile and link options are added when building library objects, and PIE-related compile options are added when building objects of executable targets, regardless of this module. Use this module to ensure that the POSITION_INDEPENDENT_CODE target property for executables is also honored at link time. Commands This module provides the following command: check_pie_supported Checks for PIE/NO_PIE support and prepares all executables to have link time PIE options enabled: check_pie_supported([OUTPUT_VARIABLE ] [LANGUAGES ...]) Options are: OUTPUT_VARIABLE Set variable with details about any error. If the check is bypassed because it uses cached results from a previous call, the output will be empty even if errors were present in the previous call. LANGUAGES ... Check the linkers used for each of the specified languages. If this option is not provided, the command checks all enabled languages. C, CXX, Fortran are supported. Added in version 3.23: OBJC, OBJCXX, CUDA, and HIP are supported. Note: To use check_pie_supported(), policy CMP0083 <# policy:CMP0083> must be set to NEW; otherwise, a fatal error will occur. Variables For each language checked, the check_pie_supported() command defines two boolean cache variables: CMAKE__LINK_PIE_SUPPORTED Set to true if PIE is supported by the linker and false otherwise. CMAKE__LINK_NO_PIE_SUPPORTED Set to true if NO_PIE is supported by the linker and false otherwise. Examples To enable PIE on an executable target at link time as well, include this module and call check_pie_supported() before setting the POSITION_INDEPENDENT_CODE target property. This will determine whether the linker for each checked language supports PIE-related link options. For example: add_executable(foo ...) include(CheckPIESupported) check_pie_supported() set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) Since not all linkers require or support PIE-related link options (for example, MSVC), retrieving any error messages might be useful for logging purposes: add_executable(foo ...) message(CHECK_START "Checking for C linker PIE support") include(CheckPIESupported) check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C) set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) if(CMAKE_C_LINK_PIE_SUPPORTED) message(CHECK_PASS "yes") else() message(CHECK_FAIL "no") message(VERBOSE "PIE is not supported at link time:\n${output}" "PIE link options will not be passed to linker.") endif() Setting the POSITION_INDEPENDENT_CODE target property on an executable without this module will set PIE-related compile options but not PIE-related link options, which might not be sufficient in certain cases: add_executable(foo ...) set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) CheckPrototypeDefinition This module provides a command to check if a C function has the expected prototype. Load this module in a CMake project with: include(CheckPrototypeDefinition) Commands This module provides the following command: check_prototype_definition Checks if a C function has the expected prototype: check_prototype_definition( ) The name of the function whose prototype is being checked. The expected prototype of the function, provided as a string. The return value of the function. This will be used as a return value in the function definition body of the generated test program to verify that the function's return type matches the expected type. A semicolon-separated list <#cmake-language-lists> of header file names required for checking the function prototype. The name of the variable to store the check result. This variable will be created as an internal cache variable. This command generates a test program and verifies that it builds without errors. The generated test program includes specified , defines a function with given literal and value and then uses the specified . The simplified test program can be illustrated as: #include // ... { return ; } int main(...) { ...()... } Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples Checking if the getpwent_r() function on Solaris/illumos systems has the expected prototype: include(CheckPrototypeDefinition) check_prototype_definition( getpwent_r "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)" "NULL" "unistd.h;pwd.h" HAVE_SOLARIS_GETPWENT_R ) CheckSourceCompiles Added in version 3.19. This module provides a command that checks whether a source code can be built for a given language. Load this module in a CMake project with: include(CheckSourceCompiles) Commands This module provides the following command: check_source_compiles Checks once whether the given source code can be built for the given language: check_source_compiles( [FAIL_REGEX ...] [SRC_EXT ] ) This command checks once that the source supplied in can be compiled (and linked into an executable) for code language . The result of the check is stored in the internal cache variable specified by . The arguments are: Language of the source code to check. Supported languages are: C, CXX, CUDA, Fortran, HIP, ISPC, OBJC, OBJCXX, and Swift. Added in version 3.21: Support for HIP language. Added in version 3.26: Support for Swift language. The source code to check. This must be an entire program, as written in a file containing the body block. All symbols used in the source code are expected to be declared as usual in their corresponding headers. Variable name of an internal cache variable to store the result of the check, with boolean true for success and boolean false for failure. FAIL_REGEX ... If one or more regular expression patterns are provided, then failure is determined by checking if anything in the compiler output matches any of the specified regular expressions. SRC_EXT By default, the internal test source file used for the check will be given a file extension that matches the requested language (e.g., .c for C, .cxx for C++, .F90 for Fortran, etc.). This option can be used to override this with the . instead. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_TRY_COMPILE_TARGET_TYPE <# variable:CMAKE_TRY_COMPILE_TARGET_TYPE> Internally, the try_compile() <#command:try_compile> command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to EXECUTABLE (the default), the check compiles and links the test source code as an executable program. If set to STATIC_LIBRARY, the test source code is compiled but not linked. Examples Example: Basic Usage The following example demonstrates how to check whether the C++ compiler supports a specific language feature using this module. In this case, the check verifies if the compiler supports C++11 lambda expressions. The result is stored in the internal cache variable HAVE_CXX11_LAMBDAS: include(CheckSourceCompiles) check_source_compiles(CXX " int main() { auto lambda = []() { return 42; }; return lambda(); } " HAVE_CXX11_LAMBDAS) Example: Checking Code With Bracket Argument The following example shows how to check whether the C compiler supports the noreturn attribute. Code is supplied using the Bracket Argument <#bracket-argument> for easier embedded quotes handling: include(CheckSourceCompiles) check_source_compiles(C [[ #if !__has_c_attribute(noreturn) # error "No noreturn attribute" #endif int main(void) { return 0; } ]] HAVE_NORETURN) Example: Performing a Check Without Linking In the following example, this module is used to perform a compile-only check of Fortran source code, whether the compiler supports the pure procedure attribute: include(CheckSourceCompiles) block() set(CMAKE_TRY_COMPILE_TARGET_TYPE "STATIC_LIBRARY") check_source_compiles( Fortran "pure subroutine foo() end subroutine" HAVE_PURE ) endblock() Example: Isolated Check In the following example, this module is used in combination with the CMakePushCheckState <#module:CMakePushCheckState> module to modify required libraries when checking whether the PostgreSQL PGVerbosity enum contains PQERRORS_SQLSTATE (available as of PostgreSQL version 12): include(CheckSourceCompiles) include(CMakePushCheckState) find_package(PostgreSQL) if(TARGET PostgreSQL::PostgreSQL) cmake_push_check_state(RESET) set(CMAKE_REQUIRED_LIBRARIES PostgreSQL::PostgreSQL) check_source_compiles(C " #include int main(void) { PGVerbosity e = PQERRORS_SQLSTATE; (void)e; return 0; } " HAVE_PQERRORS_SQLSTATE) cmake_pop_check_state() endif() See Also o The CheckSourceRuns <#module:CheckSourceRuns> module to check whether the source code can be built and also run. CheckSourceRuns Added in version 3.19. This module provides a command to check whether a source code can be built and run. Load this module in a CMake project with: include(CheckSourceRuns) Commands This module provides the following command: check_source_runs Checks once whether the given source code compiles and links into an executable that can subsequently be run: check_source_runs( [SRC_EXT ]) This command checks once that the source code supplied in can be built, linked as an executable, and then run. The result of the check is stored in the internal cache variable specified by . The arguments are: The programming language of the source to check. Supported languages are: C, CXX, CUDA, Fortran, HIP, OBJC, and OBJCXX. Added in version 3.21: Support for HIP language. The source code to be tested. It must contain a valid source program. For example, it must contain at least a main() function (in C/C++), or a program unit (in Fortran). Name of the internal cache variable with the result of the check. If the code builds and runs with exit code 0, success is indicated by a boolean true value. Failure to build or run is indicated by a boolean false value, such as an empty string or an error message. SRC_EXT By default, the internal test source file used for the check will be given a file extension that matches the requested language (e.g., .c for C, .cxx for C++, .F90 for Fortran, etc.). This option can be used to override this with the . instead. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples Example: Basic Usage The following example demonstrates how to use this module to check whether the C source code is supported and operational at runtime. The result of the check is stored in the internal cache variable HAVE_NORETURN. include(CheckSourceRuns) check_source_runs(C " #include #include noreturn void f(){ exit(0); } int main(void) { f(); return 1; } " HAVE_NORETURN) Example: Checking Fortran Code Checking if Fortran source code runs successfully: include(CheckSourceRuns) check_source_runs(Fortran " program test real :: x[*] call co_sum(x) end program " HAVE_COARRAY) Example: Checking C++ Code With Bracket Argument The following example demonstrates how to check whether the C++ standard library is functional and std::vector works at runtime. If the source compiles, links, and runs successfully, internal cache variable HAVE_WORKING_STD_VECTOR will be set to boolean true value. Code is supplied using Bracket Argument <#bracket-argument> for easier embedded quotes handling: include(CheckSourceRuns) check_source_runs(CXX [[ #include #include int main() { std::vector v = {1, 2, 3}; if (v.size() != 3) return 1; std::cout << "Vector works correctly." << std::endl; return 0; } ]] HAVE_WORKING_STD_VECTOR) Example: Isolated Check In the following example, this module is used in combination with the CMakePushCheckState <#module:CMakePushCheckState> module to modify required compile definitions and libraries when checking whether the C function sched_getcpu() is supported and operational at runtime. For example, on some systems, the sched_getcpu() function may be available at compile time but not actually implemented by the kernel. In such cases, it returns -1 and sets errno to ENOSYS. This check verifies that sched_getcpu() runs successfully and stores a boolean result in the internal cache variable HAVE_SCHED_GETCPU. include(CheckSourceRuns) include(CMakePushCheckState) cmake_push_check_state(RESET) set(CMAKE_REQUIRED_DEFINITIONS -D_GNU_SOURCE) if(CMAKE_SYSTEM_NAME STREQUAL "Haiku") set(CMAKE_REQUIRED_LIBRARIES gnu) endif() check_source_runs(C " #include int main(void) { if (sched_getcpu() == -1) { return 1; } return 0; } " HAVE_SCHED_GETCPU) cmake_pop_check_state() See Also o The CheckSourceCompiles <#module:CheckSourceCompiles> module to check whether a source code can be built. CheckStructHasMember This module provides a command to check whether a struct or class has a specified member variable. Load this module in a CMake project with: include(CheckStructHasMember) Commands This module provides the following command: check_struct_has_member Checks once if the given struct or class has the specified member variable: check_struct_has_member( [LANGUAGE ] ) This command checks once whether the struct or class contains the specified after including the given header(s) where the prototype should be declared. Multiple header files can be specified in one argument as a string using a semicolon-separated list <#cmake-language-lists>. The result is stored in an internal cache variable . The options are: LANGUAGE Use the compiler to perform the check. Acceptable values are C and CXX. If not specified, it defaults to C. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples Example: Checking C Struct Member In the following example, this module checks if the C struct timeval has a member variable tv_sec after including the header. The result of the check is stored in the internal cache variable HAVE_TIMEVAL_TV_SEC. include(CheckStructHasMember) check_struct_has_member( "struct timeval" tv_sec sys/select.h HAVE_TIMEVAL_TV_SEC ) Example: Checking C++ Struct Member In the following example, this module checks if the C++ struct std::tm has a member variable tm_gmtoff after including the header. The result of the check is stored in the internal cache variable HAVE_TM_GMTOFF. include(CheckStructHasMember) check_struct_has_member( std::tm tm_gmtoff ctime HAVE_TM_GMTOFF LANGUAGE CXX ) Example: Isolated Check With Compile Definitions In the following example, the check is performed with temporarily modified compile definitions using the CMakePushCheckState <# module:CMakePushCheckState> module: include(CheckStructHasMember) include(CMakePushCheckState) cmake_push_check_state(RESET) set(CMAKE_REQUIRED_DEFINITIONS -D_GNU_SOURCE) check_struct_has_member( "struct utsname" domainname sys/utsname.h HAVE_UTSNAME_DOMAINNAME ) cmake_pop_check_state() CheckSymbolExists This module provides a command to check whether a C symbol exists. Load this module in a CMake project with: include(CheckSymbolExists) Commands This module provides the following command: check_symbol_exists Checks once whether a symbol exists as a function, variable, or preprocessor macro in C: check_symbol_exists( ) This command checks whether the is available after including the specified header file(s) , and stores the result in the internal cache variable . Multiple header files can be specified in one argument as a string using a semicolon-separated list <#cmake-language-lists>. If the header files define the symbol as a macro, it is considered available and assumed to work. If the symbol is declared as a function or variable, the check also ensures that it links successfully (i.e., the symbol must exist in a linked library or object file). Compiler intrinsics may not be detected, as they are not always linkable or explicitly declared in headers. Symbols that are types, enum values, or compiler intrinsics are not recognized. For those, consider using the CheckTypeSize <# module:CheckTypeSize> or CheckSourceCompiles <# module:CheckSourceCompiles> module instead. This command is intended to check symbols as they appear in C. For C++ symbols, use the CheckCXXSymbolExists <# module:CheckCXXSymbolExists> module instead. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples The following example demonstrates how to check for the presence of a preprocessor macro SEEK_SET and the C function fopen() from the header using this module: include(CheckSymbolExists) # Check for macro SEEK_SET check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET) # Check for function fopen check_symbol_exists(fopen "stdio.h" HAVE_FOPEN) See Also o The CheckCXXSymbolExists <#module:CheckCXXSymbolExists> module to check whether a C++ symbol exists. CheckTypeSize This module provides a command to check the size of a C/C++ type or expression. Load this module in a CMake project with: include(CheckTypeSize) Commands This module provides the following command: check_type_size Checks once whether the C/C++ type or expression exists and determines its size: check_type_size( [RESULT_VARIABLE ] [BUILTIN_TYPES_ONLY] [LANGUAGE ] ) The arguments are: The type or expression being checked. The name of the internal cache variable for storing the size of the type or expression . This name is also used as a prefix as explained below. RESULT_VARIABLE Added in version 4.2. The name of the internal cache variable that holds a boolean value indicating whether the type or expression exists. If not given, the command will by default define an internal cache variable named HAVE_ instead. BUILTIN_TYPES_ONLY If given, only compiler-builtin types will be supported in the check. If not given, the command checks for common headers , , and , and saves results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and HAVE_STDDEF_H internal cache variables. For C++ std:: types, and are also checked with HAVE_CSTDINT and HAVE_CSTDDEF defined respectively. The command automatically includes the available headers in the type size check, thus supporting checks of types defined in the headers. LANGUAGE Uses the compiler to perform the check. Acceptable values are C and CXX. If not specified, it defaults to C. Result Variables Results are reported in the following variables: Internal cache variable that holds one of the following values: If the type or expression exists, it will have a non-zero size in bytes. 0 When the type has an architecture-dependent size; This may occur when CMAKE_OSX_ARCHITECTURES <# variable:CMAKE_OSX_ARCHITECTURES> has multiple architectures. In this case also the _KEYS variable is defined and the _CODE variable contains preprocessor tests mapping as explained below. "" (empty string) When the type or expression does not exist. HAVE_ Internal cache variable that holds a boolean value indicating whether the type or expression exists. This variable is defined when the RESULT_VARIABLE argument is not used. Added in version 4.2. Internal cache variable defined when the RESULT_VARIABLE argument is used. It holds a boolean value indicating whether the type or expression exists (same value as HAVE_). In this case, the HAVE_ variable is not defined. _CODE CMake variable that holds preprocessor code to define the macro to the size of the type, or to leave the macro undefined if the type does not exist. When the type has an architecture-dependent size ( value is 0) this variable contains preprocessor tests mapping from each architecture macro to the corresponding type size. _KEYS CMake variable that is defined only when the type has an architecture-dependent size ( value is 0) and contains a list of architecture macros. The value for each key is stored in - variables. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_EXTRA_INCLUDE_FILES A semicolon-separated list <#cmake-language-lists> of extra header files to include when performing the check. Examples Consider the code: include(CheckTypeSize) # Check for size of long. check_type_size(long SIZEOF_LONG) message("HAVE_SIZEOF_LONG: ${HAVE_SIZEOF_LONG}") message("SIZEOF_LONG: ${SIZEOF_LONG}") message("SIZEOF_LONG_CODE: ${SIZEOF_LONG_CODE}") On a 64-bit architecture, the output may look something like this: HAVE_SIZEOF_LONG: TRUE SIZEOF_LONG: 8 SIZEOF_LONG_CODE: #define SIZEOF_LONG 8 On Apple platforms, when CMAKE_OSX_ARCHITECTURES <# variable:CMAKE_OSX_ARCHITECTURES> has multiple architectures, types may have architecture-dependent sizes. For example, with the code: include(CheckTypeSize) check_type_size(long SIZEOF_LONG) message("HAVE_SIZEOF_LONG: ${HAVE_SIZEOF_LONG}") message("SIZEOF_LONG: ${SIZEOF_LONG}") foreach(key IN LISTS SIZEOF_LONG_KEYS) message("key: ${key}") message("value: ${SIZEOF_LONG-${key}}") endforeach() message("SIZEOF_LONG_CODE:\n${SIZEOF_LONG_CODE}") the result may be: HAVE_SIZEOF_LONG: TRUE SIZEOF_LONG: 0 key: __i386 value: 4 key: __x86_64 value: 8 SIZEOF_LONG_CODE: #if defined(__i386) # define SIZEOF_LONG 4 #elif defined(__x86_64) # define SIZEOF_LONG 8 #else # error SIZEOF_LONG unknown #endif Example: Configuration Header The next example demonstrates how the result variables can be used in a configuration header: include(CheckTypeSize) check_type_size(long SIZEOF_LONG) configure_file(config.h.in config.h @ONLY) config.h.in /* Define whether the type 'long' exists. */ #cmakedefine HAVE_SIZEOF_LONG /* The size of 'long', as computed by sizeof. */ @SIZEOF_LONG_CODE@ Example: Checking Complex Expressions Despite the name of this module, it may also be used to determine the size of more complex expressions. For example, to check the size of a struct member: include(CheckTypeSize) check_type_size("((struct something*)0)->member" SIZEOF_MEMBER) Example: Isolated Check In the following example, the check is performed with temporarily modified additional headers using the CMAKE_EXTRA_INCLUDE_FILES variable and CMakePushCheckState <#module:CMakePushCheckState> module. The result of the check is stored in HAVE_SIZEOF_UNION_SEMUN, and size is stored in SIZEOF_UNION_SEMUN internal cache variables. include(CheckTypeSize) include(CMakePushCheckState) cmake_push_check_state(RESET) set(CMAKE_EXTRA_INCLUDE_FILES sys/types.h sys/ipc.h sys/sem.h) check_type_size("union semun" SIZEOF_UNION_SEMUN) cmake_pop_check_state() Example: Customizing Result Variable Since CMake 4.2, the HAVE_ variable name can be customized using the RESULT_VARIABLE argument. In the following example, this module is used to check whether the struct flock exists, and the result is stored in the MyProj_HAVE_STRUCT_FLOCK internal cache variable: cmake_minimum_required(VERSION 4.2) # ... include(CheckTypeSize) include(CMakePushCheckState) cmake_push_check_state(RESET) set(CMAKE_EXTRA_INCLUDE_FILES "fcntl.h") check_type_size( "struct flock" MyProj_SIZEOF_STRUCT_FLOCK RESULT_VARIABLE MyProj_HAVE_STRUCT_FLOCK ) cmake_pop_check_state() CheckVariableExists This module provides a command to check whether a C variable exists. Load this module in a CMake project with: include(CheckVariableExists) Commands This module provides the following command: check_variable_exists Checks once if a C variable exists: check_variable_exists( ) This command attempts to compile and link a test C program that references the specified C variable . A boolean result of whether the check was successful is stored in an internal cache variable . Note: Prefer using CheckSymbolExists <#module:CheckSymbolExists> or CheckSourceCompiles <#module:CheckSourceCompiles> instead of this command for more robust detection. This command performs a link-only check and doesn't detect whether a variable is also declared in system or library headers. Neither can it detect variables that might be defined as preprocessor macros. Variables Affecting the Check The following variables may be set before calling this command to modify the way the check is run: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake- language-lists> will not work. The contents of CMAKE__FLAGS <#variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. Examples Example: Basic Usage In the following example, a check is performed whether the linker sees the C variable tzname and stores the check result in the PROJECT_HAVE_TZNAME internal cache variable: include(CheckVariableExists) check_variable_exists(tzname PROJECT_HAVE_TZNAME) Example: Isolated Check With Linked Libraries In the following example, this module is used in combination with the CMakePushCheckState <#module:CMakePushCheckState> module to link additional required library using the CMAKE_REQUIRED_LIBRARIES variable. For example, in a find module, to check whether the Net-SNMP library has the usmHMAC192SHA256AuthProtocol array: include(CheckVariableExists) include(CMakePushCheckState) find_library(SNMP_LIBRARY NAMES netsnmp) if(SNMP_LIBRARY) cmake_push_check_state(RESET) set(CMAKE_REQUIRED_LIBRARIES ${SNMP_LIBRARY}) check_variable_exists(usmHMAC192SHA256AuthProtocol SNMP_HAVE_SHA256) cmake_pop_check_state() endif() See Also o The CheckSymbolExists <#module:CheckSymbolExists> module to check whether a C symbol exists. CMakeAddFortranSubdirectory This module provides a command to add a Fortran project located in a subdirectory. Load this module in a CMake project with: include(CMakeAddFortranSubdirectory) Commands This module provides the following command: cmake_add_fortran_subdirectory Adds a Fortran-only subproject from subdirectory to the current project: cmake_add_fortran_subdirectory( PROJECT ARCHIVE_DIR RUNTIME_DIR LIBRARIES ... LINK_LIBRARIES [LINK_LIBS ...]... [CMAKE_COMMAND_LINE ...] NO_EXTERNAL_INSTALL ) This command checks whether the current compiler supports Fortran or attempts to locate a Fortran compiler. If a compatible Fortran compiler is found, the Fortran project located in is added as a subdirectory to the current project. If no Fortran compiler is found and the compiler is MSVC, it searches for the MinGW gfortran compiler. In this case, the Fortran project is built as an external project using MinGW tools, and Fortran-related imported targets are created. This setup works only if the Fortran code is built as a shared DLL library, so the BUILD_SHARED_LIBS <#variable:BUILD_SHARED_LIBS> variable is enabled in the external project. Additionally, the CMAKE_GNUtoMS <#variable:CMAKE_GNUtoMS> variable is set to ON to ensure that Microsoft-compatible .lib files are created. The options are: PROJECT The name of the Fortran project as defined in the top-level CMakeLists.txt located in . ARCHIVE_DIR Directory where the project places .lib archive files. A relative path is interpreted as relative to CMAKE_CURRENT_BINARY_DIR <# variable:CMAKE_CURRENT_BINARY_DIR>. RUNTIME_DIR Directory where the project places .dll runtime files. A relative path is interpreted as relative to CMAKE_CURRENT_BINARY_DIR <# variable:CMAKE_CURRENT_BINARY_DIR>. LIBRARIES Names of library targets to create or import into the current project. LINK_LIBRARIES Specifies link interface libraries for LIBRARIES. This option expects a list of LINK_LIBS ... items, where: o LINK_LIBS marks the start of a new pair o is a library target. o ... represents one or more dependencies required by . CMAKE_COMMAND_LINE Additional command-line flags passed to cmake(1) <# manual:cmake(1)> command when configuring the Fortran subproject. NO_EXTERNAL_INSTALL Prevents installation of the external project. Note: The NO_EXTERNAL_INSTALL option is required for forward compatibility with a future version that supports installation of the external project binaries during make install. Examples Adding a Fortran subdirectory to a project can be done by including this module and calling the cmake_add_fortran_subdirectory() command. In the following example, a Fortran project provides the hello library and its dependent world library: include(CMakeAddFortranSubdirectory) cmake_add_fortran_subdirectory( fortran-subdir PROJECT FortranHelloWorld ARCHIVE_DIR lib RUNTIME_DIR bin LIBRARIES hello world LINK_LIBRARIES LINK_LIBS hello world # hello library depends on the world library NO_EXTERNAL_INSTALL ) # The Fortran target can be then linked to the main project target. add_executable(main main.c) target_link_libraries(main PRIVATE hello) See Also There are multiple ways to integrate Fortran libraries. Alternative approaches include: o The add_subdirectory() <#command:add_subdirectory> command to add the subdirectory directly to the build. o The export() <#command:export> command can be used in the subproject to provide Imported Targets <#imported-targets> or similar for integration with other projects. o The FetchContent <#module:FetchContent> or ExternalProject <# module:ExternalProject> modules when working with external dependencies. CMakeBackwardCompatibilityCXX This module defines several backward compatibility cache variables for the CXX language to support early C++ (pre-C++98, ANSI C++). Load this module in a CMake project with: include(CMakeBackwardCompatibilityCXX) The following modules are included by this module: o TestForANSIForScope <#module:TestForANSIForScope> o TestForANSIStreamHeaders <#module:TestForANSIStreamHeaders> o TestForSSTREAM <#module:TestForSSTREAM> o TestForSTDNamespace <#module:TestForSTDNamespace> Additionally, the following cache variable may be defined: CMAKE_ANSI_CXXFLAGS A space-separated string of compiler options for enabling ANSI C++ mode, if available. Note: This module is intended for C++ code written before C++ 98. As of the C++ 98 standard, these issues have been formally addressed, making such checks obsolete. Examples Including this module provides backward compatibility cache variables, which can be used in C++. For example: CMakeLists.txt include(CMakeBackwardCompatibilityCXX) file( CONFIGURE OUTPUT config.h CONTENT [[ #cmakedefine CMAKE_NO_ANSI_FOR_SCOPE #cmakedefine CMAKE_NO_ANSI_STRING_STREAM #cmakedefine CMAKE_NO_ANSI_STREAM_HEADERS #cmakedefine CMAKE_NO_STD_NAMESPACE ]] ) CMakeDependentOption This module provides a command to define boolean options whose availability and default values depend on specified conditions or other options. This helps maintain a clean configuration interface by only displaying options that are relevant to the current settings. Load this module in CMake with: include(CMakeDependentOption) Commands This module provides the following command: cmake_dependent_option Provides a boolean option that depends on a set of conditions: cmake_dependent_option( ) This command creates a boolean and makes it available to the user in the GUI (such as cmake-gui(1) <#manual:cmake- gui(1)> or ccmake(1) <#manual:ccmake(1)>), if a set of conditions evaluates to boolean true. The arguments are: The name of a variable that stores the option value. A brief description of the option. This string is typically a short line of text and is displayed in the GUI. Boolean value for the , when evaluates to boolean true. Specifies the conditions that determine whether is set and visible in the GUI. o If evaluates to boolean false, option is hidden from the user in the GUI, and a local variable is set to . o If evaluates to boolean true, a boolean cache variable named is created with default , and option is shown in the GUI, allowing the user to enable or disable it. o If later evaluates to boolean false (on consecutive configuration run), option is hidden from the user in the GUI and the type is changed to an internal cache variable. In that case a local variable of the same name is set to . o If becomes true again in consecutive configuration runs, the user's previously set value is preserved. The argument can be: o A single condition (such as a variable name). o A semicolon-separated list <#cmake-language-lists> of multiple conditions. o Added in version 3.22: A full Condition Syntax <# condition-syntax> as used in an if() clause. See policy CMP0127 <#policy:CMP0127>. This enables using entire condition syntax (such as grouping conditions with parens and similar). The value assigned to a local variable named , when evaluates to boolean false. In CMake project mode, boolean cache variables are created as explained above. In CMake script mode, boolean variables are set instead. Examples Example: Basic Usage Using this module in a project to conditionally set an option: CMakeLists.txt include(CMakeDependentOption) cmake_dependent_option(USE_SSL_GNUTLS "Use GnuTLS for SSL" ON USE_SSL OFF) Example: Enabling/Disabling Dependent Option Extending the previous example, this demonstrates how the module allows user-configurable options based on a condition during the configuration phase: CMakeLists.txt include(CMakeDependentOption) option(USE_SSL "Enable SSL in the project" OFF) cmake_dependent_option(USE_SSL_GNUTLS "Use GnuTLS for SSL" ON USE_SSL OFF) message(STATUS "USE_SSL: ${USE_SSL}") message(STATUS "USE_SSL_GNUTLS: ${USE_SSL_GNUTLS}") On the first configuration run, a boolean cache variable USE_SSL is set to OFF, and a local variable USE_SSL_GNUTLS is set to OFF: $ cmake -B build-dir -- USE_SSL: OFF -- USE_SSL_GNUTLS: OFF Running CMake with USE_SSL=ON sets both USE_SSL and USE_SSL_GNUTLS boolean cache variables to ON: $ cmake -B build-dir -D USE_SSL=ON -- USE_SSL: ON -- USE_SSL_GNUTLS: ON On a subsequent configuration run with USE_SSL=OFF, USE_SSL_GNUTLS follows suit. However, its value is preserved in the internal cache while being overridden locally: $ cmake -B build-dir -D USE_SSL=OFF -- USE_SSL: OFF -- USE_SSL_GNUTLS: OFF Example: Semicolon-separated List of Conditions The argument can also be a semicolon-separated list of conditions. In the following example, if the variable USE_BAR is ON and variable USE_ZOT is OFF, the option USE_FOO is available and defaults to ON. Otherwise, USE_FOO is set to OFF and hidden from the user. If the values of USE_BAR or USE_ZOT change in the future configuration runs, the previous value of USE_FOO is preserved so that when it becomes available again, it retains its last set value. CMakeLists.txt include(CMakeDependentOption) cmake_dependent_option(USE_FOO "Use Foo" ON "USE_BAR;NOT USE_ZOT" OFF) Example: Full Condition Syntax As of CMake 3.22, cmake_dependent_option() supports full condition syntax. In fhe following example, if the condition evaluates to true, the option USE_FOO is available and set to ON. Otherwise, it is set to OFF and hidden in the GUI. The value of USE_FOO is preserved across configuration runs, similar to the previous example. CMakeLists.txt include(CMakeDependentOption) cmake_dependent_option(USE_FOO "Use Foo" ON "USE_A AND (USE_B OR USE_C)" OFF) Another example demonstrates how an option can be conditionally available based on the target system: CMakeLists.txt include(CMakeDependentOption) cmake_dependent_option( ENABLE_FOO "Enable feature Foo (this option is available when building for Windows)" ON [[CMAKE_SYSTEM_NAME STREQUAL "Windows"]] OFF ) See Also o The option() <#command:option> command to provide a boolean option that the user can optionally select. CMakeFindDependencyMacro This module provides a command implemented as a macro that finds dependency for a package. Load this module in a CMake package configuration file with: FooConfig.cmake or foo-config.cmake: include(CMakeFindDependencyMacro) Note: This module is designed to be used in a Package Configuration File <#config-file-packages> (Config.cmake). Commands This module provides the following command: find_dependency The find_dependency() macro wraps a find_package() <# command:find_package> call for a package dependency: find_dependency( [...]) It is designed to be used in a Package Configuration File <# config-file-packages> (Config.cmake). find_dependency forwards the correct parameters for QUIET and REQUIRED which were passed to the original find_package() <# command:find_package> call. Any additional arguments specified are forwarded to find_package() <#command:find_package>. If the dependency could not be found it sets an informative diagnostic message and calls return() <#command:return> to end processing of the calling package configuration file and return to the find_package() <#command:find_package> command that loaded it. Note: The call to return() <#command:return> makes this macro unsuitable to call from Find Modules <#find-modules>. Package Dependency Search Optimizations If find_dependency is called with arguments identical to a previous call in the same directory, perhaps due to diamond-shaped package dependencies, the underlying call to find_package() <# command:find_package> is optimized out. This optimization is important to support large package dependency graphs while avoiding a combinatorial explosion of repeated searches. However, the heuristic cannot account for ambient variables that affect package behavior, such as _USE_STATIC_LIBS, offered by some packages. Therefore package configuration files should avoid setting such variables before their calls to find_dependency. Changed in version 3.15: Previously, the underlying call to find_package() <#command:find_package> was always optimized out if the package had already been found. CMake 3.15 removed the optimization to support cases in which find_dependency call arguments request different components. Changed in version 3.26: The pre-3.15 optimization was restored, but with the above-described heuristic to account for varying find_dependency call arguments. CMakePackageConfigHelpers This module provides helper commands for creating config files <# libraries-providing-config-file-packages> that can be included by other projects to find and use a package. Load this module in a CMake project with: include(CMakePackageConfigHelpers) Generating a Package Configuration File configure_package_config_file Create a config file for a project: configure_package_config_file( INSTALL_DESTINATION [PATH_VARS ... ] [NO_SET_AND_CHECK_MACRO] [NO_CHECK_REQUIRED_COMPONENTS_MACRO] [INSTALL_PREFIX ] ) configure_package_config_file() should be used instead of the plain configure_file() <#command:configure_file> command when creating the Config.cmake or -config.cmake file for installing a project or library. It helps make the resulting package relocatable by avoiding hardcoded paths in the installed Config.cmake file. In a FooConfig.cmake file there may be code like this to make the install destinations known to the using project: set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" ) set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" ) set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" ) #...logic to determine installedPrefix from the own location... set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" ) All four options shown above are not sufficient The first three hardcode the absolute directory locations. The fourth case works only if the logic to determine the installedPrefix is correct, and if CONFIG_INSTALL_DIR contains a relative path, which in general cannot be guaranteed. This has the effect that the resulting FooConfig.cmake file would work poorly under Windows and macOS, where users are used to choosing the install location of a binary package at install time, independent from how CMAKE_INSTALL_PREFIX <# variable:CMAKE_INSTALL_PREFIX> was set at build/cmake time. Using configure_package_config_file() helps. If used correctly, it makes the resulting FooConfig.cmake file relocatable. Usage: 1. Write a FooConfig.cmake.in file as you are used to. 2. Insert a line at the top 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() <# command:configure_file> command, use configure_package_config_file(). The and arguments are the input and output file, the same way as in configure_file() <#command:configure_file>. The given to INSTALL_DESTINATION must be the destination where the FooConfig.cmake file will be installed to. This path can either be absolute, or relative to the INSTALL_PREFIX path. The variables to given as PATH_VARS are the variables which contain install destinations. For each of them, the macro will create a helper variable PACKAGE_. These helper variables must be used in the FooConfig.cmake.in file for setting the installed location. They are calculated by configure_package_config_file() so that they are always relative to the installed location of the package. This works both for relative and also for absolute locations. For absolute locations, it works only if the absolute location is a subdirectory of INSTALL_PREFIX. Added in version 3.30: The variable PACKAGE_PREFIX_DIR will always be defined after the @PACKAGE_INIT@ line. It will hold the value of the base install location. In general, variables defined via the PATH_VARS mechanism should be used instead, but PACKAGE_PREFIX_DIR can be used for those cases not easily handled by PATH_VARS, such as for files installed directly to the base install location rather than a subdirectory of it. Note: When consumers of the generated file use CMake 3.29 or older, the value of PACKAGE_PREFIX_DIR can be changed by a call to find_dependency() <#command:find_dependency> or find_package() <# command:find_package>. If a project relies on PACKAGE_PREFIX_DIR, it is the project's responsibility to ensure that the value of PACKAGE_PREFIX_DIR is preserved across any such calls, or any other calls which might include another file generated by configure_package_config_file(). Added in version 3.1: If the INSTALL_PREFIX argument is passed, this is used as the base path to calculate all the relative paths. The argument must be an absolute path. If this argument is not passed, the CMAKE_INSTALL_PREFIX <#variable:CMAKE_INSTALL_PREFIX> variable will be used instead. The default value is good when generating a FooConfig.cmake file to use your package from the install tree. When generating a FooConfig.cmake file to use your package from the build tree, this option should be used. By default, configure_package_config_file() also generates two helper macros, set_and_check() and check_required_components(), into the FooConfig.cmake file. set_and_check() should be used instead of the normal set() <# command:set> command for setting directories and file locations. In addition to setting the variable, it also checks that the referenced file or directory actually exists and fails with a fatal error if it doesn't. This ensures that the generated FooConfig.cmake file does not contain wrong references. Add the NO_SET_AND_CHECK_MACRO option to prevent the generation of the set_and_check() macro in the FooConfig.cmake file. check_required_components() should be called at the end of the FooConfig.cmake file. This macro checks whether all requested, non-optional components have been found, and if this is not the case, it sets the Foo_FOUND variable to FALSE so that the package is considered to be not found. It does that by testing the Foo__FOUND variables for all requested required components. This macro should be called even if the package doesn't provide any components to make sure users are not specifying components erroneously. Add the NO_CHECK_REQUIRED_COMPONENTS_MACRO option to prevent the generation of the check_required_components() macro in the FooConfig.cmake file. See also Example Generating Package Files. Generating a Package Version File write_basic_package_version_file Create a version file for a project: write_basic_package_version_file( [VERSION ] COMPATIBILITY [ARCH_INDEPENDENT] ) Writes a file for use as a ConfigVersion.cmake file to . See the documentation of find_package() <# command:find_package> for details on such files. is the output filename, which should be in the build tree. is the version number of the project to be installed. If no VERSION is given, the PROJECT_VERSION <#variable:PROJECT_VERSION> variable is used. If this hasn't been set, it errors out. The COMPATIBILITY mode AnyNewerVersion means that the installed package version will be considered compatible if it is newer or exactly the same as the requested version. This mode should be used for packages which are fully backward compatible, also across major versions. If SameMajorVersion is used instead, then the behavior differs from AnyNewerVersion in that the major version number must be the same as requested, e.g. version 2.0 will not be considered compatible if 1.0 is requested. This mode should be used for packages which guarantee backward compatibility within the same major version. If SameMinorVersion is used, the behavior is the same as SameMajorVersion, but both major and minor version must be the same as requested, e.g version 0.2 will not be compatible if 0.1 is requested. If ExactVersion is used, then the package is only considered compatible if the requested version matches exactly its own version number (not considering the tweak version). For example, version 1.2.3 of a package is only considered compatible to requested version 1.2.3. This mode is for packages without compatibility guarantees. If your project has more elaborate version matching rules, you will need to write your own custom ConfigVersion.cmake file instead of using this macro. Added in version 3.11: The SameMinorVersion compatibility mode. Added in version 3.14: If ARCH_INDEPENDENT is given, the installed package version will be considered compatible even if it was built for a different architecture than the requested architecture. Otherwise, an architecture check will be performed, and the package will be considered compatible only if the architecture matches exactly. For example, if the package is built for a 32-bit architecture, the package is only considered compatible if it is used on a 32-bit architecture, unless ARCH_INDEPENDENT is given, in which case the package is considered compatible on any architecture. Note: ARCH_INDEPENDENT is intended for header-only libraries or similar packages with no binaries. Added in version 3.19: The version file generated by AnyNewerVersion, SameMajorVersion and SameMinorVersion arguments of COMPATIBILITY handle the version range, if one is specified (see find_package() <# command:find_package> command for the details). ExactVersion mode is incompatible with version ranges and will display an author warning if one is specified. Internally, this macro executes configure_file() <# command:configure_file> to create the resulting version file. Depending on the COMPATIBILITY, the corresponding BasicConfigVersion-.cmake.in file is used. Please note that these files are internal to CMake and you should not call configure_file() <#command:configure_file> on them yourself, but they can be used as a starting point to create more sophisticated custom ConfigVersion.cmake files. Generating an Apple Platform Selection File generate_apple_platform_selection_file Added in version 3.29. Create an Apple platform selection file: generate_apple_platform_selection_file( INSTALL_DESTINATION [INSTALL_PREFIX ] [MACOS_INCLUDE_FILE ] [IOS_INCLUDE_FILE ] [IOS_SIMULATOR_INCLUDE_FILE ] [IOS_CATALYST_INCLUDE_FILE ] [TVOS_INCLUDE_FILE ] [TVOS_SIMULATOR_INCLUDE_FILE ] [WATCHOS_INCLUDE_FILE ] [WATCHOS_SIMULATOR_INCLUDE_FILE ] [VISIONOS_INCLUDE_FILE ] [VISIONOS_SIMULATOR_INCLUDE_FILE ] [ERROR_VARIABLE ] ) Write a file that includes an Apple-platform-specific .cmake file, e.g., for use as Config.cmake. This can be used in conjunction with the XCFRAMEWORK_LOCATION argument of export(SETUP) <#setup> to export packages in a way that a project built for any Apple platform can use them. INSTALL_DESTINATION Path to which the generated file will be installed by the caller, e.g., via install(FILES) <#files>. The path may be either relative to the INSTALL_PREFIX or absolute. INSTALL_PREFIX Path prefix to which the package will be installed by the caller. The argument must be an absolute path. If this argument is not passed, the CMAKE_INSTALL_PREFIX <#variable:CMAKE_INSTALL_PREFIX> variable will be used instead. MACOS_INCLUDE_FILE File to include if the platform is macOS. IOS_INCLUDE_FILE File to include if the platform is iOS. IOS_SIMULATOR_INCLUDE_FILE File to include if the platform is iOS Simulator. IOS_CATALYST_INCLUDE_FILE Added in version 3.31. File to include if the platform is iOS Catalyst. TVOS_INCLUDE_FILE File to include if the platform is tvOS. TVOS_SIMULATOR_INCLUDE_FILE File to include if the platform is tvOS Simulator. WATCHOS_INCLUDE_FILE File to include if the platform is watchOS. WATCHOS_SIMULATOR_INCLUDE_FILE File to include if the platform is watchOS Simulator. VISIONOS_INCLUDE_FILE File to include if the platform is visionOS. VISIONOS_SIMULATOR_INCLUDE_FILE File to include if the platform is visionOS Simulator. ERROR_VARIABLE If the consuming project is built for an unsupported platform, set to an error message. The includer may use this information to pretend the package was not found. If this option is not given, the default behavior is to issue a fatal error. If any of the optional include files is not specified, and the consuming project is built for its corresponding platform, the generated file will consider the platform to be unsupported. The behavior is determined by the ERROR_VARIABLE option. Generating an Apple Architecture Selection File generate_apple_architecture_selection_file Added in version 3.29. Create an Apple architecture selection file: generate_apple_architecture_selection_file( INSTALL_DESTINATION [INSTALL_PREFIX ] [SINGLE_ARCHITECTURES ... SINGLE_ARCHITECTURE_INCLUDE_FILES ...] [UNIVERSAL_ARCHITECTURES ... UNIVERSAL_INCLUDE_FILE ] [ERROR_VARIABLE ] ) Write a file that includes an Apple-architecture-specific .cmake file based on CMAKE_OSX_ARCHITECTURES <# variable:CMAKE_OSX_ARCHITECTURES>, e.g., for inclusion from an Apple-specific Config.cmake file. INSTALL_DESTINATION Path to which the generated file will be installed by the caller, e.g., via install(FILES) <#files>. The path may be either relative to the INSTALL_PREFIX or absolute. INSTALL_PREFIX Path prefix to which the package will be installed by the caller. The argument must be an absolute path. If this argument is not passed, the CMAKE_INSTALL_PREFIX <#variable:CMAKE_INSTALL_PREFIX> variable will be used instead. SINGLE_ARCHITECTURES ... Architectures provided by entries of SINGLE_ARCHITECTURE_INCLUDE_FILES. SINGLE_ARCHITECTURE_INCLUDE_FILES ... Architecture-specific files. One of them will be loaded when CMAKE_OSX_ARCHITECTURES <# variable:CMAKE_OSX_ARCHITECTURES> contains a single architecture matching the corresponding entry of SINGLE_ARCHITECTURES. UNIVERSAL_ARCHITECTURES ... Architectures provided by the UNIVERSAL_INCLUDE_FILE. The list may include $(ARCHS_STANDARD) to support consumption using the Xcode <#generator:Xcode> generator, but the architectures should always be listed individually too. UNIVERSAL_INCLUDE_FILE A file to load when CMAKE_OSX_ARCHITECTURES <# variable:CMAKE_OSX_ARCHITECTURES> contains a (non-strict) subset of the UNIVERSAL_ARCHITECTURES and does not match any one of the SINGLE_ARCHITECTURES. ERROR_VARIABLE If the consuming project is built for an unsupported architecture, set to an error message. The includer may use this information to pretend the package was not found. If this option is not given, the default behavior is to issue a fatal error. Example Generating Package Files Example using both the configure_package_config_file() and write_basic_package_version_file() commands: CMakeLists.txt include(GNUInstallDirs) set(INCLUDE_INSTALL_DIR ${CMAKE_INSTALL_INCLUDEDIR}/Foo CACHE PATH "Location of header files" ) set(SYSCONFIG_INSTALL_DIR ${CMAKE_INSTALL_SYSCONFDIR}/foo CACHE PATH "Location of configuration files" ) #... include(CMakePackageConfigHelpers) configure_package_config_file(FooConfig.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Foo PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR) write_basic_package_version_file( ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake VERSION 1.2.3 COMPATIBILITY SameMajorVersion ) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Foo ) FooConfig.cmake.in set(FOO_VERSION x.y.z) ... @PACKAGE_INIT@ ... set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@") set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@") check_required_components(Foo) CMakePrintHelpers This module provides convenience commands, primarily intended for debugging, to print the values of properties and variables. Load this module in CMake with: include(CMakePrintHelpers) Commands This module provides the following commands: cmake_print_properties Prints the values of properties for the specified targets, source files, directories, tests, or cache entries: cmake_print_properties( ...] | SOURCES [...] | DIRECTORIES [...] | TESTS [...] | CACHE_ENTRIES [...] > PROPERTIES [...] ) Exactly one of the scope keywords must be specified. The scope keyword and its arguments must appear before the PROPERTIES keyword in the argument list. cmake_print_variables Prints each variable name followed by its value: cmake_print_variables([...]) Examples Printing the LOCATION and INTERFACE_INCLUDE_DIRECTORIES properties for both targets foo and bar: include(CMakePrintHelpers) cmake_print_properties( TARGETS foo bar PROPERTIES LOCATION INTERFACE_INCLUDE_DIRECTORIES ) Gives: -- Properties for TARGET foo: foo.LOCATION = "/usr/lib/libfoo.so" foo.INTERFACE_INCLUDE_DIRECTORIES = "/usr/include;/usr/include/foo" Properties for TARGET bar: bar.LOCATION = "/usr/lib/libbar.so" bar.INTERFACE_INCLUDE_DIRECTORIES = "/usr/include;/usr/include/bar" Printing given variables: include(CMakePrintHelpers) cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION NOT_EXISTS) Gives: -- CMAKE_C_COMPILER="/usr/bin/cc" ; CMAKE_MAJOR_VERSION="3" ; NOT_EXISTS="" CMakePrintSystemInformation This module can be used for diagnostics to print system information. Load this module in a CMake project with: include(CMakePrintSystemInformation) Examples For example, including this module in a project: CMakeLists.txt project(Example) # ... include(CMakePrintSystemInformation) prints various CMake variables: CMAKE_SYSTEM is Linux-6.11.0-17-generic Linux 6.11.0-17-generic x86_64 CMAKE_SYSTEM file is Platform/Linux CMAKE_C_COMPILER is /usr/bin/cc CMAKE_CXX_COMPILER is /usr/bin/c++ CMAKE_SHARED_LIBRARY_CREATE_C_FLAGS is -shared CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS is -shared ... CMakePushCheckState This module provides commands for managing the state of variables that influence how various CMake check commands (e.g., check_symbol_exists() <#command:check_symbol_exists>, etc.) are performed. Load this module in a CMake project with: include(CMakePushCheckState) This module provides the following commands, which are useful for scoped configuration, for example, in CMake modules or when performing checks in a controlled environment, ensuring that temporary modifications are isolated to the scope of the check and do not propagate into other parts of the build system: o cmake_push_check_state() o cmake_reset_check_state() o cmake_pop_check_state() Affected Variables The following CMake variables are saved, reset, and restored by this module's commands: CMAKE_REQUIRED_FLAGS A space-separated string of additional flags to pass to the compiler. A semicolon-separated list <#cmake-language-lists> will not work. The contents of CMAKE__FLAGS <# variable:CMAKE__FLAGS> and its associated configuration-specific CMAKE__FLAGS_ <# variable:CMAKE__FLAGS_> variables are automatically prepended to the compiler command before the contents of this variable. CMAKE_REQUIRED_DEFINITIONS A semicolon-separated list <#cmake-language-lists> of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically. CMAKE_REQUIRED_INCLUDES A semicolon-separated list <#cmake-language-lists> of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES <#prop_dir:INCLUDE_DIRECTORIES> directory property will be ignored. CMAKE_REQUIRED_LINK_OPTIONS Added in version 3.14. A semicolon-separated list <#cmake-language-lists> of options to add to the link command (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_LIBRARIES A semicolon-separated list <#cmake-language-lists> of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets <#imported-targets> (see try_compile() <#command:try_compile> for further details). CMAKE_REQUIRED_LINK_DIRECTORIES Added in version 3.31. A semicolon-separated list <#cmake-language-lists> of library search paths to pass to the linker (see try_compile() <# command:try_compile> for further details). CMAKE_REQUIRED_QUIET Added in version 3.1. If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. CMAKE_EXTRA_INCLUDE_FILES Added in version 3.6: Previously used already by the check_type_size() <#command:check_type_size> command; now also supported by this module. A semicolon-separated list <#cmake-language-lists> of extra header files to include when performing the check. Note: Other CMake variables, such as CMAKE__FLAGS <# variable:CMAKE__FLAGS>, propagate to all checks regardless of commands provided by this module, as those fundamental variables are designed to influence the global state of the build system. Commands cmake_push_check_state Pushes (saves) the current states of the above variables onto a stack: cmake_push_check_state([RESET]) Use this command to preserve the current configuration before making temporary modifications for specific checks. RESET When this option is specified, the command not only saves the current states of the listed variables but also resets them to empty, allowing them to be reconfigured from a clean state. cmake_reset_check_state Resets (clears) the contents of the variables listed above to empty states: cmake_reset_check_state() Use this command when performing multiple sequential checks that require entirely new configurations, ensuring no previous configuration unintentionally carries over. cmake_pop_check_state Restores the states of the variables listed above to their values at the time of the most recent cmake_push_check_state() call: cmake_pop_check_state() Use this command to revert temporary changes made during a check. To prevent unexpected behavior, pair each cmake_push_check_state() with a corresponding cmake_pop_check_state(). Examples Example: Isolated Check With Compile Definitions In the following example, a check for the C symbol memfd_create() is performed with an additional _GNU_SOURCE compile definition, without affecting global compile flags. The RESET option is used to ensure that any prior values of the check-related variables are explicitly cleared before the check. include(CMakePushCheckState) # Save and reset the current state cmake_push_check_state(RESET) # Perform check with specific compile definitions set(CMAKE_REQUIRED_DEFINITIONS -D_GNU_SOURCE) include(CheckSymbolExists) check_symbol_exists(memfd_create "sys/mman.h" HAVE_MEMFD_CREATE) # Restore the original state cmake_pop_check_state() Example: Nested Configuration Scopes In the following example, variable states are pushed onto the stack multiple times, allowing for sequential or nested checks. Each cmake_pop_check_state() restores the most recent pushed states. include(CMakePushCheckState) # Save and reset the current state cmake_push_check_state(RESET) # Perform the first check with additional libraries set(CMAKE_REQUIRED_LIBRARIES ${CMAKE_DL_LIBS}) include(CheckSymbolExists) check_symbol_exists(dlopen "dlfcn.h" HAVE_DLOPEN) # Save current state cmake_push_check_state() # Perform the second check with libraries and additional compile definitions set(CMAKE_REQUIRED_DEFINITIONS -D_GNU_SOURCE) check_symbol_exists(dladdr "dlfcn.h" HAVE_DLADDR) message(STATUS "${CMAKE_REQUIRED_DEFINITIONS}") # Output: -D_GNU_SOURCE # Restore the previous state cmake_pop_check_state() message(STATUS "${CMAKE_REQUIRED_DEFINITIONS}") # Output here is empty # Reset variables to prepare for the next check cmake_reset_check_state() # Perform the next check only with additional compile definitions set(CMAKE_REQUIRED_DEFINITIONS -D_GNU_SOURCE) check_symbol_exists(dl_iterate_phdr "link.h" HAVE_DL_ITERATE_PHDR) # Restore the original state cmake_pop_check_state() CMakeVerifyManifest This module is intended to be used in command-line mode using the cmake -P <#script-processing-mode> to verify that embedded manifests and side-by-side manifests for a project match. Load this module in a CMake script with: include(CMakeVerifyManifest) This module first recursively globs *.manifest files from the current source directory and creates a list of allowed versions. Next, the script globs all *.exe and *.dll files. Each .exe and .dll file is scanned for embedded manifests and the versions of CRT are checked to be in the list of allowed versions. Input Variables This module accepts the following variables: allow_versions Additional versions can be passed by setting the allow_versions variable from the invocation command. This enables using additional embedded manifest versions in a project, even if that version was not found in a .manifest file. Examples To use this module in the project, create a local command-line script (for example, in the project's subdirectory cmake/scripts) and include the module: cmake/scripts/verify-manifest.cmake include(CMakeVerifyManifest) Then run the local script in command-line and, for example, specify additional embedded manifest of 8.0.50608.0 to be used in a project: cmake -Dallow_versions=8.0.50608.0 -Pcmake/scripts/verify-manifest.cmake CPack This module configures generators for binary installers and source packages. Load this module in a CMake project with: include(CPack) Introduction The CPack module generates the configuration files CPackConfig.cmake and CPackSourceConfig.cmake. They are intended for use in a subsequent run of the cpack <#manual:cpack(1)> program where they steer the generation of installers or/and source packages. Depending on the CMake generator, the CPack module may also add two new build targets, package and package_source. See the packaging targets section below for details. The generated binary installers will contain all files that have been installed via CMake's install() <#command:install> command (and the deprecated commands install_files() <#command:install_files>, install_programs() <#command:install_programs>, and install_targets() <#command:install_targets>). Note that the DESTINATION option of the install() <#command:install> command must be a relative path; otherwise installed files are ignored by CPack. Certain kinds of binary installers can be configured such that users can select individual application components to install. See the CPackComponent <#module:CPackComponent> module for further details. Source packages (configured through CPackSourceConfig.cmake and generated by the CPack Archive Generator <#cpack_gen:CPack Archive Generator>) will contain all source files in the project directory except those specified in CPACK_SOURCE_IGNORE_FILES. CPack Generators The CPACK_GENERATOR variable has different meanings in different contexts. In a CMakeLists.txt file, CPACK_GENERATOR is a list of generators: and when cpack <#manual:cpack(1)> is run with no other arguments, it will iterate over that list and produce one package for each generator. In a CPACK_PROJECT_CONFIG_FILE, CPACK_GENERATOR is a string naming a single generator. If you need per-cpack-generator logic to control other cpack settings, then you need a CPACK_PROJECT_CONFIG_FILE. If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator basis. It only need contain overrides. Here's how it works: o cpack <#manual:cpack(1)> runs o it includes CPackConfig.cmake o it iterates over the generators given by the -G <#cmdoption-cpack-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. o foreach generator, it then o sets CPACK_GENERATOR to the one currently being iterated o includes the CPACK_PROJECT_CONFIG_FILE o produces the package for that generator This is the key: For each generator listed in CPACK_GENERATOR in CPackConfig.cmake, cpack will reset CPACK_GENERATOR internally to the one currently being used and then include the CPACK_PROJECT_CONFIG_FILE. For a list of available generators, see cpack-generators(7) <# manual:cpack-generators(7)>. Targets package and package_source If CMake is run with the Makefile, Ninja, or Xcode generator, then include(CPack) generates a target package. This makes it possible to build a binary installer from CMake, Make, or Ninja: Instead of cpack, one may call cmake --build . --target package or make package or ninja package. The VS generator creates an uppercase target PACKAGE. If CMake is run with the Makefile or Ninja generator, then include(CPack) also generates a target package_source. To build a source package, instead of cpack -G TGZ --config CPackSourceConfig.cmake one may call cmake --build . --target package_source, make package_source, or ninja package_source. Variables common to all CPack Generators Before including this CPack module in your CMakeLists.txt file, there are a variety of variables that can be set to customize the resulting installers. The most commonly-used variables are: 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 <#manual:cpack(1)> 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:project> command in the top level CMakeLists.txt file. If version details were given, the default value will be CMAKE_PROJECT_VERSION_MAJOR <# variable: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:project> command in the top level CMakeLists.txt file. If version details were given, the default value will be CMAKE_PROJECT_VERSION_MINOR <# variable: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:project> command in the top level CMakeLists.txt file. If version details were given, the default value will be CMAKE_PROJECT_VERSION_PATCH <# variable: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: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 <#variable:CMAKE_PROJECT_NAME>. CPACK_PACKAGE_HOMEPAGE_URL Project homepage URL. The default value is taken from the CMAKE_PROJECT_HOMEPAGE_URL <# variable:CMAKE_PROJECT_HOMEPAGE_URL> variable, which is set by the top level project() <#command:project> command, or else the default will be empty if no URL was provided to project() <# command: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 Added in version 3.7. One or multiple algorithms that will be used to generate additional files with the checksum of the package. The output file names will be: ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM} Supported algorithms are those listed by the string() <# supported-hash-algorithms> command. Changed in version 4.2: The variable accepts a list of algorithms. 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 use UTF-8 characters, the file needs to be encoded in UTF-8 BOM. 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: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__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_ (e.g. CPACK_BINARY_NSIS) allowing the user to enable/disable individual generators. If the -G <# cmdoption-cpack-G> option is given on the cpack <# manual:cpack(1)> command line, it will override this variable and any CPACK_BINARY_ 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, Inno Setup and WIX 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 Added 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 Added 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. The following compression methods may take advantage of multiple cores: xz Supported if CMake is built with a liblzma that supports parallel compression. Added in version 3.21: Official CMake binaries available on cmake.org now ship with a liblzma that supports parallel compression. Older versions did not. zstd Added in version 3.24. Supported if CMake is built with libarchive 3.6 or higher. Official CMake binaries available on cmake.org support it. Other compression methods ignore this value and use only one thread. Variables for Source Package Generators The following CPack variables are specific to source packages, and will not affect binary packages: 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.* Variables for Advanced Use The following variables are for advanced uses of CPack: CPACK_CMAKE_GENERATOR What CMake generator should be used if the project is a CMake project. Defaults to the value of CMAKE_GENERATOR <# variable: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 <# variable: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 Added 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 <# variable:CMAKE_CURRENT_SOURCE_DIR>, CMAKE_CURRENT_BINARY_DIR <# variable:CMAKE_CURRENT_BINARY_DIR> and CMAKE_INSTALL_PREFIX <# variable: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 Added 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 Added 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 Added 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_ 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: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 <# manual:cpack(1)> without the -G <#cmdoption-cpack-G> option. CPACK_READELF_EXECUTABLE Added in version 3.25. Specify the readelf executable path used by CPack. The default value will be taken from the CMAKE_READELF variable, if set, which may be populated CMake when enabling languages. If CMAKE_READELF is not set, CPack will use find_program() <# command:find_program> to determine the readelf path when needed. CPACK_OBJCOPY_EXECUTABLE Added in version 3.25. Specify the objcopy executable path used by CPack. The default value will be taken from the CMAKE_OBJCOPY variable, if set, which may be populated by CMake when enabling languages. If CMAKE_OBJCOPY is not set, CPack will use find_program() <# command:find_program> to determine the objcopy path when needed. CPACK_OBJDUMP_EXECUTABLE Added in version 3.25. Specify the objdump executable path used by CPack. The default value will be taken from the CMAKE_OBJDUMP <# variable:CMAKE_OBJDUMP> variable, which may be populated by CMake when enabling languages. If CMAKE_OBJDUMP is not set, CPack will use find_program() <#command:find_program> to determine the objdump path when needed. CPackComponent This module provides commands to configure components for binary installers and source packages. Load this module in a CMake project with: include(CPackComponent) Introduction This module is also automatically included by CPack <#module:CPack>. Certain binary installers (especially the graphical installers) generated by CPack allow users to select individual application components to install. This module allows developers to configure the packaging of such components. Contents is assigned to components by the COMPONENT argument of CMake's install() <#command:install> command. Components can be annotated with user-friendly names and descriptions, inter-component dependencies, etc., and grouped in various ways to customize the resulting installer, using the commands described below. To specify different groupings for different CPack generators use a CPACK_PROJECT_CONFIG_FILE. Variables The following variables influence the component-specific packaging: 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:get_cmake_property> command can be used to obtain the COMPONENTS property, then the list(REMOVE_ITEM) <#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__COMPONENT_INSTALL Enable/Disable component install for CPack generator . 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: o ONE_PER_GROUP (default): create one package per component group o IGNORE : create one package per component (ignore the groups) o ALL_COMPONENTS_IN_ONE : create a single package with all requested components CPACK_COMPONENT__DISPLAY_NAME The name to be displayed for a component. CPACK_COMPONENT__DESCRIPTION The description of a component. CPACK_COMPONENT__GROUP The group of a component. CPACK_COMPONENT__DEPENDS The dependencies (list of components) on which this component depends. CPACK_COMPONENT__HIDDEN True if this component is hidden from the user. CPACK_COMPONENT__REQUIRED True if this component is required. CPACK_COMPONENT__DISABLED True if this component is not selected to be installed by default. Commands Add component cpack_add_component Describe an installation component. cpack_add_component(compname [DISPLAY_NAME name] [DESCRIPTION description] [HIDDEN | REQUIRED | DISABLED ] [GROUP group] [DEPENDS comp1 comp2 ... ] [INSTALL_TYPES type1 type2 ... ] [DOWNLOADED] [ARCHIVE_FILE filename] [PLIST filename]) compname is the name of an installation component, as defined by the COMPONENT argument of one or more CMake install() <#command:install> commands. With the cpack_add_component command one can set a name, a description, and other attributes of an installation component. One can also assign a component to a component group. DISPLAY_NAME is the displayed name of the component, used in graphical installers to display the component name. This value can be any string. DESCRIPTION is an extended description of the component, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using \n as the line separator. Typically, these descriptions should be no more than a few lines long. HIDDEN indicates that this component will be hidden in the graphical installer, so that the user cannot directly change whether it is installed or not. REQUIRED indicates that this component is required, and therefore will always be installed. It will be visible in the graphical installer, but it cannot be unselected. (Typically, required components are shown grayed out). DISABLED indicates that this component should be disabled (unselected) by default. The user is free to select this component for installation, unless it is also HIDDEN. DEPENDS lists the components on which this component depends. If this component is selected, then each of the components listed must also be selected. The dependency information is encoded within the installer itself, so that users cannot install inconsistent sets of components. GROUP names the component group of which this component is a part. If not provided, the component will be a standalone component, not part of any component group. Component groups are described with the cpack_add_component_group command, detailed below. INSTALL_TYPES lists the installation types of which this component is a part. When one of these installations types is selected, this component will automatically be selected. Installation types are described with the cpack_add_install_type command, detailed below. DOWNLOADED indicates that this component should be downloaded on-the-fly by the installer, rather than packaged in with the installer itself. For more information, see the cpack_configure_downloads command. ARCHIVE_FILE provides a name for the archive file created by CPack to be used for downloaded components. If not supplied, CPack will create a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of the component. See cpack_configure_downloads for more information. PLIST gives a filename that is passed to pkgbuild with the --component-plist argument when using the productbuild generator. Add component group cpack_add_component_group Describes a group of related CPack installation components. cpack_add_component_group(groupname [DISPLAY_NAME name] [DESCRIPTION description] [PARENT_GROUP parent] [EXPANDED] [BOLD_TITLE]) The cpack_add_component_group describes a group of installation components, which will be placed together within the listing of options. Typically, component groups allow the user to select/deselect all of the components within a single group via a single group-level option. Use component groups to reduce the complexity of installers with many options. groupname is an arbitrary name used to identify the group in the GROUP argument of the cpack_add_component command, which is used to place a component in a group. The name of the group must not conflict with the name of any component. DISPLAY_NAME is the displayed name of the component group, used in graphical installers to display the component group name. This value can be any string. DESCRIPTION is an extended description of the component group, used in graphical installers to give the user additional information about the components within that group. Descriptions can span multiple lines using \n as the line separator. Typically, these descriptions should be no more than a few lines long. PARENT_GROUP, if supplied, names the parent group of this group. Parent groups are used to establish a hierarchy of groups, providing an arbitrary hierarchy of groups. EXPANDED indicates that, by default, the group should show up as "expanded", so that the user immediately sees all of the components within the group. Otherwise, the group will initially show up as a single entry. BOLD_TITLE indicates that the group title should appear in bold, to call the user's attention to the group. Add installation type cpack_add_install_type Add a new installation type containing a set of predefined component selections to the graphical installer. cpack_add_install_type(typename [DISPLAY_NAME name]) The cpack_add_install_type command identifies a set of preselected components that represents a common use case for an application. For example, a "Developer" install type might include an application along with its header and library files, while an "End user" install type might just include the application's executable. Each component identifies itself with one or more install types via the INSTALL_TYPES argument to cpack_add_component. DISPLAY_NAME is the displayed name of the install type, which will typically show up in a drop-down box within a graphical installer. This value can be any string. Configure downloads cpack_configure_downloads Configure CPack to download selected components on-the-fly as part of the installation process. cpack_configure_downloads(site [UPLOAD_DIRECTORY dirname] [ALL] [ADD_REMOVE|NO_ADD_REMOVE]) The cpack_configure_downloads command configures installation-time downloads of selected components. For each downloadable component, CPack will create an archive containing the contents of that component, which should be uploaded to the given site. When the user selects that component for installation, the installer will download and extract the component in place. This feature is useful for creating small installers that only download the requested components, saving bandwidth. Additionally, the installers are small enough that they will be installed as part of the normal installation process, and the "Change" button in Windows Add/Remove Programs control panel will allow one to add or remove parts of the application after the original installation. On Windows, the downloaded-components functionality requires the ZipDLL plug-in for NSIS, available at: http://nsis.sourceforge.net/ZipDLL_plug-in On macOS, installers that download components on-the-fly can only be built and installed on system using macOS 10.5 or later. The site argument is a URL where the archives for downloadable components will reside, e.g., All of the archives produced by CPack should be uploaded to that location. UPLOAD_DIRECTORY is the local directory where CPack will create the various archives for each of the components. The contents of this directory should be uploaded to a location accessible by the URL given in the site argument. If omitted, CPack will use the directory CPackUploads inside the CMake binary directory to store the generated archives. The ALL flag indicates that all components be downloaded. Otherwise, only those components explicitly marked as DOWNLOADED or that have a specified ARCHIVE_FILE will be downloaded. Additionally, the ALL option implies ADD_REMOVE (unless NO_ADD_REMOVE is specified). ADD_REMOVE indicates that CPack should install a copy of the installer that can be called from Windows' Add/Remove Programs dialog (via the "Modify" button) to change the set of installed components. NO_ADD_REMOVE turns off this behavior. This option is ignored on Mac OS X. CPackIFW Added in version 3.1. This module looks for the location of the command-line utilities supplied with the Qt Installer Framework (QtIFW). Load this module in a CMake project with: include(CPackIFW) The module also defines several commands to control the behavior of the CPack IFW Generator <#cpack_gen:CPack IFW Generator>. Commands The module defines the following commands: cpack_ifw_configure_component Sets the arguments specific to the CPack IFW generator. cpack_ifw_configure_component( [COMMON] [ESSENTIAL] [VIRTUAL] [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS] [NAME ] [DISPLAY_NAME ] # Note: Internationalization supported [DESCRIPTION ] # Note: Internationalization supported [UPDATE_TEXT ] [VERSION ] [RELEASE_DATE ] [SCRIPT