mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-12-30 18:29:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Add Synopsis section to install, list, and string docs

Browse Source 
Summarize the command signatures in one block at the top of the
documentation as is typical in Unix command-line tool manuals.
Make the mode keywords links to the corresponding full signature
and documentation.

Issue: #17948
This commit is contained in:
Brad King
2018-05-04 08:18:32 -04:00
parent 0acd705119
commit 51c0e1407c
3 changed files with 133 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
Help/command/install.rst
View File

@@ -1,19 +1,19 @@
install
-------
.. only:: html
.. contents::
Specify rules to run at install time.
This command accepts several signatures:
Synopsis
^^^^^^^^
* :ref:`install(TARGETS) <install-targets>`
* :ref:`install(FILES|PROGRAMS) <install-files>`
* :ref:`install(DIRECTORY) <install-directory>`
* :ref:`install(SCRIPT|CODE) <install-script>`
* :ref:`install(EXPORT|EXPORT_ANDROID_MK) <install-export>`
.. parsed-literal::
install(`TARGETS`_ <target>... [...])
install({`FILES`_ | `PROGRAMS`_} <file>... DESTINATION <dir> [...])
install(`DIRECTORY`_ <dir>... DESTINATION <dir> [...])
install(`SCRIPT`_ <file> [...])
install(`CODE`_ <code> [...])
install(`EXPORT`_ <export-name> DESTINATION <dir> [...])
Introduction
^^^^^^^^^^^^
@@ -89,11 +89,11 @@ Command signatures that install files may print messages during
installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable
to control which messages are printed.
.. _install-targets:
Installing Targets
^^^^^^^^^^^^^^^^^^
.. _TARGETS:
::
install(TARGETS targets... [EXPORT <export-name>]
@@ -284,11 +284,12 @@ The install destination given to the target install ``DESTINATION`` may
use "generator expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions.
.. _install-files:
Installing Files
^^^^^^^^^^^^^^^^
.. _FILES:
.. _PROGRAMS:
::
install(<FILES|PROGRAMS> files... DESTINATION <dir>
@@ -319,11 +320,11 @@ The install destination given to the files install ``DESTINATION`` may
use "generator expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions.
.. _install-directory:
Installing Directories
^^^^^^^^^^^^^^^^^^^^^^
.. _DIRECTORY:
::
install(DIRECTORY dirs... DESTINATION <dir>
@@ -402,11 +403,12 @@ given to the directory install ``DESTINATION`` may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.
.. _install-script:
Custom Installation Logic
^^^^^^^^^^^^^^^^^^^^^^^^^
.. _CODE:
.. _SCRIPT:
::
install([[SCRIPT <file>] [CODE <code>]]
@@ -425,11 +427,11 @@ example, the code
will print a message during installation.
.. _install-export:
Installing Exports
^^^^^^^^^^^^^^^^^^
.. _EXPORT:
::
install(EXPORT <export-name> DESTINATION <dir>

80
Help/command/list.rst
View File

@@ -1,12 +1,38 @@
list
----
.. only:: html
.. contents::
List operations.
Synopsis
^^^^^^^^
.. parsed-literal::
`Reading`_
list(`LENGTH`_ <list> <out-var>)
list(`GET`_ <list> <element index> [<index> ...] <out-var>)
list(`JOIN`_ <list> <glue> <out-var>)
list(`SUBLIST`_ <list> <begin> <length> <out-var>)
`Search`_
list(`FIND`_ <list> <value> <out-var>)
`Modification`_
list(`APPEND`_ <list> [<element>...])
list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>)
list(`INSERT`_ <list> <index> [<element>...])
list(`REMOVE_ITEM`_ <list> <value>...)
list(`REMOVE_AT`_ <list> <index>...)
list(`REMOVE_DUPLICATES`_ <list>)
list(`TRANSFORM`_ <list> <ACTION> [...])
`Ordering`_
list(`REVERSE`_ <list>)
list(`SORT`_ <list>)
Introduction
^^^^^^^^^^^^
The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``,
``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create
new values for the list within the current CMake variable scope. Similar to
@@ -36,8 +62,7 @@ scope. To propagate the results of these operations upwards, use
Reading
^^^^^^^
LENGTH
""""""
.. _LENGTH:
::
@@ -45,8 +70,7 @@ LENGTH
Returns the list's length.
GET
"""
.. _GET:
::
@@ -54,8 +78,7 @@ GET
Returns the list of elements specified by indices from the list.
JOIN
""""
.. _JOIN:
::
@@ -65,8 +88,7 @@ Returns a string joining all list's elements using the glue string.
To join multiple strings, which are not part of a list, use ``JOIN`` operator
from :command:`string` command.
SUBLIST
"""""""
.. _SUBLIST:
::
@@ -80,8 +102,7 @@ the remaining elements of the list starting at ``<begin>`` will be returned.
Search
^^^^^^
FIND
""""
.. _FIND:
::
@@ -93,8 +114,7 @@ if it wasn't found.
Modification
^^^^^^^^^^^^
APPEND
""""""
.. _APPEND:
::
@@ -102,8 +122,7 @@ APPEND
Appends elements to the list.
FILTER
""""""
.. _FILTER:
::
@@ -115,8 +134,7 @@ In ``REGEX`` mode, items will be matched against the given regular expression.
For more information on regular expressions see also the
:command:`string` command.
INSERT
""""""
.. _INSERT:
::
@@ -124,8 +142,7 @@ INSERT
Inserts elements to the list to the specified location.
REMOVE_ITEM
"""""""""""
.. _REMOVE_ITEM:
::
@@ -133,8 +150,7 @@ REMOVE_ITEM
Removes the given items from the list.
REMOVE_AT
"""""""""
.. _REMOVE_AT:
::
@@ -142,8 +158,7 @@ REMOVE_AT
Removes items at given indices from the list.
REMOVE_DUPLICATES
"""""""""""""""""
.. _REMOVE_DUPLICATES:
::
@@ -151,8 +166,7 @@ REMOVE_DUPLICATES
Removes duplicated items in the list.
TRANSFORM
"""""""""
.. _TRANSFORM:
::
@@ -224,11 +238,10 @@ expression will be transformed. ::
list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
Sorting
^^^^^^^
Ordering
^^^^^^^^
REVERSE
"""""""
.. _REVERSE:
::
@@ -236,8 +249,7 @@ REVERSE
Reverses the contents of the list in-place.
SORT
""""
.. _SORT:
::

111
Help/command/string.rst
View File

@@ -1,17 +1,52 @@
string
------
.. only:: html
.. contents::
String operations.
Synopsis
^^^^^^^^
.. parsed-literal::
`Search and Replace`_
string(`FIND`_ <string> <substring> <out-var> [...])
string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...)
`Regular Expressions`_
string(`REGEX MATCH`_ <match-regex> <out-var> <input>...)
string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...)
string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...)
`Manipulation`_
string(`APPEND`_ <string-var> [<input>...])
string(`PREPEND`_ <string-var> [<input>...])
string(`CONCAT`_ <out-var> [<input>...])
string(`JOIN`_ <glue> <out-var> [<input>...])
string(`TOLOWER`_ <string1> <out-var>)
string(`TOUPPER`_ <string1> <out-var>)
string(`LENGTH`_ <string> <out-var>)
string(`SUBSTRING`_ <string> <begin> <length> <out-var>)
string(`STRIP`_ <string> <out-var>)
string(`GENEX_STRIP`_ <string> <out-var>)
`Comparison`_
string(`COMPARE`_ <op> <string1> <string2> <out-var>)
`Hashing`_
string(`\<HASH\> <HASH_>`_ <out-var> <input>)
`Generation`_
string(`ASCII`_ <number>... <out-var>)
string(`CONFIGURE`_ <string1> <out-var> [...])
string(`MAKE_C_IDENTIFIER`_ <string> <out-var>)
string(`RANDOM`_ [<option>...] <out-var>)
string(`TIMESTAMP`_ <out-var> [<format string>] [UTC])
string(`UUID`_ <out-var> ...)
Search and Replace
^^^^^^^^^^^^^^^^^^
FIND
""""
.. _FIND:
::
@@ -22,8 +57,7 @@ the supplied string. If the ``REVERSE`` flag was used, the command will
search for the position of the last occurrence of the specified
substring. If the substring is not found, a position of -1 is returned.
REPLACE
"""""""
.. _REPLACE:
::
@@ -37,8 +71,7 @@ with ``replace_string`` and store the result in the output.
Regular Expressions
^^^^^^^^^^^^^^^^^^^
REGEX MATCH
"""""""""""
.. _`REGEX MATCH`:
::
@@ -48,8 +81,7 @@ REGEX MATCH
Match the regular expression once and store the match in the output variable.
All ``<input>`` arguments are concatenated before matching.
REGEX MATCHALL
""""""""""""""
.. _`REGEX MATCHALL`:
::
@@ -60,8 +92,7 @@ Match the regular expression as many times as possible and store the matches
in the output variable as a list.
All ``<input>`` arguments are concatenated before matching.
REGEX REPLACE
"""""""""""""
.. _`REGEX REPLACE`:
::
@@ -123,8 +154,7 @@ expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``.
Manipulation
^^^^^^^^^^^^
APPEND
""""""
.. _APPEND:
::
@@ -132,8 +162,7 @@ APPEND
Append all the input arguments to the string.
PREPEND
"""""""
.. _PREPEND:
::
@@ -141,8 +170,7 @@ PREPEND
Prepend all the input arguments to the string.
CONCAT
""""""
.. _CONCAT:
::
@@ -151,8 +179,7 @@ CONCAT
Concatenate all the input arguments together and store
the result in the named output variable.
JOIN
""""
.. _JOIN:
::
@@ -165,8 +192,7 @@ To join list's elements, use preferably the ``JOIN`` operator
from :command:`list` command. This allows for the elements to have
special characters like ``;`` in them.
TOLOWER
"""""""
.. _TOLOWER:
::
@@ -174,8 +200,7 @@ TOLOWER
Convert string to lower characters.
TOUPPER
"""""""
.. _TOUPPER:
::
@@ -183,8 +208,7 @@ TOUPPER
Convert string to upper characters.
LENGTH
""""""
.. _LENGTH:
::
@@ -192,8 +216,7 @@ LENGTH
Store in an output variable a given string's length.
SUBSTRING
"""""""""
.. _SUBSTRING:
::
@@ -207,8 +230,7 @@ If string is shorter than length then end of string is used instead.
CMake 3.1 and below reported an error if length pointed past
the end of string.
STRIP
"""""
.. _STRIP:
::
@@ -217,8 +239,7 @@ STRIP
Store in an output variable a substring of a given string with leading and
trailing spaces removed.
GENEX_STRIP
"""""""""""
.. _GENEX_STRIP:
::
@@ -230,6 +251,8 @@ from the ``input string`` and store the result in the ``output variable``.
Comparison
^^^^^^^^^^
.. _COMPARE:
::
string(COMPARE LESS <string1> <string2> <output variable>)
@@ -246,6 +269,8 @@ Compare the strings and store true or false in the output variable.
Hashing
^^^^^^^
.. _`HASH`:
::
string(<HASH> <output variable> <input>)
@@ -277,8 +302,7 @@ The supported ``<HASH>`` algorithm names are:
Generation
^^^^^^^^^^
ASCII
"""""
.. _ASCII:
::
@@ -286,8 +310,7 @@ ASCII
Convert all numbers into corresponding ASCII characters.
CONFIGURE
"""""""""
.. _CONFIGURE:
::
@@ -296,8 +319,7 @@ CONFIGURE
Transform a string like :command:`configure_file` transforms a file.
MAKE_C_IDENTIFIER
"""""""""""""""""
.. _MAKE_C_IDENTIFIER:
::
@@ -308,8 +330,7 @@ underscore and store the result in the ``<output variable>``. If the first
character of the string is a digit, an underscore will also be prepended to
the result.
RANDOM
""""""
.. _RANDOM:
::
@@ -322,8 +343,7 @@ and default alphabet is all numbers and upper and lower case letters.
If an integer ``RANDOM_SEED`` is given, its value will be used to seed the
random number generator.
TIMESTAMP
"""""""""
.. _TIMESTAMP:
::
@@ -378,8 +398,7 @@ If no explicit ``<format string>`` is given it will default to:
its value will be used instead of the current time.
See https://reproducible-builds.org/specs/source-date-epoch/ for details.
UUID
""""
.. _UUID:
::