static library: add property STATIC_LIBRARY_OPTIONS

issue: #18251

6 files changed, 46 insertions, 10 deletions

diff --git a/Help/prop_tgt/LINK_FLAGS.rst b/Help/prop_tgt/LINK_FLAGS.rst
index 3a344e6..92cd3c0 100644
--- a/Help/prop_tgt/LINK_FLAGS.rst
+++ b/Help/prop_tgt/LINK_FLAGS.rst
@@ -3,11 +3,12 @@ LINK_FLAGS
 
 Additional flags to use when linking this target if it is a shared library,
 module library, or an executable. Static libraries need to use
-:prop_tgt:`STATIC_LIBRARY_FLAGS`.
+:prop_tgt:`STATIC_LIBRARY_OPTIONS` or :prop_tgt:`STATIC_LIBRARY_FLAGS`
+properties.
 
-The LINK_FLAGS property, managed as a string, can be used to add extra flags
-to the link step of a target.  :prop_tgt:`LINK_FLAGS_<CONFIG>` will add to the
-configuration ``<CONFIG>``, for example, ``DEBUG``, ``RELEASE``,
+The ``LINK_FLAGS`` property, managed as a string, can be used to add extra
+flags to the link step of a target.  :prop_tgt:`LINK_FLAGS_<CONFIG>` will add
+to the configuration ``<CONFIG>``, for example, ``DEBUG``, ``RELEASE``,
 ``MINSIZEREL``, ``RELWITHDEBINFO``, ...
 
 .. note::
diff --git a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst
index c30ecf1..e3918ca 100644
--- a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst
+++ b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst
@@ -1,7 +1,8 @@
 LINK_FLAGS_<CONFIG>
 -------------------
 
-Per-configuration linker flags for a shared library, module or executable target.
+Per-configuration linker flags for a shared library, module or executable
+target.
 
 This is the configuration-specific version of :prop_tgt:`LINK_FLAGS`.
 
diff --git a/Help/prop_tgt/LINK_OPTIONS.rst b/Help/prop_tgt/LINK_OPTIONS.rst
index c5263a2..bd5e937 100644
--- a/Help/prop_tgt/LINK_OPTIONS.rst
+++ b/Help/prop_tgt/LINK_OPTIONS.rst
@@ -1,7 +1,10 @@
 LINK_OPTIONS
 ------------
 
-List of options to use when linking this target.
+List of options to use for the link step of shared library, module
+and executable targets. Targets that are static libraries need to use
+the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property.
+
 
 This property holds a :ref:`;-list <CMake Language Lists>` of options
 specified so far for its target.  Use the :command:`target_link_options`
diff --git a/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst
index c91b1ae..66e0e8b 100644
--- a/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst
+++ b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst
@@ -2,11 +2,16 @@ STATIC_LIBRARY_FLAGS
 --------------------
 
 Archiver (or MSVC librarian) flags for a static library target.
-Targets that are shared libraries, modules, or executables can use
-the :prop_tgt:`LINK_OPTIONS` or :prop_tgt:`LINK_FLAGS` target property.
+Targets that are shared libraries, modules, or executables need to use
+the :prop_tgt:`LINK_OPTIONS` or :prop_tgt:`LINK_FLAGS` target properties.
 
-The STATIC_LIBRARY_FLAGS property, managed as a string, can be used to add
+The ``STATIC_LIBRARY_FLAGS`` property, managed as a string, can be used to add
 extra flags to the link step of a static library target.
 :prop_tgt:`STATIC_LIBRARY_FLAGS_<CONFIG>` will add to the configuration
 ``<CONFIG>``, for example, ``DEBUG``, ``RELEASE``, ``MINSIZEREL``,
 ``RELWITHDEBINFO``, ...
+
+.. note::
+
+  This property has been superseded by :prop_tgt:`STATIC_LIBRARY_OPTIONS`
+  property.
diff --git a/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst b/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst
index b867ac4..5b97941 100644
--- a/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst
+++ b/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst
@@ -1,6 +1,12 @@
 STATIC_LIBRARY_FLAGS_<CONFIG>
 -----------------------------
 
-Per-configuration archiver (or MSVC librarian) flags for a static library target.
+Per-configuration archiver (or MSVC librarian) flags for a static library
+target.
 
 This is the configuration-specific version of :prop_tgt:`STATIC_LIBRARY_FLAGS`.
+
+.. note::
+
+  This property has been superseded by :prop_tgt:`STATIC_LIBRARY_OPTIONS`
+  property.
diff --git a/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst
new file mode 100644
index 0000000..6e03185
--- /dev/null
+++ b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst
@@ -0,0 +1,20 @@
+STATIC_LIBRARY_OPTIONS
+----------------------
+
+Archiver (or MSVC librarian) flags for a static library target.
+Targets that are shared libraries, modules, or executables need to use
+the :prop_tgt:`LINK_OPTIONS` target property.
+
+This property holds a :ref:`;-list <CMake Language Lists>` of options
+specified so far for its target.  Use :command:`set_target_properties` or
+:command:`set_property` commands to set its content.
+
+Contents of ``STATIC_LIBRARY_OPTIONS`` may use "generator expressions" with the
+syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)` manual
+for available expressions.  See the :manual:`cmake-buildsystem(7)` manual
+for more on defining buildsystem properties.
+
+.. note::
+
+  This property must be used in preference to :prop_tgt:`STATIC_LIBRARY_FLAGS`
+  property.