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:
NAMESSpecify 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 varsub-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_PATHis passed.<prefix>/include/<arch>ifCMAKE_LIBRARY_ARCHITECTUREis set, and<prefix>/includefor each<prefix>inCMAKE_PREFIX_PATHCMAKE_INCLUDE_PATHCMAKE_FRAMEWORK_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_PATHis passed.<prefix>/include/<arch>ifCMAKE_LIBRARY_ARCHITECTUREis set, and<prefix>/includefor each<prefix>inCMAKE_PREFIX_PATHCMAKE_INCLUDE_PATHCMAKE_FRAMEWORK_PATH
- Search the paths specified by the
HINTSoption. 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 thePATHSoption. - Search the standard system environment variables.
This can be skipped if
NO_SYSTEM_ENVIRONMENT_PATHis an argument.- Directories in
INCLUDE,<prefix>/include/<arch>ifCMAKE_LIBRARY_ARCHITECTUREis set, and<prefix>/includefor each<prefix>/[s]bininPATH, and<entry>/includefor other entries inPATH, and the directories inPATHitself.
- Directories in
- Search cmake variables defined in the Platform files
for the current system. This can be skipped if
NO_CMAKE_SYSTEM_PATHis passed.<prefix>/include/<arch>ifCMAKE_LIBRARY_ARCHITECTUREis set, and<prefix>/includefor each<prefix>inCMAKE_SYSTEM_PREFIX_PATHCMAKE_SYSTEM_INCLUDE_PATHCMAKE_SYSTEM_FRAMEWORK_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_PATHvariable. 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.