include_guard: add doc pages and a release note

3 files changed, 55 insertions, 0 deletions

diff --git a/Help/command/include_guard.rst b/Help/command/include_guard.rst
new file mode 100644
index 0000000..62cce22
--- /dev/null
+++ b/Help/command/include_guard.rst
@@ -0,0 +1,46 @@
+include_guard
+-------------
+
+Provides an include guard for the file currently being processed by CMake.
+
+::
+
+  include_guard([DIRECTORY|GLOBAL])
+
+Sets up an include guard for the current CMake file (see the
+:variable:`CMAKE_CURRENT_LIST_FILE` variable documentation).
+
+CMake will end its processing of the current file at the location of the
+:command:`include_guard` command if the current file has already been
+processed for the applicable scope (see below). This provides functionality
+similar to the include guards commonly used in source headers or to the
+``#pragma once`` directive. If the current file has been processed previously
+for the applicable scope, the effect is as though :command:`return` had been
+called. Do not call this command from inside a function being defined within
+the current file.
+
+An optional argument specifying the scope of the guard may be provided.
+Possible values for the option are:
+
+``DIRECTORY``
+  The include guard applies within the current directory and below. The file
+  will only be included once within this directory scope, but may be included
+  again by other files outside of this directory (i.e. a parent directory or
+  another directory not pulled in by :command:`add_subdirectory` or
+  :command:`include` from the current file or its children).
+
+``GLOBAL``
+  The include guard applies globally to the whole build. The current file
+  will only be included once regardless of the scope.
+
+If no arguments given, ``include_guard`` has the same scope as a variable,
+meaning that the include guard effect is isolated by the most recent
+function scope or current directory if no inner function scopes exist.
+In this case the command behavior is the same as:
+
+.. code-block:: cmake
+
+  if(__CURRENT_FILE_VAR__)
+    return()
+  endif()
+  set(__CURRENT_FILE_VAR__ TRUE)
diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst
index 611c989..f8bfb32 100644
--- a/Help/manual/cmake-commands.7.rst
+++ b/Help/manual/cmake-commands.7.rst
@@ -44,6 +44,7 @@ These commands are always available.
    /command/get_property
    /command/if
    /command/include
+   /command/include_guard
    /command/list
    /command/macro
    /command/mark_as_advanced
diff --git a/Help/release/dev/include-guard.rst b/Help/release/dev/include-guard.rst
new file mode 100644
index 0000000..9b0c64c
--- /dev/null
+++ b/Help/release/dev/include-guard.rst
@@ -0,0 +1,8 @@
+include_guard
+-------------
+
+* The :command:`include_guard` command was introduced to allow guarding
+  CMake scripts from being included more than once. The command supports
+  ``DIRECTORY`` and ``GLOBAL`` options to adjust the corresponding include guard
+  scope. If no options given, include guard is similar to basic variable-based
+  check.