diff options
Diffstat (limited to 'Help/command')
46 files changed, 713 insertions, 476 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/ctest_submit.rst b/Help/command/ctest_submit.rst index 2ba6bef..426475c 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -33,6 +33,7 @@ The options are: ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES Upload = Files prepared for upload by ctest_upload(), in Upload.xml Submit = nothing + Done = Build is complete, in Done.xml ``FILES <file>...`` Specify an explicit list of specific files to be submitted. 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/execute_process.rst b/Help/command/execute_process.rst index 716f457..fc7d177 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -5,8 +5,8 @@ Execute one or more child processes. .. code-block:: cmake - execute_process(COMMAND <cmd1> [args1...]] - [COMMAND <cmd2> [args2...] [...]] + execute_process(COMMAND <cmd1> [<arguments>] + [COMMAND <cmd2> [<arguments>]]... [WORKING_DIRECTORY <directory>] [TIMEOUT <seconds>] [RESULT_VARIABLE <variable>] 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 b486b79..3ae9c2d 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -1,9 +1,18 @@ find_package ------------ -Load settings for an external project. +.. only:: html -:: + .. contents:: + +Find an external project, and load its settings. + +.. _`basic signature`: + +Basic Signature and Module Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] [REQUIRED] [[COMPONENTS] [components...]] @@ -15,7 +24,6 @@ will be set to indicate whether the package was found. When the package is found package-specific information is provided through variables and :ref:`Imported Targets` documented by the package itself. The ``QUIET`` option disables messages if the package cannot be found. The -``MODULE`` option disables the second signature documented below. The ``REQUIRED`` option stops processing with an error message if the package cannot be found. @@ -33,26 +41,35 @@ should be compatible (format is ``major[.minor[.patch[.tweak]]]``). The inside a find-module, the corresponding arguments are forwarded automatically from the outer call (including the ``EXACT`` flag for ``[version]``). Version support is currently provided only on a -package-by-package basis (details below). +package-by-package basis (see the `Version Selection`_ section below). + +See the :command:`cmake_policy` command documentation for discussion +of the ``NO_POLICY_SCOPE`` option. -User code should generally look for packages using the above simple -signature. The remainder of this command documentation specifies the +The command has two modes by which it searches for packages: "Module" +mode and "Config" mode. The above signature selects Module mode. +If no module is found the command falls back to Config mode, described +below. This fall back is disabled if the ``MODULE`` option is given. + +In Module mode, CMake searches for a file called ``Find<PackageName>.cmake`` +in the :variable:`CMAKE_MODULE_PATH` followed by the CMake installation. +If the file is found, it is read and processed by CMake. It is responsible +for finding the package, checking the version, and producing any needed +messages. Some find-modules provide limited or no support for versioning; +check the module documentation. + +Full Signature and Config Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +User code should generally look for packages using the above `basic +signature`_. The remainder of this command documentation specifies the 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 command has two modes by which it searches for packages: "Module" -mode and "Config" mode. Module mode is available when the command is -invoked with the above reduced signature. CMake searches for a file -called ``Find<PackageName>.cmake`` in the :variable:`CMAKE_MODULE_PATH` -followed by the CMake installation. If the file is found, it is read -and processed by CMake. It is responsible for finding the package, -checking the version, and producing any needed messages. Many -find-modules provide limited or no support for versioning; check -the module documentation. If no module is found and the ``MODULE`` -option is not given the command proceeds to Config mode. - -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...]] @@ -76,12 +93,12 @@ The complete Config mode command signature is:: ONLY_CMAKE_FIND_ROOT_PATH | NO_CMAKE_FIND_ROOT_PATH]) -The ``CONFIG`` option may be used to skip Module mode explicitly and -switch to Config mode. It is synonymous to using ``NO_MODULE``. Config -mode is also implied by use of options not specified in the reduced -signature. +The ``CONFIG`` option, the synonymous ``NO_MODULE`` option, or the use +of options not specified in the `basic signature`_ all enforce pure Config +mode. In pure Config mode, the command skips Module mode search and +proceeds at once with Config mode search. -Config mode attempts to locate a configuration file provided by the +Config mode search attempts to locate a configuration file provided by the package to be found. A cache entry called ``<PackageName>_DIR`` is created to hold the directory containing the file. By default the command searches for a package with the name ``<PackageName>``. If the ``NAMES`` option @@ -107,6 +124,13 @@ fatal error is generated and the configure step stops executing. If ``<PackageName>_DIR`` has been set to a directory not containing a configuration file CMake will ignore it and search from scratch. +Package maintainers providing CMake package configuration files are +encouraged to name and install them such that the `Search Procedure`_ +outlined below will find them without requiring use of additional options. + +Version Selection +^^^^^^^^^^^^^^^^^ + When the ``[version]`` argument is given Config mode will only find a version of the package that claims compatibility with the requested version (format is ``major[.minor[.patch[.tweak]]]``). If the ``EXACT`` @@ -180,24 +204,17 @@ 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) before calling ``find_package``. -Config mode provides an elaborate interface and search procedure. -Much of the interface is provided for completeness and for use -internally by find-modules loaded by Module mode. Most user code -should simply call:: - - find_package(<PackageName> [major[.minor]] [EXACT] [REQUIRED|QUIET]) - -in order to find a package. Package maintainers providing CMake -package configuration files are encouraged to name and install them -such that the procedure outlined below will find them without -requiring use of additional options. +Search Procedure +^^^^^^^^^^^^^^^^ CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a @@ -339,6 +356,9 @@ enabled. Every non-REQUIRED ``find_package`` call can be disabled by setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``. +Package File Interface Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + When loading a find module or package configuration file ``find_package`` defines variables to provide information about the call arguments (and restores their original state before returning): @@ -377,6 +397,3 @@ configuration file to handle components in a way that makes sense for the package. The package configuration file may set ``<PackageName>_FOUND`` to false to tell ``find_package`` that component requirements are not satisfied. - -See the :command:`cmake_policy` command documentation for discussion -of the ``NO_POLICY_SCOPE`` option. 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 5294ce8..4781f35 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -3,41 +3,49 @@ if Conditionally execute a group of commands. +Synopsis +^^^^^^^^ + .. code-block:: cmake - if(expression) - # then section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - #... - elseif(expression2) - # elseif section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - #... - else(expression) - # else section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - #... - endif(expression) - -Evaluates the given expression. If the result is true, the commands -in the THEN section are invoked. Otherwise, the commands in the else -section are invoked. The elseif and else sections are optional. You -may have multiple elseif clauses. Note that the expression in the -else and endif clause is optional. Long expressions can be used and -there is a traditional order of precedence. Parenthetical expressions -are evaluated first followed by unary tests such as ``EXISTS``, -``COMMAND``, and ``DEFINED``. Then any binary tests such as + if(<condition>) + <commands> + elseif(<condition>) # optional block, can be repeated + <commands> + else() # optional block + <commands> + endif() + +Evaluates the ``condition`` argument of the ``if`` clause according to the +`Condition syntax`_ described below. If the result is true, then the +``commands`` in the ``if`` block are executed. +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 :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 +^^^^^^^^^^^^^^^^ + +The following syntax applies to the ``condition`` argument of +the ``if``, ``elseif`` and :command:`while` clauses. + +Compound conditions are evaluated in the following order of precedence: +Innermost parentheses are evaluated first. Next come unary tests such +as ``EXISTS``, ``COMMAND``, and ``DEFINED``. Then binary tests such as ``EQUAL``, ``LESS``, ``LESS_EQUAL``, ``GREATER``, ``GREATER_EQUAL``, ``STREQUAL``, ``STRLESS``, ``STRLESS_EQUAL``, ``STRGREATER``, ``STRGREATER_EQUAL``, ``VERSION_EQUAL``, ``VERSION_LESS``, ``VERSION_LESS_EQUAL``, ``VERSION_GREATER``, ``VERSION_GREATER_EQUAL``, -and ``MATCHES`` will be evaluated. Then boolean ``NOT`` operators and -finally boolean ``AND`` and then ``OR`` operators will be evaluated. +and ``MATCHES``. Then the boolean operators in the order ``NOT``, ``AND``, +and finally ``OR``. -Possible expressions are: +Possible conditions are: ``if(<constant>)`` True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``, @@ -52,14 +60,14 @@ Possible expressions are: True if given a variable that is defined to a value that is not a false constant. False otherwise. (Note macro arguments are not variables.) -``if(NOT <expression>)`` - True if the expression is not true. +``if(NOT <condition>)`` + True if the condition is not true. -``if(<expr1> AND <expr2>)`` - True if both expressions would be considered true individually. +``if(<cond1> AND <cond2>)`` + True if both conditions would be considered true individually. -``if(<expr1> OR <expr2>)`` - True if either expression would be considered true individually. +``if(<cond1> OR <cond2>)`` + True if either condition would be considered true individually. ``if(COMMAND command-name)`` True if the given name is a command, macro or function that can be @@ -103,7 +111,7 @@ Possible expressions are: ``if(<variable|string> MATCHES regex)`` True if the given string or variable's value matches the given regular - expression. See :ref:`Regex Specification` for regex format. + condition. See :ref:`Regex Specification` for regex format. ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. ``if(<variable|string> LESS <variable|string>)`` @@ -184,31 +192,40 @@ Possible expressions are: variable is true or false just if it has been set. (Note macro arguments are not variables.) -``if((expression) AND (expression OR (expression)))`` - The expressions inside the parenthesis are evaluated first and then - the remaining expression is evaluated as in the previous examples. +``if((condition) AND (condition OR (condition)))`` + The conditions inside the parenthesis are evaluated first and then + the remaining condition is evaluated as in the previous examples. Where there are nested parenthesis the innermost are evaluated as part - of evaluating the expression that contains them. + of evaluating the condition that contains them. + +Variable Expansion +^^^^^^^^^^^^^^^^^^ 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 - if(var1) +.. code-block:: cmake + + 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/install.rst b/Help/command/install.rst index 08c5718..98074d0 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -442,10 +442,6 @@ example, the code will print a message during installation. -The contents of ``SCRIPT`` or ``CODE`` may use "generator expressions" with -the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` -manual for available expressions. - Installing Exports ^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/list.rst b/Help/command/list.rst index ad2c428..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,25 +267,29 @@ Reverses the contents of the list in-place. .. _SORT: -:: +.. code-block:: cmake list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) Sorts the list in-place alphabetically. -Use the option ``<compare>`` to select the compare type for sorting. -The ``<compare>`` option may be one of: +Use the ``COMPARE`` keyword to select the comparison method for sorting. +The ``<compare>`` option should be one of: -* ``STRING``: Sorts a list of strings alphabetically. -* ``FILE_BASENAME``: Sort a list of pathnames of files by their basenames. +* ``STRING``: Sorts a list of strings alphabetically. This is the + default behavior if the ``COMPARE`` option is not given. +* ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames. -Use the option ``<case>`` to select a case sensitive or case insensitive sort mode. -The ``<case>`` option may be one of: +Use the ``CASE`` keyword to select a case sensitive or case insensitive +sort mode. The ``<case>`` option should be one of: -* ``SENSITIVE``: Sorts the list alphabetically. -* ``INSENSITIVE``: Sorts the list alphabetically in descending order. +* ``SENSITIVE``: List items are sorted in a case-sensitive manner. This is + the default behavior if the ``CASE`` option is not given. +* ``INSENSITIVE``: List items are sorted case insensitively. The order of + items which differ only by upper/lowercase is not specified. -Use the option ``<order>`` to select a case sensitive or case insensitive sort mode. -The ``<order>`` option may be one of: +To control the sort order, the ``ORDER`` keyword can be given. +The ``<order>`` option should be one of: -* ``ASCENDING``: Sorts the list in ascending order. +* ``ASCENDING``: Sorts the list in ascending order. This is the default + behavior when the ``ORDER`` option is not given. * ``DESCENDING``: Sorts the list in descending 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/project.rst b/Help/command/project.rst index c1de057..688e56c 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -1,88 +1,119 @@ project ------- -Sets project details such as name, version, etc. and enables languages. +Set the name of the project. + +Synopsis +^^^^^^^^ .. code-block:: cmake - project(<PROJECT-NAME> [LANGUAGES] [<language-name>...]) + project(<PROJECT-NAME> [<language-name>...]) project(<PROJECT-NAME> [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] [DESCRIPTION <project-description-string>] [HOMEPAGE_URL <url-string>] [LANGUAGES <language-name>...]) -Sets the name of the project and stores the name in the -:variable:`PROJECT_NAME` variable. Additionally this sets variables +Sets the name of the project, and stores it in the variable +:variable:`PROJECT_NAME`. When called from the top-level +``CMakeLists.txt`` also stores the project name in the +variable :variable:`CMAKE_PROJECT_NAME`. + +Also sets the variables * :variable:`PROJECT_SOURCE_DIR`, :variable:`<PROJECT-NAME>_SOURCE_DIR` * :variable:`PROJECT_BINARY_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR` -If ``VERSION`` is specified, given components must be non-negative integers. -If ``VERSION`` is not specified, the default version is the empty string. -The ``VERSION`` option may not be used unless policy :policy:`CMP0048` is -set to ``NEW``. - -The :command:`project()` command stores the version number and its components -in variables - -* :variable:`PROJECT_VERSION`, - :variable:`<PROJECT-NAME>_VERSION` -* :variable:`PROJECT_VERSION_MAJOR`, - :variable:`<PROJECT-NAME>_VERSION_MAJOR` -* :variable:`PROJECT_VERSION_MINOR`, - :variable:`<PROJECT-NAME>_VERSION_MINOR` -* :variable:`PROJECT_VERSION_PATCH`, - :variable:`<PROJECT-NAME>_VERSION_PATCH` -* :variable:`PROJECT_VERSION_TWEAK`, - :variable:`<PROJECT-NAME>_VERSION_TWEAK` - -Variables corresponding to unspecified versions are set to the empty string -(if policy :policy:`CMP0048` is set to ``NEW``). - -If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION` -and :variable:`<PROJECT-NAME>_DESCRIPTION` will be set to its argument. -The description is expected to be a relatively short string, usually no more -than a few words. - -The optional ``HOMEPAGE_URL`` sets the analogous variables -:variable:`PROJECT_HOMEPAGE_URL` and :variable:`<PROJECT-NAME>_HOMEPAGE_URL`. -When this option is given, the URL provided should be the canonical home for -the project. - -Note that the description and homepage URL may be used as defaults for -things like packaging meta-data, documentation, etc. - -Optionally you can specify which languages your project supports. -Example languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, -``Fortran``, and ``ASM``. -By default ``C`` and ``CXX`` are enabled if no language options are -given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword -and list no languages, to skip enabling any languages. - -If enabling ``ASM``, list it last so that CMake can check whether -compilers for other languages like ``C`` work for assembly too. - -If a variable exists called :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +Further variables are set by the optional arguments described in the following. +If any of these arguments is not used, then the corresponding variables are +set to the empty string. + +If the variable :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` exists, the file pointed to by that variable will be included as the last step of the project command. +Options +^^^^^^^ + +The options are: + +``VERSION <version>`` + Optional; may not be used unless policy :policy:`CMP0048` is + set to ``NEW``. + + Takes a ``<version>`` argument composed of non-negative integer components, + i.e. ``<major>[.<minor>[.<patch>[.<tweak>]]]``, + and sets the variables + + * :variable:`PROJECT_VERSION`, + :variable:`<PROJECT-NAME>_VERSION` + * :variable:`PROJECT_VERSION_MAJOR`, + :variable:`<PROJECT-NAME>_VERSION_MAJOR` + * :variable:`PROJECT_VERSION_MINOR`, + :variable:`<PROJECT-NAME>_VERSION_MINOR` + * :variable:`PROJECT_VERSION_PATCH`, + :variable:`<PROJECT-NAME>_VERSION_PATCH` + * :variable:`PROJECT_VERSION_TWEAK`, + :variable:`<PROJECT-NAME>_VERSION_TWEAK`. + + When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + then the version is also stored in the variable :variable:`CMAKE_PROJECT_VERSION`. + +``DESCRIPTION <project-description-string>`` + Optional. + Sets the variables + + * :variable:`PROJECT_DESCRIPTION`, :variable:`<PROJECT-NAME>_DESCRIPTION` + + to ``<project-description-string>``. + It is recommended that this description is a relatively short string, + usually no more than a few words. + + When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`. + +``HOMEPAGE_URL <url-string>`` + Optional. + Sets the variables + + * :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL` + + to ``<url-string>``, which should be the canonical home URL for the project. + + When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + then the URL also is stored in the variable :variable:`CMAKE_PROJECT_HOMEPAGE_URL`. + +``LANGUAGES <language-name>...`` + Optional. + Can also be specified without ``LANGUAGES`` keyword per the first, short signature. + + Selects which programming languages are needed to build the project. + Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, ``Fortran``, and ``ASM``. + By default ``C`` and ``CXX`` are enabled if no language options are given. + Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, + to skip enabling any languages. + + If enabling ``ASM``, list it last so that CMake can check whether + compilers for other languages like ``C`` work for assembly too. + +The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL`` +options are intended for use as default values in package metadata and documentation. + +Usage +^^^^^ + The top-level ``CMakeLists.txt`` file for a project must contain a literal, direct call to the :command:`project` command; loading one through the :command:`include` command is not sufficient. If no such call exists CMake will implicitly add one to the top that enables the -default languages (``C`` and ``CXX``). The name of the project set in -the top level ``CMakeLists.txt`` file is available from the -:variable:`CMAKE_PROJECT_NAME` variable, its description from -:variable:`CMAKE_PROJECT_DESCRIPTION`, its homepage URL from -:variable:`CMAKE_PROJECT_HOMEPAGE_URL` and its version from -:variable:`CMAKE_PROJECT_VERSION`. +default languages (``C`` and ``CXX``). .. note:: Call the :command:`cmake_minimum_required` command at the beginning of the top-level ``CMakeLists.txt`` file even before calling the - ``project()`` command. It is important to establish version and + :command:`project()` command. It is important to establish version and policy settings before invoking other commands whose behavior they may affect. See also policy :policy:`CMP0000`. 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 29a153a..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> @@ -121,6 +121,11 @@ The following characters have special meaning in regular expressions: Matches at end of input ``.`` Matches any single character +``\<char>`` + Matches the single character specified by ``<char>``. Use this to + match special regex characters, e.g. ``\.`` for a literal ``.`` + or ``\\`` for a literal backslash ``\``. Escaping a non-special + character is unnecessary but allowed, e.g. ``\a`` matches ``a``. ``[ ]`` Matches any character(s) inside the brackets ``[^ ]`` @@ -151,12 +156,9 @@ has lower precedence than concatenation. This means that the regular expression ``^ab+d$`` matches ``abbd`` but not ``ababd``, and the regular expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``. -Backslash (``\``) characters in regular expressions are interpreted -literally and do not escape anything or represent placeholders. -However, CMake language :ref:`Escape Sequences` such as ``\t``, -``\r``, ``\n``, and ``\\`` may be used to construct literal tabs, -carriage returns, newlines, and backslashes (respectively) to pass -in a regex. For example: +CMake language :ref:`Escape Sequences` such as ``\t``, ``\r``, ``\n``, +and ``\\`` may be used to construct literal tabs, carriage returns, +newlines, and backslashes (respectively) to pass in a regex. For example: * The quoted argument ``"[ \t\r\n]"`` specifies a regex that matches any single whitespace character. @@ -164,13 +166,18 @@ in a regex. For example: a single forward slash ``/`` or backslash ``\``. * The quoted argument ``"[A-Za-z0-9_]"`` specifies a regex that matches any single "word" character in the C locale. +* The quoted argument ``"\\(\\a\\+b\\)"`` specifies a regex that matches + the exact string ``(a+b)``. Each ``\\`` is parsed in a quoted argument + as just ``\``, so the regex itself is actually ``\(\a\+\b\)``. This + can alternatively be specified in a :ref:`bracket argument` without + having to escape the backslashes, e.g. ``[[\(\a\+\b\)]]``. Manipulation ^^^^^^^^^^^^ .. _APPEND: -:: +.. code-block:: cmake string(APPEND <string variable> [<input>...]) @@ -178,7 +185,7 @@ Append all the input arguments to the string. .. _PREPEND: -:: +.. code-block:: cmake string(PREPEND <string variable> [<input>...]) @@ -186,7 +193,7 @@ Prepend all the input arguments to the string. .. _CONCAT: -:: +.. code-block:: cmake string(CONCAT <output variable> [<input>...]) @@ -195,7 +202,7 @@ the result in the named output variable. .. _JOIN: -:: +.. code-block:: cmake string(JOIN <glue> <output variable> [<input>...]) @@ -208,7 +215,7 @@ special characters like ``;`` in them. .. _TOLOWER: -:: +.. code-block:: cmake string(TOLOWER <string1> <output variable>) @@ -216,7 +223,7 @@ Convert string to lower characters. .. _TOUPPER: -:: +.. code-block:: cmake string(TOUPPER <string1> <output variable>) @@ -224,7 +231,7 @@ Convert string to upper characters. .. _LENGTH: -:: +.. code-block:: cmake string(LENGTH <string> <output variable>) @@ -232,7 +239,7 @@ Store in an output variable a given string's length. .. _SUBSTRING: -:: +.. code-block:: cmake string(SUBSTRING <string> <begin> <length> <output variable>) @@ -246,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>) @@ -255,7 +262,7 @@ trailing spaces removed. .. _GENEX_STRIP: -:: +.. code-block:: cmake string(GENEX_STRIP <input string> <output variable>) @@ -267,7 +274,7 @@ Comparison .. _COMPARE: -:: +.. code-block:: cmake string(COMPARE LESS <string1> <string2> <output variable>) string(COMPARE GREATER <string1> <string2> <output variable>) @@ -285,7 +292,7 @@ Hashing .. _`HASH`: -:: +.. code-block:: cmake string(<HASH> <output variable> <input>) @@ -318,7 +325,7 @@ Generation .. _ASCII: -:: +.. code-block:: cmake string(ASCII <number> [<number> ...] <output variable>) @@ -326,7 +333,7 @@ Convert all numbers into corresponding ASCII characters. .. _CONFIGURE: -:: +.. code-block:: cmake string(CONFIGURE <string1> <output variable> [@ONLY] [ESCAPE_QUOTES]) @@ -335,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>) @@ -346,7 +353,7 @@ the result. .. _RANDOM: -:: +.. code-block:: cmake string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] [RANDOM_SEED <seed>] <output variable>) @@ -359,7 +366,7 @@ random number generator. .. _TIMESTAMP: -:: +.. code-block:: cmake string(TIMESTAMP <output variable> [<format string>] [UTC]) @@ -414,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/target_link_libraries.rst b/Help/command/target_link_libraries.rst index e1c374e..58f312e 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -43,6 +43,9 @@ Each ``<item>`` may be: the library instead of using the full path (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``). + The full path to the target's artifact will be quoted/escaped for + the shell automatically. + * **A full path to a library file**: The generated link line will normally preserve the full path to the file. The buildsystem will have a dependency to re-link ``<target>`` if the library file changes. @@ -62,9 +65,15 @@ Each ``<item>`` may be: imported into generated project files. This is not supported by other generators. + The full path to the library file will be quoted/escaped for + the shell automatically. + * **A plain library name**: The generated link line will ask the linker to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``). + The library name/flag is treated as a command-line string fragment and + will be used with no extra quoting or escaping. + * **A link flag**: Item names starting with ``-``, but not ``-l`` or ``-framework``, are treated as linker flags. Note that such flags will be treated like any other library link item for purposes of transitive @@ -78,6 +87,23 @@ Each ``<item>`` may be: flags explicitly. The flags will then be placed at the toolchain-defined flag position in the link command. + The link flag is treated as a command-line string fragment and + will be used with no extra quoting or escaping. + +* **A generator expression**: A ``$<...>`` :manual:`generator expression + <cmake-generator-expressions(7)>` may evaluate to any of the above + items or to a :ref:`;-list <CMake Language Lists>` of them. + If the ``...`` contains any ``;`` characters, e.g. after evaluation + of a ``${list}`` variable, be sure to use an explicitly quoted + argument ``"$<...>"`` so that this command receives it as a + single ``<item>``. + + Additionally, a generator expression may be used as a fragment of + any of the above items, e.g. ``foo$<1:_d>``. + + Note that generator expressions will not be used in OLD handling of + policy :policy:`CMP0003` or policy :policy:`CMP0004`. + * A ``debug``, ``optimized``, or ``general`` keyword immediately followed by another ``<item>``. The item following such a keyword will be used only for the corresponding build configuration. The ``debug`` keyword @@ -88,18 +114,16 @@ Each ``<item>`` may be: optional. Higher granularity may be achieved for per-configuration rules by creating and linking to :ref:`IMPORTED library targets <Imported Targets>`. + These keywords are interpreted immediately by this command and therefore + have no special meaning when produced by a generator expression. Items containing ``::``, such as ``Foo::Bar``, are assumed to be :ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library target names and will cause an error if no such target exists. See policy :policy:`CMP0028`. -Arguments to ``target_link_libraries`` may use "generator expressions" -with the syntax ``$<...>``. Note however, that generator expressions -will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`. -See the :manual:`cmake-generator-expressions(7)` manual for available -expressions. See the :manual:`cmake-buildsystem(7)` manual for more on -defining buildsystem properties. +See the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. Libraries for a Target and/or its Dependents ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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. |