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 <[email protected]>
Acked-by: Robert Maynard <[email protected]>
Merge-request: !2274

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.
 
 ::
 

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.

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

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::
 

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``, ...

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`.

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()

Tests/RunCMake/target_link_options/LINK_OPTIONS-static-result.txt

@@ -0,0 +1 @@
+0

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}>

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)