rustc-book: Document `-C relocation-model`

src/doc/rustc/src/codegen-options/index.md

@@ -319,11 +319,46 @@ to a valid `.profdata` file. See the chapter on
 
 ## relocation-model
 
-This option lets you choose which
-[relocation](https://en.wikipedia.org/wiki/Relocation_\(computing\)) model to
-use.
+This option controls generation of
+[position-independent code (PIC)](https://en.wikipedia.org/wiki/Position-independent_code).
 
-To find the valid options for this flag, run `rustc --print relocation-models`.
+Supported values for this option are:
+
+#### Primary relocation models
+
+- `static` - non-relocatable code, machine instructions may use absolute addressing modes.
+
+- `pic` - fully relocatable position independent code,
+machine instructions need to use relative addressing modes.  
+Equivalent to the "uppercase" `-fPIC` or `-fPIE` options in other compilers,
+depending on the produced crate types.  
+This is the default model for majority of supported targets.
+
+#### Special relocation models
+
+- `dynamic-no-pic` - relocatable external references, non-relocatable code.  
+Only makes sense on Darwin and is rarely used.  
+If StackOverflow tells you to use this as an opt-out of PIC or PIE, don't believe it,
+use `-C relocation-model=static` instead.
+- `ropi`, `rwpi` and `ropi-rwpi` - relocatable code and read-only data, relocatable read-write data,
+and combination of both, respectively.  
+Only makes sense for certain embedded ARM targets.
+- `default` - relocation model default to the current target.  
+Only makes sense as an override for some other explicitly specified relocation model
+previously set on the command line.
+
+Supported values can also be discovered by running `rustc --print relocation-models`.
+
+#### Linking effects
+
+In addition to codegen effects, `relocation-model` has effects during linking.
+
+If the relocation model is `pic` and the current target supports position-independent executables
+(PIE), the linker will be instructed (`-pie`) to produce one.  
+If the target doesn't support both position-independent and statically linked executables,
+then `-C target-feature=+crt-static` "wins" over `-C relocation-model=pic`,
+and the linker is instructed (`-static`) to produce a statically linked
+but not position-independent executable.
 
 ## remark
 

src/librustc_session/options.rs

@@ -706,7 +706,8 @@ fn parse_src_file_hash(slot: &mut Option<SourceFileHashAlgorithm>, v: Option<&st
     profile_use: Option<PathBuf> = (None, parse_opt_pathbuf, [TRACKED],
         "use the given `.profdata` file for profile-guided optimization"),
     relocation_model: Option<RelocModel> = (None, parse_relocation_model, [TRACKED],
-        "choose the relocation model to use (`rustc --print relocation-models` for details)"),
+        "control generation of position-independent code (PIC) \
+        (`rustc --print relocation-models` for details)"),
     remark: Passes = (Passes::Some(Vec::new()), parse_passes, [UNTRACKED],
         "print remarks for these optimization passes (space separated, or \"all\")"),
     rpath: bool = (false, parse_bool, [UNTRACKED],