From 68fd542827d5ef404da6c20b5031d4f6835450db Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 16:22:18 -0700 Subject: [PATCH 01/23] Unwrap link --- src/items/external-blocks.md | 120 ++++++++++------------------------- 1 file changed, 33 insertions(+), 87 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index afe6d1945f..52dace9a22 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -209,52 +209,37 @@ r[items.extern.attributes.link] ### The `link` attribute r[items.extern.attributes.link.intro] -The *`link` attribute* specifies the name of a native library that the -compiler should link with for the items within an `extern` block. +The *`link` attribute* specifies the name of a native library that the compiler should link with for the items within an `extern` block. r[items.extern.attributes.link.syntax] -It uses the [MetaListNameValueStr] syntax to specify its inputs. The `name` key is the -name of the native library to link. The `kind` key is an optional value which -specifies the kind of library with the following possible values: +It uses the [MetaListNameValueStr] syntax to specify its inputs. The `name` key is the name of the native library to link. The `kind` key is an optional value which specifies the kind of library with the following possible values: r[items.extern.attributes.link.dylib] -- `dylib` --- Indicates a dynamic library. This is the default if `kind` is not - specified. +- `dylib` --- Indicates a dynamic library. This is the default if `kind` is not specified. r[items.extern.attributes.link.static] - `static` --- Indicates a static library. r[items.extern.attributes.link.framework] -- `framework` --- Indicates a macOS framework. This is only valid for macOS - targets. +- `framework` --- Indicates a macOS framework. This is only valid for macOS targets. r[items.extern.attributes.link.raw-dylib] -- `raw-dylib` --- Indicates a dynamic library where the compiler will generate - an import library to link against (see [`dylib` versus `raw-dylib`] below - for details). This is only valid for Windows targets. +- `raw-dylib` --- Indicates a dynamic library where the compiler will generate an import library to link against (see [`dylib` versus `raw-dylib`] below for details). This is only valid for Windows targets. r[items.extern.attributes.link.name-requirement] The `name` key must be included if `kind` is specified. r[items.extern.attributes.link.modifiers] -The optional `modifiers` argument is a way to specify linking modifiers for the -library to link. +The optional `modifiers` argument is a way to specify linking modifiers for the library to link. r[items.extern.attributes.link.modifiers.syntax] -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. +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. r[items.extern.attributes.link.modifiers.multiple] -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")]`. +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")]`. r[items.extern.attributes.link.wasm_import_module] -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 -not specified. +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 not specified. ```rust,ignore @@ -275,30 +260,21 @@ unsafe extern { ``` r[items.extern.attributes.link.empty-block] -It is valid to add the `link` attribute on an empty extern block. You can use -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. +It is valid to add the `link` attribute on an empty extern block. You can use 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. r[items.extern.attributes.link.modifiers.bundle] #### Linking modifiers: `bundle` r[items.extern.attributes.link.modifiers.bundle.allowed-kinds] -This modifier is only compatible with the `static` linking kind. -Using any other kind will result in a compiler error. +This modifier is only compatible with the `static` linking kind. Using any other kind will result in a compiler error. r[items.extern.attributes.link.modifiers.bundle.behavior] -When building a rlib or staticlib `+bundle` means that the native static library -will be packed into the rlib or staticlib archive, and then retrieved from there -during linking of the final binary. +When building a rlib or staticlib `+bundle` means that the native static library will be packed into the rlib or staticlib archive, and then retrieved from there during linking of the final binary. r[items.extern.attributes.link.modifiers.bundle.behavior-negative] -When building a rlib `-bundle` means that the native static library is registered as a dependency -of that rlib "by name", and object files from it are included only during linking of the final -binary, the file search by that name is also performed during final linking. \ -When building a staticlib `-bundle` means that the native static library is simply not included -into the archive and some higher level build system will need to add it later during linking of -the final binary. +When building a rlib `-bundle` means that the native static library is registered as a dependency of that rlib "by name", and object files from it are included only during linking of the final binary, the file search by that name is also performed during final linking. + +When building a staticlib `-bundle` means that the native static library is simply not included into the archive and some higher level build system will need to add it later during linking of the final binary. r[items.extern.attributes.link.modifiers.bundle.no-effect] This modifier has no effect when building other targets like executables or dynamic libraries. @@ -306,25 +282,21 @@ This modifier has no effect when building other targets like executables or dyna r[items.extern.attributes.link.modifiers.bundle.default] The default for this modifier is `+bundle`. -More implementation details about this modifier can be found in -[`bundle` documentation for rustc]. +More implementation details about this modifier can be found in [`bundle` documentation for rustc]. r[items.extern.attributes.link.modifiers.whole-archive] #### Linking modifiers: `whole-archive` r[items.extern.attributes.link.modifiers.whole-archive.allowed-kinds] -This modifier is only compatible with the `static` linking kind. -Using any other kind will result in a compiler error. +This modifier is only compatible with the `static` linking kind. Using any other kind will result in a compiler error. r[items.extern.attributes.link.modifiers.whole-archive.behavior] -`+whole-archive` means that the static library is linked as a whole archive -without throwing any object files away. +`+whole-archive` means that the static library is linked as a whole archive without throwing any object files away. r[items.extern.attributes.link.modifiers.whole-archive.default] The default for this modifier is `-whole-archive`. -More implementation details about this modifier can be found in -[`whole-archive` documentation for rustc]. +More implementation details about this modifier can be found in [`whole-archive` documentation for rustc]. r[items.extern.attributes.link.modifiers.verbatim] ### Linking modifiers: `verbatim` @@ -333,75 +305,49 @@ r[items.extern.attributes.link.modifiers.verbatim.allowed-kinds] This modifier is compatible with all linking kinds. r[items.extern.attributes.link.modifiers.verbatim.behavior] -`+verbatim` means that rustc itself won't add any target-specified library prefixes or suffixes -(like `lib` or `.a`) to the library name, and will try its best to ask for the same thing from the -linker. +`+verbatim` means that rustc itself won't add any target-specified library prefixes or suffixes (like `lib` or `.a`) to the library name, and will try its best to ask for the same thing from the linker. r[items.extern.attributes.link.modifiers.verbatim.behavior-negative] -`-verbatim` means that rustc will either add a target-specific prefix and suffix to the library -name before passing it to linker, or won't prevent linker from implicitly adding it. +`-verbatim` means that rustc will either add a target-specific prefix and suffix to the library name before passing it to linker, or won't prevent linker from implicitly adding it. r[items.extern.attributes.link.modifiers.verbatim.default] The default for this modifier is `-verbatim`. -More implementation details about this modifier can be found in -[`verbatim` documentation for rustc]. +More implementation details about this modifier can be found in [`verbatim` documentation for rustc]. r[items.extern.attributes.link.kind-raw-dylib] #### `dylib` versus `raw-dylib` r[items.extern.attributes.link.kind-raw-dylib.intro] -On Windows, linking against a dynamic library requires that an import library -is provided to the linker: this is a special static library that declares all -of the symbols exported by the dynamic library in such a way that the linker -knows that they have to be dynamically loaded at runtime. +On Windows, linking against a dynamic library requires that an import library is provided to the linker: this is a special static library that declares all of the symbols exported by the dynamic library in such a way that the linker knows that they have to be dynamically loaded at runtime. r[items.extern.attributes.link.kind-raw-dylib.import] -Specifying `kind = "dylib"` instructs the Rust compiler to link an import -library based on the `name` key. The linker will then use its normal library -resolution logic to find that import library. Alternatively, specifying -`kind = "raw-dylib"` instructs the compiler to generate an import library -during compilation and provide that to the linker instead. +Specifying `kind = "dylib"` instructs the Rust compiler to link an import library based on the `name` key. The linker will then use its normal library resolution logic to find that import library. Alternatively, specifying `kind = "raw-dylib"` instructs the compiler to generate an import library during compilation and provide that to the linker instead. r[items.extern.attributes.link.kind-raw-dylib.platform-specific] -`raw-dylib` is only supported on Windows. Using it when targeting other -platforms will result in a compiler error. +`raw-dylib` is only supported on Windows. Using it when targeting other platforms will result in a compiler error. r[items.extern.attributes.link.import_name_type] #### The `import_name_type` key r[items.extern.attributes.link.import_name_type.intro] -On x86 Windows, names of functions are "decorated" (i.e., have a specific prefix -and/or suffix added) to indicate their calling convention. For example, a -`stdcall` calling convention function with the name `fn1` that has no arguments -would be decorated as `_fn1@0`. However, the [PE Format] does also permit names -to have no prefix or be undecorated. Additionally, the MSVC and GNU toolchains -use different decorations for the same calling conventions which means, by -default, some Win32 functions cannot be called using the `raw-dylib` link kind -via the GNU toolchain. +On x86 Windows, names of functions are "decorated" (i.e., have a specific prefix and/or suffix added) to indicate their calling convention. For example, a `stdcall` calling convention function with the name `fn1` that has no arguments would be decorated as `_fn1@0`. However, the [PE Format] does also permit names to have no prefix or be undecorated. Additionally, the MSVC and GNU toolchains use different decorations for the same calling conventions which means, by default, some Win32 functions cannot be called using the `raw-dylib` link kind via the GNU toolchain. r[items.extern.attributes.link.import_name_type.values] -To allow for these differences, when using the `raw-dylib` link kind you may -also specify the `import_name_type` key with one of the following values to -change how functions are named in the generated import library: - -* `decorated`: The function name will be fully-decorated using the MSVC - toolchain format. -* `noprefix`: The function name will be decorated using the MSVC toolchain - format, but skipping the leading `?`, `@`, or optionally `_`. +To allow for these differences, when using the `raw-dylib` link kind you may also specify the `import_name_type` key with one of the following values to change how functions are named in the generated import library: + +* `decorated`: The function name will be fully-decorated using the MSVC toolchain format. +* `noprefix`: The function name will be decorated using the MSVC toolchain format, but skipping the leading `?`, `@`, or optionally `_`. * `undecorated`: The function name will not be decorated. r[items.extern.attributes.link.import_name_type.default] -If the `import_name_type` key is not specified, then the function name will be -fully-decorated using the target toolchain's format. +If the `import_name_type` key is not specified, then the function name will be fully-decorated using the target toolchain's format. r[items.extern.attributes.link.import_name_type.variables] -Variables are never decorated and so the `import_name_type` key has no effect on -how they are named in the generated import library. +Variables are never decorated and so the `import_name_type` key has no effect on how they are named in the generated import library. r[items.extern.attributes.link.import_name_type.platform-specific] -The `import_name_type` key is only supported on x86 Windows. Using it when -targeting other platforms will result in a compiler error. +The `import_name_type` key is only supported on x86 Windows. Using it when targeting other platforms will result in a compiler error. r[items.extern.attributes.link_name] From 7582136417e3eb2ae00552ac4e65a07ec3fdea2f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 16:26:37 -0700 Subject: [PATCH 02/23] Link "attribute" --- src/items/external-blocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 52dace9a22..a37b859a0d 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -209,7 +209,7 @@ r[items.extern.attributes.link] ### The `link` attribute r[items.extern.attributes.link.intro] -The *`link` attribute* specifies the name of a native library that the compiler should link with for the items within an `extern` block. +The *`link` [attribute][attributes]* specifies the name of a native library that the compiler should link with for the items within an `extern` block. r[items.extern.attributes.link.syntax] It uses the [MetaListNameValueStr] syntax to specify its inputs. The `name` key is the name of the native library to link. The `kind` key is an optional value which specifies the kind of library with the following possible values: From f7b7cb8f99e8651c7341e7127b1d874f07a71228 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 16:27:29 -0700 Subject: [PATCH 03/23] Move link example to the intro --- src/items/external-blocks.md | 37 ++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index a37b859a0d..e50c84a005 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -211,6 +211,25 @@ r[items.extern.attributes.link] r[items.extern.attributes.link.intro] The *`link` [attribute][attributes]* specifies the name of a native library that the compiler should link with for the items within an `extern` block. +> [!EXAMPLE] +> +> ```rust,ignore +> #[link(name = "crypto")] +> unsafe extern { +> // … +> } +> +> #[link(name = "CoreFoundation", kind = "framework")] +> unsafe extern { +> // … +> } +> +> #[link(wasm_import_module = "foo")] +> unsafe extern { +> // … +> } +> ``` + r[items.extern.attributes.link.syntax] It uses the [MetaListNameValueStr] syntax to specify its inputs. The `name` key is the name of the native library to link. The `kind` key is an optional value which specifies the kind of library with the following possible values: @@ -241,24 +260,6 @@ Specifying multiple `modifiers` arguments in a single `link` attribute, or multi r[items.extern.attributes.link.wasm_import_module] 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 not specified. - -```rust,ignore -#[link(name = "crypto")] -unsafe extern { - // … -} - -#[link(name = "CoreFoundation", kind = "framework")] -unsafe extern { - // … -} - -#[link(wasm_import_module = "foo")] -unsafe extern { - // … -} -``` - r[items.extern.attributes.link.empty-block] It is valid to add the `link` attribute on an empty extern block. You can use 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. From b92fde205952e8f7c995132c26fffb398517987f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 16:51:39 -0700 Subject: [PATCH 04/23] Fix wrong heading depth for `verbatim` --- src/items/external-blocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index e50c84a005..d8fdc67f3c 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -300,7 +300,7 @@ The default for this modifier is `-whole-archive`. More implementation details about this modifier can be found in [`whole-archive` documentation for rustc]. r[items.extern.attributes.link.modifiers.verbatim] -### Linking modifiers: `verbatim` +#### Linking modifiers: `verbatim` r[items.extern.attributes.link.modifiers.verbatim.allowed-kinds] This modifier is compatible with all linking kinds. From 2f57b0ac80f58789af306bcdaff97d19a7ea523f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 16:52:51 -0700 Subject: [PATCH 05/23] Rework items.extern.attributes.link.syntax The old text was missing some keys. This adds the keys as a list, with some more explicit organization. --- src/items/external-blocks.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index d8fdc67f3c..51826d20b8 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -231,7 +231,24 @@ The *`link` [attribute][attributes]* specifies the name of a native library that > ``` r[items.extern.attributes.link.syntax] -It uses the [MetaListNameValueStr] syntax to specify its inputs. The `name` key is the name of the native library to link. The `kind` key is an optional value which specifies the kind of library with the following possible values: +The `link` attribute uses the [MetaListNameValueStr] syntax to specify its inputs. It accepts the following keys: + +- [`name`][items.extern.attributes.link.name] --- the name of the native library to link. +- [`kind`][items.extern.attributes.link.kinds] --- the kind of library. +- [`modifiers`][items.extern.attributes.link.modifiers] --- modifiers that change the behavior of how the library is linked. +- [`wasm_import_module`][items.extern.attributes.link.wasm_import_module] --- specifies the WebAssembly module name. +- [`import_name_type`][items.extern.attributes.link.import_name_type] --- on x86 Windows, this changes how functions are named. + +r[items.extern.attributes.link.name] +#### The `name` key + + + +r[items.extern.attributes.link.name.requirement] +The `name` key must be included unless `wasm_import_module` is used. + +r[items.extern.attributes.link.kinds] +#### The `kind` key r[items.extern.attributes.link.dylib] - `dylib` --- Indicates a dynamic library. This is the default if `kind` is not specified. @@ -245,10 +262,10 @@ r[items.extern.attributes.link.framework] r[items.extern.attributes.link.raw-dylib] - `raw-dylib` --- Indicates a dynamic library where the compiler will generate an import library to link against (see [`dylib` versus `raw-dylib`] below for details). This is only valid for Windows targets. -r[items.extern.attributes.link.name-requirement] -The `name` key must be included if `kind` is specified. - r[items.extern.attributes.link.modifiers] +#### The `modifiers` key + +r[items.extern.attributes.link.modifiers.intro] The optional `modifiers` argument is a way to specify linking modifiers for the library to link. r[items.extern.attributes.link.modifiers.syntax] @@ -258,6 +275,9 @@ r[items.extern.attributes.link.modifiers.multiple] 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")]`. r[items.extern.attributes.link.wasm_import_module] +#### The `wasm_import_module` key + +r[items.extern.attributes.link.wasm_import_module.behavior] 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 not specified. r[items.extern.attributes.link.empty-block] From bb5a85f685829cdb69bee98936c0b026b6b77548 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 16:53:19 -0700 Subject: [PATCH 06/23] Move items.extern.attributes.link.empty-block It was in the wrong section. --- src/items/external-blocks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 51826d20b8..4f260209ab 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -239,6 +239,9 @@ The `link` attribute uses the [MetaListNameValueStr] syntax to specify its input - [`wasm_import_module`][items.extern.attributes.link.wasm_import_module] --- specifies the WebAssembly module name. - [`import_name_type`][items.extern.attributes.link.import_name_type] --- on x86 Windows, this changes how functions are named. +r[items.extern.attributes.link.empty-block] +It is valid to add the `link` attribute on an empty extern block. You can use 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. + r[items.extern.attributes.link.name] #### The `name` key @@ -280,9 +283,6 @@ r[items.extern.attributes.link.wasm_import_module] r[items.extern.attributes.link.wasm_import_module.behavior] 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 not specified. -r[items.extern.attributes.link.empty-block] -It is valid to add the `link` attribute on an empty extern block. You can use 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. - r[items.extern.attributes.link.modifiers.bundle] #### Linking modifiers: `bundle` From a174401dbc177e8588343e4ecbe7f22767a34af5 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 17:40:30 -0700 Subject: [PATCH 07/23] Add ABI to the example There is a warning without it. --- src/items/external-blocks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 4f260209ab..5ad5b85f60 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -215,17 +215,17 @@ The *`link` [attribute][attributes]* specifies the name of a native library that > > ```rust,ignore > #[link(name = "crypto")] -> unsafe extern { +> unsafe extern "C" { > // … > } > > #[link(name = "CoreFoundation", kind = "framework")] -> unsafe extern { +> unsafe extern "C" { > // … > } > > #[link(wasm_import_module = "foo")] -> unsafe extern { +> unsafe extern "C" { > // … > } > ``` From d0881620939968cab48aee7e0e4f4e787d3df9f5 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 17:40:47 -0700 Subject: [PATCH 08/23] Clarify that link names cannot be repeated --- src/items/external-blocks.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 5ad5b85f60..d96f1e22c7 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -239,6 +239,8 @@ The `link` attribute uses the [MetaListNameValueStr] syntax to specify its input - [`wasm_import_module`][items.extern.attributes.link.wasm_import_module] --- specifies the WebAssembly module name. - [`import_name_type`][items.extern.attributes.link.import_name_type] --- on x86 Windows, this changes how functions are named. +None of the keys may be specified more than once. + r[items.extern.attributes.link.empty-block] It is valid to add the `link` attribute on an empty extern block. You can use 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. From 75631e94f54c7cdedcb6c9cc6017d66f8921a6b5 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 17:41:08 -0700 Subject: [PATCH 09/23] Add link allowed-positions and duplicates --- src/items/external-blocks.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index d96f1e22c7..1a9c36b09a 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -241,6 +241,15 @@ The `link` attribute uses the [MetaListNameValueStr] syntax to specify its input None of the keys may be specified more than once. +r[items.extern.attributes.link.allowed-positions] +The `link` attribute may be applied to [`extern` blocks]. + +> [!NOTE] +> `rustc` currently warns in other positions, but this may be rejected in the future. + +r[items.extern.attributes.link.duplicates] +The `link` attribute may be specified multiple times, and the corresponding linking instructions for each attribute will be passed to the linker. + r[items.extern.attributes.link.empty-block] It is valid to add the `link` attribute on an empty extern block. You can use 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. @@ -456,3 +465,4 @@ restrictions as [regular function parameters]. [unwind-behavior]: functions.md#unwinding [value namespace]: ../names/namespaces.md [`link_ordinal`]: items.extern.attributes.link_ordinal +[`extern` blocks]: external-blocks.md From 6016fc7eba376ffc5b13f37d0d2ea13b36eea425 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 17:42:10 -0700 Subject: [PATCH 10/23] Add link `name` intro --- src/items/external-blocks.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 1a9c36b09a..7b513c5696 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -256,7 +256,12 @@ It is valid to add the `link` attribute on an empty extern block. You can use th r[items.extern.attributes.link.name] #### The `name` key - +r[items.extern.attributes.link.name.intro] +The `name` key specifies the name of the library to link. + + + + r[items.extern.attributes.link.name.requirement] The `name` key must be included unless `wasm_import_module` is used. From 1d31f6b47202cae5dd3be980dc2f31a917c50f10 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 17:43:14 -0700 Subject: [PATCH 11/23] Rework link kind to not use a list, and add examples --- src/items/external-blocks.md | 51 +++++++++++++++++++++++++++++------- 1 file changed, 41 insertions(+), 10 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 7b513c5696..fc4ff4420b 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -234,7 +234,7 @@ r[items.extern.attributes.link.syntax] The `link` attribute uses the [MetaListNameValueStr] syntax to specify its inputs. It accepts the following keys: - [`name`][items.extern.attributes.link.name] --- the name of the native library to link. -- [`kind`][items.extern.attributes.link.kinds] --- the kind of library. +- [`kind`][items.extern.attributes.link.kind] --- the kind of library. - [`modifiers`][items.extern.attributes.link.modifiers] --- modifiers that change the behavior of how the library is linked. - [`wasm_import_module`][items.extern.attributes.link.wasm_import_module] --- specifies the WebAssembly module name. - [`import_name_type`][items.extern.attributes.link.import_name_type] --- on x86 Windows, this changes how functions are named. @@ -266,20 +266,51 @@ The `name` key specifies the name of the library to link. r[items.extern.attributes.link.name.requirement] The `name` key must be included unless `wasm_import_module` is used. -r[items.extern.attributes.link.kinds] +r[items.extern.attributes.link.kind] #### The `kind` key -r[items.extern.attributes.link.dylib] -- `dylib` --- Indicates a dynamic library. This is the default if `kind` is not specified. +r[items.extern.attributes.link.kind.intro] +The `kind` key specifies the kind of the library. -r[items.extern.attributes.link.static] -- `static` --- Indicates a static library. +r[items.extern.attributes.link.kind.dylib] +The `dylib` kind indicates a dynamic library. This is the default if `kind` is not specified. -r[items.extern.attributes.link.framework] -- `framework` --- Indicates a macOS framework. This is only valid for macOS targets. +> [!EXAMPLE] +> +> ```rust,ignore +> #[link(name = "example", kind = "dylib")] +> unsafe extern "C" {} +> ``` + +r[items.extern.attributes.link.kind.static] +The `static` kind indicates a static library. + +> [!EXAMPLE] +> +> ```rust,ignore +> #[link(name = "example", kind = "static")] +> unsafe extern "C" {} +> ``` + +r[items.extern.attributes.link.kind.framework] +The `framework` kind indicates a macOS framework. This is only valid for macOS targets. -r[items.extern.attributes.link.raw-dylib] -- `raw-dylib` --- Indicates a dynamic library where the compiler will generate an import library to link against (see [`dylib` versus `raw-dylib`] below for details). This is only valid for Windows targets. +> [!EXAMPLE] +> +> ```rust,ignore +> #[link(name = "CoreFoundation", kind = "framework")] +> unsafe extern "C" {} +> ``` + +r[items.extern.attributes.link.kind.raw-dylib] +The `raw-dylib` kind indicates a dynamic library where the compiler will generate an import library to link against (see [`dylib` versus `raw-dylib`] below for details). This is only valid for Windows targets. + +> [!EXAMPLE] +> +> ```rust,ignore +> #[link(name = "example", kind = "raw-dylib")] +> unsafe extern "C" {} +> ``` r[items.extern.attributes.link.modifiers] #### The `modifiers` key From 2f42d7bdd6a013bd121763143af792a2fd9b6544 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 17:44:21 -0700 Subject: [PATCH 12/23] Move dylib vs raw-dylib into a note block This doesn't look like behavioral rules, but more of an explanation. Also move it to the `raw-dylib` section, since it seems mostly relevant there. --- src/items/external-blocks.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index fc4ff4420b..b682e9b0e1 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -312,6 +312,13 @@ The `raw-dylib` kind indicates a dynamic library where the compiler will generat > unsafe extern "C" {} > ``` +> [!NOTE] +> ##### `dylib` versus `raw-dylib` +> +> On Windows, linking against a dynamic library requires that an import library is provided to the linker. This is a special static library that declares all of the symbols exported by the dynamic library in such a way that the linker knows that they have to be dynamically loaded at runtime. +> +> Specifying `kind = "dylib"` instructs the Rust compiler to link an import library based on the `name` key. The linker will then use its normal library resolution logic to find that import library. Alternatively, specifying `kind = "raw-dylib"` instructs the compiler to generate an import library during compilation and provide that to the linker instead. + r[items.extern.attributes.link.modifiers] #### The `modifiers` key @@ -383,14 +390,7 @@ The default for this modifier is `-verbatim`. More implementation details about this modifier can be found in [`verbatim` documentation for rustc]. -r[items.extern.attributes.link.kind-raw-dylib] -#### `dylib` versus `raw-dylib` - -r[items.extern.attributes.link.kind-raw-dylib.intro] -On Windows, linking against a dynamic library requires that an import library is provided to the linker: this is a special static library that declares all of the symbols exported by the dynamic library in such a way that the linker knows that they have to be dynamically loaded at runtime. -r[items.extern.attributes.link.kind-raw-dylib.import] -Specifying `kind = "dylib"` instructs the Rust compiler to link an import library based on the `name` key. The linker will then use its normal library resolution logic to find that import library. Alternatively, specifying `kind = "raw-dylib"` instructs the compiler to generate an import library during compilation and provide that to the linker instead. r[items.extern.attributes.link.kind-raw-dylib.platform-specific] `raw-dylib` is only supported on Windows. Using it when targeting other platforms will result in a compiler error. From ca242d9d358a89db04bddb0467b621135c86d020 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 17:44:41 -0700 Subject: [PATCH 13/23] Delete raw-dylib platform-specific This is already specified in the raw-dylib section. --- src/items/external-blocks.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index b682e9b0e1..a489402314 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -392,8 +392,6 @@ More implementation details about this modifier can be found in [`verbatim` docu -r[items.extern.attributes.link.kind-raw-dylib.platform-specific] -`raw-dylib` is only supported on Windows. Using it when targeting other platforms will result in a compiler error. r[items.extern.attributes.link.import_name_type] #### The `import_name_type` key From a60ac9034c703091db0d0d49e964a2d38f68c086 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 17:47:36 -0700 Subject: [PATCH 14/23] Small tweaks to link modifiers Add an example, and slight rewording. --- src/items/external-blocks.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index a489402314..f1a57862aa 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -325,11 +325,21 @@ r[items.extern.attributes.link.modifiers] r[items.extern.attributes.link.modifiers.intro] The optional `modifiers` argument is a way to specify linking modifiers for the library to link. +> [!EXAMPLE] +> +> ```rust,ignore +> #[link(name = "mylib", kind = "static", modifiers = "+whole-archive")] +> unsafe extern "C" {} +> ``` + r[items.extern.attributes.link.modifiers.syntax] 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. -r[items.extern.attributes.link.modifiers.multiple] -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")]`. +r[items.extern.attributes.link.modifiers.once] +The `modifiers` argument may only be specified once. + +r[items.extern.attributes.link.modifiers.duplicates] +Duplicate modifiers are not allowed within a `modifiers` argument. r[items.extern.attributes.link.wasm_import_module] #### The `wasm_import_module` key From 80f0af59b3183fcb1b97d1e63bb7e79d39e9de13 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 17:50:15 -0700 Subject: [PATCH 15/23] Move wasm_import_module and add example It was in the middle of the modifiers section. --- src/items/external-blocks.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index f1a57862aa..6645a642d9 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -341,12 +341,6 @@ The `modifiers` argument may only be specified once. r[items.extern.attributes.link.modifiers.duplicates] Duplicate modifiers are not allowed within a `modifiers` argument. -r[items.extern.attributes.link.wasm_import_module] -#### The `wasm_import_module` key - -r[items.extern.attributes.link.wasm_import_module.behavior] -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 not specified. - r[items.extern.attributes.link.modifiers.bundle] #### Linking modifiers: `bundle` @@ -400,8 +394,18 @@ The default for this modifier is `-verbatim`. More implementation details about this modifier can be found in [`verbatim` documentation for rustc]. +r[items.extern.attributes.link.wasm_import_module] +#### The `wasm_import_module` key +r[items.extern.attributes.link.wasm_import_module.behavior] +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 not specified. +> [!EXAMPLE] +> +> ```rust,ignore +> #[link(wasm_import_module = "foo")] +> unsafe extern "C" {} +> ``` r[items.extern.attributes.link.import_name_type] #### The `import_name_type` key From 8c772c4e62801bcf02d289269985bdba15d2eb15 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Jun 2025 18:00:14 -0700 Subject: [PATCH 16/23] Add more link examples --- src/items/external-blocks.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 6645a642d9..596b6cddbf 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -344,6 +344,13 @@ Duplicate modifiers are not allowed within a `modifiers` argument. r[items.extern.attributes.link.modifiers.bundle] #### Linking modifiers: `bundle` +> [!EXAMPLE] +> +> ```rust,ignore +> #[link(name = "mylib", kind = "static", modifiers = "+bundle")] +> unsafe extern "C" {} +> ``` + r[items.extern.attributes.link.modifiers.bundle.allowed-kinds] This modifier is only compatible with the `static` linking kind. Using any other kind will result in a compiler error. @@ -366,6 +373,13 @@ More implementation details about this modifier can be found in [`bundle` docume r[items.extern.attributes.link.modifiers.whole-archive] #### Linking modifiers: `whole-archive` +> [!EXAMPLE] +> +> ```rust,ignore +> #[link(name = "mylib", kind = "static", modifiers = "+whole-archive")] +> unsafe extern "C" {} +> ``` + r[items.extern.attributes.link.modifiers.whole-archive.allowed-kinds] This modifier is only compatible with the `static` linking kind. Using any other kind will result in a compiler error. @@ -380,6 +394,13 @@ More implementation details about this modifier can be found in [`whole-archive` r[items.extern.attributes.link.modifiers.verbatim] #### Linking modifiers: `verbatim` +> [!EXAMPLE] +> +> ```rust,ignore +> #[link(name = "mylib", kind = "static", modifiers = "+verbatim")] +> unsafe extern "C" {} +> ``` + r[items.extern.attributes.link.modifiers.verbatim.allowed-kinds] This modifier is compatible with all linking kinds. @@ -410,6 +431,13 @@ The `wasm_import_module` key may be used to specify the [WebAssembly module] nam r[items.extern.attributes.link.import_name_type] #### The `import_name_type` key +> [!EXAMPLE] +> +> ```rust,ignore +> #[link(name = "mylib", kind = "raw-dylib", import_name_type = "undecorated")] +> unsafe extern "C" {} +> ``` + r[items.extern.attributes.link.import_name_type.intro] On x86 Windows, names of functions are "decorated" (i.e., have a specific prefix and/or suffix added) to indicate their calling convention. For example, a `stdcall` calling convention function with the name `fn1` that has no arguments would be decorated as `_fn1@0`. However, the [PE Format] does also permit names to have no prefix or be undecorated. Additionally, the MSVC and GNU toolchains use different decorations for the same calling conventions which means, by default, some Win32 functions cannot be called using the `raw-dylib` link kind via the GNU toolchain. From 34581db9ec03ee673f71e4260834abb5c1ae72cf Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 30 Jun 2025 11:20:59 -0700 Subject: [PATCH 17/23] Tweak wording of `dylib` versus `raw-dylib` Dropping the use of "Rust compiler". --- src/items/external-blocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 596b6cddbf..fe54fd69e8 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -317,7 +317,7 @@ The `raw-dylib` kind indicates a dynamic library where the compiler will generat > > On Windows, linking against a dynamic library requires that an import library is provided to the linker. This is a special static library that declares all of the symbols exported by the dynamic library in such a way that the linker knows that they have to be dynamically loaded at runtime. > -> Specifying `kind = "dylib"` instructs the Rust compiler to link an import library based on the `name` key. The linker will then use its normal library resolution logic to find that import library. Alternatively, specifying `kind = "raw-dylib"` instructs the compiler to generate an import library during compilation and provide that to the linker instead. +> Specifying `kind = "dylib"` links an import library based on the `name` key. The linker will then use its normal library resolution logic to find that import library. Alternatively, specifying `kind = "raw-dylib"` generates an import library during compilation and provide that to the linker instead. r[items.extern.attributes.link.modifiers] #### The `modifiers` key From 80c6d483265bf71ab3234e2eb3af7ecc93aa10c2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 30 Jun 2025 11:32:19 -0700 Subject: [PATCH 18/23] Reword link allowed-kinds This just simplifies the wording, and links to the relevant section. --- src/items/external-blocks.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index fe54fd69e8..3a52a88915 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -352,7 +352,7 @@ r[items.extern.attributes.link.modifiers.bundle] > ``` r[items.extern.attributes.link.modifiers.bundle.allowed-kinds] -This modifier is only compatible with the `static` linking kind. Using any other kind will result in a compiler error. +The `bundle` modifier may only be used with [`static` linking]. r[items.extern.attributes.link.modifiers.bundle.behavior] When building a rlib or staticlib `+bundle` means that the native static library will be packed into the rlib or staticlib archive, and then retrieved from there during linking of the final binary. @@ -381,7 +381,7 @@ r[items.extern.attributes.link.modifiers.whole-archive] > ``` r[items.extern.attributes.link.modifiers.whole-archive.allowed-kinds] -This modifier is only compatible with the `static` linking kind. Using any other kind will result in a compiler error. +The `whole-archive` modifier may only be used with [`static` linking]. r[items.extern.attributes.link.modifiers.whole-archive.behavior] `+whole-archive` means that the static library is linked as a whole archive without throwing any object files away. @@ -542,3 +542,4 @@ restrictions as [regular function parameters]. [value namespace]: ../names/namespaces.md [`link_ordinal`]: items.extern.attributes.link_ordinal [`extern` blocks]: external-blocks.md +[`static` linking]: link.staticlib From 855103779d7f82a49136238ef5783c64e2068306 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 30 Jun 2025 11:32:39 -0700 Subject: [PATCH 19/23] Move implementation note into a note block --- src/items/external-blocks.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 3a52a88915..a986d4b8a5 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -368,7 +368,8 @@ This modifier has no effect when building other targets like executables or dyna r[items.extern.attributes.link.modifiers.bundle.default] The default for this modifier is `+bundle`. -More implementation details about this modifier can be found in [`bundle` documentation for rustc]. +> [!NOTE] +> More implementation details about this modifier can be found in [`bundle` documentation for rustc]. r[items.extern.attributes.link.modifiers.whole-archive] #### Linking modifiers: `whole-archive` @@ -389,7 +390,8 @@ r[items.extern.attributes.link.modifiers.whole-archive.behavior] r[items.extern.attributes.link.modifiers.whole-archive.default] The default for this modifier is `-whole-archive`. -More implementation details about this modifier can be found in [`whole-archive` documentation for rustc]. +> [!NOTE] +> More implementation details about this modifier can be found in [`whole-archive` documentation for rustc]. r[items.extern.attributes.link.modifiers.verbatim] #### Linking modifiers: `verbatim` @@ -413,7 +415,8 @@ r[items.extern.attributes.link.modifiers.verbatim.behavior-negative] r[items.extern.attributes.link.modifiers.verbatim.default] The default for this modifier is `-verbatim`. -More implementation details about this modifier can be found in [`verbatim` documentation for rustc]. +> [!NOTE] +> More implementation details about this modifier can be found in [`verbatim` documentation for rustc]. r[items.extern.attributes.link.wasm_import_module] #### The `wasm_import_module` key From bb5b052550760613130dc85fdd18e6177ee5490c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 30 Jun 2025 11:33:01 -0700 Subject: [PATCH 20/23] Add comma to introductory clause for clarity --- src/items/external-blocks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index a986d4b8a5..cfd30cfc19 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -355,12 +355,12 @@ r[items.extern.attributes.link.modifiers.bundle.allowed-kinds] The `bundle` modifier may only be used with [`static` linking]. r[items.extern.attributes.link.modifiers.bundle.behavior] -When building a rlib or staticlib `+bundle` means that the native static library will be packed into the rlib or staticlib archive, and then retrieved from there during linking of the final binary. +When building a rlib or staticlib, `+bundle` means that the native static library will be packed into the rlib or staticlib archive, and then retrieved from there during linking of the final binary. r[items.extern.attributes.link.modifiers.bundle.behavior-negative] -When building a rlib `-bundle` means that the native static library is registered as a dependency of that rlib "by name", and object files from it are included only during linking of the final binary, the file search by that name is also performed during final linking. +When building a rlib, `-bundle` means that the native static library is registered as a dependency of that rlib "by name", and object files from it are included only during linking of the final binary, the file search by that name is also performed during final linking. -When building a staticlib `-bundle` means that the native static library is simply not included into the archive and some higher level build system will need to add it later during linking of the final binary. +When building a staticlib, `-bundle` means that the native static library is simply not included into the archive and some higher level build system will need to add it later during linking of the final binary. r[items.extern.attributes.link.modifiers.bundle.no-effect] This modifier has no effect when building other targets like executables or dynamic libraries. From 08f24b476cb93135ce3a0eec1ded7be615f39eab Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 30 Jun 2025 11:33:13 -0700 Subject: [PATCH 21/23] Specify what "this" is --- src/items/external-blocks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index cfd30cfc19..dc75fc8aab 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -363,7 +363,7 @@ When building a rlib, `-bundle` means that the native static library is register When building a staticlib, `-bundle` means that the native static library is simply not included into the archive and some higher level build system will need to add it later during linking of the final binary. r[items.extern.attributes.link.modifiers.bundle.no-effect] -This modifier has no effect when building other targets like executables or dynamic libraries. +The `bundle` modifier has no effect when building other targets like executables or dynamic libraries. r[items.extern.attributes.link.modifiers.bundle.default] The default for this modifier is `+bundle`. From 6725b21bdfd66f04fde1d54900b24876531a9bd9 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 30 Jun 2025 11:33:30 -0700 Subject: [PATCH 22/23] Drop use of "rustc" --- src/items/external-blocks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index dc75fc8aab..b1cc2fd4a1 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -407,10 +407,10 @@ r[items.extern.attributes.link.modifiers.verbatim.allowed-kinds] This modifier is compatible with all linking kinds. r[items.extern.attributes.link.modifiers.verbatim.behavior] -`+verbatim` means that rustc itself won't add any target-specified library prefixes or suffixes (like `lib` or `.a`) to the library name, and will try its best to ask for the same thing from the linker. +`+verbatim` means that the compiler won't add any target-specified library prefixes or suffixes (like `lib` or `.a`) to the library name, and will try its best to ask for the same thing from the linker. r[items.extern.attributes.link.modifiers.verbatim.behavior-negative] -`-verbatim` means that rustc will either add a target-specific prefix and suffix to the library name before passing it to linker, or won't prevent linker from implicitly adding it. +`-verbatim` means that the compiler will either add a target-specific prefix and suffix to the library name before passing it to linker, or won't prevent linker from implicitly adding it. r[items.extern.attributes.link.modifiers.verbatim.default] The default for this modifier is `-verbatim`. From 24f2856548d12c0c13c50aa14c1d31682a067de3 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 7 Oct 2025 13:49:35 -0700 Subject: [PATCH 23/23] Update link for updated attribute template --- src/items/external-blocks.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index b1cc2fd4a1..98fdeff1fc 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -205,6 +205,7 @@ r[items.extern.attributes] r[items.extern.attributes.intro] The following [attributes] control the behavior of external blocks. + r[items.extern.attributes.link] ### The `link` attribute @@ -242,10 +243,10 @@ The `link` attribute uses the [MetaListNameValueStr] syntax to specify its input None of the keys may be specified more than once. r[items.extern.attributes.link.allowed-positions] -The `link` attribute may be applied to [`extern` blocks]. +The `link` attribute may only be applied to [`extern` blocks]. > [!NOTE] -> `rustc` currently warns in other positions, but this may be rejected in the future. +> `rustc` ignores use in other positions but lints against it. This may become an error in the future. r[items.extern.attributes.link.duplicates] The `link` attribute may be specified multiple times, and the corresponding linking instructions for each attribute will be passed to the linker.