Commit 95c14579 authored by Craig Scott's avatar Craig Scott
Browse files

Help: Cleanup typos and grammar for the 3.19 release

parent f2a59d40
Pipeline #196378 waiting for manual action with stages
in 15 minutes and 21 seconds
......@@ -134,14 +134,14 @@ The options are:
``ID <id>``
Specify an identification for the deferred call.
The id may not be empty and may not begin in a capital letter ``A-Z``.
The id may begin in a ``_`` only if it was generated by another call
that used ``ID_VAR`` to get the id.
The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``.
The ``<id>`` may begin with an underscore (``_``) only if it was generated
automatically by an earlier call that used ``ID_VAR`` to get the id.
``ID_VAR <var>``
Sepcify a variable in which to store the identification for the
Specify a variable in which to store the identification for the
deferred call. If ``ID <id>`` is not given, a new identification
will be generated starting in a ``_``.
will be generated and the generated id will start with an underscore (``_``).
The currently scheduled list of deferred calls may be retrieved:
......@@ -149,7 +149,7 @@ The currently scheduled list of deferred calls may be retrieved:
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
This will store in ``<var>`` a :ref:`Semicolon-separated list <CMake Language
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
Lists>` of deferred call ids.
Details of a specific call may be retrieved from its id:
......@@ -158,7 +158,7 @@ Details of a specific call may be retrieved from its id:
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
This will store in ``<var>`` a :ref:`Semicolon-separated list <CMake Language
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
Lists>` in which the first element is the name of the command to be
called, and the remaining elements are its unevaluated arguments (any
contained ``;`` characters are included literally and cannot be distinguished
......
......@@ -83,7 +83,7 @@ The arguments are:
Restrict variable replacement to references of the form ``@VAR@``.
This is useful for configuring scripts that use ``${VAR}`` syntax.
``NO_SOURCE_PERMISSIONS``
``NO_SOURCE_PERMISSIONS``
Does not transfer the file permissions of the original file to the copy.
The copied file permissions default to the standard 644 value
(-rw-r--r--).
......
......@@ -118,9 +118,17 @@ Options:
This is analogous to the ``tee`` Unix command.
``COMMAND_ERROR_IS_FATAL <ANY|LAST>``
``COMMAND_ERROR_IS_FATAL ANY`` option stops processing if any command fails.
``COMMAND_ERROR_IS_FATAL LAST`` option stops processing if the last command
in the command list fails.
The option following ``COMMAND_ERROR_IS_FATAL`` determines the behavior when
an error is encountered:
``ANY``
If any of the commands in the list of commands fail, the
``execute_process()`` command halts with an error.
``LAST``
If the last command in the list of commands fails, the
``execute_process()`` command halts with an error. Commands earlier in the
list will not cause a fatal error.
If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
same pipe the precedence is not specified.
......
......@@ -54,7 +54,7 @@ Synopsis
file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>)
`Transfer`_
file(`DOWNLOAD`_ <url> <file> [...])
file(`DOWNLOAD`_ <url> [<file>] [...])
file(`UPLOAD`_ <file> <url> [...])
`Locking`_
......@@ -498,8 +498,9 @@ from the input content to produce the output content. The options are:
See policy :policy:`CMP0070`.
``TARGET <target>``
Specify target which to use when evaluating generator expressions. Enables
use of generator expressions requiring a target.
Specify which target to use when evaluating generator expressions that
require a target for evaluation (e.g. ``$<COMPILE_FEATURES:...>``,
``$<TARGET_PROPERTY:prop>``).
Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific
``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
......@@ -763,7 +764,8 @@ which would make them unable to support a hard link.
.. code-block:: cmake
file(CHMOD <files>... <directories>... [PERMISSIONS <permissions>...]
file(CHMOD <files>... <directories>...
[PERMISSIONS <permissions>...]
[FILE_PERMISSIONS <permissions>...]
[DIRECTORY_PERMISSIONS <permissions>...])
......@@ -775,34 +777,36 @@ Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``,
Valid combination of keywords are:
``PERMISSIONS``
all items are changed
All items are changed.
``FILE_PERMISSIONS``
only files are changed
Only files are changed.
``DIRECTORY_PERMISSIONS``
only directories are changed
Only directories are changed.
``PERMISSIONS`` and ``FILE_PERMISSIONS``
``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files
``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files.
``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories
``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories.
``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for
directories
Use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for
directories.
.. _CHMOD_RECURSE:
.. code-block:: cmake
file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>...
FILE_PERMISSIONS <permissions>... DIRECTORY_PERMISSIONS <permissions>...)
file(CHMOD_RECURSE <files>... <directories>...
[PERMISSIONS <permissions>...]
[FILE_PERMISSIONS <permissions>...]
[DIRECTORY_PERMISSIONS <permissions>...])
Same as `CHMOD`_, but change the permissions of files and directories present in
the ``<directories>..`` recursively.
the ``<directories>...`` recursively.
Path Conversion
^^^^^^^^^^^^^^^
......@@ -859,11 +863,11 @@ Transfer
file(DOWNLOAD <url> [<file>] [<options>...])
file(UPLOAD <file> <url> [<options>...])
The ``DOWNLOAD`` mode downloads the given ``<url>`` to a local ``<file>``. If
``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not saved. This
can be useful if you want to know if a file can be downloaded (for example, to
check that it exists) without actually saving it anywhere. The ``UPLOAD`` mode
uploads a local ``<file>`` to a given ``<url>``.
The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local ``<file>``.
If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not saved.
This can be useful if you want to know if a file can be downloaded (for example,
to check that it exists) without actually saving it anywhere. The ``UPLOAD``
mode uploads a local ``<file>`` to a given ``<url>``.
Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
......@@ -986,8 +990,7 @@ Archiving
file(ARCHIVE_CREATE OUTPUT <archive>
PATHS <paths>...
[FORMAT <format>]
[COMPRESSION <compression>]
[COMPRESSION_LEVEL <compression level>]
[COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]]
[MTIME <mtime>]
[VERBOSE])
......@@ -1005,9 +1008,9 @@ compression. The other formats use no compression by default, but can be
directed to do so with the ``COMPRESSION`` option. Valid values for
``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.
Compression level can be specied by using ``COMPRESSION_LEVEL`` option.
Compression level should be between 0-9. 0 is the default compression.
``COMPRESSION`` option must be specified for ``COMPRESSION_LEVEL``.
The compression level can be specified with the ``COMPRESSION_LEVEL`` option.
The ``<compression-level>`` should be between 0-9, with the default being 0.
The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given.
.. note::
With ``FORMAT`` set to ``raw`` only one file will be compressed with the
......
......@@ -44,7 +44,8 @@ specified:
* A version range with the format ``versionMin...[<]versionMax`` where
``versionMin`` and ``versionMax`` have the same format as the single
version. By default, both end points are included. By specifying ``<``,
the upper end point will be excluded.
the upper end point will be excluded. Version ranges are only supported
with CMake 3.19 or later.
The ``EXACT`` option requests that the version be matched exactly. This option
is incompatible with the specification of a version range.
......
......@@ -37,7 +37,7 @@ be one of the following keywords:
``PROGRAM``
The first item in ``<args>`` is assumed to be an executable and will be
search in the system search path or left as a full path. If not found,
searched in the system search path or left as a full path. If not found,
``<variable>`` will be empty. Otherwise, ``<variable>`` is a list of 2
elements:
......
......@@ -484,12 +484,12 @@ where each ``x`` represents a lower case hexadecimal character.
Where required, an uppercase representation can be requested
with the optional ``UPPER`` flag.
.. _JSON:
JSON
^^^^
.. _JSON:
Functionality for querying a JSON string
Functionality for querying a JSON string.
.. _GET:
.. code-block:: cmake
......@@ -522,7 +522,7 @@ will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``,
MEMBER <json-string>
[<member|index> ...] <index>)
Get the name of the ``<index>``:th member in ``<json-string>`` at the location
Get the name of the ``<index>``-th member in ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments.
Requires an element of object type.
......@@ -534,7 +534,7 @@ Requires an element of object type.
Get the length of an element in ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments.
Required an element of array or object type.
Requires an element of array or object type.
.. _REMOVE:
.. code-block:: cmake
......@@ -544,7 +544,7 @@ Required an element of array or object type.
Remove an element from ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments. The JSON string
without the removed element will we written in ``<out-var>``.
without the removed element will be stored in ``<out-var>``.
.. _SET:
.. code-block:: cmake
......@@ -566,8 +566,8 @@ Compare the two JSON objects given by ``<json-string1>`` and ``<json-string2>``
for equality
If the optional ``ERROR_VARIABLE`` argument is given errors will be
reported in ``<error-variable>``. If no error occurs the ``<error-variable>``
If the optional ``ERROR_VARIABLE`` argument is given, errors will be
reported in ``<error-variable>``. If no error occurs, the ``<error-variable>``
will be set to ``NOTFOUND``. If ``ERROR_VARIABLE`` is not set a CMake error
will be issued.
When an error occurs the ``<out-var>`` will be set to
......
......@@ -285,6 +285,6 @@ Variables specific to CPack External generator
.. variable:: CPACK_EXTERNAL_BUILT_PACKAGES
The ``CPACK_EXTERNAL_PACKAGE_SCRIPT`` script may set this list variable to the
full paths of generated package files. CPack copy these files from the stage
directory back to the top build directory and possibly produce checksum files
if the :variable:`CPACK_PACKAGE_CHECKSUM` is set.
full paths of generated package files. CPack will copy these files from the
staging directory back to the top build directory and possibly produce
checksum files if the :variable:`CPACK_PACKAGE_CHECKSUM` is set.
......@@ -21,13 +21,13 @@ file name components no longer add a dependency on the evaluated target.
In CMake 3.18 and lower a dependency on the evaluated target of the above
generator expressions would be always added. CMake 3.19 and above prefer
generator expressions would always be added. CMake 3.19 and above prefer
to not add this dependency. This policy provides compatibility for projects
that have not been updated to expect the new behavior.
The ``OLD`` behavior for this policy is to add a dependency on the evaluated
target for the the above generator expressions. The ``NEW`` behavior of
this policy is to not add a dependency on the evaluated target for the the
target for the above generator expressions. The ``NEW`` behavior of
this policy is to not add a dependency on the evaluated target for the
above generator expressions.
This policy was introduced in CMake version 3.19. Unlike many policies,
......
......@@ -47,7 +47,7 @@ a revised design to address these problems:
* The ``download``, ``update``, and ``patch`` steps are independent.
* The ``configure``, ``build``, ``test``, and ``install`` steps are not.
For custom steps, the :command:`ExternalProject_Add_Step` command provies
For custom steps, the :command:`ExternalProject_Add_Step` command provides
an ``INDEPENDENT`` option to mark them as independent. It is an error to
mark a step as independent if it depends on other steps that are not. Note
that this use of the term "independent" refers only to independence from
......
......@@ -14,7 +14,8 @@ Presets
-------
* :manual:`cmake(1)` and :manual:`cmake-gui(1)` now recognize
``CMakePresets.json`` and ``CMakeUserPresets.json`` files.
``CMakePresets.json`` and ``CMakeUserPresets.json`` files (see
:manual:`cmake-presets(7)`).
Generators
----------
......@@ -105,21 +106,22 @@ Commands
* The :command:`file(GENERATE)` command gained a new ``TARGET`` keyword to
support resolving target-dependent generator expressions.
* The :command:`file` gained sub-command `REAL_PATH` to compute a path with
symlinks resolved.
* The :command:`file` command gained a new ``REAL_PATH`` sub-command to
compute a path with symlinks resolved.
* The :command:`find_package` command learned to handle a version range.
* The :command:`separate_arguments` command gained new ``PROGRAM`` option to
search program.
* The :command:`separate_arguments` command gained a new ``PROGRAM`` option.
It allows the arguments to be treated as a program invocation and will
resolve the executable to a full path if it can be found.
* The :command:`set_property`, :command:`get_property`,
and :command:`get_directory_property` commands' ``DIRECTORY``
options now accept references to binary directory paths,
such as the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
* The ``DIRECTORY`` option of the :command:`set_property`,
:command:`get_property`, and :command:`get_directory_property` commands
now accepts references to binary directory paths, such as the value of
:variable:`CMAKE_CURRENT_BINARY_DIR`.
* The :command:`string` command gained set of new ``JSON`` sub commands
to provide JSON parsing capabilities.
* The :command:`string` command gained a set of new ``JSON`` sub commands
that provide JSON parsing capabilities.
Variables
---------
......@@ -134,6 +136,9 @@ Variables
initialize the new :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property and
avoid unnecessarily building dependencies for a static library.
* The :variable:`CMAKE_PCH_INSTANTIATE_TEMPLATES` variable was added to
initialize the new :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property.
* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable
was added to tell the :ref:`Visual Studio Generators` what maximum
version of the Windows SDK to choose.
......@@ -149,8 +154,8 @@ Properties
* The :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property was added to enable
template instantiation in the precompiled header. This is enabled by default
and offers a roughly 20% compile time improvement. Currently only supported
by Clang 11.
and may significantly improve compile times. Currently only supported for
Clang (version 11 or later).
* The :prop_tgt:`WIN32_EXECUTABLE` target property now supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
......@@ -175,19 +180,20 @@ Modules
:module:`CheckCXXSourceRuns` to more languages.
It also supports the ``CUDA`` language.
* :module:`CMakePackageConfigHelpers` module learned to manage version range.
* The :module:`CMakePackageConfigHelpers` module gained support for version
ranges.
* The :module:`FindCUDAToolkit` module gained support for finding CUDA
toolkits that do not contain ``nvcc``, as well as for finding scattered
toolkit installations when cross-compiling.
* The :module:`FindPackageHandleStandardArgs` module learned to handle
version range. It also gained the ``find_package_check_version()`` command to
check the validity of a version against version-related arguments of
version ranges. It also gained the ``find_package_check_version()`` command
to check the validity of a version against version-related arguments of
:command:`find_package` command.
* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
modules gained the capability to manage a version range.
modules gained the ability to handle a version range.
* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
modules provide, respectively, the variable ``Python3_LINK_OPTIONS``,
......@@ -195,14 +201,14 @@ Modules
* The :module:`FindSDL` module now provides:
* imported target ``SDL::SDL``,
* An imported target ``SDL::SDL``.
* result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``,
* Result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``.
* version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``
* Version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``,
``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``.
* :module:`FindSWIG` module gains the capability to manage a version range.
* The :module:`FindSWIG` module gained the ability to handle a version range.
* The :module:`FindTIFF` module gained a ``CXX`` component to
find the ``tiffxx`` library containing C++ bindings.
......@@ -211,15 +217,17 @@ Modules
target and associated ``Vulkan_GLSLC_EXECUTABLE`` variable which contain
the path to the GLSL SPIR-V compiler.
* :module:`UseSWIG` module gains new source file properties ``OUTPUT_DIR`` and
``OUTFILE_DIR`` to manage output directories on per source basis.
* The :module:`UseSWIG` module gained support for new source file properties
``OUTPUT_DIR`` and ``OUTFILE_DIR`` to manage output directories on a
per-source basis.
CTest
-----
* :manual:`ctest(1)` now supports ``compute-sanitizer`` (``cuda-memcheck``) as
``CTEST_MEMORYCHECK_COMMAND``. The different tools (memcheck, racecheck,
synccheck, initcheck) supplied by ``compute-sanitizer`` can be selected by
* :manual:`ctest(1)` now supports the CUDA ``compute-sanitizer`` checker
(previously known as ``cuda-memcheck``) as the ``CTEST_MEMORYCHECK_COMMAND``.
The different tools (``memcheck``, ``racecheck``, ``synccheck`` and
``initcheck``) supported by ``compute-sanitizer`` can be selected by
adding appropriate flags to the ``CTEST_MEMORYCHECK_COMMAND_OPTIONS``
variable. The default flags are ``--tool memcheck --leak-check full``.
......
......@@ -161,8 +161,8 @@ macro.
.. note:: ``COMPATIBILITY_MODE`` ``AnyNewerVersion`` handles the version range
if any is specified (see :command:`find_package` command for the details).
All other modes are incompatible with version range and will display an
author warning if a one is specified.
All other modes are incompatible with version ranges and will display an
author warning if one is specified.
If ``ARCH_INDEPENDENT`` is given, the installed package version will be
considered compatible even if it was built for a different architecture than
......
......@@ -19,7 +19,7 @@ Check that the ``<flag>`` is accepted by the compiler without a diagnostic.
Stores the result in an internal cache entry named ``<var>``.
This command temporarily sets the ``CMAKE_REQUIRED_DEFINITIONS`` variable
and calls the ``check_source_compiles(<LANG>`` function from the
and calls the ``check_source_compiles(<LANG>)`` function from the
:module:`CheckSourceCompiles` module. See documentation of that
module for a listing of variables that can otherwise modify the build.
......
......@@ -19,15 +19,12 @@ Check that the link ``<flag>`` is accepted by the ``<lang>`` compiler without
a diagnostic. Stores the result in an internal cache entry named ``<var>``.
This command temporarily sets the ``CMAKE_REQUIRED_LINK_OPTIONS`` variable
and calls the ``check_<lang>_source_compiles`` macro from the
``Check<lang>SourceCompiles`` module (:module:`CheckCSourceCompiles`,
:module:`CheckCSourceCompiles`, :module:`CheckCXXSourceCompiles`,
:module:`CheckOBJCSourceCompiles`, :module:`CheckOBJCXXSourceCompiles` or
:module:`CheckFortranSourceCompiles`). See documentation of these
modules for a listing of variables that can otherwise modify the build.
The underlying implementation rely on :prop_tgt:`LINK_OPTIONS` property to
check the specified flag. The ``LINKER:`` prefix, as described in
and calls the :command:`check_source_compiles` command from the
:module:`CheckSourceCompiles` module. See that module's documentation
for a listing of variables that can otherwise modify the build.
The underlying implementation relies on the :prop_tgt:`LINK_OPTIONS` property
to check the specified flag. The ``LINKER:`` prefix, as described in the
:command:`target_link_options` command, can be used as well.
A positive result from this check indicates only that the compiler did not
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment