From c2efb3efcd083523a73a2a9721b7101fbfc0fe0f Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Tue, 16 Oct 2018 21:50:48 +0200 Subject: Help: Revise docs on Scripting Commands Revise docs for all "Scripting Commands", except four find_XXX that use a macro suite of their own. * Take full advantage of the improved syntax highlighting. * Make consequential use of <..> placeholders. * Clarify things here and there in the text. Specific improvements to some command docs: * "math": Correct description of novel hexadecimal capability. * "if", "foreach", "while": Provide link to "endif" etc * "foreach", "while": Mention "break" and "continue". * "foreach": Simplify explanation of ``RANGE`` and ``IN`` signatures; advise against negative arguments or reverse ranges (compare issue #18461) * "endif", "endfunction" etc: Explain that the argument is optional and maintained for compatibility only --- Help/command/break.rst | 4 +- Help/command/cmake_host_system_information.rst | 2 +- Help/command/cmake_minimum_required.rst | 16 +++-- Help/command/cmake_parse_arguments.rst | 22 +++--- Help/command/cmake_policy.rst | 12 ++-- Help/command/configure_file.rst | 22 ++++-- Help/command/continue.rst | 6 +- Help/command/else.rst | 4 +- Help/command/elseif.rst | 9 +-- Help/command/endforeach.rst | 8 ++- Help/command/endfunction.rst | 8 ++- Help/command/endif.rst | 8 ++- Help/command/endmacro.rst | 8 ++- Help/command/endwhile.rst | 8 ++- Help/command/file.rst | 32 ++++----- Help/command/find_package.rst | 10 ++- Help/command/foreach.rst | 99 ++++++++++++++++++-------- Help/command/function.rst | 38 +++++----- Help/command/get_cmake_property.rst | 12 ++-- Help/command/get_directory_property.rst | 6 +- Help/command/get_filename_component.rst | 30 +++----- Help/command/get_property.rst | 20 +++--- Help/command/if.rst | 25 ++++--- Help/command/include.rst | 10 +-- Help/command/include_guard.rst | 2 +- Help/command/list.rst | 60 ++++++++++------ Help/command/macro.rst | 36 ++++++---- Help/command/mark_as_advanced.rst | 27 ++++--- Help/command/math.rst | 40 ++++++----- Help/command/message.rst | 2 +- Help/command/option.rst | 15 ++-- Help/command/return.rst | 7 +- Help/command/separate_arguments.rst | 46 +++++++----- Help/command/set.rst | 12 ++-- Help/command/set_directory_properties.rst | 8 ++- Help/command/set_property.rst | 27 +++---- Help/command/site_name.rst | 2 +- Help/command/string.rst | 46 ++++++------ Help/command/unset.rst | 4 +- Help/command/variable_watch.rst | 14 ++-- Help/command/while.rst | 24 ++++--- 41 files changed, 472 insertions(+), 319 deletions(-) diff --git a/Help/command/break.rst b/Help/command/break.rst index fc2cd3c..4875a2b 100644 --- a/Help/command/break.rst +++ b/Help/command/break.rst @@ -3,10 +3,10 @@ break Break from an enclosing foreach or while loop. -:: +.. code-block:: cmake break() -Breaks from an enclosing foreach loop or while loop +Breaks from an enclosing :command:`foreach` or :command:`while` loop. See also the :command:`continue` command. diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 2dee93a..2e9563a 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -3,7 +3,7 @@ cmake_host_system_information Query host system specific information. -:: +.. code-block:: cmake cmake_host_system_information(RESULT QUERY ...) diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index 2f1ab60..e6ebcf0 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -1,11 +1,15 @@ cmake_minimum_required ---------------------- -Set the minimum required version of cmake for a project and -update `Policy Settings`_ to match the version given:: +Require a minimum version of cmake. + +.. code-block:: cmake cmake_minimum_required(VERSION [...] [FATAL_ERROR]) +Sets the minimum required version of cmake for a project. +Also updates the policy settings as explained below. + ```` and the optional ```` are each CMake versions of the form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal. @@ -47,13 +51,17 @@ as of a given CMake version and tells newer CMake versions to warn about their new policies. When a ```` version higher than 2.4 is specified the command -implicitly invokes:: +implicitly invokes + +.. code-block:: cmake cmake_policy(VERSION [...]) which sets CMake policies based on the range of versions specified. When a ```` version 2.4 or lower is given the command implicitly -invokes:: +invokes + +.. code-block:: cmake cmake_policy(VERSION 2.4[...]) diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index efbef54..c8327e2 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -1,26 +1,28 @@ cmake_parse_arguments --------------------- -``cmake_parse_arguments`` is intended to be used in macros or functions for -parsing the arguments given to that macro or function. It processes the -arguments and defines a set of variables which hold the values of the -respective options. +Parse function or macro arguments. -:: +.. code-block:: cmake cmake_parse_arguments( - args...) + ...) - cmake_parse_arguments(PARSE_ARGV N - ) + cmake_parse_arguments(PARSE_ARGV + ) + +This command is for use in macros or functions. +It processes the arguments given to that macro or function, +and defines a set of variables which hold the values of the +respective options. -The first signature reads processes arguments passed in the ``args...``. +The first signature reads processes arguments passed in the ``...``. This may be used in either a :command:`macro` or a :command:`function`. The ``PARSE_ARGV`` signature is only for use in a :command:`function` body. In this case the arguments that are parsed come from the ``ARGV#`` variables of the calling function. The parsing starts with -the Nth argument, where ``N`` is an unsigned integer. This allows for +the ````-th argument, where ```` is an unsigned integer. This allows for the values to have special characters like ``;`` in them. The ```` argument contains all options for the respective macro, diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index c3f7cfb..a80f982 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -22,7 +22,9 @@ Setting Policies by CMake Version The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW`` behavior. While setting policies individually is supported, we -encourage projects to set policies based on CMake versions:: +encourage projects to set policies based on CMake versions: + +.. code-block:: cmake cmake_policy(VERSION [...]) @@ -50,7 +52,7 @@ command implicitly calls ``cmake_policy(VERSION)`` too. Setting Policies Explicitly ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake cmake_policy(SET CMP NEW) cmake_policy(SET CMP OLD) @@ -66,7 +68,7 @@ policy state to ``NEW``. Checking Policy Settings ^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake cmake_policy(GET CMP ) @@ -85,7 +87,9 @@ scripts loaded by :command:`include` and :command:`find_package` commands except when invoked with the ``NO_POLICY_SCOPE`` option (see also policy :policy:`CMP0011`). The ``cmake_policy`` command provides an interface to manage custom -entries on the policy stack:: +entries on the policy stack: + +.. code-block:: cmake cmake_policy(PUSH) cmake_policy(POP) diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index e08c573..29e85bd 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -3,7 +3,7 @@ configure_file Copy a file to another location and modify its contents. -:: +.. code-block:: cmake configure_file( [COPYONLY] [ESCAPE_QUOTES] [@ONLY] @@ -13,15 +13,21 @@ Copies an ```` file to an ```` file and substitutes variable values referenced as ``@VAR@`` or ``${VAR}`` in the input file content. Each variable reference will be replaced with the current value of the variable, or the empty string if the variable -is not defined. Furthermore, input lines of the form:: +is not defined. Furthermore, input lines of the form + +.. code-block:: c #cmakedefine VAR ... -will be replaced with either:: +will be replaced with either + +.. code-block:: c #define VAR ... -or:: +or + +.. code-block:: c /* #undef VAR */ @@ -33,12 +39,16 @@ either ``#define VAR 1`` or ``#define VAR 0`` similarly. The result lines (with the exception of the ``#undef`` comments) can be indented using spaces and/or tabs between the ``#`` character and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace -indentation will be preserved in the output lines:: +indentation will be preserved in the output lines: + +.. code-block:: c # cmakedefine VAR # cmakedefine01 VAR -will be replaced, if ``VAR`` is defined, with:: +will be replaced, if ``VAR`` is defined, with + +.. code-block:: c # define VAR # define VAR 1 diff --git a/Help/command/continue.rst b/Help/command/continue.rst index 1c7d673..31c7089 100644 --- a/Help/command/continue.rst +++ b/Help/command/continue.rst @@ -3,10 +3,12 @@ continue Continue to the top of enclosing foreach or while loop. -:: +.. code-block:: cmake continue() The ``continue`` command allows a cmake script to abort the rest of a block in a :command:`foreach` or :command:`while` loop, and start at the top of -the next iteration. See also the :command:`break` command. +the next iteration. + +See also the :command:`break` command. diff --git a/Help/command/else.rst b/Help/command/else.rst index 0e5a198..a98fcd8 100644 --- a/Help/command/else.rst +++ b/Help/command/else.rst @@ -3,8 +3,8 @@ else Starts the else portion of an if block. -:: +.. code-block:: cmake - else(expression) + else([]) See the :command:`if` command. diff --git a/Help/command/elseif.rst b/Help/command/elseif.rst index 9a8dfed..6bf8646 100644 --- a/Help/command/elseif.rst +++ b/Help/command/elseif.rst @@ -1,10 +1,11 @@ elseif ------ -Starts the elseif portion of an if block. +Starts an elseif portion of an if block. -:: +.. code-block:: cmake - elseif(expression) + elseif() -See the :command:`if` command. +See the :command:`if` command, especially for the syntax and logic +of the ````. diff --git a/Help/command/endforeach.rst b/Help/command/endforeach.rst index 9af972b..fd923d5 100644 --- a/Help/command/endforeach.rst +++ b/Help/command/endforeach.rst @@ -3,8 +3,12 @@ endforeach Ends a list of commands in a foreach block. -:: +.. code-block:: cmake - endforeach(expression) + endforeach([]) See the :command:`foreach` command. + +The optional ```` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the ```` argument of +the opening ``foreach`` clause. diff --git a/Help/command/endfunction.rst b/Help/command/endfunction.rst index 6cc196c..e27129d 100644 --- a/Help/command/endfunction.rst +++ b/Help/command/endfunction.rst @@ -3,8 +3,12 @@ endfunction Ends a list of commands in a function block. -:: +.. code-block:: cmake - endfunction(expression) + endfunction([]) See the :command:`function` command. + +The optional ```` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the ```` argument +of the opening ``function`` command. diff --git a/Help/command/endif.rst b/Help/command/endif.rst index a0163bf..fc4f038 100644 --- a/Help/command/endif.rst +++ b/Help/command/endif.rst @@ -3,8 +3,12 @@ endif Ends a list of commands in an if block. -:: +.. code-block:: cmake - endif(expression) + endif([]) See the :command:`if` command. + +The optional ```` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the argument of the opening +``if`` clause. diff --git a/Help/command/endmacro.rst b/Help/command/endmacro.rst index 47327a7..4290ba7 100644 --- a/Help/command/endmacro.rst +++ b/Help/command/endmacro.rst @@ -3,8 +3,12 @@ endmacro Ends a list of commands in a macro block. -:: +.. code-block:: cmake - endmacro(expression) + endmacro([]) See the :command:`macro` command. + +The optional ```` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the ```` argument +of the opening ``macro`` command. diff --git a/Help/command/endwhile.rst b/Help/command/endwhile.rst index 798c20e..5ef585b 100644 --- a/Help/command/endwhile.rst +++ b/Help/command/endwhile.rst @@ -3,8 +3,12 @@ endwhile Ends a list of commands in a while block. -:: +.. code-block:: cmake - endwhile(expression) + endwhile([]) See the :command:`while` command. + +The optional ```` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the argument of the opening +``while`` clause. diff --git a/Help/command/file.rst b/Help/command/file.rst index d4a6006..f5279c0 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -42,7 +42,7 @@ Reading .. _READ: -:: +.. code-block:: cmake file(READ [OFFSET ] [LIMIT ] [HEX]) @@ -54,7 +54,7 @@ be converted to a hexadecimal representation (useful for binary data). .. _STRINGS: -:: +.. code-block:: cmake file(STRINGS [...]) @@ -105,7 +105,7 @@ from the input file. .. _HASH: -:: +.. code-block:: cmake file( ) @@ -116,7 +116,7 @@ command. .. _TIMESTAMP: -:: +.. code-block:: cmake file(TIMESTAMP [] [UTC]) @@ -133,7 +133,7 @@ Writing .. _WRITE: .. _APPEND: -:: +.. code-block:: cmake file(WRITE ...) file(APPEND ...) @@ -150,7 +150,7 @@ to update the file only when its content changes. .. _TOUCH: .. _TOUCH_NOCREATE: -:: +.. code-block:: cmake file(TOUCH [...]) file(TOUCH_NOCREATE [...]) @@ -167,7 +167,7 @@ modified. .. _GENERATE: -:: +.. code-block:: cmake file(GENERATE OUTPUT output-file @@ -217,7 +217,7 @@ Filesystem .. _GLOB: .. _GLOB_RECURSE: -:: +.. code-block:: cmake file(GLOB [LIST_DIRECTORIES true|false] [RELATIVE ] [CONFIGURE_DEPENDS] @@ -272,7 +272,7 @@ Examples of recursive globbing include:: .. _RENAME: -:: +.. code-block:: cmake file(RENAME ) @@ -282,7 +282,7 @@ Move a file or directory within a filesystem from ```` to .. _REMOVE: .. _REMOVE_RECURSE: -:: +.. code-block:: cmake file(REMOVE [...]) file(REMOVE_RECURSE [...]) @@ -293,7 +293,7 @@ given file does not exist. .. _MAKE_DIRECTORY: -:: +.. code-block:: cmake file(MAKE_DIRECTORY [...]) @@ -302,7 +302,7 @@ Create the given directories and their parents as needed. .. _COPY: .. _INSTALL: -:: +.. code-block:: cmake file( ... DESTINATION [FILE_PERMISSIONS ...] @@ -338,7 +338,7 @@ Path Conversion .. _RELATIVE_PATH: -:: +.. code-block:: cmake file(RELATIVE_PATH ) @@ -348,7 +348,7 @@ store it in the ````. .. _TO_CMAKE_PATH: .. _TO_NATIVE_PATH: -:: +.. code-block:: cmake file(TO_CMAKE_PATH "" ) file(TO_NATIVE_PATH "" ) @@ -370,7 +370,7 @@ Transfer .. _DOWNLOAD: .. _UPLOAD: -:: +.. code-block:: cmake file(DOWNLOAD [...]) file(UPLOAD [...]) @@ -460,7 +460,7 @@ Locking .. _LOCK: -:: +.. code-block:: cmake file(LOCK [DIRECTORY] [RELEASE] [GUARD ] diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 3ad571c..3ae9c2d 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -12,7 +12,7 @@ Find an external project, and load its settings. Basic Signature and Module Mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake find_package( [version] [EXACT] [QUIET] [MODULE] [REQUIRED] [[COMPONENTS] [components...]] @@ -67,7 +67,9 @@ full command signature and details of the search process. Project maintainers wishing to provide a package to be found by this command are encouraged to read on. -The complete Config mode command signature is:: +The complete Config mode command signature is + +.. code-block:: cmake find_package( [version] [EXACT] [QUIET] [REQUIRED] [[COMPONENTS] [components...]] @@ -202,7 +204,9 @@ is set no attempt is made to choose a highest or closest version number. To control the order in which ``find_package`` checks for compatibility use the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. -For instance in order to select the highest version one can set:: +For instance in order to select the highest version one can set + +.. code-block:: cmake SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index 106ba73..ae2afb2 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -3,45 +3,82 @@ foreach Evaluate a group of commands for each value in a list. -:: +.. code-block:: cmake - foreach(loop_var arg1 arg2 ...) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - endforeach(loop_var) + foreach( ) + + endforeach() -All commands between foreach and the matching endforeach are recorded -without being invoked. Once the endforeach is evaluated, the recorded -list of commands is invoked once for each argument listed in the -original foreach command. Before each iteration of the loop -``${loop_var}`` will be set as a variable with the current value in the -list. +where ```` is a list of items that are separated by +semicolon or whitespace. +All commands between ``foreach`` and the matching ``endforeach`` are recorded +without being invoked. Once the ``endforeach`` is evaluated, the recorded +list of commands is invoked once for each item in ````. +At the beginning of each iteration the variable ``loop_var`` will be set +to the value of the current item. -:: +The commands :command:`break` and :command:`continue` provide means to +escape from the normal control flow. - foreach(loop_var RANGE total) - foreach(loop_var RANGE start stop [step]) +Per legacy, the :command:`endforeach` command admits +an optional ```` argument. +If used, it must be a verbatim +repeat of the argument of the opening +``foreach`` command. -Foreach can also iterate over a generated range of numbers. There are -three types of this iteration: +.. code-block:: cmake -* When specifying single number, the range will have elements [0, ... to - "total"] (inclusive). + foreach( RANGE ) -* When specifying two numbers, the range will have elements from the - first number to the second number (inclusive). +In this variant, ``foreach`` iterates over the numbers +0, 1, ... up to (and including) the nonnegative integer ````. -* The third optional number is the increment used to iterate from the - first number to the second number (inclusive). +.. code-block:: cmake -:: + foreach( RANGE []) + +In this variant, ``foreach`` iterates over the numbers from +```` up to at most ```` in steps of ````. +If ```` is not specified, then the step size is 1. +The three arguments ```` ```` ```` must +all be nonnegative integers, and ```` must not be +smaller than ````; otherwise you enter the danger zone +of undocumented behavior that may change in future releases. + +.. code-block:: cmake + + foreach(loop_var IN [LISTS []] [ITEMS []]) - foreach(loop_var IN [LISTS [list1 [...]]] - [ITEMS [item1 [...]]]) +In this variant, ```` is a whitespace or semicolon +separated list of list-valued variables. The ``foreach`` +command iterates over each item in each given list. +The ```` following the ``ITEMS`` keyword are processed +as in the first variant of the ``foreach`` command. +The forms ``LISTS A`` and ``ITEMS ${A}`` are +equivalent. + +The following example shows how the ``LISTS`` option is +processed: + +.. code-block:: cmake + + set(A 0;1) + set(B 2 3) + set(C "4 5") + set(D 6;7 8) + set(E "") + foreach(X IN LISTS A B C D E) + message(STATUS "X=${X}") + endforeach() + +yields +:: -Iterates over a precise list of items. The ``LISTS`` option names -list-valued variables to be traversed, including empty elements (an -empty string is a zero-length list). (Note macro -arguments are not variables.) The ``ITEMS`` option ends argument -parsing and includes all arguments following it in the iteration. + -- X=0 + -- X=1 + -- X=2 + -- X=3 + -- X=4 5 + -- X=6 + -- X=7 + -- X=8 diff --git a/Help/command/function.rst b/Help/command/function.rst index 7ffdfee..4a223b4 100644 --- a/Help/command/function.rst +++ b/Help/command/function.rst @@ -1,27 +1,29 @@ function -------- -Start recording a function for later invocation as a command:: - - function( [arg1 [arg2 [arg3 ...]]]) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - endfunction() - -Define a function named ```` that takes arguments named ``arg1``, -``arg2``, ``arg3``, (...). -Commands listed after function, but before the matching -:command:`endfunction()`, are not invoked until the function is invoked. -When it is invoked, the commands recorded in the function are first -modified by replacing formal parameters (``${arg1}``) with the arguments -passed, and then invoked as normal commands. +Start recording a function for later invocation as a command. + +.. code-block:: cmake + + function( [ ...]) + + endfunction() + +Defines a function named ```` that takes arguments +named ````, ... +The ```` in the function definition are recorded; +they are not invoked until the function is invoked. When +the function is invoked, the recorded ```` are first +modified by replacing formal parameters (``${arg1}``, ...) +with the arguments passed, and then invoked as normal commands. + In addition to referencing the formal parameters you can reference the ``ARGC`` variable which will be set to the number of arguments passed into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which will have the actual values of the arguments passed in. This facilitates creating functions with optional arguments. -Additionally ``ARGV`` holds the list of all arguments given to the + +Furthermore, ``ARGV`` holds the list of all arguments given to the function and ``ARGN`` holds the list of arguments past the last expected argument. Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined @@ -29,6 +31,10 @@ behavior. Checking that ``ARGC`` is greater than ``#`` is the only way to ensure that ``ARGV#`` was passed to the function as an extra argument. +Per legacy, the :command:`endfunction` command admits an optional +```` argument. If used, it must be a verbatim repeat of the +argument of the opening ``function`` command. + A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for details. diff --git a/Help/command/get_cmake_property.rst b/Help/command/get_cmake_property.rst index 497ab4e..58bf741 100644 --- a/Help/command/get_cmake_property.rst +++ b/Help/command/get_cmake_property.rst @@ -3,14 +3,14 @@ get_cmake_property Get a global property of the CMake instance. -:: +.. code-block:: cmake - get_cmake_property(VAR property) + get_cmake_property( ) -Get a global property from the CMake instance. The value of the property is -stored in the variable ``VAR``. If the property is not found, ``VAR`` -will be set to "NOTFOUND". See the :manual:`cmake-properties(7)` manual -for available properties. +Gets a global property from the CMake instance. The value of +the ```` is stored in the variable ````. +If the property is not found, ```` will be set to ``"NOTFOUND"``. +See the :manual:`cmake-properties(7)` manual for available properties. See also the :command:`get_property` command ``GLOBAL`` option. diff --git a/Help/command/get_directory_property.rst b/Help/command/get_directory_property.rst index bf8349c..218efa9 100644 --- a/Help/command/get_directory_property.rst +++ b/Help/command/get_directory_property.rst @@ -3,11 +3,11 @@ get_directory_property Get a property of ``DIRECTORY`` scope. -:: +.. code-block:: cmake get_directory_property( [DIRECTORY ] ) -Store a property of directory scope in the named ````. +Stores a property of directory scope in the named ````. The ``DIRECTORY`` argument specifies another directory from which to retrieve the property value instead of the current directory. The specified directory must have already been traversed by CMake. @@ -18,7 +18,7 @@ if the property is not found for the nominated directory scope, the search will chain to a parent scope as described for the :command:`define_property` command. -:: +.. code-block:: cmake get_directory_property( [DIRECTORY ] DEFINITION ) diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index f11c0fc..3e3c9c3 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -3,13 +3,11 @@ get_filename_component Get a specific component of a full filename. ------------------------------------------------------------------------------- +.. code-block:: cmake -:: - - get_filename_component( [CACHE]) + get_filename_component( [CACHE]) -Set ```` to a component of ````, where ```` is one of: +Sets ```` to a component of ````, where ```` is one of: :: @@ -24,15 +22,11 @@ The longest file extension is always considered. If the optional ``CACHE`` argument is specified, the result variable is added to the cache. ------------------------------------------------------------------------------- - -:: +.. code-block:: cmake - get_filename_component( - [BASE_DIR ] - [CACHE]) + get_filename_component( [BASE_DIR ] [CACHE]) -Set ```` to the absolute path of ````, where ```` is one +Sets ```` to the absolute path of ````, where ```` is one of: :: @@ -41,7 +35,7 @@ of: REALPATH = Full path to existing file with symlinks resolved If the provided ```` is a relative path, it is evaluated relative -to the given base directory ````. If no base directory is +to the given base directory ````. If no base directory is provided, the default base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. @@ -49,16 +43,12 @@ Paths are returned with forward slashes and have no trailing slashes. If the optional ``CACHE`` argument is specified, the result variable is added to the cache. ------------------------------------------------------------------------------- - -:: +.. code-block:: cmake - get_filename_component( - PROGRAM [PROGRAM_ARGS ] - [CACHE]) + get_filename_component( PROGRAM [PROGRAM_ARGS ] [CACHE]) The program in ```` will be found in the system search path or left as a full path. If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then any command-line arguments present in the ```` string are split -from the program name and stored in ````. This is used to +from the program name and stored in ````. This is used to separate a program name from its arguments in a command line string. diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index 8b85f7d..c0f9b46 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -3,32 +3,33 @@ get_property Get a property. -:: +.. code-block:: cmake get_property( ] | TARGET | SOURCE | INSTALL | TEST | CACHE | - VARIABLE> + VARIABLE > PROPERTY [SET | DEFINED | BRIEF_DOCS | FULL_DOCS]) -Get one property from one object in a scope. The first argument -specifies the variable in which to store the result. The second -argument determines the scope from which to get the property. It must -be one of the following: +Gets one property from one object in a scope. + +The first argument specifies the variable in which to store the result. +The second argument determines the scope from which to get the property. +It must be one of the following: ``GLOBAL`` Scope is unique and does not accept a name. ``DIRECTORY`` Scope defaults to the current directory but another - directory (already processed by CMake) may be named by full or - relative path. + directory (already processed by CMake) may be named by the + full or relative path ````. ``TARGET`` Scope must name one existing target. @@ -58,6 +59,7 @@ value indicating whether the property has been set. If the ``DEFINED`` option is given the variable is set to a boolean value indicating whether the property has been defined such as with the :command:`define_property` command. + If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a string containing documentation for the requested property. If documentation is requested for a property that has not been defined diff --git a/Help/command/if.rst b/Help/command/if.rst index 8abe9ba..4781f35 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -6,7 +6,7 @@ Conditionally execute a group of commands. Synopsis ^^^^^^^^ -:: +.. code-block:: cmake if() @@ -23,8 +23,11 @@ Otherwise, optional ``elseif`` blocks are processed in the same way. Finally, if no ``condition`` is true, ``commands`` in the optional ``else`` block are executed. -Per legacy, the ``else`` and ``endif`` clause may also have a ``condition`` argument, -which then must be a verbatim repeat of the argument of the opening ``if`` clause. +Per legacy, the :command:`else` and :command:`elseif` commands admit +an optional ```` argument. +If used, it must be a verbatim +repeat of the argument of the opening +``if`` command. Condition Syntax ^^^^^^^^^^^^^^^^ @@ -202,21 +205,27 @@ The if command was written very early in CMake's history, predating the ``${}`` variable evaluation syntax, and for convenience evaluates variables named by its arguments as shown in the above signatures. Note that normal variable evaluation with ``${}`` applies before the if -command even receives the arguments. Therefore code like:: +command even receives the arguments. Therefore code like + +.. code-block:: cmake set(var1 OFF) set(var2 "var1") if(${var2}) -appears to the if command as:: +appears to the if command as + +.. code-block:: cmake - if(var1) + if(var1) and is evaluated according to the ``if()`` case documented above. The result is ``OFF`` which is false. However, if we remove the -``${}`` from the example then the command sees:: +``${}`` from the example then the command sees + +.. code-block:: cmake - if(var2) + if(var2) which is true because ``var2`` is defined to "var1" which is not a false constant. diff --git a/Help/command/include.rst b/Help/command/include.rst index eeca4c6..80968da 100644 --- a/Help/command/include.rst +++ b/Help/command/include.rst @@ -3,16 +3,16 @@ include Load and run CMake code from a file or module. -:: +.. code-block:: cmake - include( [OPTIONAL] [RESULT_VARIABLE ] + include( [OPTIONAL] [RESULT_VARIABLE ] [NO_POLICY_SCOPE]) -Load and run CMake code from the file given. Variable reads and +Loads and runs CMake code from the file given. Variable reads and writes access the scope of the caller (dynamic scoping). If ``OPTIONAL`` is present, then no error is raised if the file does not exist. If -``RESULT_VARIABLE`` is given the variable will be set to the full filename -which has been included or NOTFOUND if it failed. +``RESULT_VARIABLE`` is given the variable ```` will be set to the +full filename which has been included or ``NOTFOUND`` if it failed. If a module is specified instead of a file, the file with name ``.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`, diff --git a/Help/command/include_guard.rst b/Help/command/include_guard.rst index 62cce22..877aa86 100644 --- a/Help/command/include_guard.rst +++ b/Help/command/include_guard.rst @@ -3,7 +3,7 @@ include_guard Provides an include guard for the file currently being processed by CMake. -:: +.. code-block:: cmake include_guard([DIRECTORY|GLOBAL]) diff --git a/Help/command/list.rst b/Help/command/list.rst index 2357a9b..bfcdf34 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -64,7 +64,7 @@ Reading .. _LENGTH: -:: +.. code-block:: cmake list(LENGTH ) @@ -72,7 +72,7 @@ Returns the list's length. .. _GET: -:: +.. code-block:: cmake list(GET [ ...] ) @@ -80,7 +80,7 @@ Returns the list of elements specified by indices from the list. .. _JOIN: -:: +.. code-block:: cmake list(JOIN ) @@ -90,7 +90,7 @@ from :command:`string` command. .. _SUBLIST: -:: +.. code-block:: cmake list(SUBLIST ) @@ -104,7 +104,7 @@ Search .. _FIND: -:: +.. code-block:: cmake list(FIND ) @@ -116,7 +116,7 @@ Modification .. _APPEND: -:: +.. code-block:: cmake list(APPEND [ ...]) @@ -124,7 +124,7 @@ Appends elements to the list. .. _FILTER: -:: +.. code-block:: cmake list(FILTER REGEX ) @@ -136,7 +136,7 @@ For more information on regular expressions see also the .. _INSERT: -:: +.. code-block:: cmake list(INSERT [ ...]) @@ -144,7 +144,7 @@ Inserts elements to the list to the specified location. .. _REMOVE_ITEM: -:: +.. code-block:: cmake list(REMOVE_ITEM [ ...]) @@ -152,7 +152,7 @@ Removes the given items from the list. .. _REMOVE_AT: -:: +.. code-block:: cmake list(REMOVE_AT [ ...]) @@ -160,7 +160,7 @@ Removes items at given indices from the list. .. _REMOVE_DUPLICATES: -:: +.. code-block:: cmake list(REMOVE_DUPLICATES ) @@ -168,7 +168,7 @@ Removes duplicated items in the list. .. _TRANSFORM: -:: +.. code-block:: cmake list(TRANSFORM [] [OUTPUT_VARIABLE ]) @@ -190,30 +190,40 @@ The actions have exactly the same semantics as sub-commands of The ```` may be one of: ``APPEND``, ``PREPEND``: Append, prepend specified value to each element of -the list. :: +the list. + +.. code-block:: cmake list(TRANSFORM ...) ``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower -characters. :: +characters. + +.. code-block:: cmake list(TRANSFORM ...) ``STRIP``: Remove leading and trailing spaces from each element of the -list. :: +list. + +.. code-block:: cmake list(TRANSFORM STRIP ...) ``GENEX_STRIP``: Strip any :manual:`generator expressions ` from each -element of the list. :: +element of the list. + +.. code-block:: cmake list(TRANSFORM GENEX_STRIP ...) ``REPLACE``: Match the regular expression as many times as possible and substitute the replacement expression for the match for each element of the list -(Same semantic as ``REGEX REPLACE`` from :command:`string` command). :: +(Same semantic as ``REGEX REPLACE`` from :command:`string` command). + +.. code-block:: cmake list(TRANSFORM REPLACE ...) @@ -223,17 +233,23 @@ type of selector can be specified at a time. The ```` may be one of: -``AT``: Specify a list of indexes. :: +``AT``: Specify a list of indexes. + +.. code-block:: cmake list(TRANSFORM AT [ ...] ...) ``FOR``: Specify a range with, optionally, an increment used to iterate over -the range. :: +the range. + +.. code-block:: cmake list(TRANSFORM FOR [] ...) ``REGEX``: Specify a regular expression. Only elements matching the regular -expression will be transformed. :: +expression will be transformed. + +.. code-block:: cmake list(TRANSFORM REGEX ...) @@ -243,7 +259,7 @@ Ordering .. _REVERSE: -:: +.. code-block:: cmake list(REVERSE ) @@ -251,7 +267,7 @@ Reverses the contents of the list in-place. .. _SORT: -:: +.. code-block:: cmake list(SORT [COMPARE ] [CASE ] [ORDER ]) diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 6bee69c..2746b1b 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -1,27 +1,29 @@ macro ----- -Start recording a macro for later invocation as a command:: +Start recording a macro for later invocation as a command - macro( [arg1 [arg2 [arg3 ...]]]) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... +.. code-block:: cmake + + macro( [ ...]) + endmacro() -Define a macro named ```` that takes arguments named ``arg1``, -``arg2``, ``arg3``, (...). +Defines a macro named ```` that takes arguments +named ````, ... Commands listed after macro, but before the matching :command:`endmacro()`, are not invoked until the macro is invoked. When it is invoked, the commands recorded in the macro are first -modified by replacing formal parameters (``${arg1}``) with the arguments -passed, and then invoked as normal commands. +modified by replacing formal parameters (``${arg1}``, ...) +with the arguments passed, and then invoked as normal commands. + In addition to referencing the formal parameters you can reference the values ``${ARGC}`` which will be set to the number of arguments passed into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``, ... which will have the actual values of the arguments passed in. This facilitates creating macros with optional arguments. -Additionally ``${ARGV}`` holds the list of all arguments given to the + +Furthermore, ``${ARGV}`` holds the list of all arguments given to the macro and ``${ARGN}`` holds the list of arguments past the last expected argument. Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined @@ -38,7 +40,9 @@ Macro Argument Caveats Note that the parameters to a macro and values such as ``ARGN`` are not variables in the usual CMake sense. They are string replacements much like the C preprocessor would do with a macro. -Therefore you will NOT be able to use commands like:: +Therefore you will NOT be able to use commands like + +.. code-block:: cmake if(ARGV1) # ARGV1 is not a variable if(DEFINED ARGV2) # ARGV2 is not a variable @@ -50,18 +54,22 @@ In the second and third case, the proper way to check if an optional variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``. In the last case, you can use ``foreach(loop_var ${ARGN})`` but this will skip empty arguments. -If you need to include them, you can use:: +If you need to include them, you can use + +.. code-block:: cmake set(list_var "${ARGN}") foreach(loop_var IN LISTS list_var) Note that if you have a variable with the same name in the scope from which the macro is called, using unreferenced names will use the -existing variable instead of the arguments. For example:: +existing variable instead of the arguments. For example: + +.. code-block:: cmake macro(_BAR) foreach(arg IN LISTS ARGN) - [...] + endforeach() endmacro() diff --git a/Help/command/mark_as_advanced.rst b/Help/command/mark_as_advanced.rst index c3f94fc..5712fb4 100644 --- a/Help/command/mark_as_advanced.rst +++ b/Help/command/mark_as_advanced.rst @@ -3,17 +3,22 @@ mark_as_advanced Mark cmake cached variables as advanced. -:: +.. code-block:: cmake - mark_as_advanced([CLEAR|FORCE] VAR [VAR2 ...]) + mark_as_advanced([CLEAR|FORCE] ...) -Mark the named cached variables as advanced. An advanced variable -will not be displayed in any of the cmake GUIs unless the show -advanced option is on. If ``CLEAR`` is the first argument advanced -variables are changed back to unadvanced. If ``FORCE`` is the first -argument, then the variable is made advanced. If neither ``FORCE`` nor -``CLEAR`` is specified, new values will be marked as advanced, but if the -variable already has an advanced/non-advanced state, it will not be -changed. +Sets the advanced/non-advanced state of the named +cached variables. -It does nothing in script mode. +An advanced variable will not be displayed in any +of the cmake GUIs unless the ``show advanced`` option is on. +In script mode, the advanced/non-advanced state has no effect. + +If the keyword ``CLEAR`` is given +then advanced variables are changed back to unadvanced. +If the keyword ``FORCE`` is given +then the variables are made advanced. +If neither ``FORCE`` nor ``CLEAR`` is specified, +new values will be marked as advanced, but if a +variable already has an advanced/non-advanced state, +it will not be changed. diff --git a/Help/command/math.rst b/Help/command/math.rst index 63af931..4fa55f6 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -1,30 +1,36 @@ math ---- -Mathematical expressions. +Evaluate a mathematical expression. -:: +.. code-block:: cmake - math(EXPR [OUTPUT_FORMAT ]) + math(EXPR "" [OUTPUT_FORMAT ]) -``EXPR`` evaluates mathematical expression and returns result in the -output variable. Example mathematical expression is ``5 * (10 + 13)``. +Evaluates a mathematical ```` and sets ```` to the +resulting value. + +The mathematical expression must be given as a string (i.e. enclosed in +double quotation marks). An example is ``"5 * (10 + 13)"``. Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``, -``^``, ``~``, ``<<``, ``>>``, and ``(...)``. They have the same meaning -as they do in C code. +``^``, ``~``, ``<<``, ``>>``, and ``(...)``; they have the same meaning +as in C code. + +Hexadecimal numbers are recognized when prefixed with "0x", as in C code. -Numeric constants are evaluated in decimal or hexadecimal representation. +The result is formatted according to the option ``OUTPUT_FORMAT``, +where ```` is one of -The result is formatted according to the option "OUTPUT_FORMAT" , -where ```` is one of: -:: +``HEXADECIMAL`` + Hexadecimal notation as in C code, i. e. starting with "0x". +``DECIMAL`` + Decimal notation. Which is also used if no ``OUTPUT_FORMAT`` option + is specified. - HEXADECIMAL = Result in output variable will be formatted in C code - Hexadecimal notation. - DECIMAL = Result in output variable will be formatted in decimal notation. +For example -For example:: +.. code-block:: cmake - math(EXPR value "100 * 0xA" DECIMAL) results in value is set to "1000" - math(EXPR value "100 * 0xA" HEXADECIMAL) results in value is set to "0x3e8" + math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000" + math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8" diff --git a/Help/command/message.rst b/Help/command/message.rst index 04c62fd..2b4b1aa 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -3,7 +3,7 @@ message Display a message to the user. -:: +.. code-block:: cmake message([] "message to display" ...) diff --git a/Help/command/option.rst b/Help/command/option.rst index 4fabb87..8956307 100644 --- a/Help/command/option.rst +++ b/Help/command/option.rst @@ -1,17 +1,16 @@ option ------ -Provides an option that the user can optionally select. +Provide an option that the user can optionally select. -:: +.. code-block:: cmake - option( "help string describing option" - [initial value]) + option( "" [value]) -Provide an option for the user to select as ``ON`` or ``OFF``. If no -initial value is provided, ``OFF`` is used. If the option is already -set as a normal variable then the command does nothing -(see policy :policy:`CMP0077`). +Provides an option for the user to select as ``ON`` or ``OFF``. +If no initial ```` is provided, ``OFF`` is used. +If ```` is already set as a normal variable +then the command does nothing (see policy :policy:`CMP0077`). If you have options that depend on the values of other options, see the module help for :module:`CMakeDependentOption`. diff --git a/Help/command/return.rst b/Help/command/return.rst index e49fb3c..830992c 100644 --- a/Help/command/return.rst +++ b/Help/command/return.rst @@ -3,7 +3,7 @@ return Return from a file, directory or function. -:: +.. code-block:: cmake return() @@ -14,5 +14,6 @@ and control is returned to the including file. If it is encountered in a file which is not included by another file, e.g. a ``CMakeLists.txt``, control is returned to the parent directory if there is one. If return is called in a function, control is returned to the caller of the function. -Note that a macro is not a function and does not handle return like a -function does. + +Note that a :command:`macro `, unlike a :command:`function `, +is expanded in place and therefore cannot handle ``return()``. diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst index 47982a5..fbca859 100644 --- a/Help/command/separate_arguments.rst +++ b/Help/command/separate_arguments.rst @@ -1,33 +1,43 @@ separate_arguments ------------------ -Parse space-separated arguments into a semicolon-separated list. +Parse command-line arguments into a semicolon-separated list. -:: +.. code-block:: cmake - separate_arguments( _COMMAND "") + separate_arguments( ) -Parses a UNIX- or Windows-style command-line string "" and -stores a semicolon-separated list of the arguments in ````. The -entire command line must be given in one "" argument. +Parses a space-separated string ```` into a list of items, +and stores this list in semicolon-separated standard form in ````. -The ``UNIX_COMMAND`` mode separates arguments by unquoted whitespace. It -recognizes both single-quote and double-quote pairs. A backslash -escapes the next literal character (``\"`` is ``"``); there are no special -escapes (``\n`` is just ``n``). +This function is intended for parsing command-line arguments. +The entire command line must be passed as one string in the +argument ````. -The ``WINDOWS_COMMAND`` mode parses a Windows command-line using the same -syntax the runtime library uses to construct argv at startup. It -separates arguments by whitespace that is not double-quoted. -Backslashes are literal unless they precede double-quotes. See the -MSDN article `Parsing C Command-Line Arguments`_ for details. +The exact parsing rules depend on the operating system. +They are specified by the ```` argument which must +be one of the following keywords: -The ``NATIVE_COMMAND`` mode parses a Windows command-line if the host -system is Windows, and a UNIX command-line otherwise. +``UNIX_COMMAND`` + Arguments are separated by by unquoted whitespace. + Both single-quote and double-quote pairs are respected. + A backslash escapes the next literal character (``\"`` is ``"``); + there are no special escapes (``\n`` is just ``n``). + +``WINDOWS_COMMAND`` + A Windows command-line is parsed using the same + syntax the runtime library uses to construct argv at startup. It + separates arguments by whitespace that is not double-quoted. + Backslashes are literal unless they precede double-quotes. See the + MSDN article `Parsing C Command-Line Arguments`_ for details. + +``NATIVE_COMMAND`` + Proceeds as in ``WINDOWS_COMMAND`` mode if the host system is Windows. + Otherwise proceeds as in ``UNIX_COMMAND`` mode. .. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx -:: +.. code-block:: cmake separate_arguments() diff --git a/Help/command/set.rst b/Help/command/set.rst index b24ebef..d57b177 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -15,11 +15,11 @@ unset. See the :command:`unset` command to unset variables explicitly. Set Normal Variable ^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake set( ... [PARENT_SCOPE]) -Set the given ```` in the current function or directory scope. +Sets 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 @@ -32,11 +32,11 @@ undefined and if it had a value, it is still that value). Set Cache Entry ^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake set( ... CACHE [FORCE]) -Set the given cache ```` (cache entry). Since cache entries +Sets 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. @@ -84,8 +84,8 @@ current working directory and convert it to an absolute path. Set Environment Variable ^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake set(ENV{} ...) -Set the current process environment ```` to the given value. +Sets the current process environment ```` to the given value. diff --git a/Help/command/set_directory_properties.rst b/Help/command/set_directory_properties.rst index 42e7fd7..cc71522 100644 --- a/Help/command/set_directory_properties.rst +++ b/Help/command/set_directory_properties.rst @@ -1,11 +1,13 @@ set_directory_properties ------------------------ -Set properties of the current directory and subdirectories in key-value pairs. +Set properties of the current directory and subdirectories. -:: +.. code-block:: cmake - set_directory_properties(PROPERTIES prop1 value1 prop2 value2) + set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...) + +Sets properties of the current directory and its subdirectories in key-value pairs. See :ref:`Directory Properties` for the list of properties known to CMake and their individual documentation for the behavior of each property. diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index c89e1ce..2d270ec 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -3,21 +3,22 @@ set_property Set a named property in a given scope. -:: - - set_property( +.. code-block:: cmake + + set_property(] | + TARGET [ ...] | + SOURCE [ ...] | + INSTALL [ ...] | + TEST [ ...] | + CACHE [ ...] > [APPEND] [APPEND_STRING] - PROPERTY [value1 [value2 ...]]) + PROPERTY [value1 ...]) -Set one property on zero or more objects of a scope. The first -argument determines the scope in which the property is set. It must -be one of the following: +Sets one property on zero or more objects of a scope. + +The first argument determines the scope in which the property is set. +It must be one of the following: ``GLOBAL`` Scope is unique and does not accept a name. diff --git a/Help/command/site_name.rst b/Help/command/site_name.rst index e17c1ee..1bcaead 100644 --- a/Help/command/site_name.rst +++ b/Help/command/site_name.rst @@ -3,6 +3,6 @@ site_name Set the given variable to the name of the computer. -:: +.. code-block:: cmake site_name(variable) diff --git a/Help/command/string.rst b/Help/command/string.rst index cc18069..893fb43 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -48,7 +48,7 @@ Search and Replace .. _FIND: -:: +.. code-block:: cmake string(FIND [REVERSE]) @@ -59,7 +59,7 @@ substring. If the substring is not found, a position of -1 is returned. .. _REPLACE: -:: +.. code-block:: cmake string(REPLACE @@ -73,7 +73,7 @@ Regular Expressions .. _`REGEX MATCH`: -:: +.. code-block:: cmake string(REGEX MATCH [...]) @@ -83,7 +83,7 @@ All ```` arguments are concatenated before matching. .. _`REGEX MATCHALL`: -:: +.. code-block:: cmake string(REGEX MATCHALL [...]) @@ -94,7 +94,7 @@ All ```` arguments are concatenated before matching. .. _`REGEX REPLACE`: -:: +.. code-block:: cmake string(REGEX REPLACE @@ -177,7 +177,7 @@ Manipulation .. _APPEND: -:: +.. code-block:: cmake string(APPEND [...]) @@ -185,7 +185,7 @@ Append all the input arguments to the string. .. _PREPEND: -:: +.. code-block:: cmake string(PREPEND [...]) @@ -193,7 +193,7 @@ Prepend all the input arguments to the string. .. _CONCAT: -:: +.. code-block:: cmake string(CONCAT [...]) @@ -202,7 +202,7 @@ the result in the named output variable. .. _JOIN: -:: +.. code-block:: cmake string(JOIN [...]) @@ -215,7 +215,7 @@ special characters like ``;`` in them. .. _TOLOWER: -:: +.. code-block:: cmake string(TOLOWER ) @@ -223,7 +223,7 @@ Convert string to lower characters. .. _TOUPPER: -:: +.. code-block:: cmake string(TOUPPER ) @@ -231,7 +231,7 @@ Convert string to upper characters. .. _LENGTH: -:: +.. code-block:: cmake string(LENGTH ) @@ -239,7 +239,7 @@ Store in an output variable a given string's length. .. _SUBSTRING: -:: +.. code-block:: cmake string(SUBSTRING ) @@ -253,7 +253,7 @@ If string is shorter than length then end of string is used instead. .. _STRIP: -:: +.. code-block:: cmake string(STRIP ) @@ -262,7 +262,7 @@ trailing spaces removed. .. _GENEX_STRIP: -:: +.. code-block:: cmake string(GENEX_STRIP ) @@ -274,7 +274,7 @@ Comparison .. _COMPARE: -:: +.. code-block:: cmake string(COMPARE LESS ) string(COMPARE GREATER ) @@ -292,7 +292,7 @@ Hashing .. _`HASH`: -:: +.. code-block:: cmake string( ) @@ -325,7 +325,7 @@ Generation .. _ASCII: -:: +.. code-block:: cmake string(ASCII [ ...] ) @@ -333,7 +333,7 @@ Convert all numbers into corresponding ASCII characters. .. _CONFIGURE: -:: +.. code-block:: cmake string(CONFIGURE [@ONLY] [ESCAPE_QUOTES]) @@ -342,7 +342,7 @@ Transform a string like :command:`configure_file` transforms a file. .. _MAKE_C_IDENTIFIER: -:: +.. code-block:: cmake string(MAKE_C_IDENTIFIER ) @@ -353,7 +353,7 @@ the result. .. _RANDOM: -:: +.. code-block:: cmake string(RANDOM [LENGTH ] [ALPHABET ] [RANDOM_SEED ] ) @@ -366,7 +366,7 @@ random number generator. .. _TIMESTAMP: -:: +.. code-block:: cmake string(TIMESTAMP [] [UTC]) @@ -421,7 +421,7 @@ If no explicit ```` is given it will default to: .. _UUID: -:: +.. code-block:: cmake string(UUID NAMESPACE NAME TYPE [UPPER]) diff --git a/Help/command/unset.rst b/Help/command/unset.rst index c19dd31..1a5e49f 100644 --- a/Help/command/unset.rst +++ b/Help/command/unset.rst @@ -3,7 +3,7 @@ unset Unset a variable, cache variable, or environment variable. -:: +.. code-block:: cmake unset( [CACHE | PARENT_SCOPE]) @@ -24,7 +24,7 @@ for further details. ```` can be an environment variable such as: -:: +.. code-block:: cmake unset(ENV{LD_LIBRARY_PATH}) diff --git a/Help/command/variable_watch.rst b/Help/command/variable_watch.rst index a2df058..ce69bcf 100644 --- a/Help/command/variable_watch.rst +++ b/Help/command/variable_watch.rst @@ -3,11 +3,13 @@ variable_watch Watch the CMake variable for change. -:: +.. code-block:: cmake - variable_watch( []) + variable_watch( []) -If the specified variable changes, the message will be printed about -the variable being changed. If the command is specified, the command -will be executed. The command will receive the following arguments: -COMMAND( ) +If the specified ```` changes, a message will be printed +to inform about the change. + +Additionally, if ```` is given, this command will be executed. +The command will receive the following arguments: +``COMMAND( )`` diff --git a/Help/command/while.rst b/Help/command/while.rst index 7509da3..a4957c1 100644 --- a/Help/command/while.rst +++ b/Help/command/while.rst @@ -3,15 +3,23 @@ while Evaluate a group of commands while a condition is true -:: +.. code-block:: cmake - while(condition) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - endwhile(condition) + while() + + endwhile() All commands between while and the matching :command:`endwhile` are recorded without being invoked. Once the :command:`endwhile` is evaluated, the -recorded list of commands is invoked as long as the condition is true. The -condition is evaluated using the same logic as the :command:`if` command. +recorded list of commands is invoked as long as the ```` is true. + +The ```` has the same syntax and is evaluated using the same logic +as described at length for the :command:`if` command. + +The commands :command:`break` and :command:`continue` provide means to +escape from the normal control flow. + +Per legacy, the :command:`endwhile` command admits +an optional ```` argument. +If used, it must be a verbatim repeat of the argument of the opening +``while`` command. -- cgit v0.12