SCOPE_FOR

Specify which scopes must be created.

If SCOPE_FOR is not specified, this is equivalent to:

block(SCOPE_FOR VARIABLES POLICIES)

PROPAGATE

When a variable scope is created by the block() command, this option sets or unsets the specified variables in the parent scope. This is equivalent to set(PARENT_SCOPE) or unset(PARENT_SCOPE) commands.

set(var1 "INIT1")
set(var2 "INIT2")
block(PROPAGATE var1 var2)


  set(var1 "VALUE1")


  unset(var2)
endblock()
# Now var1 holds VALUE1, and var2 is unset

This option is only allowed when a variable scope is created. An error will be raised in the other cases.

• endblock()
• return()
• cmake_policy()

NUMBER_OF_LOGICAL_CORES

Number of logical cores

NUMBER_OF_PHYSICAL_CORES

Number of physical cores

HOSTNAME

Hostname

FQDN

Fully qualified domain name

TOTAL_VIRTUAL_MEMORY

Total virtual memory in MiB [1]

AVAILABLE_VIRTUAL_MEMORY

Available virtual memory in MiB [1]

TOTAL_PHYSICAL_MEMORY

Total physical memory in MiB [1]

AVAILABLE_PHYSICAL_MEMORY

Available physical memory in MiB [1]

IS_64BIT

New in version 3.10.

One if processor is 64Bit

HAS_FPU

New in version 3.10.

One if processor has floating point unit

HAS_MMX

New in version 3.10.

One if processor supports MMX instructions

HAS_MMX_PLUS

New in version 3.10.

One if processor supports Ext. MMX instructions

HAS_SSE

New in version 3.10.

One if processor supports SSE instructions

HAS_SSE2

New in version 3.10.

One if processor supports SSE2 instructions

HAS_SSE_FP

New in version 3.10.

One if processor supports SSE FP instructions

HAS_SSE_MMX

New in version 3.10.

One if processor supports SSE MMX instructions

HAS_AMD_3DNOW

New in version 3.10.

One if processor supports 3DNow instructions

HAS_AMD_3DNOW_PLUS

New in version 3.10.

One if processor supports 3DNow+ instructions

HAS_IA64

New in version 3.10.

One if IA64 processor emulating x86

HAS_SERIAL_NUMBER

New in version 3.10.

One if processor has serial number

PROCESSOR_SERIAL_NUMBER

New in version 3.10.

Processor serial number

PROCESSOR_NAME

New in version 3.10.

Human readable processor name

PROCESSOR_DESCRIPTION

New in version 3.10.

Human readable full processor description

OS_NAME

New in version 3.10.

See CMAKE_HOST_SYSTEM_NAME

OS_RELEASE

New in version 3.10.

The OS sub-type e.g. on Windows Professional

OS_VERSION

New in version 3.10.

The OS build ID

OS_PLATFORM

New in version 3.10.

See CMAKE_HOST_SYSTEM_PROCESSOR

MSYSTEM_PREFIX

New in version 3.28.

Available only on Windows hosts. In a MSYS or MinGW development environment that sets the MSYSTEM environment variable, this is its installation prefix. Otherwise, this is the empty string.

DISTRIB_INFO

New in version 3.22.

Read /etc/os-release file and define the given <variable> into a list of read variables

DISTRIB_<name>

New in version 3.22.

Get the <name> variable (see man 5 os-release) if it exists in the /etc/os-release file

Example:

cmake_host_system_information(RESULT PRETTY_NAME QUERY DISTRIB_PRETTY_NAME)
message(STATUS "${PRETTY_NAME}")
cmake_host_system_information(RESULT DISTRO QUERY DISTRIB_INFO)
foreach(VAR IN LISTS DISTRO)


  message(STATUS "${VAR}=`${${VAR}}`")
endforeach()

Output:

-- Ubuntu 20.04.2 LTS
-- DISTRO_BUG_REPORT_URL=`https://bugs.launchpad.net/ubuntu/`
-- DISTRO_HOME_URL=`https://www.ubuntu.com/`
-- DISTRO_ID=`ubuntu`
-- DISTRO_ID_LIKE=`debian`
-- DISTRO_NAME=`Ubuntu`
-- DISTRO_PRETTY_NAME=`Ubuntu 20.04.2 LTS`
-- DISTRO_PRIVACY_POLICY_URL=`https://www.ubuntu.com/legal/terms-and-policies/privacy-policy`
-- DISTRO_SUPPORT_URL=`https://help.ubuntu.com/`
-- DISTRO_UBUNTU_CODENAME=`focal`
-- DISTRO_VERSION=`20.04.2 LTS (Focal Fossa)`
-- DISTRO_VERSION_CODENAME=`focal`
-- DISTRO_VERSION_ID=`20.04`

CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS

In addition to the scripts shipped with CMake, a user may append full paths to his script(s) to the this list. The script filename has the following format: NNN-<name>.cmake, where NNN is three digits used to apply collected scripts in a specific order.

CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname>

Variables collected by the user provided fallback script ought to be assigned to CMake variables using this naming convention. Example, the ID variable from the manual becomes CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID.

CMAKE_GET_OS_RELEASE_FALLBACK_RESULT

The fallback script ought to store names of all assigned CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname> variables in this list.

• HKLM or HKEY_LOCAL_MACHINE
• HKCU or HKEY_CURRENT_USER
• HKCR or HKEY_CLASSES_ROOT
• HKU or HKEY_USERS
• HKCC or HKEY_CURRENT_CONFIG

VALUE_NAMES

Request the list of value names defined under <key>. If a default value is defined, it will be identified with the special name (default).

SUBKEYS

Request the list of subkeys defined under <key>.

VALUE <name>

Request the data stored in value named <name>. If VALUE is not specified or argument is the special name (default), the content of the default value, if any, will be returned.

# query default value for HKLM/SOFTWARE/Kitware key
cmake_host_system_information(RESULT result


                              QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
# query default value for HKLM/SOFTWARE/Kitware key using special value name
cmake_host_system_information(RESULT result


                              QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware"


                              VALUE "(default)")

Supported types are:

For all other types, an empty string is returned.

VIEW

Specify which registry views must be queried. When not specified, BOTH view is used.

SEPARATOR

Specify the separator character for REG_MULTI_SZ type. When not specified, the character \0 is used.

ERROR_VARIABLE <result>

Returns any error raised during query operation. In case of success, the variable holds an empty string.

cmake_language(CALL <command> [<arg>...])

Calls the named <command> with the given arguments (if any). For example, the code:

set(message_command "message")
cmake_language(CALL ${message_command} STATUS "Hello World!")

is equivalent to

message(STATUS "Hello World!")

NOTE:

cmake_language(EVAL CODE <code>...)

Evaluates the <code>... as CMake code.

For example, the code:

set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")
cmake_language(EVAL CODE "


  if (${condition})


    message(STATUS TRUE)


  else()


    message(STATUS FALSE)


  endif()"
)

is equivalent to

set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "


  if (${condition})


    message(STATUS TRUE)


  else()


    message(STATUS FALSE)


  endif()"
)
include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)

