find_pathΒΆ
A short-hand signature is:
find_path (<VAR> name1 [path1 path2 ...])
The general signature is:
find_path (
          <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 directory containing the 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 file in a directory 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 file in a directory. - 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.- Changed in version 3.24: On - Windowsplatform, 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
- Added in version 3.24. - Specify which registry views must be queried. This option is only meaningful on - Windowsplatforms and will be ignored on other ones. When not specified, the- TARGETview is used when the- CMP0134policy is- NEW. Refer to- CMP0134for 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 ( - 64and- 32) and generate a path for each.
- 32_64
- Query both views ( - 32and- 64) and generate a path for each.
- HOST
- Query the registry matching the architecture of the host: - 64on 64-bit Windows and- 32on 32-bit Windows.
- TARGET
- Query the registry matching the architecture specified by the - CMAKE_SIZEOF_VOID_Pvariable. If not defined, fall back to- HOSTview.
- BOTH
- Query both views ( - 32and- 64). The order depends on the following rules: If the- CMAKE_SIZEOF_VOID_Pvariable is defined, use the following view depending on the content of this variable:- 8:- 64_32
- 4:- 32_64
 - If the - CMAKE_SIZEOF_VOID_Pvariable 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
- Added 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_path (result NAMES ... VALIDATOR my_check)- Note that if a cached result is used, the search is skipped and any - VALIDATORis ignored. The cached result is not required to pass the validation function.
- DOC
- Specify the documentation string for the - <VAR>cache entry.
- NO_CACHE
- Added 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
- Added 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_path 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.- Added in version 3.12. - Specifically, search paths specified by the following variables, in order: - <PackageName>_ROOTCMake variable, where- <PackageName>is the case-preserved package name.
- <PACKAGENAME>_ROOTCMake variable, where- <PACKAGENAME>is the upper-cased package name. See policy- CMP0144.- Added in version 3.27. 
- <PackageName>_ROOTenvironment variable, where- <PackageName>is the case-preserved package name.
- <PACKAGENAME>_ROOTenvironment variable, where- <PACKAGENAME>is the upper-cased package name. See policy- CMP0144.- Added 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_PATHis passed or by setting the- CMAKE_FIND_USE_PACKAGE_ROOT_PATHto- FALSE.- <prefix>/include/<arch>if- CMAKE_LIBRARY_ARCHITECTUREis set, and- <prefix>/includefor each- <prefix>in the- <PackageName>_ROOTCMake variable and the- <PackageName>_ROOTenvironment 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_PATHis passed or by setting the- CMAKE_FIND_USE_CMAKE_PATHto- FALSE.- <prefix>/include/<arch>if- CMAKE_LIBRARY_ARCHITECTUREis set, and- <prefix>/includefor each- <prefix>in- CMAKE_PREFIX_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_PATHis passed or by setting the- CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATHto- FALSE.- <prefix>/include/<arch>if- CMAKE_LIBRARY_ARCHITECTUREis set, and- <prefix>/includefor each- <prefix>in- CMAKE_PREFIX_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 the- PATHSoption.
- Search the standard system environment variables. This can be skipped if - NO_SYSTEM_ENVIRONMENT_PATHis passed or by setting the- CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATHto- FALSE.- The directories in - INCLUDEand- PATH.
 - On Windows hosts, CMake 3.3 through 3.27 searched additional paths: - <prefix>/include/<arch>if- CMAKE_LIBRARY_ARCHITECTUREis set, and- <prefix>/includefor each- <prefix>/[s]binin- PATH, and- <entry>/includefor 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_PREFIXand- CMAKE_STAGING_PREFIXcan be skipped if- NO_CMAKE_INSTALL_PREFIXis passed or by setting the- CMAKE_FIND_USE_INSTALL_PREFIXto- FALSE. All these locations can be skipped if- NO_CMAKE_SYSTEM_PATHis passed or by setting the- CMAKE_FIND_USE_CMAKE_SYSTEM_PATHto- FALSE.- <prefix>/include/<arch>if- CMAKE_LIBRARY_ARCHITECTUREis set, and- <prefix>/includefor each- <prefix>in- CMAKE_SYSTEM_PREFIX_PATH
 - The platform paths that these variables contain are locations that typically include installed software. An example being - /usr/localfor 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.
Added 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_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_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) find_path (<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 searching for frameworks, if the file is specified as A/b.h, then
the framework search will look for A.framework/Headers/b.h.  If that
is found the path will be set to the path to the framework.  CMake
will convert this to the correct -F option to include the file.
