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 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
Specify directories to search in addition to the default locations. The
ENV var
sub-option reads paths from a system environment variable.PATH_SUFFIXES
Specify additional subdirectories to check below each directory location otherwise considered.
DOC
Specify the documentation string for the
<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:
Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a
-DVAR=value
. This can be skipped ifNO_CMAKE_PATH
is passed.<prefix>/include/<arch>
ifCMAKE_LIBRARY_ARCHITECTURE
is set, and<prefix>/include
for each<prefix>
inCMAKE_PREFIX_PATH
Search paths specified in cmake-specific environment variables. These are intended to be set in the user’s shell configuration. This can be skipped if
NO_CMAKE_ENVIRONMENT_PATH
is passed.<prefix>/include/<arch>
ifCMAKE_LIBRARY_ARCHITECTURE
is set, and<prefix>/include
for each<prefix>
inCMAKE_PREFIX_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 thePATHS
option.Search the standard system environment variables. This can be skipped if
NO_SYSTEM_ENVIRONMENT_PATH
is an argument.Directories in
INCLUDE
. On Windows hosts:<prefix>/include/<arch>
ifCMAKE_LIBRARY_ARCHITECTURE
is set, and<prefix>/include
for each<prefix>/[s]bin
inPATH
, and<entry>/include
for other entries inPATH
, and the directories inPATH
itself.
Search cmake variables defined in the Platform files for the current system. This can be skipped if
NO_CMAKE_SYSTEM_PATH
is passed.<prefix>/include/<arch>
ifCMAKE_LIBRARY_ARCHITECTURE
is set, and<prefix>/include
for each<prefix>
inCMAKE_SYSTEM_PREFIX_PATH
Search the paths specified by the PATHS option or in the short-hand version of the command. These are typically hard-coded guesses.
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
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.