echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Convert some literal blocks into tables and lists

Browse Source 
Also, ensure that header-less tables have a top border in cmake.css.
This commit is contained in:
Nikita Nemkin 2025-01-23 15:31:58 +05:00 committed by Brad King
parent 914d580a4f
commit 718043b540
15 changed files with 231 additions and 217 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
Help/command/ctest_submit.rst
View File

@ -24,21 +24,20 @@ The options are:
``PARTS <part>...``
Specify a subset of parts to submit. Valid part names are:
.. parsed-literal::
Start = nothing
Update = ctest_update results, in Update.xml
Configure = ctest_configure results, in Configure.xml
Build = ctest_build results, in Build.xml
Test = ctest_test results, in Test.xml
Coverage = ctest_coverage results, in Coverage.xml
MemCheck = ctest_memcheck results, in DynamicAnalysis.xml and
DynamicAnalysis-Test.xml
Notes = Files listed by :variable:`CTEST_NOTES_FILES`, in Notes.xml
ExtraFiles = Files listed by :variable:`CTEST_EXTRA_SUBMIT_FILES`
Upload = Files prepared for upload by ctest_upload(), in Upload.xml
Submit = nothing
Done = Build is complete, in Done.xml
* ``Start`` - nothing.
* ``Update`` - :command:`ctest_update` results, in ``Update.xml``.
* ``Configure`` - :command:`ctest_configure` results, in ``Configure.xml``.
* ``Build`` - :command:`ctest_build` results, in ``Build.xml``.
* ``Test`` - :command:`ctest_test` results, in ``Test.xml``.
* ``Coverage`` - :command:`ctest_coverage` results, in ``Coverage.xml``.
* ``MemCheck`` - :command:`ctest_memcheck` results, in
``DynamicAnalysis.xml`` and ``DynamicAnalysis-Test.xml``.
* ``Notes`` - Files listed by :variable:`CTEST_NOTES_FILES`, in ``Notes.xml``.
* ``ExtraFiles`` - Files listed by :variable:`CTEST_EXTRA_SUBMIT_FILES`.
* ``Upload`` - Files prepared for upload by :command:`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.

16
Help/command/define_property.rst
View File

@ -21,15 +21,13 @@ primary use case.
The first argument determines the kind of scope in which the property should
be used. It must be one of the following:
::
GLOBAL = associated with the global namespace
DIRECTORY = associated with one directory
TARGET = associated with one target
SOURCE = associated with one source file
TEST = associated with a test named with add_test
VARIABLE = documents a CMake language variable
CACHED_VARIABLE = documents a CMake cache variable
* ``GLOBAL`` - associated with the global namespace.
* ``DIRECTORY`` - associated with one directory.
* ``TARGET`` - associated with one target.
* ``SOURCE`` - associated with one source file.
* ``TEST`` - associated with a test named with :command:`add_test`.
* ``VARIABLE`` - documents a CMake language variable.
* ``CACHED_VARIABLE`` - documents a CMake cache variable.
Note that unlike :command:`set_property` and :command:`get_property` no
actual scope needs to be given; only the kind of scope is important.

22
Help/command/get_filename_component.rst
View File

@ -20,15 +20,13 @@ Get a specific component of a full filename.
Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of:
::
DIRECTORY = Directory without file name
NAME = File name without directory
EXT = File name longest extension (.b.c from d/a.b.c)
NAME_WE = File name with neither the directory nor the longest extension
LAST_EXT = File name last extension (.c from d/a.b.c)
NAME_WLE = File name with neither the directory nor the last extension
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
* ``DIRECTORY`` - directory without file name.
* ``NAME`` - file name without directory.
* ``EXT`` - file name longest extension (``.b.c`` from ``d/a.b.c``).
* ``NAME_WE`` - file name with neither the directory nor the longest extension.
* ``LAST_EXT`` - file name last extension (``.c`` from ``d/a.b.c``).
* ``NAME_WLE`` - file name with neither the directory nor the last extension.
* ``PATH`` - legacy alias for ``DIRECTORY`` (use for CMake <= 2.8.11).
.. versionadded:: 3.14
Added the ``LAST_EXT`` and ``NAME_WLE`` modes.
@ -46,10 +44,8 @@ added to the cache.
Sets ``<var>`` to the absolute path of ``<FileName>``, where ``<mode>`` is one
of:
::
ABSOLUTE = Full path to file
REALPATH = Full path to existing file with symlinks resolved
* ``ABSOLUTE`` - full path to file.
* ``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 ``<dir>``. If no base directory is

8
Help/command/include_regular_expression.rst
View File

@ -10,9 +10,7 @@ Set the regular expression used for dependency checking.
Sets the regular expressions used in dependency checking. Only files
matching ``regex_match`` will be traced as dependencies. Only files
matching ``regex_complain`` will generate warnings if they cannot be found
(standard header paths are not searched). The defaults are:
(standard header paths are not searched).
::
regex_match = "^.*$" (match everything)
regex_complain = "^$" (match empty string only)
The default for ``regex_match`` is ``"^.*$"`` (match everything).
The default for ``regex_complain`` is ``"^$"`` (match empty string only).

6
Help/command/load_command.rst
View File

@ -14,10 +14,6 @@ cmCOMMAND_NAME. If found, it is loaded as a module and the command is
added to the set of available CMake commands. Usually,
:command:`try_compile` is used before this command to compile the
module. If the command is successfully loaded a variable named
.. code-block:: cmake
CMAKE_LOADED_COMMAND_<COMMAND_NAME>
``CMAKE_LOADED_COMMAND_<COMMAND_NAME>``
will be set to the full path of the module that was loaded. Otherwise
the variable will not be set.

6
Help/command/string.rst
View File

@ -478,10 +478,8 @@ Generation
If no explicit ``<format_string>`` is given, it will default to:
::
%Y-%m-%dT%H:%M:%S for local time.
%Y-%m-%dT%H:%M:%SZ for UTC.
* ``%Y-%m-%dT%H:%M:%S`` for local time.
* ``%Y-%m-%dT%H:%M:%SZ`` for UTC.
.. versionadded:: 3.8
If the ``SOURCE_DATE_EPOCH`` environment variable is set,

16
Help/include/COMPILE_DEFINITIONS_DISCLAIMER.txt
View File

@ -5,14 +5,16 @@ to be escaped correctly, do not attempt to work-around the problem by
adding escape sequences to the value. Your work-around may break in a
future version of CMake that has improved escape support. Instead
consider defining the macro in a (configured) header file. Then
report the limitation. Known limitations include::
report the limitation. Known limitations include:
# - broken almost everywhere
; - broken in VS IDE 7.0 and Borland Makefiles
, - broken in VS IDE
% - broken in some cases in NMake
& | - broken in some cases on MinGW
^ < > \" - broken in most Make tools on Windows
============= ========================
``#`` Broken almost everywhere.
``;`` Broken in VS IDE 7.0 and Borland Makefiles.
``,`` Broken in VS IDE.
``%`` Broken in some cases in NMake.
``& |`` Broken in some cases on MinGW.
``^ < > \ "`` Broken in most Make tools on Windows.
============= ========================
CMake does not reject these values outright because they do work in
some cases. Use with caution.

10
Help/policy/CMP0002.rst
View File

@ -10,12 +10,10 @@ Targets names created with :command:`add_executable`, :command:`add_library`, or
:command:`add_custom_target` are logical build target names. Logical target
names must be globally unique because:
::
- Unique names may be referenced unambiguously both in CMake
code and on make tool command lines.
- Logical names are used by Xcode and VS IDE generators
to produce meaningful project names for the targets.
* Unique names may be referenced unambiguously both in CMake
code and on make tool command lines.
* Logical names are used by Xcode and VS IDE generators
to produce meaningful project names for the targets.
The logical name of executable and library targets does not have to
correspond to the physical file names built. Consider using the

19
Help/prop_cache/TYPE.rst
View File

@ -7,15 +7,18 @@ Cache entry values are always strings, but CMake GUIs present widgets
to help users set values. The GUIs use this property as a hint to
determine the widget type. Valid ``TYPE`` values are:
::
.. table::
:align: left
BOOL = Boolean ON/OFF value.
PATH = Path to a directory.
FILEPATH = Path to a file.
STRING = Generic string value.
INTERNAL = Do not present in GUI at all.
STATIC = Value managed by CMake, do not change.
UNINITIALIZED = Type not yet specified.
================= ========================================
``BOOL`` Boolean ON/OFF value.
``PATH`` Path to a directory.
``FILEPATH`` Path to a file.
``STRING`` Generic string value.
``INTERNAL`` Do not present in GUI at all.
``STATIC`` Value managed by CMake, do not change.
``UNINITIALIZED`` Type not yet specified.
================= ========================================
Generally the ``TYPE`` of a cache entry should be set by the command which
creates it ( :command:`set`, :command:`option`, :command:`find_library`, etc.).

15
Help/variable/CMAKE_CFG_INTDIR.rst
View File

@ -16,13 +16,16 @@ of the per-configuration output subdirectory. On :ref:`Makefile Generators`
this evaluates to ``.`` because there is only one configuration in a build tree.
Example values:
::
.. table::
:align: left
$(Configuration) = Visual Studio
$(CONFIGURATION) = Xcode
. = Make-based tools
. = Ninja
${CONFIGURATION} = Ninja Multi-Config
========================= ==============================
``$(Configuration)`` Visual Studio
``$(CONFIGURATION)`` Xcode
``.`` Make-based tools
``.`` Ninja
``${CONFIGURATION}`` Ninja Multi-Config
========================= ==============================
Since these values are evaluated by the native build system, this
variable is suitable only for use in command lines that will be

27
Help/variable/MSVC_TOOLSET_VERSION.rst
View File

@ -7,17 +7,24 @@ The toolset version of Microsoft Visual C/C++ being used if any.
If MSVC-like is being used, this variable is set based on the version
of the compiler as given by the :variable:`MSVC_VERSION` variable.
Known toolset version numbers are::
Known toolset version numbers are:
80 = VS 2005 (8.0)
90 = VS 2008 (9.0)
100 = VS 2010 (10.0)
110 = VS 2012 (11.0)
120 = VS 2013 (12.0)
140 = VS 2015 (14.0)
141 = VS 2017 (15.0)
142 = VS 2019 (16.0)
143 = VS 2022 (17.0)
.. table::
:align: left
===== ==============
Value Version
===== ==============
80 VS 2005 (8.0)
90 VS 2008 (9.0)
100 VS 2010 (10.0)
110 VS 2012 (11.0)
120 VS 2013 (12.0)
140 VS 2015 (14.0)
141 VS 2017 (15.0)
142 VS 2019 (16.0)
143 VS 2022 (17.0)
===== ==============
Compiler versions newer than those known to CMake will be reported
as the latest known toolset version.

33
Help/variable/MSVC_VERSION.rst
View File

@ -6,20 +6,27 @@ If a compiler simulating Visual C++ is being used, this variable is set
to the toolset version simulated as given by the ``_MSC_VER``
preprocessor definition.
Known version numbers are::
Known version numbers are:
1200 = VS 6.0
1300 = VS 7.0
1310 = VS 7.1
1400 = VS 8.0 (v80 toolset)
1500 = VS 9.0 (v90 toolset)
1600 = VS 10.0 (v100 toolset)
1700 = VS 11.0 (v110 toolset)
1800 = VS 12.0 (v120 toolset)
1900 = VS 14.0 (v140 toolset)
1910-1919 = VS 15.0 (v141 toolset)
1920-1929 = VS 16.0 (v142 toolset)
1930-1949 = VS 17.0 (v143 toolset)
.. table::
:align: left
========= ==============
Value Version
========= ==============
1200 VS 6.0
1300 VS 7.0
1310 VS 7.1
1400 VS 8.0 (v80 toolset)
1500 VS 9.0 (v90 toolset)
1600 VS 10.0 (v100 toolset)
1700 VS 11.0 (v110 toolset)
1800 VS 12.0 (v120 toolset)
1900 VS 14.0 (v140 toolset)
1910-1919 VS 15.0 (v141 toolset)
1920-1929 VS 16.0 (v142 toolset)
1930-1949 VS 17.0 (v143 toolset)
========= ==============
See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` and
:variable:`MSVC_TOOLSET_VERSION` variable.

