| .\" Man page generated from reStructuredText. |
| . |
| .TH "CMAKE-LANGUAGE" "7" "Apr 12, 2022" "3.23.1" "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* \(aq[\(aq |
| \fBbracket_content \fP ::= <any text not containing a \fI\%bracket_close\fP with |
| the same number of \(aq=\(aq as the \fI\%bracket_open\fP> |
| \fBbracket_close \fP ::= \(aq]\(aq \(aq=\(aq* \(aq]\(aq |
| |
| .fi |
| .sp |
| An opening bracket is written \fB[\fP followed by zero or more \fB=\fP followed |
| by \fB[\fP\&. The corresponding closing bracket is written \fB]\fP followed |
| by the same number of \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). |
| .sp |
| 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. |
| They may instead be written as quoted arguments \fB"\-Da=\e"b c\e""\fP, |
| \fB"\-Da=$(v)"\fP, and \fB"a\e" \e"b\e"c\e"d"\fP, respectively. |
| .sp |
| 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 \fB$\fP, \fB(\fP, |
| \fBMAKEVAR\fP, and \fB)\fP arguments). |
| .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>}\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 and reasons why |
| the \fB$\fP is also technically permitted but is discouraged. |
| .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{<variable>}\fP\&. |
| See the \fI\%Environment Variables\fP section for more information. |
| .sp |
| A \fIcache variable reference\fP has the form \fB$CACHE{<variable>}\fP\&. |
| See \fBCACHE\fP for more information. |
| .sp |
| The \fBif()\fP command has a special condition syntax that |
| allows for variable references in the short form \fB<variable>\fP |
| instead of \fB${<variable>}\fP\&. |
| However, environment and cache variables always need to be |
| referenced as \fB$ENV{<variable>}\fP or \fB$CACHE{<variable>}\fP\&. |
| .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_open\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_open\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_open\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 within it, 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. |
| The \fB$CACHE{VAR}\fP syntax can be used to do direct cache entry |
| lookups. |
| .sp |
| The \fBcmake\-variables(7)\fP manual documents the many variables |
| that are provided by CMake or have meaning to CMake when set |
| by project code. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| CMake reserves identifiers that: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| begin with \fBCMAKE_\fP (upper\-, lower\-, or mixed\-case), or |
| .IP \(bu 2 |
| begin with \fB_CMAKE_\fP (upper\-, lower\-, or mixed\-case), or |
| .IP \(bu 2 |
| begin with \fB_\fP followed by the name of any \fBCMake Command\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SH ENVIRONMENT VARIABLES |
| .sp |
| Environment Variables are like ordinary \fI\%Variables\fP, with the |
| following differences: |
| .INDENT 0.0 |
| .TP |
| .B Scope |
| Environment variables have global scope in a CMake process. |
| They are never cached. |
| .TP |
| .B References |
| \fI\%Variable References\fP have the form \fB$ENV{<variable>}\fP\&. |
| .TP |
| .B Initialization |
| Initial values of the CMake environment variables are those of |
| the calling process. |
| Values can be changed using the \fBset()\fP and \fBunset()\fP |
| commands. |
| These commands only affect the running CMake process, |
| not the system environment at large. |
| Changed values are not written back to the calling process, |
| and they are not seen by subsequent build or test processes. |
| .UNINDENT |
| .sp |
| The \fBcmake\-env\-variables(7)\fP manual documents environment |
| variables that have special meaning to CMake. |
| .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 |
| command stores multiple values into the destination variable |
| as a list: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(srcs a.c b.c c.c) # sets "srcs" to "a.c;b.c;c.c" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| 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 \fB;\fP characters |
| in list elements, thus flattening nested lists: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(x a "b;c") # sets "x" to "a;b;c", not "a;b\e;c" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In general, lists do not support elements containing \fB;\fP characters. |
| To avoid problems, consider the following advice: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| The interfaces of many CMake commands, variables, and properties accept |
| semicolon\-separated lists. Avoid passing lists with elements containing |
| semicolons to these interfaces unless they document either direct support |
| or some way to escape or encode semicolons. |
| .IP \(bu 2 |
| When constructing a list, substitute an otherwise\-unused placeholder |
| for \fB;\fP in elements when. Then substitute \fB;\fP for the placeholder |
| when processing list elements. |
| For example, the following code uses \fB|\fP in place of \fB;\fP characters: |
| .INDENT 2.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(mylist a "b|c") |
| foreach(entry IN LISTS mylist) |
| string(REPLACE "|" ";" entry "${entry}") |
| # use "${entry}" normally |
| endforeach() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBExternalProject\fP module\(aqs \fBLIST_SEPARATOR\fP option is an |
| example of an interface built using this approach. |
| .IP \(bu 2 |
| In lists of \fBgenerator expressions\fP, |
| use the \fB$<SEMICOLON>\fP generator expression. |
| .IP \(bu 2 |
| In command calls, use \fI\%Quoted Argument\fP syntax whenever possible. |
| The called command will receive the content of the argument with |
| semicolons preserved. An \fI\%Unquoted Argument\fP will be split on |
| semicolons. |
| .IP \(bu 2 |
| In \fBfunction()\fP implementations, avoid \fBARGV\fP and \fBARGN\fP, |
| which do not distinguish semicolons in values from those separating values. |
| Instead, prefer using named positional arguments and the \fBARGC\fP and |
| \fBARGV#\fP variables. |
| When using \fBcmake_parse_arguments()\fP to parse arguments, prefer |
| its \fBPARSE_ARGV\fP signature, which uses the \fBARGV#\fP variables. |
| .sp |
| Note that this approach does not apply to \fBmacro()\fP implementations |
| because they reference arguments using placeholders, not real variables. |
| .UNINDENT |
| .SH COPYRIGHT |
| 2000-2022 Kitware, Inc. and Contributors |
| .\" Generated by docutils manpage writer. |
| . |