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>enable_language — 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="enable_testing" href="enable_testing.html" />
    <link rel="prev" title="define_property" href="define_property.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

enable_language

enable_language¶

Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc)

enable_language(<lang>... [OPTIONAL])

Enables support for the named languages in CMake.  This is the same as
the project() command but does not create any of the extra
variables that are created by the project command.

Supported languages are C, CXX (i.e.  C++), CSharp (i.e.  C#), CUDA,
OBJC (i.e. Objective-C), OBJCXX (i.e. Objective-C++), Fortran, HIP,
ISPC, Swift, ASM, ASM_NASM, ASM_MARMASM, ASM_MASM, and ASM-ATT.

New in version 3.8: Added CSharp and CUDA support.

New in version 3.15: Added Swift support.

New in version 3.16: Added OBJC and OBJCXX support.

New in version 3.18: Added ISPC support.

New in version 3.21: Added HIP support.

New in version 3.26: Added ASM_MARMASM support.

If enabling ASM, list it last so that CMake can check whether
compilers for other languages like C work for assembly too.

This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or
indirectly through link dependencies.  It is simplest to enable all
needed languages in the top-level directory of a project.

The OPTIONAL keyword is a placeholder for future implementation and
does not currently work. Instead you can use the CheckLanguage
module to verify support before enabling.

Previous topic

define_property

Next topic

enable_testing

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-commands(7) »

enable_language

        © 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>enable_testing — 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="export" href="export.html" />
    <link rel="prev" title="enable_language" href="enable_language.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

enable_testing

enable_testing¶

Enable testing for current directory and below.

enable_testing()

Enables testing for this directory and below.

This command should be in the source directory root
because ctest expects to find a test file in the build
directory root.

This command is automatically invoked when the CTest
module is included, except if the BUILD_TESTING option is
turned off.

See also the add_test() command.

Previous topic

enable_language

Next topic

export

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-commands(7) »

enable_testing

        © 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>endblock — 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="endforeach" href="endforeach.html" />
    <link rel="prev" title="elseif" href="elseif.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

endblock

endblock¶

New in version 3.25.

Ends a list of commands in a block() and removes the scopes
created by the block() command.

endblock()

Previous topic

elseif

Next topic

endforeach

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-commands(7) »

endblock

        © 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>endforeach — 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="endfunction" href="endfunction.html" />
    <link rel="prev" title="endblock" href="endblock.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

endforeach

endforeach¶

Ends a list of commands in a foreach block.

endforeach([<loop_var>])

See the foreach() command.

The optional <loop_var> argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the <loop_var> argument of
the opening foreach clause.

Previous topic

endblock

Next topic

endfunction

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-commands(7) »

endforeach

        © 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>endfunction — 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="endif" href="endif.html" />
    <link rel="prev" title="endforeach" href="endforeach.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

endfunction

endfunction¶

Ends a list of commands in a function block.

endfunction([<name>])

See the function() command.

The optional <name> argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the <name> argument
of the opening function command.

Previous topic

endforeach

Next topic

endif

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-commands(7) »

endfunction

        © 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>endif — 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="endmacro" href="endmacro.html" />
    <link rel="prev" title="endfunction" href="endfunction.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

endif

endif¶

Ends a list of commands in an if block.

endif([<condition>])

See the if() command.

The optional <condition> argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the argument of the opening
if clause.

Previous topic

endfunction

Next topic

endmacro

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-commands(7) »

endif

        © 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>endmacro — 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="endwhile" href="endwhile.html" />
    <link rel="prev" title="endif" href="endif.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

endmacro

endmacro¶

Ends a list of commands in a macro block.

endmacro([<name>])

See the macro() command.

The optional <name> argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the <name> argument
of the opening macro command.

Previous topic

endif

Next topic

endwhile

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-commands(7) »

endmacro

        © 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>endwhile — 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="execute_process" href="execute_process.html" />
    <link rel="prev" title="endmacro" href="endmacro.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

endwhile

endwhile¶

Ends a list of commands in a while block.

endwhile([<condition>])

See the while() command.

The optional <condition> argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the argument of the opening
while clause.

Previous topic

endmacro

Next topic

execute_process

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-commands(7) »

endwhile

        © 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>exec_program — 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="export_library_dependencies" href="export_library_dependencies.html" />
    <link rel="prev" title="build_name" href="build_name.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

exec_program

exec_program¶

Changed in version 3.28: This command is available only if policy CMP0153 is not set to NEW.
Port projects to the execute_process() command.

Deprecated since version 3.0: Use the execute_process() command instead.

Run an executable program during the processing of the CMakeList.txt
file.

exec_program(Executable [directory in which to run]
             [ARGS <arguments to executable>]
             [OUTPUT_VARIABLE <var>]
             [RETURN_VALUE <var>])

The executable is run in the optionally specified directory.  The
executable can include arguments if it is double quoted, but it is
better to use the optional ARGS argument to specify arguments to the
program.  This is because cmake will then be able to escape spaces in
the executable path.  An optional argument OUTPUT_VARIABLE specifies a
variable in which to store the output.  To capture the return value of
the execution, provide a RETURN_VALUE.  If OUTPUT_VARIABLE is
specified, then no output will go to the stdout/stderr of the console
running cmake.

Previous topic

build_name

Next topic

export_library_dependencies

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-commands(7) »

exec_program

        © 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>execute_process — 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="file" href="file.html" />
    <link rel="prev" title="endwhile" href="endwhile.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

execute_process

execute_process¶

Execute one or more child processes.

execute_process(COMMAND <cmd1> [<arguments>]
                [COMMAND <cmd2> [<arguments>]]...
                [WORKING_DIRECTORY <directory>]
                [TIMEOUT <seconds>]
                [RESULT_VARIABLE <variable>]
                [RESULTS_VARIABLE <variable>]
                [OUTPUT_VARIABLE <variable>]
                [ERROR_VARIABLE <variable>]
                [INPUT_FILE <file>]
                [OUTPUT_FILE <file>]
                [ERROR_FILE <file>]
                [OUTPUT_QUIET]
                [ERROR_QUIET]
                [COMMAND_ECHO <where>]
                [OUTPUT_STRIP_TRAILING_WHITESPACE]
                [ERROR_STRIP_TRAILING_WHITESPACE]
                [ENCODING <name>]
                [ECHO_OUTPUT_VARIABLE]
                [ECHO_ERROR_VARIABLE]
                [COMMAND_ERROR_IS_FATAL <ANY|LAST>])

Runs the given sequence of one or more commands.

Commands are executed concurrently as a pipeline, with the standard
output of each process piped to the standard input of the next.
A single standard error pipe is used for all processes.

execute_process runs commands while CMake is configuring the project,
prior to build system generation.  Use the add_custom_target() and
add_custom_command() commands to create custom commands that run
at build time.

Options:

COMMAND

A child process command line.

CMake executes the child process using operating system APIs directly:

On POSIX platforms, the command line is passed to the
child process in an argv[] style array.

On Windows platforms, the command line is encoded as a string such
that child processes using CommandLineToArgvW will decode the
original arguments.

No intermediate shell is used, so shell operators such as >
are treated as normal arguments.
(Use the INPUT_*, OUTPUT_*, and ERROR_* options to
redirect stdin, stdout, and stderr.)

For sequential execution of multiple commands use multiple
execute_process calls each with a single COMMAND argument.

WORKING_DIRECTORY

The named directory will be set as the current working directory of
the child processes.

TIMEOUT

After the specified number of seconds (fractions allowed), all unfinished
child processes will be terminated, and the RESULT_VARIABLE will be
set to a string mentioning the "timeout".

RESULT_VARIABLE

The variable will be set to contain the result of last child process.
This will be an integer return code from the last child or a string
describing an error condition.

RESULTS_VARIABLE <variable>

New in version 3.10.

The variable will be set to contain the result of all processes as a
semicolon-separated list, in order of the
given COMMAND arguments.  Each entry will be an integer return code
from the corresponding child or a string describing an error condition.

INPUT_FILE <file>

<file> is attached to the standard input pipe of the first COMMAND
process.

OUTPUT_FILE <file>

<file> is attached to the standard output pipe of the last COMMAND
process.

ERROR_FILE <file>

<file> is attached to the standard error pipe of all COMMAND
processes.

New in version 3.3: If the same <file> is named for both OUTPUT_FILE and ERROR_FILE
then it will be used for both standard output and standard error pipes.

OUTPUT_QUIET, ERROR_QUIET

The standard output on OUTPUT_VARIABLE or standard error on
ERROR_VARIABLE are not connected (no variable content).
The  *_FILE and ECHO_*_VARIABLE options are not affected.

OUTPUT_VARIABLE, ERROR_VARIABLE

The variable named will be set with the contents of the standard output
and standard error pipes, respectively.  If the same variable is named
for both pipes their output will be merged in the order produced.

ECHO_OUTPUT_VARIABLE, ECHO_ERROR_VARIABLE

New in version 3.18.

The standard output or standard error will not be exclusively redirected to
the specified variables.

The output will be duplicated into the specified variables and also onto
standard output or standard error analogous to the tee Unix command.

Note

If more than one OUTPUT_* or ERROR_* option is given for the
same pipe the precedence is not specified.
If no OUTPUT_* or ERROR_* options are given the output will
be shared with the corresponding pipes of the CMake process itself.

COMMAND_ECHO <where>

New in version 3.15.

The command being run will be echo'ed to <where> with <where>
being set to one of STDERR, STDOUT or NONE.
See the CMAKE_EXECUTE_PROCESS_COMMAND_ECHO variable for a way
to control the default behavior when this option is not present.

ENCODING <name>

New in version 3.8.

On Windows, the encoding that is used to decode output from the process.
Ignored on other platforms.
Valid encoding names are:

NONE

Perform no decoding.  This assumes that the process output is encoded
in the same way as CMake's internal encoding (UTF-8).
This is the default.

AUTO

Use the current active console's codepage or if that isn't
available then use ANSI.

ANSI

Use the ANSI codepage.

OEM

Use the original equipment manufacturer (OEM) code page.

UTF8 or UTF-8

Use the UTF-8 codepage.

New in version 3.11: Accept UTF-8 spelling for consistency with the
UTF-8 RFC naming convention.

COMMAND_ERROR_IS_FATAL <ANY|LAST>

New in version 3.19.

The option following COMMAND_ERROR_IS_FATAL determines the behavior when
an error is encountered:

ANY
If any of the commands in the list of commands fail, the
execute_process() command halts with an error.

LAST
If the last command in the list of commands fails, the
execute_process() command halts with an error.  Commands earlier in the
list will not cause a fatal error.

Previous topic

endwhile

Next topic

file

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-commands(7) »

execute_process

        © 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>export — 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="fltk_wrap_ui" href="fltk_wrap_ui.html" />
    <link rel="prev" title="enable_testing" href="enable_testing.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

export

export¶

Export targets or packages for outside projects to use them directly
from the current project's build tree, without installation.

See the install(EXPORT) command to export targets from an
install tree.

Synopsis¶

export(TARGETS <target>... [...])
export(EXPORT <export-name> [...])
export(PACKAGE <PackageName>)
export(SETUP <export-name> [...])

Exporting Targets¶

export(TARGETS <target>... [...])¶

export(TARGETS <target>... [NAMESPACE <namespace>]
       [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]
       [CXX_MODULES_DIRECTORY <directory>])

Creates a file <filename> that may be included by outside projects to
import targets named by <target>... from the current project's build tree.
This is useful during cross-compiling to build utility executables that can
run on the host platform in one project and then import them into another
project being compiled for the target platform.

The file created by this command is specific to the build tree and
should never be installed.  See the install(EXPORT) command to
export targets from an install tree.

The options are:

NAMESPACE <namespace>

Prepend the <namespace> string to all target names written to the file.

APPEND

Append to the file instead of overwriting it.  This can be used to
incrementally export multiple targets to the same file.

EXPORT_LINK_INTERFACE_LIBRARIES

Include the contents of the properties named with the pattern
(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?
in the export, even when policy CMP0022 is NEW.  This is useful
to support consumers using CMake versions older than 2.8.12.

CXX_MODULES_DIRECTORY <directory>

New in version 3.28.

Export C++ module properties to files under the given directory. Each file
will be named according to the target's export name (without any namespace).
These files will automatically be included from the export file.

This signature requires all targets to be listed explicitly.  If a library
target is included in the export, but a target to which it links is not
included, the behavior is unspecified.  See the export(EXPORT) signature
to automatically export the same targets from the build tree as
install(EXPORT) would from an install tree.

Note

Object Libraries under Xcode have special handling if
multiple architectures are listed in CMAKE_OSX_ARCHITECTURES.
In this case they will be exported as Interface Libraries with
no object files available to clients.  This is sufficient to satisfy
transitive usage requirements of other targets that link to the
object libraries in their implementation.

This command exports all Build Configurations from the build tree.
See the CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> variable to map
configurations of dependent projects to the exported configurations.

Exporting Targets to Android.mk¶

export(TARGETS <target>... ANDROID_MK <filename>)

New in version 3.7.

This signature exports cmake built targets to the android ndk build system
by creating an Android.mk file that references the prebuilt targets. The
Android NDK supports the use of prebuilt libraries, both static and shared.
This allows cmake to build the libraries of a project and make them available
to an ndk build system complete with transitive dependencies, include flags
and defines required to use the libraries. The signature takes a list of
targets and puts them in the Android.mk file specified by the
<filename> given. This signature can only be used if policy
CMP0022 is NEW for all targets given. A error will be issued if
that policy is set to OLD for one of the targets.

Exporting Targets matching install(EXPORT)¶

export(EXPORT <export-name> [...])

export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]
       [CXX_MODULES_DIRECTORY <directory>] [EXPORT_PACKAGE_DEPENDENCIES])

Creates a file <filename> that may be included by outside projects to
import targets from the current project's build tree.  This is the same
as the export(TARGETS) signature, except that the targets are not
explicitly listed.  Instead, it exports the targets associated with
the installation export <export-name>.  Target installations may be
associated with the export <export-name> using the EXPORT option
of the install(TARGETS) command.

EXPORT_PACKAGE_DEPENDENCIES

New in version 3.29.

Specify that find_dependency() calls should be exported. See
install(EXPORT) for details on how this works.

Exporting Packages¶

export(PACKAGE <PackageName>)¶

export(PACKAGE <PackageName>)

Store the current build directory in the CMake user package registry
for package <PackageName>.  The find_package() command may consider the
directory while searching for package <PackageName>.  This helps dependent
projects find and use a package from the current project's build tree
without help from the user.  Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (<PackageName>Config.cmake) that works with the
build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package
registry.

Changed in version 3.1: If the CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable
is enabled, the export(PACKAGE) command will do nothing.

Changed in version 3.15: By default the export(PACKAGE) command does nothing (see policy
CMP0090) because populating the user package registry has effects
outside the source and build trees.  Set the
CMAKE_EXPORT_PACKAGE_REGISTRY variable to add build directories
to the CMake user package registry.

Configuring Exports¶

export(SETUP <export-name> [...])¶

export(SETUP <export-name>
       [PACKAGE_DEPENDENCY <dep>
        [ENABLED (<bool-true>|<bool-false>|AUTO)]
        [EXTRA_ARGS <args>...]
       ] [...]
       [TARGET <target>
        [XCFRAMEWORK_LOCATION <location>]
       ] [...]
       )

New in version 3.29.

Configure the parameters of an export. The arguments are as follows:

PACKAGE_DEPENDENCY <dep>

Specify a package dependency to configure. This changes how
find_dependency() calls are written during
export(EXPORT) and install(EXPORT). <dep> is the
name of a package to export. This argument accepts the following additional
arguments:

ENABLED

Manually control whether or not the dependency is exported. This accepts
the following values:

<bool-true>

Any value that CMake recognizes as "true". Always export the dependency,
even if no exported targets depend on it. This can be used to manually
add find_dependency() calls to the export.

<bool-false>

Any value that CMake recognizes as "false". Never export the dependency,
even if an exported target depends on it.

AUTO

Only export the dependency if an exported target depends on it.

EXTRA_ARGS <args>

Specify additional arguments to pass to find_dependency() after
the REQUIRED argument.

TARGET <target>

Specify a target to configure in this export. This argument accepts the
following additional arguments:

XCFRAMEWORK_LOCATION

Specify the location of an .xcframework which contains the library from
this target. If specified, the generated code will check to see if the
.xcframework exists, and if it does, it will use the .xcframework
as its imported location instead of the installed library.

Table of Contents

export

Synopsis

Exporting Targets

Exporting Targets to Android.mk

Exporting Targets matching install(EXPORT)

Exporting Packages

Configuring Exports

Previous topic

enable_testing

Next topic

fltk_wrap_ui

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-commands(7) »

export

        © 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>export_library_dependencies — 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="install_files" href="install_files.html" />
    <link rel="prev" title="exec_program" href="exec_program.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

export_library_dependencies

export_library_dependencies¶

Disallowed since version 3.0.  See CMake Policy CMP0033.

Use install(EXPORT) or export() command.

This command generates an old-style library dependencies file.
Projects requiring CMake 2.6 or later should not use the command.  Use
instead the install(EXPORT) command to help export targets from an
installation tree and the export() command to export targets from a
build tree.

The old-style library dependencies file does not take into account
per-configuration names of libraries or the
LINK_INTERFACE_LIBRARIES target property.

export_library_dependencies(<file> [APPEND])

Create a file named <file> that can be included into a CMake listfile
with the INCLUDE command.  The file will contain a number of SET
commands that will set all the variables needed for library dependency
information.  This should be the last command in the top level
CMakeLists.txt file of the project.  If the APPEND option is
specified, the SET commands will be appended to the given file instead
of replacing it.

Previous topic

exec_program

Next topic

install_files

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-commands(7) »

export_library_dependencies

        © 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>find_file — 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="find_library" href="find_library.html" />
    <link rel="prev" title="file" href="file.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

find_file

find_file¶

A short-hand signature is:

find_file (<VAR> name1 [path1 path2 ...])

The general signature is:

find_file (
          <VAR>
          name | NAMES name1 [name2 ...]
          [HINTS [path | ENV var]... ]
          [PATHS [path | ENV var]... ]
          [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [VALIDATOR function]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [REQUIRED]
          [NO_DEFAULT_PATH]
          [NO_PACKAGE_ROOT_PATH]
          [NO_CMAKE_PATH]
          [NO_CMAKE_ENVIRONMENT_PATH]
          [NO_SYSTEM_ENVIRONMENT_PATH]
          [NO_CMAKE_SYSTEM_PATH]
          [NO_CMAKE_INSTALL_PREFIX]
          [CMAKE_FIND_ROOT_PATH_BOTH |
           ONLY_CMAKE_FIND_ROOT_PATH |
           NO_CMAKE_FIND_ROOT_PATH]
         )

This command is used to find a full path to named file.
A cache entry, or a normal variable if NO_CACHE is specified,
named by <VAR> is created to store the result of this command.
If the full path to a file is found the result is stored in the variable
and the search will not be repeated unless the variable is cleared.
If nothing is found, the result will be <VAR>-NOTFOUND.

Options include:

NAMES

Specify one or more possible names for the full path to a file.

When using this to specify names with and without a version
suffix, we recommend specifying the unversioned name first
so that locally-built packages can be found before those
provided by distributions.

HINTS, PATHS

Specify directories to search in addition to the default locations.
The ENV var sub-option reads paths from a system environment
variable.

Changed in version 3.24: On Windows platform, it is possible to include registry queries as part
of the directories, using a dedicated syntax.
Such specifications will be ignored on all other platforms.

REGISTRY_VIEW

New in version 3.24.

Specify which registry views must be queried. This option is only meaningful
on Windows platforms and will be ignored on other ones. When not
specified, the TARGET view is used when the
CMP0134 policy is NEW. Refer to CMP0134 for the
default view when the policy is OLD.

64

Query the 64-bit registry. On 32-bit Windows, it always returns the string
/REGISTRY-NOTFOUND.

32

Query the 32-bit registry.

64_32

Query both views (64 and 32) and generate a path for each.

32_64

Query both views (32 and 64) and generate a path for each.

HOST

Query the registry matching the architecture of the host: 64 on 64-bit
Windows and 32 on 32-bit Windows.

TARGET

Query the registry matching the architecture specified by the
CMAKE_SIZEOF_VOID_P variable. If not defined, fall back to
HOST view.

BOTH

Query both views (32 and 64). The order depends on the following
rules: If the CMAKE_SIZEOF_VOID_P variable is defined, use the
following view depending on the content of this variable:

8: 64_32

4: 32_64

If the CMAKE_SIZEOF_VOID_P variable is not defined, rely on the
architecture of the host:

64-bit: 64_32

32-bit: 32

PATH_SUFFIXES

Specify additional subdirectories to check below each directory
location otherwise considered.

VALIDATOR

New in version 3.25.

Specify a function() to be called for each candidate item found
(a macro() cannot be provided, that will result in an error).
Two arguments will be passed to the validator function: the name of a
result variable, and the absolute path to the candidate item.  The item
will be accepted and the search will end unless the function sets the
value in the result variable to false in the calling scope.  The result
variable will hold a true value when the validator function is entered.

function(my_check validator_result_var item)
  if(NOT item MATCHES ...)
    set(${validator_result_var} FALSE PARENT_SCOPE)
  endif()
endfunction()

find_file (result NAMES ... VALIDATOR my_check)

Note that if a cached result is used, the search is skipped and any
VALIDATOR is ignored.  The cached result is not required to pass the
validation function.

DOC

Specify the documentation string for the <VAR> cache entry.

NO_CACHE

New in version 3.21.

The result of the search will be stored in a normal variable rather than
a cache entry.

Note

If the variable is already set before the call (as a normal or cache
variable) then the search will not occur.

Warning

This option should be used with caution because it can greatly increase
the cost of repeated configure steps.

REQUIRED

New in version 3.18.

Stop processing with an error message if nothing is found, otherwise
the search will be attempted again the next time find_file is invoked
with the same variable.

If NO_DEFAULT_PATH is specified, then no additional paths are
added to the search.
If NO_DEFAULT_PATH is not specified, the search process is as follows:

If called from within a find module or any other script loaded by a call to
find_package(<PackageName>), search prefixes unique to the
current package being found.  See policy CMP0074.

New in version 3.12.

Specifically, search paths specified by the following variables, in order:

<PackageName>_ROOT CMake variable,
where <PackageName> is the case-preserved package name.

<PACKAGENAME>_ROOT CMake variable,
where <PACKAGENAME> is the upper-cased package name.
See policy CMP0144.

New in version 3.27.

<PackageName>_ROOT environment variable,
where <PackageName> is the case-preserved package name.

<PACKAGENAME>_ROOT environment variable,
where <PACKAGENAME> is the upper-cased package name.
See policy CMP0144.

New in version 3.27.

The package root variables are maintained as a stack, so if called from
nested find modules or config packages, root paths from the parent's find
module or config package will be searched after paths from the current
module or package.  In other words, the search order would be
<CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT},
<ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE.

<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE
is set, and <prefix>/include for each <prefix> in the
<PackageName>_ROOT CMake variable and the
<PackageName>_ROOT environment variable if
called from within a find module loaded by
find_package(<PackageName>)

Search paths specified in cmake-specific cache variables.
These are intended to be used on the command line with a -DVAR=value.
The values are interpreted as semicolon-separated lists.
This can be skipped if NO_CMAKE_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_PATH to FALSE.

<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE
is set, and <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH

CMAKE_INCLUDE_PATH

CMAKE_FRAMEWORK_PATH

Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration,
and therefore use the host's native path separator
(; on Windows and : on UNIX).
This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed or
by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to FALSE.

<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set,
and <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH

CMAKE_INCLUDE_PATH

CMAKE_FRAMEWORK_PATH

Search the paths specified by the HINTS option.
These should be paths computed by system introspection, such as a
hint provided by the location of another item already found.
Hard-coded guesses should be specified with the PATHS option.

Search the standard system environment variables.
This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by
setting the CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.

The directories in INCLUDE
and PATH.

On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE
is set, and <prefix>/include for each <prefix>/[s]bin in PATH, and
<entry>/include for other entries in PATH.
This behavior was removed by CMake 3.28.

Search cmake variables defined in the Platform files
for the current system.  The searching of CMAKE_INSTALL_PREFIX and
CMAKE_STAGING_PREFIX can be
skipped if NO_CMAKE_INSTALL_PREFIX is passed or by setting the
CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All these locations
can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.

<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE
is set, and <prefix>/include for each <prefix> in
CMAKE_SYSTEM_PREFIX_PATH

CMAKE_SYSTEM_INCLUDE_PATH

CMAKE_SYSTEM_FRAMEWORK_PATH

The platform paths that these variables contain are locations that
typically include installed software. An example being /usr/local for
UNIX based platforms.

Search the paths specified by the PATHS option
or in the short-hand version of the command.
These are typically hard-coded guesses.

The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
CMAKE_SYSTEM_IGNORE_PATH and
CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables can also cause some
of the above locations to be ignored.

New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to globally disable
various search locations.

On macOS the CMAKE_FIND_FRAMEWORK and
CMAKE_FIND_APPBUNDLE variables determine the order of
preference between Apple-style and unix-style package components.

The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
directories to be prepended to all other search directories.  This
effectively "re-roots" the entire search under given locations.
Paths which are descendants of the CMAKE_STAGING_PREFIX are excluded
from this re-rooting, because that variable is always a path on the host system.
By default the CMAKE_FIND_ROOT_PATH is empty.

The CMAKE_SYSROOT variable can also be used to specify exactly one
directory to use as a prefix.  Setting CMAKE_SYSROOT also has other
effects.  See the documentation for that variable for more.

These variables are especially useful when cross-compiling to
point to the root directory of the target environment and CMake will
search there too.  By default at first the directories listed in
CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT
directory is searched, and then the non-rooted directories will be
searched.  The default behavior can be adjusted by setting
CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.  This behavior can be manually
overridden on a per-call basis using options:

CMAKE_FIND_ROOT_PATH_BOTH

Search in the order described above.

NO_CMAKE_FIND_ROOT_PATH

Do not use the CMAKE_FIND_ROOT_PATH variable.

ONLY_CMAKE_FIND_ROOT_PATH

Search only the re-rooted directories and directories below
CMAKE_STAGING_PREFIX.

The default search order is designed to be most-specific to
least-specific for common use cases.
Projects may override the order by simply calling the command
multiple times and using the NO_* options:

find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_file (<VAR> NAMES name)

Once one of the calls succeeds the result variable will be set
and stored in the cache so that no call will search again.

Previous topic

file

Next topic

find_library

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-commands(7) »

find_file

        © 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>find_library — 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="find_package" href="find_package.html" />
    <link rel="prev" title="find_file" href="find_file.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

find_library

find_library¶

A short-hand signature is:

find_library (<VAR> name1 [path1 path2 ...])

The general signature is:

find_library (
          <VAR>
          name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
          [HINTS [path | ENV var]... ]
          [PATHS [path | ENV var]... ]
          [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [VALIDATOR function]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [REQUIRED]
          [NO_DEFAULT_PATH]
          [NO_PACKAGE_ROOT_PATH]
          [NO_CMAKE_PATH]
          [NO_CMAKE_ENVIRONMENT_PATH]
          [NO_SYSTEM_ENVIRONMENT_PATH]
          [NO_CMAKE_SYSTEM_PATH]
          [NO_CMAKE_INSTALL_PREFIX]
          [CMAKE_FIND_ROOT_PATH_BOTH |
           ONLY_CMAKE_FIND_ROOT_PATH |
           NO_CMAKE_FIND_ROOT_PATH]
         )

This command is used to find a library.
A cache entry, or a normal variable if NO_CACHE is specified,
named by <VAR> is created to store the result of this command.
If the library is found the result is stored in the variable
and the search will not be repeated unless the variable is cleared.
If nothing is found, the result will be <VAR>-NOTFOUND.

Options include:

NAMES

Specify one or more possible names for the library.

When using this to specify names with and without a version
suffix, we recommend specifying the unversioned name first
so that locally-built packages can be found before those
provided by distributions.

HINTS, PATHS

Specify directories to search in addition to the default locations.
The ENV var sub-option reads paths from a system environment
variable.

Changed in version 3.24: On Windows platform, it is possible to include registry queries as part
of the directories, using a dedicated syntax.
Such specifications will be ignored on all other platforms.

REGISTRY_VIEW

New in version 3.24.

Specify which registry views must be queried. This option is only meaningful
on Windows platforms and will be ignored on other ones. When not
specified, the TARGET view is used when the
CMP0134 policy is NEW. Refer to CMP0134 for the
default view when the policy is OLD.

64

Query the 64-bit registry. On 32-bit Windows, it always returns the string
/REGISTRY-NOTFOUND.

32

Query the 32-bit registry.

64_32

Query both views (64 and 32) and generate a path for each.

32_64

Query both views (32 and 64) and generate a path for each.

HOST

Query the registry matching the architecture of the host: 64 on 64-bit
Windows and 32 on 32-bit Windows.

TARGET

Query the registry matching the architecture specified by the
CMAKE_SIZEOF_VOID_P variable. If not defined, fall back to
HOST view.

BOTH

Query both views (32 and 64). The order depends on the following
rules: If the CMAKE_SIZEOF_VOID_P variable is defined, use the
following view depending on the content of this variable:

8: 64_32

4: 32_64

If the CMAKE_SIZEOF_VOID_P variable is not defined, rely on the
architecture of the host:

64-bit: 64_32

32-bit: 32

PATH_SUFFIXES

Specify additional subdirectories to check below each directory
location otherwise considered.

VALIDATOR

New in version 3.25.

Specify a function() to be called for each candidate item found
(a macro() cannot be provided, that will result in an error).
Two arguments will be passed to the validator function: the name of a
result variable, and the absolute path to the candidate item.  The item
will be accepted and the search will end unless the function sets the
value in the result variable to false in the calling scope.  The result
variable will hold a true value when the validator function is entered.

function(my_check validator_result_var item)
  if(NOT item MATCHES ...)
    set(${validator_result_var} FALSE PARENT_SCOPE)
  endif()
endfunction()

find_library (result NAMES ... VALIDATOR my_check)

Note that if a cached result is used, the search is skipped and any
VALIDATOR is ignored.  The cached result is not required to pass the
validation function.

DOC

Specify the documentation string for the <VAR> cache entry.

NO_CACHE

New in version 3.21.

The result of the search will be stored in a normal variable rather than
a cache entry.

Note

If the variable is already set before the call (as a normal or cache
variable) then the search will not occur.

Warning

This option should be used with caution because it can greatly increase
the cost of repeated configure steps.

REQUIRED

New in version 3.18.

Stop processing with an error message if nothing is found, otherwise
the search will be attempted again the next time find_library is invoked
with the same variable.

If NO_DEFAULT_PATH is specified, then no additional paths are
added to the search.
If NO_DEFAULT_PATH is not specified, the search process is as follows:

If called from within a find module or any other script loaded by a call to
find_package(<PackageName>), search prefixes unique to the
current package being found.  See policy CMP0074.

New in version 3.12.

Specifically, search paths specified by the following variables, in order:

<PackageName>_ROOT CMake variable,
where <PackageName> is the case-preserved package name.

<PACKAGENAME>_ROOT CMake variable,
where <PACKAGENAME> is the upper-cased package name.
See policy CMP0144.

New in version 3.27.

<PackageName>_ROOT environment variable,
where <PackageName> is the case-preserved package name.

<PACKAGENAME>_ROOT environment variable,
where <PACKAGENAME> is the upper-cased package name.
See policy CMP0144.

New in version 3.27.

The package root variables are maintained as a stack, so if called from
nested find modules or config packages, root paths from the parent's find
module or config package will be searched after paths from the current
module or package.  In other words, the search order would be
<CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT},
<ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE.

<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set,
and <prefix>/lib for each <prefix> in the
<PackageName>_ROOT CMake variable and the
<PackageName>_ROOT environment variable if
called from within a find module loaded by
find_package(<PackageName>)

Search paths specified in cmake-specific cache variables.
These are intended to be used on the command line with a -DVAR=value.
The values are interpreted as semicolon-separated lists.
This can be skipped if NO_CMAKE_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_PATH to FALSE.

<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set,
and <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH

CMAKE_LIBRARY_PATH