47
Modules/ExternalData.cmake
View File

@ -244,21 +244,22 @@ members of a series are fetched, only the file originally named by the
recognizes file series names ending with ``#.ext``, ``_#.ext``, ``.#.ext``,
or ``-#.ext`` where ``#`` is a sequence of decimal digits and ``.ext`` is
any single extension. Configure it with a regex that parses ``<number>``
and ``<suffix>`` parts from the end of ``<name>``::
and ``<suffix>`` parts from the end of ``<name>``:
ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$
``ExternalData_SERIES_PARSE`` - regex of the form ``(<number>)(<suffix>)$``.
For more complicated cases set::
For more complicated cases set:
ExternalData_SERIES_PARSE = regex with at least two () groups
ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
* ``ExternalData_SERIES_PARSE`` - regex with at least two ``()`` groups.
* ``ExternalData_SERIES_PARSE_PREFIX`` - regex group number of the ``<prefix>``, if any.
* ``ExternalData_SERIES_PARSE_NUMBER`` - regex group number of the ``<number>``.
* ``ExternalData_SERIES_PARSE_SUFFIX`` - regex group number of the ``<suffix>``.
Configure series number matching with a regex that matches the
``<number>`` part of series members named ``<prefix><number><suffix>``::
``<number>`` part of series members named ``<prefix><number><suffix>``:
ExternalData_SERIES_MATCH = regex matching <number> in all series members
``ExternalData_SERIES_MATCH`` - regex matching ``<number>`` in all series
members
Note that the ``<suffix>`` of a series does not include a hash-algorithm
extension.
@ -298,20 +299,22 @@ source directory.
Hash Algorithms
^^^^^^^^^^^^^^^
The following hash algorithms are supported::
The following hash algorithms are supported:
%(algo) <ext> Description
------- ----- -----------
MD5 .md5 Message-Digest Algorithm 5, RFC 1321
SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
SHA3_224 .sha3-224 Keccak SHA-3
SHA3_256 .sha3-256 Keccak SHA-3
SHA3_384 .sha3-384 Keccak SHA-3
SHA3_512 .sha3-512 Keccak SHA-3
============ ============= ============
%(algo) <ext> Description
============ ============= ============
``MD5`` ``.md5`` Message-Digest Algorithm 5, RFC 1321
``SHA1`` ``.sha1`` US Secure Hash Algorithm 1, RFC 3174
``SHA224`` ``.sha224`` US Secure Hash Algorithms, RFC 4634
``SHA256`` ``.sha256`` US Secure Hash Algorithms, RFC 4634
``SHA384`` ``.sha384`` US Secure Hash Algorithms, RFC 4634
``SHA512`` ``.sha512`` US Secure Hash Algorithms, RFC 4634
``SHA3_224`` ``.sha3-224`` Keccak SHA-3
``SHA3_256`` ``.sha3-256`` Keccak SHA-3
``SHA3_384`` ``.sha3-384`` Keccak SHA-3
``SHA3_512`` ``.sha3-512`` Keccak SHA-3
============ ============= ============
.. versionadded:: 3.8
Added the ``SHA3_*`` hash algorithms.

