code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckIncludeFiles — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckIPOSupported" href="CheckIPOSupported.html" />
    <link rel="prev" title="CheckIncludeFile" href="CheckIncludeFile.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckIncludeFiles

CheckIncludeFiles¶

Provides a macro to check if a list of one or more header files can
be included together.

CHECK_INCLUDE_FILES¶

CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>])

Check if the given <includes> list may be included together
in a source file and store the result in an internal cache
entry named <variable>.  Specify the <includes> argument
as a ;-list of header file names.

If LANGUAGE is set, the specified compiler will be used to perform the
check. Acceptable values are C and CXX. 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.

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

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

See modules CheckIncludeFile and CheckIncludeFileCXX
to check for a single header file in C or CXX languages.

Previous topic

CheckIncludeFile

Next topic

CheckIPOSupported

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckIncludeFiles

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckLanguage — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckLibraryExists" href="CheckLibraryExists.html" />
    <link rel="prev" title="CheckIPOSupported" href="CheckIPOSupported.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckLanguage

CheckLanguage¶

Check whether a language can be enabled by the enable_language()
or project() commands:

check_language¶

check_language(<lang>)

Try enabling language <lang> in a test project and record results
in the cache:

CMAKE_<LANG>_COMPILER

If the language can be enabled, this variable is set to the compiler
that was found.  If the language cannot be enabled, this variable is
set to NOTFOUND.

If this variable is already set, either explicitly or cached by
a previous call, the check is skipped.

CMAKE_<LANG>_HOST_COMPILER

This variable is set when <lang> is CUDA or HIP.

If the check detects an explicit host compiler that is required for
compilation, this variable will be set to that compiler.
If the check detects that no explicit host compiler is needed,
this variable will be cleared.

If this variable is already set, its value is preserved only if
CMAKE_<LANG>_COMPILER is also set.
Otherwise, the check runs and overwrites
CMAKE_<LANG>_HOST_COMPILER with a new result.
Note that CMAKE_<LANG>_HOST_COMPILER documents it should
not be set without also setting
CMAKE_<LANG>_COMPILER to a NVCC compiler.

CMAKE_<LANG>_PLATFORM

This variable is set to the detected GPU platform when <lang> is HIP.

If the variable is already set its value is always preserved. Only compatible values
will be considered for CMAKE_<LANG>_COMPILER.

For example:

check_language(Fortran)
if(CMAKE_Fortran_COMPILER)
  enable_language(Fortran)
else()
  message(STATUS "No Fortran support")
endif()

Previous topic

CheckIPOSupported

Next topic

CheckLibraryExists

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckLanguage

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckLibraryExists — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckLinkerFlag" href="CheckLinkerFlag.html" />
    <link rel="prev" title="CheckLanguage" href="CheckLanguage.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckLibraryExists

CheckLibraryExists¶

Check if the function exists.

CHECK_LIBRARY_EXISTS¶

CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE)

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.

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

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

Previous topic

CheckLanguage

Next topic

CheckLinkerFlag

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckLibraryExists

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckLinkerFlag — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckOBJCCompilerFlag" href="CheckOBJCCompilerFlag.html" />
    <link rel="prev" title="CheckLibraryExists" href="CheckLibraryExists.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckLinkerFlag

CheckLinkerFlag¶

New in version 3.18.

Check whether the compiler supports a given link flag.

check_linker_flag¶

check_linker_flag(<lang> <flag> <var>)

Check that the link <flag> is accepted by the <lang> compiler without
a diagnostic.  Stores the result in an internal cache entry named <var>.

This command temporarily sets the CMAKE_REQUIRED_LINK_OPTIONS variable
and calls the check_source_compiles() command from the
CheckSourceCompiles module.  See that module's documentation
for a listing of variables that can otherwise modify the build.

The underlying implementation relies on the LINK_OPTIONS property
to check the specified flag. The LINKER: prefix, as described in the
target_link_options() command, can be used as well.

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.

Note

Since the try_compile() command forwards flags from variables
like CMAKE_<LANG>_FLAGS, unknown flags in such variables may
cause a false negative for this check.

Previous topic

CheckLibraryExists

Next topic

CheckOBJCCompilerFlag

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckLinkerFlag

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckOBJCCompilerFlag — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckOBJCSourceCompiles" href="CheckOBJCSourceCompiles.html" />
    <link rel="prev" title="CheckLinkerFlag" href="CheckLinkerFlag.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckOBJCCompilerFlag

CheckOBJCCompilerFlag¶

New in version 3.16.

Check whether the Objective-C compiler supports a given flag.

check_objc_compiler_flag¶

check_objc_compiler_flag(<flag> <resultVar>)

