diff options
Diffstat (limited to 'Help/command')
| -rw-r--r-- | Help/command/add_test.rst | 3 | ||||
| -rw-r--r-- | Help/command/aux_source_directory.rst | 4 | ||||
| -rw-r--r-- | Help/command/build_command.rst | 2 | ||||
| -rw-r--r-- | Help/command/cmake_parse_arguments.rst | 14 | ||||
| -rw-r--r-- | Help/command/ctest_submit.rst | 20 | ||||
| -rw-r--r-- | Help/command/enable_testing.rst | 15 | ||||
| -rw-r--r-- | Help/command/execute_process.rst | 15 | ||||
| -rw-r--r-- | Help/command/export.rst | 9 | ||||
| -rw-r--r-- | Help/command/install.rst | 19 | ||||
| -rw-r--r-- | Help/command/list.rst | 39 | ||||
| -rw-r--r-- | Help/command/use_mangled_mesa.rst | 2 |
11 files changed, 111 insertions, 31 deletions
diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index a8c257d..46b9b63 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -55,7 +55,8 @@ file produced by target ``myexe``. CMake will generate tests only if the :command:`enable_testing` command has been invoked. The :module:`CTest` module invokes the - command automatically when the ``BUILD_TESTING`` option is ``ON``. + command automatically unless the ``BUILD_TESTING`` option is turned + ``OFF``. --------------------------------------------------------------------- diff --git a/Help/command/aux_source_directory.rst b/Help/command/aux_source_directory.rst index e0af665..9619f35 100644 --- a/Help/command/aux_source_directory.rst +++ b/Help/command/aux_source_directory.rst @@ -11,14 +11,14 @@ Collects the names of all the source files in the specified directory and stores the list in the ``<variable>`` provided. This command is intended to be used by projects that use explicit template instantiation. Template instantiation files can be stored in a -"Templates" subdirectory and collected automatically using this +``Templates`` subdirectory and collected automatically using this command to avoid manually listing all instantiations. It is tempting to use this command to avoid writing the list of source files for a library or executable target. While this seems to work, there is no way for CMake to generate a build system that knows when a new source file has been added. Normally the generated build system -knows when it needs to rerun CMake because the CMakeLists.txt file is +knows when it needs to rerun CMake because the ``CMakeLists.txt`` file is modified to add a new source. When the source is just added to the directory without modifying this file, one would have to manually rerun CMake to generate a build system incorporating the new file. diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index b83edaf..6659005 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -14,7 +14,7 @@ This is mainly intended for internal use by the :module:`CTest` module. Sets the given ``<variable>`` to a command-line string of the form:: - <cmake> --build . [--config <config>] [--target <target>] [-- -i] + <cmake> --build . [--config <config>] [--target <target>...] [-- -i] where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line tool, and ``<config>`` and ``<target>`` are the values provided to the diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index c8327e2..196d90f 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -59,6 +59,11 @@ All remaining arguments are collected in a variable where recognized. This can be checked afterwards to see whether your macro was called with unrecognized parameters. +``<one_value_keywords>`` and ``<multi_value_keywords>`` that where given no +values at all are collected in a variable ``<prefix>_KEYWORDS_MISSING_VALUES`` +that will be undefined if all keywords received values. This can be checked +to see if there where keywords without any values given. + As an example here a ``my_install()`` macro, which takes similar arguments as the real :command:`install` command: @@ -77,7 +82,7 @@ Assume ``my_install()`` has been called like this: .. code-block:: cmake - my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub) + my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS) After the ``cmake_parse_arguments`` call the macro will have set or undefined the following variables:: @@ -89,6 +94,8 @@ the following variables:: MY_INSTALL_TARGETS = "foo;bar" MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL" + MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS" + # No value for "CONFIGURATIONS" given You can then continue and process these variables. @@ -97,5 +104,6 @@ one_value_keyword another recognized keyword follows, this is interpreted as the beginning of the new option. E.g. ``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in ``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL`` -is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty and -``MY_INSTALL_OPTIONAL`` will therefore be set to ``TRUE``. +is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added +to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will +therefore be set to ``TRUE``. diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index fba03fd..983fc20 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -7,6 +7,7 @@ Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`. ctest_submit([PARTS <part>...] [FILES <file>...] [SUBMIT_URL <url>] + [BUILD_ID <result-var>] [HTTPHEADER <header>] [RETRY_COUNT <count>] [RETRY_DELAY <delay>] @@ -44,9 +45,21 @@ The options are: The ``http`` or ``https`` URL of the dashboard server to send the submission to. If not given, the :variable:`CTEST_SUBMIT_URL` variable is used. +``BUILD_ID <result-var>`` + Store in the ``<result-var>`` variable the ID assigned to this build by + CDash. + ``HTTPHEADER <HTTP-header>`` Specify HTTP header to be included in the request to CDash during submission. - This suboption can be repeated several times. + For example, CDash can be configured to only accept submissions from + authenticated clients. In this case, you should provide a bearer token in your + header: + + .. code-block:: cmake + + ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>") + + This suboption can be repeated several times for multiple headers. ``RETRY_COUNT <count>`` Specify how many times to retry a timed-out submission. @@ -86,5 +99,6 @@ with a content hash of the file. If CDash does not already have the file, then it is uploaded. Along with the file, a CDash type string is specified to tell CDash which handler to use to process the data. -This signature accepts the ``SUBMIT_URL``, ``HTTPHEADER``, ``RETRY_COUNT``, -``RETRY_DELAY``, ``RETURN_VALUE`` and ``QUIET`` options as described above. +This signature accepts the ``SUBMIT_URL``, ``BUILD_ID``, ``HTTPHEADER``, +``RETRY_COUNT``, ``RETRY_DELAY``, ``RETURN_VALUE`` and ``QUIET`` options +as described above. diff --git a/Help/command/enable_testing.rst b/Help/command/enable_testing.rst index e2028d2..3ac1a19 100644 --- a/Help/command/enable_testing.rst +++ b/Help/command/enable_testing.rst @@ -7,7 +7,14 @@ Enable testing for current directory and below. enable_testing() -Enables testing for this directory and below. See also the -:command:`add_test` command. Note that ctest expects to find a test file -in the build directory root. Therefore, this command should be in the -source directory root. +Enables testing for this directory and below. + +This command should be in the source directory root +because ctest expects to find a test file in the build +directory root. + +This command is automatically invoked when the :module:`CTest` +module is included, except if the ``BUILD_TESTING`` option is +turned off. + +See also the :command:`add_test` command. diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index 3a56dce..2d71352 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -22,7 +22,9 @@ Execute one or more child processes. [ERROR_STRIP_TRAILING_WHITESPACE] [ENCODING <name>]) -Runs the given sequence of one or more commands in parallel with the standard +Runs the given sequence of one or more commands. + +Commands are executed concurrently as a pipeline, with the standard output of each process piped to the standard input of the next. A single standard error pipe is used for all processes. @@ -46,8 +48,9 @@ Options: the child processes. ``TIMEOUT`` - The child processes will be terminated if they do not finish in the - specified number of seconds (fractions are allowed). + After the specified number of seconds (fractions allowed), all unfinished + child processes will be terminated, and the ``RESULT_VARIABLE`` will be + set to a string mentioning the "timeout". ``RESULT_VARIABLE`` The variable will be set to contain the result of last child process. @@ -56,9 +59,9 @@ Options: ``RESULTS_VARIABLE <variable>`` The variable will be set to contain the result of all processes as a - :ref:`semicolon-separated list <CMake Language Lists>`, in order of the given ``COMMAND`` - arguments. Each entry will be an integer return code from the - corresponding child or a string describing an error condition. + :ref:`semicolon-separated list <CMake Language Lists>`, in order of the + given ``COMMAND`` arguments. Each entry will be an integer return code + from the corresponding child or a string describing an error condition. ``OUTPUT_VARIABLE``, ``ERROR_VARIABLE`` The variable named will be set with the contents of the standard output diff --git a/Help/command/export.rst b/Help/command/export.rst index b255ee8..ffd60e1 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -62,8 +62,13 @@ registry that this command creates works only in conjunction with a package configuration file (``<PackageName>Config.cmake``) that works with the build tree. In some cases, for example for packaging and for system wide installations, it is not desirable to write the user package -registry. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable -is enabled, the ``export(PACKAGE)`` command will do nothing. +registry. + +By default the ``export(PACKAGE)`` command does nothing (see policy +:policy:`CMP0090`) because populating the user package registry has effects +outside the source and build trees. Set the +:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories to +the CMake user package registry. .. code-block:: cmake diff --git a/Help/command/install.rst b/Help/command/install.rst index 6910d6d..a4cee71 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -99,6 +99,7 @@ Windows platforms are unaffected. Installing Targets ^^^^^^^^^^^^^^^^^^ +.. _`install(TARGETS)`: .. _TARGETS: .. code-block:: cmake @@ -288,18 +289,20 @@ the following additional arguments: is not recommended to use ``NAMELINK_SKIP`` in conjunction with ``NAMELINK_COMPONENT``. -The ``install(TARGETS)`` command can also accept the following options at the +The `install(TARGETS)`_ command can also accept the following options at the top level: ``EXPORT`` This option associates the installed target files with an export called ``<export-name>``. It must appear before any target options. To actually - install the export file itself, call ``install(EXPORT)``, documented below. + install the export file itself, call `install(EXPORT)`_, documented below. + See documentation of the :prop_tgt:`EXPORT_NAME` target property to change + the name of the exported target. ``INCLUDES DESTINATION`` This option specifies a list of directories which will be added to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the - ``<targets>`` when exported by the :command:`install(EXPORT)` command. If a + ``<targets>`` when exported by the `install(EXPORT)`_ command. If a relative path is specified, it is treated as relative to the ``$<INSTALL_PREFIX>``. @@ -333,7 +336,7 @@ targets that link to the object libraries in their implementation. Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property set to ``TRUE`` has undefined behavior. -:command:`install(TARGETS)` can install targets that were created in +`install(TARGETS)`_ can install targets that were created in other directories. When using such cross-directory install rules, running ``make install`` (or similar) from a subdirectory will not guarantee that targets from other directories are up-to-date. You can use @@ -348,6 +351,8 @@ use "generator expressions" with the syntax ``$<...>``. See the Installing Files ^^^^^^^^^^^^^^^^ +.. _`install(FILES)`: +.. _`install(PROGRAMS)`: .. _FILES: .. _PROGRAMS: @@ -436,6 +441,7 @@ use "generator expressions" with the syntax ``$<...>``. See the Installing Directories ^^^^^^^^^^^^^^^^^^^^^^ +.. _`install(DIRECTORY)`: .. _DIRECTORY: .. code-block:: cmake @@ -560,6 +566,8 @@ manual for available expressions. Custom Installation Logic ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _`install(CODE)`: +.. _`install(SCRIPT)`: .. _CODE: .. _SCRIPT: @@ -589,6 +597,7 @@ name, not the file's contents). See the Installing Exports ^^^^^^^^^^^^^^^^^^ +.. _`install(EXPORT)`: .. _EXPORT: .. code-block:: cmake @@ -605,7 +614,7 @@ Installing Exports The ``EXPORT`` form generates and installs a CMake file containing code to import targets from the installation tree into another project. Target installations are associated with the export ``<export-name>`` -using the ``EXPORT`` option of the ``install(TARGETS)`` signature +using the ``EXPORT`` option of the `install(TARGETS)`_ signature documented above. The ``NAMESPACE`` option will prepend ``<namespace>`` to the target names as they are written to the import file. By default the generated file will be called ``<export-name>.cmake`` but the ``FILE`` diff --git a/Help/command/list.rst b/Help/command/list.rst index bfcdf34..4444af7 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -21,6 +21,9 @@ Synopsis list(`APPEND`_ <list> [<element>...]) list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>) list(`INSERT`_ <list> <index> [<element>...]) + list(`POP_BACK`_ <list> [<out-var>...]) + list(`POP_FRONT`_ <list> [<out-var>...]) + list(`PREPEND`_ <list> [<element>...]) list(`REMOVE_ITEM`_ <list> <value>...) list(`REMOVE_AT`_ <list> <index>...) list(`REMOVE_DUPLICATES`_ <list>) @@ -33,8 +36,9 @@ Synopsis Introduction ^^^^^^^^^^^^ -The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, -``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create +The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``PREPEND``, +``POP_BACK``, ``POP_FRONT``, ``REMOVE_AT``, ``REMOVE_ITEM``, +``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create new values for the list within the current CMake variable scope. Similar to the :command:`set` command, the LIST command creates new variable values in the current scope, even if the list itself is actually defined in a parent @@ -142,6 +146,34 @@ For more information on regular expressions see also the Inserts elements to the list to the specified location. +.. _POP_BACK: + +.. code-block:: cmake + + list(POP_BACK <list> [<out-var>...]) + +If no variable name is given, removes exactly one element. Otherwise, +assign the last element's value to the given variable and removes it, +up to the last variable name given. + +.. _POP_FRONT: + +.. code-block:: cmake + + list(POP_FRONT <list> [<out-var>...]) + +If no variable name is given, removes exactly one element. Otherwise, +assign the first element's value to the given variable and removes it, +up to the last variable name given. + +.. _PREPEND: + +.. code-block:: cmake + + list(PREPEND <list> [<element> ...]) + +Insert elements to the 0th position in the list. + .. _REMOVE_ITEM: .. code-block:: cmake @@ -164,7 +196,8 @@ Removes items at given indices from the list. list(REMOVE_DUPLICATES <list>) -Removes duplicated items in the list. +Removes duplicated items in the list. The relative order of items is preserved, +but if duplicates are encountered, only the first instance is preserved. .. _TRANSFORM: diff --git a/Help/command/use_mangled_mesa.rst b/Help/command/use_mangled_mesa.rst index 4d9e12b..5b0e2ee 100644 --- a/Help/command/use_mangled_mesa.rst +++ b/Help/command/use_mangled_mesa.rst @@ -9,7 +9,7 @@ Copy mesa headers for use in combination with system GL. use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY) -The path to mesa includes, should contain gl_mangle.h. The mesa +The path to mesa includes, should contain ``gl_mangle.h``. The mesa headers are copied to the specified output directory. This allows mangled mesa headers to override other GL headers by being added to the include directory path earlier. |