.\" Man page generated from reStructuredText.

.

.TH "CMAKE-LANGUAGE" "7" "October 14, 2015" "3.3.2" "CMake"

.SH NAME

cmake-language \- CMake Language Reference

.

.nr rst2man-indent-level 0

.

.de1 rstReportMargin

\\$1 \\n[an-margin]

level \\n[rst2man-indent-level]

level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]

-

\\n[rst2man-indent0]

\\n[rst2man-indent1]

\\n[rst2man-indent2]

..

.de1 INDENT

.\" .rstReportMargin pre:

. RS \\$1

. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]

. nr rst2man-indent-level +1

.\" .rstReportMargin post:

..

.de UNINDENT

. RE

.\" indent \\n[an-margin]

.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]

.nr rst2man-indent-level -1

.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]

.in \\n[rst2man-indent\\n[rst2man-indent-level]]u

..

.SH ORGANIZATION

.sp

CMake input files are written in the "CMake Language" in source files

named \fBCMakeLists.txt\fP or ending in a \fB\&.cmake\fP file name extension.

.sp

CMake Language source files in a project are organized into:

.INDENT 0.0

.IP \(bu 2

\fI\%Directories\fP (\fBCMakeLists.txt\fP),

.IP \(bu 2

\fI\%Scripts\fP (\fB<script>.cmake\fP), and

.IP \(bu 2

\fI\%Modules\fP (\fB<module>.cmake\fP).

.UNINDENT

.SS Directories

.sp

When CMake processes a project source tree, the entry point is

a source file called \fBCMakeLists.txt\fP in the top\-level source

directory.  This file may contain the entire build specification

or use the \fBadd_subdirectory()\fP command to add subdirectories

to the build.  Each subdirectory added by the command must also

contain a \fBCMakeLists.txt\fP file as the entry point to that

directory.  For each source directory whose \fBCMakeLists.txt\fP file

is processed CMake generates a corresponding directory in the build

tree to act as the default working and output directory.

.SS Scripts

.sp

An individual \fB<script>.cmake\fP source file may be processed

in \fIscript mode\fP by using the \fBcmake(1)\fP command\-line tool

with the \fB\-P\fP 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.

.SS Modules

.sp

CMake Language code in either \fI\%Directories\fP or \fI\%Scripts\fP may

use the \fBinclude()\fP command to load a \fB<module>.cmake\fP

source file in the scope of the including context.

See the \fBcmake\-modules(7)\fP 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 \fBCMAKE_MODULE_PATH\fP

variable.

.SH SYNTAX

.SS Encoding

.sp

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 \fB\en\fP or \fB\er\en\fP but will be converted to \fB\en\fP

as input files are read.

.sp

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

\fI\%Byte\-Order Mark\fP in source files.

.SS Source Files

.sp

A CMake Language source file consists of zero or more

\fI\%Command Invocations\fP separated by newlines and optionally

spaces and \fI\%Comments\fP:

.sp

.nf

\fBfile        \fP ::=  \fI\%file_element\fP*

\fBfile_element\fP ::=  \fI\%command_invocation\fP \fI\%line_ending\fP |

                  (\fI\%bracket_comment\fP|\fI\%space\fP)* \fI\%line_ending\fP

\fBline_ending \fP ::=  \fI\%line_comment\fP? \fI\%newline\fP

\fBspace       \fP ::=  <match \(aq[ \et]+\(aq>

\fBnewline     \fP ::=  <match \(aq\en\(aq>

.fi

.sp

Note that any source file line not inside \fI\%Command Arguments\fP or

a \fI\%Bracket Comment\fP can end in a \fI\%Line Comment\fP\&.

.SS Command Invocations

.sp

A \fIcommand invocation\fP is a name followed by paren\-enclosed arguments

separated by whitespace:

.sp

.nf

\fBcommand_invocation \fP ::=  \fI\%space\fP* \fI\%identifier\fP \fI\%space\fP* \(aq(\(aq \fI\%arguments\fP \(aq)\(aq

\fBidentifier         \fP ::=  <match \(aq[A\-Za\-z_][A\-Za\-z0\-9_]*\(aq>

\fBarguments          \fP ::=  \fI\%argument\fP? \fI\%separated_arguments\fP*

\fBseparated_arguments\fP ::=  \fI\%separation\fP+ \fI\%argument\fP? |

                         \fI\%separation\fP* \(aq(\(aq \fI\%arguments\fP \(aq)\(aq

\fBseparation         \fP ::=  \fI\%space\fP | \fI\%line_ending\fP

.fi

.sp

For example:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_executable(hello world.c)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Command names are case\-insensitive.

Nested unquoted parentheses in the arguments must balance.

Each \fB(\fP or \fB)\fP is given to the command invocation as

a literal \fI\%Unquoted Argument\fP\&.  This may be used in calls

to the \fBif()\fP command to enclose conditions.

For example:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

if(FALSE AND (FALSE OR TRUE)) # evaluates to FALSE

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

\fBNOTE:\fP

.INDENT 0.0

.INDENT 3.5

CMake versions prior to 3.0 require command name identifiers

to be at least 2 characters.

.sp

CMake versions prior to 2.8.12 silently accept an \fI\%Unquoted Argument\fP

or a \fI\%Quoted Argument\fP immediately following a \fI\%Quoted Argument\fP and

not separated by any whitespace.  For compatibility, CMake 2.8.12 and

higher accept such code but produce a warning.

.UNINDENT

.UNINDENT

.SS Command Arguments

.sp

There are three types of arguments within \fI\%Command Invocations\fP:

.sp

.nf

\fBargument\fP ::=  \fI\%bracket_argument\fP | \fI\%quoted_argument\fP | \fI\%unquoted_argument\fP

.fi

.SS Bracket Argument

.sp

A \fIbracket argument\fP, inspired by \fI\%Lua\fP long bracket syntax,

encloses content between opening and closing "brackets" of the

same length:

.sp

.nf

\fBbracket_argument\fP ::=  \fI\%bracket_open\fP \fI\%bracket_content\fP \fI\%bracket_close\fP

\fBbracket_open    \fP ::=  \(aq[\(aq \(aq=\(aq{len} \(aq[\(aq

\fBbracket_content \fP ::=  <any text not containing a \fI\%bracket_close\fP

                       of the same {len} as the \fI\%bracket_open\fP>

\fBbracket_close   \fP ::=  \(aq]\(aq \(aq=\(aq{len} \(aq]\(aq

.fi

.sp

An opening bracket of length \fIlen >= 0\fP is written \fB[\fP followed

by \fIlen\fP \fB=\fP followed by \fB[\fP and the corresponding closing

bracket is written \fB]\fP followed by \fIlen\fP \fB=\fP followed by \fB]\fP\&.

Brackets do not nest.  A unique length may always be chosen

for the opening and closing brackets to contain closing brackets

of other lengths.

.sp

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 \fI\%Escape Sequences\fP or \fI\%Variable References\fP,

is performed.  A bracket argument is always given to the command

invocation as exactly one argument.

.sp

For example:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

message([=[

This is the first line in a bracket argument with bracket length 1.

No \e\-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.

]=])

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

\fBNOTE:\fP

.INDENT 0.0

.INDENT 3.5

CMake versions prior to 3.0 do not support bracket arguments.

They interpret the opening bracket as the start of an

\fI\%Unquoted Argument\fP\&.

.UNINDENT

.UNINDENT

.SS Quoted Argument

.sp

A \fIquoted argument\fP encloses content between opening and closing

double\-quote characters:

.sp

.nf

\fBquoted_argument    \fP ::=  \(aq"\(aq \fI\%quoted_element\fP* \(aq"\(aq

\fBquoted_element     \fP ::=  <any character except \(aq\e\(aq or \(aq"\(aq> |

                         \fI\%escape_sequence\fP |

                         \fI\%quoted_continuation\fP

\fBquoted_continuation\fP ::=  \(aq\e\(aq \fI\%newline\fP

.fi

.sp

Quoted argument content consists of all text between opening and

closing quotes.  Both \fI\%Escape Sequences\fP and \fI\%Variable References\fP

are evaluated.  A quoted argument is always given to the command

invocation as exactly one argument.

.sp

For example:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

message("This is a quoted argument containing multiple lines.

This is always one argument even though it contains a ; character.

Both \e\e\-escape sequences and ${variable} references are evaluated.

The text does not end on an escaped double\-quote like \e".

It does end in an unescaped double quote.

")

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

The final \fB\e\fP 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:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

message("\e

This is the first line of a quoted argument. \e

In fact it is the only line but since it is long \e

the source code uses line continuation.\e

")

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

\fBNOTE:\fP

.INDENT 0.0

.INDENT 3.5

CMake versions prior to 3.0 do not support continuation with \fB\e\fP\&.

They report errors in quoted arguments containing lines ending in

an odd number of \fB\e\fP characters.

.UNINDENT

.UNINDENT

.SS Unquoted Argument

.sp

An \fIunquoted argument\fP is not enclosed by any quoting syntax.

It may not contain any whitespace, \fB(\fP, \fB)\fP, \fB#\fP, \fB"\fP, or \fB\e\fP

except when escaped by a backslash:

.sp

.nf

\fBunquoted_argument\fP ::=  \fI\%unquoted_element\fP+ | \fI\%unquoted_legacy\fP

\fBunquoted_element \fP ::=  <any character except whitespace or one of \(aq()#"\e\(aq> |

                       \fI\%escape_sequence\fP

\fBunquoted_legacy  \fP ::=  <see note in text>

.fi

.sp

Unquoted argument content consists of all text in a contiguous block

of allowed or escaped characters.  Both \fI\%Escape Sequences\fP and

\fI\%Variable References\fP are evaluated.  The resulting value is divided

in the same way \fI\%Lists\fP 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.

.sp

For example:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

foreach(arg

    NoSpace

    Escaped\e Space

    This;Divides;Into;Five;Arguments

    Escaped\e;Semicolon

    )

  message("${arg}")

endforeach()

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

\fBNOTE:\fP

.INDENT 0.0

.INDENT 3.5

To support legacy CMake code, unquoted arguments may also contain

double\-quoted strings (\fB"..."\fP, possibly enclosing horizontal

whitespace), and make\-style variable references (\fB$(MAKEVAR)\fP).

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 \fB\-Da="b c"\fP,

\fB\-Da=$(v)\fP, and \fBa" "b"c"d\fP are each interpreted literally.

.sp

The above "unquoted_legacy" production represents such arguments.

We do not recommend using legacy unquoted arguments in new code.

Instead use a \fI\%Quoted Argument\fP or a \fI\%Bracket Argument\fP to

represent the content.

.UNINDENT

.UNINDENT

.SS Escape Sequences

.sp

An \fIescape sequence\fP is a \fB\e\fP followed by one character:

.sp

.nf

\fBescape_sequence \fP ::=  \fI\%escape_identity\fP | \fI\%escape_encoded\fP | \fI\%escape_semicolon\fP

\fBescape_identity \fP ::=  \(aq\e\(aq <match \(aq[^A\-Za\-z0\-9;]\(aq>

\fBescape_encoded  \fP ::=  \(aq\et\(aq | \(aq\er\(aq | \(aq\en\(aq

\fBescape_semicolon\fP ::=  \(aq\e;\(aq

.fi

.sp

A \fB\e\fP followed by a non\-alphanumeric character simply encodes the literal

character without interpreting it as syntax.  A \fB\et\fP, \fB\er\fP, or \fB\en\fP

encodes a tab, carriage return, or newline character, respectively. A \fB\e;\fP

outside of any \fI\%Variable References\fP  encodes itself but may be used in an

\fI\%Unquoted Argument\fP to encode the \fB;\fP without dividing the argument

value on it.  A \fB\e;\fP inside \fI\%Variable References\fP encodes the literal

\fB;\fP character.  (See also policy \fBCMP0053\fP documentation for

historical considerations.)

.SS Variable References

.sp

A \fIvariable reference\fP has the form \fB${variable_name}\fP and is

evaluated inside a \fI\%Quoted Argument\fP or an \fI\%Unquoted Argument\fP\&.

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. \fB${outer_${inner_variable}_variable}\fP\&.

.sp

Literal variable references may consist of alphanumeric characters,

the characters \fB/_.+\-\fP, and \fI\%Escape Sequences\fP\&.  Nested references

may be used to evaluate variables of any name.  (See also policy

\fBCMP0053\fP documentation for historical considerations.)

.sp

The \fI\%Variables\fP section documents the scope of variable names

and how their values are set.

.sp

An \fIenvironment variable reference\fP has the form \fB$ENV{VAR}\fP and

is evaluated in the same contexts as a normal variable reference.

.SS Comments

.sp

A comment starts with a \fB#\fP character that is not inside a

\fI\%Bracket Argument\fP, \fI\%Quoted Argument\fP, or escaped with \fB\e\fP

as part of an \fI\%Unquoted Argument\fP\&.  There are two types of

comments: a \fI\%Bracket Comment\fP and a \fI\%Line Comment\fP\&.

.SS Bracket Comment

.sp

A \fB#\fP immediately followed by a \fI\%Bracket Argument\fP forms a

\fIbracket comment\fP consisting of the entire bracket enclosure:

.sp

.nf

\fBbracket_comment\fP ::=  \(aq#\(aq \fI\%bracket_argument\fP

.fi

.sp

For example:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

#[[This is a bracket comment.

It runs until the close bracket.]]

message("First Argument\en" #[[Bracket Comment]] "Second Argument")

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

\fBNOTE:\fP

.INDENT 0.0

.INDENT 3.5

CMake versions prior to 3.0 do not support bracket comments.

They interpret the opening \fB#\fP as the start of a \fI\%Line Comment\fP\&.

.UNINDENT

.UNINDENT

.SS Line Comment

.sp

A \fB#\fP not immediately followed by a \fI\%Bracket Argument\fP forms a

\fIline comment\fP that runs until the end of the line:

.sp

.nf

\fBline_comment\fP ::=  \(aq#\(aq <any text not starting in a \fI\%bracket_argument\fP

                       and not containing a \fI\%newline\fP>

.fi

.sp

For example:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

# This is a line comment.

message("First Argument\en" # This is a line comment :)

        "Second Argument") # This is a line comment.

.ft P

.fi

.UNINDENT

.UNINDENT

.SH CONTROL STRUCTURES

.SS Conditional Blocks

.sp

The \fBif()\fP/\fBelseif()\fP/\fBelse()\fP/\fBendif()\fP

commands delimit code blocks to be executed conditionally.

.SS Loops

.sp

The \fBforeach()\fP/\fBendforeach()\fP and

\fBwhile()\fP/\fBendwhile()\fP commands delimit code

blocks to be executed in a loop.  Inside such blocks the

\fBbreak()\fP command may be used to terminate the loop

early whereas the \fBcontinue()\fP command may be used

to start with the next iteration immediately.

.SS Command Definitions

.sp

The \fBmacro()\fP/\fBendmacro()\fP, and

\fBfunction()\fP/\fBendfunction()\fP commands delimit

code blocks to be recorded for later invocation as commands.

.SH VARIABLES

.sp

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 \fBset()\fP and \fBunset()\fP 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 \fB_\fP and \fB\-\fP\&.

.sp

Variables have dynamic scope.  Each variable "set" or "unset"

creates a binding in the current scope:

.INDENT 0.0

.TP

.B Function Scope

\fI\%Command Definitions\fP created by the \fBfunction()\fP 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.

.TP

.B Directory Scope

Each of the \fI\%Directories\fP in a source tree has its own variable

bindings.  Before processing the \fBCMakeLists.txt\fP file for a

directory, CMake copies all variable bindings currently defined

in the parent directory, if any, to initialize the new directory

scope.  CMake \fI\%Scripts\fP, when processed with \fBcmake \-P\fP, bind

variables in one "directory" scope.

.sp

A variable "set" or "unset" not inside a function call binds

to the current directory scope.

.TP

.B 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 \fBCACHE\fP option of the

\fBset()\fP and \fBunset()\fP commands.

.UNINDENT

.sp

When evaluating \fI\%Variable References\fP, 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.

.sp

The \fBcmake\-variables(7)\fP manual documents many variables

that are provided by CMake or have meaning to CMake when set

by project code.

.SH LISTS

.sp

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 \fI\%Unquoted Argument\fP\&.  In such contexts, a string

is divided into list elements by splitting on \fB;\fP characters not

following an unequal number of \fB[\fP and \fB]\fP characters and not

immediately preceded by a \fB\e\fP\&.  The sequence \fB\e;\fP does not

divide a value but is replaced by \fB;\fP in the resulting element.

.sp

A list of elements is represented as a string by concatenating

the elements separated by \fB;\fP\&.  For example, the \fBset()\fP