Check that the <flag> is accepted by the compiler without
a diagnostic.  Stores the result in an internal cache entry
named <resultVar>.

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.

The check is only performed once, with the result cached in the variable named
by <resultVar>. Every subsequent CMake run will reuse this cached value
rather than performing the check again, even if the <code> changes. In
order to force the check to be re-evaluated, the variable named by
<resultVar> must be manually removed from the cache.

The compile and link commands can be influenced by setting any of the
following variables prior to calling check_objc_compiler_flag()

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

Previous topic

CheckLinkerFlag

Next topic

CheckOBJCSourceCompiles

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckOBJCCompilerFlag

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckOBJCSourceCompiles — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckOBJCSourceRuns" href="CheckOBJCSourceRuns.html" />
    <link rel="prev" title="CheckOBJCCompilerFlag" href="CheckOBJCCompilerFlag.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckOBJCSourceCompiles

CheckOBJCSourceCompiles¶

New in version 3.16.

Check if given Objective-C source compiles and links into an executable.

check_objc_source_compiles¶

check_objc_source_compiles(<code> <resultVar>
                           [FAIL_REGEX <regex1> [<regex2>...]])

Check that the source supplied in <code> 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 <resultVar>, 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
expressions.

The check is only performed once, with the result cached in the variable named
by <resultVar>. Every subsequent CMake run will reuse this cached value
rather than performing the check again, even if the <code> changes. In
order to force the check to be re-evaluated, the variable named by
<resultVar> must be manually removed from the cache.

The compile and link commands can be influenced by setting any of the
following variables prior to calling check_objc_source_compiles()

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

Previous topic

CheckOBJCCompilerFlag

Next topic

CheckOBJCSourceRuns

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckOBJCSourceCompiles

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckOBJCSourceRuns — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckOBJCXXCompilerFlag" href="CheckOBJCXXCompilerFlag.html" />
    <link rel="prev" title="CheckOBJCSourceCompiles" href="CheckOBJCSourceCompiles.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckOBJCSourceRuns

CheckOBJCSourceRuns¶

New in version 3.16.

Check if given Objective-C source compiles and links into an executable and can
subsequently be run.

check_objc_source_runs¶

check_objc_source_runs(<code> <resultVar>)

Check that the source supplied in <code> can be compiled as a Objective-C source
file, linked as an executable and then run. The <code> must contain at
least a main() function. If the <code> could be built and run
successfully, the internal cache variable specified by <resultVar> 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).

The check is only performed once, with the result cached in the variable named
by <resultVar>. Every subsequent CMake run will reuse this cached value
rather than performing the check again, even if the <code> changes. In
order to force the check to be re-evaluated, the variable named by
<resultVar> must be manually removed from the cache.

The compile and link commands can be influenced by setting any of the
following variables prior to calling check_objc_source_runs()

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

Previous topic

CheckOBJCSourceCompiles

Next topic

CheckOBJCXXCompilerFlag

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckOBJCSourceRuns

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckOBJCXXCompilerFlag — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckOBJCXXSourceCompiles" href="CheckOBJCXXSourceCompiles.html" />
    <link rel="prev" title="CheckOBJCSourceRuns" href="CheckOBJCSourceRuns.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckOBJCXXCompilerFlag

CheckOBJCXXCompilerFlag¶

New in version 3.16.

Check whether the Objective-C++ compiler supports a given flag.

check_objcxx_compiler_flag¶

check_objcxx_compiler_flag(<flag> <resultVar>)

Check that the <flag> is accepted by the compiler without
a diagnostic.  Stores the result in an internal cache entry
named <resultVar>.

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.

The check is only performed once, with the result cached in the variable named
by <resultVar>. Every subsequent CMake run will reuse this cached value
rather than performing the check again, even if the <code> changes. In
order to force the check to be re-evaluated, the variable named by
<resultVar> must be manually removed from the cache.

The compile and link commands can be influenced by setting any of the
following variables prior to calling check_objcxx_compiler_flag()

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

Previous topic

CheckOBJCSourceRuns

Next topic

CheckOBJCXXSourceCompiles

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckOBJCXXCompilerFlag

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckOBJCXXSourceCompiles — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckOBJCXXSourceRuns" href="CheckOBJCXXSourceRuns.html" />
    <link rel="prev" title="CheckOBJCXXCompilerFlag" href="CheckOBJCXXCompilerFlag.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckOBJCXXSourceCompiles

CheckOBJCXXSourceCompiles¶

New in version 3.16.

Check if given Objective-C++ source compiles and links into an executable.

check_objcxx_source_compiles¶

