1include_guard
2-------------
3
4.. versionadded:: 3.10
5
6Provides an include guard for the file currently being processed by CMake.
7
8.. code-block:: cmake
9
10  include_guard([DIRECTORY|GLOBAL])
11
12Sets up an include guard for the current CMake file (see the
13:variable:`CMAKE_CURRENT_LIST_FILE` variable documentation).
14
15CMake will end its processing of the current file at the location of the
16:command:`include_guard` command if the current file has already been
17processed for the applicable scope (see below). This provides functionality
18similar to the include guards commonly used in source headers or to the
19``#pragma once`` directive. If the current file has been processed previously
20for the applicable scope, the effect is as though :command:`return` had been
21called. Do not call this command from inside a function being defined within
22the current file.
23
24An optional argument specifying the scope of the guard may be provided.
25Possible values for the option are:
26
27``DIRECTORY``
28  The include guard applies within the current directory and below. The file
29  will only be included once within this directory scope, but may be included
30  again by other files outside of this directory (i.e. a parent directory or
31  another directory not pulled in by :command:`add_subdirectory` or
32  :command:`include` from the current file or its children).
33
34``GLOBAL``
35  The include guard applies globally to the whole build. The current file
36  will only be included once regardless of the scope.
37
38If no arguments given, ``include_guard`` has the same scope as a variable,
39meaning that the include guard effect is isolated by the most recent
40function scope or current directory if no inner function scopes exist.
41In this case the command behavior is the same as:
42
43.. code-block:: cmake
44
45  if(__CURRENT_FILE_VAR__)
46    return()
47  endif()
48  set(__CURRENT_FILE_VAR__ TRUE)
49