# 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()

## See Also

- The `CheckSourceCompiles` module to check whether a source code can be built.