rustc book: document how the RUST_TARGET_PATH variable is used

based on the module comment in
rust/compiler/rustc_target/src/spec/mod.rs

Fixes #128280

1 files changed, 13 insertions, 0 deletions

diff --git a/src/doc/rustc/src/targets/custom.md b/src/doc/rustc/src/targets/custom.md
index a67cb10fc75..a332d24c9f1 100644
--- a/src/doc/rustc/src/targets/custom.md
+++ b/src/doc/rustc/src/targets/custom.md
@@ -15,3 +15,16 @@ rustc +nightly -Z unstable-options --target=wasm32-unknown-unknown --print targe
 ```
 
 To use a custom target, see the (unstable) [`build-std` feature](../../cargo/reference/unstable.html#build-std) of `cargo`.
+
+## Custom Target Lookup Path
+
+When `rustc` is given an option `--target=TARGET` (where `TARGET` is any string), it uses the following logic:
+1. if `TARGET` is the name of a built-in target, use that
+2. if `TARGET` is a path to a file, read that file as a json target
+3. otherwise, search the colon-seperated list of directories found
+   in the `RUST_TARGET_PATH` environment variable from left to right
+   for a file named `TARGET.json`.
+
+These steps are tried in order, so if there are multple potentially valid
+interpretations for a target, whichever is found first will take priority.
+If none of these methods find a target, an error is thrown.