summaryrefslogtreecommitdiffstats
path: root/Help/command
diff options
context:
space:
mode:
authorPavel Solodovnikov <hellyeahdominate@gmail.com>2017-06-22 08:13:15 (GMT)
committerPavel Solodovnikov <hellyeahdominate@gmail.com>2017-06-22 08:13:15 (GMT)
commit80f1221f5088bb7ea7864a819c36d03e96f21155 (patch)
treefd51e3c07e4721c4e3d893a354f9a5d939c6d4cd /Help/command
parent85b52a04bd225d04f54cabccc4cbd10f788c1bf0 (diff)
downloadCMake-80f1221f5088bb7ea7864a819c36d03e96f21155.zip
CMake-80f1221f5088bb7ea7864a819c36d03e96f21155.tar.gz
CMake-80f1221f5088bb7ea7864a819c36d03e96f21155.tar.bz2
include_guard: add doc pages and a release note
Diffstat (limited to 'Help/command')
-rw-r--r--Help/command/include_guard.rst46
1 files changed, 46 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)