From 8be7694d9756f535d7f681b396cfda44e0463c64 Mon Sep 17 00:00:00 2001
From: Craig Scott <craig.scott@crascit.com>
Date: Sun, 18 Jul 2021 15:57:06 +1000
Subject: Help: Fix trivial typo
---
Help/command/target_link_libraries.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst
index ac231bc..c85094a 100644
--- a/Help/command/target_link_libraries.rst
+++ b/Help/command/target_link_libraries.rst
@@ -300,7 +300,7 @@ The object files associated with an object library may be referenced
by the :genex:`$<TARGET_OBJECTS>` generator expression. Such object
files are placed on the link line *before* all libraries, regardless
of their relative order. Additionally, an ordering dependency will be
-added to the build sysstem to make sure the object library is up-to-date
+added to the build system to make sure the object library is up-to-date
before the dependent target links. For example, the code
.. code-block:: cmake
--
cgit v0.12
From b5a96716eb38e5859f10947e3d61bb4a8c0dffc0 Mon Sep 17 00:00:00 2001
From: Craig Scott <craig.scott@crascit.com>
Date: Sun, 18 Jul 2021 16:45:20 +1000
Subject: Help: Clarify which project() call PROJECT_IS_TOP_LEVEL is for
---
Help/variable/PROJECT_IS_TOP_LEVEL.rst | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Help/variable/PROJECT_IS_TOP_LEVEL.rst b/Help/variable/PROJECT_IS_TOP_LEVEL.rst
index ad61fec..7e40704 100644
--- a/Help/variable/PROJECT_IS_TOP_LEVEL.rst
+++ b/Help/variable/PROJECT_IS_TOP_LEVEL.rst
@@ -3,7 +3,8 @@ PROJECT_IS_TOP_LEVEL
.. versionadded:: 3.21
-A boolean variable indicating whether :command:`project` was called in a top
+A boolean variable indicating whether the most recently called
+:command:`project` command in the current scope or above was in the top
level ``CMakeLists.txt`` file.
Some modules should only be included as part of the top level
--
cgit v0.12
From c8ea886123711c3e47794bb1f297950333e4904c Mon Sep 17 00:00:00 2001
From: Craig Scott <craig.scott@crascit.com>
Date: Tue, 20 Jul 2021 08:38:49 +1000
Subject: Help: Re-order file() sub-commands in Filesystem section
The file(COPY_FILE) sub-command is closely related to the
file(COPY) sub-command. Move the former to just before the
latter for improved continuity. The file(RENAME) sub-command is
also somewhat related to file(COPY_FILE), so it was also moved to
keep it just before file(COPY_FILE).
The file(MAKE_DIRECTORY) sub-command was also moved to just
before the file(REMOVE) and file(REMOVE_RECURSE) sub-commands
to keep them together and improve logical flow of operations.
---
Help/command/file.rst | 56 +++++++++++++++++++++++++--------------------------
1 file changed, 28 insertions(+), 28 deletions(-)
diff --git a/Help/command/file.rst b/Help/command/file.rst
index 943bf7c..a9cbd40 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -38,10 +38,10 @@ Synopsis
`Filesystem`_
file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...])
+ file(`MAKE_DIRECTORY`_ [<dir>...])
+ file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...])
file(`RENAME`_ <oldname> <newname> [...])
file(`COPY_FILE`_ <oldname> <newname> [...])
- file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...])
- file(`MAKE_DIRECTORY`_ [<dir>...])
file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
file(`SIZE`_ <filename> <out-var>)
file(`READ_SYMLINK`_ <linkname> <out-var>)
@@ -691,6 +691,32 @@ Examples of recursive globbing include::
/dir/*.py - match all python files in /dir and subdirectories
+.. _MAKE_DIRECTORY:
+
+.. code-block:: cmake
+
+ file(MAKE_DIRECTORY [<directories>...])
+
+Create the given directories and their parents as needed.
+
+.. _REMOVE:
+.. _REMOVE_RECURSE:
+
+.. code-block:: cmake
+
+ file(REMOVE [<files>...])
+ file(REMOVE_RECURSE [<files>...])
+
+Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given
+files and directories, also non-empty directories. No error is emitted if a
+given file does not exist. Relative input paths are evaluated with respect
+to the current source directory.
+
+.. versionchanged:: 3.15
+ Empty input paths are ignored with a warning. Previous versions of CMake
+ interpreted empty strings as a relative path with respect to the current
+ directory and removed its contents.
+
.. _RENAME:
.. code-block:: cmake
@@ -739,32 +765,6 @@ The options are:
If the ``<newname>`` path already exists, do not replace it if it is the
same as ``<oldname>``. Otherwise, an error is emitted.
-.. _REMOVE:
-.. _REMOVE_RECURSE:
-
-.. code-block:: cmake
-
- file(REMOVE [<files>...])
- file(REMOVE_RECURSE [<files>...])
-
-Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given
-files and directories, also non-empty directories. No error is emitted if a
-given file does not exist. Relative input paths are evaluated with respect
-to the current source directory.
-
-.. versionchanged:: 3.15
- Empty input paths are ignored with a warning. Previous versions of CMake
- interpreted empty string as a relative path with respect to the current
- directory and removed its contents.
-
-.. _MAKE_DIRECTORY:
-
-.. code-block:: cmake
-
- file(MAKE_DIRECTORY [<directories>...])
-
-Create the given directories and their parents as needed.
-
.. _COPY:
.. _INSTALL:
--
cgit v0.12
From 8d1944c675a2240f3b71f813cbf7139429ab766c Mon Sep 17 00:00:00 2001
From: Craig Scott <craig.scott@crascit.com>
Date: Sun, 18 Jul 2021 19:13:06 +1000
Subject: Help: Expand details for file(COPY_FILE)
---
Help/command/file.rst | 20 ++++++++++++++++++--
1 file changed, 18 insertions(+), 2 deletions(-)
diff --git a/Help/command/file.rst b/Help/command/file.rst
index a9cbd40..f038871 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -751,6 +751,8 @@ The options are:
[RESULT <result>]
[ONLY_IF_DIFFERENT])
+.. versionadded:: 3.21
+
Copy a file from ``<oldname>`` to ``<newname>``. Directories are not
supported. Symlinks are ignored and ``<oldfile>``'s content is read and
written to ``<newname>`` as a new file.
@@ -762,8 +764,17 @@ The options are:
If ``RESULT`` is not specified and the operation fails, an error is emitted.
``ONLY_IF_DIFFERENT``
- If the ``<newname>`` path already exists, do not replace it if it is the
- same as ``<oldname>``. Otherwise, an error is emitted.
+ If the ``<newname>`` path already exists, do not replace it if the file's
+ contents are already the same as ``<oldname>`` (this avoids updating
+ ``<newname>``'s timestamp).
+
+This sub-command has some similarities to :command:`configure_file` with the
+``COPYONLY`` option. An important difference is that :command:`configure_file`
+creates a dependency on the source file, so CMake will be re-run if it changes.
+The ``file(COPY_FILE)`` sub-command does not create such a dependency.
+
+See also the ``file(COPY)`` sub-command just below which provides
+further file-copying capabilities.
.. _COPY:
.. _INSTALL:
@@ -779,6 +790,11 @@ The options are:
[[PATTERN <pattern> | REGEX <regex>]
[EXCLUDE] [PERMISSIONS <permissions>...]] [...])
+.. note::
+
+ For a simple file copying operation, the ``file(COPY_FILE)`` sub-command
+ just above may be easier to use.
+
The ``COPY`` signature copies files, directories, and symlinks to a
destination folder. Relative input paths are evaluated with respect
to the current source directory, and a relative destination is
--
cgit v0.12