CMAKE_FRAMEWORK_PATH

Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration,
and therefore use the host's native path separator
(; on Windows and : on UNIX).
This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed or
by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to FALSE.

<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set,
and <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH

CMAKE_LIBRARY_PATH

CMAKE_FRAMEWORK_PATH

Search the paths specified by the HINTS option.
These should be paths computed by system introspection, such as a
hint provided by the location of another item already found.
Hard-coded guesses should be specified with the PATHS option.

Search the standard system environment variables.
This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by
setting the CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.

The directories in LIB
and PATH.

On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE
is set, and <prefix>/lib for each <prefix>/[s]bin in PATH, and
<entry>/lib for other entries in PATH.
This behavior was removed by CMake 3.28.

Search cmake variables defined in the Platform files
for the current system.  The searching of CMAKE_INSTALL_PREFIX and
CMAKE_STAGING_PREFIX can be
skipped if NO_CMAKE_INSTALL_PREFIX is passed or by setting the
CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All these locations
can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.

<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set,
and <prefix>/lib for each <prefix> in
CMAKE_SYSTEM_PREFIX_PATH

CMAKE_SYSTEM_LIBRARY_PATH

CMAKE_SYSTEM_FRAMEWORK_PATH

The platform paths that these variables contain are locations that
typically include installed software. An example being /usr/local for
UNIX based platforms.

Search the paths specified by the PATHS option
or in the short-hand version of the command.
These are typically hard-coded guesses.

The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
CMAKE_SYSTEM_IGNORE_PATH and
CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables can also cause some
of the above locations to be ignored.

New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to globally disable
various search locations.

On macOS the CMAKE_FIND_FRAMEWORK and
CMAKE_FIND_APPBUNDLE variables determine the order of
preference between Apple-style and unix-style package components.

The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
directories to be prepended to all other search directories.  This
effectively "re-roots" the entire search under given locations.
Paths which are descendants of the CMAKE_STAGING_PREFIX are excluded
from this re-rooting, because that variable is always a path on the host system.
By default the CMAKE_FIND_ROOT_PATH is empty.

The CMAKE_SYSROOT variable can also be used to specify exactly one
directory to use as a prefix.  Setting CMAKE_SYSROOT also has other
effects.  See the documentation for that variable for more.

These variables are especially useful when cross-compiling to
point to the root directory of the target environment and CMake will
search there too.  By default at first the directories listed in
CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT
directory is searched, and then the non-rooted directories will be
searched.  The default behavior can be adjusted by setting
CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.  This behavior can be manually
overridden on a per-call basis using options:

CMAKE_FIND_ROOT_PATH_BOTH

Search in the order described above.

NO_CMAKE_FIND_ROOT_PATH

Do not use the CMAKE_FIND_ROOT_PATH variable.

ONLY_CMAKE_FIND_ROOT_PATH

Search only the re-rooted directories and directories below
CMAKE_STAGING_PREFIX.

The default search order is designed to be most-specific to
least-specific for common use cases.
Projects may override the order by simply calling the command
multiple times and using the NO_* options:

find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_library (<VAR> NAMES name)

Once one of the calls succeeds the result variable will be set
and stored in the cache so that no call will search again.

When more than one value is given to the NAMES option this command by
default will consider one name at a time and search every directory
for it.  The NAMES_PER_DIR option tells this command to consider one
directory at a time and search for all names in it.

Each library name given to the NAMES option is first considered
as a library file name and then considered with platform-specific
prefixes (e.g. lib) and suffixes (e.g. .so).  Therefore one
may specify library file names such as libfoo.a directly.
This can be used to locate static libraries on UNIX-like systems.

If the library found is a framework, then <VAR> will be set to the full
path to the framework <fullPath>/A.framework.  When a full path to a
framework is used as a library, CMake will use a -framework A, and a
-F<fullPath> to link the framework to the target.

New in version 3.28: The library found can now be a .xcframework folder.

If the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable is set all
search paths will be tested as normal, with the suffix appended, and with
all matches of lib/ replaced with
lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/.  This variable overrides
the FIND_LIBRARY_USE_LIB32_PATHS,
FIND_LIBRARY_USE_LIBX32_PATHS,
and FIND_LIBRARY_USE_LIB64_PATHS global properties.

If the FIND_LIBRARY_USE_LIB32_PATHS global property is set
all search paths will be tested as normal, with 32/ appended, and
with all matches of lib/ replaced with lib32/.  This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the project() command
is enabled.

If the FIND_LIBRARY_USE_LIBX32_PATHS global property is set
all search paths will be tested as normal, with x32/ appended, and
with all matches of lib/ replaced with libx32/.  This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the project() command
is enabled.

If the FIND_LIBRARY_USE_LIB64_PATHS global property is set
all search paths will be tested as normal, with 64/ appended, and
with all matches of lib/ replaced with lib64/.  This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the project() command
is enabled.

Previous topic

find_file

Next topic

find_package

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-commands(7) »

find_library

        © 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>find_package — 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="find_path" href="find_path.html" />
    <link rel="prev" title="find_library" href="find_library.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-commands(7) »

find_package

find_package¶

Contents

find_package

Search Modes

Basic Signature

Full Signature

Config Mode Search Procedure

Config Mode Version Selection

Package File Interface Variables

Note

The Using Dependencies Guide provides a high-level
introduction to this general topic. It provides a broader overview of
where the find_package() command fits into the bigger picture,
including its relationship to the FetchContent module.
The guide is recommended pre-reading before moving on to the details below.

Find a package (usually provided by something external to the project),
and load its package-specific details.  Calls to this command can also
be intercepted by dependency providers.

Search Modes¶

The command has a few modes by which it searches for packages:

Module mode

In this mode, CMake searches for a file called Find<PackageName>.cmake,
looking first in the locations listed in the CMAKE_MODULE_PATH,
then among the Find Modules provided by the CMake installation.
If the file is found, it is read and processed by CMake.  It is responsible
for finding the package, checking the version, and producing any needed
messages.  Some Find modules provide limited or no support for versioning;
check the Find module's documentation.

The Find<PackageName>.cmake file is not typically provided by the
package itself.  Rather, it is normally provided by something external to
the package, such as the operating system, CMake itself, or even the project
from which the find_package() command was called.  Being externally
provided, Find Modules tend to be heuristic in nature and are
susceptible to becoming out-of-date.  They typically search for certain
libraries, files and other package artifacts.

Module mode is only supported by the
basic command signature.

Config mode

In this mode, CMake searches for a file called
<lowercasePackageName>-config.cmake or <PackageName>Config.cmake.
It will also look for <lowercasePackageName>-config-version.cmake or
<PackageName>ConfigVersion.cmake if version details were specified
(see Config Mode Version Selection for an explanation of how these separate
version files are used).

In config mode, the command can be given a list of names to search for
as package names.  The locations where CMake searches for the config and
version files is considerably more complicated than for Module mode
(see Config Mode Search Procedure).

The config and version files are typically installed as part of the
package, so they tend to be more reliable than Find modules.  They usually
contain direct knowledge of the package contents, so no searching or
heuristics are needed within the config or version files themselves.

Config mode is supported by both the basic and
full command signatures.

FetchContent redirection mode

New in version 3.24: A call to find_package() can be redirected internally to a package
provided by the FetchContent module.  To the caller, the behavior
will appear similar to Config mode, except that the search logic is
by-passed and the component information is not used.  See
FetchContent_Declare() and FetchContent_MakeAvailable()
for further details.

When not redirected to a package provided by FetchContent, the
command arguments determine whether Module or Config mode is used.  When the
basic signature is used, the command searches in Module mode first.
If the package is not found, the search falls back to Config mode.
A user may set the CMAKE_FIND_PACKAGE_PREFER_CONFIG variable
to true to reverse the priority and direct CMake to search using Config mode
first before falling back to Module mode.  The basic signature can also be
forced to use only Module mode with a MODULE keyword.  If the
full signature is used, the command only searches in Config mode.

Where possible, user code should generally look for packages using the
basic signature, since that allows the package to be found with any mode.
Project maintainers wishing to provide a config package should understand
the bigger picture, as explained in Full Signature and all subsequent
sections on this page.

Basic Signature¶

find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
             [REQUIRED] [[COMPONENTS] [components...]]
             [OPTIONAL_COMPONENTS components...]
             [REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)]
             [GLOBAL]
             [NO_POLICY_SCOPE]
             [BYPASS_PROVIDER])

