rust: fix -C prefer-dynamic behavior

I noticed when building a project that uses a proc macro that Meson
passed -C prefer-dynamic for the executable, and not the proc macro,
while cargo passed -C prefer-dynamic for the proc macro, but not for
the executable.  Meson's behavior broke setting -C panic=abort on the
executable.

As far as we can tell, because we explicitly pass each library path to
rustc, the only thing -C prefer-dynamic affects in Meson is how the
standard libraries are linked.  Generally, one does not want the
standard libraries to be dynamically linked, because if the Rust
compiler is ever updated, anything linked against the old standard
libraries will likely break, due to the lack of a stable Rust ABI.
Therefore, I've reorganised Meson's behavior around the principle that
the standard libraries should only be dynamically linked when Rust
dynamic linking has already been opted into in some other way.  The
details of how this manifests are now explained in the documentation.

1 files changed, 8 insertions, 0 deletions

diff --git a/docs/markdown/Rust.md b/docs/markdown/Rust.md
index b7e36e3c7..151aac080 100644
--- a/docs/markdown/Rust.md
+++ b/docs/markdown/Rust.md
@@ -65,3 +65,11 @@ be configured to use the file as it's not in the source root (Meson does not
 write files into the source directory). [See the upstream
 docs](https://rust-analyzer.github.io/manual.html#non-cargo-based-projects) for
 more information on how to configure that.
+
+## Linking with standard libraries
+
+Meson will link the Rust standard libraries (e.g. libstd) statically, unless the
+target is a proc macro or dylib, or it depends on a dylib, in which case [`-C
+prefer-dynamic`](https://doc.rust-lang.org/rustc/codegen-options/index.html#prefer-dynamic)
+will be passed to the Rust compiler, and the standard libraries will be
+dynamically linked.