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