From 6fd746215c5cb8149888314f8899daafadb8414f Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Sat, 27 Jul 2024 16:25:49 -0400
Subject: [PATCH] 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
---
 src/doc/rustc/src/targets/custom.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/src/doc/rustc/src/targets/custom.md b/src/doc/rustc/src/targets/custom.md
index a67cb10fc75a8..852bbfbfa7959 100644
--- a/src/doc/rustc/src/targets/custom.md
+++ b/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.