1CMAKE-LANGUAGE(7) CMake CMAKE-LANGUAGE(7)
2
6 cmake-language - CMake Language Reference
7
9 CMake input files are written in the “CMake Language” in source files
10 named CMakeLists.txt or ending in a .cmake file name extension.
11 CMake Language source files in a project are organized into:
13 · Directories (CMakeLists.txt),
15 · Scripts (<script>.cmake), and
17 · Modules (<module>.cmake).
19 Directories
21 When CMake processes a project source tree, the entry point is a source
22 file called CMakeLists.txt in the top-level source directory. This
23 file may contain the entire build specification or use the add_subdi‐
24 rectory() command to add subdirectories to the build. Each subdirec‐
25 tory added by the command must also contain a CMakeLists.txt file as
26 the entry point to that directory. For each source directory whose
27 CMakeLists.txt file is processed CMake generates a corresponding direc‐
28 tory in the build tree to act as the default working and output direc‐
29 tory.
30 Scripts
32 An individual <script>.cmake source file may be processed in script
33 mode by using the cmake(1) command-line tool with the -P option.
34 Script mode simply runs the commands in the given CMake Language source
35 file and does not generate a build system. It does not allow CMake
36 commands that define build targets or actions.
37 Modules
39 CMake Language code in either Directories or Scripts may use the
40 include() command to load a <module>.cmake source file in the scope of
41 the including context. See the cmake-modules(7) manual page for docu‐
42 mentation of modules included with the CMake distribution. Project
43 source trees may also provide their own modules and specify their loca‐
44 tion(s) in the CMAKE_MODULE_PATH variable.
45
47 Encoding
48 A CMake Language source file may be written in 7-bit ASCII text for
49 maximum portability across all supported platforms. Newlines may be
50 encoded as either \n or \r\n but will be converted to \n as input files
51 are read.
52 Note that the implementation is 8-bit clean so source files may be
54 encoded as UTF-8 on platforms with system APIs supporting this encod‐
55 ing. In addition, CMake 3.2 and above support source files encoded in
56 UTF-8 on Windows (using UTF-16 to call system APIs). Furthermore,
57 CMake 3.0 and above allow a leading UTF-8 Byte-Order Mark in source
58 files.
59 Source Files
61 A CMake Language source file consists of zero or more Command Invoca‐
62 tions separated by newlines and optionally spaces and Comments:
63 file ::= file_element*
65 file_element ::= command_invocation line_ending |
66 (bracket_comment|space)* line_ending
67 line_ending ::= line_comment? newline
68 space ::= <match '[ \t]+'>
69 newline ::= <match '\n'>
70 Note that any source file line not inside Command Arguments or a
73 Bracket Comment can end in a Line Comment.
74 Command Invocations
76 A command invocation is a name followed by paren-enclosed arguments
77 separated by whitespace:
78 command_invocation ::= space* identifier space* '(' arguments ')'
80 identifier ::= <match '[A-Za-z_][A-Za-z0-9_]*'>
81 arguments ::= argument? separated_arguments*
82 separated_arguments ::= separation+ argument? |
83 separation* '(' arguments ')'
84 separation ::= space | line_ending
85 For example:
88 add_executable(hello world.c)
90 Command names are case-insensitive. Nested unquoted parentheses in the
92 arguments must balance. Each ( or ) is given to the command invocation
93 as a literal Unquoted Argument. This may be used in calls to the if()
94 command to enclose conditions. For example:
95 if(FALSE AND (FALSE OR TRUE)) # evaluates to FALSE
97 NOTE:
99 CMake versions prior to 3.0 require command name identifiers to be
100 at least 2 characters.
101 CMake versions prior to 2.8.12 silently accept an Unquoted Argument
103 or a Quoted Argument immediately following a Quoted Argument and not
104 separated by any whitespace. For compatibility, CMake 2.8.12 and
105 higher accept such code but produce a warning.
106 Command Arguments
108 There are three types of arguments within Command Invocations:
109 argument ::= bracket_argument | quoted_argument | unquoted_argument
111 Bracket Argument
114 A bracket argument, inspired by Lua long bracket syntax, encloses con‐
115 tent between opening and closing “brackets” of the same length:
116 bracket_argument ::= bracket_open bracket_content bracket_close
118 bracket_open ::= '[' '='* '['
119 bracket_content ::= <any text not containing a bracket_close with
120 the same number of '=' as the bracket_open>
121 bracket_close ::= ']' '='* ']'
122 An opening bracket is written [ followed by zero or more = followed by
125 [. The corresponding closing bracket is written ] followed by the same
126 number of = followed by ]. Brackets do not nest. A unique length may
127 always be chosen for the opening and closing brackets to contain clos‐
128 ing brackets of other lengths.
129 Bracket argument content consists of all text between the opening and
131 closing brackets, except that one newline immediately following the
132 opening bracket, if any, is ignored. No evaluation of the enclosed
133 content, such as Escape Sequences or Variable References, is performed.
134 A bracket argument is always given to the command invocation as exactly
135 one argument.
136 For example:
138 message([=[
140 This is the first line in a bracket argument with bracket length 1.
141 No \-escape sequences or ${variable} references are evaluated.
142 This is always one argument even though it contains a ; character.
143 The text does not end on a closing bracket of length 0 like ]].
144 It does end in a closing bracket of length 1.
145 ]=])
146 NOTE:
148 CMake versions prior to 3.0 do not support bracket arguments. They
149 interpret the opening bracket as the start of an Unquoted Argument.
150 Quoted Argument
152 A quoted argument encloses content between opening and closing dou‐
153 ble-quote characters:
154 quoted_argument ::= '"' quoted_element* '"'
156 quoted_element ::= <any character except '\' or '"'> |
157 escape_sequence |
158 quoted_continuation
159 quoted_continuation ::= '\' newline
160 Quoted argument content consists of all text between opening and clos‐
163 ing quotes. Both Escape Sequences and Variable References are evalu‐
164 ated. A quoted argument is always given to the command invocation as
165 exactly one argument.
166 For example:
168 message("This is a quoted argument containing multiple lines.
170 This is always one argument even though it contains a ; character.
171 Both \\-escape sequences and ${variable} references are evaluated.
172 The text does not end on an escaped double-quote like \".
173 It does end in an unescaped double quote.
174 ")
175 The final \ on any line ending in an odd number of backslashes is
177 treated as a line continuation and ignored along with the immediately
178 following newline character. For example:
179 message("\
181 This is the first line of a quoted argument. \
182 In fact it is the only line but since it is long \
183 the source code uses line continuation.\
184 ")
185 NOTE:
187 CMake versions prior to 3.0 do not support continuation with \.
188 They report errors in quoted arguments containing lines ending in an
189 odd number of \ characters.
190 Unquoted Argument
192 An unquoted argument is not enclosed by any quoting syntax. It may not
193 contain any whitespace, (, ), #, ", or \ except when escaped by a back‐
194 slash:
195 unquoted_argument ::= unquoted_element+ | unquoted_legacy
197 unquoted_element ::= <any character except whitespace or one of '()#"\'> |
198 escape_sequence
199 unquoted_legacy ::= <see note in text>
200 Unquoted argument content consists of all text in a contiguous block of
203 allowed or escaped characters. Both Escape Sequences and Variable Ref‐
204 erences are evaluated. The resulting value is divided in the same way
205 Lists divide into elements. Each non-empty element is given to the
206 command invocation as an argument. Therefore an unquoted argument may
207 be given to a command invocation as zero or more arguments.
208 For example:
210 foreach(arg
212 NoSpace
213 Escaped\ Space
214 This;Divides;Into;Five;Arguments
215 Escaped\;Semicolon
216 )
217 message("${arg}")
218 endforeach()
219 NOTE:
221 To support legacy CMake code, unquoted arguments may also contain
222 double-quoted strings ("...", possibly enclosing horizontal white‐
223 space), and make-style variable references ($(MAKEVAR)).
224 Unescaped double-quotes must balance, may not appear at the begin‐
226 ning of an unquoted argument, and are treated as part of the con‐
227 tent. For example, the unquoted arguments -Da="b c", -Da=$(v), and
228 a" "b"c"d are each interpreted literally. They may instead be writ‐
229 ten as quoted arguments "-Da=\"b c\"", "-Da=$(v)", and "a\"
230 \"b\"c\"d", respectively.
231 Make-style references are treated literally as part of the content
233 and do not undergo variable expansion. They are treated as part of
234 a single argument (rather than as separate $, (, MAKEVAR, and )
235 arguments).
236 The above “unquoted_legacy” production represents such arguments.
238 We do not recommend using legacy unquoted arguments in new code.
239 Instead use a Quoted Argument or a Bracket Argument to represent the
240 content.
241 Escape Sequences
243 An escape sequence is a \ followed by one character:
244 escape_sequence ::= escape_identity | escape_encoded | escape_semicolon
246 escape_identity ::= '\' <match '[^A-Za-z0-9;]'>
247 escape_encoded ::= '\t' | '\r' | '\n'
248 escape_semicolon ::= '\;'
249 A \ followed by a non-alphanumeric character simply encodes the literal
252 character without interpreting it as syntax. A \t, \r, or \n encodes a
253 tab, carriage return, or newline character, respectively. A \; outside
254 of any Variable References encodes itself but may be used in an
255 Unquoted Argument to encode the ; without dividing the argument value
256 on it. A \; inside Variable References encodes the literal ; charac‐
257 ter. (See also policy CMP0053 documentation for historical considera‐
258 tions.)
259 Variable References
261 A variable reference has the form ${variable_name} and is evaluated
262 inside a Quoted Argument or an Unquoted Argument. A variable reference
263 is replaced by the value of the variable, or by the empty string if the
264 variable is not set. Variable references can nest and are evaluated
265 from the inside out, e.g. ${outer_${inner_variable}_variable}.
266 Literal variable references may consist of alphanumeric characters, the
268 characters /_.+-, and Escape Sequences. Nested references may be used
269 to evaluate variables of any name. (See also policy CMP0053 documenta‐
270 tion for historical considerations.)
271 The Variables section documents the scope of variable names and how
273 their values are set.
274 An environment variable reference has the form $ENV{VAR} and is evalu‐
276 ated in the same contexts as a normal variable reference.
277 Comments
279 A comment starts with a # character that is not inside a Bracket Argu‐
280 ment, Quoted Argument, or escaped with \ as part of an Unquoted Argu‐
281 ment. There are two types of comments: a Bracket Comment and a Line
282 Comment.
283 Bracket Comment
285 A # immediately followed by a Bracket Argument forms a bracket comment
286 consisting of the entire bracket enclosure:
287 bracket_comment ::= '#' bracket_argument
289 For example:
292 #[[This is a bracket comment.
294 It runs until the close bracket.]]
295 message("First Argument\n" #[[Bracket Comment]] "Second Argument")
296 NOTE:
298 CMake versions prior to 3.0 do not support bracket comments. They
299 interpret the opening # as the start of a Line Comment.
300 Line Comment
302 A # not immediately followed by a Bracket Argument forms a line comment
303 that runs until the end of the line:
304 line_comment ::= '#' <any text not starting in a bracket_argument
306 and not containing a newline>
307 For example:
310 # This is a line comment.
312 message("First Argument\n" # This is a line comment :)
313 "Second Argument") # This is a line comment.
314
316 Conditional Blocks
317 The if()/elseif()/else()/endif() commands delimit code blocks to be
318 executed conditionally.
319 Loops
321 The foreach()/endforeach() and while()/endwhile() commands delimit code
322 blocks to be executed in a loop. Inside such blocks the break() com‐
323 mand may be used to terminate the loop early whereas the continue()
324 command may be used to start with the next iteration immediately.
325 Command Definitions
327 The macro()/endmacro(), and function()/endfunction() commands delimit
328 code blocks to be recorded for later invocation as commands.
329
331 Variables are the basic unit of storage in the CMake Language. Their
332 values are always of string type, though some commands may interpret
333 the strings as values of other types. The set() and unset() commands
334 explicitly set or unset a variable, but other commands have semantics
335 that modify variables as well. Variable names are case-sensitive and
336 may consist of almost any text, but we recommend sticking to names con‐
337 sisting only of alphanumeric characters plus _ and -.
338 Variables have dynamic scope. Each variable “set” or “unset” creates a
340 binding in the current scope:
341 Function Scope
343 Command Definitions created by the function() command create
344 commands that, when invoked, process the recorded commands in a
345 new variable binding scope. A variable “set” or “unset” binds
346 in this scope and is visible for the current function and any
347 nested calls within it, but not after the function returns.
348 Directory Scope
350 Each of the Directories in a source tree has its own variable
351 bindings. Before processing the CMakeLists.txt file for a
352 directory, CMake copies all variable bindings currently defined
353 in the parent directory, if any, to initialize the new directory
354 scope. CMake Scripts, when processed with cmake -P, bind vari‐
355 ables in one “directory” scope.
356 A variable “set” or “unset” not inside a function call binds to
358 the current directory scope.
359 Persistent Cache
361 CMake stores a separate set of “cache” variables, or “cache
362 entries”, whose values persist across multiple runs within a
363 project build tree. Cache entries have an isolated binding
364 scope modified only by explicit request, such as by the CACHE
365 option of the set() and unset() commands.
366 When evaluating Variable References, CMake first searches the function
368 call stack, if any, for a binding and then falls back to the binding in
369 the current directory scope, if any. If a “set” binding is found, its
370 value is used. If an “unset” binding is found, or no binding is found,
371 CMake then searches for a cache entry. If a cache entry is found, its
372 value is used. Otherwise, the variable reference evaluates to an empty
373 string.
374 The cmake-variables(7) manual documents many variables that are pro‐
376 vided by CMake or have meaning to CMake when set by project code.
377
379 Although all values in CMake are stored as strings, a string may be
380 treated as a list in certain contexts, such as during evaluation of an
381 Unquoted Argument. In such contexts, a string is divided into list
382 elements by splitting on ; characters not following an unequal number
383 of [ and ] characters and not immediately preceded by a \. The
384 sequence \; does not divide a value but is replaced by ; in the result‐
385 ing element.
386 A list of elements is represented as a string by concatenating the ele‐
388 ments separated by ;. For example, the set() command stores multiple
389 values into the destination variable as a list:
390 set(srcs a.c b.c c.c) # sets "srcs" to "a.c;b.c;c.c"
392 Lists are meant for simple use cases such as a list of source files and
394 should not be used for complex data processing tasks. Most commands
395 that construct lists do not escape ; characters in list elements, thus
396 flattening nested lists:
397 set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c"
399
401 2000-2018 Kitware, Inc. and Contributors
4023.11.4 May 13, 2019 CMAKE-LANGUAGE(7)