CMAKE-LANGUAGE(7) CMake CMAKE-LANGUAGE(7)NAMEcmake-language - CMake Language Reference
ORGANIZATION
CMake input files are written in the "CMake Language" in source files
named CMakeLists.txt or ending in a .cmake file name extension.
CMake Language source files in a project are organized into:
· Directories (CMakeLists.txt),
· Scripts (<script>.cmake), and
· Modules (<module>.cmake).
Directories
When CMake processes a project source tree, the entry point is a source
file called CMakeLists.txt in the top-level source directory. This
file may contain the entire build specification or use the add_subdi‐
rectory() command to add subdirectories to the build. Each subdirec‐
tory added by the command must also contain a CMakeLists.txt file as
the entry point to that directory. For each source directory whose
CMakeLists.txt file is processed CMake generates a corresponding direc‐
tory in the build tree to act as the default working and output direc‐
tory.
Scripts
An individual <script>.cmake source file may be processed in script
mode by using the cmake(1) command-line tool with the -P option.
Script mode simply runs the commands in the given CMake Language source
file and does not generate a build system. It does not allow CMake
commands that define build targets or actions.
Modules
CMake Language code in either Directories or Scripts may use the
include() command to load a <module>.cmake source file in the scope of
the including context. See the cmake-modules(7) manual page for docu‐
mentation of modules included with the CMake distribution. Project
source trees may also provide their own modules and specify their loca‐
tion(s) in the CMAKE_MODULE_PATH variable.
SYNTAX
Encoding
A CMake Language source file may be written in 7-bit ASCII text for
maximum portability across all supported platforms. Newlines may be
encoded as either \n or \r\n but will be converted to \n as input files
are read.
Note that the implementation is 8-bit clean so source files may be
encoded as UTF-8 on platforms with system APIs supporting this encod‐
ing. In addition, CMake 3.2 and above support source files encoded in
UTF-8 on Windows (using UTF-16 to call system APIs). Furthermore,
CMake 3.0 and above allow a leading UTF-8 Byte-Order Mark in source
files.
Source Files
A CMake Language source file consists of zero or more Command Invoca‐
tions separated by newlines and optionally spaces and Comments:
file ::= file_element*
file_element ::= command_invocation line_ending |
(bracket_comment|space)* line_ending
line_ending ::= line_comment? newline
space ::= <match '[ \t]+'>
newline ::= <match '\n'>
Note that any source file line not inside Command Arguments or a
Bracket Comment can end in a Line Comment.
Command Invocations
A command invocation is a name followed by paren-enclosed arguments
separated by whitespace:
command_invocation ::= space* identifier space* '(' arguments ')'
identifier ::= <match '[A-Za-z_][A-Za-z0-9_]*'>
arguments ::= argument? separated_arguments*
separated_arguments ::= separation+ argument? |
separation* '(' arguments ')'
separation ::= space | line_ending
For example:
add_executable(hello world.c)
Command names are case-insensitive. Nested unquoted parentheses in the
arguments must balance. Each ( or ) is given to the command invocation
as a literal Unquoted Argument. This may be used in calls to the if()
command to enclose conditions. For example:
if(FALSE AND (FALSE OR TRUE)) # evaluates to FALSE
NOTE:
CMake versions prior to 3.0 require command name identifiers to be
at least 2 characters.
CMake versions prior to 2.8.12 silently accept an Unquoted Argument
or a Quoted Argument immediately following a Quoted Argument and not
separated by any whitespace. For compatibility, CMake 2.8.12 and
higher accept such code but produce a warning.
Command Arguments
There are three types of arguments within Command Invocations:
argument ::= bracket_argument | quoted_argument | unquoted_argument
Bracket Argument
A bracket argument, inspired by Lua long bracket syntax, encloses con‐
tent between opening and closing "brackets" of the same length:
bracket_argument ::= bracket_open bracket_content bracket_close
bracket_open ::= '[' '='{len} '['
bracket_content ::= <any text not containing a bracket_close
of the same {len} as the bracket_open>
bracket_close ::= ']' '='{len} ']'
An opening bracket of length len >= 0 is written [ followed by len =
followed by [ and the corresponding closing bracket is written ] fol‐
lowed by len = followed by ]. Brackets do not nest. A unique length
may always be chosen for the opening and closing brackets to contain
closing brackets of other lengths.
Bracket argument content consists of all text between the opening and
closing brackets, except that one newline immediately following the
opening bracket, if any, is ignored. No evaluation of the enclosed
content, such as Escape Sequences or Variable References, is performed.
A bracket argument is always given to the command invocation as exactly
one argument.
For example:
message([=[
This is the first line in a bracket argument with bracket length 1.
No \-escape sequences or ${variable} references are evaluated.
This is always one argument even though it contains a ; character.
The text does not end on a closing bracket of length 0 like ]].
It does end in a closing bracket of length 1.
]=])
NOTE:
CMake versions prior to 3.0 do not support bracket arguments. They
interpret the opening bracket as the start of an Unquoted Argument.
Quoted Argument
A quoted argument encloses content between opening and closing dou‐
ble-quote characters:
quoted_argument ::= '"' quoted_element* '"'
quoted_element ::= <any character except '\' or '"'> |
escape_sequence |
quoted_continuation
quoted_continuation ::= '\' newline
Quoted argument content consists of all text between opening and clos‐
ing quotes. Both Escape Sequences and Variable References are evalu‐
ated. A quoted argument is always given to the command invocation as
exactly one argument.
For example:
message("This is a quoted argument containing multiple lines.
This is always one argument even though it contains a ; character.
Both \\-escape sequences and ${variable} references are evaluated.
The text does not end on an escaped double-quote like \".
It does end in an unescaped double quote.
")
The final \ on any line ending in an odd number of backslashes is
treated as a line continuation and ignored along with the immediately
following newline character. For example:
message("\
This is the first line of a quoted argument. \
In fact it is the only line but since it is long \
the source code uses line continuation.\
")
NOTE:
CMake versions prior to 3.0 do not support continuation with \.
They report errors in quoted arguments containing lines ending in an
odd number of \ characters.
Unquoted Argument
An unquoted argument is not enclosed by any quoting syntax. It may not
contain any whitespace, (, ), #, ", or \ except when escaped by a back‐
slash:
unquoted_argument ::= unquoted_element+ | unquoted_legacy
unquoted_element ::= <any character except whitespace or one of '()#"\'> |
escape_sequence
unquoted_legacy ::= <see note in text>
Unquoted argument content consists of all text in a contiguous block of
allowed or escaped characters. Both Escape Sequences and Variable Ref‐
erences are evaluated. The resulting value is divided in the same way
Lists divide into elements. Each non-empty element is given to the
command invocation as an argument. Therefore an unquoted argument may
be given to a command invocation as zero or more arguments.
For example:
foreach(arg
NoSpace
Escaped\ Space
This;Divides;Into;Five;Arguments
Escaped\;Semicolon
)
message("${arg}")
endforeach()
NOTE:
To support legacy CMake code, unquoted arguments may also contain
double-quoted strings ("...", possibly enclosing horizontal white‐
space), and make-style variable references ($(MAKEVAR)). Unescaped
double-quotes must balance, may not appear at the beginning of an
unquoted argument, and are treated as part of the content. For
example, the unquoted arguments -Da="b c", -Da=$(v), and a" "b"c"d
are each interpreted literally.
The above "unquoted_legacy" production represents such arguments.
We do not recommend using legacy unquoted arguments in new code.
Instead use a Quoted Argument or a Bracket Argument to represent the
content.
Escape Sequences
An escape sequence is a \ followed by one character:
escape_sequence ::= escape_identity | escape_encoded | escape_semicolon
escape_identity ::= '\' <match '[^A-Za-z0-9;]'>
escape_encoded ::= '\t' | '\r' | '\n'
escape_semicolon ::= '\;'
A \ followed by a non-alphanumeric character simply encodes the literal
character without interpreting it as syntax. A \t, \r, or \n encodes a
tab, carriage return, or newline character, respectively. A \; outside
of any Variable References encodes itself but may be used in an
Unquoted Argument to encode the ; without dividing the argument value
on it. A \; inside Variable References encodes the literal ; charac‐
ter. (See also policy CMP0053 documentation for historical considera‐
tions.)
Variable References
A variable reference has the form ${variable_name} and is evaluated
inside a Quoted Argument or an Unquoted Argument. A variable reference
is replaced by the value of the variable, or by the empty string if the
variable is not set. Variable references can nest and are evaluated
from the inside out, e.g. ${outer_${inner_variable}_variable}.
Literal variable references may consist of alphanumeric characters, the
characters /_.+-, and Escape Sequences. Nested references may be used
to evaluate variables of any name. (See also policy CMP0053 documenta‐
tion for historical considerations.)
The Variables section documents the scope of variable names and how
their values are set.
An environment variable reference has the form $ENV{VAR} and is evalu‐
ated in the same contexts as a normal variable reference.
Comments
A comment starts with a # character that is not inside a Bracket Argu‐
ment, Quoted Argument, or escaped with \ as part of an Unquoted Argu‐
ment. There are two types of comments: a Bracket Comment and a Line
Comment.
Bracket Comment
A # immediately followed by a Bracket Argument forms a bracket comment
consisting of the entire bracket enclosure:
bracket_comment ::= '#' bracket_argument
For example:
#[[This is a bracket comment.
It runs until the close bracket.]]
message("First Argument\n" #[[Bracket Comment]] "Second Argument")
NOTE:
CMake versions prior to 3.0 do not support bracket comments. They
interpret the opening # as the start of a Line Comment.
Line Comment
A # not immediately followed by a Bracket Argument forms a line comment
that runs until the end of the line:
line_comment ::= '#' <any text not starting in a bracket_argument
and not containing a newline>
For example:
# This is a line comment.
message("First Argument\n" # This is a line comment :)
"Second Argument") # This is a line comment.
CONTROL STRUCTURES
Conditional Blocks
The if()/elseif()/else()/endif() commands delimit code blocks to be
executed conditionally.
Loops
The foreach()/endforeach() and while()/endwhile() commands delimit code
blocks to be executed in a loop. Inside such blocks the break() com‐
mand may be used to terminate the loop early whereas the continue()
command may be used to start with the next iteration immediately.
Command Definitions
The macro()/endmacro(), and function()/endfunction() commands delimit
code blocks to be recorded for later invocation as commands.
VARIABLES
Variables are the basic unit of storage in the CMake Language. Their
values are always of string type, though some commands may interpret
the strings as values of other types. The set() and unset() commands
explicitly set or unset a variable, but other commands have semantics
that modify variables as well. Variable names are case-sensitive and
may consist of almost any text, but we recommend sticking to names con‐
sisting only of alphanumeric characters plus _ and -.
Variables have dynamic scope. Each variable "set" or "unset" creates a
binding in the current scope:
Function Scope
Command Definitions created by the function() command create
commands that, when invoked, process the recorded commands in a
new variable binding scope. A variable "set" or "unset" binds
in this scope and is visible for the current function and any
nested calls, but not after the function returns.
Directory Scope
Each of the Directories in a source tree has its own variable
bindings. Before processing the CMakeLists.txt file for a
directory, CMake copies all variable bindings currently defined
in the parent directory, if any, to initialize the new directory
scope. CMake Scripts, when processed with cmake -P, bind vari‐
ables in one "directory" scope.
A variable "set" or "unset" not inside a function call binds to
the current directory scope.
Persistent Cache
CMake stores a separate set of "cache" variables, or "cache
entries", whose values persist across multiple runs within a
project build tree. Cache entries have an isolated binding
scope modified only by explicit request, such as by the CACHE
option of the set() and unset() commands.
When evaluating Variable References, CMake first searches the function
call stack, if any, for a binding and then falls back to the binding in
the current directory scope, if any. If a "set" binding is found, its
value is used. If an "unset" binding is found, or no binding is found,
CMake then searches for a cache entry. If a cache entry is found, its
value is used. Otherwise, the variable reference evaluates to an empty
string.
The cmake-variables(7) manual documents many variables that are pro‐
vided by CMake or have meaning to CMake when set by project code.
LISTS
Although all values in CMake are stored as strings, a string may be
treated as a list in certain contexts, such as during evaluation of an
Unquoted Argument. In such contexts, a string is divided into list
elements by splitting on ; characters not following an unequal number
of [ and ] characters and not immediately preceded by a \. The
sequence \; does not divide a value but is replaced by ; in the result‐
ing element.
A list of elements is represented as a string by concatenating the ele‐
ments separated by ;. For example, the set() command stores multiple
values into the destination variable as a list:
set(srcs a.c b.c c.c) # sets "srcs" to "a.c;b.c;c.c"
Lists are meant for simple use cases such as a list of source files and
should not be used for complex data processing tasks. Most commands
that construct lists do not escape ; characters in list elements, thus
flattening nested lists:
set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c"
COPYRIGHT
2000-2015 Kitware, Inc.
3.4.2 February 17, 2016 CMAKE-LANGUAGE(7)