check_objcxx_source_compiles(<code> <resultVar>
                             [FAIL_REGEX <regex1> [<regex2>...]])

Check that the source supplied in <code> 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 <resultVar>, 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
expressions.

The check is only performed once, with the result cached in the variable named
by <resultVar>. Every subsequent CMake run will reuse this cached value
rather than performing the check again, even if the <code> changes. In
order to force the check to be re-evaluated, the variable named by
<resultVar> must be manually removed from the cache.

The compile and link commands can be influenced by setting any of the
following variables prior to calling check_objcxx_source_compiles()

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

Previous topic

CheckOBJCXXCompilerFlag

Next topic

CheckOBJCXXSourceRuns

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckOBJCXXSourceCompiles

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckOBJCXXSourceRuns — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckPIESupported" href="CheckPIESupported.html" />
    <link rel="prev" title="CheckOBJCXXSourceCompiles" href="CheckOBJCXXSourceCompiles.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckOBJCXXSourceRuns

CheckOBJCXXSourceRuns¶

New in version 3.16.

Check if given Objective-C++ source compiles and links into an executable and can
subsequently be run.

check_objcxx_source_runs¶

check_objcxx_source_runs(<code> <resultVar>)

Check that the source supplied in <code> can be compiled as a Objective-C++ source
file, linked as an executable and then run. The <code> must contain at
least a main() function. If the <code> could be built and run
successfully, the internal cache variable specified by <resultVar> 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).

The check is only performed once, with the result cached in the variable named
by <resultVar>. Every subsequent CMake run will reuse this cached value
rather than performing the check again, even if the <code> changes. In
order to force the check to be re-evaluated, the variable named by
<resultVar> must be manually removed from the cache.

The compile and link commands can be influenced by setting any of the
following variables prior to calling check_objcxx_source_runs()

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

Previous topic

CheckOBJCXXSourceCompiles

Next topic

CheckPIESupported

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckOBJCXXSourceRuns

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckPIESupported — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckPrototypeDefinition" href="CheckPrototypeDefinition.html" />
    <link rel="prev" title="CheckOBJCXXSourceRuns" href="CheckOBJCXXSourceRuns.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckPIESupported

CheckPIESupported¶

New in version 3.14.

Check whether the linker supports Position Independent Code (PIE) or No
Position Independent Code (NO_PIE) for executables.
Use this to ensure that the POSITION_INDEPENDENT_CODE target
property for executables will be honored at link time.

check_pie_supported¶

check_pie_supported([OUTPUT_VARIABLE <output>]
                    [LANGUAGES <lang>...])

Options are:

OUTPUT_VARIABLE <output>

Set <output> 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.

LANGUAGES <lang>...

Check the linkers used for each of the specified languages.
If this option is not provided, the command checks all enabled languages.

C, CXX, Fortran are supported.

New in version 3.23: OBJC, OBJCXX, CUDA, and HIP are supported.

It makes no sense to use this module when CMP0083 is set to OLD,
so the command will return an error in this case.  See policy CMP0083
for details.

Variables¶

For each language checked, two boolean cache variables are defined.

CMAKE_<lang>_LINK_PIE_SUPPORTED

Set to true if PIE is supported by the linker and false otherwise.

CMAKE_<lang>_LINK_NO_PIE_SUPPORTED

Set to true if NO_PIE is supported by the linker and false otherwise.

Examples¶

check_pie_supported()
set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)

# 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}.\n"
                  "PIE link options will not be passed to linker.")
endif()

Table of Contents

CheckPIESupported

Variables

Examples

Previous topic

CheckOBJCXXSourceRuns

Next topic

CheckPrototypeDefinition

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckPIESupported

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckPrototypeDefinition — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckSourceCompiles" href="CheckSourceCompiles.html" />
    <link rel="prev" title="CheckPIESupported" href="CheckPIESupported.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckPrototypeDefinition

CheckPrototypeDefinition¶

Check if the prototype we expect is correct.

check_prototype_definition¶

check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)

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.

Example:

check_prototype_definition(getpwent_r
 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
 "NULL"
 "unistd.h;pwd.h"
 SOLARIS_GETPWENT_R)

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

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

Previous topic

CheckPIESupported

Next topic

CheckSourceCompiles

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckPrototypeDefinition

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckSourceCompiles — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckSourceRuns" href="CheckSourceRuns.html" />
    <link rel="prev" title="CheckPrototypeDefinition" href="CheckPrototypeDefinition.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckSourceCompiles

CheckSourceCompiles¶

New in version 3.19.

Check if given source compiles and links into an executable.

check_source_compiles¶

check_source_compiles(<lang> <code> <resultVar>
                      [FAIL_REGEX <regex1> [<regex2>...]]
                      [SRC_EXT <extension>])

