From c008ee29bf6d7510888ec45390601259845a3aba Mon Sep 17 00:00:00 2001
From: Rui Ueyama <ruiu@cs.stanford.edu>
Date: Mon, 27 Dec 2021 12:14:30 +0900
Subject: [PATCH] Update README

---
 README.md | 46 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 41 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index e37da3bedb..ae4309686a 100644
--- a/README.md
+++ b/README.md
@@ -94,15 +94,49 @@ sudo apt-get install bsdmainutils dwarfdump libc6-dev:i386 lib32gcc-10-dev libst
 
 ## How to use
 
+<details><summary>A classic way to use mold</summary>
+
 On Unix, the linker command (which is usually `/usr/bin/ld`) is
-invoked indirectly by `cc` (or `gcc` or `clang`), which is typically
-in turn indirectly invoked by `make` or some other build system command.
+invoked indirectly by the compiler driver (which is usually `cc`,
+`gcc` or `clang`), which is typically in turn indirectly invoked by
+`make` or some other build system command.
+
+If you can specify an additional command line option to your compiler
+driver by modifying build system's config files, add one of the
+following flags to use `mold` instead of `/usr/bin/ld`:
 
-A classic way to use `mold`:
+- clang before 12.0: pass `-fuse-ld=<absolute-path-to-mold-executable>`;
 
-- `clang` before 12.0: pass `-fuse-ld=<absolute-path-to-mold-executable>`;
 - clang after 12.0: pass `--ld-path=<absolute-path-to-mold-executable>`;
-- gcc: `--ld-path` patch [has been declined by GCC maintainers](https://gcc.gnu.org/pipermail/gcc-patches/2021-June/573833.html), instead they advise to use a [workaround](https://gcc.gnu.org/pipermail/gcc-patches/2021-June/573823.html): create directory `<dirname>`, then `ln -s <path-to-mold> <dirname>/ld`, and then pass `-B<dirname>` (`-B` tells GCC to look for `ld` in specified location).
+
+- gcc: `--ld-path` patch [has been declined by GCC
+  maintainers](https://gcc.gnu.org/pipermail/gcc-patches/2021-June/573833.html),
+  instead they advise to use a
+  [workaround](https://gcc.gnu.org/pipermail/gcc-patches/2021-June/573823.html):
+  create directory `<dirname>`, then `ln -s <path-to-mold>
+  <dirname>/ld`, and then pass `-B<dirname>` (`-B` tells GCC to look
+  for `ld` in specified location).
+
+</details>
+
+<details><summary>If you are using Rust</summary>
+
+Create `.cargo/config.toml` in your project with the following:
+
+```
+[target.x86_64-unknown-linux-gnu]
+linker = "clang"
+rustflags = ["-C", "link-arg=-fuse-ld=/path/to/mold"]
+```
+
+where `/path/to/mold` is an absolute path to `mold` exectuable.
+
+If you want to use mold for all projects, put the above snippet to
+`~/.cargo/config.toml`.
+
+</details>
+
+<details><summary>mold -run</summary>
 
 It is sometimes very hard to pass an appropriate command line option
 to `cc` to specify an alternative linker.  To deal with the situation,
@@ -126,6 +160,8 @@ variable set to its companion shared object file. The shared object
 file intercepts all function calls to `exec(3)`-family functions to
 replace `argv[0]` with `mold` if it is `ld`, `ld.gold` or `ld.lld`.
 
+</details>
+
 mold leaves its identification string in `.comment` section in an output
 file. You can print it out to verify that you are actually using mold.