cmake_language(DEFER <options>... CALL <command> [<arg>...])

Schedules a call to the named <command> with the given arguments (if any) to occur at a later time. By default, deferred calls are executed as if written at the end of the current directory's CMakeLists.txt file, except that they run even after a return() call. Variable references in arguments are evaluated at the time the deferred call is executed.

The options are:

The currently scheduled list of deferred calls may be retrieved:

cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)

This will store in <var> a semicolon-separated list of deferred call ids. The ids are for the directory scope in which the calls have been deferred to (i.e. where they will be executed), which can be different to the scope in which they were created. The DIRECTORY option can be used to specify the scope for which to retrieve the call ids. If that option is not given, the call ids for the current directory scope will be returned.

Details of a specific call may be retrieved from its id:

cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)

This will store in <var> a semicolon-separated list in which the first element is the name of the command to be called, and the remaining elements are its unevaluated arguments (any contained ; characters are included literally and cannot be distinguished from multiple arguments). If multiple calls are scheduled with the same id, this retrieves the first one. If no call is scheduled with the given id in the specified DIRECTORY scope (or the current directory scope if no DIRECTORY option is given), this stores an empty string in the variable.

Deferred calls may be canceled by their id:

cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)

This cancels all deferred calls matching any of the given ids in the specified DIRECTORY scope (or the current directory scope if no DIRECTORY option is given). Unknown ids are silently ignored.

cmake_language(SET_DEPENDENCY_PROVIDER <command> SUPPORTED_METHODS <methods>...)

When a call is made to find_package() or FetchContent_MakeAvailable(), the call may be forwarded to a dependency provider which then has the opportunity to fulfill the request. If the request is for one of the <methods> specified when the provider was set, CMake calls the provider's <command> with a set of method-specific arguments. If the provider does not fulfill the request, or if the provider doesn't support the request's method, or no provider is set, the built-in find_package() or FetchContent_MakeAvailable() implementation is used to fulfill the request in the usual way.

One or more of the following values can be specified for the <methods> when setting the provider:

Only one provider can be set at any point in time. If a provider is already set when cmake_language(SET_DEPENDENCY_PROVIDER) is called, the new provider replaces the previously set one. The specified <command> must already exist when cmake_language(SET_DEPENDENCY_PROVIDER) is called. As a special case, providing an empty string for the <command> and no <methods> will discard any previously set provider.

The dependency provider can only be set while processing one of the files specified by the CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable. Thus, dependency providers can only be set as part of the first call to project(). Calling cmake_language(SET_DEPENDENCY_PROVIDER) outside of that context will result in an error.

NOTE:

FIND_PACKAGE

The <method-specific-args> will be everything passed to the find_package() call that requested the dependency. The first of these <method-specific-args> will therefore always be the name of the dependency. Dependency names are case-sensitive for this method because find_package() treats them case-sensitively too.

If the provider command fulfills the request, it must set the same variable that find_package() expects to be set. For a dependency named depName, the provider must set depName_FOUND to true if it fulfilled the request. If the provider returns without setting this variable, CMake will assume the request was not fulfilled and will fall back to the built-in implementation.

If the provider needs to call the built-in find_package() implementation as part of its processing, it can do so by including the BYPASS_PROVIDER keyword as one of the arguments.

FETCHCONTENT_MAKEAVAILABLE_SERIAL

The <method-specific-args> will be everything passed to the FetchContent_Declare() call that corresponds to the requested dependency, with the following exceptions:

The first of the <method-specific-args> will always be the name of the dependency. Dependency names are case-insensitive for this method because FetchContent also treats them case-insensitively.

If the provider fulfills the request, it should call FetchContent_SetPopulated(), passing the name of the dependency as the first argument. The SOURCE_DIR and BINARY_DIR arguments to that command should only be given if the provider makes the dependency's source and build directories available in exactly the same way as the built-in FetchContent_MakeAvailable() command.

If the provider returns without calling FetchContent_SetPopulated() for the named dependency, CMake will assume the request was not fulfilled and will fall back to the built-in implementation.

Note that empty arguments may be significant for this method (e.g. an empty string following a GIT_SUBMODULES keyword). Therefore, if forwarding these arguments on to another command, extra care must be taken to avoid such arguments being silently dropped.

If FETCHCONTENT_SOURCE_DIR_<uppercaseDepName> is set, then the dependency provider will never see requests for the <depName> dependency for this method. When the user sets such a variable, they are explicitly overriding where to get that dependency from and are taking on the responsibility that their overriding version meets any requirements for that dependency and is compatible with whatever else in the project uses it. Depending on the value of FETCHCONTENT_TRY_FIND_PACKAGE_MODE and whether the OVERRIDE_FIND_PACKAGE option was given to FetchContent_Declare(), having FETCHCONTENT_SOURCE_DIR_<uppercaseDepName> set may also prevent the dependency provider from seeing requests for a find_package(depName) call too.

cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)

Writes the current message() logging level into the given <output_variable>.

See message() for the possible logging levels.

The current message logging level can be set either using the --log-level command line option of the cmake(1) program or using the CMAKE_MESSAGE_LOG_LEVEL variable.

If both the command line option and the variable are set, the command line option takes precedence. If neither are set, the default logging level is returned.

cmake_language(EXIT <exit-code>)

Terminate the current cmake -P script and exit with <exit-code>.

This command works only in script mode. If used outside of that context, it will cause a fatal error.

The <exit-code> should be non-negative. If <exit-code> is negative, then the behavior is unspecified (e.g., on Windows the error code -1 becomes 0xffffffff, and on Linux it becomes 255). Exit codes above 255 may not be supported by the underlying shell or platform, and some shells may interpret values above 125 specially. Therefore, it is advisable to only specify an <exit-code> in the range 0 to 125.

•

cmake_policy()

• function()
• macro()

<path-var>

Always the name of a variable. For commands that expect a <path-var> as input, the variable must exist and it is expected to hold a single path.

<input>

A string literal which may contain a path, path fragment, or multiple paths with a special separator depending on the command. See the description of each command to see how this is interpreted.

<input>...

Zero or more string literal arguments.

<out-var>

The name of a variable into which the result of a command will be written.

root-name

Identifies the root on a filesystem with multiple roots (such as "C:" or "//myserver"). It is optional.

root-directory-separator

A directory separator that, if present, indicates that this path is absolute. If it is missing and the first element other than the root-name is an item-name, then the path is relative.

item-name

A sequence of characters that aren't directory separators. This name may identify a file, a hard link, a symbolic link, or a directory. Two special cases are recognized:

The (...)* pattern shown above is to indicate that there can be zero or more item names, with multiple items separated by a directory-separator. The ()* characters are not part of the path.

directory-separator

The only recognized directory separator is a forward slash character /. If this character is repeated, it is treated as a single directory separator. In other words, /usr///////lib is the same as /usr/lib.

filename

A path has a filename if it does not end with a directory-separator. The filename is effectively the last item-name of the path, so it can also be a hard link, symbolic link or a directory.

A filename can have an extension. By default, the extension is defined as the sub-string beginning at the left-most period (including the period) and until the end of the filename. In commands that accept a LAST_ONLY keyword, LAST_ONLY changes the interpretation to the sub-string beginning at the right-most period.

The following exceptions apply to the above interpretation:

The stem is the part of the filename before the extension.

1.

If the path is empty, stop (the normalized form of an empty path is also an empty path).

2.

Replace each directory-separator, which may consist of multiple separators, with a single / (/a///b --> /a/b).

3.

Remove each solitary period (.) and any immediately following directory-separator (/a/./b/. --> /a/b).

4.

Remove each item-name (other than ..) that is immediately followed by a directory-separator and a .., along with any immediately following directory-separator (/a/b/../c --> a/c).

5.

If there is a root-directory, remove any .. and any directory-separators immediately following them. The parent of the root directory is treated as still the root directory (/../a --> /a).

6.

If the last item-name is .., remove any trailing directory-separator (../ --> ..).

7.

If the path is empty by this stage, add a dot (normal form of ./ is .).

• For HAS_ROOT_PATH, a true result will only be returned if at least one of root-name or root-directory is non-empty.
• For HAS_PARENT_PATH, the root directory is also considered to have a parent, which will be itself. The result is true except if the path consists of just a filename.

cmake_policy(VERSION <min>[...<max>])

cmake_policy(SET CMP<NNNN> NEW|OLD)

cmake_policy(GET CMP<NNNN> <variable>)

cmake_policy(PUSH)

Create a new entry on the policy stack.

cmake_policy(POP)

Remove the last policy stack entry created with cmake_policy(PUSH).

•

cmake_minimum_required()

<input>

Path to the input file. A relative path is treated with respect to the value of CMAKE_CURRENT_SOURCE_DIR. The input path must be a file, not a directory.

<output>

Path to the output file or directory. A relative path is treated with respect to the value of CMAKE_CURRENT_BINARY_DIR. If the path names an existing directory the output file is placed in that directory with the same file name as the input file. If the path contains non-existent directories, they are created.

NO_SOURCE_PERMISSIONS

New in version 3.19.

Do not transfer the permissions of the input file to the output file. The copied file permissions default to the standard 644 value (-rw-r--r--).

USE_SOURCE_PERMISSIONS

New in version 3.20.

Transfer the permissions of the input file to the output file. This is already the default behavior if none of the three permissions-related keywords are given (NO_SOURCE_PERMISSIONS, USE_SOURCE_PERMISSIONS or FILE_PERMISSIONS). The USE_SOURCE_PERMISSIONS keyword mostly serves as a way of making the intended behavior clearer at the call site.

FILE_PERMISSIONS <permissions>...

New in version 3.20.

Ignore the input file's permissions and use the specified <permissions> for the output file instead.

COPYONLY

Copy the file without replacing any variable references or other content. This option may not be used with NEWLINE_STYLE.

ESCAPE_QUOTES

Escape any substituted quotes with backslashes (C-style).

@ONLY

Restrict variable replacement to references of the form @VAR@. This is useful for configuring scripts that use ${VAR} syntax.

NEWLINE_STYLE <style>

Specify the newline style for the output file. Specify UNIX or LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n newlines. This option may not be used with COPYONLY.

•

file(GENERATE)

COMMAND

A child process command line.

CMake executes the child process using operating system APIs directly:

No intermediate shell is used, so shell operators such as > are treated as normal arguments. (Use the INPUT_*, OUTPUT_*, and ERROR_* options to redirect stdin, stdout, and stderr.)

For sequential execution of multiple commands use multiple execute_process calls each with a single COMMAND argument.

WORKING_DIRECTORY

The named directory will be set as the current working directory of the child processes.

TIMEOUT

After the specified number of seconds (fractions allowed), all unfinished child processes will be terminated, and the RESULT_VARIABLE will be set to a string mentioning the "timeout".

RESULT_VARIABLE

The variable will be set to contain the result of last child process. This will be an integer return code from the last child or a string describing an error condition.

RESULTS_VARIABLE <variable>

New in version 3.10.

The variable will be set to contain the result of all processes as a semicolon-separated list, in order of the given COMMAND arguments. Each entry will be an integer return code from the corresponding child or a string describing an error condition.

INPUT_FILE <file>

<file> is attached to the standard input pipe of the first COMMAND process.

OUTPUT_FILE <file>

<file> is attached to the standard output pipe of the last COMMAND process.

ERROR_FILE <file>

<file> is attached to the standard error pipe of all COMMAND processes.

OUTPUT_QUIET, ERROR_QUIET

The standard output on OUTPUT_VARIABLE or standard error on ERROR_VARIABLE are not connected (no variable content). The *_FILE and ECHO_*_VARIABLE options are not affected.

OUTPUT_VARIABLE, ERROR_VARIABLE

The variable named will be set with the contents of the standard output and standard error pipes, respectively. If the same variable is named for both pipes their output will be merged in the order produced.

ECHO_OUTPUT_VARIABLE, ECHO_ERROR_VARIABLE

New in version 3.18.

The standard output or standard error will not be exclusively redirected to the specified variables.

The output will be duplicated into the specified variables and also onto standard output or standard error analogous to the tee Unix command.

COMMAND_ECHO <where>

New in version 3.15.

The command being run will be echo'ed to <where> with <where> being set to one of STDERR, STDOUT or NONE. See the CMAKE_EXECUTE_PROCESS_COMMAND_ECHO variable for a way to control the default behavior when this option is not present.

ENCODING <name>

New in version 3.8.

On Windows, the encoding that is used to decode output from the process. Ignored on other platforms. Valid encoding names are:

COMMAND_ERROR_IS_FATAL <ANY|LAST>

New in version 3.19.

The option following COMMAND_ERROR_IS_FATAL determines the behavior when an error is encountered:

file(READ <filename> <variable> [OFFSET <offset>] [LIMIT <max-in>] [HEX])

Read content from a file called <filename> and store it in a <variable>. Optionally start from the given <offset> and read at most <max-in> bytes. The HEX option causes data to be converted to a hexadecimal representation (useful for binary data). If the HEX option is specified, letters in the output (a through f) are in lowercase.

file(STRINGS <filename> <variable> <options>...)

Parse a list of ASCII strings from <filename> and store it in <variable>. Binary data in the file are ignored. Carriage return (\r, CR) characters are ignored. The options are:

New in version 3.2: Added the UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE encodings.

For example, the code

file(STRINGS myfile.txt myfile)

stores a list in the variable myfile in which each item is a line from the input file.

file(<HASH> <filename> <variable>)

Compute a cryptographic hash of the content of <filename> and store it in a <variable>. The supported <HASH> algorithm names are those listed by the string(<HASH>) command.

file(TIMESTAMP <filename> <variable> [<format>] [UTC])

Compute a string representation of the modification time of <filename> and store it in <variable>. Should the command be unable to obtain a timestamp variable will be set to the empty string ("").

See the string(TIMESTAMP) command for documentation of the <format> and UTC options.

file(GET_RUNTIME_DEPENDENCIES [...])

New in version 3.16.

Recursively get the list of libraries depended on by the given files:

file(GET_RUNTIME_DEPENDENCIES


  [RESOLVED_DEPENDENCIES_VAR <deps_var>]


  [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]


  [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]


  [EXECUTABLES <executable_files>...]


  [LIBRARIES <library_files>...]


  [MODULES <module_files>...]


  [DIRECTORIES <directories>...]


  [BUNDLE_EXECUTABLE <bundle_executable_file>]


  [PRE_INCLUDE_REGEXES <regexes>...]


  [PRE_EXCLUDE_REGEXES <regexes>...]


  [POST_INCLUDE_REGEXES <regexes>...]


  [POST_EXCLUDE_REGEXES <regexes>...]


  [POST_INCLUDE_FILES <files>...]


  [POST_EXCLUDE_FILES <files>...]


  )

Please note that this sub-command is not intended to be used in project mode. It is intended for use at install time, either from code generated by the install(RUNTIME_DEPENDENCY_SET) command, or from code provided by the project via install(CODE) or install(SCRIPT). For example:

install(CODE [[


  file(GET_RUNTIME_DEPENDENCIES


    # ...


    )


  ]])

The arguments are as follows:

The following arguments specify filters for including or excluding libraries to be resolved. See below for a full description of how they work.

These arguments can be used to exclude unwanted system libraries when resolving the dependencies, or to include libraries from a specific directory. The filtering works as follows:

Different platforms have different rules for how dependencies are resolved. These specifics are described here.

On Linux platforms, library resolution works as follows:

On Windows platforms, library resolution works as follows:

file(GET_RUNTIME_DEPENDENCIES


  # ...


  PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"


  )

file(GET_RUNTIME_DEPENDENCIES


  # ...


  PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"


  )

On Apple platforms, library resolution works as follows:

This function accepts several variables that determine which tool is used for dependency resolution:

file(WRITE <filename> <content>...)

file(APPEND <filename> <content>...)

Write <content> into a file called <filename>. If the file does not exist, it will be created. If the file already exists, WRITE mode will overwrite it and APPEND mode will append to the end. Any directories in the path specified by <filename> that do not exist will be created.

If the file is a build input, use the configure_file() command to update the file only when its content changes.

file(TOUCH <files>...)

file(TOUCH_NOCREATE <files>...)

New in version 3.12.

Create a file with no content if it does not yet exist. If the file already exists, its access and/or modification will be updated to the time when the function call is executed.

Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file does not exist it will be silently ignored.

With TOUCH and TOUCH_NOCREATE, the contents of an existing file will not be modified.

file(GENERATE [...])

Generate an output file for each build configuration supported by the current CMake Generator. Evaluate generator expressions from the input content to produce the output content.

file(GENERATE OUTPUT <output-file>


     <INPUT <input-file>|CONTENT <content>>


     [CONDITION <expression>] [TARGET <target>]


     [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |


      FILE_PERMISSIONS <permissions>...]


     [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

The options are:

Exactly one CONTENT or INPUT option must be given. A specific OUTPUT file may be named by at most one invocation of file(GENERATE). Generated files are modified and their timestamp updated on subsequent cmake runs only if their content is changed.

Note also that file(GENERATE) does not create the output file until the generation phase. The output file will not yet have been written when the file(GENERATE) command returns, it is written only after processing all of a project's CMakeLists.txt files.

file(CONFIGURE OUTPUT <output-file> CONTENT <content> [ESCAPE_QUOTES] [@ONLY] [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

New in version 3.18.

Generate an output file using the input given by CONTENT and substitute variable values referenced as @VAR@ or ${VAR} contained therein. The substitution rules behave the same as the configure_file() command. In order to match configure_file()'s behavior, generator expressions are not supported for both OUTPUT and CONTENT.

The arguments are:

file(GLOB <variable> [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] <globbing-expressions>...)

file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] <globbing-expressions>...)

Generate a list of files that match the <globbing-expressions> and store it into the <variable>. Globbing expressions are similar to regular expressions, but much simpler. If RELATIVE flag is specified, the results will be returned as relative paths to the given path.

Changed in version 3.6: The results will be ordered lexicographically.

On Windows and macOS, globbing is case-insensitive even if the underlying filesystem is case-sensitive (both filenames and globbing expressions are converted to lowercase before matching). On other platforms, globbing is case-sensitive.

New in version 3.3: By default GLOB lists directories. Directories are omitted in the result if LIST_DIRECTORIES is set to false.

New in version 3.12: If the CONFIGURE_DEPENDS flag is specified, CMake will add logic to the main build system check target to rerun the flagged GLOB commands at build time. If any of the outputs change, CMake will regenerate the build system.

NOTE:

Examples of globbing expressions include:

The GLOB_RECURSE mode will traverse all the subdirectories of the matched directory and match the files. Subdirectories that are symlinks are only traversed if FOLLOW_SYMLINKS is given or policy CMP0009 is not set to NEW.

New in version 3.3: By default GLOB_RECURSE omits directories from result list. Setting LIST_DIRECTORIES to true adds directories to result list. If FOLLOW_SYMLINKS is given or policy CMP0009 is not set to NEW then LIST_DIRECTORIES treats symlinks as directories.

Examples of recursive globbing include:

file(MAKE_DIRECTORY <directories>...)

Create the given directories and their parents as needed.

file(REMOVE <files>...)

file(REMOVE_RECURSE <files>...)

Remove the given files. The REMOVE_RECURSE mode will remove the given files and directories, including non-empty directories. No error is emitted if a given file does not exist. Relative input paths are evaluated with respect to the current source directory.

Changed in version 3.15: Empty input paths are ignored with a warning. Previous versions of CMake interpreted empty strings as a relative path with respect to the current directory and removed its contents.

file(RENAME <oldname> <newname> [RESULT <result>] [NO_REPLACE])

Move a file or directory within a filesystem from <oldname> to <newname>, replacing the destination atomically.

The options are:

file(COPY_FILE <oldname> <newname> [RESULT <result>] [ONLY_IF_DIFFERENT] [INPUT_MAY_BE_RECENT])

New in version 3.21.

Copy a file from <oldname> to <newname>. Directories are not supported. Symlinks are ignored and <oldfile>'s content is read and written to <newname> as a new file.

The options are:

This sub-command has some similarities to configure_file() with the COPYONLY option. An important difference is that configure_file() creates a dependency on the source file, so CMake will be re-run if it changes. The file(COPY_FILE) sub-command does not create such a dependency.

See also the file(COPY) sub-command just below which provides further file-copying capabilities.

file(COPY [...])

file(INSTALL [...])

The COPY signature copies files, directories, and symlinks to a destination folder. Relative input paths are evaluated with respect to the current source directory, and a relative destination is evaluated with respect to the current build directory. Copying preserves input file timestamps, and optimizes out a file if it exists at the destination with the same timestamp. Copying preserves input permissions unless explicit permissions or NO_SOURCE_PERMISSIONS are given (default is USE_SOURCE_PERMISSIONS).

file(<COPY|INSTALL> <files>... DESTINATION <dir>


     [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]


     [FILE_PERMISSIONS <permissions>...]


     [DIRECTORY_PERMISSIONS <permissions>...]


     [FOLLOW_SYMLINK_CHAIN]


     [FILES_MATCHING]


     [[PATTERN <pattern> | REGEX <regex>]


      [EXCLUDE] [PERMISSIONS <permissions>...]] [...])

NOTE:

New in version 3.15: If FOLLOW_SYMLINK_CHAIN is specified, COPY will recursively resolve the symlinks at the paths given until a real file is found, and install a corresponding symlink in the destination for each symlink encountered. For each symlink that is installed, the resolution is stripped of the directory, leaving only the filename, meaning that the new symlink points to a file in the same directory as the symlink. This feature is useful on some Unix systems, where libraries are installed as a chain of symlinks with version numbers, with less specific versions pointing to more specific versions. FOLLOW_SYMLINK_CHAIN will install all of these symlinks and the library itself into the destination directory. For example, if you have the following directory structure:

and you do:

file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)

This will install all of the symlinks and libfoo.so.1.2.3 itself into lib.

See the install(DIRECTORY) command for documentation of permissions, FILES_MATCHING, PATTERN, REGEX, and EXCLUDE options. Copying directories preserves the structure of their content even if options are used to select a subset of files.

The INSTALL signature differs slightly from COPY: it prints status messages, and NO_SOURCE_PERMISSIONS is default. Installation scripts generated by the install() command use this signature (with some undocumented options for internal use).

Changed in version 3.22: The environment variable CMAKE_INSTALL_MODE can override the default copying behavior of file(INSTALL).

file(SIZE <filename> <variable>)

New in version 3.14.

Determine the file size of the <filename> and put the result in <variable> variable. Requires that <filename> is a valid path pointing to a file and is readable.

file(READ_SYMLINK <linkname> <variable>)

New in version 3.14.

Query the symlink <linkname> and stores the path it points to in the result <variable>. If <linkname> does not exist or is not a symlink, CMake issues a fatal error.

Note that this command returns the raw symlink path and does not resolve a relative path. The following is an example of how to ensure that an absolute path is obtained:

set(linkname "/path/to/foo.sym")
file(READ_SYMLINK "${linkname}" result)
if(NOT IS_ABSOLUTE "${result}")


  get_filename_component(dir "${linkname}" DIRECTORY)


  set(result "${dir}/${result}")
endif()

file(CREATE_LINK <original> <linkname> [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])

New in version 3.14.

Create a link <linkname> that points to <original>. It will be a hard link by default, but providing the SYMBOLIC option results in a symbolic link instead. Hard links require that original exists and is a file, not a directory. If <linkname> already exists, it will be overwritten.

The <result> variable, if specified, receives the status of the operation. It is set to 0 upon success or an error message otherwise. If RESULT is not specified and the operation fails, a fatal error is emitted.

Specifying COPY_ON_ERROR enables copying the file as a fallback if creating the link fails. It can be useful for handling situations such as <original> and <linkname> being on different drives or mount points, which would make them unable to support a hard link.

file(CHMOD <files>... <directories>... [PERMISSIONS <permissions>...] [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...])

New in version 3.19.

Set the permissions for the <files>... and <directories>... specified. Valid permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID, SETGID.

Valid combination of keywords are:

file(CHMOD_RECURSE <files>... <directories>... [PERMISSIONS <permissions>...] [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...])

New in version 3.19.

Same as CHMOD, but change the permissions of files and directories present in the <directories>... recursively.

file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])

