## 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
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],