Check that the source supplied in <code> 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 <resultVar>,
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
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 .<extension> instead.

The <code> must contain a valid main program. For example:

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

check_source_compiles(Fortran
"program test
error stop
end program"
HAVE_ERROR_STOP)

The check is only performed once, with the result cached in the variable
named by <resultVar>. Every subsequent CMake run will reuse this cached
value rather than performing the check again, even if the <code> changes.
In order to force the check to be re-evaluated, the variable named by
<resultVar> must be manually removed from the cache.

The compile and link commands can be influenced by setting any of the
following variables prior to calling check_source_compiles():

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

Previous topic

CheckPrototypeDefinition

Next topic

CheckSourceRuns

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckSourceCompiles

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckSourceRuns — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckStructHasMember" href="CheckStructHasMember.html" />
    <link rel="prev" title="CheckSourceCompiles" href="CheckSourceCompiles.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckSourceRuns

CheckSourceRuns¶

New in version 3.19.

Check if given source compiles and links into an executable and can
subsequently be run.

check_source_runs¶

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

Check that the source supplied in <code> can be compiled as a source
file for the requested language, linked as an executable and then run.
If the <code> could be built and run successfully, the internal cache variable
specified by <resultVar> will be set to 1, otherwise it will be set to
a value that evaluates to boolean false (e.g. an empty string or an error
message).

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 .<extension> instead.

The <code> must contain a valid main program. For example:

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

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

The check is only performed once, with the result cached in the variable named
by <resultVar>. Every subsequent CMake run will reuse this cached value
rather than performing the check again, even if the <code> changes. In
order to force the check to be re-evaluated, the variable named by
<resultVar> must be manually removed from the cache.

The compile and link commands can be influenced by setting any of the
following variables prior to calling check_source_runs()

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

Previous topic

CheckSourceCompiles

Next topic

CheckStructHasMember

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckSourceRuns

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckStructHasMember — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckSymbolExists" href="CheckSymbolExists.html" />
    <link rel="prev" title="CheckSourceRuns" href="CheckSourceRuns.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckStructHasMember

CheckStructHasMember¶

Check if the given struct or class has the specified member variable

CHECK_STRUCT_HAS_MEMBER¶

CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
                        [LANGUAGE <language>])

<struct> - the name of the struct or class you are interested in
<member> - the member which existence you want to check
<header> - the header(s) where the prototype should be declared
<variable> - variable to store the result
<language> - the compiler to use (C or CXX)

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

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

Example:

CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h
                        HAVE_TIMEVAL_TV_SEC LANGUAGE C)

Previous topic

CheckSourceRuns

Next topic

CheckSymbolExists

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckStructHasMember

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckSymbolExists — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckTypeSize" href="CheckTypeSize.html" />
    <link rel="prev" title="CheckStructHasMember" href="CheckStructHasMember.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckSymbolExists

CheckSymbolExists¶

Provides a macro to check if a symbol exists as a function, variable,
or macro in C.

check_symbol_exists¶

check_symbol_exists(<symbol> <files> <variable>)

Check that the <symbol> is available after including given header
<files> and store the result in a <variable>.  Specify the list
of files in one argument as a semicolon-separated list.
<variable> will be created as an internal cache variable.

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 CheckTypeSize or CheckSourceCompiles).
If the check needs to be done in C++, consider using
CheckCXXSymbolExists instead.

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

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

For example:

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)

Previous topic

CheckStructHasMember

Next topic

CheckTypeSize

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckSymbolExists

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckTypeSize — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CheckVariableExists" href="CheckVariableExists.html" />
    <link rel="prev" title="CheckSymbolExists" href="CheckSymbolExists.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckTypeSize

CheckTypeSize¶

Check sizeof a type

check_type_size¶

check_type_size(<type> <variable> [BUILTIN_TYPES_ONLY]
                                  [LANGUAGE <language>])

Check if the type exists and determine its size.  Results are reported
in the following variables:

HAVE_<variable>

Holds a true or false value indicating whether the type exists.

<variable>

Holds one of the following values:

<size>

Type has non-zero size <size>.

0

Type has architecture-dependent size.  This may occur when
CMAKE_OSX_ARCHITECTURES has multiple architectures.
In this case <variable>_CODE contains C preprocessor tests
mapping from each architecture macro to the corresponding type size.
The list of architecture macros is stored in <variable>_KEYS,
and the value for each key is stored in <variable>-<key>.

"" (empty string)

Type does not exist.

<variable>_CODE

Holds C preprocessor code to define the macro <variable> to the size
of the type, or to leave the macro undefined if the type does not exist.

