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 rust-lang#128280

src/doc/rustc/src/targets/custom.md

@@ -15,3 +15,14 @@ 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 for a file named
+   `TARGET.json`.
+
+If none of these methods find a target, an error is thrown.