[Cmake-commits] CMake branch, next, updated. v2.8.12.1-4910-g2901d3b
Brad King
brad.king at kitware.com
Fri Nov 8 09:02:31 EST 2013
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".
The branch, next has been updated
via 2901d3b284d8a4f8e1022fa5735e5f7bcd146767 (commit)
via 79fd233806960fdf84d912a34f1c3a801e13b5be (commit)
via a931ee44143b7ef3d0106ed5da497e66229aa073 (commit)
via 4d76bcc817fd61ca37a713b1b1bd763902b03493 (commit)
from 17afa3bcf9f51f1adf121a46732e75f409afaf48 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=2901d3b284d8a4f8e1022fa5735e5f7bcd146767
commit 2901d3b284d8a4f8e1022fa5735e5f7bcd146767
Merge: 17afa3b 79fd233
Author: Brad King <brad.king at kitware.com>
AuthorDate: Fri Nov 8 09:02:29 2013 -0500
Commit: CMake Topic Stage <kwrobot at kitware.com>
CommitDate: Fri Nov 8 09:02:29 2013 -0500
Merge topic 'doc-cmake-language' into next
79fd233 Help: Reference cmake-language.7 comment docs from cmake-developer.7
a931ee4 Help: Add cmake-language.7 manual
4d76bcc CMake Nightly Date Stamp
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=79fd233806960fdf84d912a34f1c3a801e13b5be
commit 79fd233806960fdf84d912a34f1c3a801e13b5be
Author: Brad King <brad.king at kitware.com>
AuthorDate: Fri Nov 8 08:21:08 2013 -0500
Commit: Brad King <brad.king at kitware.com>
CommitDate: Fri Nov 8 08:41:49 2013 -0500
Help: Reference cmake-language.7 comment docs from cmake-developer.7
The cmake-language.7 manual now documents comment syntax. Reference it
from cmake-developer.7 when discussing how to add comment-enclosed
documentation to modules.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index 5d20c54..5857acf 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -255,7 +255,8 @@ containing just the line::
The ``cmake-module`` directive will scan the module file to extract
reStructuredText markup from comment blocks that start in ``.rst:``.
-Add to the top of ``Modules/<module-name>.cmake`` a #-comment of the form:
+Add to the top of ``Modules/<module-name>.cmake`` a
+:ref:`Line Comment` block of the form:
.. code-block:: cmake
@@ -265,7 +266,7 @@ Add to the top of ``Modules/<module-name>.cmake`` a #-comment of the form:
#
# <reStructuredText documentation of module>
-or a bracket-comment of the form:
+or a :ref:`Bracket Comment` of the form:
.. code-block:: cmake
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=a931ee44143b7ef3d0106ed5da497e66229aa073
commit a931ee44143b7ef3d0106ed5da497e66229aa073
Author: Brad King <brad.king at kitware.com>
AuthorDate: Fri Nov 8 08:19:30 2013 -0500
Commit: Brad King <brad.king at kitware.com>
CommitDate: Fri Nov 8 08:41:46 2013 -0500
Help: Add cmake-language.7 manual
diff --git a/Help/index.rst b/Help/index.rst
index dea1463..0d33825 100644
--- a/Help/index.rst
+++ b/Help/index.rst
@@ -40,6 +40,7 @@ Other Manuals
/manual/cmake-developer.7
/manual/cmake-generator-expressions.7
+ /manual/cmake-language.7
.. only:: html
diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst
new file mode 100644
index 0000000..7285897
--- /dev/null
+++ b/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"
-----------------------------------------------------------------------
Summary of changes:
Help/index.rst | 1 +
Help/manual/cmake-developer.7.rst | 5 +-
Help/manual/cmake-language.7.rst | 470 +++++++++++++++++++++++++++++++++++++
Source/CMakeVersion.cmake | 2 +-
4 files changed, 475 insertions(+), 3 deletions(-)
create mode 100644 Help/manual/cmake-language.7.rst
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list