Skip to content

About

fetch_paths() is a smart CMake function that quickly retrieves files or directories using powerful regex filtering and flexible search modes to streamline your build process.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

28 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

fetch_paths.cmake

中文

Introduction

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.

Quick Start

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)

Function Prototype

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

Parameters

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.

Examples

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

Search Directory and Output Base

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 Files and Inspect the Exclusion List

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

Append Another Directory

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.

Filter and Group by File Type

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.

Directories and Non-Recursive Searches

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

Behavior and Limitations

  • 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. APPEND does not re-filter or reorder existing entries.
  • When EXCLUDE_LIST_VAR is specified, its value is replaced on each call, including in APPEND mode. 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 DIRECTORY mode 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_, plus ARGC, ARGN, ARGV, and ARGV followed 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.

Running Tests

From the repository root:

mkdir build
cd build
cmake ..
cmake --build . --config Debug
ctest -C Debug --output-on-failure

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

About

fetch_paths() is a smart CMake function that quickly retrieves files or directories using powerful regex filtering and flexible search modes to streamline your build process.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages