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.