1set
2---
3
4Set a normal, cache, or environment variable to a given value.
5See the :ref:`cmake-language(7) variables <CMake Language Variables>`
6documentation for the scopes and interaction of normal variables
7and cache entries.
8
9Signatures of this command that specify a ``<value>...`` placeholder
10expect zero or more arguments.  Multiple arguments will be joined as
11a :ref:`semicolon-separated list <CMake Language Lists>` to form the actual variable
12value to be set.  Zero arguments will cause normal variables to be
13unset.  See the :command:`unset` command to unset variables explicitly.
14
15Set Normal Variable
16^^^^^^^^^^^^^^^^^^^
17
18.. code-block:: cmake
19
20  set(<variable> <value>... [PARENT_SCOPE])
21
22Sets the given ``<variable>`` in the current function or directory scope.
23
24If the ``PARENT_SCOPE`` option is given the variable will be set in
25the scope above the current scope.  Each new directory or function
26creates a new scope.  This command will set the value of a variable
27into the parent directory or calling function (whichever is applicable
28to the case at hand). The previous state of the variable's value stays the
29same in the current scope (e.g., if it was undefined before, it is still
30undefined and if it had a value, it is still that value).
31
32Set Cache Entry
33^^^^^^^^^^^^^^^
34
35.. code-block:: cmake
36
37  set(<variable> <value>... CACHE <type> <docstring> [FORCE])
38
39Sets the given cache ``<variable>`` (cache entry).  Since cache entries
40are meant to provide user-settable values this does not overwrite
41existing cache entries by default.  Use the ``FORCE`` option to
42overwrite existing entries.
43
44The ``<type>`` must be specified as one of:
45
46``BOOL``
47  Boolean ``ON/OFF`` value.  :manual:`cmake-gui(1)` offers a checkbox.
48
49``FILEPATH``
50  Path to a file on disk.  :manual:`cmake-gui(1)` offers a file dialog.
51
52``PATH``
53  Path to a directory on disk.  :manual:`cmake-gui(1)` offers a file dialog.
54
55``STRING``
56  A line of text.  :manual:`cmake-gui(1)` offers a text field or a
57  drop-down selection if the :prop_cache:`STRINGS` cache entry
58  property is set.
59
60``INTERNAL``
61  A line of text.  :manual:`cmake-gui(1)` does not show internal entries.
62  They may be used to store variables persistently across runs.
63  Use of this type implies ``FORCE``.
64
65The ``<docstring>`` must be specified as a line of text providing
66a quick summary of the option for presentation to :manual:`cmake-gui(1)`
67users.
68
69If the cache entry does not exist prior to the call or the ``FORCE``
70option is given then the cache entry will be set to the given value.
71
72.. note::
73
74  The content of the cache variable will not be directly accessible if a normal
75  variable of the same name already exists (see :ref:`rules of variable
76  evaluation <CMake Language Variables>`). If policy :policy:`CMP0126` is set
77  to ``OLD``, any normal variable binding in the current scope will be removed.
78
79It is possible for the cache entry to exist prior to the call but
80have no type set if it was created on the :manual:`cmake(1)` command
81line by a user through the ``-D<var>=<value>`` option without
82specifying a type.  In this case the ``set`` command will add the
83type.  Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
84and the ``<value>`` provided on the command line is a relative path,
85then the ``set`` command will treat the path as relative to the
86current working directory and convert it to an absolute path.
87
88Set Environment Variable
89^^^^^^^^^^^^^^^^^^^^^^^^
90
91.. code-block:: cmake
92
93  set(ENV{<variable>} [<value>])
94
95Sets an :manual:`Environment Variable <cmake-env-variables(7)>`
96to the given value.
97Subsequent calls of ``$ENV{<variable>}`` will return this new value.
98
99This command affects only the current CMake process, not the process
100from which CMake was called, nor the system environment at large,
101nor the environment of subsequent build or test processes.
102
103If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is
104an empty string, then this command will clear any existing value of the
105environment variable.
106
107Arguments after ``<value>`` are ignored. If extra arguments are found,
108then an author warning is issued.
109