From 8be7694d9756f535d7f681b396cfda44e0463c64 Mon Sep 17 00:00:00 2001 From: Craig Scott 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:`$` 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 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 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`_} [...] [...]) + file(`MAKE_DIRECTORY`_ [...]) + file({`REMOVE`_ | `REMOVE_RECURSE`_ } [...]) file(`RENAME`_ [...]) file(`COPY_FILE`_ [...]) - file({`REMOVE`_ | `REMOVE_RECURSE`_ } [...]) - file(`MAKE_DIRECTORY`_ [...]) file({`COPY`_ | `INSTALL`_} ... DESTINATION [...]) file(`SIZE`_ ) file(`READ_SYMLINK`_ ) @@ -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 [...]) + +Create the given directories and their parents as needed. + +.. _REMOVE: +.. _REMOVE_RECURSE: + +.. code-block:: cmake + + file(REMOVE [...]) + file(REMOVE_RECURSE [...]) + +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 ```` path already exists, do not replace it if it is the same as ````. Otherwise, an error is emitted. -.. _REMOVE: -.. _REMOVE_RECURSE: - -.. code-block:: cmake - - file(REMOVE [...]) - file(REMOVE_RECURSE [...]) - -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 [...]) - -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 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 ] [ONLY_IF_DIFFERENT]) +.. versionadded:: 3.21 + Copy a file from ```` to ````. Directories are not supported. Symlinks are ignored and ````'s content is read and written to ```` 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 ```` path already exists, do not replace it if it is the - same as ````. Otherwise, an error is emitted. + If the ```` path already exists, do not replace it if the file's + contents are already the same as ```` (this avoids updating + ````'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 | REGEX ] [EXCLUDE] [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