From 91eb736390b69d186edda8a1105d898cd58a77ca Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 1 Apr 2015 16:24:39 -0400 Subject: [PATCH] Help: Rewrite 'set` command documentation Much of the information in the old set() command documentation is now covered in the cmake-language(7) manual. Rewrite the documentation with this in mind. Split up the signatures for each kind of variable into different subsections. --- Help/command/set.rst | 160 +++++++++++++++++-------------------------- 1 file changed, 62 insertions(+), 98 deletions(-) diff --git a/Help/command/set.rst b/Help/command/set.rst index 7a595505f..9f2bf72fb 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -1,116 +1,80 @@ 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 ` +documentation for the scopes and interaction of normal variables +and cache entries. + +Signatures of this command that specify a ``...`` placeholder +expect zero or more arguments. Multiple arguments will be joined as +a :ref:`;-list ` 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( - [[CACHE [FORCE]] | PARENT_SCOPE]) + set( ... [PARENT_SCOPE]) -Within CMake sets to the value . is -expanded before is set to it. Normally, set will set a -regular CMake variable. If CACHE is present, then the 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, and - are required. is used by the CMake GUI to choose a -widget with which the user sets a value. The value for may be -one of +Set the given ```` in the current function or directory scope. + +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( ... CACHE [FORCE]) -If 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 ```` (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 ```` 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 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. + +``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. + +``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``. + +The ```` 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. + +Set Environment Variable +^^^^^^^^^^^^^^^^^^^^^^^^ :: - set( ... ) + set(ENV{} ...) -In this case is set to a semicolon separated list of -values. - - 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. +Set the current process environment ```` to the given value.