From f2c1f2402ee230bef6ebd3867aaa6f761466b61c Mon Sep 17 00:00:00 2001 From: Sebastian Leske Date: Mon, 11 Jun 2012 15:34:00 -0400 Subject: [PATCH] Improve documentation of set command (#13269) --- Source/cmSetCommand.h | 88 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 75 insertions(+), 13 deletions(-) diff --git a/Source/cmSetCommand.h b/Source/cmSetCommand.h index 66b129e32..2dd80e37f 100644 --- a/Source/cmSetCommand.h +++ b/Source/cmSetCommand.h @@ -52,7 +52,7 @@ public: */ virtual const char* GetTerseDocumentation() const { - return "Set a CMAKE variable to a given value."; + return "Set a CMake, cache or environment variable to a given value."; } /** @@ -63,26 +63,37 @@ public: return " set( \n" " [[CACHE [FORCE]] | PARENT_SCOPE])\n" - "Within CMake sets to the value . is expanded" - " before is set to it. If CACHE is present, then the " - " is put in the cache. and are then " - "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\n" + "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\n" " FILEPATH = File chooser dialog.\n" " PATH = Directory chooser dialog.\n" " STRING = Arbitrary string.\n" " BOOL = Boolean ON/OFF checkbox.\n" " INTERNAL = No GUI entry (used for persistent variables).\n" - "If is INTERNAL, then the is always written into the " - "cache, replacing any values existing in the cache. If it is not a " - "cache variable, then this always writes into the current makefile. The " - "FORCE option will overwrite the cache value removing any changes by " - "the user.\n" + "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." + "\n" + "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.\n" "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).\n" + "hand). PARENT_SCOPE cannot be combined with CACHE.\n" "If is not specified then the variable is removed " "instead of set. See also: the unset() command.\n" " set( ... )\n" @@ -90,7 +101,58 @@ public: "values.\n" " can be an environment variable such as:\n" " set( ENV{PATH} /home/martink )\n" - "in which case the environment variable will be set."; + "in which case the environment variable will be set.\n" + "*** Variable types in CMake ***\n" + "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. \n" + "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'.\n" + "Some examples:\n" + "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'.\n" + "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.\n" + "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.\n" + "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):" + "\n" + "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."; } cmTypeMacro(cmSetCommand, cmCommand);