The basic signature is supported by both Module and Config modes.
The MODULE keyword implies that only Module mode can be used to find
the package, with no fallback to Config mode.

Regardless of the mode used, a <PackageName>_FOUND variable will be
set to indicate whether the package was found.  When the package is found,
package-specific information may be provided through other variables and
Imported Targets documented by the package itself.  The
QUIET option disables informational messages, including those indicating
that the package cannot be found if it is not REQUIRED.  The REQUIRED
option stops processing with an error message if the package cannot be found.

A package-specific list of required components may be listed after the
COMPONENTS keyword.  If any of these components are not able to be
satisfied, the package overall is considered to be not found.  If the
REQUIRED option is also present, this is treated as a fatal error,
otherwise execution still continues.  As a form of shorthand, if the
REQUIRED option is present, the COMPONENTS keyword can be omitted
and the required components can be listed directly after REQUIRED.

Additional optional components may be listed after
OPTIONAL_COMPONENTS.  If these cannot be satisfied, the package overall
can still be considered found, as long as all required components are
satisfied.

The set of available components and their meaning are defined by the
target package.  Formally, it is up to the target package how to
interpret the component information given to it, but it should follow
the expectations stated above.  For calls where no components are specified,
there is no single expected behavior and target packages should clearly
define what occurs in such cases.  Common arrangements include assuming it
should find all components, no components or some well-defined subset of the
available components.

New in version 3.24: The REGISTRY_VIEW keyword specifies which registry views should be
queried. This keyword is only meaningful on Windows platforms and will
be ignored on all others. Formally, it is up to the target package how to
interpret the registry view information given to it.

New in version 3.24: Specifying the GLOBAL keyword will promote all imported targets to
a global scope in the importing project. Alternatively, this functionality
can be enabled by setting the CMAKE_FIND_PACKAGE_TARGETS_GLOBAL
variable.

The [version] argument requests a version with which the package found
should be compatible. There are two possible forms in which it may be
specified:

A single version with the format major[.minor[.patch[.tweak]]], where
each component is a numeric value.

A version range with the format versionMin...[<]versionMax where
versionMin and versionMax have the same format and constraints
on components being integers as the single version.  By default, both end
points are included.  By specifying <, the upper end point will be
excluded. Version ranges are only supported with CMake 3.19 or later.

The EXACT option requests that the version be matched exactly. This option
is incompatible with the specification of a version range.

If no [version] and/or component list is given to a recursive invocation
inside a find-module, the corresponding arguments are forwarded
automatically from the outer call (including the EXACT flag for
[version]).  Version support is currently provided only on a
package-by-package basis (see the Version Selection section below).
When a version range is specified but the package is only designed to expect
a single version, the package will ignore the upper end point of the range and
only take the single version at the lower end of the range into account.

See the cmake_policy() command documentation for discussion
of the NO_POLICY_SCOPE option.

New in version 3.24: The BYPASS_PROVIDER keyword is only allowed when find_package() is
being called by a dependency provider.
It can be used by providers to call the built-in find_package()
implementation directly and prevent that call from being re-routed back to
itself.  Future versions of CMake may detect attempts to use this keyword
from places other than a dependency provider and halt with a fatal error.

Full Signature¶

