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.
This commit is contained in:
Brad King
parent
c6593511bb
commit
91eb736390
|
|
@ -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])
|
||||
|
||||
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 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).
|
||||
|
||||
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.
|
||||
|
||||
``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``.
|
||||
|
||||
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.
|
||||
|
||||
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(<variable> <value1> ... <valueN>)
|
||||
set(ENV{<variable>} <value>...)
|
||||
|
||||
In this case <variable> is set to a semicolon separated list of
|
||||
values.
|
||||
|
||||
<variable> can be an environment variable such as:
|
||||
|
||||
::
|
||||
|
||||
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 the current process environment ``<variable>`` to the given value.
|
||||
|
|
|
|||
Loading…
Reference in New Issue