docs: Update docs for LD and ld entries

3 files changed, 31 insertions, 2 deletions

diff --git a/docs/markdown/Cross-compilation.md b/docs/markdown/Cross-compilation.md
index 43e1382..d94d487 100644
--- a/docs/markdown/Cross-compilation.md
+++ b/docs/markdown/Cross-compilation.md
@@ -87,6 +87,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'
@@ -102,6 +103,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