# CheckSourceCompiles

Added in version 3.19.

This module provides a command that checks whether a source code can be built for a given language.

Load this module in a CMake project with:

    include(CheckSourceCompiles)

## Commands

This module provides the following command:

check_source_compiles

  Checks once whether the given source code can be built for the given language:

      check_source_compiles(
        <lang>
        <code>
        <variable>
        [FAIL_REGEX <regexes>...]
        [SRC_EXT <extension>]
      )

  This command checks once that the source supplied in `<code>` can be compiled (and linked into an executable) for code language `<lang>`. The result of the check is stored in the internal cache variable specified by `<variable>`.

  The arguments are:

  `<lang>`

    Language of the source code to check. Supported languages are: `C`, `CXX`, `CUDA`, `Fortran`, `HIP`, `ISPC`, `OBJC`, `OBJCXX`, and `Swift`.

    Added in version 3.21: Support for `HIP` language.

    Added in version 3.26: Support for `Swift` language.

  `<code>`

    The source code to check. This must be an entire program, as written in a file containing the body block. All symbols used in the source code are expected to be declared as usual in their corresponding headers.

  `<variable>`

    Variable name of an internal cache variable to store the result of the check, with boolean true for success and boolean false for failure.

  `FAIL_REGEX <regexes>...`

    If one or more regular expression patterns are provided, then failure is determined by checking if anything in the compiler output matches any of the specified regular expressions.

  `SRC_EXT <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.

  `CMAKE_TRY_COMPILE_TARGET_TYPE`

    Internally, the `try_compile()` command is used to perform the check, and this variable controls the type of target it creates. If this variable is set to `EXECUTABLE` (the default), the check compiles and links the test source code as an executable program. If set to `STATIC_LIBRARY`, the test source code is compiled but not linked.

## Examples

### Example: Basic Usage

The following example demonstrates how to check whether the C++ compiler supports a specific language feature using this module. In this case, the check verifies if the compiler supports `C++11` lambda expressions. The result is stored in the internal cache variable `HAVE_CXX11_LAMBDAS`:

    include(CheckSourceCompiles)

    check_source_compiles(CXX [[
      int main()
      {
        auto lambda = []() { return 42; };
        return lambda();
      }
    ]] HAVE_CXX11_LAMBDAS)

### Example: Checking Code With Bracket Argument

The following example shows how to check whether the C compiler supports the `noreturn` attribute. Code is supplied using the Bracket Argument for easier embedded quotes handling:

    include(CheckSourceCompiles)

    check_source_compiles(C [[
      #if !__has_c_attribute(noreturn)
      #  error "No noreturn attribute"
      #endif
      int main(void) { return 0; }
    ]] HAVE_NORETURN)

### Example: Performing a Check Without Linking

In the following example, this module is used to perform a compile-only check of Fortran source code, whether the compiler supports the `pure` procedure attribute:

    include(CheckSourceCompiles)

    block()
      set(CMAKE_TRY_COMPILE_TARGET_TYPE "STATIC_LIBRARY")

      check_source_compiles(
        Fortran
        "pure subroutine foo()
        end subroutine"
        HAVE_PURE
      )
    endblock()

### Example: Isolated Check

In the following example, this module is used in combination with the `CMakePushCheckState` module to modify required libraries when checking whether the PostgreSQL `PGVerbosity` enum contains `PQERRORS_SQLSTATE` (available as of PostgreSQL version 12):

    include(CheckSourceCompiles)
    include(CMakePushCheckState)

    find_package(PostgreSQL)

    if(TARGET PostgreSQL::PostgreSQL)
      cmake_push_check_state(RESET)
        set(CMAKE_REQUIRED_LIBRARIES PostgreSQL::PostgreSQL)

        check_source_compiles(C [[
          #include <libpq-fe.h>
          int main(void)
          {
            PGVerbosity e = PQERRORS_SQLSTATE;
            (void)e;
            return 0;
          }
        ]] HAVE_PQERRORS_SQLSTATE)
      cmake_pop_check_state()
    endif()

## See Also

- The `CheckSourceRuns` module to check whether the source code can be built and also run.