From 6c4f8b4596fb48f5eeea905b7fbdd9350b9e7838 Mon Sep 17 00:00:00 2001 From: Shane Parris Date: Wed, 14 Feb 2018 11:36:12 -0500 Subject: Adjust help documentation for file(GLOB), add topic notes --- Help/command/file.rst | 13 +++++++++++-- Help/release/dev/glob_configure_depends.rst | 6 ++++++ 2 files changed, 17 insertions(+), 2 deletions(-) create mode 100644 Help/release/dev/glob_configure_depends.rst diff --git a/Help/command/file.rst b/Help/command/file.rst index 5e18077..43ce3d9 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -98,10 +98,10 @@ command. :: file(GLOB - [LIST_DIRECTORIES true|false] [RELATIVE ] + [LIST_DIRECTORIES true|false] [RELATIVE ] [CONFIGURE_DEPENDS] [...]) file(GLOB_RECURSE [FOLLOW_SYMLINKS] - [LIST_DIRECTORIES true|false] [RELATIVE ] + [LIST_DIRECTORIES true|false] [RELATIVE ] [CONFIGURE_DEPENDS] [...]) Generate a list of files that match the ```` and @@ -110,6 +110,11 @@ regular expressions, but much simpler. If ``RELATIVE`` flag is specified, the results will be returned as relative paths to the given path. The results will be ordered lexicographically. +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. + By default ``GLOB`` lists directories - directories are omitted in result if ``LIST_DIRECTORIES`` is set to false. @@ -118,6 +123,10 @@ By default ``GLOB`` lists directories - directories are omitted in result if your source tree. If no CMakeLists.txt file changes when a source is added or removed then the generated build system cannot know when to ask CMake to regenerate. + The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or if + a new generator is added in the future that cannot support it, projects using + it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there is + still a cost to perform the check on every rebuild. Examples of globbing expressions include:: diff --git a/Help/release/dev/glob_configure_depends.rst b/Help/release/dev/glob_configure_depends.rst new file mode 100644 index 0000000..147e44a --- /dev/null +++ b/Help/release/dev/glob_configure_depends.rst @@ -0,0 +1,6 @@ +glob_configure_depends +---------------------- + +* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands + learned a new flag ``CONFIGURE_DEPENDS`` which enables expression of + build system dependency on globbed directory's contents. -- cgit v0.12