Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
CMake
CMake
Commits
95c14579
Commit
95c14579
authored
Oct 24, 2020
by
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
Changes
14
Pipelines
1
Hide whitespace changes
Inline
Side-by-side
Help/command/cmake_language.rst
View file @
95c14579
...
...
@@ -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>``
S
e
pcify a variable in which to store the identification for the
Sp
e
cify 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:`
S
emicolon-separated list <CMake Language
This will store in ``<var>`` a :ref:`
s
emicolon-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:`
S
emicolon-separated list <CMake Language
This will store in ``<var>`` a :ref:`
s
emicolon-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
...
...
Help/command/configure_file.rst
View file @
95c14579
...
...
@@ -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--).
...
...
Help/command/execute_process.rst
View file @
95c14579
...
...
@@ -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.
...
...
Help/command/file.rst
View file @
95c14579
...
...
@@ -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``
a
ll items are changed
A
ll items are changed
.
``FILE_PERMISSIONS``
o
nly files are changed
O
nly files are changed
.
``DIRECTORY_PERMISSIONS``
o
nly directories are changed
O
nly 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``
u
se ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for
directories
U
se ``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``.
C
ompression level can be specied
by using
``COMPRESSION_LEVEL`` option.
C
ompression
level should be between 0-9
. 0 is
the default
compression
.
``COMPRESSION`` option must be
specified for
``COMPRESSION_LEVEL``.
The c
ompression level can be speci
fi
ed
with the
``COMPRESSION_LEVEL`` option.
The ``<c
ompression
-
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
...
...
Help/command/find_package.rst
View file @
95c14579
...
...
@@ -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
.
...
...
Help/command/separate_arguments.rst
View file @
95c14579
...
...
@@ -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,
search
ed
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:
...
...
Help/command/string.rst
View file @
95c14579
...
...
@@ -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.
Require
d
an element of array or object type.
Require
s
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
w
e
written
in ``<out-var>``.
without the removed element will
b
e
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
...
...
Help/cpack_gen/external.rst
View file @
95c14579
...
...
@@ -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.
Help/policy/CMP0112.rst
View file @
95c14579
...
...
@@ -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,
...
...
Help/policy/CMP0114.rst
View file @
95c14579
...
...
@@ -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 provi
d
es
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
...
...
Help/release/3.19.rst
View file @
95c14579
...
...
@@ -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:`
g
et_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:`
s
et_property`,
:command:`get_property`,
and :command:`get_directory_property` commands
now accept
s
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
t
o
provide JSON parsing capabilities.
* The :command:`string` command gained
a
set of new ``JSON`` sub commands
t
hat
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 time
s
. 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 range
s
. 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
cap
ability to
m
an
ag
e a version range.
modules gained the ability to
h
an
dl
e 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``
.
*
r
esult variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``
,
*
R
esult variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``
.
*
v
ersion variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``
*
V
ersion variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``
,
``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``.
* :module:`FindSWIG` module gain
s
the
cap
ability to
m
an
ag
e a version range.
*
The
:module:`FindSWIG` module gain
ed
the ability to
h
an
dl
e 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``.
...
...
Modules/CMakePackageConfigHelpers.cmake
View file @
95c14579
...
...
@@ -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 range
s
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
...
...
Modules/CheckCompilerFlag.cmake
View file @
95c14579
...
...
@@ -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.
...
...
Modules/CheckLinkerFlag.cmake
View file @
95c14579
...
...
@@ -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
...
...
Craig Scott
@craig.scott
mentioned in commit
394a5b71
·
Oct 26, 2020
mentioned in commit
394a5b71
mentioned in commit 394a5b71b039b0f3dac58998b758b10c7cabb37d
Toggle commit list
Craig Scott
@craig.scott
mentioned in commit
39fac5f4
·
Oct 26, 2020
mentioned in commit
39fac5f4
mentioned in commit 39fac5f4760f5700fc0e755e37aded3d35673dc0
Toggle commit list
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment