Merge topic 'doc-fixups-release-3.27'

78e7ea598d cmLocalGenerator: Fix trivial spelling error in code comment
1285fe27ff Help: Improve formatting and fix wording for ENABLE_EXPORTS
91336d061c Help: Improve formatting and cross-references for DEPENDS_EXPLICIT_ONLY
03208d9e18 Help: Fix indenting within TARGET_RUNTIME_DLLS genex docs

Acked-by: Kitware Robot <[email protected]>
Merge-request: !8688

Help/command/add_custom_command.rst

@@ -376,7 +376,7 @@ The options are:
 
   .. versionadded:: 3.27
 
-  Indicate that the command's ``DEPENDS`` argument represents all files
+  Indicates that the command's ``DEPENDS`` argument represents all files
   required by the command and implicit dependencies are not required.
 
   Without this option, if any target uses the output of the custom command,
@@ -390,6 +390,10 @@ The options are:
   Only the :ref:`Ninja Generators` actually use this information to remove
   unnecessary implicit dependencies.
 
+  See also the :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property, which may
+  provide another way for reducing the impact of target dependencies in some
+  scenarios.
+
 Examples: Generating Files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 

Help/manual/cmake-generator-expressions.7.rst

@@ -2267,9 +2267,9 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
     section for details.  Many :ref:`Find Modules` produce imported targets
     with the ``UNKNOWN`` type and therefore will be ignored.
 
-On platforms that support runtime paths (``RPATH``), refer to the
-:prop_tgt:`INSTALL_RPATH` target property.
-On Apple platforms, refer to the :prop_tgt:`INSTALL_NAME_DIR` target property.
+  On platforms that support runtime paths (``RPATH``), refer to the
+  :prop_tgt:`INSTALL_RPATH` target property.
+  On Apple platforms, refer to the :prop_tgt:`INSTALL_NAME_DIR` target property.
 
 .. genex:: $<TARGET_RUNTIME_DLL_DIRS:tgt>
 

Help/prop_tgt/ENABLE_EXPORTS.rst

@@ -27,30 +27,33 @@ varies by platform:
   referencing the executable since the dynamic loader will
   automatically bind symbols when the module is loaded.
 
-This property is initialized by the value of the variable
-:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` if it is set when an executable
-target is created.
+This property is initialized by the value of the
+:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` variable, if it is set when an
+executable target is created.  If :variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS`
+is not set, the :variable:`CMAKE_ENABLE_EXPORTS` variable is used to initialize
+the property instead for backward compatibility reasons.
+See below for alternative initialization behavior for shared library targets.
 
 .. versionadded:: 3.27
-  On macOS, to link with a shared library (standard one as well as framework),
-  a linker import file (e.g. a text-based stubs file, with ``.tbd`` extension)
-  can be used instead of the shared library itself.
-
-The generation of these linker import files, as well as the consumption, is
-controlled by this property. When this property is set to true, CMake will
-generate a ``.tbd`` file for each shared library created by
-:command:`add_library` command. This allow other targets to use this ``.tbd``
-file to link to the library with the :command:`target_link_libraries`
-command.
-
-.. note::
-
-  For compatibility purpose, this property will be ignored if
-  :prop_tgt:`XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS <XCODE_ATTRIBUTE_<an-attribute>>`
-  target property or the
-  :variable:`CMAKE_XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS <CMAKE_XCODE_ATTRIBUTE_<an-attribute>>`
-  variable is set to ``NO``.
-
-This property is initialized by the value of the variable
-:variable:`CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS` if it is set when a shared
-library target is created.
+  On Apple platforms, to link with a shared library (either a bare library or a
+  framework), a linker import file can be used instead of the actual shared
+  library. These linker import files are also known as text-based stubs, and
+  they have a ``.tbd`` file extension.
+
+  The generation of these linker import files, as well as their consumption, is
+  controlled by this property. When this property is set to true on a shared
+  library target, CMake will generate a ``.tbd`` file for the library.
+  Other targets that link to the shared library target will then use this
+  ``.tbd`` file when linking rather than linking to the shared library binary.
+
+  .. note::
+
+    For backward compatibility reasons, this property will be ignored if the
+    :prop_tgt:`XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS <XCODE_ATTRIBUTE_<an-attribute>>`
+    target property or the
+    :variable:`CMAKE_XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS <CMAKE_XCODE_ATTRIBUTE_<an-attribute>>`
+    variable is set to false.
+
+  For shared library targets, this property is initialized by the value of the
+  :variable:`CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS` variable, if it is set when
+  the target is created.

Help/variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY.rst

@@ -3,9 +3,11 @@ CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY
 
 .. versionadded:: 3.27
 
-Whether to enable DEPENDS_EXPLICIT_ONLY option by default in
+Whether to enable the ``DEPENDS_EXPLICIT_ONLY`` option by default in
 :command:`add_custom_command`.
 
 This variable affects the default behavior of the :command:`add_custom_command`
-command.  Setting this variable to ``ON`` is equivalent to using the ``DEPENDS_EXPLICIT_ONLY``
-option in all uses of that command.
+command.  Setting this variable to ``ON`` is equivalent to using the
+``DEPENDS_EXPLICIT_ONLY`` option in all uses of that command.
+
+See also :variable:`CMAKE_OPTIMIZE_DEPENDENCIES`.

Help/variable/CMAKE_ENABLE_EXPORTS.rst

@@ -9,6 +9,7 @@ This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target
 property for executable targets when they are created by calls to the
 :command:`add_executable` command.  See the property documentation for details.
 
-This command has been superseded by the
-:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` command.  It is provided for
-compatibility with older CMake code.
+This variable has been superseded by the
+:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` variable.  It is provided for
+backward compatibility with older CMake code, but should not be used in new
+projects.

Source/cmLocalGenerator.cxx

@@ -70,7 +70,7 @@
 #endif
 
 // List of variables that are replaced when
-// rules are expanced.  These variables are
+// rules are expanded.  These variables are
 // replaced in the form <var> with GetSafeDefinition(var).
 // ${LANG} is replaced in the variable first with all enabled
 // languages.