diff --git a/Modules/CheckCSourceCompiles.cmake b/Modules/CheckCSourceCompiles.cmake index 79aca932aa..c01b6cffee 100644 --- a/Modules/CheckCSourceCompiles.cmake +++ b/Modules/CheckCSourceCompiles.cmake @@ -5,7 +5,7 @@ CheckCSourceCompiles -------------------- -Check if given C source compiles and links into an executable. +Check once if C source code can be built. .. command:: check_c_source_compiles @@ -14,19 +14,21 @@ Check if given C source compiles and links into an executable. check_c_source_compiles( [FAIL_REGEX [...]]) - Check that the source supplied in ```` can be compiled as a C source - file and linked as an executable (so it must contain at least a ``main()`` - function). The result will be stored in the internal cache variable specified - by ````, with a boolean true value for success and boolean false - for failure. If ``FAIL_REGEX`` is provided, then failure is determined by - checking if anything in the output matches any of the specified regular + Check once that the source supplied in ```` can be built. The result is + stored in the internal cache variable specified by ````, with + boolean ``true`` for success and boolean ``false`` for failure. + + If ``FAIL_REGEX`` is provided, then failure is determined by checking + if anything in the compiler output matches any of the specified regular expressions. - The check is only performed once, with the result cached in the variable named - by ````. Every subsequent CMake run will reuse this cached value - rather than performing the check again, even if the ```` changes. In - order to force the check to be re-evaluated, the variable named by - ```` must be manually removed from the cache. + Internally, :command:`try_compile` is used to compile the source. If + :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default), + the source is compiled and linked as an executable program. If set to + ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all + functions must be declared as usual. + + See also :command:`check_source_runs` to run compiled source. The compile and link commands can be influenced by setting any of the following variables prior to calling ``check_c_source_compiles()``: diff --git a/Modules/CheckCXXSourceCompiles.cmake b/Modules/CheckCXXSourceCompiles.cmake index 7531236e8c..7c03c4ac3f 100644 --- a/Modules/CheckCXXSourceCompiles.cmake +++ b/Modules/CheckCXXSourceCompiles.cmake @@ -5,7 +5,7 @@ CheckCXXSourceCompiles ---------------------- -Check if given C++ source compiles and links into an executable. +Check once if C++ source code can be built. .. command:: check_cxx_source_compiles @@ -14,19 +14,21 @@ Check if given C++ source compiles and links into an executable. check_cxx_source_compiles( [FAIL_REGEX [...]]) - Check that the source supplied in ```` can be compiled as a C++ source - file and linked as an executable (so it must contain at least a ``main()`` - function). The result will be stored in the internal cache variable specified - by ````, with a boolean true value for success and boolean false - for failure. If ``FAIL_REGEX`` is provided, then failure is determined by - checking if anything in the output matches any of the specified regular + Check once that the source supplied in ```` can be built. The result is + stored in the internal cache variable specified by ````, with + boolean ``true`` for success and boolean ``false`` for failure. + + If ``FAIL_REGEX`` is provided, then failure is determined by checking + if anything in the compiler output matches any of the specified regular expressions. - The check is only performed once, with the result cached in the variable named - by ````. Every subsequent CMake run will reuse this cached value - rather than performing the check again, even if the ```` changes. In - order to force the check to be re-evaluated, the variable named by - ```` must be manually removed from the cache. + Internally, :command:`try_compile` is used to compile the source. If + :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default), + the source is compiled and linked as an executable program. If set to + ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all + functions must be declared as usual. + + See also :command:`check_source_runs` to run compiled source. The compile and link commands can be influenced by setting any of the following variables prior to calling ``check_cxx_source_compiles()``: diff --git a/Modules/CheckFortranSourceCompiles.cmake b/Modules/CheckFortranSourceCompiles.cmake index ed374ef116..4cbe67ae3a 100644 --- a/Modules/CheckFortranSourceCompiles.cmake +++ b/Modules/CheckFortranSourceCompiles.cmake @@ -7,7 +7,7 @@ CheckFortranSourceCompiles .. versionadded:: 3.1 -Check if given Fortran source compiles and links into an executable. +Check once if Fortran source code can be built. .. command:: check_fortran_source_compiles @@ -18,40 +18,25 @@ Check if given Fortran source compiles and links into an executable. [SRC_EXT ] ) - Checks that the source supplied in ```` can be compiled as a Fortran - source file and linked as an executable. The ```` must be a Fortran - ``program``. - - .. code-block:: cmake - - check_fortran_source_compiles("program test - error stop - end program" - HAVE_ERROR_STOP - SRC_EXT .F90) - - This command can help avoid costly build processes when a compiler lacks support - for a necessary feature, or a particular vendor library is not compatible with - the Fortran compiler version being used. This generate-time check may advise the - user of such before the main build process. See also the - :command:`check_fortran_source_runs` command to run the compiled code. - - The result will be stored in the internal cache - variable ````, with a boolean true value for success and boolean - false for failure. + Check once that the source supplied in ```` can be built. The result is + stored in the internal cache variable specified by ````, with + boolean ``true`` for success and boolean ``false`` for failure. If ``FAIL_REGEX`` is provided, then failure is determined by checking - if anything in the output matches any of the specified regular expressions. + if anything in the compiler output matches any of the specified regular + expressions. By default, the test source file will be given a ``.F`` file extension. The ``SRC_EXT`` option can be used to override this with ``.`` instead-- ``.F90`` is a typical choice. - The check is only performed once, with the result cached in the variable named - by ````. Every subsequent CMake run will reuse this cached value - rather than performing the check again, even if the ```` changes. In - order to force the check to be re-evaluated, the variable named by - ```` must be manually removed from the cache. + See also :command:`check_source_runs` to run compiled source. + + Internally, :command:`try_compile` is used to compile the source. If + :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default), + the source is compiled and linked as an executable program. If set to + ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all + functions must be declared as usual. The compile and link commands can be influenced by setting any of the following variables prior to calling ``check_fortran_source_compiles()``: diff --git a/Modules/CheckOBJCSourceCompiles.cmake b/Modules/CheckOBJCSourceCompiles.cmake index bc0cac1a15..c6e09db238 100644 --- a/Modules/CheckOBJCSourceCompiles.cmake +++ b/Modules/CheckOBJCSourceCompiles.cmake @@ -7,7 +7,7 @@ CheckOBJCSourceCompiles .. versionadded:: 3.16 -Check if given Objective-C source compiles and links into an executable. +Check once if Objective-C source can be built. .. command:: check_objc_source_compiles @@ -16,19 +16,21 @@ Check if given Objective-C source compiles and links into an executable. check_objc_source_compiles( [FAIL_REGEX [...]]) - Check that the source supplied in ```` can be compiled as a Objectie-C source - file and linked as an executable (so it must contain at least a ``main()`` - function). The result will be stored in the internal cache variable specified - by ````, with a boolean true value for success and boolean false - for failure. If ``FAIL_REGEX`` is provided, then failure is determined by - checking if anything in the output matches any of the specified regular + Check once that the source supplied in ```` can be built. The result is + stored in the internal cache variable specified by ````, with + boolean ``true`` for success and boolean ``false`` for failure. + + If ``FAIL_REGEX`` is provided, then failure is determined by checking + if anything in the compiler output matches any of the specified regular expressions. - The check is only performed once, with the result cached in the variable named - by ````. Every subsequent CMake run will reuse this cached value - rather than performing the check again, even if the ```` changes. In - order to force the check to be re-evaluated, the variable named by - ```` must be manually removed from the cache. + Internally, :command:`try_compile` is used to compile the source. If + :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default), + the source is compiled and linked as an executable program. If set to + ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all + functions must be declared as usual. + + See also :command:`check_source_runs` to run compiled source. The compile and link commands can be influenced by setting any of the following variables prior to calling ``check_objc_source_compiles()`` diff --git a/Modules/CheckOBJCXXSourceCompiles.cmake b/Modules/CheckOBJCXXSourceCompiles.cmake index 366d7d5cd0..4a18c21346 100644 --- a/Modules/CheckOBJCXXSourceCompiles.cmake +++ b/Modules/CheckOBJCXXSourceCompiles.cmake @@ -7,7 +7,7 @@ CheckOBJCXXSourceCompiles .. versionadded:: 3.16 -Check if given Objective-C++ source compiles and links into an executable. +Check once if Objective-C++ source can be built. .. command:: check_objcxx_source_compiles @@ -16,19 +16,21 @@ Check if given Objective-C++ source compiles and links into an executable. check_objcxx_source_compiles( [FAIL_REGEX [...]]) - Check that the source supplied in ```` can be compiled as a Objective-C++ source - file and linked as an executable (so it must contain at least a ``main()`` - function). The result will be stored in the internal cache variable specified - by ````, with a boolean true value for success and boolean false - for failure. If ``FAIL_REGEX`` is provided, then failure is determined by - checking if anything in the output matches any of the specified regular + Check once that the source supplied in ```` can be built. The result is + stored in the internal cache variable specified by ````, with + boolean ``true`` for success and boolean ``false`` for failure. + + If ``FAIL_REGEX`` is provided, then failure is determined by checking + if anything in the compiler output matches any of the specified regular expressions. - The check is only performed once, with the result cached in the variable named - by ````. Every subsequent CMake run will reuse this cached value - rather than performing the check again, even if the ```` changes. In - order to force the check to be re-evaluated, the variable named by - ```` must be manually removed from the cache. + Internally, :command:`try_compile` is used to compile the source. If + :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default), + the source is compiled and linked as an executable program. If set to + ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all + functions must be declared as usual. + + See also :command:`check_source_runs` to run compiled source. The compile and link commands can be influenced by setting any of the following variables prior to calling ``check_objcxx_source_compiles()`` diff --git a/Modules/CheckSourceCompiles.cmake b/Modules/CheckSourceCompiles.cmake index af905a4e6e..b79726a66b 100644 --- a/Modules/CheckSourceCompiles.cmake +++ b/Modules/CheckSourceCompiles.cmake @@ -8,7 +8,7 @@ CheckSourceCompiles .. versionadded:: 3.19 -Check if given source compiles and links into an executable. +Check once if source code can be built for a given language. .. command:: check_source_compiles @@ -18,40 +18,50 @@ Check if given source compiles and links into an executable. [FAIL_REGEX [...]] [SRC_EXT ]) - Check that the source supplied in ```` can be compiled as a source - file for the requested language and linked as an executable. The result - will be stored in the internal cache variable specified by ````, - with a boolean true value for success and boolean false for failure. If - ``FAIL_REGEX`` is provided, then failure is determined by checking if - anything in the compiler output matches any of the specified regular + Check once that the source supplied in ```` can be built for code + language ````. The result is stored in the internal cache variable + specified by ````, with boolean ``true`` for success and + boolean ``false`` for failure. + + If ``FAIL_REGEX`` is provided, then failure is determined by checking + if anything in the compiler output matches any of the specified regular expressions. By default, the test source file will be given a file extension that matches the requested language. The ``SRC_EXT`` option can be used to override this with ``.`` instead. - The ```` must contain a valid main program. For example: + The C example checks if the compiler supports the ``noreturn`` attribute: .. code-block:: cmake + set(CMAKE_TRY_COMPILE_TARGET_TYPE "STATIC_LIBRARY") + check_source_compiles(C - "#include - #include - noreturn void f(){ exit(0); } - int main(void) { f(); return 1; }" + "#if !__has_c_attribute(noreturn) + #error \"No noreturn attribute\" + #endif" HAVE_NORETURN) - check_source_compiles(Fortran - "program test - error stop - end program" - HAVE_ERROR_STOP) + The Fortran example checks if the compiler supports the ``pure`` procedure + attribute: - The check is only performed once, with the result cached in the variable - named by ````. Every subsequent CMake run will reuse this cached - value rather than performing the check again, even if the ```` changes. - In order to force the check to be re-evaluated, the variable named by - ```` must be manually removed from the cache. + .. code-block:: cmake + + set(CMAKE_TRY_COMPILE_TARGET_TYPE "STATIC_LIBRARY") + + check_source_compiles(Fortran + "pure subroutine foo() + end subroutine" + HAVE_PURE) + + Internally, :command:`try_compile` is used to compile the source. If + :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default), + the source is compiled and linked as an executable program. If set to + ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all + functions must be declared as usual. + + See also :command:`check_source_runs` to run compiled source. The compile and link commands can be influenced by setting any of the following variables prior to calling ``check_source_compiles()``: