[Cmake-commits] CMake branch, next, updated. v3.2.1-1382-g6f7cdfd
Brad King
brad.king at kitware.com
Wed Apr 1 16:30:13 EDT 2015
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 6f7cdfdde45d0c0c7a994c67d096e78f36aa8ce9 (commit)
via 77d466ec556bf6722e20d0c7a9b253d69f113c6c (commit)
via 91eb736390b69d186edda8a1105d898cd58a77ca (commit)
via c6593511bb1b5f9b73df972ef92c6c9b0a045304 (commit)
from 1e1aeda71ce556388b343fe260c1b3f6453b945e (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=6f7cdfdde45d0c0c7a994c67d096e78f36aa8ce9
commit 6f7cdfdde45d0c0c7a994c67d096e78f36aa8ce9
Merge: 1e1aeda 77d466e
Author: Brad King <brad.king at kitware.com>
AuthorDate: Wed Apr 1 16:30:12 2015 -0400
Commit: CMake Topic Stage <kwrobot at kitware.com>
CommitDate: Wed Apr 1 16:30:12 2015 -0400
Merge topic 'doc-set-command' into next
77d466ec Help: Document conversion of PATH/FILEPATH cache values to absolute paths
91eb7363 Help: Rewrite 'set` command documentation
c6593511 Help: Add link target to cmake-language.7 variables section
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=77d466ec556bf6722e20d0c7a9b253d69f113c6c
commit 77d466ec556bf6722e20d0c7a9b253d69f113c6c
Author: Brad King <brad.king at kitware.com>
AuthorDate: Wed Apr 1 16:25:42 2015 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Wed Apr 1 16:29:52 2015 -0400
Help: Document conversion of PATH/FILEPATH cache values to absolute paths
Suggested-by: Roger Leigh <rleigh at codelibre.net>
diff --git a/Help/command/set.rst b/Help/command/set.rst
index 9f2bf72..d04b880 100644
--- a/Help/command/set.rst
+++ b/Help/command/set.rst
@@ -70,6 +70,15 @@ Furthermore, any normal variable binding in the current scope will
be removed to expose the newly cached value to any immediately
following evaluation.
+It is possible for the cache entry to exist prior to the call but
+have no type set if it was created on the :manual:`cmake(1)` command
+line by a user through the ``-D<var>=<value>`` option without
+specifying a type. In this case the ``set`` command will add the
+type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
+and the ``<value>`` provided on the command line is a relative path,
+then the ``set`` command will treat the path as relative to the
+current working directory and convert it to an absolute path.
+
Set Environment Variable
^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt
index 363d0aa..986b541 100644
--- a/Help/manual/OPTIONS_BUILD.txt
+++ b/Help/manual/OPTIONS_BUILD.txt
@@ -10,7 +10,7 @@
containing SET commands that use the CACHE option, not a
cache-format file.
-``-D <var>:<type>=<value>``
+``-D <var>:<type>=<value>, -D <var>=<value>``
Create a cmake cache entry.
When cmake is first run in an empty build tree, it creates a
@@ -19,6 +19,14 @@
takes priority over the project's default value. The option may be
repeated for as many cache entries as desired.
+ If the ``:<type>`` portion is given it must be one of the types
+ specified by the :command:`set` command documentation for its
+ ``CACHE`` signature.
+ If the ``:<type>`` portion is omitted the entry will be created
+ with no type if it does not exist with a type already. If a
+ command in the project sets the type to ``PATH`` or ``FILEPATH``
+ then the ``<value>`` will be converted to an absolute path.
+
``-U <globbing_expr>``
Remove matching entries from CMake cache.
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=91eb736390b69d186edda8a1105d898cd58a77ca
commit 91eb736390b69d186edda8a1105d898cd58a77ca
Author: Brad King <brad.king at kitware.com>
AuthorDate: Wed Apr 1 16:24:39 2015 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Wed Apr 1 16:29:52 2015 -0400
Help: Rewrite 'set` command documentation
Much of the information in the old set() command documentation is now
covered in the cmake-language(7) manual. Rewrite the documentation
with this in mind. Split up the signatures for each kind of variable
into different subsections.
diff --git a/Help/command/set.rst b/Help/command/set.rst
index 7a59550..9f2bf72 100644
--- a/Help/command/set.rst
+++ b/Help/command/set.rst
@@ -1,116 +1,80 @@
set
---
-Set a CMake, cache or environment variable to a given value.
+Set a normal, cache, or environment variable to a given value.
+See the :ref:`cmake-language(7) variables <CMake Language Variables>`
+documentation for the scopes and interaction of normal variables
+and cache entries.
+
+Signatures of this command that specify a ``<value>...`` placeholder
+expect zero or more arguments. Multiple arguments will be joined as
+a :ref:`;-list <CMake Language Lists>` to form the actual variable
+value to be set. Zero arguments will cause normal variables to be
+unset. See the :command:`unset` command to unset variables explicitly.
+
+Set Normal Variable
+^^^^^^^^^^^^^^^^^^^
::
- set(<variable> <value>
- [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
+ set(<variable> <value>... [PARENT_SCOPE])
+
+Set the given ``<variable>`` in the current function or directory scope.
+
+If the ``PARENT_SCOPE`` option is given the variable will be set in
+the scope above the current scope. Each new directory or function
+creates a new scope. This command will set the value of a variable
+into the parent directory or calling function (whichever is applicable
+to the case at hand).
-Within CMake sets <variable> to the value <value>. <value> is
-expanded before <variable> is set to it. Normally, set will set a
-regular CMake variable. If CACHE is present, then the <variable> is
-put in the cache instead, unless it is already in the cache. See
-section 'Variable types in CMake' below for details of regular and
-cache variables and their interactions. If CACHE is used, <type> and
-<docstring> are required. <type> is used by the CMake GUI to choose a
-widget with which the user sets a value. The value for <type> may be
-one of
+Set Cache Entry
+^^^^^^^^^^^^^^^
::
- FILEPATH = File chooser dialog.
- PATH = Directory chooser dialog.
- STRING = Arbitrary string.
- BOOL = Boolean ON/OFF checkbox.
- INTERNAL = No GUI entry (used for persistent variables).
+ set(<variable> <value>... CACHE <type> <docstring> [FORCE])
-If <type> is INTERNAL, the cache variable is marked as internal, and
-will not be shown to the user in tools like cmake-gui. This is
-intended for values that should be persisted in the cache, but which
-users should not normally change. INTERNAL implies FORCE.
+Set the given cache ``<variable>`` (cache entry). Since cache entries
+are meant to provide user-settable values this does not overwrite
+existing cache entries by default. Use the ``FORCE`` option to
+overwrite existing entries.
-Normally, set(...CACHE...) creates cache variables, but does not
-modify them. If FORCE is specified, the value of the cache variable
-is set, even if the variable is already in the cache. This should
-normally be avoided, as it will remove any changes to the cache
-variable's value by the user.
+The ``<type>`` must be specified as one of:
-If PARENT_SCOPE is present, the variable will be set in the scope
-above the current scope. Each new directory or function creates a new
-scope. This command will set the value of a variable into the parent
-directory or calling function (whichever is applicable to the case at
-hand). PARENT_SCOPE cannot be combined with CACHE.
+``BOOL``
+ Boolean ``ON/OFF`` value. :manual:`cmake-gui(1)` offers a checkbox.
-If <value> is not specified then the variable is removed instead of
-set. See also: the unset() command.
+``FILEPATH``
+ Path to a file on disk. :manual:`cmake-gui(1)` offers a file dialog.
-::
+``PATH``
+ Path to a directory on disk. :manual:`cmake-gui(1)` offers a file dialog.
+
+``STRING``
+ A line of text. :manual:`cmake-gui(1)` offers a text field or a
+ drop-down selection if the :prop_cache:`STRINGS` cache entry
+ property is set.
- set(<variable> <value1> ... <valueN>)
+``INTERNAL``
+ A line of text. :manual:`cmake-gui(1)` does not show internal entries.
+ They may be used to store variables persistently across runs.
+ Use of this type implies ``FORCE``.
-In this case <variable> is set to a semicolon separated list of
-values.
+The ``<docstring>`` must be specified as a line of text providing
+a quick summary of the option for presentation to :manual:`cmake-gui(1)`
+users.
-<variable> can be an environment variable such as:
+If the cache entry does not exist prior to the call or the ``FORCE``
+option is given then the cache entry will be set to the given value.
+Furthermore, any normal variable binding in the current scope will
+be removed to expose the newly cached value to any immediately
+following evaluation.
+
+Set Environment Variable
+^^^^^^^^^^^^^^^^^^^^^^^^
::
- set( ENV{PATH} /home/martink )
-
-in which case the environment variable will be set.
-
-*** Variable types in CMake ***
-
-In CMake there are two types of variables: normal variables and cache
-variables. Normal variables are meant for the internal use of the
-script (just like variables in most programming languages); they are
-not persisted across CMake runs. Cache variables (unless set with
-INTERNAL) are mostly intended for configuration settings where the
-first CMake run determines a suitable default value, which the user
-can then override, by editing the cache with tools such as ccmake or
-cmake-gui. Cache variables are stored in the CMake cache file, and
-are persisted across CMake runs.
-
-Both types can exist at the same time with the same name but different
-values. When ${FOO} is evaluated, CMake first looks for a normal
-variable 'FOO' in scope and uses it if set. If and only if no normal
-variable exists then it falls back to the cache variable 'FOO'.
-
-Some examples:
-
-The code 'set(FOO "x")' sets the normal variable 'FOO'. It does not
-touch the cache, but it will hide any existing cache value 'FOO'.
-
-The code 'set(FOO "x" CACHE ...)' checks for 'FOO' in the cache,
-ignoring any normal variable of the same name. If 'FOO' is in the
-cache then nothing happens to either the normal variable or the cache
-variable. If 'FOO' is not in the cache, then it is added to the
-cache.
-
-Finally, whenever a cache variable is added or modified by a command,
-CMake also *removes* the normal variable of the same name from the
-current scope so that an immediately following evaluation of it will
-expose the newly cached value.
-
-Normally projects should avoid using normal and cache variables of the
-same name, as this interaction can be hard to follow. However, in
-some situations it can be useful. One example (used by some
-projects):
-
-A project has a subproject in its source tree. The child project has
-its own CMakeLists.txt, which is included from the parent
-CMakeLists.txt using add_subdirectory(). Now, if the parent and the
-child project provide the same option (for example a compiler option),
-the parent gets the first chance to add a user-editable option to the
-cache. Normally, the child would then use the same value that the
-parent uses. However, it may be necessary to hard-code the value for
-the child project's option while still allowing the user to edit the
-value used by the parent project. The parent project can achieve this
-simply by setting a normal variable with the same name as the option
-in a scope sufficient to hide the option's cache variable from the
-child completely. The parent has already set the cache variable, so
-the child's set(...CACHE...) will do nothing, and evaluating the
-option variable will use the value from the normal variable, which
-hides the cache variable.
+ set(ENV{<variable>} <value>...)
+
+Set the current process environment ``<variable>`` to the given value.
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=c6593511bb1b5f9b73df972ef92c6c9b0a045304
commit c6593511bb1b5f9b73df972ef92c6c9b0a045304
Author: Brad King <brad.king at kitware.com>
AuthorDate: Wed Apr 1 16:24:24 2015 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Wed Apr 1 16:24:24 2015 -0400
Help: Add link target to cmake-language.7 variables section
diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst
index 4a9f0b5..41542c9 100644
--- a/Help/manual/cmake-language.7.rst
+++ b/Help/manual/cmake-language.7.rst
@@ -485,6 +485,8 @@ 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
=========
-----------------------------------------------------------------------
Summary of changes:
Help/command/set.rst | 163 ++++++++++++++++----------------------
Help/manual/OPTIONS_BUILD.txt | 10 ++-
Help/manual/cmake-language.7.rst | 2 +
3 files changed, 79 insertions(+), 96 deletions(-)
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list