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 ...]]
          [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.

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:

1. New in version 3.12: 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. Specifically, look in the <PackageName>_ROOT CMake variable and the <PackageName>_ROOT environment variable. 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. See policy CMP0074.

   • <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>)

2. 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

3. 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

4. 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.

5. 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: <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.

6. 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.

7. 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.