summaryrefslogtreecommitdiffstats
path: root/Help/manual/cmake-language.7.rst
blob: 27b5d30b4a8edc0c007580e0b01eb48a496d7b3d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
.. cmake-manual-description: CMake Language Reference

cmake-language(7)
*****************

.. only:: html

   .. contents::

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 :command:`add_subdirectory` command to add subdirectories
to the build.  Each subdirectory 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 directory in the build
tree to act as the default working and output directory.

Scripts
-------

An individual ``<script>.cmake`` source file may be processed
in *script mode* by using the :manual:`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 :command:`include` command to load a ``<module>.cmake``
source file in the scope of the including context.
See the :manual:`cmake-modules(7)` manual page for documentation
of modules included with the CMake distribution.
Project source trees may also provide their own modules and
specify their location(s) in the :variable:`CMAKE_MODULE_PATH`
variable.

Syntax
======

.. _`CMake Language Encoding`:

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
encoding.  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.

.. _`Byte-Order Mark`: http://en.wikipedia.org/wiki/Byte_order_mark

Source Files
------------

A CMake Language source file consists of zero or more
`Command Invocations`_ separated by newlines and optionally
spaces and `Comments`_:

.. raw:: latex

   \begin{small}

.. productionlist::
 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'>

.. raw:: latex

   \end{small}

Note that any source file line not inside `Command Arguments`_ or
a `Bracket Comment`_ can end in a `Line Comment`_.

.. _`Command Invocations`:

Command Invocations
-------------------

A *command invocation* is a name followed by paren-enclosed arguments
separated by whitespace:

.. raw:: latex

   \begin{small}

.. productionlist::
 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`

.. raw:: latex

   \end{small}

For example:

.. code-block:: cmake

 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 :command:`if` command to enclose conditions.
For example:

.. code-block:: cmake

 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`_:

.. raw:: latex

   \begin{small}

.. productionlist::
 argument: `bracket_argument` | `quoted_argument` | `unquoted_argument`

.. raw:: latex

   \end{small}

.. _`Bracket Argument`:

Bracket Argument
^^^^^^^^^^^^^^^^

A *bracket argument*, inspired by `Lua`_ long bracket syntax,
encloses content between opening and closing "brackets" of the
same length:

.. raw:: latex

   \begin{small}

.. productionlist::
 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} ']'

.. raw:: latex

   \end{small}

An opening bracket of length *len >= 0* is written ``[`` followed
by *len* ``=`` followed by ``[`` and the corresponding closing
bracket is written ``]`` followed 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:

.. code-block:: cmake

 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`_.

.. _`Lua`: http://www.lua.org/

.. _`Quoted Argument`:

Quoted Argument
^^^^^^^^^^^^^^^

A *quoted argument* encloses content between opening and closing
double-quote characters:

.. raw:: latex

   \begin{small}

.. productionlist::
 quoted_argument: '"' `quoted_element`* '"'
 quoted_element: <any character except '\' or '"'> |
                 : `escape_sequence` |
                 : `quoted_continuation`
 quoted_continuation: '\' `newline`

.. raw:: latex

   \end{small}

Quoted argument content consists of all text between opening and
closing quotes.  Both `Escape Sequences`_ and `Variable References`_
are evaluated.  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:

.. code-block:: cmake

 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`:

Unquoted Argument
^^^^^^^^^^^^^^^^^

An *unquoted argument* is not enclosed by any quoting syntax.
It may not contain any whitespace, ``(``, ``)``, ``#``, ``"``, or ``\``
except when escaped by a backslash:

.. raw:: latex

   \begin{small}

.. productionlist::
 unquoted_argument: `unquoted_element`+ | `unquoted_legacy`
 unquoted_element: <any character except whitespace or one of '()#"\'> |
                 : `escape_sequence`
 unquoted_legacy: <see note in text>

.. raw:: latex

   \end{small}

Unquoted argument content consists of all text in a contiguous block
of allowed or escaped characters.  Both `Escape Sequences`_ and
`Variable References`_ 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:

.. code-block:: cmake

 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
 whitespace), 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.

 Make-style references are treated literally as part of the content
 and do not undergo variable expansion.  They are treated as part
 of a single argument (rather than as separate ``$``, ``(``,
 ``MAKEVAR``, and ``)`` arguments).

 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`:

Escape Sequences
----------------

An *escape sequence* is a ``\`` followed by one character:

.. raw:: latex

   \begin{small}

.. productionlist::
 escape_sequence: `escape_identity` | `escape_encoded` | `escape_semicolon`
 escape_identity: '\' <match '[^A-Za-z0-9;]'>
 escape_encoded: '\t' | '\r' | '\n'
 escape_semicolon: '\;'

.. raw:: latex

   \end{small}

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
``;`` character.  (See also policy :policy:`CMP0053` documentation for
historical considerations.)

.. _`Variable References`:

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
:policy:`CMP0053` documentation 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 evaluated in the same contexts as a normal variable reference.

Comments
--------

A comment starts with a ``#`` character that is not inside a
`Bracket Argument`_, `Quoted Argument`_, or escaped with ``\``
as part of an `Unquoted Argument`_.  There are two types of
comments: a `Bracket Comment`_ and a `Line Comment`_.

.. _`Bracket Comment`:

Bracket Comment
^^^^^^^^^^^^^^^

A ``#`` immediately followed by a `Bracket Argument`_ forms a
*bracket comment* consisting of the entire bracket enclosure:

.. raw:: latex

   \begin{small}

.. productionlist::
 bracket_comment: '#' `bracket_argument`

.. raw:: latex

   \end{small}

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`:

Line Comment
^^^^^^^^^^^^

A ``#`` not immediately followed by a `Bracket Argument`_ forms a
*line comment* that runs until the end of the line:

.. raw:: latex

   \begin{small}

.. productionlist::
 line_comment: '#' <any text not starting in a `bracket_argument`
             :      and not containing a `newline`>

.. raw:: latex

   \end{small}

For example:

.. code-block:: cmake

 # 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 :command:`if`/:command:`elseif`/:command:`else`/:command:`endif`
commands delimit code blocks to be executed conditionally.

Loops
-----

The :command:`foreach`/:command:`endforeach` and
:command:`while`/:command:`endwhile` commands delimit code
blocks to be executed in a loop.  Inside such blocks the
:command:`break` command may be used to terminate the loop
early whereas the :command:`continue` command may be used
to start with the next iteration immediately.

Command Definitions
-------------------

The :command:`macro`/:command:`endmacro`, and
:command:`function`/:command:`endfunction` commands delimit
code blocks to be recorded for later invocation as commands.

.. _`CMake Language Variables`:

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 :command:`set` and :command:`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 consisting 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 :command:`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
 variables 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
 :command:`set` and :command:`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 :manual:`cmake-variables(7)` manual documents many variables
that are provided by CMake or have meaning to CMake when set
by project code.

.. _`CMake Language Lists`:

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 resulting element.

A list of elements is represented as a string by concatenating
the elements separated by ``;``.  For example, the :command:`set`
command stores multiple values into the destination variable
as a list:

.. code-block:: cmake

 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:

.. code-block:: cmake

 set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c"