summaryrefslogtreecommitdiffstats
path: root/Help
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2017-06-28 12:53:21 (GMT)
committerKitware Robot <kwrobot@kitware.com>2017-06-28 12:53:30 (GMT)
commit0552747b58799afd6cb23db1cc5296a605cfde18 (patch)
tree4d8765b3cbc64a3e0ad40d5dcfecf836ec2bb99d /Help
parent45ca0403ac11a78550997a38d9d55a06439220c9 (diff)
parentc96f43b7dd1d41379fe63b4e8b508b2b034520b6 (diff)
downloadCMake-0552747b58799afd6cb23db1cc5296a605cfde18.zip
CMake-0552747b58799afd6cb23db1cc5296a605cfde18.tar.gz
CMake-0552747b58799afd6cb23db1cc5296a605cfde18.tar.bz2
Merge topic 'feature/include_guard'
c96f43b7 include_guard: add tests for the feature 80f1221f include_guard: add doc pages and a release note 85b52a04 include_guard: add vim syntax highlighting rules d44bd1c2 include_guard: implement new command Acked-by: Kitware Robot <kwrobot@kitware.com> Reviewed-by: Craig Scott <craig.scott@crascit.com> Merge-request: !928
Diffstat (limited to 'Help')
-rw-r--r--Help/command/include_guard.rst46
-rw-r--r--Help/manual/cmake-commands.7.rst1
-rw-r--r--Help/release/dev/include-guard.rst8
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.