Merge pull request #6207 from dcbaker/linker-option

Add a way to select the dynamic linker meson uses

4 files changed, 48 insertions, 2 deletions

diff --git a/docs/markdown/Cross-compilation.md b/docs/markdown/Cross-compilation.md
index beb9824..b3cdc81 100644
--- a/docs/markdown/Cross-compilation.md
+++ b/docs/markdown/Cross-compilation.md
@@ -97,6 +97,7 @@ this:
 [binaries]
 c = '/usr/bin/i586-mingw32msvc-gcc'
 cpp = '/usr/bin/i586-mingw32msvc-g++'
+ld = 'gold'
 ar = '/usr/i586-mingw32msvc/bin/ar'
 strip = '/usr/i586-mingw32msvc/bin/strip'
 pkgconfig = '/usr/bin/i586-mingw32msvc-pkg-config'
@@ -112,6 +113,12 @@ of a wrapper, these lines are all you need to write. Meson will
 automatically use the given wrapper when it needs to run host
 binaries. This happens e.g. when running the project's test suite.
 
+ld is special because it is compiler specific. For compilers like gcc and
+clang which are used to invoke the linker this is a value to pass to their
+"choose the linker" argument (-fuse-ld= in this case). For compilers like
+MSVC and Clang-Cl, this is the path to a linker for meson to invoke, such as
+`link.exe` or `lld-link.exe`. Support for ls is *new in 0.53.0*
+
 The next section lists properties of the cross compiler and its target
 system, and thus properties of host system of what we're building. It
 looks like this:
diff --git a/docs/markdown/Native-environments.md b/docs/markdown/Native-environments.md
index 41e678e..677f067 100644
--- a/docs/markdown/Native-environments.md
+++ b/docs/markdown/Native-environments.md
@@ -40,6 +40,7 @@ like `llvm-config`
 c = '/usr/local/bin/clang'
 cpp = '/usr/local/bin/clang++'
 rust = '/usr/local/bin/rust'
+ld = 'gold'
 llvm-config = '/usr/local/llvm-svn/bin/llvm-config'
 ```
 
diff --git a/docs/markdown/howtox.md b/docs/markdown/howtox.md
index 188f1f7..f73d6b9 100644
--- a/docs/markdown/howtox.md
+++ b/docs/markdown/howtox.md
@@ -23,8 +23,29 @@ compilation is done by setting `CC` to point to the cross compiler
 that Meson supports natively the case where you compile helper tools
 (such as code generators) and use the results during the
 build. Because of this Meson needs to know both the native and the
-cross compiler. The former is set via the environment variables and
-the latter via the cross file only.
+cross compiler. The former is set via the environment variables or
+native-files and the latter via the cross file only.
+
+## Set dynamic linker
+
+```console
+$ CC=clang LD=lld meson <options>
+```
+
+or
+
+```console
+$ CC=clang-cl LD=link meson <options>
+```
+
+Like the compiler, the linker is selected via the LD environment variable, or
+through the `ld` entry in a native or cross file. You must be aware of
+whehter you're using a compiler that invokes the linker itself (most
+compilers including GCC and Clang) or a linker that is invoked directly (when
+using MSVC or compilers that act like it, including Clang-Cl). With the
+former `ld` or `LD` should be the value to pass to the compiler's special
+argument (such as `-fuse-ld` with clang and gcc), with the latter it should
+be an exectuable, such as `lld-link.exe`.
 
 ## Set default C/C++ language version
 
diff --git a/docs/markdown/snippets/linker_override.md b/docs/markdown/snippets/linker_override.md
new file mode 100644
index 0000000..21cb072
--- /dev/null
+++ b/docs/markdown/snippets/linker_override.md
@@ -0,0 +1,17 @@
+## Generic Overrider for Dynamic Linker selection
+
+Previous to meson 0.52.0 you set the dynamic linker using compiler specific
+flags passed via language flags and hoped things worked out. In meson 0.52.0
+meson started detecting the linker and making intelligent decisions about
+using it. Unfortunately this broke choosing a non-default linker.
+
+Now there is a generic mechanism for doing this, you may use the LD
+environment variable (with normal meson environment variable rules), or add
+the following to a cross or native file:
+
+```ini
+[binaries]
+ld = 'gold'
+```
+
+And meson will select the linker if possible.