Document native library modifier syntax and the whole-archive modifier specifically

Author: petrochenkov

src/items/external-blocks.md

@@ -125,6 +125,13 @@ specifies the kind of library with the following possible values:
 
 The `name` key must be included if `kind` is specified.
 
+The optional `modifiers` key 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. The last boolean value specified for a given modifier wins. \
+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 +160,22 @@ 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.
+
+This modifier translates to `--whole-archive` for `ld`-like linkers,
+to `/WHOLEARCHIVE` for `link.exe`, and to `-force_load` for `ld64`.
+The modifier does nothing for linkers that don't support it.
+
+The default for this modifier is `-whole-archive`. \
+NOTE: The default may currently be different when building dylibs for some targets,
+but it is not guaranteed.
+
 ### The `link_name` attribute
 
 The `link_name` attribute may be specified on declarations inside an `extern`