Merge pull request #2268 from xizheyin/issue-137421

Add issue link for explaining that why rustc_private linker fails

2 files changed, 56 insertions, 0 deletions

diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index ce74c741b39..a090f96f3f8 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -124,6 +124,7 @@
 - [rustc_driver and rustc_interface](./rustc-driver/intro.md)
     - [Example: Type checking](./rustc-driver/interacting-with-the-ast.md)
     - [Example: Getting diagnostics](./rustc-driver/getting-diagnostics.md)
+    - [Remarks on perma-unstable features](./rustc-driver/remarks-on-perma-unstable-features.md)
 - [Errors and Lints](diagnostics.md)
     - [Diagnostic and subdiagnostic structs](./diagnostics/diagnostic-structs.md)
     - [Translation](./diagnostics/translation.md)
diff --git a/src/doc/rustc-dev-guide/src/rustc-driver/remarks-on-perma-unstable-features.md b/src/doc/rustc-dev-guide/src/rustc-driver/remarks-on-perma-unstable-features.md
new file mode 100644
index 00000000000..c307adc00a0
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/rustc-driver/remarks-on-perma-unstable-features.md
@@ -0,0 +1,55 @@
+
+# Remarks on perma unstable features
+
+## `rustc_private`
+
+### Overview
+
+The `rustc_private` feature allows external crates to use compiler internals.
+
+### Using `rustc-private` with Official Toolchains
+
+When using the `rustc_private` feature with official Rust toolchains distributed via rustup, you need to install two additional components:
+
+1. **`rustc-dev`**: Provides compiler libraries
+2. **`llvm-tools`**: Provides LLVM libraries required for linking
+
+#### Installation Steps
+
+Install both components using rustup:
+
+```bash
+rustup component add rustc-dev llvm-tools
+```
+
+#### Common Error
+
+Without the `llvm-tools` component, you'll encounter linking errors like:
+
+```
+error: linking with `cc` failed: exit status: 1
+  |
+  = note: rust-lld: error: unable to find library -lLLVM-{version}
+```
+
+### Using `rustc-private` with Custom Toolchains
+
+For custom-built toolchains or environments not using rustup, additional configuration is typically required:
+
+#### Requirements
+
+- LLVM libraries must be available in your system's library search paths
+- The LLVM version must match the one used to build your Rust toolchain
+
+#### Troubleshooting Steps
+
+1. **Check LLVM installation**: Verify LLVM is installed and accessible
+2. **Configure library paths**: You may need to set environment variables:
+   ```bash
+   export LD_LIBRARY_PATH=/path/to/llvm/lib:$LD_LIBRARY_PATH
+   ```
+3. **Check version compatibility**: Ensure your LLVM version is compatible with your Rust toolchain
+
+### Additional Resources
+
+- [GitHub Issue #137421](https://github.com/rust-lang/rust/issues/137421): Explains that `rustc_private` linker failures often occur because `llvm-tools` is not installed