Directory

Operations to manipule directories. It requires CMake 3.20 or newer.

Synopsis

directory(SCAN <output_list_var> LIST_DIRECTORIES <on|off> RELATIVE <on|off> ROOT_DIR <directory_path> <INCLUDE_REGEX|EXCLUDE_REGEX> <regular_expression>)
directory(SCAN_DIRS <output_list_var> RECURSE <on|off> RELATIVE <on|off> ROOT_DIR <directory_path> <INCLUDE_REGEX|EXCLUDE_REGEX> <regular_expression>)
directory(FIND_LIB <output_lib_var> FIND_IMPLIB <output_implib_var> NAME <raw_filename> <STATIC|SHARED> RELATIVE <on|off> ROOT_DIR <directory_path>)

Usage

directory(SCAN <output_list_var> LIST_DIRECTORIES <on|off> RELATIVE <on|off> ROOT_DIR <directory_path> <INCLUDE_REGEX|EXCLUDE_REGEX> <regular_expression>)

Recursively scans files and directories under ROOT_DIR, applies an optional filter based on INCLUDE_REGEX or EXCLUDE_REGEX, and stores the result in <output_list_var>.

Paths are returned as relative to ROOT_DIR if RELATIVE is on, or as absolute paths if RELATIVE is off.

If LIST_DIRECTORIES is on, directories are included in the result. If LIST_DIRECTORIES is off, only files are listed.

Example usage:

directory(SCAN result_list
          LIST_DIRECTORIES off
          RELATIVE on
          ROOT_DIR "${CMAKE_CURRENT_SOURCE_DIR}"
          INCLUDE_REGEX ".*[.]cpp$|.*[.]cc$|.*[.]cxx$")
# output is:
#   src/main.cpp;src/util.cpp;lib/module.cpp

directory(SCAN_DIRS <output_list_var> RECURSE <on|off> RELATIVE <on|off> ROOT_DIR <directory_path> <INCLUDE_REGEX|EXCLUDE_REGEX> <regular_expression>)

Scan and collect all directories under ROOT_DIR that match the regular expression provided with either INCLUDE_REGEX or EXCLUDE_REGEX, and store the result in <output_list_var>.

If RECURSE is on, the function traverses subdirectories recursively. If RECURSE is off, only the directories directly under ROOT_DIR are considered.

The paths in the result are returned relative to ROOT_DIR if RELATIVE is on, or as absolute paths if RELATIVE is off.

Example usage:

directory(SCAN_DIRS matched_dirs
          RECURSE on
          RELATIVE on
          ROOT_DIR "${CMAKE_CURRENT_SOURCE_DIR}"
          INCLUDE_REGEX "include")
# output is:
#   src/include;src/lib/include

directory(FIND_LIB <output_lib_var> FIND_IMPLIB <output_implib_var> NAME <raw_filename> <STATIC|SHARED> RELATIVE <on|off> ROOT_DIR <directory_path>)

Search recursively in ROOT_DIR for a library and, on DLL platforms, its import library. The name to search for is given via NAME, which should represent the base name of the library (without prefix or suffix).

The matching uses system-defined prefixes and suffixes depending on the STATIC (by CMAKE_STATIC_LIBRARY_PREFIX and CMAKE_STATIC_LIBRARY_SUFFIX) or SHARED (by CMAKE_SHARED_LIBRARY_PREFIX and CMAKE_SHARED_LIBRARY_SUFFIX) flag, as well as CMAKE_FIND_LIBRARY_PREFIXES and CMAKE_FIND_LIBRARY_SUFFIXES if defined. This makes the behavior similar to find_library(), but more robust.

Note

The different value of prefix and suffix that the variables used to search for libraries can take are:

# With GCC on Windows
# CMAKE_SHARED_LIBRARY_PREFIX: lib
# CMAKE_SHARED_LIBRARY_SUFFIX: .dll
# CMAKE_STATIC_LIBRARY_PREFIX: lib
# CMAKE_STATIC_LIBRARY_SUFFIX: .a
# CMAKE_FIND_LIBRARY_PREFIXES: lib;
# CMAKE_FIND_LIBRARY_SUFFIXES: .dll.a;.a;.lib

# With MSVC on Windows
# CMAKE_SHARED_LIBRARY_PREFIX:
# CMAKE_SHARED_LIBRARY_SUFFIX: .dll
# CMAKE_STATIC_LIBRARY_PREFIX:
# CMAKE_STATIC_LIBRARY_SUFFIX: .lib
# CMAKE_FIND_LIBRARY_PREFIXES: ;lib
# CMAKE_FIND_LIBRARY_SUFFIXES: .dll.lib;.lib;.a

If a matching library is found, its path is stored in <output_lib_var>. If a matching import library is found, its path is stored in <output_implib_var>. If RELATIVE is set to on, the results are relative to ROOT_DIR. Otherwise, absolute paths are returned.

If no match is found, the values will be <output_lib_var>-NOTFOUND and <output_implib_var>-NOTFOUND. If multiple matches are found, a fatal error is raised.

This command is especially useful to locate dependency artifacts when configuring imported targets manually (see also CMake's guide to binary import and export). The resulting paths are typically used to set properties like IMPORTED_LOCATION and IMPORTED_IMPLIB_DEBUG on an imported target, particularly in development or custom build setups where standard find_library() behavior is not sufficient.

Example usage:

directory(FIND_LIB mylib_path
          FIND_IMPLIB mylib_import
          NAME "zlib1"
          SHARED
          RELATIVE on
          ROOT_DIR "${CMAKE_SOURCE_DIR}/libs")
# output is:
#   lib=lib/zlib1.dll
#   implib=lib/zlib1.lib