Help/command/set.rst

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