From 35fb54fa499074112a9e0391cab7583a14698209 Mon Sep 17 00:00:00 2001
From: Christian Robles <8890471+roblesch@users.noreply.github.com>
Date: Thu, 22 Aug 2024 16:08:04 -0700
Subject: [PATCH] Use lld for rustdoc on Linux in config_fast_builds.toml
 (#14839)

# Objective

Running `cargo ci` on Fedora 40 causes a system crash due to many `ld`
processes consuming all available memory when performing doc tests.

## Solution

This PR extends #13553.

- Add reference to #12207 in the CI sections of `CONTRIBUTING.md` and
`config_fast_builds.toml`.
- Add sample `rustdocflags` configurations for `lld` and `mold` to
`config_fast_builds.toml` for Linux.

## Testing

Crashing configuration

- config.toml
  ```
  [target.x86_64-unknown-linux-gnu]
  linker = "clang"
  rustflags = ["-Clink-arg=-fuse-ld=lld"]

  [alias]
  ci = "run --package ci --"
  ```
- Test command
  `cargo ci`

Working configuration

- config.toml
  ```
  [target.x86_64-unknown-linux-gnu]
  linker = "clang"
  rustflags = ["-Clink-arg=-fuse-ld=lld"]
  rustdocflags = ["-Clink-arg=-fuse-ld=lld"]

  [alias]
  ci = "run --package ci --"
  ```
- Test command
  `cargo ci`
---
 .cargo/config_fast_builds.toml | 11 ++++++++++-
 CONTRIBUTING.md                |  2 +-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/.cargo/config_fast_builds.toml b/.cargo/config_fast_builds.toml
index ddb5ca2656..ea6cacee2a 100644
--- a/.cargo/config_fast_builds.toml
+++ b/.cargo/config_fast_builds.toml
@@ -83,12 +83,21 @@ rustflags = [
   # - Ubuntu: `sudo apt-get install mold clang`
   # - Fedora: `sudo dnf install mold clang`
   # - Arch: `sudo pacman -S mold clang`
-  # "-Clink-arg=-fuse-ld=/usr/bin/mold",
+  # "-Clink-arg=-fuse-ld=mold",
 
   # Nightly
   # "-Zshare-generics=y",
   # "-Zthreads=0",
 ]
+# Some systems may experience linker performance issues when running doc tests.
+# See https://github.com/bevyengine/bevy/issues/12207 for details.
+rustdocflags = [
+  # LLD linker
+  "-Clink-arg=-fuse-ld=lld",
+
+  # Mold linker
+  # "-Clink-arg=-fuse-ld=mold",
+]
 
 [target.x86_64-apple-darwin]
 rustflags = [
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 95f162bd46..e961ed14c6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -423,7 +423,7 @@ If you're new to Bevy, here's the workflow we use:
 2. Make your changes in a local clone of your fork, typically in its own new branch.
    1. Try to split your work into separate commits, each with a distinct purpose. Be particularly mindful of this when responding to reviews so it's easy to see what's changed.
    2. Tip: [You can set up a global `.gitignore` file](https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files#configuring-ignored-files-for-all-repositories-on-your-computer) to exclude your operating system/text editor's special/temporary files. (e.g. `.DS_Store`, `thumbs.db`, `*~`, `*.swp` or `*.swo`) This allows us to keep the `.gitignore` file in the repo uncluttered.
-3. To test CI validations locally, run the `cargo run -p ci` command. This will run most checks that happen in CI, but can take some time. You can also run sub-commands to iterate faster depending on what you're contributing:
+3. To test CI validations locally, run the `cargo run -p ci` command. This will run most checks that happen in CI, but can take some time. Some systems may experience [linker performance issues when running doc tests](https://github.com/bevyengine/bevy/issues/12207). You can also run sub-commands to iterate faster depending on what you're contributing:
     * `cargo run -p ci -- lints` - to run formatting and clippy.
     * `cargo run -p ci -- test` - to run tests.
     * `cargo run -p ci -- doc` - to run doc tests and doc checks.