find_package(<PackageName> [version] [EXACT] [QUIET]
             [REQUIRED] [[COMPONENTS] [components...]]
             [OPTIONAL_COMPONENTS components...]
             [CONFIG|NO_MODULE]
             [GLOBAL]
             [NO_POLICY_SCOPE]
             [BYPASS_PROVIDER]
             [NAMES name1 [name2 ...]]
             [CONFIGS config1 [config2 ...]]
             [HINTS path1 [path2 ... ]]
             [PATHS path1 [path2 ... ]]
             [REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)]
             [PATH_SUFFIXES suffix1 [suffix2 ...]]
             [NO_DEFAULT_PATH]
             [NO_PACKAGE_ROOT_PATH]
             [NO_CMAKE_PATH]
             [NO_CMAKE_ENVIRONMENT_PATH]
             [NO_SYSTEM_ENVIRONMENT_PATH]
             [NO_CMAKE_PACKAGE_REGISTRY]
             [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
             [NO_CMAKE_SYSTEM_PATH]
             [NO_CMAKE_INSTALL_PREFIX]
             [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
             [CMAKE_FIND_ROOT_PATH_BOTH |
              ONLY_CMAKE_FIND_ROOT_PATH |
              NO_CMAKE_FIND_ROOT_PATH])

The CONFIG option, the synonymous NO_MODULE option, or the use
of options not specified in the basic signature all enforce pure Config
mode.  In pure Config mode, the command skips Module mode search and
proceeds at once with Config mode search.

Config mode search attempts to locate a configuration file provided by the
package to be found.  A cache entry called <PackageName>_DIR is created to
hold the directory containing the file.  By default, the command searches for
a package with the name <PackageName>.  If the NAMES option is given,
the names following it are used instead of <PackageName>.  The names are
also considered when determining whether to redirect the call to a package
provided by FetchContent.

The command searches for a file called <PackageName>Config.cmake or
<lowercasePackageName>-config.cmake for each name specified.
A replacement set of possible configuration file names may be given
using the CONFIGS option.  The Config Mode Search Procedure is specified below.
Once found, any version constraint is checked,
and if satisfied, the configuration file is read and processed by CMake.
Since the file is provided by the package it already knows the
location of package contents.  The full path to the configuration file
is stored in the cmake variable <PackageName>_CONFIG.

All configuration files which have been considered by CMake while
searching for the package with an appropriate version are stored in the
<PackageName>_CONSIDERED_CONFIGS variable, and the associated versions
in the <PackageName>_CONSIDERED_VERSIONS variable.

If the package configuration file cannot be found CMake will generate
an error describing the problem unless the QUIET argument is
specified.  If REQUIRED is specified and the package is not found a
fatal error is generated and the configure step stops executing.  If
<PackageName>_DIR has been set to a directory not containing a
configuration file CMake will ignore it and search from scratch.

Package maintainers providing CMake package configuration files are
encouraged to name and install them such that the Config Mode Search Procedure
outlined below will find them without requiring use of additional options.

Config Mode Search Procedure¶

Note

When Config mode is used, this search procedure is applied regardless of
whether the full or basic
signature was given.

New in version 3.24: All calls to find_package() (even in Module mode) first look for a config
package file in the CMAKE_FIND_PACKAGE_REDIRECTS_DIR directory.
The FetchContent module, or even the project itself, may write files
to that location to redirect find_package() calls to content already
provided by the project.  If no config package file is found in that location,
the search proceeds with the logic described below.

CMake constructs a set of possible installation prefixes for the
package.  Under each prefix several directories are searched for a
configuration file.  The tables below show the directories searched.
Each entry is meant for installation trees following Windows (W), UNIX
(U), or Apple (A) conventions:

Entry

Convention

<prefix>/

W

<prefix>/(cmake|CMake)/

W

<prefix>/<name>*/

W

<prefix>/<name>*/(cmake|CMake)/

W

<prefix>/<name>*/(cmake|CMake)/<name>*/ [1]

W

<prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/

U

<prefix>/(lib/<arch>|lib*|share)/<name>*/

U

<prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/

U

<prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/

W/U

<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/

W/U

<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/

W/U

[1]

New in version 3.25.

On systems supporting macOS FRAMEWORK and BUNDLE, the
following directories are searched for Frameworks or Application Bundles
containing a configuration file:

Entry

Convention

<prefix>/<name>.framework/Resources/

A

<prefix>/<name>.framework/Resources/CMake/

A

<prefix>/<name>.framework/Versions/*/Resources/

A

<prefix>/<name>.framework/Versions/*/Resources/CMake/

A

<prefix>/<name>.app/Contents/Resources/

A

<prefix>/<name>.app/Contents/Resources/CMake/

A

In all cases the <name> is treated as case-insensitive and corresponds
to any of the names specified (<PackageName> or names given by NAMES).

If at least one compiled language has been enabled, the architecture-specific
lib/<arch> and lib* directories may be searched based on the compiler's
target architecture, in the following order:

lib/<arch>

Searched if the CMAKE_LIBRARY_ARCHITECTURE variable is set.

lib64

Searched on 64 bit platforms (CMAKE_SIZEOF_VOID_P is 8) and the
FIND_LIBRARY_USE_LIB64_PATHS property is set to TRUE.

lib32

Searched on 32 bit platforms (CMAKE_SIZEOF_VOID_P is 4) and the
FIND_LIBRARY_USE_LIB32_PATHS property is set to TRUE.

libx32

Searched on platforms using the x32 ABI
if the FIND_LIBRARY_USE_LIBX32_PATHS property is set to TRUE.

lib

Always searched.

Changed in version 3.24: On Windows platform, it is possible to include registry queries as part
of the directories specified through HINTS and PATHS keywords, using
a dedicated syntax. Such specifications
will be ignored on all other platforms.

New in version 3.24: REGISTRY_VIEW can be specified to manage Windows registry queries
specified as part of PATHS and HINTS.

Specify which registry views must be queried. This option is only meaningful
on Windows platforms and will be ignored on other ones. When not
specified, the TARGET view is used when the
CMP0134 policy is NEW. Refer to CMP0134 for the
default view when the policy is OLD.

64

Query the 64-bit registry. On 32-bit Windows, it always returns the string
/REGISTRY-NOTFOUND.

32

Query the 32-bit registry.

64_32

Query both views (64 and 32) and generate a path for each.

32_64

Query both views (32 and 64) and generate a path for each.

HOST

Query the registry matching the architecture of the host: 64 on 64-bit
Windows and 32 on 32-bit Windows.

TARGET

Query the registry matching the architecture specified by the
CMAKE_SIZEOF_VOID_P variable. If not defined, fall back to
HOST view.

BOTH

Query both views (32 and 64). The order depends on the following
rules: If the CMAKE_SIZEOF_VOID_P variable is defined, use the
following view depending on the content of this variable:

8: 64_32

4: 32_64

If the CMAKE_SIZEOF_VOID_P variable is not defined, rely on the
architecture of the host:

64-bit: 64_32

32-bit: 32

If PATH_SUFFIXES is specified, the suffixes are appended to each
(W) or (U) directory entry one-by-one.

This set of directories is intended to work in cooperation with
projects that provide configuration files in their installation trees.
Directories above marked with (W) are intended for installations on
Windows where the prefix may point at the top of an application's
installation directory.  Those marked with (U) are intended for
installations on UNIX platforms where the prefix is shared by multiple
packages.  This is merely a convention, so all (W) and (U) directories
are still searched on all platforms.  Directories marked with (A) are
intended for installations on Apple platforms.  The
CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE
variables determine the order of preference.

The set of installation prefixes is constructed using the following
steps.  If NO_DEFAULT_PATH is specified all NO_* options are
enabled.

Search prefixes unique to the current <PackageName> being found.
See policy CMP0074.

New in version 3.12.

Specifically, search prefixes specified by the following variables,
in order:

<PackageName>_ROOT CMake variable,
where <PackageName> is the case-preserved package name.

<PACKAGENAME>_ROOT CMake variable,
where <PACKAGENAME> is the upper-cased package name.
See policy CMP0144.

New in version 3.27.

<PackageName>_ROOT environment variable,
where <PackageName> is the case-preserved package name.

<PACKAGENAME>_ROOT environment variable,
where <PACKAGENAME> is the upper-cased package name.
See policy CMP0144.

New in version 3.27.

The package root variables are maintained as a stack so if
called from within a find module, root paths from the parent's find
module will also be searched after paths for the current package.
This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE.

Search paths specified in cmake-specific cache variables.  These
are intended to be used on the command line with a -DVAR=VALUE.
The values are interpreted as semicolon-separated lists.
This can be skipped if NO_CMAKE_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_PATH to FALSE:

CMAKE_PREFIX_PATH

CMAKE_FRAMEWORK_PATH

CMAKE_APPBUNDLE_PATH

Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration,
and therefore use the host's native path separator
(; on Windows and : on UNIX).
This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed or by setting
the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to FALSE:

<PackageName>_DIR

CMAKE_PREFIX_PATH

CMAKE_FRAMEWORK_PATH

CMAKE_APPBUNDLE_PATH

Search paths specified by the HINTS option.  These should be paths
computed by system introspection, such as a hint provided by the
location of another item already found.  Hard-coded guesses should
be specified with the PATHS option.

Search the standard system environment variables.  This can be
skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed  or by setting the
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE. Path entries
ending in /bin or /sbin are automatically converted to their
parent directories:

PATH

Search paths stored in the CMake User Package Registry.
This can be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed or by
setting the variable CMAKE_FIND_USE_PACKAGE_REGISTRY
to FALSE or the deprecated variable
CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY to TRUE.

See the cmake-packages(7) manual for details on the user
package registry.

Search cmake variables defined in the Platform files for the
current system. The searching of CMAKE_INSTALL_PREFIX and
CMAKE_STAGING_PREFIX can be
skipped if NO_CMAKE_INSTALL_PREFIX is passed or by setting the
CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All these locations
can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by setting the
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE:

CMAKE_SYSTEM_PREFIX_PATH

CMAKE_SYSTEM_FRAMEWORK_PATH

CMAKE_SYSTEM_APPBUNDLE_PATH

The platform paths that these variables contain are locations that
typically include installed software. An example being /usr/local for
UNIX based platforms.

Search paths stored in the CMake System Package Registry.
This can be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed
or by setting the CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY
variable to FALSE or the deprecated variable
CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY to TRUE.

See the cmake-packages(7) manual for details on the system
package registry.

Search paths specified by the PATHS option.  These are typically
hard-coded guesses.

The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
CMAKE_SYSTEM_IGNORE_PATH and
CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables can also cause some
of the above locations to be ignored.

New in version 3.16: Added the CMAKE_FIND_USE_<CATEGORY> variables to globally disable
various search locations.

The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
directories to be prepended to all other search directories.  This
effectively "re-roots" the entire search under given locations.
Paths which are descendants of the CMAKE_STAGING_PREFIX are excluded
from this re-rooting, because that variable is always a path on the host system.
By default the CMAKE_FIND_ROOT_PATH is empty.

The CMAKE_SYSROOT variable can also be used to specify exactly one
directory to use as a prefix.  Setting CMAKE_SYSROOT also has other
effects.  See the documentation for that variable for more.

These variables are especially useful when cross-compiling to
point to the root directory of the target environment and CMake will
search there too.  By default at first the directories listed in
CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT
directory is searched, and then the non-rooted directories will be
searched.  The default behavior can be adjusted by setting
CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.  This behavior can be manually
overridden on a per-call basis using options:

CMAKE_FIND_ROOT_PATH_BOTH

Search in the order described above.

NO_CMAKE_FIND_ROOT_PATH

Do not use the CMAKE_FIND_ROOT_PATH variable.

ONLY_CMAKE_FIND_ROOT_PATH

Search only the re-rooted directories and directories below
CMAKE_STAGING_PREFIX.

The default search order is designed to be most-specific to
least-specific for common use cases.
Projects may override the order by simply calling the command
multiple times and using the NO_* options:

find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH)
find_package (<PackageName>)

Once one of the calls succeeds the result variable will be set
and stored in the cache so that no call will search again.

By default the value stored in the result variable will be the path at
which the file is found.  The CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS
variable may be set to TRUE before calling find_package in order
to resolve symbolic links and store the real path to the file.

Every non-REQUIRED find_package call can be disabled or made REQUIRED:

Setting the CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable
to TRUE disables the package.  This also disables redirection to a
package provided by FetchContent.

Setting the CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> variable
to TRUE makes the package REQUIRED.

Setting both variables to TRUE simultaneously is an error.

Config Mode Version Selection¶

Note

When Config mode is used, this version selection process is applied
regardless of whether the full or
basic signature was given.

