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>} and is evaluated inside
262 a Quoted Argument or an Unquoted Argument. A variable reference is
263 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 and reasons why the $ is also tech‐
271 nically permitted but is discouraged.
272 The Variables section documents the scope of variable names and how
274 their values are set.
275 An environment variable reference has the form $ENV{<variable>}. See
277 the Environment Variables section for more information.
278 A cache variable reference has the form $CACHE{<variable>}. See CACHE
280 for more information.
281 The if() command has a special condition syntax that allows for vari‐
283 able references in the short form <variable> instead of ${<variable>}.
284 However, environment and cache variables always need to be referenced
285 as $ENV{<variable>} or $CACHE{<variable>}.
286 Comments
288 A comment starts with a # character that is not inside a Bracket Argu‐
289 ment, Quoted Argument, or escaped with \ as part of an Unquoted Argu‐
290 ment. There are two types of comments: a Bracket Comment and a Line
291 Comment.
292 Bracket Comment
294 A # immediately followed by a bracket_open forms a bracket comment con‐
295 sisting of the entire bracket enclosure:
296 bracket_comment ::= '#' bracket_argument
298 For example:
301 #[[This is a bracket comment.
303 It runs until the close bracket.]]
304 message("First Argument\n" #[[Bracket Comment]] "Second Argument")
305 NOTE:
307 CMake versions prior to 3.0 do not support bracket comments. They
308 interpret the opening # as the start of a Line Comment.
309 Line Comment
311 A # not immediately followed by a bracket_open forms a line comment
312 that runs until the end of the line:
313 line_comment ::= '#' <any text not starting in a bracket_open
315 and not containing a newline>
316 For example:
319 # This is a line comment.
321 message("First Argument\n" # This is a line comment :)
322 "Second Argument") # This is a line comment.
323
325 Conditional Blocks
326 The if()/elseif()/else()/endif() commands delimit code blocks to be
327 executed conditionally.
328 Loops
330 The foreach()/endforeach() and while()/endwhile() commands delimit code
331 blocks to be executed in a loop. Inside such blocks the break() com‐
332 mand may be used to terminate the loop early whereas the continue()
333 command may be used to start with the next iteration immediately.
334 Command Definitions
336 The macro()/endmacro(), and function()/endfunction() commands delimit
337 code blocks to be recorded for later invocation as commands.
338
340 Variables are the basic unit of storage in the CMake Language. Their
341 values are always of string type, though some commands may interpret
342 the strings as values of other types. The set() and unset() commands
343 explicitly set or unset a variable, but other commands have semantics
344 that modify variables as well. Variable names are case-sensitive and
345 may consist of almost any text, but we recommend sticking to names con‐
346 sisting only of alphanumeric characters plus _ and -.
347 Variables have dynamic scope. Each variable “set” or “unset” creates a
349 binding in the current scope:
350 Function Scope
352 Command Definitions created by the function() command create
353 commands that, when invoked, process the recorded commands in a
354 new variable binding scope. A variable “set” or “unset” binds
355 in this scope and is visible for the current function and any
356 nested calls within it, but not after the function returns.
357 Directory Scope
359 Each of the Directories in a source tree has its own variable
360 bindings. Before processing the CMakeLists.txt file for a
361 directory, CMake copies all variable bindings currently defined
362 in the parent directory, if any, to initialize the new directory
363 scope. CMake Scripts, when processed with cmake -P, bind vari‐
364 ables in one “directory” scope.
365 A variable “set” or “unset” not inside a function call binds to
367 the current directory scope.
368 Persistent Cache
370 CMake stores a separate set of “cache” variables, or “cache
371 entries”, whose values persist across multiple runs within a
372 project build tree. Cache entries have an isolated binding
373 scope modified only by explicit request, such as by the CACHE
374 option of the set() and unset() commands.
375 When evaluating Variable References, CMake first searches the function
377 call stack, if any, for a binding and then falls back to the binding in
378 the current directory scope, if any. If a “set” binding is found, its
379 value is used. If an “unset” binding is found, or no binding is found,
380 CMake then searches for a cache entry. If a cache entry is found, its
381 value is used. Otherwise, the variable reference evaluates to an empty
382 string. The $CACHE{VAR} syntax can be used to do direct cache entry
383 lookups.
384 The cmake-variables(7) manual documents the many variables that are
386 provided by CMake or have meaning to CMake when set by project code.
387 NOTE:
389 CMake reserves identifiers that:
390 · begin with CMAKE_ (upper-, lower-, or mixed-case), or
392 · begin with _CMAKE_ (upper-, lower-, or mixed-case), or
394 · begin with _ followed by the name of any CMake Command.
396
398 Environment Variables are like ordinary Variables, with the following
399 differences:
400 Scope Environment variables have global scope in a CMake process.
402 They are never cached.
403 References
405 Variable References have the form $ENV{<variable>}.
406 Initialization
408 Initial values of the CMake environment variables are those of
409 the calling process. Values can be changed using the set() and
410 unset() commands. These commands only affect the running CMake
411 process, not the system environment at large. Changed values
412 are not written back to the calling process, and they are not
413 seen by subsequent build or test processes.
414 The cmake-env-variables(7) manual documents environment variables that
416 have special meaning to CMake.
417
419 Although all values in CMake are stored as strings, a string may be
420 treated as a list in certain contexts, such as during evaluation of an
421 Unquoted Argument. In such contexts, a string is divided into list
422 elements by splitting on ; characters not following an unequal number
423 of [ and ] characters and not immediately preceded by a \. The
424 sequence \; does not divide a value but is replaced by ; in the result‐
425 ing element.
426 A list of elements is represented as a string by concatenating the ele‐
428 ments separated by ;. For example, the set() command stores multiple
429 values into the destination variable as a list:
430 set(srcs a.c b.c c.c) # sets "srcs" to "a.c;b.c;c.c"
432 Lists are meant for simple use cases such as a list of source files and
434 should not be used for complex data processing tasks. Most commands
435 that construct lists do not escape ; characters in list elements, thus
436 flattening nested lists:
437 set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c"
439
441 2000-2020 Kitware, Inc. and Contributors
4423.17.2 Apr 28, 2020 CMAKE-LANGUAGE(7)