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.