A short-hand signature is:
find_file (<VAR> name1 [path1 path2 ...])
The general signature is:
find_file ( <VAR> name | NAMES name1 [name2 ...] [HINTS path1 [path2 ... ENV var]] [PATHS path1 [path2 ... ENV var]] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] [NO_DEFAULT_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_CMAKE_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] [NO_CMAKE_SYSTEM_PATH] [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 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
, and the search will be attempted again the next time find_file is invoked with the same variable.
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
ENV var
sub-option reads paths from a system environment variable.PATH_SUFFIXES
DOC
<VAR>
cache entry.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:
-DVAR=value
. This can be skipped if NO_CMAKE_PATH
is passed.<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
NO_CMAKE_ENVIRONMENT_PATH
is passed.<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
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.NO_SYSTEM_ENVIRONMENT_PATH
is an argument.INCLUDE
, <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
, and the directories in PATH
itself.NO_CMAKE_SYSTEM_PATH
is passed.<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
On OS X 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
NO_CMAKE_FIND_ROOT_PATH
CMAKE_FIND_ROOT_PATH
variable.ONLY_CMAKE_FIND_ROOT_PATH
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.
© 2000–2016 Kitware, Inc.
© 2000–2011 Insight Software Consortium
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.5/command/find_file.html