From 0fc5e6dbf0f500fabd38653aa87f9d721d59b3b8 Mon Sep 17 00:00:00 2001 From: Vadim Petrochenkov Date: Tue, 15 Feb 2022 21:14:18 +0800 Subject: [PATCH] Document native library modifier syntax and the `whole-archive` modifier specifically --- src/items/external-blocks.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 9ad100fbd..84f8046f2 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -125,6 +125,15 @@ specifies the kind of library with the following possible values: The `name` key must be included if `kind` is specified. +The optional `modifiers` argument is a way to specify linking modifiers for the +library to link. +Modifiers are specified as a comma-delimited string with each modifier prefixed +with either a `+` or `-` to indicate that the modifier is enabled or disabled, +respectively. +Specifying multiple `modifiers` arguments in a single `link` attribute, +or multiple identical modifiers in the same `modifiers` argument is not currently supported. \ +Example: `#[link(name = "mylib", kind = "static", modifiers = "+whole-archive")`. + The `wasm_import_module` key may be used to specify the [WebAssembly module] name for the items within an `extern` block when importing symbols from the host environment. The default module name is `env` if `wasm_import_module` is @@ -153,6 +162,16 @@ this to satisfy the linking requirements of extern blocks elsewhere in your code (including upstream crates) instead of adding the attribute to each extern block. +#### Linking modifiers: `whole-archive` + +This modifier is only compatible with the `static` linking kind. +Using any other kind will result in a compiler error. + +`+whole-archive` means that the static library is linked as a whole archive +without throwing any object files away. + +More implementation details about this modifier can be found in [documentation for rustc]. + ### The `link_name` attribute The `link_name` attribute may be specified on declarations inside an `extern` @@ -186,3 +205,4 @@ restrictions as [regular function parameters]. [_Visibility_]: ../visibility-and-privacy.md [attributes]: ../attributes.md [regular function parameters]: functions.md#attributes-on-function-parameters +[documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-whole-archive