The options are:

BUILTIN_TYPES_ONLY

Support only compiler-builtin types.  If not given, the macro checks
for headers <sys/types.h>, <stdint.h>, and <stddef.h>, and
saves results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and
HAVE_STDDEF_H.  The type size check automatically includes the
available headers, thus supporting checks of types defined in the headers.

LANGUAGE <language>

Use the <language> compiler to perform the check.
Acceptable values are C and CXX.

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:

check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)

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

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_INCLUDES

A ;-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

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

CMAKE_EXTRA_INCLUDE_FILES

list of extra headers to include.

Previous topic

CheckSymbolExists

Next topic

CheckVariableExists

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckTypeSize

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CheckVariableExists — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMakeAddFortranSubdirectory" href="CMakeAddFortranSubdirectory.html" />
    <link rel="prev" title="CheckTypeSize" href="CheckTypeSize.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckVariableExists

CheckVariableExists¶

Check if the variable exists.

CHECK_VARIABLE_EXISTS¶

CHECK_VARIABLE_EXISTS(VAR VARIABLE)

VAR      - the name of the variable
VARIABLE - variable to store the result
           Will be created as an internal cache variable.

This macro is only for C variables.

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

CMAKE_REQUIRED_FLAGS

String of additional flags to pass to the compiler. The string must be
space-delimited--a ;-list will not work.
The contents of CMAKE_<LANG>_FLAGS and
its associated configuration-specific variable are automatically added
to the compiler command before the contents of CMAKE_REQUIRED_FLAGS.

CMAKE_REQUIRED_DEFINITIONS

A ;-list of compiler definitions of the form
-DFOO or -DFOO=bar. A definition for the name specified by
<resultVar> will also be added automatically.

CMAKE_REQUIRED_LINK_OPTIONS

New in version 3.14.

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

CMAKE_REQUIRED_LIBRARIES

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 try_compile() for
further details).

CMAKE_REQUIRED_QUIET

New in version 3.1.

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

Previous topic

CheckTypeSize

Next topic

CMakeAddFortranSubdirectory

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

CheckVariableExists

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>Dart — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Documentation" href="Documentation.html" />
    <link rel="prev" title="CMakeParseArguments" href="CMakeParseArguments.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

Dart

Dart¶

Deprecated since version 3.27: This module is available only if policy CMP0145
is not set to NEW.  Do not use it in new code.
Use the CTest module instead.

Configure a project for testing with CTest or old Dart Tcl Client

This file is the backwards-compatibility version of the CTest module.
It supports using the old Dart 1 Tcl client for driving dashboard
submissions as well as testing with CTest.  This module should be
included in the CMakeLists.txt file at the top of a project.  Typical
usage:

include(Dart)
if(BUILD_TESTING)
  # ... testing related CMake code ...
endif()

The BUILD_TESTING option is created by the Dart module to determine
whether testing support should be enabled.  The default is ON.

Previous topic

CMakeParseArguments

Next topic

Documentation

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

Dart

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>DeployQt4 — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="ExternalData" href="ExternalData.html" />
    <link rel="prev" title="CTestUseLaunchers" href="CTestUseLaunchers.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

DeployQt4

DeployQt4¶

Functions to help assemble a standalone Qt4 executable.

A collection of CMake utility functions useful for deploying Qt4
executables.

The following functions are provided by this module:

write_qt4_conf
resolve_qt4_paths
fixup_qt4_executable
install_qt4_plugin_path
install_qt4_plugin
install_qt4_executable

Requires CMake 2.6 or greater because it uses function and
PARENT_SCOPE.  Also depends on BundleUtilities.cmake.

write_qt4_conf(<qt_conf_dir> <qt_conf_contents>)

Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>.

resolve_qt4_paths(<paths_var> [<executable_path>])

Loop through <paths_var> list and if any don't exist resolve them
relative to the <executable_path> (if supplied) or the
CMAKE_INSTALL_PREFIX.

fixup_qt4_executable(<executable>
  [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])

Copies Qt plugins, writes a Qt configuration file (if needed) and
fixes up a Qt4 executable using BundleUtilities so it is standalone
and can be drag-and-drop copied to another machine as long as all of
the system libraries are compatible.

<executable> should point to the executable to be fixed-up.

<qtplugins> should contain a list of the names or paths of any Qt
plugins to be installed.

<libs> will be passed to BundleUtilities and should be a list of any
already installed plugins, libraries or executables to also be
fixed-up.

<dirs> will be passed to BundleUtilities and should contain and
directories to be searched to find library dependencies.

<plugins_dir> allows an custom plugins directory to be used.

<request_qt_conf> will force a qt.conf file to be written even if not
needed.

