Merge topic 'docs-static-lib-link-options'

a6a543ced6 Help: Clarify that link options don't apply to static library targets

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !3285

2 files changed, 26 insertions, 15 deletions

diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst
index 1b02bee..a83005b 100644
--- a/Help/command/add_link_options.rst
+++ b/Help/command/add_link_options.rst
@@ -1,20 +1,25 @@
 add_link_options
 ----------------
 
-Add options to the link of shared library, module and executable targets.
+Add options to the link step for executable, shared library or module
+library targets in the current directory and below that are added after
+this command is invoked.
 
 .. code-block:: cmake
 
   add_link_options(<option> ...)
 
-Adds options to the link step for targets in the current directory and below
-that are added after this command is invoked. See documentation of the
+This command can be used to add any link options, but alternative commands
+exist to add libraries (:command:`target_link_libraries` or
+:command:`link_libraries`).  See documentation of the
 :prop_dir:`directory <LINK_OPTIONS>` and
 :prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties.
 
-This command can be used to add any options, but alternative commands
-exist to add libraries (:command:`target_link_libraries` or
-:command:`link_libraries`).
+.. note::
+
+  This command cannot be used to add options for static library targets,
+  since they do not use a linker.  To add archiver or MSVC librarian flags,
+  see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property.
 
 Arguments to ``add_link_options`` may use "generator expressions" with
 the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst
index 285455a..b5abbc4 100644
--- a/Help/command/target_link_options.rst
+++ b/Help/command/target_link_options.rst
@@ -1,7 +1,8 @@
 target_link_options
 -------------------
 
-Add link options to a target.
+Add options to the link step for an executable, shared library or module
+library target.
 
 .. code-block:: cmake
 
@@ -9,20 +10,25 @@ Add link options to a target.
     <INTERFACE|PUBLIC|PRIVATE> [items1...]
     [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
 
-Specifies link options to use when linking a given target.  The
-named ``<target>`` must have been created by a command such as
+The named ``<target>`` must have been created by a command such as
 :command:`add_executable` or :command:`add_library` and must not be an
 :ref:`ALIAS target <Alias Targets>`.
 
+This command can be used to add any link options, but alternative commands
+exist to add libraries (:command:`target_link_libraries` or
+:command:`link_libraries`).  See documentation of the
+:prop_dir:`directory <LINK_OPTIONS>` and
+:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties.
+
+.. note::
+
+  This command cannot be used to add options for static library targets,
+  since they do not use a linker.  To add archiver or MSVC librarian flags,
+  see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property.
+
 If ``BEFORE`` is specified, the content will be prepended to the property
 instead of being appended.
 
-This command can be used to add any options, but
-alternative commands exist to add libraries
-(:command:`target_link_libraries` and :command:`link_libraries`).
-See documentation of the :prop_dir:`directory <LINK_OPTIONS>` and
-:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties.
-
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
 specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``
 items will populate the :prop_tgt:`LINK_OPTIONS` property of