New in version 3.19.

Compute the absolute path to an existing file or directory with symlinks resolved. The options are:

Changed in version 3.28: All symlinks are resolved before collapsing ../ components. See policy CMP0152.

file(RELATIVE_PATH <variable> <directory> <file>)

Compute the relative path from a <directory> to a <file> and store it in the <variable>.

file(TO_CMAKE_PATH "<path>" <variable>)

file(TO_NATIVE_PATH "<path>" <variable>)

The TO_CMAKE_PATH mode converts a native <path> into a cmake-style path with forward-slashes (/). The input can be a single path or a system search path like $ENV{PATH}. A search path will be converted to a cmake-style list separated by ; characters.

The TO_NATIVE_PATH mode converts a cmake-style <path> into a native path with platform-specific slashes (\ on Windows hosts and / elsewhere).

Always use double quotes around the <path> to be sure it is treated as a single argument to this command.

file(DOWNLOAD <url> [<file>] <options>...)

file(UPLOAD <file> <url> <options>...)

The DOWNLOAD subcommand downloads the given <url> to a local <file>. The UPLOAD mode uploads a local <file> to a given <url>.

New in version 3.19: If <file> is not specified for file(DOWNLOAD), the file is not saved. This can be useful if you want to know if a file can be downloaded (for example, to check that it exists) without actually saving it anywhere.