install_qt4_plugin_path(plugin executable copy installed_plugin_path_var
                        <plugins_dir> <component> <configurations>)

Install (or copy) a resolved <plugin> to the default plugins directory
(or <plugins_dir>) relative to <executable> and store the result in
<installed_plugin_path_var>.

If <copy> is set to TRUE then the plugins will be copied rather than
installed.  This is to allow this module to be used at CMake time
rather than install time.

If <component> is set then anything installed will use this COMPONENT.

install_qt4_plugin(plugin executable copy installed_plugin_path_var
                   <plugins_dir> <component>)

Install (or copy) an unresolved <plugin> to the default plugins
directory (or <plugins_dir>) relative to <executable> and store the
result in <installed_plugin_path_var>.  See documentation of
INSTALL_QT4_PLUGIN_PATH.

install_qt4_executable(<executable>
  [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])

Installs Qt plugins, writes a Qt configuration file (if needed) and
fixes up a Qt4 executable using BundleUtilities so it is standalone
and can be drag-and-drop copied to another machine as long as all of
the system libraries are compatible.  The executable will be fixed-up
at install time.  <component> is the COMPONENT used for bundle fixup
and plugin installation.  See documentation of FIXUP_QT4_BUNDLE.

Previous topic

CTestUseLaunchers

Next topic

ExternalData

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

DeployQt4

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>Documentation — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="GetPrerequisites" href="GetPrerequisites.html" />
    <link rel="prev" title="Dart" href="Dart.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

Documentation

Documentation¶

Deprecated since version 3.18: This module does nothing, unless policy CMP0106 is set to OLD.

This module provides support for the VTK documentation framework.  It
relies on several tools (Doxygen, Perl, etc).

Previous topic

Dart

Next topic

GetPrerequisites

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

Documentation

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>ExternalData — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="ExternalProject" href="ExternalProject.html" />
    <link rel="prev" title="DeployQt4" href="DeployQt4.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

ExternalData

ExternalData¶

Contents

ExternalData

Introduction

Module Functions

Module Variables

Referencing Files

Referencing Single Files

Referencing File Series

Referencing Associated Files

Referencing Directories

Hash Algorithms

Custom Fetch Scripts

Manage data files stored outside source tree

Introduction¶

Use this module to unambiguously reference data files stored outside
the source tree and fetch them at build time from arbitrary local and
remote content-addressed locations.  Functions provided by this module
recognize arguments with the syntax DATA{<name>} as references to
external data, replace them with full paths to local copies of those
data, and create build rules to fetch and update the local copies.

For example:

include(ExternalData)
set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
                               "file:////host/share/%(algo)/%(hash)"
                               "http://data.org/%(algo)/%(hash)")
ExternalData_Add_Test(MyData
  NAME MyTest
  COMMAND MyExe DATA{MyInput.png}
  )
ExternalData_Add_Target(MyData)

When test MyTest runs the DATA{MyInput.png} argument will be
replaced by the full path to a real instance of the data file
MyInput.png on disk.  If the source tree contains a content link
such as MyInput.png.md5 then the MyData target creates a real
MyInput.png in the build tree.

Module Functions¶

ExternalData_Expand_Arguments¶

The ExternalData_Expand_Arguments function evaluates DATA{}
references in its arguments and constructs a new list of arguments:

ExternalData_Expand_Arguments(
  <target>   # Name of data management target
  <outVar>   # Output variable
  [args...]  # Input arguments, DATA{} allowed
  )

It replaces each DATA{} reference in an argument with the full path of
a real data file on disk that will exist after the <target> builds.

ExternalData_Add_Test¶

The ExternalData_Add_Test function wraps around the CMake
add_test() command but supports DATA{} references in
its arguments:

ExternalData_Add_Test(
  <target>   # Name of data management target
  ...        # Arguments of add_test(), DATA{} allowed
  )

It passes its arguments through ExternalData_Expand_Arguments and then
invokes the add_test() command using the results.

ExternalData_Add_Target¶

The ExternalData_Add_Target function creates a custom target to
manage local instances of data files stored externally:

ExternalData_Add_Target(
  <target>                  # Name of data management target
  [SHOW_PROGRESS <ON|OFF>]  # Show progress during the download
  )

It creates custom commands in the target as necessary to make data
files available for each DATA{} reference previously evaluated by
other functions provided by this module.
Data files may be fetched from one of the URL templates specified in
the ExternalData_URL_TEMPLATES variable, or may be found locally
in one of the paths specified in the ExternalData_OBJECT_STORES
variable.

New in version 3.20: The SHOW_PROGRESS argument may be passed to suppress progress information
during the download of objects. If not provided, it defaults to OFF for
Ninja and Ninja Multi-Config generators and ON
otherwise.

