From 968d40066cbf48bedc5f66378db2345df8300679 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Rakic?= Date: Sat, 16 Dec 2023 20:01:11 +0000 Subject: [PATCH 1/4] remove unstable linker flavors from stable documentation --- src/doc/rustc/src/codegen-options/index.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/doc/rustc/src/codegen-options/index.md b/src/doc/rustc/src/codegen-options/index.md index cfbe1e09cde0c..835d052ad7a6c 100644 --- a/src/doc/rustc/src/codegen-options/index.md +++ b/src/doc/rustc/src/codegen-options/index.md @@ -249,9 +249,6 @@ flavor. Valid options are: * `gcc`: use the `cc` executable, which is typically gcc or clang on many systems. * `ld`: use the `ld` executable. * `msvc`: use the `link.exe` executable from Microsoft Visual Studio MSVC. -* `ptx`: use [`rust-ptx-linker`](https://github.com/denzp/rust-ptx-linker) - for Nvidia NVPTX GPGPU support. -* `bpf`: use [`bpf-linker`](https://github.com/alessandrod/bpf-linker) for eBPF support. * `wasm-ld`: use the [`wasm-ld`](https://lld.llvm.org/WebAssembly.html) executable, a port of LLVM `lld` for WebAssembly. * `ld64.lld`: use the LLVM `lld` executable with the [`-flavor darwin` From 8560c67e4c09b9917ea8c00ec37373ff77bb51c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Rakic?= Date: Sat, 16 Dec 2023 20:02:22 +0000 Subject: [PATCH 2/4] describe unstable linker flavors in the unstable book --- .../src/compiler-flags/codegen-options.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 src/doc/unstable-book/src/compiler-flags/codegen-options.md diff --git a/src/doc/unstable-book/src/compiler-flags/codegen-options.md b/src/doc/unstable-book/src/compiler-flags/codegen-options.md new file mode 100644 index 0000000000000..9d2e03121ef74 --- /dev/null +++ b/src/doc/unstable-book/src/compiler-flags/codegen-options.md @@ -0,0 +1,32 @@ +# Unstable codegen options + +All of these options are passed to `rustc` via the `-C` flag, short for "codegen". The flags are +stable but some of their values are individually unstable, and also require using `-Z +unstable-options` to be accepted. + +## linker-flavor + +In addition to the stable set of linker flavors, the following unstable values also exist: +- `ptx`: use [`rust-ptx-linker`](https://github.com/denzp/rust-ptx-linker) + for Nvidia NVPTX GPGPU support. +- `bpf`: use [`bpf-linker`](https://github.com/alessandrod/bpf-linker) for eBPF support. + +Additionally, a set of more precise linker flavors also exists, for example allowing targets to +declare that they use the LLD linker by default. The following values are currently unstable, and +the goal is for them to become stable, and preferred in practice over the existing stable values: +- `gnu`: unix-like linker with GNU extensions +- `gnu-lld`: `gnu` using LLD +- `gnu-cc`: `gnu` using a C/C++ compiler as the linker driver +- `gnu-lld-cc`: `gnu` using LLD and a C/C++ compiler as the linker driver +- `darwin`: unix-like linker for Apple targets +- `darwin-lld`: `darwin` using LLD +- `darwin-cc`: `darwin` using a C/C++ compiler as the linker driver +- `darwin-lld-cc`: `darwin` using LLD and a C/C++ compiler as the linker driver +- `wasm-lld`: unix-like linker for Wasm targets, with LLD +- `wasm-lld-cc`: unix-like linker for Wasm targets, with LLD and a C/C++ compiler as the linker + driver +- `unix`: basic unix-like linker for "any other Unix" targets (Solaris/illumos, L4Re, MSP430, etc), + not supported with LLD. +- `unix-cc`: `unix` using a C/C++ compiler as the linker driver +- `msvc-lld`: MSVC-style linker for Windows and UEFI, with LLD +- `em-cc`: emscripten compiler frontend, similar to `wasm-lld-cc` with a different interface From d39324b52545881f25adb1bb615045067d334654 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Rakic?= Date: Sat, 16 Dec 2023 20:19:37 +0000 Subject: [PATCH 3/4] describe unstable self-contained linking components in the unstable book --- .../src/compiler-flags/codegen-options.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) 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 9d2e03121ef74..31dfcdb199ab9 100644 --- a/src/doc/unstable-book/src/compiler-flags/codegen-options.md +++ b/src/doc/unstable-book/src/compiler-flags/codegen-options.md @@ -30,3 +30,27 @@ the goal is for them to become stable, and preferred in practice over the existi - `unix-cc`: `unix` using a C/C++ compiler as the linker driver - `msvc-lld`: MSVC-style linker for Windows and UEFI, with LLD - `em-cc`: emscripten compiler frontend, similar to `wasm-lld-cc` with a different interface + +## link-self-contained + +This flag generally controls whether the linker will use libraries and objects shipped with Rust +instead of those in the system. The stable boolean values for this flag are coarse-grained +(everything or nothing), but there exists a set of unstable values with finer-grained control, +`-Clink-self-contained` can accept a comma-separated list of components, individually enabled +(`+component`) or disabled (`-component`): +- `crto`: CRT objects (e.g. on `windows-gnu`, `musl`, `wasi` targets) +- `libc`: libc static library (e.g. on `musl`, `wasi` targets) +- `unwind`: libgcc/libunwind (e.g. on `windows-gnu`, `fuchsia`, `fortanix`, `gnullvm` targets) +- `linker`: linker, dlltool, and their necessary libraries (e.g. on `windows-gnu` and for + `rust-lld`) +- `sanitizers`: sanitizer runtime libraries +- `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). + +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. From 3006e62909c032491563528c9197e7492a86456a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9my=20Rakic?= Date: Sat, 16 Dec 2023 20:20:07 +0000 Subject: [PATCH 4/4] fix typo in stable doc codegen-options chapter --- src/doc/rustc/src/codegen-options/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/rustc/src/codegen-options/index.md b/src/doc/rustc/src/codegen-options/index.md index 835d052ad7a6c..4a4f1ae98e407 100644 --- a/src/doc/rustc/src/codegen-options/index.md +++ b/src/doc/rustc/src/codegen-options/index.md @@ -221,7 +221,7 @@ metrics. ## 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 or those in the system. +linker will use libraries and objects shipped with Rust instead of those in the system. It takes one of the following values: * no value: rustc will use heuristic to disable self-contained mode if system has necessary tools.