Options to both DOWNLOAD and UPLOAD are:

file(DOWNLOAD <url>


     HTTPHEADER "Authorization: Bearer <auth-token>"


     HTTPHEADER "UserAgent: Mozilla/5.0")

For https:// URLs CMake must be built with OpenSSL support. TLS/SSL certificates are not checked by default. Set TLS_VERIFY to ON to check certificates.

Additional options to DOWNLOAD are:

file(LOCK <path> [DIRECTORY] [RELEASE] [GUARD <FUNCTION|FILE|PROCESS>] [RESULT_VARIABLE <variable>] [TIMEOUT <seconds>])

New in version 3.2.

Lock a file specified by <path> if no DIRECTORY option present and file <path>/cmake.lock otherwise. The file will be locked for the scope defined by the GUARD option (default value is PROCESS). The RELEASE option can be used to unlock the file explicitly. If the TIMEOUT option is not specified, CMake will wait until the lock succeeds or until a fatal error occurs. If TIMEOUT is set to 0, locking will be tried once and the result will be reported immediately. If TIMEOUT is not 0, CMake will try to lock the file for the period specified by the TIMEOUT <seconds> value. Any errors will be interpreted as fatal if there is no RESULT_VARIABLE option. Otherwise, the result will be stored in <variable> and will be 0 on success or an error message on failure.

