.\" Man page generated from reStructuredText. . .TH "CMAKE-MODULES" "7" "December 03, 2022" "3.25.1" "CMake" .SH NAME cmake-modules \- CMake Modules Reference . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .sp The modules listed here are part of the CMake distribution. Projects may provide further modules; their location(s) can be specified in the \fBCMAKE_MODULE_PATH\fP variable. .SH UTILITY MODULES .sp These modules are loaded using the \fBinclude()\fP command. .SS AndroidTestUtilities .sp New in version 3.7. .sp Create a test that automatically loads specified data onto an Android device. .SS Introduction .sp Use this module to push data needed for testing an Android device behavior onto a connected Android device. The module will accept files and libraries 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. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include(AndroidTestUtilities) android_add_test_data( example_setup_test FILES ... LIBS ... DEVICE_TEST_DIR "/data/local/tests/example" DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA" ) .ft P .fi .UNINDENT .UNINDENT .sp At build time a test named "example_setup_test" will be created. Run this test on the command line with \fBctest(1)\fP to load the data onto the Android device. .SS Module Functions .INDENT 0.0 .TP .B android_add_test_data .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C android_add_test_data( [FILES ...] [FILES_DEST ] [LIBS ...] [LIBS_DEST ] [DEVICE_OBJECT_STORE ] [DEVICE_TEST_DIR ] [NO_LINK_REGEX ...] ) .ft P .fi .UNINDENT .UNINDENT .sp The \fBandroid_add_test_data\fP function is used to copy files and libraries needed to run project\-specific tests. On the host operating system, this is done at build time. For on\-device testing, the files are loaded onto the device by the manufactured test at run time. .sp This function accepts the following named parameters: .INDENT 7.0 .TP .B \fBFILES ...\fP zero or more files needed for testing .TP .B \fBLIBS ...\fP zero or more libraries needed for testing .TP .B \fBFILES_DEST \fP absolute path where the data files are expected to be .TP .B \fBLIBS_DEST \fP absolute path where the libraries are expected to be .TP .B \fBDEVICE_OBJECT_STORE \fP absolute path to the location where the data is stored on\-device .TP .B \fBDEVICE_TEST_DIR \fP absolute path to the root directory of the on\-device test location .TP .B \fBNO_LINK_REGEX ...\fP list of regex strings matching the names of files that should be copied from the object store to the testing directory .UNINDENT .UNINDENT .SS BundleUtilities .sp Functions to help assemble a standalone bundle application. .sp A collection of CMake utility functions useful for dealing with \fB\&.app\fP bundles on the Mac and bundle\-like directories on any OS. .sp The following functions are provided by this module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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 .ft P .fi .UNINDENT .UNINDENT .sp Requires CMake 2.6 or greater because it uses function, break and \fBPARENT_SCOPE\fP\&. Also depends on \fBGetPrerequisites.cmake\fP\&. .sp DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from \fBCMakeLists.txt\fP)! Instead, invoke them from an \fBinstall(CODE)\fP or \fBinstall(SCRIPT)\fP rule. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fixup_bundle( ) .ft P .fi .UNINDENT .UNINDENT .sp Fix up \fB\fP bundle in\-place and make it standalone, such that it can be drag\-n\-drop copied to another machine and run on that machine as long as all of the system libraries are compatible. .sp If you pass plugins to \fBfixup_bundle\fP as the libs parameter, you should install them or copy them into the bundle before calling \fBfixup_bundle\fP\&. The \fB\fP parameter is a list of libraries that must be fixed up, but that cannot be determined by \fBotool\fP output analysis (i.e. \fBplugins\fP). .sp Gather all the keys for all the executables and libraries in a bundle, and then, for each key, copy each prerequisite into the bundle. Then fix each one up according to its own list of prerequisites. .sp Then clear all the keys and call \fBverify_app\fP on the final bundle to ensure that it is truly standalone. .sp New in version 3.6: As an optional parameter (\fBIGNORE_ITEM\fP) a list of file names can be passed, which are then ignored (e.g. \fBIGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"\fP). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C copy_and_fixup_bundle( ) .ft P .fi .UNINDENT .UNINDENT .sp Makes a copy of the bundle \fB\fP at location \fB\fP and then fixes up the new copied bundle in\-place at \fB\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C verify_app() .ft P .fi .UNINDENT .UNINDENT .sp Verifies that an application \fB\fP appears valid based on running analysis tools on it. Calls \fBmessage(FATAL_ERROR)\fP if the application is not verified. .sp New in version 3.6: As an optional parameter (\fBIGNORE_ITEM\fP) a list of file names can be passed, which are then ignored (e.g. \fBIGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"\fP) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C get_bundle_main_executable( ) .ft P .fi .UNINDENT .UNINDENT .sp The result will be the full path name of the bundle\(aqs main executable file or an \fBerror:\fP prefixed string if it could not be determined. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C get_dotapp_dir( ) .ft P .fi .UNINDENT .UNINDENT .sp Returns the nearest parent dir whose name ends with \fB\&.app\fP given the full path to an executable. If there is no such parent dir, then simply return the dir containing the executable. .sp The returned directory may or may not exist. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C get_bundle_and_executable( ) .ft P .fi .UNINDENT .UNINDENT .sp Takes either a \fB\&.app\fP directory name or the name of an executable nested inside a \fB\&.app\fP directory and returns the path to the \fB\&.app\fP directory in \fB\fP and the path to its main executable in \fB\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C get_bundle_all_executables( ) .ft P .fi .UNINDENT .UNINDENT .sp Scans \fB\fP bundle recursively for all \fB\fP executable files and accumulates them into a variable. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C get_item_key( ) .ft P .fi .UNINDENT .UNINDENT .sp Given \fB\fP file name, generate \fB\fP 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 \fB\&.\fP replaced by \fB_\fP .sp This key is used as a prefix for CMake variables so that we can associate a set of variables with a given item based on its key. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C clear_bundle_keys() .ft P .fi .UNINDENT .UNINDENT .sp Loop over the \fB\fP list of keys, clearing all the variables associated with each key. After the loop, clear the list of keys itself. .sp Caller of \fBget_bundle_keys\fP should call \fBclear_bundle_keys\fP when done with list of keys. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C set_bundle_key_values( []) .ft P .fi .UNINDENT .UNINDENT .sp Add \fB\fP key to the list (if necessary) for the given item. If added, also set all the variables associated with that key. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C get_bundle_keys( ) .ft P .fi .UNINDENT .UNINDENT .sp Loop over all the executable and library files within \fB\fP bundle (and given as extra \fB\fP) and accumulate a list of keys representing them. Set values associated with each key such that we can loop over all of them and copy prerequisite libs into the bundle and then do appropriate \fBinstall_name_tool\fP fixups. .sp New in version 3.6: As an optional parameter (\fBIGNORE_ITEM\fP) a list of file names can be passed, which are then ignored (e.g. \fBIGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"\fP) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C copy_resolved_item_into_bundle( ) .ft P .fi .UNINDENT .UNINDENT .sp Copy a resolved item into the bundle if necessary. Copy is not necessary, if the \fB\fP is "the same as" the \fB\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C copy_resolved_framework_into_bundle( ) .ft P .fi .UNINDENT .UNINDENT .sp Copy a resolved framework into the bundle if necessary. Copy is not necessary, if the \fB\fP is "the same as" the \fB\fP\&. .sp By default, \fBBU_COPY_FULL_FRAMEWORK_CONTENTS\fP is not set. If you want full frameworks embedded in your bundles, set \fBBU_COPY_FULL_FRAMEWORK_CONTENTS\fP to \fBON\fP before calling fixup_bundle. By default, \fBCOPY_RESOLVED_FRAMEWORK_INTO_BUNDLE\fP copies the framework dylib itself plus the framework \fBResources\fP directory. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fixup_bundle_item( ) .ft P .fi .UNINDENT .UNINDENT .sp Get the direct/non\-system prerequisites of the \fB\fP\&. For each prerequisite, change the way it is referenced to the value of the \fB_EMBEDDED_ITEM\fP keyed variable for that prerequisite. (Most likely changing to an \fB@executable_path\fP style reference.) .sp This function requires that the \fB\fP be \fBinside\fP the bundle already. In other words, if you pass plugins to \fBfixup_bundle\fP as the libs parameter, you should install them or copy them into the bundle before calling \fBfixup_bundle\fP\&. The \fBlibs\fP parameter is a list of libraries that must be fixed up, but that cannot be determined by otool output analysis. (i.e., \fBplugins\fP) .sp Also, change the id of the item being fixed up to its own \fB_EMBEDDED_ITEM\fP value. .sp Accumulate changes in a local variable and make \fIone\fP call to \fBinstall_name_tool\fP at the end of the function with all the changes at once. .sp If the \fBBU_CHMOD_BUNDLE_ITEMS\fP variable is set then bundle items will be marked writable before \fBinstall_name_tool\fP tries to change them. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C verify_bundle_prerequisites( ) .ft P .fi .UNINDENT .UNINDENT .sp Verifies that the sum of all prerequisites of all files inside the bundle are contained within the bundle or are \fBsystem\fP libraries, presumed to exist everywhere. .sp New in version 3.6: As an optional parameter (\fBIGNORE_ITEM\fP) a list of file names can be passed, which are then ignored (e.g. \fBIGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"\fP) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C verify_bundle_symlinks( ) .ft P .fi .UNINDENT .UNINDENT .sp Verifies that any symlinks found in the \fB\fP bundle point to other files that are already also in the bundle... Anything that points to an external file causes this function to fail the verification. .SS CheckCCompilerFlag .sp Check whether the C compiler supports a given flag. .INDENT 0.0 .TP .B check_c_compiler_flag .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_c_compiler_flag( ) .ft P .fi .UNINDENT .UNINDENT .sp Check that the \fB\fP is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry named \fB\fP\&. .UNINDENT .sp This command temporarily sets the \fBCMAKE_REQUIRED_DEFINITIONS\fP variable and calls the \fBcheck_c_source_compiles\fP macro from the \fBCheckCSourceCompiles\fP module. See documentation of that module for a listing of variables that can otherwise modify the build. .sp A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since the \fBtry_compile()\fP command forwards flags from variables like \fBCMAKE_C_FLAGS\fP, unknown flags in such variables may cause a false negative for this check. .UNINDENT .UNINDENT .SS CheckCompilerFlag .sp New in version 3.19. .sp Check whether the compiler supports a given flag. .INDENT 0.0 .TP .B check_compiler_flag .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_compiler_flag( ) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Check that the \fB\fP is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry named \fB\fP\&. .sp This command temporarily sets the \fBCMAKE_REQUIRED_DEFINITIONS\fP variable and calls the \fBcheck_source_compiles()\fP function from the \fBCheckSourceCompiles\fP module. See documentation of that module for a listing of variables that can otherwise modify the build. .sp A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since the \fBtry_compile()\fP command forwards flags from variables like \fBCMAKE__FLAGS\fP, unknown flags in such variables may cause a false negative for this check. .UNINDENT .UNINDENT .SS CheckCSourceCompiles .sp Check if given C source compiles and links into an executable. .INDENT 0.0 .TP .B check_c_source_compiles .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_c_source_compiles( [FAIL_REGEX [...]]) .ft P .fi .UNINDENT .UNINDENT .sp Check that the source supplied in \fB\fP can be compiled as a C source file and linked as an executable (so it must contain at least a \fBmain()\fP function). The result will be stored in the internal cache variable specified by \fB\fP, with a boolean true value for success and boolean false for failure. If \fBFAIL_REGEX\fP is provided, then failure is determined by checking if anything in the output matches any of the specified regular expressions. .sp The underlying check is performed by the \fBtry_compile()\fP command. The compile and link commands can be influenced by setting any of the following variables prior to calling \fBcheck_c_source_compiles()\fP: .INDENT 7.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP Additional flags to pass to the compiler. Note that the contents of \fBCMAKE_C_FLAGS\fP and its associated configuration\-specific variable are automatically added to the compiler command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP A ;\-list of compiler definitions of the form \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by \fB\fP will also be added automatically. .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP A ;\-list of header search paths to pass to the compiler. These will be the only header search paths used by \fBtry_compile()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP directory property will be ignored. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14. .sp A ;\-list of options to add to the link command (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1. .sp If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. .UNINDENT .sp The check is only performed once, with the result cached in the variable named by \fB\fP\&. Every subsequent CMake run will re\-use this cached value rather than performing the check again, even if the \fB\fP changes. In order to force the check to be re\-evaluated, the variable named by \fB\fP must be manually removed from the cache. .UNINDENT .SS CheckCSourceRuns .sp Check if given C source compiles and links into an executable and can subsequently be run. .INDENT 0.0 .TP .B check_c_source_runs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_c_source_runs( ) .ft P .fi .UNINDENT .UNINDENT .sp Check that the source supplied in \fB\fP can be compiled as a C source file, linked as an executable and then run. The \fB\fP must contain at least a \fBmain()\fP function. If the \fB\fP could be built and run successfully, the internal cache variable specified by \fB\fP will be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message). .sp The underlying check is performed by the \fBtry_run()\fP command. The compile and link commands can be influenced by setting any of the following variables prior to calling \fBcheck_c_source_runs()\fP: .INDENT 7.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP Additional flags to pass to the compiler. Note that the contents of \fBCMAKE_C_FLAGS\fP and its associated configuration\-specific variable are automatically added to the compiler command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP A ;\-list of compiler definitions of the form \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by \fB\fP will also be added automatically. .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP A ;\-list of header search paths to pass to the compiler. These will be the only header search paths used by \fBtry_run()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP directory property will be ignored. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14. .sp A ;\-list of options to add to the link command (see \fBtry_run()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_run()\fP for further details). .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1. .sp If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. .UNINDENT .sp The check is only performed once, with the result cached in the variable named by \fB\fP\&. Every subsequent CMake run will re\-use this cached value rather than performing the check again, even if the \fB\fP changes. In order to force the check to be re\-evaluated, the variable named by \fB\fP must be manually removed from the cache. .UNINDENT .SS CheckCXXCompilerFlag .sp Check whether the CXX compiler supports a given flag. .INDENT 0.0 .TP .B check_cxx_compiler_flag .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_cxx_compiler_flag( ) .ft P .fi .UNINDENT .UNINDENT .sp Check that the \fB\fP is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry named \fB\fP\&. .UNINDENT .sp This command temporarily sets the \fBCMAKE_REQUIRED_DEFINITIONS\fP variable and calls the \fBcheck_cxx_source_compiles\fP macro from the \fBCheckCXXSourceCompiles\fP module. See documentation of that module for a listing of variables that can otherwise modify the build. .sp A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since the \fBtry_compile()\fP command forwards flags from variables like \fBCMAKE_CXX_FLAGS\fP, unknown flags in such variables may cause a false negative for this check. .UNINDENT .UNINDENT .SS CheckCXXSourceCompiles .sp Check if given C++ source compiles and links into an executable. .INDENT 0.0 .TP .B check_cxx_source_compiles .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_cxx_source_compiles( [FAIL_REGEX [...]]) .ft P .fi .UNINDENT .UNINDENT .sp Check that the source supplied in \fB\fP can be compiled as a C++ source file and linked as an executable (so it must contain at least a \fBmain()\fP function). The result will be stored in the internal cache variable specified by \fB\fP, with a boolean true value for success and boolean false for failure. If \fBFAIL_REGEX\fP is provided, then failure is determined by checking if anything in the output matches any of the specified regular expressions. .sp The underlying check is performed by the \fBtry_compile()\fP command. The compile and link commands can be influenced by setting any of the following variables prior to calling \fBcheck_cxx_source_compiles()\fP: .INDENT 7.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP Additional flags to pass to the compiler. Note that the contents of \fBCMAKE_CXX_FLAGS\fP and its associated configuration\-specific variable are automatically added to the compiler command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP A ;\-list of compiler definitions of the form \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by \fB\fP will also be added automatically. .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP A ;\-list of header search paths to pass to the compiler. These will be the only header search paths used by \fBtry_compile()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP directory property will be ignored. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14. .sp A ;\-list of options to add to the link command (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1. .sp If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. .UNINDENT .sp The check is only performed once, with the result cached in the variable named by \fB\fP\&. Every subsequent CMake run will re\-use this cached value rather than performing the check again, even if the \fB\fP changes. In order to force the check to be re\-evaluated, the variable named by \fB\fP must be manually removed from the cache. .UNINDENT .SS CheckCXXSourceRuns .sp Check if given C++ source compiles and links into an executable and can subsequently be run. .INDENT 0.0 .TP .B check_cxx_source_runs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_cxx_source_runs( ) .ft P .fi .UNINDENT .UNINDENT .sp Check that the source supplied in \fB\fP can be compiled as a C++ source file, linked as an executable and then run. The \fB\fP must contain at least a \fBmain()\fP function. If the \fB\fP could be built and run successfully, the internal cache variable specified by \fB\fP will be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message). .sp The underlying check is performed by the \fBtry_run()\fP command. The compile and link commands can be influenced by setting any of the following variables prior to calling \fBcheck_cxx_source_runs()\fP: .INDENT 7.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP Additional flags to pass to the compiler. Note that the contents of \fBCMAKE_CXX_FLAGS\fP and its associated configuration\-specific variable are automatically added to the compiler command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP A ;\-list of compiler definitions of the form \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by \fB\fP will also be added automatically. .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP A ;\-list of header search paths to pass to the compiler. These will be the only header search paths used by \fBtry_run()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP directory property will be ignored. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14. .sp A ;\-list of options to add to the link command (see \fBtry_run()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_run()\fP for further details). .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1. .sp If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. .UNINDENT .sp The check is only performed once, with the result cached in the variable named by \fB\fP\&. Every subsequent CMake run will re\-use this cached value rather than performing the check again, even if the \fB\fP changes. In order to force the check to be re\-evaluated, the variable named by \fB\fP must be manually removed from the cache. .UNINDENT .SS CheckCXXSymbolExists .sp Check if a symbol exists as a function, variable, or macro in \fBC++\fP\&. .INDENT 0.0 .TP .B check_cxx_symbol_exists .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_cxx_symbol_exists( ) .ft P .fi .UNINDENT .UNINDENT .sp Check that the \fB\fP is available after including given header \fB\fP and store the result in a \fB\fP\&. Specify the list of files in one argument as a semicolon\-separated list. \fBcheck_cxx_symbol_exists()\fP can be used to check for symbols as seen by the C++ compiler, as opposed to \fBcheck_symbol_exists()\fP, which always uses the \fBC\fP compiler. .sp If the header files define the symbol as a macro it is considered available and assumed to work. If the header files declare the symbol as a function or variable then the symbol must also be available for linking. If the symbol is a type, enum value, or C++ template it will not be recognized: consider using the \fBCheckTypeSize\fP or \fBCheckSourceCompiles\fP module instead. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This command is unreliable when \fB\fP is (potentially) an overloaded function. 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 \fBCheckCXXSourceCompiles\fP module for checking any function symbol (unless somehow you surely know the checked function is not overloaded on other systems or will not be so in the future). .UNINDENT .UNINDENT .sp The following variables may be set before calling this macro to modify the way the check is run: .INDENT 0.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP string of compile command line flags. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP a ;\-list of macros to define (\-DFOO=bar). .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP a ;\-list of header search paths to pass to the compiler. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14: a ;\-list of options to add to the link command. .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP a ;\-list of libraries to add to the link command. See policy \fBCMP0075\fP\&. .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1: execute quietly without messages. .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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) .ft P .fi .UNINDENT .UNINDENT .SS CheckFortranCompilerFlag .sp New in version 3.3. .sp Check whether the Fortran compiler supports a given flag. .INDENT 0.0 .TP .B check_fortran_compiler_flag .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_fortran_compiler_flag( ) .ft P .fi .UNINDENT .UNINDENT .sp Check that the \fB\fP is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry named \fB\fP\&. .UNINDENT .sp This command temporarily sets the \fBCMAKE_REQUIRED_DEFINITIONS\fP variable and calls the \fBcheck_fortran_source_compiles\fP macro from the \fBCheckFortranSourceCompiles\fP module. See documentation of that module for a listing of variables that can otherwise modify the build. .sp A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since the \fBtry_compile()\fP command forwards flags from variables like \fBCMAKE_Fortran_FLAGS\fP, unknown flags in such variables may cause a false negative for this check. .UNINDENT .UNINDENT .SS CheckFortranFunctionExists .sp Check if a Fortran function exists. .INDENT 0.0 .TP .B CHECK_FORTRAN_FUNCTION_EXISTS .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C CHECK_FORTRAN_FUNCTION_EXISTS( ) .ft P .fi .UNINDENT .UNINDENT .sp where .INDENT 7.0 .TP .B \fB\fP the name of the Fortran function .TP .B \fB\fP variable to store the result; will be created as an internal cache variable. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This command does not detect functions in Fortran modules. In general it is recommended to use \fBCheckSourceCompiles\fP instead to determine if a Fortran function or subroutine is available. .UNINDENT .UNINDENT .sp The following variables may be set before calling this macro to modify the way the check is run: .INDENT 0.0 .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14: A ;\-list of options to add to the link command (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_compile()\fP for further details). .UNINDENT .SS CheckFortranSourceCompiles .sp New in version 3.1. .sp Check if given Fortran source compiles and links into an executable. .INDENT 0.0 .TP .B check_fortran_source_compiles .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_fortran_source_compiles( [FAIL_REGEX ...] [SRC_EXT ] ) .ft P .fi .UNINDENT .UNINDENT .sp Checks that the source supplied in \fB\fP can be compiled as a Fortran source file and linked as an executable. The \fB\fP must be a Fortran program containing at least an \fBend\fP statement\-\-for example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_fortran_source_compiles("character :: b; error stop b; end" F2018ESTOPOK SRC_EXT F90) .ft P .fi .UNINDENT .UNINDENT .sp This command can help avoid costly build processes when a compiler lacks support for a necessary feature, or a particular vendor library is not compatible with the Fortran compiler version being used. This generate\-time check may advise the user of such before the main build process. See also the \fBcheck_fortran_source_runs()\fP command to actually run the compiled code. .sp The result will be stored in the internal cache variable \fB\fP, with a boolean true value for success and boolean false for failure. .sp If \fBFAIL_REGEX\fP is provided, then failure is determined by checking if anything in the output matches any of the specified regular expressions. .sp By default, the test source file will be given a \fB\&.F\fP file extension. The \fBSRC_EXT\fP option can be used to override this with \fB\&.\fP instead\-\- \fB\&.F90\fP is a typical choice. .sp The underlying check is performed by the \fBtry_compile()\fP command. The compile and link commands can be influenced by setting any of the following variables prior to calling \fBcheck_fortran_source_compiles()\fP: .INDENT 7.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP Additional flags to pass to the compiler. Note that the contents of \fBCMAKE_Fortran_FLAGS\fP and its associated configuration\-specific variable are automatically added to the compiler command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP A ;\-list of compiler definitions of the form \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by \fB\fP will also be added automatically. .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP A ;\-list of header search paths to pass to the compiler. These will be the only header search paths used by \fBtry_compile()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP directory property will be ignored. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14. .sp A ;\-list of options to add to the link command (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_QUIET\fP If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. .UNINDENT .sp The check is only performed once, with the result cached in the variable named by \fB\fP\&. Every subsequent CMake run will re\-use this cached value rather than performing the check again, even if the \fB\fP changes. In order to force the check to be re\-evaluated, the variable named by \fB\fP must be manually removed from the cache. .UNINDENT .SS CheckFortranSourceRuns .sp New in version 3.14. .sp Check if given Fortran source compiles and links into an executable and can subsequently be run. .INDENT 0.0 .TP .B check_fortran_source_runs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_fortran_source_runs( [SRC_EXT ]) .ft P .fi .UNINDENT .UNINDENT .sp Check that the source supplied in \fB\fP can be compiled as a Fortran source file, linked as an executable and then run. The \fB\fP must be a Fortran program containing at least an \fBend\fP statement\-\-for example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK) .ft P .fi .UNINDENT .UNINDENT .sp This command can help avoid costly build processes when a compiler lacks support for a necessary feature, or a particular vendor library is not compatible with the Fortran compiler version being used. Some of these failures only occur at runtime instead of linktime, and a trivial runtime example can catch the issue before the main build process. .sp If the \fB\fP could be built and run successfully, the internal cache variable specified by \fB\fP will be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message). .sp By default, the test source file will be given a \fB\&.F90\fP file extension. The \fBSRC_EXT\fP option can be used to override this with \fB\&.\fP instead. .sp The underlying check is performed by the \fBtry_run()\fP command. The compile and link commands can be influenced by setting any of the following variables prior to calling \fBcheck_fortran_source_runs()\fP: .INDENT 7.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP Additional flags to pass to the compiler. Note that the contents of \fBCMAKE_Fortran_FLAGS\fP and its associated configuration\-specific variable are automatically added to the compiler command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP A ;\-list of compiler definitions of the form \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by \fB\fP will also be added automatically. .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP A ;\-list of header search paths to pass to the compiler. These will be the only header search paths used by \fBtry_run()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP directory property will be ignored. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP A ;\-list of options to add to the link command (see \fBtry_run()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_run()\fP for further details). .TP .B \fBCMAKE_REQUIRED_QUIET\fP If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. .UNINDENT .sp The check is only performed once, with the result cached in the variable named by \fB\fP\&. Every subsequent CMake run will re\-use this cached value rather than performing the check again, even if the \fB\fP changes. In order to force the check to be re\-evaluated, the variable named by \fB\fP must be manually removed from the cache. .UNINDENT .SS CheckFunctionExists .sp Check if a C function can be linked .INDENT 0.0 .TP .B check_function_exists .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_function_exists( ) .ft P .fi .UNINDENT .UNINDENT .sp Checks that the \fB\fP is provided by libraries on the system and store the result in a \fB\fP, which will be created as an internal cache variable. .UNINDENT .sp The following variables may be set before calling this macro to modify the way the check is run: .INDENT 0.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP string of compile command line flags. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP a ;\-list of macros to define (\-DFOO=bar). .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP a ;\-list of header search paths to pass to the compiler. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14: a ;\-list of options to add to the link command. .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP a ;\-list of libraries to add to the link command. See policy \fBCMP0075\fP\&. .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1: execute quietly without messages. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Prefer using \fBCheckSymbolExists\fP instead of this module, for the following reasons: .INDENT 0.0 .IP \(bu 2 \fBcheck_function_exists()\fP can\(aqt detect functions that are inlined in headers or specified as a macro. .IP \(bu 2 \fBcheck_function_exists()\fP can\(aqt detect anything in the 32\-bit versions of the Win32 API, because of a mismatch in calling conventions. .IP \(bu 2 \fBcheck_function_exists()\fP only verifies linking, it does not verify that the function is declared in system headers. .UNINDENT .UNINDENT .UNINDENT .SS CheckIncludeFileCXX .sp Provides a macro to check if a header file can be included in \fBCXX\fP\&. .INDENT 0.0 .TP .B CHECK_INCLUDE_FILE_CXX .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C CHECK_INCLUDE_FILE_CXX( []) .ft P .fi .UNINDENT .UNINDENT .sp Check if the given \fB\fP file may be included in a \fBCXX\fP source file and store the result in an internal cache entry named \fB\fP\&. The optional third argument may be used to add compilation flags to the check (or use \fBCMAKE_REQUIRED_FLAGS\fP below). .UNINDENT .sp The following variables may be set before calling this macro to modify the way the check is run: .INDENT 0.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP string of compile command line flags. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP a ;\-list of macros to define (\-DFOO=bar). .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP a ;\-list of header search paths to pass to the compiler. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14: a ;\-list of options to add to the link command. .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP a ;\-list of libraries to add to the link command. See policy \fBCMP0075\fP\&. .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1: execute quietly without messages. .UNINDENT .sp See modules \fBCheckIncludeFile\fP and \fBCheckIncludeFiles\fP to check for one or more \fBC\fP headers. .SS CheckIncludeFile .sp Provides a macro to check if a header file can be included in \fBC\fP\&. .INDENT 0.0 .TP .B CHECK_INCLUDE_FILE .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C CHECK_INCLUDE_FILE( []) .ft P .fi .UNINDENT .UNINDENT .sp Check if the given \fB\fP file may be included in a \fBC\fP source file and store the result in an internal cache entry named \fB\fP\&. The optional third argument may be used to add compilation flags to the check (or use \fBCMAKE_REQUIRED_FLAGS\fP below). .UNINDENT .sp The following variables may be set before calling this macro to modify the way the check is run: .INDENT 0.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP string of compile command line flags. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP a ;\-list of macros to define (\-DFOO=bar). .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP a ;\-list of header search paths to pass to the compiler. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14: a ;\-list of options to add to the link command. .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP a ;\-list of libraries to add to the link command. See policy \fBCMP0075\fP\&. .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1: execute quietly without messages. .UNINDENT .sp See the \fBCheckIncludeFiles\fP module to check for multiple headers at once. See the \fBCheckIncludeFileCXX\fP module to check for headers using the \fBCXX\fP language. .SS CheckIncludeFiles .sp Provides a macro to check if a list of one or more header files can be included together. .INDENT 0.0 .TP .B CHECK_INCLUDE_FILES .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C CHECK_INCLUDE_FILES("" [LANGUAGE ]) .ft P .fi .UNINDENT .UNINDENT .sp Check if the given \fB\fP list may be included together in a source file and store the result in an internal cache entry named \fB\fP\&. Specify the \fB\fP argument as a ;\-list of header file names. .sp If \fBLANGUAGE\fP is set, the specified compiler will be used to perform the check. Acceptable values are \fBC\fP and \fBCXX\fP\&. If not set, the C compiler will be used if enabled. If the C compiler is not enabled, the C++ compiler will be used if enabled. .UNINDENT .sp The following variables may be set before calling this macro to modify the way the check is run: .INDENT 0.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP string of compile command line flags. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP a ;\-list of macros to define (\-DFOO=bar). .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP a ;\-list of header search paths to pass to the compiler. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14: a ;\-list of options to add to the link command. .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP a ;\-list of libraries to add to the link command. See policy \fBCMP0075\fP\&. .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1: execute quietly without messages. .UNINDENT .sp See modules \fBCheckIncludeFile\fP and \fBCheckIncludeFileCXX\fP to check for a single header file in \fBC\fP or \fBCXX\fP languages. .SS CheckIPOSupported .sp New in version 3.9. .sp Check whether the compiler supports an interprocedural optimization (IPO/LTO). Use this before enabling the \fBINTERPROCEDURAL_OPTIMIZATION\fP target property. .INDENT 0.0 .TP .B check_ipo_supported .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_ipo_supported([RESULT ] [OUTPUT ] [LANGUAGES ...]) .ft P .fi .UNINDENT .UNINDENT .sp Options are: .INDENT 7.0 .TP .B \fBRESULT \fP Set \fB\fP variable to \fBYES\fP if IPO is supported by the compiler and \fBNO\fP otherwise. If this option is not given then the command will issue a fatal error if IPO is not supported. .TP .B \fBOUTPUT \fP Set \fB\fP variable with details about any error. .TP .B \fBLANGUAGES ...\fP Specify languages whose compilers to check. Languages \fBC\fP, \fBCXX\fP, and \fBFortran\fP are supported. .UNINDENT .UNINDENT .sp It makes no sense to use this module when \fBCMP0069\fP is set to \fBOLD\fP so module will return error in this case. See policy \fBCMP0069\fP for details. .sp New in version 3.13: Add support for Visual Studio generators. .sp New in version 3.24: The check uses the caller\(aqs \fBCMAKE__FLAGS\fP and \fBCMAKE__FLAGS_\fP values. See policy \fBCMP0138\fP\&. .SS Examples .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C check_ipo_supported() # fatal error if IPO is not supported set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Optional IPO. Do not use IPO if it\(aqs not supported by compiler. 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() .ft P .fi .UNINDENT .UNINDENT .SS CheckLanguage .sp Check if a language can be enabled .sp Usage: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C check_language() .ft P .fi .UNINDENT .UNINDENT .sp where \fB\fP is a language that may be passed to \fBenable_language()\fP such as \fBFortran\fP\&. If \fBCMAKE__COMPILER\fP is already defined the check does nothing. Otherwise it tries enabling the language in a test project. The result is cached in \fBCMAKE__COMPILER\fP as the compiler that was found, or \fBNOTFOUND\fP if the language cannot be enabled. For CUDA which can have an explicit host compiler, the cache \fBCMAKE_CUDA_HOST_COMPILER\fP variable will be set if it was required for compilation (and cleared if it was not). .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C check_language(Fortran) if(CMAKE_Fortran_COMPILER) enable_language(Fortran) else() message(STATUS "No Fortran support") endif() .ft P .fi .UNINDENT .UNINDENT .SS CheckLibraryExists .sp Check if the function exists. .INDENT 0.0 .TP .B CHECK_LIBRARY_EXISTS .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE) .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C LIBRARY \- the name of the library you are looking for FUNCTION \- the name of the function LOCATION \- location where the library should be found VARIABLE \- variable to store the result Will be created as an internal cache variable. .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp The following variables may be set before calling this macro to modify the way the check is run: .INDENT 0.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP string of compile command line flags. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP list of macros to define (\-DFOO=bar). .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14: list of options to pass to link command. .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP list of libraries to link. .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1: execute quietly without messages. .UNINDENT .SS CheckLinkerFlag .sp New in version 3.18. .sp Check whether the compiler supports a given link flag. .INDENT 0.0 .TP .B check_linker_flag .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_linker_flag( ) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Check that the link \fB\fP is accepted by the \fB\fP compiler without a diagnostic. Stores the result in an internal cache entry named \fB\fP\&. .sp This command temporarily sets the \fBCMAKE_REQUIRED_LINK_OPTIONS\fP variable and calls the \fBcheck_source_compiles()\fP command from the \fBCheckSourceCompiles\fP module. See that module\(aqs documentation for a listing of variables that can otherwise modify the build. .sp The underlying implementation relies on the \fBLINK_OPTIONS\fP property to check the specified flag. The \fBLINKER:\fP prefix, as described in the \fBtarget_link_options()\fP command, can be used as well. .sp A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the link flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since the \fBtry_compile()\fP command forwards flags from variables like \fBCMAKE__FLAGS\fP, unknown flags in such variables may cause a false negative for this check. .UNINDENT .UNINDENT .SS CheckOBJCCompilerFlag .sp New in version 3.16. .sp Check whether the Objective\-C compiler supports a given flag. .INDENT 0.0 .TP .B check_objc_compiler_flag .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_objc_compiler_flag( ) .ft P .fi .UNINDENT .UNINDENT .sp Check that the \fB\fP is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry named \fB\fP\&. .UNINDENT .sp This command temporarily sets the \fBCMAKE_REQUIRED_DEFINITIONS\fP variable and calls the \fBcheck_objc_source_compiles\fP macro from the \fBCheckOBJCSourceCompiles\fP module. See documentation of that module for a listing of variables that can otherwise modify the build. .sp A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since the \fBtry_compile()\fP command forwards flags from variables like \fBCMAKE_OBJC_FLAGS\fP, unknown flags in such variables may cause a false negative for this check. .UNINDENT .UNINDENT .SS CheckOBJCSourceCompiles .sp New in version 3.16. .sp Check if given Objective\-C source compiles and links into an executable. .INDENT 0.0 .TP .B check_objc_source_compiles .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_objc_source_compiles( [FAIL_REGEX [...]]) .ft P .fi .UNINDENT .UNINDENT .sp Check that the source supplied in \fB\fP can be compiled as a Objectie\-C source file and linked as an executable (so it must contain at least a \fBmain()\fP function). The result will be stored in the internal cache variable specified by \fB\fP, with a boolean true value for success and boolean false for failure. If \fBFAIL_REGEX\fP is provided, then failure is determined by checking if anything in the output matches any of the specified regular expressions. .sp The underlying check is performed by the \fBtry_compile()\fP command. The compile and link commands can be influenced by setting any of the following variables prior to calling \fBcheck_objc_source_compiles()\fP: .INDENT 7.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP Additional flags to pass to the compiler. Note that the contents of \fBCMAKE_OBJC_FLAGS\fP and its associated configuration\-specific variable are automatically added to the compiler command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP A ;\-list of compiler definitions of the form \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by \fB\fP will also be added automatically. .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP A ;\-list of header search paths to pass to the compiler. These will be the only header search paths used by \fBtry_compile()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP directory property will be ignored. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP A ;\-list of options to add to the link command (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_QUIET\fP If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. .UNINDENT .sp The check is only performed once, with the result cached in the variable named by \fB\fP\&. Every subsequent CMake run will re\-use this cached value rather than performing the check again, even if the \fB\fP changes. In order to force the check to be re\-evaluated, the variable named by \fB\fP must be manually removed from the cache. .UNINDENT .SS CheckOBJCSourceRuns .sp New in version 3.16. .sp Check if given Objective\-C source compiles and links into an executable and can subsequently be run. .INDENT 0.0 .TP .B check_objc_source_runs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_objc_source_runs( ) .ft P .fi .UNINDENT .UNINDENT .sp Check that the source supplied in \fB\fP can be compiled as a Objective\-C source file, linked as an executable and then run. The \fB\fP must contain at least a \fBmain()\fP function. If the \fB\fP could be built and run successfully, the internal cache variable specified by \fB\fP will be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message). .sp The underlying check is performed by the \fBtry_run()\fP command. The compile and link commands can be influenced by setting any of the following variables prior to calling \fBcheck_objc_source_runs()\fP: .INDENT 7.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP Additional flags to pass to the compiler. Note that the contents of \fBCMAKE_OBJC_FLAGS\fP and its associated configuration\-specific variable are automatically added to the compiler command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP A ;\-list of compiler definitions of the form \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by \fB\fP will also be added automatically. .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP A ;\-list of header search paths to pass to the compiler. These will be the only header search paths used by \fBtry_run()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP directory property will be ignored. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP A ;\-list of options to add to the link command (see \fBtry_run()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_run()\fP for further details). .TP .B \fBCMAKE_REQUIRED_QUIET\fP If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. .UNINDENT .sp The check is only performed once, with the result cached in the variable named by \fB\fP\&. Every subsequent CMake run will re\-use this cached value rather than performing the check again, even if the \fB\fP changes. In order to force the check to be re\-evaluated, the variable named by \fB\fP must be manually removed from the cache. .UNINDENT .SS CheckOBJCXXCompilerFlag .sp New in version 3.16. .sp Check whether the Objective\-C++ compiler supports a given flag. .INDENT 0.0 .TP .B check_objcxx_compiler_flag .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_objcxx_compiler_flag( ) .ft P .fi .UNINDENT .UNINDENT .sp Check that the \fB\fP is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry named \fB\fP\&. .UNINDENT .sp This command temporarily sets the \fBCMAKE_REQUIRED_DEFINITIONS\fP variable and calls the \fBcheck_objcxx_source_compiles\fP macro from the \fBCheckOBJCXXSourceCompiles\fP module. See documentation of that module for a listing of variables that can otherwise modify the build. .sp A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since the \fBtry_compile()\fP command forwards flags from variables like \fBCMAKE_OBJCXX_FLAGS\fP, unknown flags in such variables may cause a false negative for this check. .UNINDENT .UNINDENT .SS CheckOBJCXXSourceCompiles .sp New in version 3.16. .sp Check if given Objective\-C++ source compiles and links into an executable. .INDENT 0.0 .TP .B check_objcxx_source_compiles .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_objcxx_source_compiles( [FAIL_REGEX [...]]) .ft P .fi .UNINDENT .UNINDENT .sp Check that the source supplied in \fB\fP can be compiled as a Objective\-C++ source file and linked as an executable (so it must contain at least a \fBmain()\fP function). The result will be stored in the internal cache variable specified by \fB\fP, with a boolean true value for success and boolean false for failure. If \fBFAIL_REGEX\fP is provided, then failure is determined by checking if anything in the output matches any of the specified regular expressions. .sp The underlying check is performed by the \fBtry_compile()\fP command. The compile and link commands can be influenced by setting any of the following variables prior to calling \fBcheck_objcxx_source_compiles()\fP: .INDENT 7.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP Additional flags to pass to the compiler. Note that the contents of \fBCMAKE_OBJCXX_FLAGS\fP and its associated configuration\-specific variable are automatically added to the compiler command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP A ;\-list of compiler definitions of the form \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by \fB\fP will also be added automatically. .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP A ;\-list of header search paths to pass to the compiler. These will be the only header search paths used by \fBtry_compile()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP directory property will be ignored. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP A ;\-list of options to add to the link command (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_QUIET\fP If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. .UNINDENT .sp The check is only performed once, with the result cached in the variable named by \fB\fP\&. Every subsequent CMake run will re\-use this cached value rather than performing the check again, even if the \fB\fP changes. In order to force the check to be re\-evaluated, the variable named by \fB\fP must be manually removed from the cache. .UNINDENT .SS CheckOBJCXXSourceRuns .sp New in version 3.16. .sp Check if given Objective\-C++ source compiles and links into an executable and can subsequently be run. .INDENT 0.0 .TP .B check_objcxx_source_runs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_objcxx_source_runs( ) .ft P .fi .UNINDENT .UNINDENT .sp Check that the source supplied in \fB\fP can be compiled as a Objective\-C++ source file, linked as an executable and then run. The \fB\fP must contain at least a \fBmain()\fP function. If the \fB\fP could be built and run successfully, the internal cache variable specified by \fB\fP will be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message). .sp The underlying check is performed by the \fBtry_run()\fP command. The compile and link commands can be influenced by setting any of the following variables prior to calling \fBcheck_objcxx_source_runs()\fP: .INDENT 7.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP Additional flags to pass to the compiler. Note that the contents of \fBCMAKE_OBJCXX_FLAGS\fP and its associated configuration\-specific variable are automatically added to the compiler command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP A ;\-list of compiler definitions of the form \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by \fB\fP will also be added automatically. .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP A ;\-list of header search paths to pass to the compiler. These will be the only header search paths used by \fBtry_run()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP directory property will be ignored. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP A ;\-list of options to add to the link command (see \fBtry_run()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_run()\fP for further details). .TP .B \fBCMAKE_REQUIRED_QUIET\fP If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. .UNINDENT .sp The check is only performed once, with the result cached in the variable named by \fB\fP\&. Every subsequent CMake run will re\-use this cached value rather than performing the check again, even if the \fB\fP changes. In order to force the check to be re\-evaluated, the variable named by \fB\fP must be manually removed from the cache. .UNINDENT .SS CheckPIESupported .sp New in version 3.14. .sp Check whether the linker supports Position Independent Code (PIE) or No Position Independent Code (NO_PIE) for executables. Use this to ensure that the \fBPOSITION_INDEPENDENT_CODE\fP target property for executables will be honored at link time. .INDENT 0.0 .TP .B check_pie_supported .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_pie_supported([OUTPUT_VARIABLE ] [LANGUAGES ...]) .ft P .fi .UNINDENT .UNINDENT .sp Options are: .INDENT 7.0 .TP .B \fBOUTPUT_VARIABLE \fP Set \fB\fP 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. .TP .B \fBLANGUAGES ...\fP Check the linkers used for each of the specified languages. If this option is not provided, the command checks all enabled languages. .sp \fBC\fP, \fBCXX\fP, \fBFortran\fP are supported. .sp New in version 3.23: \fBOBJC\fP, \fBOBJCXX\fP, \fBCUDA\fP, and \fBHIP\fP are supported. .UNINDENT .UNINDENT .sp It makes no sense to use this module when \fBCMP0083\fP is set to \fBOLD\fP, so the command will return an error in this case. See policy \fBCMP0083\fP for details. .SS Variables .sp For each language checked, two boolean cache variables are defined. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBCMAKE__LINK_PIE_SUPPORTED\fP Set to true if \fBPIE\fP is supported by the linker and false otherwise. .TP .B \fBCMAKE__LINK_NO_PIE_SUPPORTED\fP Set to true if \fBNO_PIE\fP is supported by the linker and false otherwise. .UNINDENT .UNINDENT .UNINDENT .SS Examples .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C check_pie_supported() set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Retrieve any error message. check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C) set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) if(NOT CMAKE_C_LINK_PIE_SUPPORTED) message(WARNING "PIE is not supported at link time: ${output}.\en" "PIE link options will not be passed to linker.") endif() .ft P .fi .UNINDENT .UNINDENT .SS CheckPrototypeDefinition .sp Check if the prototype we expect is correct. .INDENT 0.0 .TP .B check_prototype_definition .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE) .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C FUNCTION \- The name of the function (used to check if prototype exists) PROTOTYPE\- The prototype to check. RETURN \- The return value of the function. HEADER \- The header files required. VARIABLE \- The variable to store the result. Will be created as an internal cache variable. .ft P .fi .UNINDENT .UNINDENT .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_prototype_definition(getpwent_r "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)" "NULL" "unistd.h;pwd.h" SOLARIS_GETPWENT_R) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp The following variables may be set before calling this function to modify the way the check is run: .INDENT 0.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP string of compile command line flags. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP list of macros to define (\-DFOO=bar). .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP list of include directories. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14: list of options to pass to link command. .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP list of libraries to link. .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1: execute quietly without messages. .UNINDENT .SS CheckSourceCompiles .sp New in version 3.19. .sp Check if given source compiles and links into an executable. .INDENT 0.0 .TP .B check_source_compiles .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_source_compiles( [FAIL_REGEX [...]] [SRC_EXT ]) .ft P .fi .UNINDENT .UNINDENT .sp Check that the source supplied in \fB\fP can be compiled as a source file for the requested language and linked as an executable (so it must contain at least a \fBmain()\fP function). The result will be stored in the internal cache variable specified by \fB\fP, with a boolean true value for success and boolean false for failure. If \fBFAIL_REGEX\fP is provided, then failure is determined by checking if anything in the output matches any of the specified regular expressions. .sp By default, the test source file will be given a file extension that matches the requested language. The \fBSRC_EXT\fP option can be used to override this with \fB\&.\fP instead. .sp The underlying check is performed by the \fBtry_compile()\fP command. The compile and link commands can be influenced by setting any of the following variables prior to calling \fBcheck_source_compiles()\fP: .INDENT 7.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP Additional flags to pass to the compiler. Note that the contents of \fBCMAKE__FLAGS\fP and its associated configuration\-specific variable are automatically added to the compiler command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP A ;\-list of compiler definitions of the form \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by \fB\fP will also be added automatically. .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP A ;\-list of header search paths to pass to the compiler. These will be the only header search paths used by \fBtry_compile()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP directory property will be ignored. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP A ;\-list of options to add to the link command (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_compile()\fP for further details). .TP .B \fBCMAKE_REQUIRED_QUIET\fP If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. .UNINDENT .sp The check is only performed once, with the result cached in the variable named by \fB\fP\&. Every subsequent CMake run will re\-use this cached value rather than performing the check again, even if the \fB\fP changes. In order to force the check to be re\-evaluated, the variable named by \fB\fP must be manually removed from the cache. .UNINDENT .SS CheckSourceRuns .sp New in version 3.19. .sp Check if given source compiles and links into an executable and can subsequently be run. .INDENT 0.0 .TP .B check_source_runs .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_source_runs( [SRC_EXT ]) .ft P .fi .UNINDENT .UNINDENT .sp Check that the source supplied in \fB\fP can be compiled as a source file for the requested language, linked as an executable and then run. The \fB\fP must contain at least a \fBmain()\fP function. If the \fB\fP could be built and run successfully, the internal cache variable specified by \fB\fP will be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message). .sp By default, the test source file will be given a file extension that matches the requested language. The \fBSRC_EXT\fP option can be used to override this with \fB\&.\fP instead. .sp The underlying check is performed by the \fBtry_run()\fP command. The compile and link commands can be influenced by setting any of the following variables prior to calling \fBcheck_objc_source_runs()\fP: .INDENT 7.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP Additional flags to pass to the compiler. Note that the contents of \fBCMAKE_OBJC_FLAGS\fP and its associated configuration\-specific variable are automatically added to the compiler command before the contents of \fBCMAKE_REQUIRED_FLAGS\fP\&. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP A ;\-list of compiler definitions of the form \fB\-DFOO\fP or \fB\-DFOO=bar\fP\&. A definition for the name specified by \fB\fP will also be added automatically. .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP A ;\-list of header search paths to pass to the compiler. These will be the only header search paths used by \fBtry_run()\fP, i.e. the contents of the \fBINCLUDE_DIRECTORIES\fP directory property will be ignored. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP A ;\-list of options to add to the link command (see \fBtry_run()\fP for further details). .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP A ;\-list of libraries to add to the link command. These can be the name of system libraries or they can be Imported Targets (see \fBtry_run()\fP for further details). .TP .B \fBCMAKE_REQUIRED_QUIET\fP If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. .UNINDENT .sp The check is only performed once, with the result cached in the variable named by \fB\fP\&. Every subsequent CMake run will re\-use this cached value rather than performing the check again, even if the \fB\fP changes. In order to force the check to be re\-evaluated, the variable named by \fB\fP must be manually removed from the cache. .UNINDENT .SS CheckStructHasMember .sp Check if the given struct or class has the specified member variable .INDENT 0.0 .TP .B CHECK_STRUCT_HAS_MEMBER .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C CHECK_STRUCT_HAS_MEMBER( [LANGUAGE ]) .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \- the name of the struct or class you are interested in \- the member which existence you want to check \- the header(s) where the prototype should be declared \- variable to store the result \- the compiler to use (C or CXX) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp The following variables may be set before calling this macro to modify the way the check is run: .INDENT 0.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP string of compile command line flags. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP list of macros to define (\-DFOO=bar). .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP list of include directories. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14: list of options to pass to link command. .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP list of libraries to link. .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1: execute quietly without messages. .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h HAVE_TIMEVAL_TV_SEC LANGUAGE C) .ft P .fi .UNINDENT .UNINDENT .SS CheckSymbolExists .sp Provides a macro to check if a symbol exists as a function, variable, or macro in \fBC\fP\&. .INDENT 0.0 .TP .B check_symbol_exists .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_symbol_exists( ) .ft P .fi .UNINDENT .UNINDENT .sp Check that the \fB\fP is available after including given header \fB\fP and store the result in a \fB\fP\&. Specify the list of files in one argument as a semicolon\-separated list. \fB\fP will be created as an internal cache variable. .UNINDENT .sp If the header files define the symbol as a macro it is considered available and assumed to work. If the header files declare the symbol as a function or variable then the symbol must also be available for linking (so intrinsics may not be detected). If the symbol is a type, enum value, or intrinsic it will not be recognized (consider using \fBCheckTypeSize\fP or \fBCheckSourceCompiles\fP). If the check needs to be done in C++, consider using \fBCheckCXXSymbolExists\fP instead. .sp The following variables may be set before calling this macro to modify the way the check is run: .INDENT 0.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP string of compile command line flags. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP a ;\-list of macros to define (\-DFOO=bar). .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP a ;\-list of header search paths to pass to the compiler. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14: a ;\-list of options to add to the link command. .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP a ;\-list of libraries to add to the link command. See policy \fBCMP0075\fP\&. .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1: execute quietly without messages. .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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) .ft P .fi .UNINDENT .UNINDENT .SS CheckTypeSize .sp Check sizeof a type .INDENT 0.0 .TP .B check_type_size .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C check_type_size( [BUILTIN_TYPES_ONLY] [LANGUAGE ]) .ft P .fi .UNINDENT .UNINDENT .sp Check if the type exists and determine its size. Results are reported in the following variables: .INDENT 7.0 .TP .B \fBHAVE_\fP Holds a true or false value indicating whether the type exists. .TP .B \fB\fP Holds one of the following values: .INDENT 7.0 .TP .B \fB\fP Type has non\-zero size \fB\fP\&. .TP .B \fB0\fP Type has architecture\-dependent size. This may occur when \fBCMAKE_OSX_ARCHITECTURES\fP has multiple architectures. In this case \fB_CODE\fP contains C preprocessor tests mapping from each architecture macro to the corresponding type size. The list of architecture macros is stored in \fB_KEYS\fP, and the value for each key is stored in \fB\-\fP\&. .TP .B "" (empty string) Type does not exist. .UNINDENT .TP .B \fB_CODE\fP Holds C preprocessor code to define the macro \fB\fP to the size of the type, or to leave the macro undefined if the type does not exist. .UNINDENT .sp The options are: .sp \fBBUILTIN_TYPES_ONLY\fP .INDENT 7.0 .INDENT 3.5 Support only compiler\-builtin types. If \fInot\fP given, the macro checks for headers \fB\fP, \fB\fP, and \fB\fP, and saves results in \fBHAVE_SYS_TYPES_H\fP, \fBHAVE_STDINT_H\fP, and \fBHAVE_STDDEF_H\fP\&. The type size check automatically includes the available headers, thus supporting checks of types defined in the headers. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B \fBLANGUAGE \fP Use the \fB\fP compiler to perform the check. Acceptable values are \fBC\fP and \fBCXX\fP\&. .UNINDENT .UNINDENT .sp Despite the name of the macro you may use it to check the size of more complex expressions, too. To check e.g. for the size of a struct member you can do something like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C check_type_size("((struct something*)0)\->member" SIZEOF_MEMBER) .ft P .fi .UNINDENT .UNINDENT .sp The following variables may be set before calling this macro to modify the way the check is run: .INDENT 0.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP string of compile command line flags. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP list of macros to define (\-DFOO=bar). .TP .B \fBCMAKE_REQUIRED_INCLUDES\fP list of include directories. .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14: list of options to pass to link command. .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP list of libraries to link. .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1: execute quietly without messages. .TP .B \fBCMAKE_EXTRA_INCLUDE_FILES\fP list of extra headers to include. .UNINDENT .SS CheckVariableExists .sp Check if the variable exists. .INDENT 0.0 .TP .B CHECK_VARIABLE_EXISTS .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C CHECK_VARIABLE_EXISTS(VAR VARIABLE) .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C VAR \- the name of the variable VARIABLE \- variable to store the result Will be created as an internal cache variable. .ft P .fi .UNINDENT .UNINDENT .sp This macro is only for \fBC\fP variables. .UNINDENT .sp The following variables may be set before calling this macro to modify the way the check is run: .INDENT 0.0 .TP .B \fBCMAKE_REQUIRED_FLAGS\fP string of compile command line flags. .TP .B \fBCMAKE_REQUIRED_DEFINITIONS\fP list of macros to define (\-DFOO=bar). .TP .B \fBCMAKE_REQUIRED_LINK_OPTIONS\fP New in version 3.14: list of options to pass to link command. .TP .B \fBCMAKE_REQUIRED_LIBRARIES\fP list of libraries to link. .TP .B \fBCMAKE_REQUIRED_QUIET\fP New in version 3.1: execute quietly without messages. .UNINDENT .SS CMakeAddFortranSubdirectory .sp Add a fortran\-only subdirectory, find a fortran compiler, and build. .sp The \fBcmake_add_fortran_subdirectory\fP function adds a subdirectory to a project that contains a fortran\-only subproject. The module will check the current compiler and see if it can support fortran. If no fortran compiler is found and the compiler is MSVC, then this module will find the MinGW gfortran. It will then use an external project to build with the MinGW tools. It will also create imported targets for the libraries created. This will only work if the fortran code is built into a dll, so \fBBUILD_SHARED_LIBS\fP is turned on in the project. In addition the \fBCMAKE_GNUtoMS\fP option is set to on, so that Microsoft \fB\&.lib\fP files are created. Usage is as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmake_add_fortran_subdirectory( # name of subdirectory PROJECT # project name in subdir top CMakeLists.txt ARCHIVE_DIR # dir where project places .lib files RUNTIME_DIR # dir where project places .dll files LIBRARIES ... # names of library targets to import LINK_LIBRARIES # link interface libraries for LIBRARIES [LINK_LIBS ...]... CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake NO_EXTERNAL_INSTALL # skip installation of external project ) .ft P .fi .UNINDENT .UNINDENT .sp Relative paths in \fBARCHIVE_DIR\fP and \fBRUNTIME_DIR\fP are interpreted with respect to the build directory corresponding to the source directory in which the function is invoked. .sp Limitations: .sp \fBNO_EXTERNAL_INSTALL\fP is required for forward compatibility with a future version that supports installation of the external project binaries during \fBmake install\fP\&. .SS CMakeBackwardCompatibilityCXX .sp define a bunch of backwards compatibility variables .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C CMAKE_ANSI_CXXFLAGS \- flag for ansi c++ CMAKE_HAS_ANSI_STRING_STREAM \- has include(TestForANSIStreamHeaders) include(CheckIncludeFileCXX) include(TestForSTDNamespace) include(TestForANSIForScope) .ft P .fi .UNINDENT .UNINDENT .SS CMakeDependentOption .sp Macro to provide an option dependent on other options. .sp This macro presents an option to the user only if a set of other conditions are true. .INDENT 0.0 .TP .B cmake_dependent_option .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cmake_dependent_option(