1CMAKE-LANGUAGE(7)                    CMake                   CMAKE-LANGUAGE(7)
2
3
4

NAME

6       cmake-language - CMake Language Reference
7

ORGANIZATION

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
12       CMake Language source files in a project are organized into:
13
14Directories (CMakeLists.txt),
15
16Scripts (<script>.cmake), and
17
18Modules (<module>.cmake).
19
20   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
31   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
38   Modules
39       CMake Language code in either Directories or Scripts may  use  the  in‐
40       clude()  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

SYNTAX

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
53       Note that the implementation is 8-bit clean so source files may be  en‐
54       coded  as UTF-8 on platforms with system APIs supporting this encoding.
55       In addition, CMake 3.2 and above support source files encoded in  UTF-8
56       on  Windows (using UTF-16 to call system APIs).  Furthermore, CMake 3.0
57       and above allow a leading UTF-8 Byte-Order Mark in source files.
58
59   Source Files
60       A CMake Language source file consists of zero or more  Command  Invoca‐
61       tions separated by newlines and optionally spaces and Comments:
62
63       file         ::=  file_element*
64       file_element ::=  command_invocation line_ending |
65                         (bracket_comment|space)* line_ending
66       line_ending  ::=  line_comment? newline
67       space        ::=  <match '[ \t]+'>
68       newline      ::=  <match '\n'>
69
70
71       Note  that  any  source  file  line  not  inside Command Arguments or a
72       Bracket Comment can end in a Line Comment.
73
74   Command Invocations
75       A command invocation is a name  followed  by  paren-enclosed  arguments
76       separated by whitespace:
77
78       command_invocation  ::=  space* identifier space* '(' arguments ')'
79       identifier          ::=  <match '[A-Za-z_][A-Za-z0-9_]*'>
80       arguments           ::=  argument? separated_arguments*
81       separated_arguments ::=  separation+ argument? |
82                                separation* '(' arguments ')'
83       separation          ::=  space | line_ending
84
85
86       For example:
87
88          add_executable(hello world.c)
89
90       Command names are case-insensitive.  Nested unquoted parentheses in the
91       arguments must balance.  Each ( or ) is given to the command invocation
92       as  a literal Unquoted Argument.  This may be used in calls to the if()
93       command to enclose conditions.  For example:
94
95          if(FALSE AND (FALSE OR TRUE)) # evaluates to FALSE
96
97       NOTE:
98          CMake versions prior to 3.0 require command name identifiers  to  be
99          at least 2 characters.
100
101          CMake  versions prior to 2.8.12 silently accept an Unquoted Argument
102          or a Quoted Argument immediately following a Quoted Argument and not
103          separated  by  any  whitespace.  For compatibility, CMake 2.8.12 and
104          higher accept such code but produce a warning.
105
106   Command Arguments
107       There are three types of arguments within Command Invocations:
108
109       argument ::=  bracket_argument | quoted_argument | unquoted_argument
110
111
112   Bracket Argument
113       A bracket argument, inspired by Lua long bracket syntax, encloses  con‐
114       tent between opening and closing "brackets" of the same length:
115
116       bracket_argument ::=  bracket_open bracket_content bracket_close
117       bracket_open     ::=  '[' '='* '['
118       bracket_content  ::=  <any text not containing a bracket_close with
119                              the same number of '=' as the bracket_open>
120       bracket_close    ::=  ']' '='* ']'
121
122
123       An  opening bracket is written [ followed by zero or more = followed by
124       [.  The corresponding closing bracket is written ] followed by the same
125       number  of = followed by ].  Brackets do not nest.  A unique length may
126       always be chosen for the opening and closing brackets to contain  clos‐
127       ing brackets of other lengths.
128
129       Bracket  argument  content consists of all text between the opening and
130       closing brackets, except that one  newline  immediately  following  the
131       opening  bracket,  if  any,  is ignored.  No evaluation of the enclosed
132       content, such as Escape Sequences or Variable References, is performed.
133       A bracket argument is always given to the command invocation as exactly
134       one argument.
135
136       For example:
137
138          message([=[
139          This is the first line in a bracket argument with bracket length 1.
140          No \-escape sequences or ${variable} references are evaluated.
141          This is always one argument even though it contains a ; character.
142          The text does not end on a closing bracket of length 0 like ]].
143          It does end in a closing bracket of length 1.
144          ]=])
145
146       NOTE:
147          CMake versions prior to 3.0 do not support bracket arguments.   They
148          interpret the opening bracket as the start of an Unquoted Argument.
149
150   Quoted Argument
151       A  quoted  argument  encloses  content between opening and closing dou‐
152       ble-quote characters:
153
154       quoted_argument     ::=  '"' quoted_element* '"'
155       quoted_element      ::=  <any character except '\' or '"'> |
156                                escape_sequence |
157                                quoted_continuation
158       quoted_continuation ::=  '\' newline
159
160
161       Quoted argument content consists of all text between opening and  clos‐
162       ing  quotes.   Both Escape Sequences and Variable References are evalu‐
163       ated.  A quoted argument is always given to the command  invocation  as
164       exactly one argument.
165
166       For example:
167
168          message("This is a quoted argument containing multiple lines.
169          This is always one argument even though it contains a ; character.
170          Both \\-escape sequences and ${variable} references are evaluated.
171          The text does not end on an escaped double-quote like \".
172          It does end in an unescaped double quote.
173          ")
174
175       The  final  \  on  any  line  ending in an odd number of backslashes is
176       treated as a line continuation and ignored along with  the  immediately
177       following newline character.  For example:
178
179          message("\
180          This is the first line of a quoted argument. \
181          In fact it is the only line but since it is long \
182          the source code uses line continuation.\
183          ")
184
185       NOTE:
186          CMake  versions  prior  to  3.0  do not support continuation with \.
187          They report errors in quoted arguments containing lines ending in an
188          odd number of \ characters.
189
190   Unquoted Argument
191       An unquoted argument is not enclosed by any quoting syntax.  It may not
192       contain any whitespace, (, ), #, ", or \ except when escaped by a back‐
193       slash:
194
195       unquoted_argument ::=  unquoted_element+ | unquoted_legacy
196       unquoted_element  ::=  <any character except whitespace or one of '()#"\'> |
197                              escape_sequence
198       unquoted_legacy   ::=  <see note in text>
199
200
201       Unquoted argument content consists of all text in a contiguous block of
202       allowed or escaped characters.  Both Escape Sequences and Variable Ref‐
203       erences  are evaluated.  The resulting value is divided in the same way
204       Lists divide into elements.  Each non-empty element  is  given  to  the
205       command  invocation as an argument.  Therefore an unquoted argument may
206       be given to a command invocation as zero or more arguments.
207
208       For example:
209
210          foreach(arg
211              NoSpace
212              Escaped\ Space
213              This;Divides;Into;Five;Arguments
214              Escaped\;Semicolon
215              )
216            message("${arg}")
217          endforeach()
218
219       NOTE:
220          To support legacy CMake code, unquoted arguments  may  also  contain
221          double-quoted  strings  ("...", possibly enclosing horizontal white‐
222          space), and make-style variable references ($(MAKEVAR)).
223
224          Unescaped double-quotes must balance, may not appear at  the  begin‐
225          ning  of  an  unquoted argument, and are treated as part of the con‐
226          tent.  For example, the unquoted arguments -Da="b c", -Da=$(v),  and
227          a" "b"c"d are each interpreted literally.  They may instead be writ‐
228          ten  as  quoted  arguments  "-Da=\"b  c\"",  "-Da=$(v)",  and   "a\"
229          \"b\"c\"d", respectively.
230
231          Make-style  references  are treated literally as part of the content
232          and do not undergo variable expansion.  They are treated as part  of
233          a  single argument (rather than as separate $, (, MAKEVAR, and ) ar‐
234          guments).
235
236          The above "unquoted_legacy" production  represents  such  arguments.
237          We  do  not  recommend  using legacy unquoted arguments in new code.
238          Instead use a Quoted Argument or a Bracket Argument to represent the
239          content.
240
241   Escape Sequences
242       An escape sequence is a \ followed by one character:
243
244       escape_sequence  ::=  escape_identity | escape_encoded | escape_semicolon
245       escape_identity  ::=  '\' <match '[^A-Za-z0-9;]'>
246       escape_encoded   ::=  '\t' | '\r' | '\n'
247       escape_semicolon ::=  '\;'
248
249
250       A \ followed by a non-alphanumeric character simply encodes the literal
251       character without interpreting it as syntax.  A \t, \r, or \n encodes a
252       tab,  carriage return, or newline character, respectively. A \; outside
253       of any Variable References  encodes  itself  but  may  be  used  in  an
254       Unquoted  Argument  to encode the ; without dividing the argument value
255       on it.  A \; inside Variable References encodes the literal  ;  charac‐
256       ter.   (See also policy CMP0053 documentation for historical considera‐
257       tions.)
258
259   Variable References
260       A variable reference has the form ${<variable>} and is evaluated inside
261       a Quoted Argument or an Unquoted Argument.  A variable reference is re‐
262       placed by the value of the variable, or by  the  empty  string  if  the
263       variable  is  not  set.  Variable references can nest and are evaluated
264       from the inside out, e.g. ${outer_${inner_variable}_variable}.
265
266       Literal variable references may consist of alphanumeric characters, the
267       characters  /_.+-, and Escape Sequences.  Nested references may be used
268       to evaluate variables of any name.  See also policy CMP0053  documenta‐
269       tion  for historical considerations and reasons why the $ is also tech‐
270       nically permitted but is discouraged.
271
272       The Variables section documents the scope of  variable  names  and  how
273       their values are set.
274
275       An  environment  variable reference has the form $ENV{<variable>}.  See
276       the Environment Variables section for more information.
277
278       A cache variable reference has the form $CACHE{<variable>}.  See  CACHE
279       for more information.
280
281       The  if()  command has a special condition syntax that allows for vari‐
282       able references in the short form <variable> instead of  ${<variable>}.
283       However,  environment  and cache variables always need to be referenced
284       as $ENV{<variable>} or $CACHE{<variable>}.
285
286   Comments
287       A comment starts with a # character that is not inside a Bracket  Argu‐
288       ment,  Quoted  Argument, or escaped with \ as part of an Unquoted Argu‐
289       ment.  There are two types of comments: a Bracket Comment  and  a  Line
290       Comment.
291
292   Bracket Comment
293       A # immediately followed by a bracket_open forms a bracket comment con‐
294       sisting of the entire bracket enclosure:
295
296       bracket_comment ::=  '#' bracket_argument
297
298
299       For example:
300
301          #[[This is a bracket comment.
302          It runs until the close bracket.]]
303          message("First Argument\n" #[[Bracket Comment]] "Second Argument")
304
305       NOTE:
306          CMake versions prior to 3.0 do not support bracket  comments.   They
307          interpret the opening # as the start of a Line Comment.
308
309   Line Comment
310       A  #  not  immediately  followed by a bracket_open forms a line comment
311       that runs until the end of the line:
312
313       line_comment ::=  '#' <any text not starting in a bracket_open
314                              and not containing a newline>
315
316
317       For example:
318
319          # This is a line comment.
320          message("First Argument\n" # This is a line comment :)
321                  "Second Argument") # This is a line comment.
322

CONTROL STRUCTURES

324   Conditional Blocks
325       The if()/elseif()/else()/endif() commands delimit code blocks to be ex‐
326       ecuted conditionally.
327
328   Loops
329       The foreach()/endforeach() and while()/endwhile() commands delimit code
330       blocks to be executed in a loop.  Inside such blocks the  break()  com‐
331       mand  may  be  used  to terminate the loop early whereas the continue()
332       command may be used to start with the next iteration immediately.
333
334   Command Definitions
335       The macro()/endmacro(), and function()/endfunction()  commands  delimit
336       code blocks to be recorded for later invocation as commands.
337

VARIABLES

339       Variables  are  the basic unit of storage in the CMake Language.  Their
340       values are always of string type, though some  commands  may  interpret
341       the  strings  as values of other types.  The set() and unset() commands
342       explicitly set or unset a variable, but other commands  have  semantics
343       that  modify  variables as well.  Variable names are case-sensitive and
344       may consist of almost any text, but we recommend sticking to names con‐
345       sisting only of alphanumeric characters plus _ and -.
346
347       Variables have dynamic scope.  Each variable "set" or "unset" creates a
348       binding in the current scope:
349
350       Function Scope
351              Command Definitions created by  the  function()  command  create
352              commands  that, when invoked, process the recorded commands in a
353              new variable binding scope.  A variable "set" or  "unset"  binds
354              in  this  scope  and is visible for the current function and any
355              nested calls within it, but not after the function returns.
356
357       Directory Scope
358              Each of the Directories in a source tree has  its  own  variable
359              bindings.   Before  processing the CMakeLists.txt file for a di‐
360              rectory, CMake copies all variable bindings currently defined in
361              the  parent  directory,  if any, to initialize the new directory
362              scope.  CMake Scripts, when processed with cmake -P, bind  vari‐
363              ables in one "directory" scope.
364
365              A  variable "set" or "unset" not inside a function call binds to
366              the current directory scope.
367
368       Persistent Cache
369              CMake stores a separate set of "cache" variables, or "cache  en‐
370              tries",  whose  values  persist  across  multiple  runs within a
371              project build tree.  Cache  entries  have  an  isolated  binding
372              scope  modified  only  by explicit request, such as by the CACHE
373              option of the set() and unset() commands.
374
375       When evaluating Variable References, CMake first searches the  function
376       call stack, if any, for a binding and then falls back to the binding in
377       the current directory scope, if any.  If a "set" binding is found,  its
378       value is used.  If an "unset" binding is found, or no binding is found,
379       CMake then searches for a cache entry.  If a cache entry is found,  its
380       value is used.  Otherwise, the variable reference evaluates to an empty
381       string.  The $CACHE{VAR} syntax can be used to do  direct  cache  entry
382       lookups.
383
384       The  cmake-variables(7)  manual  documents  the many variables that are
385       provided by CMake or have meaning to CMake when set by project code.
386
387       NOTE:
388          CMake reserves identifiers that:
389
390          • begin with CMAKE_ (upper-, lower-, or mixed-case), or
391
392          • begin with _CMAKE_ (upper-, lower-, or mixed-case), or
393
394          • begin with _ followed by the name of any CMake Command.
395

ENVIRONMENT VARIABLES

397       Environment Variables are like ordinary Variables, with  the  following
398       differences:
399
400       Scope  Environment  variables  have  global  scope  in a CMake process.
401              They are never cached.
402
403       References
404              Variable References have the form $ENV{<variable>}.
405
406       Initialization
407              Initial values of the CMake environment variables are  those  of
408              the  calling process.  Values can be changed using the set() and
409              unset() commands.  These commands only affect the running  CMake
410              process,  not  the  system environment at large.  Changed values
411              are not written back to the calling process, and  they  are  not
412              seen by subsequent build or test processes.
413
414       The  cmake-env-variables(7) manual documents environment variables that
415       have special meaning to CMake.
416

LISTS

418       Although all values in CMake are stored as strings,  a  string  may  be
419       treated  as a list in certain contexts, such as during evaluation of an
420       Unquoted Argument.  In such contexts, a string is divided into list el‐
421       ements  by splitting on ; characters not following an unequal number of
422       [ and ] characters and not immediately preceded by a \.   The  sequence
423       \;  does  not divide a value but is replaced by ; in the resulting ele‐
424       ment.
425
426       A list of elements is represented as a string by concatenating the ele‐
427       ments  separated  by ;.  For example, the set() command stores multiple
428       values into the destination variable as a list:
429
430          set(srcs a.c b.c c.c) # sets "srcs" to "a.c;b.c;c.c"
431
432       Lists are meant for simple use cases such as a list of source files and
433       should  not  be  used for complex data processing tasks.  Most commands
434       that construct lists do not escape ; characters in list elements,  thus
435       flattening nested lists:
436
437          set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c"
438
440       2000-2022 Kitware, Inc. and Contributors
441
442
443
444
4453.22.2                           Jan 25, 2022                CMAKE-LANGUAGE(7)
Impressum