diff options
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 <variable> QUERY <key> ...) 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 <min>[...<max>] [FATAL_ERROR]) +Sets the minimum required version of cmake for a project. +Also updates the policy settings as explained below. + ``<min>`` and the optional ``<max>`` 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 ``<min>`` version higher than 2.4 is specified the command -implicitly invokes:: +implicitly invokes + +.. code-block:: cmake cmake_policy(VERSION <min>[...<max>]) which sets CMake policies based on the range of versions specified. When a ``<min>`` version 2.4 or lower is given the command implicitly -invokes:: +invokes + +.. code-block:: cmake cmake_policy(VERSION 2.4[...<max>]) 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(<prefix> <options> <one_value_keywords> - <multi_value_keywords> args...) + <multi_value_keywords> <args>...) - cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords> - <multi_value_keywords>) + cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options> + <one_value_keywords> <multi_value_keywords>) + +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 ``<args>...``. 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 ``<N>``-th argument, where ``<N>`` is an unsigned integer. This allows for the values to have special characters like ``;`` in them. The ``<options>`` 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 <min>[...<max>]) @@ -50,7 +52,7 @@ command implicitly calls ``cmake_policy(VERSION)`` too. Setting Policies Explicitly ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake cmake_policy(SET CMP<NNNN> NEW) cmake_policy(SET CMP<NNNN> OLD) @@ -66,7 +68,7 @@ policy state to ``NEW``. Checking Policy Settings ^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake cmake_policy(GET CMP<NNNN> <variable>) @@ -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(<input> <output> [COPYONLY] [ESCAPE_QUOTES] [@ONLY] @@ -13,15 +13,21 @@ Copies an ``<input>`` file to an ``<output>`` 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([<condition>]) 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(<condition>) -See the :command:`if` command. +See the :command:`if` command, especially for the syntax and logic +of the ``<condition>``. 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([<loop_var>]) See the :command:`foreach` command. + +The optional ``<loop_var>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the ``<loop_var>`` 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([<name>]) See the :command:`function` command. + +The optional ``<name>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the ``<name>`` 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([<condition>]) See the :command:`if` command. + +The optional ``<condition>`` 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([<name>]) See the :command:`macro` command. + +The optional ``<name>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the ``<name>`` 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([<condition>]) See the :command:`while` command. + +The optional ``<condition>`` 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 <filename> <variable> [OFFSET <offset>] [LIMIT <max-in>] [HEX]) @@ -54,7 +54,7 @@ be converted to a hexadecimal representation (useful for binary data). .. _STRINGS: -:: +.. code-block:: cmake file(STRINGS <filename> <variable> [<options>...]) @@ -105,7 +105,7 @@ from the input file. .. _HASH: -:: +.. code-block:: cmake file(<HASH> <filename> <variable>) @@ -116,7 +116,7 @@ command. .. _TIMESTAMP: -:: +.. code-block:: cmake file(TIMESTAMP <filename> <variable> [<format>] [UTC]) @@ -133,7 +133,7 @@ Writing .. _WRITE: .. _APPEND: -:: +.. code-block:: cmake file(WRITE <filename> <content>...) file(APPEND <filename> <content>...) @@ -150,7 +150,7 @@ to update the file only when its content changes. .. _TOUCH: .. _TOUCH_NOCREATE: -:: +.. code-block:: cmake file(TOUCH [<files>...]) file(TOUCH_NOCREATE [<files>...]) @@ -167,7 +167,7 @@ modified. .. _GENERATE: -:: +.. code-block:: cmake file(GENERATE OUTPUT output-file <INPUT input-file|CONTENT content> @@ -217,7 +217,7 @@ Filesystem .. _GLOB: .. _GLOB_RECURSE: -:: +.. code-block:: cmake file(GLOB <variable> [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] @@ -272,7 +272,7 @@ Examples of recursive globbing include:: .. _RENAME: -:: +.. code-block:: cmake file(RENAME <oldname> <newname>) @@ -282,7 +282,7 @@ Move a file or directory within a filesystem from ``<oldname>`` to .. _REMOVE: .. _REMOVE_RECURSE: -:: +.. code-block:: cmake file(REMOVE [<files>...]) file(REMOVE_RECURSE [<files>...]) @@ -293,7 +293,7 @@ given file does not exist. .. _MAKE_DIRECTORY: -:: +.. code-block:: cmake file(MAKE_DIRECTORY [<directories>...]) @@ -302,7 +302,7 @@ Create the given directories and their parents as needed. .. _COPY: .. _INSTALL: -:: +.. code-block:: cmake file(<COPY|INSTALL> <files>... DESTINATION <dir> [FILE_PERMISSIONS <permissions>...] @@ -338,7 +338,7 @@ Path Conversion .. _RELATIVE_PATH: -:: +.. code-block:: cmake file(RELATIVE_PATH <variable> <directory> <file>) @@ -348,7 +348,7 @@ store it in the ``<variable>``. .. _TO_CMAKE_PATH: .. _TO_NATIVE_PATH: -:: +.. code-block:: cmake file(TO_CMAKE_PATH "<path>" <variable>) file(TO_NATIVE_PATH "<path>" <variable>) @@ -370,7 +370,7 @@ Transfer .. _DOWNLOAD: .. _UPLOAD: -:: +.. code-block:: cmake file(DOWNLOAD <url> <file> [<options>...]) file(UPLOAD <file> <url> [<options>...]) @@ -460,7 +460,7 @@ Locking .. _LOCK: -:: +.. code-block:: cmake file(LOCK <path> [DIRECTORY] [RELEASE] [GUARD <FUNCTION|FILE|PROCESS>] 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(<PackageName> [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(<PackageName> [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(<loop_var> <items>) + <commands> + 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 ``<items>`` 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 ``<items>``. +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 ``<loop_var>`` 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(<loop_var> RANGE <stop>) -* 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 ``<stop>``. -* The third optional number is the increment used to iterate from the - first number to the second number (inclusive). +.. code-block:: cmake -:: + foreach(<loop_var> RANGE <start> <stop> [<step>]) + +In this variant, ``foreach`` iterates over the numbers from +``<start>`` up to at most ``<stop>`` in steps of ``<step>``. +If ``<step>`` is not specified, then the step size is 1. +The three arguments ``<start>`` ``<stop>`` ``<step>`` must +all be nonnegative integers, and ``<stop>`` must not be +smaller than ``<start>``; otherwise you enter the danger zone +of undocumented behavior that may change in future releases. + +.. code-block:: cmake + + foreach(loop_var IN [LISTS [<lists>]] [ITEMS [<items>]]) - foreach(loop_var IN [LISTS [list1 [...]]] - [ITEMS [item1 [...]]]) +In this variant, ``<lists>`` is a whitespace or semicolon +separated list of list-valued variables. The ``foreach`` +command iterates over each item in each given list. +The ``<items>`` 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(<name> [arg1 [arg2 [arg3 ...]]]) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - endfunction(<name>) - -Define a function named ``<name>`` 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(<name> [<arg1> ...]) + <commands> + endfunction() + +Defines a function named ``<name>`` that takes arguments +named ``<arg1>``, ... +The ``<commands>`` in the function definition are recorded; +they are not invoked until the function is invoked. When +the function is invoked, the recorded ``<commands>`` 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 +``<name>`` 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(<var> <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 ``<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. 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(<variable> [DIRECTORY <dir>] <prop-name>) -Store a property of directory scope in the named ``<variable>``. +Stores a property of directory scope in the named ``<variable>``. 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(<variable> [DIRECTORY <dir>] DEFINITION <var-name>) 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(<VAR> <FileName> <COMP> [CACHE]) + get_filename_component(<var> <FileName> <mode> [CACHE]) -Set ``<VAR>`` to a component of ``<FileName>``, where ``<COMP>`` is one of: +Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` 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(<VAR> <FileName> - <COMP> [BASE_DIR <BASE_DIR>] - [CACHE]) + get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE]) -Set ``<VAR>`` to the absolute path of ``<FileName>``, where ``<COMP>`` is one +Sets ``<var>`` to the absolute path of ``<FileName>``, where ``<mode>`` is one of: :: @@ -41,7 +35,7 @@ of: REALPATH = Full path to existing file with symlinks resolved If the provided ``<FileName>`` is a relative path, it is evaluated relative -to the given base directory ``<BASE_DIR>``. If no base directory is +to the given base directory ``<dir>``. 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(<VAR> <FileName> - PROGRAM [PROGRAM_ARGS <ARG_VAR>] - [CACHE]) + get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE]) The program in ``<FileName>`` 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 ``<FileName>`` string are split -from the program name and stored in ``<ARG_VAR>``. This is used to +from the program name and stored in ``<arg_var>``. 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(<variable> <GLOBAL | - DIRECTORY [dir] | + DIRECTORY [<dir>] | TARGET <target> | SOURCE <source> | INSTALL <file> | TEST <test> | CACHE <entry> | - VARIABLE> + VARIABLE > PROPERTY <name> [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 ``<dir>``. ``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(<condition>) <commands> @@ -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 ``<condition>`` 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(<variable>)`` 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(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>] + include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>] [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 ``<var>`` 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 ``<modulename>.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 <list> <output variable>) @@ -72,7 +72,7 @@ Returns the list's length. .. _GET: -:: +.. code-block:: cmake list(GET <list> <element index> [<element index> ...] <output variable>) @@ -80,7 +80,7 @@ Returns the list of elements specified by indices from the list. .. _JOIN: -:: +.. code-block:: cmake list(JOIN <list> <glue> <output variable>) @@ -90,7 +90,7 @@ from :command:`string` command. .. _SUBLIST: -:: +.. code-block:: cmake list(SUBLIST <list> <begin> <length> <output variable>) @@ -104,7 +104,7 @@ Search .. _FIND: -:: +.. code-block:: cmake list(FIND <list> <value> <output variable>) @@ -116,7 +116,7 @@ Modification .. _APPEND: -:: +.. code-block:: cmake list(APPEND <list> [<element> ...]) @@ -124,7 +124,7 @@ Appends elements to the list. .. _FILTER: -:: +.. code-block:: cmake list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) @@ -136,7 +136,7 @@ For more information on regular expressions see also the .. _INSERT: -:: +.. code-block:: cmake list(INSERT <list> <element_index> <element> [<element> ...]) @@ -144,7 +144,7 @@ Inserts elements to the list to the specified location. .. _REMOVE_ITEM: -:: +.. code-block:: cmake list(REMOVE_ITEM <list> <value> [<value> ...]) @@ -152,7 +152,7 @@ Removes the given items from the list. .. _REMOVE_AT: -:: +.. code-block:: cmake list(REMOVE_AT <list> <index> [<index> ...]) @@ -160,7 +160,7 @@ Removes items at given indices from the list. .. _REMOVE_DUPLICATES: -:: +.. code-block:: cmake list(REMOVE_DUPLICATES <list>) @@ -168,7 +168,7 @@ Removes duplicated items in the list. .. _TRANSFORM: -:: +.. code-block:: cmake list(TRANSFORM <list> <ACTION> [<SELECTOR>] [OUTPUT_VARIABLE <output variable>]) @@ -190,30 +190,40 @@ The actions have exactly the same semantics as sub-commands of The ``<ACTION>`` may be one of: ``APPEND``, ``PREPEND``: Append, prepend specified value to each element of -the list. :: +the list. + +.. code-block:: cmake list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) ``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower -characters. :: +characters. + +.. code-block:: cmake list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) ``STRIP``: Remove leading and trailing spaces from each element of the -list. :: +list. + +.. code-block:: cmake list(TRANSFORM <list> STRIP ...) ``GENEX_STRIP``: Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` from each -element of the list. :: +element of the list. + +.. code-block:: cmake list(TRANSFORM <list> 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 <list> REPLACE <regular_expression> <replace_expression> ...) @@ -223,17 +233,23 @@ type of selector can be specified at a time. The ``<SELECTOR>`` may be one of: -``AT``: Specify a list of indexes. :: +``AT``: Specify a list of indexes. + +.. code-block:: cmake list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) ``FOR``: Specify a range with, optionally, an increment used to iterate over -the range. :: +the range. + +.. code-block:: cmake list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) ``REGEX``: Specify a regular expression. Only elements matching the regular -expression will be transformed. :: +expression will be transformed. + +.. code-block:: cmake list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) @@ -243,7 +259,7 @@ Ordering .. _REVERSE: -:: +.. code-block:: cmake list(REVERSE <list>) @@ -251,7 +267,7 @@ Reverses the contents of the list in-place. .. _SORT: -:: +.. code-block:: cmake list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <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(<name> [arg1 [arg2 [arg3 ...]]]) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... +.. code-block:: cmake + + macro(<name> [<arg1> ...]) + <commands> endmacro(<name>) -Define a macro named ``<name>`` that takes arguments named ``arg1``, -``arg2``, ``arg3``, (...). +Defines a macro named ``<name>`` that takes arguments +named ``<arg1>``, ... 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) - [...] + <commands> 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] <var1> ...) -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-variable> <math-expression> [OUTPUT_FORMAT <format>]) + math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>]) -``EXPR`` evaluates mathematical expression and returns result in the -output variable. Example mathematical expression is ``5 * (10 + 13)``. +Evaluates a mathematical ``<expression>`` and sets ``<variable>`` 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 ``<format>`` is one of -The result is formatted according to the option "OUTPUT_FORMAT" , -where ``<format>`` 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([<mode>] "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(<option_variable> "help string describing option" - [initial value]) + option(<variable> "<help_text>" [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 ``<value>`` is provided, ``OFF`` is used. +If ``<variable>`` 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 <macro>`, unlike a :command:`function <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(<var> <NATIVE|UNIX|WINDOWS>_COMMAND "<args>") + separate_arguments(<variable> <mode> <args>) -Parses a UNIX- or Windows-style command-line string "<args>" and -stores a semicolon-separated list of the arguments in ``<var>``. The -entire command line must be given in one "<args>" argument. +Parses a space-separated string ``<args>`` into a list of items, +and stores this list in semicolon-separated standard form in ``<variable>``. -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 ``<args>``. -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 ``<mode>`` 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(<var>) 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(<variable> <value>... [PARENT_SCOPE]) -Set the given ``<variable>`` in the current function or directory scope. +Sets the given ``<variable>`` 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(<variable> <value>... CACHE <type> <docstring> [FORCE]) -Set the given cache ``<variable>`` (cache entry). Since cache entries +Sets 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. @@ -84,8 +84,8 @@ current working directory and convert it to an absolute path. Set Environment Variable ^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake set(ENV{<variable>} <value>...) -Set the current process environment ``<variable>`` to the given value. +Sets the current process environment ``<variable>`` 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(<GLOBAL | - DIRECTORY [dir] | - TARGET [target1 [target2 ...]] | - SOURCE [src1 [src2 ...]] | - INSTALL [file1 [file2 ...]] | - TEST [test1 [test2 ...]] | - CACHE [entry1 [entry2 ...]]> +.. code-block:: cmake + + set_property(<GLOBAL | + DIRECTORY [<dir>] | + TARGET [<target1> ...] | + SOURCE [<src1> ...] | + INSTALL [<file1> ...] | + TEST [<test1> ...] | + CACHE [<entry1> ...] > [APPEND] [APPEND_STRING] - PROPERTY <name> [value1 [value2 ...]]) + PROPERTY <name> [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 <string> <substring> <output variable> [REVERSE]) @@ -59,7 +59,7 @@ substring. If the substring is not found, a position of -1 is returned. .. _REPLACE: -:: +.. code-block:: cmake string(REPLACE <match_string> <replace_string> <output variable> @@ -73,7 +73,7 @@ Regular Expressions .. _`REGEX MATCH`: -:: +.. code-block:: cmake string(REGEX MATCH <regular_expression> <output variable> <input> [<input>...]) @@ -83,7 +83,7 @@ All ``<input>`` arguments are concatenated before matching. .. _`REGEX MATCHALL`: -:: +.. code-block:: cmake string(REGEX MATCHALL <regular_expression> <output variable> <input> [<input>...]) @@ -94,7 +94,7 @@ All ``<input>`` arguments are concatenated before matching. .. _`REGEX REPLACE`: -:: +.. code-block:: cmake string(REGEX REPLACE <regular_expression> <replace_expression> <output variable> @@ -177,7 +177,7 @@ Manipulation .. _APPEND: -:: +.. code-block:: cmake string(APPEND <string variable> [<input>...]) @@ -185,7 +185,7 @@ Append all the input arguments to the string. .. _PREPEND: -:: +.. code-block:: cmake string(PREPEND <string variable> [<input>...]) @@ -193,7 +193,7 @@ Prepend all the input arguments to the string. .. _CONCAT: -:: +.. code-block:: cmake string(CONCAT <output variable> [<input>...]) @@ -202,7 +202,7 @@ the result in the named output variable. .. _JOIN: -:: +.. code-block:: cmake string(JOIN <glue> <output variable> [<input>...]) @@ -215,7 +215,7 @@ special characters like ``;`` in them. .. _TOLOWER: -:: +.. code-block:: cmake string(TOLOWER <string1> <output variable>) @@ -223,7 +223,7 @@ Convert string to lower characters. .. _TOUPPER: -:: +.. code-block:: cmake string(TOUPPER <string1> <output variable>) @@ -231,7 +231,7 @@ Convert string to upper characters. .. _LENGTH: -:: +.. code-block:: cmake string(LENGTH <string> <output variable>) @@ -239,7 +239,7 @@ Store in an output variable a given string's length. .. _SUBSTRING: -:: +.. code-block:: cmake string(SUBSTRING <string> <begin> <length> <output variable>) @@ -253,7 +253,7 @@ If string is shorter than length then end of string is used instead. .. _STRIP: -:: +.. code-block:: cmake string(STRIP <string> <output variable>) @@ -262,7 +262,7 @@ trailing spaces removed. .. _GENEX_STRIP: -:: +.. code-block:: cmake string(GENEX_STRIP <input string> <output variable>) @@ -274,7 +274,7 @@ Comparison .. _COMPARE: -:: +.. code-block:: cmake string(COMPARE LESS <string1> <string2> <output variable>) string(COMPARE GREATER <string1> <string2> <output variable>) @@ -292,7 +292,7 @@ Hashing .. _`HASH`: -:: +.. code-block:: cmake string(<HASH> <output variable> <input>) @@ -325,7 +325,7 @@ Generation .. _ASCII: -:: +.. code-block:: cmake string(ASCII <number> [<number> ...] <output variable>) @@ -333,7 +333,7 @@ Convert all numbers into corresponding ASCII characters. .. _CONFIGURE: -:: +.. code-block:: cmake string(CONFIGURE <string1> <output variable> [@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 <input string> <output variable>) @@ -353,7 +353,7 @@ the result. .. _RANDOM: -:: +.. code-block:: cmake string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] [RANDOM_SEED <seed>] <output variable>) @@ -366,7 +366,7 @@ random number generator. .. _TIMESTAMP: -:: +.. code-block:: cmake string(TIMESTAMP <output variable> [<format string>] [UTC]) @@ -421,7 +421,7 @@ If no explicit ``<format string>`` is given it will default to: .. _UUID: -:: +.. code-block:: cmake string(UUID <output variable> NAMESPACE <namespace> NAME <name> TYPE <MD5|SHA1> [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(<variable> [CACHE | PARENT_SCOPE]) @@ -24,7 +24,7 @@ for further details. ``<variable>`` 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 name> [<command to execute>]) + variable_watch(<variable> [<command>]) -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(<variable> <access> <value> <current list file> <stack>) +If the specified ``<variable>`` changes, a message will be printed +to inform about the change. + +Additionally, if ``<command>`` is given, this command will be executed. +The command will receive the following arguments: +``COMMAND(<variable> <access> <value> <current_list_file> <stack>)`` 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(<condition>) + <commands> + 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 ``<condition>`` is true. + +The ``<condition>`` 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 ``<condition>`` argument. +If used, it must be a verbatim repeat of the argument of the opening +``while`` command. |