@@ -235,15 +235,33 @@ coverage measurement. Its use is not recommended.
235
235
236
236
## link-self-contained
237
237
238
- On ` windows-gnu ` , ` linux-musl ` , and ` wasi ` targets, this flag controls whether the
239
- linker will use libraries and objects shipped with Rust instead of those in the system.
240
- It takes one of the following values:
238
+ This flag controls whether the linker will use libraries and objects shipped with Rust instead of
239
+ those in the system. It also controls which binary is used for the linker itself. This allows
240
+ overriding cases when detection fails or the user wants to use shipped libraries.
241
+
242
+ You can enable or disable the usage of any self-contained components using one of the following values:
241
243
242
244
* no value: rustc will use heuristic to disable self-contained mode if system has necessary tools.
243
245
* ` y ` , ` yes ` , ` on ` , ` true ` : use only libraries/objects shipped with Rust.
244
246
* ` n ` , ` no ` , ` off ` or ` false ` : rely on the user or the linker to provide non-Rust libraries/objects.
245
247
246
- This allows overriding cases when detection fails or user wants to use shipped libraries.
248
+ It is also possible to enable or disable specific self-contained components in a more granular way.
249
+ You can pass a comma-separated list of self-contained components, individually enabled
250
+ (` +component ` ) or disabled (` -component ` ).
251
+
252
+ Currently, only the ` linker ` granular option is stabilized, and only on the ` x86_64-unknown-linux-gnu ` target:
253
+ - ` linker ` : toggle the usage of self-contained linker binaries (linker, dlltool, and their necessary libraries)
254
+
255
+ Note that only the ` -linker ` opt-out is stable on the ` x86_64-unknown-linux-gnu ` target: ` +linker ` is
256
+ already the default on this target.
257
+
258
+ #### Implementation notes
259
+
260
+ On the ` x86_64-unknown-linux-gnu ` target, when using the default linker flavor (using ` cc ` as the
261
+ linker driver) and linker features (to try using ` lld ` ), ` rustc ` will try to use the self-contained
262
+ linker by passing a ` -B /path/to/sysroot/ ` link argument to the driver to find ` rust-lld ` in the
263
+ sysroot. For backwards-compatibility, and to limit name and ` PATH ` collisions, this is done using a
264
+ shim executable (the ` lld-wrapper ` tool) that forwards execution to the ` rust-lld ` executable itself.
247
265
248
266
## linker
249
267
@@ -256,6 +274,39 @@ Note that on Unix-like targets (for example, `*-unknown-linux-gnu` or `*-unknown
256
274
the C compiler (for example ` cc ` or ` clang ` ) is used as the "linker" here, serving as a linker driver.
257
275
It will invoke the actual linker with all the necessary flags to be able to link against the system libraries like libc.
258
276
277
+ ## linker-features
278
+
279
+ The ` -Clinker-features ` flag allows enabling or disabling specific features used during linking.
280
+
281
+ These feature flags are a flexible extension mechanism that is complementary to linker flavors,
282
+ designed to avoid the combinatorial explosion of having to create a new set of flavors for each
283
+ linker feature we'd want to use.
284
+
285
+ The flag accepts a comma-separated list of features, individually enabled (` +feature ` ) or disabled
286
+ (` -feature ` ).
287
+
288
+ Currently only one is stable, and only on the ` x86_64-unknown-linux-gnu ` target:
289
+ - ` lld ` : to toggle trying to use the lld linker, either the system-installed binary, or the self-contained
290
+ ` rust-lld ` linker (via the [ ` -Clink-self-contained=+linker ` ] ( #link-self-contained ) flag).
291
+
292
+ For example, use:
293
+ - ` -Clinker-features=+lld ` to opt into using the ` lld ` linker, when possible (see the Implementation notes below)
294
+ - ` -Clinker-features=-lld ` to opt out instead, for targets where it is configured as the default linker
295
+
296
+ Note that only the ` -lld ` opt-out is stable on the ` x86_64-unknown-linux-gnu ` target: ` +lld ` is
297
+ already the default on this target.
298
+
299
+ #### Implementation notes
300
+
301
+ On the ` x86_64-unknown-linux-gnu ` target, when using the default linker flavor (using ` cc ` as the
302
+ linker driver), ` rustc ` will try to use lld by passing a ` -fuse-ld=lld ` link argument to the driver.
303
+ ` rustc ` will also try to detect if that _ causes_ an error during linking (for example, if GCC is too
304
+ old to understand the flag, and returns an error) and will then retry linking without this argument,
305
+ as a fallback.
306
+
307
+ If the user _ also_ passes a ` -Clink-arg=-fuse-ld=$value ` , both will be given to the linker
308
+ driver but the user's will be passed last, and would generally have priority over ` rustc ` 's.
309
+
259
310
## linker-flavor
260
311
261
312
This flag controls the linker flavor used by ` rustc ` . If a linker is given with
0 commit comments