When the [version] argument is given, Config mode will only find a
version of the package that claims compatibility with the requested
version (see format specification). If the
EXACT option is given, only a version of the package claiming an exact match
of the requested version may be found.  CMake does not establish any
convention for the meaning of version numbers.  Package version
numbers are checked by "version" files provided by the packages themselves
or by FetchContent.  For a candidate package configuration file
<config-file>.cmake the corresponding version file is located next
to it and named either <config-file>-version.cmake or
<config-file>Version.cmake.  If no such version file is available
then the configuration file is assumed to not be compatible with any
requested version.  A basic version file containing generic version
matching code can be created using the
CMakePackageConfigHelpers module.  When a version file
is found it is loaded to check the requested version number.  The
version file is loaded in a nested scope in which the following
variables have been defined:

PACKAGE_FIND_NAME

The <PackageName>

PACKAGE_FIND_VERSION

Full requested version string

PACKAGE_FIND_VERSION_MAJOR

Major version if requested, else 0

PACKAGE_FIND_VERSION_MINOR

Minor version if requested, else 0

PACKAGE_FIND_VERSION_PATCH

Patch version if requested, else 0

PACKAGE_FIND_VERSION_TWEAK

Tweak version if requested, else 0

PACKAGE_FIND_VERSION_COUNT

Number of version components, 0 to 4

When a version range is specified, the above version variables will hold
values based on the lower end of the version range.  This is to preserve
compatibility with packages that have not been implemented to expect version
ranges.  In addition, the version range will be described by the following
variables:

PACKAGE_FIND_VERSION_RANGE

Full requested version range string

PACKAGE_FIND_VERSION_RANGE_MIN

This specifies whether the lower end point of the version range should be
included or excluded.  Currently, the only supported value for this variable
is INCLUDE.

PACKAGE_FIND_VERSION_RANGE_MAX

This specifies whether the upper end point of the version range should be
included or excluded.  The supported values for this variable are
INCLUDE and EXCLUDE.

PACKAGE_FIND_VERSION_MIN

Full requested version string of the lower end point of the range

PACKAGE_FIND_VERSION_MIN_MAJOR

Major version of the lower end point if requested, else 0

PACKAGE_FIND_VERSION_MIN_MINOR

Minor version of the lower end point if requested, else 0

PACKAGE_FIND_VERSION_MIN_PATCH

Patch version of the lower end point if requested, else 0

PACKAGE_FIND_VERSION_MIN_TWEAK

Tweak version of the lower end point if requested, else 0

PACKAGE_FIND_VERSION_MIN_COUNT

Number of version components of the lower end point, 0 to 4

PACKAGE_FIND_VERSION_MAX

Full requested version string of the upper end point of the range

PACKAGE_FIND_VERSION_MAX_MAJOR

Major version of the upper end point if requested, else 0

PACKAGE_FIND_VERSION_MAX_MINOR

Minor version of the upper end point if requested, else 0

PACKAGE_FIND_VERSION_MAX_PATCH

Patch version of the upper end point if requested, else 0

PACKAGE_FIND_VERSION_MAX_TWEAK

Tweak version of the upper end point if requested, else 0

PACKAGE_FIND_VERSION_MAX_COUNT

Number of version components of the upper end point, 0 to 4

Regardless of whether a single version or a version range is specified, the
variable PACKAGE_FIND_VERSION_COMPLETE will be defined and will hold
the full requested version string as specified.

The version file checks whether it satisfies the requested version and
sets these variables:

PACKAGE_VERSION

Full provided version string

PACKAGE_VERSION_EXACT

True if version is exact match

PACKAGE_VERSION_COMPATIBLE

True if version is compatible

PACKAGE_VERSION_UNSUITABLE

True if unsuitable as any version

These variables are checked by the find_package command to determine
whether the configuration file provides an acceptable version.  They
are not available after the find_package call returns.  If the version
is acceptable the following variables are set:

<PackageName>_VERSION

Full provided version string

<PackageName>_VERSION_MAJOR

Major version if provided, else 0

<PackageName>_VERSION_MINOR

Minor version if provided, else 0

<PackageName>_VERSION_PATCH

Patch version if provided, else 0

<PackageName>_VERSION_TWEAK

Tweak version if provided, else 0

<PackageName>_VERSION_COUNT

Number of version components, 0 to 4

and the corresponding package configuration file is loaded.
When multiple package configuration files are available whose version files
claim compatibility with the version requested it is unspecified which
one is chosen: unless the variable CMAKE_FIND_PACKAGE_SORT_ORDER
is set no attempt is made to choose a highest or closest version number.

To control the order in which find_package checks for compatibility use
the two variables CMAKE_FIND_PACKAGE_SORT_ORDER and
CMAKE_FIND_PACKAGE_SORT_DIRECTION.
For instance in order to select the highest version one can set

SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)

before calling find_package.

Package File Interface Variables¶

When loading a find module or package configuration file find_package
defines variables to provide information about the call arguments (and
restores their original state before returning):

CMAKE_FIND_PACKAGE_NAME

The <PackageName> which is searched for

<PackageName>_FIND_REQUIRED

True if REQUIRED option was given

<PackageName>_FIND_QUIETLY

True if QUIET option was given

<PackageName>_FIND_REGISTRY_VIEW

The requested view if REGISTRY_VIEW option was given

<PackageName>_FIND_VERSION

Full requested version string

<PackageName>_FIND_VERSION_MAJOR

Major version if requested, else 0

<PackageName>_FIND_VERSION_MINOR

Minor version if requested, else 0

<PackageName>_FIND_VERSION_PATCH

Patch version if requested, else 0

<PackageName>_FIND_VERSION_TWEAK

Tweak version if requested, else 0

<PackageName>_FIND_VERSION_COUNT

Number of version components, 0 to 4

<PackageName>_FIND_VERSION_EXACT

True if EXACT option was given

<PackageName>_FIND_COMPONENTS

List of specified components (required and optional)

<PackageName>_FIND_REQUIRED_<c>

True if component <c> is required,
false if component <c> is optional

When a version range is specified, the above version variables will hold
values based on the lower end of the version range.  This is to preserve
compatibility with packages that have not been implemented to expect version
ranges.  In addition, the version range will be described by the following
variables:

<PackageName>_FIND_VERSION_RANGE

Full requested version range string

<PackageName>_FIND_VERSION_RANGE_MIN

This specifies whether the lower end point of the version range is
included or excluded.  Currently, INCLUDE is the only supported value.

<PackageName>_FIND_VERSION_RANGE_MAX

This specifies whether the upper end point of the version range is
included or excluded.  The possible values for this variable are
INCLUDE or EXCLUDE.

<PackageName>_FIND_VERSION_MIN

Full requested version string of the lower end point of the range

<PackageName>_FIND_VERSION_MIN_MAJOR

Major version of the lower end point if requested, else 0

<PackageName>_FIND_VERSION_MIN_MINOR

Minor version of the lower end point if requested, else 0

<PackageName>_FIND_VERSION_MIN_PATCH

Patch version of the lower end point if requested, else 0

<PackageName>_FIND_VERSION_MIN_TWEAK

Tweak version of the lower end point if requested, else 0

<PackageName>_FIND_VERSION_MIN_COUNT

Number of version components of the lower end point, 0 to 4

<PackageName>_FIND_VERSION_MAX

Full requested version string of the upper end point of the range

<PackageName>_FIND_VERSION_MAX_MAJOR

Major version of the upper end point if requested, else 0

<PackageName>_FIND_VERSION_MAX_MINOR

Minor version of the upper end point if requested, else 0

<PackageName>_FIND_VERSION_MAX_PATCH

Patch version of the upper end point if requested, else 0

<PackageName>_FIND_VERSION_MAX_TWEAK

Tweak version of the upper end point if requested, else 0

<PackageName>_FIND_VERSION_MAX_COUNT

Number of version components of the upper end point, 0 to 4

Regardless of whether a single version or a version range is specified, the
variable <PackageName>_FIND_VERSION_COMPLETE will be defined and will hold
the full requested version string as specified.

In Module mode the loaded find module is responsible to honor the
request detailed by these variables; see the find module for details.
In Config mode find_package handles REQUIRED, QUIET, and
[version] options automatically but leaves it to the package
configuration file to handle components in a way that makes sense
for the package.  The package configuration file may set
<PackageName>_FOUND to false to tell find_package that component
requirements are not satisfied.

Table of Contents

find_package

Search Modes

Basic Signature

Full Signature

Config Mode Search Procedure

Config Mode Version Selection

Package File Interface Variables

Previous topic

find_library

Next topic

find_path

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-commands(7) »

find_package

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