Help: Add cmake-language.7 manual

Help/index.rst

@@ -40,6 +40,7 @@ Other Manuals
 
    /manual/cmake-developer.7
    /manual/cmake-generator-expressions.7
+   /manual/cmake-language.7
 
 .. only:: html
 

Help/manual/cmake-language.7.rst

@@ -0,0 +1,470 @@
+.. cmake-manual-description: CMake Language Reference
+
+cmake-language(7)
+*****************
+
+.. only:: html or latex
+
+   .. 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
+======
+
+Encoding
+--------
+
+A CMake Language source file must be written in 7-bit ASCII text
+to be portable 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.  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`_:
+
+.. 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'>
+
+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:
+
+.. 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`
+
+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`_:
+
+.. productionlist::
+ argument: `bracket_argument` | `quoted_argument` | `unquoted_argument`
+
+Bracket Argument
+^^^^^^^^^^^^^^^^
+
+A *bracket argument*, inspired by `Lua`_ long bracket syntax,
+encloses content between opening and closing "brackets" of the
+same length:
+
+.. 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} ']'
+
+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
+^^^^^^^^^^^^^^^
+
+A *quoted argument* encloses content between opening and closing
+double-quote characters:
+
+.. productionlist::
+ quoted_argument: '"' `quoted_element`* '"'
+ quoted_element: <any character except '\' or '"'> |
+                 : `escape_sequence` |
+                 : `quoted_continuation`
+ quoted_continuation: '\' `newline`
+
+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:
+
+.. code-block:: cmake
+
+ 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
+^^^^^^^^^^^^^^^^^
+
+An *unquoted argument* is not enclosed by any quoting syntax.
+It may not contain any whitespace, ``(``, ``)``, ``#``, ``"``, or ``\``
+except when escaped by a backslash:
+
+.. productionlist::
+ unquoted_argument: `unquoted_element`+ | `unquoted_legacy`
+ unquoted_element: <any character except whitespace or one of '()#"\'> |
+                 : `escape_sequence`
+ unquoted_legacy: <see note in text>
+
+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.
+
+ 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
+----------------
+
+An *escape sequence* is a ``\`` followed by one character:
+
+.. productionlist::
+ escape_sequence: `escape_identity` | `escape_encoded` | `escape_semicolon`
+ escape_identity: '\(' | '\)' | '\#' | '\"' | '\ ' |
+                : '\\' | '\$' | '\@' | '\^'
+ escape_encoded: '\t' | '\r' | '\n'
+ escape_semicolon: '\;'
+
+A ``\`` followed by one of ``()#" \#@^`` 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 ``\;`` encodes itself but may be used in an `Unquoted Argument`_
+to encode the ``;`` without dividing the argument value on it.
+
+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}``.
+
+The `Variables`_ section documents the scope of variable names
+and how their values are set.
+
+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:
+
+.. productionlist::
+ bracket_comment: '#' `bracket_argument`
+
+For example:
+
+.. code-block:: cmake
+
+ #[[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:
+
+.. productionlist::
+ line_comment: '#' <any text not starting in a `bracket_argument`
+             :      and not containing a `newline`>
+
+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.  The :command:`break` command
+may be used inside such blocks to terminate the loop early.
+
+Command Definitions
+-------------------
+
+The :command:`macro`/:command:`endmacro`, and
+:command:`function`/:command:`endfunction` commands delimit
+code blocks to be recorded for later invocation as commands.
+
+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.
+
+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"