diff options
Diffstat (limited to 'share/cmake-3.10/Help/manual/cmake-language.7.rst')
| -rw-r--r-- | share/cmake-3.10/Help/manual/cmake-language.7.rst | 580 |
1 files changed, 0 insertions, 580 deletions
diff --git a/share/cmake-3.10/Help/manual/cmake-language.7.rst b/share/cmake-3.10/Help/manual/cmake-language.7.rst deleted file mode 100644 index 87f8f9d..0000000 --- a/share/cmake-3.10/Help/manual/cmake-language.7.rst +++ /dev/null @@ -1,580 +0,0 @@ -.. 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: '[' '='* '[' - bracket_content: <any text not containing a `bracket_close` with - : the same number of '=' as the `bracket_open`> - bracket_close: ']' '='* ']' - -.. raw:: latex - - \end{small} - -An opening bracket is written ``[`` followed by zero or more ``=`` followed -by ``[``. The corresponding closing bracket is written ``]`` followed -by the same number of ``=`` 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. - They may instead be written as quoted arguments ``"-Da=\"b c\""``, - ``"-Da=$(v)"``, and ``"a\" \"b\"c\"d"``, respectively. - - 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 within it, 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" |