--- name: "cmake-modules" section: "7" platform: "linux" package: "cmake" version: "4.4.5-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/cmake-modules" --- # cmake-modules(7) 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. ## 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)](/ctest/1.md)** \<#manual:[ctest(1)](/ctest/1.md)\> 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: - • **fixup\_bundle()** - • **copy\_and\_fixup\_bundle()** - • **verify\_app()** - • **get\_bundle\_main\_executable()** - • **get\_dotapp\_dir()** - • **get\_bundle\_and\_executable()** - • **get\_bundle\_all\_executables()** - • **get\_item\_key()** - • **get\_item\_rpaths()** - • **clear\_bundle\_keys()** - • **set\_bundle\_key\_values()** - • **get\_bundle\_keys()** - • **copy\_resolved\_item\_into\_bundle()** - • **copy\_resolved\_framework\_into\_bundle()** - • **fixup\_bundle\_item()** - • **verify\_bundle\_prerequisites()** - • **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 - • 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 - • 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 - • The **CheckSourceCompiles** \<#module:CheckSourceCompiles\> module for a more general command to check whether source can be built. - • 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 - • The **CheckSourceRuns** \<#module:CheckSourceRuns\> module for a more general command syntax. - • 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 - • 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 - • The **CheckSourceCompiles** \<#module:CheckSourceCompiles\> module for a more general command to check whether source can be built. - • 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 - • The **CheckSourceRuns** \<#module:CheckSourceRuns\> module for a more general command syntax. - • 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 - • 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 - • 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 - • The **CheckFunctionExists** \<#module:CheckFunctionExists\> module to check whether a C function exists. - • 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 - • The **CheckSourceCompiles** \<#module:CheckSourceCompiles\> module for a more general command to check whether source can be built. - • 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 - • The **CheckSourceRuns** \<#module:CheckSourceRuns\> module for a more general command syntax. - • 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: - • **check\_function\_exists()** can't detect functions that are inlined in headers or defined as preprocessor macros. - • **check\_function\_exists()** can't detect anything in the 32-bit versions of the Win32 API, because of a mismatch in calling conventions. - • **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 - • The **CheckSymbolExists** \<#module:CheckSymbolExists\> module to check whether a C symbol exists. - • The **CheckSourceCompiles** \<#module:CheckSourceCompiles\> module to check whether a source code can be compiled. - • 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 space-separated string 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 - • The **CheckIncludeFileCXX** \<#module:CheckIncludeFileCXX\> module to check for single C++ header. - • 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 space-separated string 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 - • The **CheckIncludeFile** \<#module:CheckIncludeFile\> module to check for single C header. - • 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 - • The **CheckIncludeFile** \<#module:CheckIncludeFile\> module to check for a single C header. - • 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: - • **C** - • **CXX** - • **CUDA** Added in version 3.25. - • **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 - • 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 - • The **CMAKE\_LINKER\_TYPE** \<#variable:CMAKE\_LINKER\_TYPE\> variable to specify the linker, which will be used also by this module. - • 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 - • 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 - • The **CheckSourceCompiles** \<#module:CheckSourceCompiles\> module for a more general command to check whether source can be built. - • 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 - • The **CheckSourceRuns** \<#module:CheckSourceRuns\> module for a more general command syntax. - • 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 - • 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 - • The **CheckSourceCompiles** \<#module:CheckSourceCompiles\> module for a more general command to check whether source can be built. - • 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 - • The **CheckSourceRuns** \<#module:CheckSourceRuns\> module for a more general command syntax. - • 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 - • 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 - • 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 - • 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 - • 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: - • **LINK\_LIBS** marks the start of a new pair - • **\** is a library target. - • **\...** represents one or more dependencies required by **\**. - **CMAKE\_COMMAND\_LINE** Additional command-line flags passed to **[cmake(1)](/cmake/1.md)** \<#manual:[cmake(1)](/cmake/1.md)\> 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: - • The **add\_subdirectory()** \<#command:add\_subdirectory\> command to add the subdirectory directly to the build. - • The **export()** \<#command:export\> command can be used in the subproject to provide Imported Targets \<#imported-targets\> or similar for integration with other projects. - • 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: - • **TestForANSIForScope** \<#module:TestForANSIForScope\> - • **TestForANSIStreamHeaders** \<#module:TestForANSIStreamHeaders\> - • **TestForSSTREAM** \<#module:TestForSSTREAM\> - • **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)](/cmake-gui/1.md)** \<#manual:[cmake-gui(1)](/cmake-gui/1.md)\> or **[ccmake(1)](/ccmake/1.md)** \<#manual:[ccmake(1)](/ccmake/1.md)\>), 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. - • If **\** evaluates to boolean false, option is hidden from the user in the GUI, and a local variable **\** is set to **\**. - • 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. - • 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 **\**. - • If **\** becomes true again in consecutive configuration runs, the user's previously set value is preserved. The **\** argument can be: - • A single condition (such as a variable name). - • A semicolon-separated list \<#cmake-language-lists\> of multiple conditions. - • 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 - • 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 **SamePatchVersion** is used, the package is only considered compatible if the requested version matches exactly through the patch version, ignoring any tweak version. For example, version 1.2.3.4 of a package is considered compatible with requested version 1.2.3.5, but not with requested version 1.2.4. If **SameFullVersion** is used, the package is only considered compatible if the requested version matches exactly through all specified version components. For example, version 1.2.3.4 of a package is only considered compatible with requested version 1.2.3.4. Missing version components are not treated as implicit zeroes, so version 1.2.3 is not considered compatible with requested version 1.2.3.0. If **SemanticVersion** is used, the behavior follows the usual semantic versioning interpretation: when the installed package version has a major component greater than zero, the behavior is the same as **SameMajorVersion**. When the installed package version has a major component zero, the behavior is the same as **SameMinorVersion**. If **ExactVersion** is used, the behavior is the same as **SamePatchVersion**. 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. Added in version 4.4: The **SamePatchVersion**, **SameFullVersion**, and **SemanticVersion** compatibility modes. The version file generated by **SemanticVersion** handles version ranges if one is specified (see **find\_package()** \<#command:find\_package\> command for the details). **SamePatchVersion** and **SameFullVersion** modes are incompatible with version ranges and will display an author warning if one is specified. Deprecated since version 4.4: The **ExactVersion** compatibility mode. Use **SamePatchVersion** or **SameFullVersion** instead, depending on whether the tweak version should be ignored. 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: - • **cmake\_push\_check\_state()** - • **cmake\_reset\_check\_state()** - • **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)](/cpack/1.md)\> 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)](/cpack/1.md)\> 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: - • **cpack** \<#manual:[cpack(1)](/cpack/1.md)\> runs - • it includes **CPackConfig.cmake** - • 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. - • foreach generator, it then - • sets **CPACK\_GENERATOR** to the one currently being iterated - • includes the **CPACK\_PROJECT\_CONFIG\_FILE** - • 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)](/cpack-generators/7.md)** \<#manual:[cpack-generators(7)](/cpack-generators/7.md)\>. ### 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)](/cpack/1.md)\> 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)](/cpack/1.md)\> 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. - **CPACK\_COMPRESSION\_LEVEL** Added in version 4.3. Select the compression level to use when it's applicable, such as compressing the installer package. Some compression methods used by CPack generators such as Debian or Archive may take advantage of different compression levels. The accepted values are in the range **0** to **9**. If you select the **zstd** compression method, you can select the compression level between **0** and **19**, except the **zip** archive format. By default **CPACK\_COMPRESSION\_LEVEL** is set to **0**, which selects the default compression level. It is selected automatically by the archive library backend and not directly set by CMake itself. The default compression level may vary between archive formats, platforms, etc. ### 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)](/cpack/1.md)\> 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: - • ONE\_PER\_GROUP (default): create one package per component group - • IGNORE : create one package per component (ignore the groups) - • 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