Note that lock is advisory; there is no guarantee that other processes will respect this lock, i.e. lock synchronize two or more CMake instances sharing some modifiable resources. Similar logic applies to the DIRECTORY option; locking a parent directory doesn't prevent other LOCK commands from locking any child directory or file.

Trying to lock the same file twice is not allowed. Any intermediate directories and the file itself will be created if they not exist. The GUARD and TIMEOUT options are ignored on the RELEASE operation.

file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [FORMAT <format>] [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]] [MTIME <mtime>] [VERBOSE])

New in version 3.18.

Creates the specified <archive> file with the files and directories listed in <paths>. Note that <paths> must list actual files or directories; wildcards are not supported.

Use the FORMAT option to specify the archive format. Supported values for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is not given, the default format is paxr.

Some archive formats allow the type of compression to be specified. The 7zip and zip archive formats already imply a specific type of compression. The other formats use no compression by default, but can be directed to do so with the COMPRESSION option. Valid values for <compression> are None, BZip2, GZip, XZ, and Zstd.

New in version 3.19: The compression level can be specified with the COMPRESSION_LEVEL option. The <compression-level> should be between 0-9, with the default being 0. The COMPRESSION option must be present when COMPRESSION_LEVEL is given.

New in version 3.26: The <compression-level> of the Zstd algorithm can be set between 0-19.

NOTE:

The VERBOSE option enables verbose output for the archive operation.

To specify the modification time recorded in tarball entries, use the MTIME option.

file(ARCHIVE_EXTRACT INPUT <archive> [DESTINATION <dir>] [PATTERNS <patterns>...] [LIST_ONLY] [VERBOSE] [TOUCH])

New in version 3.18.

Extracts or lists the content of the specified <archive>.

The directory where the content of the archive will be extracted to can be specified using the DESTINATION option. If the directory does not exist, it will be created. If DESTINATION is not given, the current binary directory will be used.

If required, you may select which files and directories to list or extract from the archive using the specified <patterns>. Wildcards are supported. If the PATTERNS option is not given, the entire archive will be listed or extracted.

LIST_ONLY will list the files in the archive rather than extract them.

NOTE:

New in version 3.24: The TOUCH option gives extracted files a current local timestamp instead of extracting file timestamps from the archive.

With VERBOSE, the command will produce verbose output.

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.

PATH_SUFFIXES

Specify additional subdirectories to check below each directory location otherwise considered.

VALIDATOR

New 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_file (result NAMES ... VALIDATOR my_check)

Note that if a cached result is used, the search is skipped and any VALIDATOR is ignored. The cached result is not required to pass the validation function.

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:

WARNING:

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.

1.

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.

New in version 3.12.

Specifically, search paths specified by the following variables, in order:

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.

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.

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.

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.

On Windows hosts, CMake 3.3 through 3.27 searched additional paths: <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. This behavior was removed by CMake 3.28.

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.

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.

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.

NAMES

Specify one or more possible names for the library.

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.

PATH_SUFFIXES

Specify additional subdirectories to check below each directory location otherwise considered.

VALIDATOR

New 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_library (result NAMES ... VALIDATOR my_check)

Note that if a cached result is used, the search is skipped and any VALIDATOR is ignored. The cached result is not required to pass the validation function.

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:

WARNING:

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_library is invoked with the same variable.

1.

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.

New in version 3.12.

Specifically, search paths specified by the following variables, in order:

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.

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.

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.

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.

On Windows hosts, CMake 3.3 through 3.27 searched additional paths: <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/lib for each <prefix>/[s]bin in PATH, and <entry>/lib for other entries in PATH. This behavior was removed by CMake 3.28.

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.

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.

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.

Module mode

In this mode, CMake searches for a file called Find<PackageName>.cmake, looking first in the locations listed in the CMAKE_MODULE_PATH, then among the Find Modules provided by the CMake installation. If the file is found, it is read and processed by CMake. It is responsible for finding the package, checking the version, and producing any needed messages. Some Find modules provide limited or no support for versioning; check the Find module's documentation.

The Find<PackageName>.cmake file is not typically provided by the package itself. Rather, it is normally provided by something external to the package, such as the operating system, CMake itself, or even the project from which the find_package() command was called. Being externally provided, Find Modules tend to be heuristic in nature and are susceptible to becoming out-of-date. They typically search for certain libraries, files and other package artifacts.

Module mode is only supported by the basic command signature.

Config mode

In this mode, CMake searches for a file called <lowercasePackageName>-config.cmake or <PackageName>Config.cmake. It will also look for <lowercasePackageName>-config-version.cmake or <PackageName>ConfigVersion.cmake if version details were specified (see Config Mode Version Selection for an explanation of how these separate version files are used).

In config mode, the command can be given a list of names to search for as package names. The locations where CMake searches for the config and version files is considerably more complicated than for Module mode (see Config Mode Search Procedure).

The config and version files are typically installed as part of the package, so they tend to be more reliable than Find modules. They usually contain direct knowledge of the package contents, so no searching or heuristics are needed within the config or version files themselves.

Config mode is supported by both the basic and full command signatures.

FetchContent redirection mode

New in version 3.24: A call to find_package() can be redirected internally to a package provided by the FetchContent module. To the caller, the behavior will appear similar to Config mode, except that the search logic is by-passed and the component information is not used. See FetchContent_Declare() and FetchContent_MakeAvailable() for further details.

lib/<arch>

Searched if the CMAKE_LIBRARY_ARCHITECTURE variable is set.