189
Modules/FindDoxygen.cmake
View File

@ -39,21 +39,22 @@ The following variables are defined by this module:
The version reported by ``doxygen --version``.
Imported Targets
^^^^^^^^^^^^^^^^
.. versionadded:: 3.9
The module defines ``IMPORTED`` targets for Doxygen and each component found.
These can be used as part of custom commands, etc. and should be preferred over
old-style (and now deprecated) variables like ``DOXYGEN_EXECUTABLE``. The
following import targets are defined if their corresponding executable could be
found (the component import targets will only be defined if that component was
requested):
::
Doxygen::doxygen
Doxygen::dot
Doxygen::mscgen
Doxygen::dia
The module defines ``IMPORTED`` targets for Doxygen and each component found.
These can be used as part of custom commands, etc. and should be preferred over
old-style (and now deprecated) variables like ``DOXYGEN_EXECUTABLE``. The
following import targets are defined if their corresponding executable could be
found (the component import targets will only be defined if that component was
requested):
* ``Doxygen::doxygen``
* ``Doxygen::dot``
* ``Doxygen::mscgen``
* ``Doxygen::dia``
Functions
^^^^^^^^^
@ -231,94 +232,94 @@ options and will convert their associated CMake variable's contents into the
required form if set. CMake variables are named ``DOXYGEN_<name>`` for the
Doxygen settings specified here.
::
.. hlist::
ABBREVIATE_BRIEF
ALIASES
CITE_BIB_FILES
DIAFILE_DIRS
DOTFILE_DIRS
DOT_FONTPATH
ENABLED_SECTIONS
EXAMPLE_PATH
EXAMPLE_PATTERNS
EXCLUDE
EXCLUDE_PATTERNS
EXCLUDE_SYMBOLS
EXPAND_AS_DEFINED
EXTENSION_MAPPING
EXTRA_PACKAGES
EXTRA_SEARCH_MAPPINGS
FILE_PATTERNS
FILTER_PATTERNS
FILTER_SOURCE_PATTERNS
HTML_EXTRA_FILES
HTML_EXTRA_STYLESHEET
IGNORE_PREFIX
IMAGE_PATH
INCLUDE_FILE_PATTERNS
INCLUDE_PATH
INPUT
LATEX_EXTRA_FILES
LATEX_EXTRA_STYLESHEET
MATHJAX_EXTENSIONS
MSCFILE_DIRS
PLANTUML_INCLUDE_PATH
PREDEFINED
QHP_CUST_FILTER_ATTRS
QHP_SECT_FILTER_ATTRS
STRIP_FROM_INC_PATH
STRIP_FROM_PATH
TAGFILES
TCL_SUBST
- ``ABBREVIATE_BRIEF``
- ``ALIASES``
- ``CITE_BIB_FILES``
- ``DIAFILE_DIRS``
- ``DOTFILE_DIRS``
- ``DOT_FONTPATH``
- ``ENABLED_SECTIONS``
- ``EXAMPLE_PATH``
- ``EXAMPLE_PATTERNS``
- ``EXCLUDE``
- ``EXCLUDE_PATTERNS``
- ``EXCLUDE_SYMBOLS``
- ``EXPAND_AS_DEFINED``
- ``EXTENSION_MAPPING``
- ``EXTRA_PACKAGES``
- ``EXTRA_SEARCH_MAPPINGS``
- ``FILE_PATTERNS``
- ``FILTER_PATTERNS``
- ``FILTER_SOURCE_PATTERNS``
- ``HTML_EXTRA_FILES``
- ``HTML_EXTRA_STYLESHEET``
- ``IGNORE_PREFIX``
- ``IMAGE_PATH``
- ``INCLUDE_FILE_PATTERNS``
- ``INCLUDE_PATH``
- ``INPUT``
- ``LATEX_EXTRA_FILES``
- ``LATEX_EXTRA_STYLESHEET``
- ``MATHJAX_EXTENSIONS``
- ``MSCFILE_DIRS``
- ``PLANTUML_INCLUDE_PATH``
- ``PREDEFINED``
- ``QHP_CUST_FILTER_ATTRS``
- ``QHP_SECT_FILTER_ATTRS``
- ``STRIP_FROM_INC_PATH``
- ``STRIP_FROM_PATH``
- ``TAGFILES``
- ``TCL_SUBST``
The following single value Doxygen options will be quoted automatically
if they contain at least one space:
::
.. hlist::
CHM_FILE
DIA_PATH
DOCBOOK_OUTPUT
DOCSET_FEEDNAME
DOCSET_PUBLISHER_NAME
DOT_FONTNAME
DOT_PATH
EXTERNAL_SEARCH_ID
FILE_VERSION_FILTER
GENERATE_TAGFILE
HHC_LOCATION
HTML_FOOTER
HTML_HEADER
HTML_OUTPUT
HTML_STYLESHEET
INPUT_FILTER
LATEX_FOOTER
LATEX_HEADER
LATEX_OUTPUT
LAYOUT_FILE
MAN_OUTPUT
MAN_SUBDIR
MATHJAX_CODEFILE
MSCGEN_PATH
OUTPUT_DIRECTORY
PERL_PATH
PLANTUML_JAR_PATH
PROJECT_BRIEF
PROJECT_LOGO
PROJECT_NAME
QCH_FILE
QHG_LOCATION
QHP_CUST_FILTER_NAME
QHP_VIRTUAL_FOLDER
RTF_EXTENSIONS_FILE
RTF_OUTPUT
RTF_STYLESHEET_FILE
SEARCHDATA_FILE
USE_MDFILE_AS_MAINPAGE
WARN_FORMAT
WARN_LOGFILE
XML_OUTPUT
- ``CHM_FILE``
- ``DIA_PATH``
- ``DOCBOOK_OUTPUT``
- ``DOCSET_FEEDNAME``
- ``DOCSET_PUBLISHER_NAME``
- ``DOT_FONTNAME``
- ``DOT_PATH``
- ``EXTERNAL_SEARCH_ID``
- ``FILE_VERSION_FILTER``
- ``GENERATE_TAGFILE``
- ``HHC_LOCATION``
- ``HTML_FOOTER``
- ``HTML_HEADER``
- ``HTML_OUTPUT``
- ``HTML_STYLESHEET``
- ``INPUT_FILTER``
- ``LATEX_FOOTER``
- ``LATEX_HEADER``
- ``LATEX_OUTPUT``
- ``LAYOUT_FILE``
- ``MAN_OUTPUT``
- ``MAN_SUBDIR``
- ``MATHJAX_CODEFILE``
- ``MSCGEN_PATH``
- ``OUTPUT_DIRECTORY``
- ``PERL_PATH``
- ``PLANTUML_JAR_PATH``
- ``PROJECT_BRIEF``
- ``PROJECT_LOGO``
- ``PROJECT_NAME``
- ``QCH_FILE``
- ``QHG_LOCATION``
- ``QHP_CUST_FILTER_NAME``
- ``QHP_VIRTUAL_FOLDER``
- ``RTF_EXTENSIONS_FILE``
- ``RTF_OUTPUT``
- ``RTF_STYLESHEET_FILE``
- ``SEARCHDATA_FILE``
- ``USE_MDFILE_AS_MAINPAGE``
- ``WARN_FORMAT``
- ``WARN_LOGFILE``
- ``XML_OUTPUT``
.. versionadded:: 3.11
There are situations where it may be undesirable for a particular config option

5
Utilities/Sphinx/static/cmake.css
View File

@ -86,3 +86,8 @@ code.xref.cmake-guide {
code.xref.cmake-guide span.pre {
white-space: inherit;
}
/* Ensure top border for header-less tables. */
table.docutils td {
border-top: 1px solid #aaa;
}