Typically only one target is needed to manage all external data within
a project.  Call this function once at the end of configuration after
all data references have been processed.

Module Variables¶

The following variables configure behavior.  They should be set before
calling any of the functions provided by this module.

ExternalData_BINARY_ROOT¶

The ExternalData_BINARY_ROOT variable may be set to the directory to
hold the real data files named by expanded DATA{} references.  The
default is CMAKE_BINARY_DIR.  The directory layout will mirror that of
content links under ExternalData_SOURCE_ROOT.

ExternalData_CUSTOM_SCRIPT_<key><a class="headerlink" href="#variable:ExternalData_CUSTOM_SCRIPT_<key>" title="Permalink to this definition">¶

New in version 3.2.

Specify a full path to a .cmake custom fetch script identified by
<key> in entries of the ExternalData_URL_TEMPLATES list.
See Custom Fetch Scripts.

ExternalData_LINK_CONTENT¶

The ExternalData_LINK_CONTENT variable may be set to the name of a
supported hash algorithm to enable automatic conversion of real data
files referenced by the DATA{} syntax into content links.  For each
such <file> a content link named <file><ext> is created.  The
original file is renamed to the form .ExternalData_<algo>_<hash> to
stage it for future transmission to one of the locations in the list
of URL templates (by means outside the scope of this module).  The
data fetch rule created for the content link will use the staged
object if it cannot be found using any URL template.

ExternalData_NO_SYMLINKS¶

New in version 3.3.

The real data files named by expanded DATA{} references may be made
available under ExternalData_BINARY_ROOT using symbolic links on
some platforms.  The ExternalData_NO_SYMLINKS variable may be set
to disable use of symbolic links and enable use of copies instead.

ExternalData_OBJECT_STORES¶

The ExternalData_OBJECT_STORES variable may be set to a list of local
directories that store objects using the layout <dir>/%(algo)/%(hash).
These directories will be searched first for a needed object.  If the
object is not available in any store then it will be fetched remotely
using the URL templates and added to the first local store listed.  If
no stores are specified the default is a location inside the build
tree.

ExternalData_SERIES_PARSE¶

ExternalData_SERIES_PARSE_PREFIX¶

ExternalData_SERIES_PARSE_NUMBER¶

ExternalData_SERIES_PARSE_SUFFIX¶

ExternalData_SERIES_MATCH¶

See Referencing File Series.

ExternalData_SOURCE_ROOT¶

The ExternalData_SOURCE_ROOT variable may be set to the highest source
directory containing any path named by a DATA{} reference.  The
default is CMAKE_SOURCE_DIR.  ExternalData_SOURCE_ROOT and
CMAKE_SOURCE_DIR must refer to directories within a single source
distribution (e.g.  they come together in one tarball).

ExternalData_TIMEOUT_ABSOLUTE¶

The ExternalData_TIMEOUT_ABSOLUTE variable sets the download
absolute timeout, in seconds, with a default of 300 seconds.
Set to 0 to disable enforcement.

ExternalData_TIMEOUT_INACTIVITY¶

The ExternalData_TIMEOUT_INACTIVITY variable sets the download
inactivity timeout, in seconds, with a default of 60 seconds.
Set to 0 to disable enforcement.

ExternalData_URL_ALGO_<algo>_<key><a class="headerlink" href="#variable:ExternalData_URL_ALGO_<algo>_<key>" title="Permalink to this definition">¶

New in version 3.3.

Specify a custom URL component to be substituted for URL template
placeholders of the form %(algo:<key>), where <key> is a
valid C identifier, when fetching an object referenced via hash
algorithm <algo>.  If not defined, the default URL component
is just <algo> for any <key>.

ExternalData_URL_TEMPLATES¶

The ExternalData_URL_TEMPLATES may be set to provide a list
of URL templates using the placeholders %(algo) and %(hash)
in each template.  Data fetch rules try each URL template in order
by substituting the hash algorithm name for %(algo) and the hash
value for %(hash).  Alternatively one may use %(algo:<key>)
with ExternalData_URL_ALGO_<algo>_<key> variables to gain more
flexibility in remote URLs.

Referencing Files¶

Referencing Single Files¶

The DATA{} syntax is literal and the <name> is a full or relative path
within the source tree.  The source tree must contain either a real
data file at <name> or a "content link" at <name><ext> containing a
hash of the real file using a hash algorithm corresponding to <ext>.
For example, the argument DATA{img.png} may be satisfied by either a
real img.png file in the current source directory or a img.png.md5
file containing its MD5 sum.

New in version 3.8: Multiple content links of the same name with different hash algorithms
are supported (e.g. img.png.sha256 and img.png.sha1) so long as
they all correspond to the same real file.  This allows objects to be
fetched from sources indexed by different hash algorithms.