lib64

Searched on 64 bit platforms (CMAKE_SIZEOF_VOID_P is 8) and the FIND_LIBRARY_USE_LIB64_PATHS property is set to TRUE.

lib32

Searched on 32 bit platforms (CMAKE_SIZEOF_VOID_P is 4) and the FIND_LIBRARY_USE_LIB32_PATHS property is set to TRUE.

libx32

Searched on platforms using the x32 ABI if the FIND_LIBRARY_USE_LIBX32_PATHS property is set to TRUE.

lib

Always searched.

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:

If the CMAKE_SIZEOF_VOID_P variable is not defined, rely on the architecture of the host:

1.

Search prefixes unique to the current <PackageName> being found. See policy CMP0074.

New in version 3.12.

Specifically, search prefixes specified by the following variables, in order:

The package root variables are maintained as a stack so if called from within a find module, root paths from the parent's find module will also be searched after paths for the current package. This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE.

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:

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:

4.

Search 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. Path entries ending in /bin or /sbin are automatically converted to their parent directories:

6.

Search paths stored in the CMake User Package Registry. This can be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed or by setting the variable CMAKE_FIND_USE_PACKAGE_REGISTRY to FALSE or the deprecated variable CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY to TRUE.

See the cmake-packages(7) manual for details on the user package registry.

7.

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:

The platform paths that these variables contain are locations that typically include installed software. An example being /usr/local for UNIX based platforms.

8.

Search paths stored in the CMake System Package Registry. This can be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed or by setting the CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable to FALSE or the deprecated variable CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY to TRUE.

See the cmake-packages(7) manual for details on the system package registry.

9.

Search paths specified by the PATHS option. These are typically hard-coded guesses.

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.

• Setting the CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to TRUE disables the package. This also disables redirection to a package provided by FetchContent.
• Setting the CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> variable to TRUE makes the package REQUIRED.

PACKAGE_FIND_NAME

The <PackageName>

PACKAGE_FIND_VERSION

Full requested version string

PACKAGE_FIND_VERSION_MAJOR

Major version if requested, else 0

PACKAGE_FIND_VERSION_MINOR

Minor version if requested, else 0

PACKAGE_FIND_VERSION_PATCH

Patch version if requested, else 0

PACKAGE_FIND_VERSION_TWEAK

Tweak version if requested, else 0

PACKAGE_FIND_VERSION_COUNT

Number of version components, 0 to 4

PACKAGE_FIND_VERSION_RANGE

Full requested version range string

PACKAGE_FIND_VERSION_RANGE_MIN

This specifies whether the lower end point of the version range should be included or excluded. Currently, the only supported value for this variable is INCLUDE.

PACKAGE_FIND_VERSION_RANGE_MAX

This specifies whether the upper end point of the version range should be included or excluded. The supported values for this variable are INCLUDE and EXCLUDE.

PACKAGE_FIND_VERSION_MIN

Full requested version string of the lower end point of the range

PACKAGE_FIND_VERSION_MIN_MAJOR

Major version of the lower end point if requested, else 0

PACKAGE_FIND_VERSION_MIN_MINOR

Minor version of the lower end point if requested, else 0

PACKAGE_FIND_VERSION_MIN_PATCH

Patch version of the lower end point if requested, else 0

PACKAGE_FIND_VERSION_MIN_TWEAK

Tweak version of the lower end point if requested, else 0

PACKAGE_FIND_VERSION_MIN_COUNT

Number of version components of the lower end point, 0 to 4

PACKAGE_FIND_VERSION_MAX

Full requested version string of the upper end point of the range

PACKAGE_FIND_VERSION_MAX_MAJOR

Major version of the upper end point if requested, else 0

PACKAGE_FIND_VERSION_MAX_MINOR

Minor version of the upper end point if requested, else 0

PACKAGE_FIND_VERSION_MAX_PATCH

Patch version of the upper end point if requested, else 0

PACKAGE_FIND_VERSION_MAX_TWEAK

Tweak version of the upper end point if requested, else 0

PACKAGE_FIND_VERSION_MAX_COUNT

Number of version components of the upper end point, 0 to 4

PACKAGE_VERSION

Full provided version string

PACKAGE_VERSION_EXACT

True if version is exact match

PACKAGE_VERSION_COMPATIBLE

True if version is compatible

PACKAGE_VERSION_UNSUITABLE

True if unsuitable as any version

<PackageName>_VERSION

Full provided version string

<PackageName>_VERSION_MAJOR

Major version if provided, else 0

<PackageName>_VERSION_MINOR

Minor version if provided, else 0

<PackageName>_VERSION_PATCH

Patch version if provided, else 0

<PackageName>_VERSION_TWEAK

Tweak version if provided, else 0

<PackageName>_VERSION_COUNT

Number of version components, 0 to 4

CMAKE_FIND_PACKAGE_NAME

The <PackageName> which is searched for

<PackageName>_FIND_REQUIRED

True if REQUIRED option was given

<PackageName>_FIND_QUIETLY

True if QUIET option was given

<PackageName>_FIND_REGISTRY_VIEW

The requested view if REGISTRY_VIEW option was given

<PackageName>_FIND_VERSION

Full requested version string

<PackageName>_FIND_VERSION_MAJOR

Major version if requested, else 0

<PackageName>_FIND_VERSION_MINOR

Minor version if requested, else 0

<PackageName>_FIND_VERSION_PATCH

Patch version if requested, else 0

<PackageName>_FIND_VERSION_TWEAK

Tweak version if requested, else 0

<PackageName>_FIND_VERSION_COUNT

Number of version components, 0 to 4

<PackageName>_FIND_VERSION_EXACT

True if EXACT option was given

<PackageName>_FIND_COMPONENTS

List of specified components (required and optional)

<PackageName>_FIND_REQUIRED_<c>

True if component <c> is required, false if component <c> is optional

<PackageName>_FIND_VERSION_RANGE

Full requested version range string

<PackageName>_FIND_VERSION_RANGE_MIN

This specifies whether the lower end point of the version range is included or excluded. Currently, INCLUDE is the only supported value.

<PackageName>_FIND_VERSION_RANGE_MAX

This specifies whether the upper end point of the version range is included or excluded. The possible values for this variable are INCLUDE or EXCLUDE.

<PackageName>_FIND_VERSION_MIN

Full requested version string of the lower end point of the range

<PackageName>_FIND_VERSION_MIN_MAJOR

Major version of the lower end point if requested, else 0

<PackageName>_FIND_VERSION_MIN_MINOR

Minor version of the lower end point if requested, else 0

<PackageName>_FIND_VERSION_MIN_PATCH

