Merge topic 'doc-set-command'

77d466ec Help: Document conversion of PATH/FILEPATH cache values to absolute paths
91eb7363 Help: Rewrite 'set` command documentation
c6593511 Help: Add link target to cmake-language.7 variables section

Help/command/set.rst

@@ -1,116 +1,89 @@
 set
 ---
 
-Set a CMake, cache or environment variable to a given value.
+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
+a :ref:`;-list <CMake Language Lists>` to form the actual variable
+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
+^^^^^^^^^^^^^^^^^^^
 
 ::
 
-  set(<variable> <value>
-      [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
+  set(<variable> <value>... [PARENT_SCOPE])
+
+Set the given ``<variable>`` in the current function or directory 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
+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
+to the case at hand).
+
+Set Cache Entry
+^^^^^^^^^^^^^^^
 
 ::
 
-  FILEPATH = File chooser dialog.
-  PATH     = Directory chooser dialog.
-  STRING   = Arbitrary string.
-  BOOL     = Boolean ON/OFF checkbox.
-  INTERNAL = No GUI entry (used for persistent variables).
+  set(<variable> <value>... CACHE <type> <docstring> [FORCE])
 
-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.
+Set the given cache ``<variable>`` (cache entry).  Since cache entries
+are meant to provide user-settable values this does not overwrite
+existing cache entries by default.  Use the ``FORCE`` option to
+overwrite existing entries.
 
-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.
+The ``<type>`` must be specified as one of:
 
-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.
+``BOOL``
+  Boolean ``ON/OFF`` value.  :manual:`cmake-gui(1)` offers a checkbox.
 
-If <value> is not specified then the variable is removed instead of
-set.  See also: the unset() command.
+``FILEPATH``
+  Path to a file on disk.  :manual:`cmake-gui(1)` offers a file dialog.
 
-::
+``PATH``
+  Path to a directory on disk.  :manual:`cmake-gui(1)` offers a file dialog.
 
-  set(<variable> <value1> ... <valueN>)
+``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.
 
-In this case <variable> is set to a semicolon separated list of
-values.
+``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``.
 
-<variable> can be an environment variable such as:
+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.
+
+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.
+
+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.
+
+Set Environment Variable
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
-  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.
+  set(ENV{<variable>} <value>...)
+
+Set the current process environment ``<variable>`` to the given value.

Help/manual/OPTIONS_BUILD.txt

@@ -10,7 +10,7 @@
  containing SET commands that use the CACHE option, not a
  cache-format file.
 
-``-D <var>:<type>=<value>``
+``-D <var>:<type>=<value>, -D <var>=<value>``
  Create a cmake cache entry.
 
  When cmake is first run in an empty build tree, it creates a
@@ -19,6 +19,14 @@
  takes priority over the project's default value.  The option may be
  repeated for as many cache entries as desired.
 
+ If the ``:<type>`` portion is given it must be one of the types
+ specified by the :command:`set` command documentation for its
+ ``CACHE`` signature.
+ If the ``:<type>`` portion is omitted the entry will be created
+ with no type if it does not exist with a type already.  If a
+ command in the project sets the type to ``PATH`` or ``FILEPATH``
+ then the ``<value>`` will be converted to an absolute path.
+
 ``-U <globbing_expr>``
  Remove matching entries from CMake cache.
 

Help/manual/cmake-language.7.rst

@@ -485,6 +485,8 @@ The :command:`macro`/:command:`endmacro`, and
 :command:`function`/:command:`endfunction` commands delimit
 code blocks to be recorded for later invocation as commands.
 
+.. _`CMake Language Variables`:
+
 Variables
 =========