117 lines
4.8 KiB
ReStructuredText
117 lines
4.8 KiB
ReStructuredText
set
|
|
---
|
|
|
|
Set a CMake, cache or environment variable to a given value.
|
|
|
|
::
|
|
|
|
set(<variable> <value>
|
|
[[CACHE <type> <docstring> [FORCE]] | 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
|
|
|
|
::
|
|
|
|
FILEPATH = File chooser dialog.
|
|
PATH = Directory chooser dialog.
|
|
STRING = Arbitrary string.
|
|
BOOL = Boolean ON/OFF checkbox.
|
|
INTERNAL = No GUI entry (used for persistent variables).
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
If <value> is not specified then the variable is removed instead of
|
|
set. See also: the unset() command.
|
|
|
|
::
|
|
|
|
set(<variable> <value1> ... <valueN>)
|
|
|
|
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.
|