Patch version of the lower end point if requested, else 0

<PackageName>_FIND_VERSION_MIN_TWEAK

Tweak version of the lower end point if requested, else 0

<PackageName>_FIND_VERSION_MIN_COUNT

Number of version components of the lower end point, 0 to 4

<PackageName>_FIND_VERSION_MAX

Full requested version string of the upper end point of the range

<PackageName>_FIND_VERSION_MAX_MAJOR

Major version of the upper end point if requested, else 0

<PackageName>_FIND_VERSION_MAX_MINOR

Minor version of the upper end point if requested, else 0

<PackageName>_FIND_VERSION_MAX_PATCH

Patch version of the upper end point if requested, else 0

<PackageName>_FIND_VERSION_MAX_TWEAK

Tweak version of the upper end point if requested, else 0

<PackageName>_FIND_VERSION_MAX_COUNT

Number of version components of the upper end point, 0 to 4

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

PATH_SUFFIXES

Specify additional subdirectories to check below each directory location otherwise considered.

VALIDATOR

New 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 VALIDATOR is ignored. The cached result is not required to pass the validation function.

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:

WARNING:

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_path is invoked with the same variable.

1.

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.

New in version 3.12.

Specifically, search paths specified by the following variables, in order:

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.

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.

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.

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.

On Windows hosts, CMake 3.3 through 3.27 searched additional paths: <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. This behavior was removed by CMake 3.28.

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.

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.

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.

NAMES

Specify one or more possible names for the program.

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 BOTH view is used when the CMP0134 policy is NEW. Refer to CMP0134 for the default view when the policy is OLD.

PATH_SUFFIXES

Specify additional subdirectories to check below each directory location otherwise considered.

VALIDATOR

New 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_program (result NAMES ... VALIDATOR my_check)

Note that if a cached result is used, the search is skipped and any VALIDATOR is ignored. The cached result is not required to pass the validation function.

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:

WARNING:

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_program is invoked with the same variable.

1.

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.

New in version 3.12.

Specifically, search paths specified by the following variables, in order:

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.

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.

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.

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.

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.

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.

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.

• if the only loop_var given, then it sets a series of loop_var_N variables to the current item from the corresponding list;
• if multiple variable names passed, their count should match the lists variables count;
• if any of the lists are shorter, the corresponding iteration variable is not defined for the current iteration.

• break()
• continue()
• endforeach()
• while()

• cmake_parse_arguments()
• endfunction()
• return()

•

the get_property() command GLOBAL option

• define_property()
• the more general get_property() command

•

cmake_path()

GLOBAL

Scope is unique and does not accept a name.

DIRECTORY

Scope defaults to the current directory but another directory (already processed by CMake) may be named by the full or relative path <dir>. Relative paths are treated as relative to the current source directory. See also the get_directory_property() command.

New in version 3.19: <dir> may reference a binary directory.

TARGET

Scope must name one existing target. See also the get_target_property() command.

SOURCE

Scope must name one source file. By default, the source file's property will be read from the current source directory's scope.

New in version 3.18: Directory scope can be overridden with one of the following sub-options:

See also the get_source_file_property() command.

INSTALL

New in version 3.1.

Scope must name one installed file path.

TEST

Scope must name one existing test. See also the get_test_property() command.

New in version 3.28: Directory scope can be overridden with the following sub-option:

CACHE

Scope must name one cache entry.

VARIABLE

Scope is unique and does not accept a name.

• define_property()
• set_property()

1.

Parentheses.

2.

Unary tests such as EXISTS, COMMAND, and DEFINED.

3.

Binary tests such as EQUAL, LESS, LESS_EQUAL, GREATER, GREATER_EQUAL, STREQUAL, STRLESS, STRLESS_EQUAL, STRGREATER, STRGREATER_EQUAL, VERSION_EQUAL, VERSION_LESS, VERSION_LESS_EQUAL, VERSION_GREATER, VERSION_GREATER_EQUAL, PATH_EQUAL, and MATCHES.

4.

Unary logical operator NOT.

5.

Binary logical operators AND and OR, from left to right, without any short-circuit.

if(<constant>)

True if the constant is 1, ON, YES, TRUE, Y, or a non-zero number (including floating point numbers). False if the constant is 0, OFF, NO, FALSE, N, IGNORE, NOTFOUND, the empty string, or ends in the suffix -NOTFOUND. Named boolean constants are case-insensitive. If the argument is not one of these specific constants, it is treated as a variable or string (see Variable Expansion further below) and one of the following two forms applies.

if(<variable>)

True if given a variable that is defined to a value that is not a false constant. False otherwise, including if the variable is undefined. Note that macro arguments are not variables. Environment Variables also cannot be tested this way, e.g. if(ENV{some_var}) will always evaluate to false.

if(<string>)

A quoted string always evaluates to false unless:

if(NOT <condition>)

True if the condition is not true.

if(<cond1> AND <cond2>)

True if both conditions would be considered true individually.

if(<cond1> OR <cond2>)

True if either condition would be considered true individually.

if((condition) AND (condition OR (condition)))

The conditions inside the parenthesis are evaluated first and then the remaining condition is evaluated as in the other examples. Where there are nested parenthesis the innermost are evaluated as part of evaluating the condition that contains them.

if(COMMAND <command-name>)

True if the given name is a command, macro or function that can be invoked.

if(POLICY <policy-id>)

True if the given name is an existing policy (of the form CMP<NNNN>).

if(TARGET <target-name>)

True if the given name is an existing logical target name created by a call to the add_executable(), add_library(), or add_custom_target() command that has already been invoked (in any directory).

if(TEST <test-name>)

New in version 3.3.

True if the given name is an existing test name created by the add_test() command.

if(DEFINED <name>|CACHE{<name>}|ENV{<name>})

New in version 3.14: Added support for CACHE{<name>} variables.

if(<variable|string> IN_LIST <variable>)

New in version 3.3.

True if the given element is contained in the named list variable.

if(EXISTS <path-to-file-or-directory>)

True if the named file or directory exists and is readable. Behavior is well-defined only for explicit full paths (a leading ~/ is not expanded as a home directory and is considered a relative path). Resolves symbolic links, i.e. if the named file or directory is a symbolic link, returns true if the target of the symbolic link exists.

False if the given path is an empty string.

NOTE:

if(IS_READABLE <path-to-file-or-directory>)

New in version 3.29.

True if the named file or directory is readable. Behavior is well-defined only for explicit full paths (a leading ~/ is not expanded as a home directory and is considered a relative path). Resolves symbolic links, i.e. if the named file or directory is a symbolic link, returns true if the target of the symbolic link is readable.

False if the given path is an empty string.