Help/command/set.rst

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.