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
14       · Directories (CMakeLists.txt),
15
16       · Scripts (<script>.cmake), and
17
18       · Modules (<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
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

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
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
60   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
64       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
71
72       Note that any source file  line  not  inside  Command  Arguments  or  a
73       Bracket Comment can end in a Line Comment.
74
75   Command Invocations
76       A  command  invocation  is  a name followed by paren-enclosed arguments
77       separated by whitespace:
78
79       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
86
87       For example:
88
89          add_executable(hello world.c)
90
91       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
96          if(FALSE AND (FALSE OR TRUE)) # evaluates to FALSE
97
98       NOTE:
99          CMake  versions  prior to 3.0 require command name identifiers to be
100          at least 2 characters.
101
102          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
107   Command Arguments
108       There are three types of arguments within Command Invocations:
109
110       argument ::=  bracket_argument | quoted_argument | unquoted_argument
111
112
113   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
117       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
123
124       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
130       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
137       For example:
138
139          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
147       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
151   Quoted Argument
152       A quoted argument encloses content between  opening  and  closing  dou‐
153       ble-quote characters:
154
155       quoted_argument     ::=  '"' quoted_element* '"'
156       quoted_element      ::=  <any character except '\' or '"'> |
157                                escape_sequence |
158                                quoted_continuation
159       quoted_continuation ::=  '\' newline
160
161
162       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
167       For example:
168
169          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
176       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
180          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
186       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
191   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
196       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
201
202       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
209       For example:
210
211          foreach(arg
212              NoSpace
213              Escaped\ Space
214              This;Divides;Into;Five;Arguments
215              Escaped\;Semicolon
216              )
217            message("${arg}")
218          endforeach()
219
220       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
225          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
232          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
237          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
242   Escape Sequences
243       An escape sequence is a \ followed by one character:
244
245       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
250
251       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
260   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
267       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
273       The  Variables  section  documents  the scope of variable names and how
274       their values are set.
275
276       An environment variable reference has the form  $ENV{<variable>}.   See
277       the Environment Variables section for more information.
278
279       A  cache variable reference has the form $CACHE{<variable>}.  See CACHE
280       for more information.
281
282       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
287   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
293   Bracket Comment
294       A # immediately followed by a bracket_open forms a bracket comment con‐
295       sisting of the entire bracket enclosure:
296
297       bracket_comment ::=  '#' bracket_argument
298
299
300       For example:
301
302          #[[This is a bracket comment.
303          It runs until the close bracket.]]
304          message("First Argument\n" #[[Bracket Comment]] "Second Argument")
305
306       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
310   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
314       line_comment ::=  '#' <any text not starting in a bracket_open
315                              and not containing a newline>
316
317
318       For example:
319
320          # This is a line comment.
321          message("First Argument\n" # This is a line comment :)
322                  "Second Argument") # This is a line comment.
323

CONTROL STRUCTURES

325   Conditional Blocks
326       The  if()/elseif()/else()/endif()  commands  delimit  code blocks to be
327       executed conditionally.
328
329   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
335   Command Definitions
336       The  macro()/endmacro(),  and function()/endfunction() commands delimit
337       code blocks to be recorded for later invocation as commands.
338

VARIABLES

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
348       Variables have dynamic scope.  Each variable “set” or “unset” creates a
349       binding in the current scope:
350
351       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
358       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
366              A variable “set” or “unset” not inside a function call binds  to
367              the current directory scope.
368
369       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
376       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
385       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
388       NOTE:
389          CMake reserves identifiers that:
390
391          · begin with CMAKE_ (upper-, lower-, or mixed-case), or
392
393          · begin with _CMAKE_ (upper-, lower-, or mixed-case), or
394
395          · begin with _ followed by the name of any CMake Command.
396

ENVIRONMENT VARIABLES

398       Environment  Variables  are like ordinary Variables, with the following
399       differences:
400
401       Scope  Environment variables have global  scope  in  a  CMake  process.
402              They are never cached.
403
404       References
405              Variable References have the form $ENV{<variable>}.
406
407       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
415       The cmake-env-variables(7) manual documents environment variables  that
416       have special meaning to CMake.
417

LISTS

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
427       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
431          set(srcs a.c b.c c.c) # sets "srcs" to "a.c;b.c;c.c"
432
433       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
438          set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c"
439
441       2000-2020 Kitware, Inc. and Contributors
442
443
444
445
4463.17.2                           Apr 28, 2020                CMAKE-LANGUAGE(7)
Impressum