CheckSourceRuns

Added in version 3.19.

This module provides a command to check whether a source code can be built and run.

Load this module in a CMake project with:

include(CheckSourceRuns)

Commands

This module provides the following command:

check_source_runs

Checks once whether the given source code compiles and links into an executable that can subsequently be run:

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

This command checks once that the <lang> source code supplied in <code> can be built, linked as an executable, and then run. The result of the check is stored in the internal cache variable specified by <variable>.

The arguments are:

<lang>: The programming language of the source <code> to check. Supported languages are: C, CXX, CUDA, Fortran, HIP, OBJC, and OBJCXX.

Added in version 3.21: Support for HIP language.
<code>: The source code to be tested. It must contain a valid source program. For example, it must contain at least a main() function (in C/C++), or a program unit (in Fortran).
<variable>: Name of the internal cache variable with the result of the check. If the code builds and runs with exit code 0, success is indicated by a boolean true value. Failure to build or run is indicated by a boolean false value, such as an empty string or an error message.
SRC_EXT <extension>: By default, the internal test source file used for the check will be given a file extension that matches the requested language (e.g., .c for C, .cxx for C++, .F90 for Fortran, etc.). This option can be used to override this with the .<extension> instead.

Variables Affecting the Check

The following variables may be set before calling this command to modify the way the check is run:

CMAKE_REQUIRED_FLAGS: A space-separated string of additional flags to pass to the compiler. A semicolon-separated list will not work. The contents of CMAKE_<LANG>_FLAGS and its associated configuration-specific CMAKE_<LANG>_FLAGS_<CONFIG> variables are automatically prepended to the compiler command before the contents of this variable.

CMAKE_REQUIRED_DEFINITIONS: A semicolon-separated list of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically.

CMAKE_REQUIRED_INCLUDES: A semicolon-separated list of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES directory property will be ignored.

CMAKE_REQUIRED_LINK_OPTIONS: Added in version 3.14.

A semicolon-separated list of options to add to the link command (see try_compile() for further details).

CMAKE_REQUIRED_LIBRARIES: A semicolon-separated list of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets (see try_compile() for further details).

CMAKE_REQUIRED_LINK_DIRECTORIES: Added in version 3.31.

A semicolon-separated list of library search paths to pass to the linker (see try_compile() for further details).

CMAKE_REQUIRED_QUIET: Added in version 3.1.

If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed.

Examples

Example: Basic Usage

The following example demonstrates how to use this module to check whether the C source code is supported and operational at runtime. The result of the check is stored in the internal cache variable HAVE_NORETURN.

include(CheckSourceRuns)

check_source_runs(C "
  #include <stdlib.h>
  #include <stdnoreturn.h>
  noreturn void f(){ exit(0); }
  int main(void) { f(); return 1; }
" HAVE_NORETURN)

Example: Checking Fortran Code

Checking if Fortran source code runs successfully:

include(CheckSourceRuns)

check_source_runs(Fortran "
  program test
  real :: x[*]
  call co_sum(x)
  end program
" HAVE_COARRAY)

Example: Checking C++ Code With Bracket Argument

The following example demonstrates how to check whether the C++ standard library is functional and std::vector works at runtime. If the source compiles, links, and runs successfully, internal cache variable HAVE_WORKING_STD_VECTOR will be set to boolean true value. Code is supplied using Bracket Argument for easier embedded quotes handling:

include(CheckSourceRuns)

check_source_runs(CXX [[
  #include <iostream>
  #include <vector>

  int main()
  {
    std::vector<int> v = {1, 2, 3};
    if (v.size() != 3) return 1;
    std::cout << "Vector works correctly." << std::endl;
    return 0;
  }
]] HAVE_WORKING_STD_VECTOR)

Example: Isolated Check

In the following example, this module is used in combination with the CMakePushCheckState module to modify required compile definitions and libraries when checking whether the C function sched_getcpu() is supported and operational at runtime. For example, on some systems, the sched_getcpu() function may be available at compile time but not actually implemented by the kernel. In such cases, it returns -1 and sets errno to ENOSYS. This check verifies that sched_getcpu() runs successfully and stores a boolean result in the internal cache variable HAVE_SCHED_GETCPU.

include(CheckSourceRuns)
include(CMakePushCheckState)

cmake_push_check_state(RESET)
  set(CMAKE_REQUIRED_DEFINITIONS -D_GNU_SOURCE)

  if(CMAKE_SYSTEM_NAME STREQUAL "Haiku")
    set(CMAKE_REQUIRED_LIBRARIES gnu)
  endif()

  check_source_runs(C "
    #include <sched.h>
    int main(void)
    {
      if (sched_getcpu() == -1) {
        return 1;
      }
      return 0;
    }
  " HAVE_SCHED_GETCPU)
cmake_pop_check_state()