summaryrefslogtreecommitdiffstats
path: root/Help/command/set.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Help/command/set.rst')
-rw-r--r--Help/command/set.rst116
1 files changed, 116 insertions, 0 deletions
diff --git a/Help/command/set.rst b/Help/command/set.rst
new file mode 100644
index 0000000..7a59550
--- /dev/null
+++ b/Help/command/set.rst
@@ -0,0 +1,116 @@
+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.