"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "Help/manual/cmake-language.7.rst" between
cmake-3.13.4.tar.gz and cmake-3.14.0-rc1.tar.gz

About: CMake is a cross-platform build system designed to build, test and package software. Release candidate.

cmake-language.7.rst  (cmake-3.13.4):cmake-language.7.rst  (cmake-3.14.0-rc1)
skipping to change at line 209 skipping to change at line 209
for the opening and closing brackets to contain closing brackets for the opening and closing brackets to contain closing brackets
of other lengths. of other lengths.
Bracket argument content consists of all text between the opening Bracket argument content consists of all text between the opening
and closing brackets, except that one newline immediately following and closing brackets, except that one newline immediately following
the opening bracket, if any, is ignored. No evaluation of the the opening bracket, if any, is ignored. No evaluation of the
enclosed content, such as `Escape Sequences`_ or `Variable References`_, enclosed content, such as `Escape Sequences`_ or `Variable References`_,
is performed. A bracket argument is always given to the command is performed. A bracket argument is always given to the command
invocation as exactly one argument. invocation as exactly one argument.
For example: .. No code-block syntax highlighting in the following example
(long string literal not supported by our cmake.py)
.. code-block:: cmake For example::
message([=[ message([=[
This is the first line in a bracket argument with bracket length 1. This is the first line in a bracket argument with bracket length 1.
No \-escape sequences or ${variable} references are evaluated. No \-escape sequences or ${variable} references are evaluated.
This is always one argument even though it contains a ; character. This is always one argument even though it contains a ; character.
The text does not end on a closing bracket of length 0 like ]]. The text does not end on a closing bracket of length 0 like ]].
It does end in a closing bracket of length 1. It does end in a closing bracket of length 1.
]=]) ]=])
.. note:: .. note::
skipping to change at line 256 skipping to change at line 257
.. raw:: latex .. raw:: latex
\end{small} \end{small}
Quoted argument content consists of all text between opening and Quoted argument content consists of all text between opening and
closing quotes. Both `Escape Sequences`_ and `Variable References`_ closing quotes. Both `Escape Sequences`_ and `Variable References`_
are evaluated. A quoted argument is always given to the command are evaluated. A quoted argument is always given to the command
invocation as exactly one argument. invocation as exactly one argument.
.. No code-block syntax highlighting in the following example
(escape \" not supported by our cmake.py)
For example: For example:
:: .. code-block:: cmake
message("This is a quoted argument containing multiple lines. message("This is a quoted argument containing multiple lines.
This is always one argument even though it contains a ; character. This is always one argument even though it contains a ; character.
Both \\-escape sequences and ${variable} references are evaluated. Both \\-escape sequences and ${variable} references are evaluated.
The text does not end on an escaped double-quote like \". The text does not end on an escaped double-quote like \".
It does end in an unescaped double quote. It does end in an unescaped double quote.
") ")
.. No code-block syntax highlighting in the following example
(for conformity with the two above examples)
The final ``\`` on any line ending in an odd number of backslashes The final ``\`` on any line ending in an odd number of backslashes
is treated as a line continuation and ignored along with the is treated as a line continuation and ignored along with the
immediately following newline character. For example: immediately following newline character. For example:
.. code-block:: cmake .. code-block:: cmake
message("\ message("\
This is the first line of a quoted argument. \ This is the first line of a quoted argument. \
In fact it is the only line but since it is long \ In fact it is the only line but since it is long \
the source code uses line continuation.\ the source code uses line continuation.\
") ")
.. note:: .. note::
CMake versions prior to 3.0 do not support continuation with ``\``. CMake versions prior to 3.0 do not support continuation with ``\``.
They report errors in quoted arguments containing lines ending in They report errors in quoted arguments containing lines ending in
an odd number of ``\`` characters. an odd number of ``\`` characters.
.. _`Unquoted Argument`: .. _`Unquoted Argument`:
Unquoted Argument Unquoted Argument
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
skipping to change at line 385 skipping to change at line 392
`Unquoted Argument`_ to encode the ``;`` without dividing the argument `Unquoted Argument`_ to encode the ``;`` without dividing the argument
value on it. A ``\;`` inside `Variable References`_ encodes the literal value on it. A ``\;`` inside `Variable References`_ encodes the literal
``;`` character. (See also policy :policy:`CMP0053` documentation for ``;`` character. (See also policy :policy:`CMP0053` documentation for
historical considerations.) historical considerations.)
.. _`Variable References`: .. _`Variable References`:
Variable References Variable References
------------------- -------------------
A *variable reference* has the form ``${variable_name}`` and is A *variable reference* has the form ``${<variable>}`` and is
evaluated inside a `Quoted Argument`_ or an `Unquoted Argument`_. evaluated inside a `Quoted Argument`_ or an `Unquoted Argument`_.
A variable reference is replaced by the value of the variable, A variable reference is replaced by the value of the variable,
or by the empty string if the variable is not set. or by the empty string if the variable is not set.
Variable references can nest and are evaluated from the Variable references can nest and are evaluated from the
inside out, e.g. ``${outer_${inner_variable}_variable}``. inside out, e.g. ``${outer_${inner_variable}_variable}``.
Literal variable references may consist of alphanumeric characters, Literal variable references may consist of alphanumeric characters,
the characters ``/_.+-``, and `Escape Sequences`_. Nested references the characters ``/_.+-``, and `Escape Sequences`_. Nested references
may be used to evaluate variables of any name. See also policy may be used to evaluate variables of any name. See also policy
:policy:`CMP0053` documentation for historical considerations and reasons why :policy:`CMP0053` documentation for historical considerations and reasons why
the ``$`` is also technically permitted but is discouraged. the ``$`` is also technically permitted but is discouraged.
The `Variables`_ section documents the scope of variable names The `Variables`_ section documents the scope of variable names
and how their values are set. and how their values are set.
An *environment variable reference* has the form ``$ENV{VAR}`` and An *environment variable reference* has the form ``$ENV{<variable>}``.
is evaluated in the same contexts as a normal variable reference. See the `Environment Variables`_ section for more information.
See :variable:`ENV` for more information.
A *cache variable reference* has the form ``$CACHE{VAR}`` and A *cache variable reference* has the form ``$CACHE{<variable>}``.
is evaluated in the same contexts as a normal variable reference.
See :variable:`CACHE` for more information. See :variable:`CACHE` for more information.
The :command:`if` command has a special condition syntax that
allows for variable references in the short form ``<variable>``
instead of ``${<variable>}``.
However, environment and cache variables always need to be
referenced as ``$ENV{<variable>}`` or ``$CACHE{<variable>}``.
Comments Comments
-------- --------
A comment starts with a ``#`` character that is not inside a A comment starts with a ``#`` character that is not inside a
`Bracket Argument`_, `Quoted Argument`_, or escaped with ``\`` `Bracket Argument`_, `Quoted Argument`_, or escaped with ``\``
as part of an `Unquoted Argument`_. There are two types of as part of an `Unquoted Argument`_. There are two types of
comments: a `Bracket Comment`_ and a `Line Comment`_. comments: a `Bracket Comment`_ and a `Line Comment`_.
.. _`Bracket Comment`: .. _`Bracket Comment`:
skipping to change at line 555 skipping to change at line 566
When evaluating `Variable References`_, CMake first searches the When evaluating `Variable References`_, CMake first searches the
function call stack, if any, for a binding and then falls back function call stack, if any, for a binding and then falls back
to the binding in the current directory scope, if any. If a to the binding in the current directory scope, if any. If a
"set" binding is found, its value is used. If an "unset" binding "set" binding is found, its value is used. If an "unset" binding
is found, or no binding is found, CMake then searches for a is found, or no binding is found, CMake then searches for a
cache entry. If a cache entry is found, its value is used. cache entry. If a cache entry is found, its value is used.
Otherwise, the variable reference evaluates to an empty string. Otherwise, the variable reference evaluates to an empty string.
The ``$CACHE{VAR}`` syntax can be used to do direct cache entry The ``$CACHE{VAR}`` syntax can be used to do direct cache entry
lookups. lookups.
The :manual:`cmake-variables(7)` manual documents many variables The :manual:`cmake-variables(7)` manual documents the many variables
that are provided by CMake or have meaning to CMake when set that are provided by CMake or have meaning to CMake when set
by project code. by project code.
.. _`CMake Language Environment Variables`:
Environment Variables
=====================
Environment Variables are like ordinary `Variables`_, with the
following differences:
Scope
Environment variables have global scope in a CMake process.
They are never cached.
References
`Variable References`_ have the form ``$ENV{<variable>}``.
Initialization
Initial values of the CMake environment variables are those of
the calling process.
Values can be changed using the :command:`set` and :command:`unset`
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.
The :manual:`cmake-env-variables(7)` manual documents environment
variables that have special meaning to CMake.
.. _`CMake Language Lists`: .. _`CMake Language Lists`:
Lists Lists
===== =====
Although all values in CMake are stored as strings, a string Although all values in CMake are stored as strings, a string
may be treated as a list in certain contexts, such as during may be treated as a list in certain contexts, such as during
evaluation of an `Unquoted Argument`_. In such contexts, a string evaluation of an `Unquoted Argument`_. In such contexts, a string
is divided into list elements by splitting on ``;`` characters not is divided into list elements by splitting on ``;`` characters not
following an unequal number of ``[`` and ``]`` characters and not following an unequal number of ``[`` and ``]`` characters and not
 End of changes. 12 change blocks. 
21 lines changed or deleted 60 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)