Referencing File Series¶

The DATA{} syntax can be told to fetch a file series using the form
DATA{<name>,:}, where the : is literal.  If the source tree
contains a group of files or content links named like a series then a
reference to one member adds rules to fetch all of them.  Although all
members of a series are fetched, only the file originally named by the
DATA{} argument is substituted for it.  The default configuration
recognizes file series names ending with #.ext, _#.ext, .#.ext,
or -#.ext where # is a sequence of decimal digits and .ext is
any single extension.  Configure it with a regex that parses <number>
and <suffix> parts from the end of <name>:

ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$

For more complicated cases set:

ExternalData_SERIES_PARSE = regex with at least two () groups
ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number

Configure series number matching with a regex that matches the
<number> part of series members named <prefix><number><suffix>:

ExternalData_SERIES_MATCH = regex matching <number> in all series members

Note that the <suffix> of a series does not include a hash-algorithm
extension.

Referencing Associated Files¶

The DATA{} syntax can alternatively match files associated with the
named file and contained in the same directory.  Associated files may
be specified by options using the syntax
DATA{<name>,<opt1>,<opt2>,...}.  Each option may specify one file by
name or specify a regular expression to match file names using the
syntax REGEX:<regex>.  For example, the arguments:

DATA{MyData/MyInput.mhd,MyInput.img}                   # File pair
DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series

will pass MyInput.mha and MyFrames00.png on the command line but
ensure that the associated files are present next to them.

Referencing Directories¶

The DATA{} syntax may reference a directory using a trailing slash and
a list of associated files.  The form DATA{<name>/,<opt1>,<opt2>,...}
adds rules to fetch any files in the directory that match one of the
associated file options.  For example, the argument
DATA{MyDataDir/,REGEX:.*} will pass the full path to a MyDataDir
directory on the command line and ensure that the directory contains
files corresponding to every file or content link in the MyDataDir
source directory.

New in version 3.3: In order to match associated files in subdirectories,
specify a RECURSE: option, e.g. DATA{MyDataDir/,RECURSE:,REGEX:.*}.

Hash Algorithms¶

The following hash algorithms are supported:

%(algo)     <ext>     Description
-------     -----     -----------
MD5         .md5      Message-Digest Algorithm 5, RFC 1321
SHA1        .sha1     US Secure Hash Algorithm 1, RFC 3174
SHA224      .sha224   US Secure Hash Algorithms, RFC 4634
SHA256      .sha256   US Secure Hash Algorithms, RFC 4634
SHA384      .sha384   US Secure Hash Algorithms, RFC 4634
SHA512      .sha512   US Secure Hash Algorithms, RFC 4634
SHA3_224    .sha3-224 Keccak SHA-3
SHA3_256    .sha3-256 Keccak SHA-3
SHA3_384    .sha3-384 Keccak SHA-3
SHA3_512    .sha3-512 Keccak SHA-3

New in version 3.8: Added the SHA3_* hash algorithms.

Note that the hashes are used only for unique data identification and
download verification.

Custom Fetch Scripts¶

New in version 3.2.

When a data file must be fetched from one of the URL templates
specified in the ExternalData_URL_TEMPLATES variable, it is
normally downloaded using the file(DOWNLOAD) command.
One may specify usage of a custom fetch script by using a URL
template of the form ExternalDataCustomScript://<key>/<loc>.
The <key> must be a C identifier, and the <loc> must
contain the %(algo) and %(hash) placeholders.
A variable corresponding to the key, ExternalData_CUSTOM_SCRIPT_<key>,
must be set to the full path to a .cmake script file.  The script
will be included to perform the actual fetch, and provided with
the following variables:

ExternalData_CUSTOM_LOCATION¶

When a custom fetch script is loaded, this variable is set to the
location part of the URL, which will contain the substituted hash
algorithm name and content hash value.

ExternalData_CUSTOM_FILE¶

When a custom fetch script is loaded, this variable is set to the
full path to a file in which the script must store the fetched
content.  The name of the file is unspecified and should not be
interpreted in any way.

The custom fetch script is expected to store fetched content in the
file or set a variable:

ExternalData_CUSTOM_ERROR¶

When a custom fetch script fails to fetch the requested content,
it must set this variable to a short one-line message describing
the reason for failure.

Table of Contents

ExternalData

Introduction

Module Functions

Module Variables

Referencing Files

Referencing Single Files

Referencing File Series

Referencing Associated Files

Referencing Directories

Hash Algorithms

Custom Fetch Scripts

Previous topic

DeployQt4

Next topic

ExternalProject

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-modules(7) »

ExternalData

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.