Merge topic 'better_static_link_flags_docs'

6b17d85873 Help: Document when LINK_FLAGS and STATIC_LIBRARY_FLAGS are used
9561d42f95 target_link_options: Add test to verify static library behavior

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Robert Maynard <robert.maynard@kitware.com>
Merge-request: !2274

10 files changed, 34 insertions, 9 deletions

diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst
index 821198d..551d440 100644
--- a/Help/command/add_link_options.rst
+++ b/Help/command/add_link_options.rst
@@ -1,7 +1,7 @@
 add_link_options
 ----------------
 
-Adds options to the link of targets.
+Adds options to the link of shared library, module and executable targets.
 
 ::
 
diff --git a/Help/prop_dir/LINK_OPTIONS.rst b/Help/prop_dir/LINK_OPTIONS.rst
index 04b9e08..15c555f 100644
--- a/Help/prop_dir/LINK_OPTIONS.rst
+++ b/Help/prop_dir/LINK_OPTIONS.rst
@@ -1,7 +1,8 @@
 LINK_OPTIONS
 ------------
 
-List of options to use for the link step.
+List of options to use for the link step of shared library, module
+and executable targets.
 
 This property holds a :ref:`;-list <CMake Language Lists>` of options
 given so far to the :command:`add_link_options` command.
diff --git a/Help/prop_tgt/LINK_FLAGS.rst b/Help/prop_tgt/LINK_FLAGS.rst
index e0b72b5..3a344e6 100644
--- a/Help/prop_tgt/LINK_FLAGS.rst
+++ b/Help/prop_tgt/LINK_FLAGS.rst
@@ -1,7 +1,9 @@
 LINK_FLAGS
 ----------
 
-Additional flags to use when linking this target.
+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`.
 
 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
diff --git a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst
index 1f2910b..c30ecf1 100644
--- a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst
+++ b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst
@@ -1,9 +1,9 @@
 LINK_FLAGS_<CONFIG>
 -------------------
 
-Per-configuration linker flags for a target.
+Per-configuration linker flags for a shared library, module or executable target.
 
-This is the configuration-specific version of LINK_FLAGS.
+This is the configuration-specific version of :prop_tgt:`LINK_FLAGS`.
 
 .. note::
 
diff --git a/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst
index d3b2cd4..c91b1ae 100644
--- a/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst
+++ b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst
@@ -1,6 +1,12 @@
 STATIC_LIBRARY_FLAGS
 --------------------
 
-Extra flags to use when linking static libraries.
+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.
 
-Extra flags to use when linking a static library.
+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``, ...
diff --git a/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst b/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst
index cca353d..b867ac4 100644
--- a/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst
+++ b/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst
@@ -1,6 +1,6 @@
 STATIC_LIBRARY_FLAGS_<CONFIG>
 -----------------------------
 
-Per-configuration flags for creating a static library.
+Per-configuration archiver (or MSVC librarian) flags for a static library target.
 
-This is the configuration-specific version of STATIC_LIBRARY_FLAGS.
+This is the configuration-specific version of :prop_tgt:`STATIC_LIBRARY_FLAGS`.
diff --git a/Tests/RunCMake/target_link_options/LINK_OPTIONS-static-check.cmake b/Tests/RunCMake/target_link_options/LINK_OPTIONS-static-check.cmake
new file mode 100644
index 0000000..b68e451
--- /dev/null
+++ b/Tests/RunCMake/target_link_options/LINK_OPTIONS-static-check.cmake
@@ -0,0 +1,7 @@
+
+if (actual_stdout MATCHES "BADFLAG_RELEASE")
+  set (RunCMake_TEST_FAILED "Found 'BADFLAG_RELEASE' which was not expected.")
+endif()
+if (actual_stdout MATCHES "SHELL:")
+  string (APPEND RunCMake_TEST_FAILED "\nFound unexpected prefix 'SHELL:'.")
+endif()
diff --git a/Tests/RunCMake/target_link_options/LINK_OPTIONS-static-result.txt b/Tests/RunCMake/target_link_options/LINK_OPTIONS-static-result.txt
new file mode 100644
index 0000000..573541a
--- /dev/null
+++ b/Tests/RunCMake/target_link_options/LINK_OPTIONS-static-result.txt
@@ -0,0 +1 @@
+0
diff --git a/Tests/RunCMake/target_link_options/LINK_OPTIONS.cmake b/Tests/RunCMake/target_link_options/LINK_OPTIONS.cmake
index f17195d..84cf129 100644
--- a/Tests/RunCMake/target_link_options/LINK_OPTIONS.cmake
+++ b/Tests/RunCMake/target_link_options/LINK_OPTIONS.cmake
@@ -22,6 +22,13 @@ add_executable(LinkOptions_consumer LinkOptionsExe.c)
 target_link_libraries(LinkOptions_consumer PRIVATE LinkOptions_producer)
 
 
+# static library with generator expression
+add_library(LinkOptions_static STATIC LinkOptionsLib.c)
+target_link_options(LinkOptions_static PRIVATE $<$<CONFIG:Release>:${pre}BADFLAG_RELEASE${obj}>
+  "SHELL:" # produces no options
+  )
+
+
 # shared library with generator expression
 add_library(LinkOptions_shared SHARED LinkOptionsLib.c)
 target_link_options(LinkOptions_shared PRIVATE $<$<CONFIG:Release>:${pre}BADFLAG_RELEASE${obj}>
diff --git a/Tests/RunCMake/target_link_options/RunCMakeTest.cmake b/Tests/RunCMake/target_link_options/RunCMakeTest.cmake
index 121a0ce..39f580f 100644
--- a/Tests/RunCMake/target_link_options/RunCMakeTest.cmake
+++ b/Tests/RunCMake/target_link_options/RunCMakeTest.cmake
@@ -21,6 +21,7 @@ if (NOT CMAKE_C_COMPILER_ID STREQUAL "Intel")
 
   run_cmake_target(LINK_OPTIONS basic LinkOptions)
   run_cmake_target(LINK_OPTIONS interface LinkOptions_consumer)
+  run_cmake_target(LINK_OPTIONS static LinkOptions_static --config Release)
   run_cmake_target(LINK_OPTIONS shared LinkOptions_shared --config Release)
   run_cmake_target(LINK_OPTIONS mod LinkOptions_mod --config Release)
   run_cmake_target(LINK_OPTIONS exe LinkOptions_exe --config Release)