diff options
| -rw-r--r-- | src/doc/rustc/src/codegen-options/index.md | 59 | ||||
| -rw-r--r-- | src/doc/unstable-book/src/compiler-flags/codegen-options.md | 8 | ||||
| -rw-r--r-- | src/doc/unstable-book/src/compiler-flags/linker-features.md | 35 |
3 files changed, 59 insertions, 43 deletions
diff --git a/src/doc/rustc/src/codegen-options/index.md b/src/doc/rustc/src/codegen-options/index.md index bb109adf76f..07eafdf4c4c 100644 --- a/src/doc/rustc/src/codegen-options/index.md +++ b/src/doc/rustc/src/codegen-options/index.md @@ -235,15 +235,33 @@ coverage measurement. Its use is not recommended. ## link-self-contained -On `windows-gnu`, `linux-musl`, and `wasi` targets, this flag controls whether the -linker will use libraries and objects shipped with Rust instead of those in the system. -It takes one of the following values: +This flag controls whether the linker will use libraries and objects shipped with Rust instead of +those in the system. It also controls which binary is used for the linker itself. This allows +overriding cases when detection fails or the user wants to use shipped libraries. + +You can enable or disable the usage of any self-contained components using one of the following values: * no value: rustc will use heuristic to disable self-contained mode if system has necessary tools. * `y`, `yes`, `on`, `true`: use only libraries/objects shipped with Rust. * `n`, `no`, `off` or `false`: rely on the user or the linker to provide non-Rust libraries/objects. -This allows overriding cases when detection fails or user wants to use shipped libraries. +It is also possible to enable or disable specific self-contained components in a more granular way. +You can pass a comma-separated list of self-contained components, individually enabled +(`+component`) or disabled (`-component`). + +Currently, only the `linker` granular option is stabilized, and only on the `x86_64-unknown-linux-gnu` target: +- `linker`: toggle the usage of self-contained linker binaries (linker, dlltool, and their necessary libraries) + +Note that only the `-linker` opt-out is stable on the `x86_64-unknown-linux-gnu` target: `+linker` is +already the default on this target. + +#### Implementation notes + +On the `x86_64-unknown-linux-gnu` target, when using the default linker flavor (using `cc` as the +linker driver) and linker features (to try using `lld`), `rustc` will try to use the self-contained +linker by passing a `-B /path/to/sysroot/` link argument to the driver to find `rust-lld` in the +sysroot. For backwards-compatibility, and to limit name and `PATH` collisions, this is done using a +shim executable (the `lld-wrapper` tool) that forwards execution to the `rust-lld` executable itself. ## linker @@ -256,6 +274,39 @@ Note that on Unix-like targets (for example, `*-unknown-linux-gnu` or `*-unknown the C compiler (for example `cc` or `clang`) is used as the "linker" here, serving as a linker driver. It will invoke the actual linker with all the necessary flags to be able to link against the system libraries like libc. +## linker-features + +The `-Clinker-features` flag allows enabling or disabling specific features used during linking. + +These feature flags are a flexible extension mechanism that is complementary to linker flavors, +designed to avoid the combinatorial explosion of having to create a new set of flavors for each +linker feature we'd want to use. + +The flag accepts a comma-separated list of features, individually enabled (`+feature`) or disabled +(`-feature`). + +Currently only one is stable, and only on the `x86_64-unknown-linux-gnu` target: +- `lld`: to toggle trying to use the lld linker, either the system-installed binary, or the self-contained + `rust-lld` linker (via the [`-Clink-self-contained=+linker`](#link-self-contained) flag). + +For example, use: +- `-Clinker-features=+lld` to opt into using the `lld` linker, when possible (see the Implementation notes below) +- `-Clinker-features=-lld` to opt out instead, for targets where it is configured as the default linker + +Note that only the `-lld` opt-out is stable on the `x86_64-unknown-linux-gnu` target: `+lld` is +already the default on this target. + +#### Implementation notes + +On the `x86_64-unknown-linux-gnu` target, when using the default linker flavor (using `cc` as the +linker driver), `rustc` will try to use lld by passing a `-fuse-ld=lld` link argument to the driver. +`rustc` will also try to detect if that _causes_ an error during linking (for example, if GCC is too +old to understand the flag, and returns an error) and will then retry linking without this argument, +as a fallback. + +If the user _also_ passes a `-Clink-arg=-fuse-ld=$value`, both will be given to the linker +driver but the user's will be passed last, and would generally have priority over `rustc`'s. + ## linker-flavor This flag controls the linker flavor used by `rustc`. If a linker is given with diff --git a/src/doc/unstable-book/src/compiler-flags/codegen-options.md b/src/doc/unstable-book/src/compiler-flags/codegen-options.md index cc51554706d..f927e5c439c 100644 --- a/src/doc/unstable-book/src/compiler-flags/codegen-options.md +++ b/src/doc/unstable-book/src/compiler-flags/codegen-options.md @@ -51,10 +51,10 @@ instead of those in the system. The stable boolean values for this flag are coar - `mingw`: other MinGW libs and Windows import libs Out of the above self-contained linking components, `linker` is the only one currently implemented -(beyond parsing the CLI options). +(beyond parsing the CLI options) and stabilized. It refers to the LLD linker, built from the same LLVM revision used by rustc (named `rust-lld` to avoid naming conflicts), that is distributed via `rustup` with the compiler (and is used by default -for the wasm targets). One can also opt-in to use it by combining this flag with an appropriate -linker flavor: for example, `-Clinker-flavor=gnu-lld-cc -Clink-self-contained=+linker` will use the -toolchain's `rust-lld` as the linker. +for the wasm targets). One can also opt into using it by combining this flag with the appropriate +linker feature: for example, `-Clinker-features=+lld -Clink-self-contained=+linker` will use the +toolchain's `rust-lld` as the linker instead of the system's lld with `-Clinker-features=+lld` only. diff --git a/src/doc/unstable-book/src/compiler-flags/linker-features.md b/src/doc/unstable-book/src/compiler-flags/linker-features.md deleted file mode 100644 index 643fcf7c6d7..00000000000 --- a/src/doc/unstable-book/src/compiler-flags/linker-features.md +++ /dev/null @@ -1,35 +0,0 @@ -# `linker-features` - --------------------- - -The `-Zlinker-features` compiler flag allows enabling or disabling specific features used during -linking, and is intended to be stabilized under the codegen options as `-Clinker-features`. - -These feature flags are a flexible extension mechanism that is complementary to linker flavors, -designed to avoid the combinatorial explosion of having to create a new set of flavors for each -linker feature we'd want to use. - -For example, this design allows: -- default feature sets for principal flavors, or for specific targets. -- flavor-specific features: for example, clang offers automatic cross-linking with `--target`, which - gcc-style compilers don't support. The *flavor* is still a C/C++ compiler, and we don't want to - multiply the number of flavors for this use-case. Instead, we can have a single `+target` feature. -- umbrella features: for example, if clang accumulates more features in the future than just the - `+target` above. That could be modeled as `+clang`. -- niche features for resolving specific issues: for example, on Apple targets the linker flag - implementing the `as-needed` native link modifier (#99424) is only possible on sufficiently recent - linker versions. -- still allows for discovery and automation, for example via feature detection. This can be useful - in exotic environments/build systems. - -The flag accepts a comma-separated list of features, individually enabled (`+features`) or disabled -(`-features`), though currently only one is exposed on the CLI: -- `lld`: to toggle using the lld linker, either the system-installed binary, or the self-contained - `rust-lld` linker. - -As described above, this list is intended to grow in the future. - -One of the most common uses of this flag will be to toggle self-contained linking with `rust-lld` on -and off: `-Clinker-features=+lld -Clink-self-contained=+linker` will use the toolchain's `rust-lld` -as the linker. Inversely, `-Clinker-features=-lld` would opt out of that, if the current target had -self-contained linking enabled by default. |