This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "CMake".
The branch, master has been updated via da1580b48e84cf1fc3bfb518d7e78b61393a0ef2 (commit) via 26494d279fa527857139c128464b6e38260a9a0d (commit) via 3793bed9df0c7f056eaf85c0267088fc8cea647c (commit) via 008cb6aa991a515cd31a9b7e6a5837555ff2d43a (commit) via f87d5f13c29a961238ccf623d4954d2d0636adaa (commit) via 35fe47bd5d9508aa90fd1569eb2eaf3f982ebee5 (commit) via 8e56e8b28327fbe83562ad7a4e947b2275b1479d (commit) via d004d8c59a6daa5b27c6e737b687793f51557704 (commit) via c2efb3efcd083523a73a2a9721b7101fbfc0fe0f (commit) from 2296ede5ad67ace711f3f9c2dff33ea1f9b9aeb4 (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=da1580b48e84cf1fc3bfb518d7e78b61393a0ef2 commit da1580b48e84cf1fc3bfb518d7e78b61393a0ef2 Merge: 26494d2 f87d5f1 Author: Brad King <brad.k...@kitware.com> AuthorDate: Wed Oct 24 10:42:38 2018 -0400 Commit: Brad King <brad.k...@kitware.com> CommitDate: Wed Oct 24 10:42:38 2018 -0400 Merge branch 'release-3.13' https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=26494d279fa527857139c128464b6e38260a9a0d commit 26494d279fa527857139c128464b6e38260a9a0d Merge: 3793bed 8e56e8b Author: Brad King <brad.k...@kitware.com> AuthorDate: Wed Oct 24 14:40:13 2018 +0000 Commit: Kitware Robot <kwro...@kitware.com> CommitDate: Wed Oct 24 10:41:31 2018 -0400 Merge topic 'vs-csharp-win32-flags' 8e56e8b283 VS: Fix CSharp support for win32res: and win32icon: flags Acked-by: Kitware Robot <kwro...@kitware.com> Merge-request: !2516 https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=3793bed9df0c7f056eaf85c0267088fc8cea647c commit 3793bed9df0c7f056eaf85c0267088fc8cea647c Merge: 008cb6a d004d8c Author: Brad King <brad.k...@kitware.com> AuthorDate: Wed Oct 24 14:40:00 2018 +0000 Commit: Kitware Robot <kwro...@kitware.com> CommitDate: Wed Oct 24 10:40:24 2018 -0400 Merge topic 'vs-csharp-in-custom-target' d004d8c59a VS: Fix crash on CSharp sources in a custom target Acked-by: Kitware Robot <kwro...@kitware.com> Merge-request: !2515 https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=008cb6aa991a515cd31a9b7e6a5837555ff2d43a commit 008cb6aa991a515cd31a9b7e6a5837555ff2d43a Merge: 2296ede c2efb3e Author: Brad King <brad.k...@kitware.com> AuthorDate: Wed Oct 24 14:39:28 2018 +0000 Commit: Kitware Robot <kwro...@kitware.com> CommitDate: Wed Oct 24 10:39:39 2018 -0400 Merge topic 'scripting-commands' c2efb3efcd Help: Revise docs on Scripting Commands Acked-by: Kitware Robot <kwro...@kitware.com> Merge-request: !2504 https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=c2efb3efcd083523a73a2a9721b7101fbfc0fe0f commit c2efb3efcd083523a73a2a9721b7101fbfc0fe0f Author: Joachim Wuttke (l) <j.wut...@fz-juelich.de> AuthorDate: Tue Oct 16 21:50:48 2018 +0200 Commit: Joachim Wuttke (o) <j.wut...@fz-juelich.de> CommitDate: Tue Oct 23 15:12:10 2018 +0200 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 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. ----------------------------------------------------------------------- Summary of changes: 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 ++++-- Source/cmVS10CSharpFlagTable.h | 4 +- Source/cmVS11CSharpFlagTable.h | 4 +- Source/cmVS12CSharpFlagTable.h | 4 +- Source/cmVS140CSharpFlagTable.h | 4 +- Source/cmVS141CSharpFlagTable.h | 4 +- Source/cmVisualStudio10TargetGenerator.cxx | 4 + Tests/CSharpOnly/CMakeLists.txt | 3 + .../vtkIncluded.cxx => CSharpOnly/empty.cs} | 0 .../install/pattern => CSharpOnly}/empty.txt | 0 50 files changed, 489 insertions(+), 329 deletions(-) copy Tests/{Wrapping/vtkIncluded.cxx => CSharpOnly/empty.cs} (100%) copy Tests/{RunCMake/install/pattern => CSharpOnly}/empty.txt (100%) hooks/post-receive -- CMake _______________________________________________ Cmake-commits mailing list Cmake-commits@cmake.org https://cmake.org/mailman/listinfo/cmake-commits