LINK_OPTIONS: Add support of "LINKER:" prefix

7 files changed, 73 insertions, 9 deletions

diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt
new file mode 100644
index 0000000..76927be
--- /dev/null
+++ b/Help/command/LINK_OPTIONS_LINKER.txt
@@ -0,0 +1,10 @@
+To pass options to the linker tool, each compiler driver has is own syntax.
+The ``LINKER:`` prefix can be used to specify, in a portable way, options
+to pass to the linker tool. The ``LINKER:`` prefix is replaced by the required
+driver option and the rest of the option string defines linker arguments using
+``,`` as separator. These arguments will be formatted according to the
+:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` and
+:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variables.
+
+For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for
+``Clang`` and ``-Wl,-z,defs`` for ``GNU GCC``.
diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst
index c827d70..821198d 100644
--- a/Help/command/add_link_options.rst
+++ b/Help/command/add_link_options.rst
@@ -7,12 +7,12 @@ Adds options to the link of targets.
 
   add_link_options(<option> ...)
 
-Adds options to the linker command line for targets in the current
-directory and below that are added after this command is invoked.
-See documentation of the :prop_dir:`directory <LINK_OPTIONS>` and
+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
+: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 command
+This command can be used to add any options, but alternative commands
 exist to add libraries (:command:`target_link_libraries` or
 :command:`link_libraries`).
 
@@ -21,4 +21,6 @@ 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.
 
+.. include:: LINK_OPTIONS_LINKER.txt
+
 .. include:: OPTIONS_SHELL.txt
diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst
index 489f981..8f47180 100644
--- a/Help/command/target_link_options.rst
+++ b/Help/command/target_link_options.rst
@@ -29,7 +29,7 @@ items will populate the :prop_tgt:`LINK_OPTIONS` property of
 ``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
 :prop_tgt:`INTERFACE_LINK_OPTIONS` property of ``<target>``.
 (:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.)
-The following arguments specify compile options.  Repeated calls for the same
+The following arguments specify link options.  Repeated calls for the same
 ``<target>`` append items in the order called.
 
 Arguments to ``target_link_options`` may use "generator expressions"
@@ -37,4 +37,6 @@ 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.
 
+.. include:: LINK_OPTIONS_LINKER.txt
+
 .. include:: OPTIONS_SHELL.txt
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index edfff6c..fde1aab 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -460,6 +460,8 @@ Variables for Languages
    /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE
    /variable/CMAKE_LANG_LINKER_PREFERENCE
    /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES
+   /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG
+   /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP
    /variable/CMAKE_LANG_LINK_EXECUTABLE
    /variable/CMAKE_LANG_OUTPUT_EXTENSION
    /variable/CMAKE_LANG_PLATFORM_ID
diff --git a/Help/release/dev/LINK_OPTIONS.rst b/Help/release/dev/LINK_OPTIONS.rst
index 87e7c40..e40dab2 100644
--- a/Help/release/dev/LINK_OPTIONS.rst
+++ b/Help/release/dev/LINK_OPTIONS.rst
@@ -3,9 +3,9 @@ LINK_OPTIONS
 
 * CMake gained new capabilities to manage link step:
 
-  * :prop_dir:`LINK_OPTIONS` directory property
+  * :prop_dir:`LINK_OPTIONS` directory property.
   * :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
-    properties
+    properties.
   * :command:`add_link_options` command to add link options in the current
-    directory
-  * :command:`target_link_options` command to add link options to targets
+    directory.
+  * :command:`target_link_options` command to add link options to targets.
diff --git a/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst
new file mode 100644
index 0000000..0e52282
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst
@@ -0,0 +1,39 @@
+CMAKE_<LANG>_LINKER_WRAPPER_FLAG
+--------------------------------
+
+Defines the syntax of compiler driver option to pass options to the linker
+tool. It will be used to translate the ``LINKER:`` prefix in the link options
+(see :command:`add_link_options` and :command:`target_link_options`).
+
+This variable holds a :ref:`;-list <CMake Language Lists>` of tokens.
+If a space (i.e. " ") is specified as last token, flag and ``LINKER:``
+arguments will be specified as separate arguments to the compiler driver.
+The :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variable can be specified
+to manage concatenation of arguments.
+
+For example, for ``Clang`` we have:
+
+.. code-block:: cmake
+
+  set (CMAKE_C_LINKER_WRAPPER_FLAG "-Xlinker" " ")
+
+Specifying ``"LINKER:-z defs"`` will be transformed in
+``-Xlinker -z -Xlinker defs``.
+
+For ``GNU GCC``:
+
+.. code-block:: cmake
+
+  set (CMAKE_C_LINKER_WRAPPER_FLAG "-Wl,")
+  set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",")
+
+Specifying ``"LINKER:-z defs"`` will be transformed in ``-Wl,-z,defs``.
+
+And for ``SunPro``:
+
+.. code-block:: cmake
+
+  set (CMAKE_C_LINKER_WRAPPER_FLAG "-Qoption" "ld" " ")
+  set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",")
+
+Specifying ``"LINKER:-z defs"`` will be transformed in ``-Qoption ld -z,defs``.
diff --git a/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst
new file mode 100644
index 0000000..faf1481
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst
@@ -0,0 +1,9 @@
+CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP
+------------------------------------
+
+This variable is used with :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG`
+variable to format ``LINKER:`` prefix in the link options
+(see :command:`add_link_options` and :command:`target_link_options`).
+
+When specified, arguments of the ``LINKER:`` prefix will be concatenated using
+this value as separator.