Is there an include once command for cmake files? - cmake

Question

Does anyone know a simple way to apply the "include once" pattern in CMake files? In C/C++ it used to require a #ifdef / #endif pair in the beginning and end of the header file until #pragma once became common. Of course, it's possible to do the same in CMake, but I thought it'd be nice if it didn't require an explicit conditional statement.
Re-edition: It seems that the return() command should do it. And I'd define a macro like this:
macro(include_once)
if (INCLUDED_${CMAKE_CURRENT_LIST_FILE})
return()
endif()
set(INCLUDED_${CMAKE_CURRENT_LIST_FILE} true)
endmacro()
Use the macro in the beginning of your file, without any arguments. Because it's a macro, the return is from the include command for the file, not from the macro itself.
Notice that the created variable has an odd name, but CMake seems to accept this.

Answer 1

I used to use the logic that others have suggested as the solution. Then I learned that cmake has this functionality built in.
Take a look at the include_guard() command. I believe this will do what you want.
New in version 3.10.
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 CMAKE_CURRENT_LIST_FILE variable documentation).
CMake will end its processing of the current file at the location of the 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 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 add_subdirectory() or 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:
if(__CURRENT_FILE_VAR__)
return()
endif()
set(__CURRENT_FILE_VAR__ TRUE)

Answer 2

The simplest guard pattern against multiple module's inclusion would be
if(<something-which-is-defined-in-your-module>)
return()
endif()
E.g., if your CMake module defines a function foo_func, you may use this guard:
if(COMMAND foo_func)
return()
endif()
Do you actually need a guard?
Depended on things, defined in the module, the module may require protection agains multiple inclusion or not.
In many simple cases a guard is not needed: the module's code will work even when included multiple times.
But in some other cases, wrong protection may break the usage of the proptected module.
A module defines a function or a macro: guard is not needed.
CMake allows to define the functions and macros many times.
A module defines a constant variable: guard is not needed.
Like with function, CMake allows to define the variable many times.
But if you use guard in that case, it should check variable, not a function:
if(foo_var)
return()
endif()
This is because functions have global visibility, but variables have local visibility. That is, if you module will be included into other subtree, the function will be already visible in that subtree, but the variable is not.
A module defines a global variable via set(CACHE): guard is needed only if variable is defined as set(CACHE INTERNAL).
Variables defined via, e.g., set(CACHE STRING) or find_library don't require guards.
A module defines global property: guard is needed.
Note, that if your module uses simple (not CACHE) variable as global, it cannot work in multiple subtrees, so guard should be
if(foo_var)
message(SEND_ERROR "Module <...> cannot be included twice")
endif()