set.rst 3.85 KB
Newer Older
1
2
3
set
---

4
5
6
7
8
9
10
Set a normal, cache, or environment variable to a given value.
See the :ref:`cmake-language(7) variables <CMake Language Variables>`
documentation for the scopes and interaction of normal variables
and cache entries.

Signatures of this command that specify a ``<value>...`` placeholder
expect zero or more arguments.  Multiple arguments will be joined as
11
a :ref:`semicolon-separated list <CMake Language Lists>` to form the actual variable
12
13
14
15
16
value to be set.  Zero arguments will cause normal variables to be
unset.  See the :command:`unset` command to unset variables explicitly.

Set Normal Variable
^^^^^^^^^^^^^^^^^^^
17

18
.. code-block:: cmake
19

20
21
  set(<variable> <value>... [PARENT_SCOPE])

22
Sets the given ``<variable>`` in the current function or directory scope.
23
24
25
26
27

If the ``PARENT_SCOPE`` option is given 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
28
29
30
to the case at hand). The previous state of the variable's value stays the
same in the current scope (e.g., if it was undefined before, it is still
undefined and if it had a value, it is still that value).
31

32
33
Set Cache Entry
^^^^^^^^^^^^^^^
34

35
.. code-block:: cmake
36

37
  set(<variable> <value>... CACHE <type> <docstring> [FORCE])
38

39
Sets the given cache ``<variable>`` (cache entry).  Since cache entries
40
41
42
are meant to provide user-settable values this does not overwrite
existing cache entries by default.  Use the ``FORCE`` option to
overwrite existing entries.
43

44
The ``<type>`` must be specified as one of:
45

46
47
``BOOL``
  Boolean ``ON/OFF`` value.  :manual:`cmake-gui(1)` offers a checkbox.
48

49
50
``FILEPATH``
  Path to a file on disk.  :manual:`cmake-gui(1)` offers a file dialog.
51

52
53
54
55
56
57
58
``PATH``
  Path to a directory on disk.  :manual:`cmake-gui(1)` offers a file dialog.

``STRING``
  A line of text.  :manual:`cmake-gui(1)` offers a text field or a
  drop-down selection if the :prop_cache:`STRINGS` cache entry
  property is set.
59

60
61
62
63
``INTERNAL``
  A line of text.  :manual:`cmake-gui(1)` does not show internal entries.
  They may be used to store variables persistently across runs.
  Use of this type implies ``FORCE``.
64

65
66
67
The ``<docstring>`` must be specified as a line of text providing
a quick summary of the option for presentation to :manual:`cmake-gui(1)`
users.
68

69
70
71
72
73
74
If the cache entry does not exist prior to the call or the ``FORCE``
option is given then the cache entry will be set to the given value.
Furthermore, any normal variable binding in the current scope will
be removed to expose the newly cached value to any immediately
following evaluation.

75
76
77
78
79
80
81
82
83
It is possible for the cache entry to exist prior to the call but
have no type set if it was created on the :manual:`cmake(1)` command
line by a user through the ``-D<var>=<value>`` option without
specifying a type.  In this case the ``set`` command will add the
type.  Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
and the ``<value>`` provided on the command line is a relative path,
then the ``set`` command will treat the path as relative to the
current working directory and convert it to an absolute path.

84
85
Set Environment Variable
^^^^^^^^^^^^^^^^^^^^^^^^
86

87
.. code-block:: cmake
88

89
  set(ENV{<variable>} [<value>])
90

91
92
93
94
95
96
97
Sets an :manual:`Environment Variable <cmake-env-variables(7)>`
to the given value.
Subsequent calls of ``$ENV{<variable>}`` will return this new value.

This command affects only the current CMake process, not the process
from which CMake was called, nor the system environment at large,
nor the environment of subsequent build or test processes.
98
99
100
101
102
103
104

If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is
an empty string, then this command will clear any existing value of the
environment variable.

Arguments after ``<value>`` are ignored. If extra arguments are found,
then an author warning is issued.