fetch_paths.cmake is a lightweight CMake utility for collecting file or directory paths.
It supports recursive searches, regex filtering, and configurable relative paths.
Searches run during CMake configuration. After adding or removing files or directories, rerun CMake to refresh the results; building alone does not discover these changes.
Requires CMake 3.10 or newer. Copy cmake/fetch_paths.cmake into your project's cmake/ directory.
For a project with src/main.cpp as its entry point:
my_app/
CMakeLists.txt
cmake/fetch_paths.cmake
src/main.cpp
Use the following CMakeLists.txt:
cmake_minimum_required(VERSION 3.10)
project(my_app LANGUAGES CXX)
include("${CMAKE_CURRENT_SOURCE_DIR}/cmake/fetch_paths.cmake")
fetch_paths(sources WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src")
add_executable(my_app ${sources})The result is src/main.cpp, relative to the directory containing this CMakeLists.txt.
Keep build and third-party directories outside the search directory, or exclude them explicitly.
A recursive search of the project root can also collect generated sources, such as CMake's compiler identification files.
Alternatively, add the copied directory to the module search path and include the module without the .cmake suffix:
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
include(fetch_paths)fetch_paths(<output_var>
[RELATIVE_PATH <relative_path>]
[WORKING_DIRECTORY <directory>]
[OUTPUT_FILTER_LIST <regex> ...]
[EXCLUDE_FILTER_LIST <regex> ...]
[EXCLUDE_LIST_VAR <var>]
[EXCLUDE_LIST_FILTER_LIST <regex> ...]
[APPEND]
[DISABLE_RECURSION]
[DIRECTORY])| Parameter | Description |
|---|---|
output_var |
Required. Name of the variable that receives the result list; pass the name, not its value. |
RELATIVE_PATH <relative_path> |
Base directory for the returned paths. Relative values are resolved against CMAKE_CURRENT_SOURCE_DIR; the default is CMAKE_CURRENT_SOURCE_DIR. |
WORKING_DIRECTORY <directory> |
Directory to search. Relative values are resolved against CMAKE_CURRENT_SOURCE_DIR; the default is CMAKE_CURRENT_SOURCE_DIR. |
OUTPUT_FILTER_LIST <regex> ... |
Keep paths matching at least one regex. Defaults to .+\.(c|cpp|cc|cxx|C)$ for files, or .* in DIRECTORY mode. |
EXCLUDE_FILTER_LIST <regex> ... |
Remove paths matching any of these regexes after applying the output filters. |
EXCLUDE_LIST_VAR <var> |
Variable that receives paths accepted by the output filters but removed by the exclusion filters, optionally narrowed by EXCLUDE_LIST_FILTER_LIST. It is empty if no exclusion filters are supplied. |
EXCLUDE_LIST_FILTER_LIST <regex> ... |
Keep only excluded paths matching at least one regex. Defaults to .*. This does not change output_var. |
APPEND |
Append new results to output_var instead of replacing it. Duplicates are not removed. |
DISABLE_RECURSION |
Search only the working directory, without searching its subdirectories. |
DIRECTORY |
Return directories instead of files. |
The examples below run from the project root after including the module, using this directory structure. Results are shown as CMake lists, with entries separated by semicolons.
my_app/
src/
main.cpp
util.h
generated/version.cpp
tests/test_main.cpp
platform/windows/native.cpp
Changing WORKING_DIRECTORY does not change the output base:
fetch_paths(sources WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src")sources = src/generated/version.cpp;src/main.cpp;src/tests/test_main.cpp
To return paths relative to src/, set RELATIVE_PATH as well:
fetch_paths(sources
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src"
RELATIVE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/src")sources = generated/version.cpp;main.cpp;tests/test_main.cpp
When passing the result directly to add_executable() in the current CMakeLists.txt, keeping the default base is usually more convenient.
Exclude test and generated sources, but keep only test sources in the exclusion list:
fetch_paths(sources
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src"
EXCLUDE_FILTER_LIST "^src/(generated|tests)/"
EXCLUDE_LIST_VAR excluded_sources
EXCLUDE_LIST_FILTER_LIST "^src/tests/")sources = src/main.cpp
excluded_sources = src/tests/test_main.cpp
src/generated/version.cpp is still excluded from sources; the secondary filter only removes it from excluded_sources.
src/util.h never enters either list because it does not match the default output filter.
Regexes match returned paths, which is why the exclusion patterns start with src/ rather than just tests/ or generated/.
Use APPEND to combine results from separate searches:
fetch_paths(sources
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src"
EXCLUDE_FILTER_LIST "^src/(generated|tests)/")
fetch_paths(sources APPEND
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/platform/windows")sources = src/main.cpp;platform/windows/native.cpp
APPEND does not remove duplicates or reorder existing entries.
If you also specify EXCLUDE_LIST_VAR, that variable receives only the current call's excluded results; it is not appended to.
Supply multiple regexes to group headers before source files:
fetch_paths(files
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src"
OUTPUT_FILTER_LIST "\\.(h|hpp)$" "\\.(c|cpp|cc|cxx|C)$")files = src/util.h;src/generated/version.cpp;src/main.cpp;src/tests/test_main.cpp
Each path belongs to the first matching regex group. Paths within each group are in lexicographical order.
Collect directory paths:
fetch_paths(directories DIRECTORY
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src")directories = src/generated;src/tests
Or collect source files directly inside src/, without searching subdirectories:
fetch_paths(sources DISABLE_RECURSION
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src")sources = src/main.cpp
- Regexes match paths in their returned form, not just filenames. On Windows, if the output base and search directory are on different volumes, absolute paths are returned instead.
- New results are grouped by the first matching output regex, in regex order. Overlapping regexes do not duplicate a path.
APPENDdoes not re-filter or reorder existing entries. - When
EXCLUDE_LIST_VARis specified, its value is replaced on each call, including inAPPENDmode. Secondary exclusion filters group and retain paths in the same way as output filters, without changing the main output. - Directory symlinks are returned only in
DIRECTORYmode and are not searched recursively. File symlinks remain eligible in file mode. - Explicit empty path arguments and empty regex lists use their defaults. Empty entries in an otherwise nonempty regex list are ignored.
Passing
EXCLUDE_LIST_VAR ""disables exclusion output. - A nonexistent working directory returns an empty list. Unknown arguments and keywords with no value at all are errors; this is different from explicitly passing an empty string.
- Output and exclusion variable names must differ.
Names starting with
_fetch_paths_, plusARGC,ARGN,ARGV, andARGVfollowed by one or more digits, are reserved. - Escape regex backslashes in quoted CMake strings, for example
"\\.cpp$", or use bracket arguments such as[=[\.cpp$]=]. A semicolon inside a single regex argument is preserved. - Result paths containing semicolons or unbalanced square brackets cannot be represented reliably in CMake lists and are not supported.
From the repository root:
mkdir build
cd build
cmake ..
cmake --build . --config Debug
ctest -C Debug --output-on-failureThe original assertions also run during configuration. CTest runs those assertions and the boundary regression suite. Symlink checks are skipped with a reason if the environment cannot create symlinks.