From 12092cdc506db79a954fb3ecc2cdd38f5a8209aa Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 16 Sep 2025 13:21:01 -0700 Subject: [PATCH 1/3] More clearly define the default abi of an extern block This attempts to make it clearer that if the ABI string is not specified, it defaults to the "C" ABI. I felt like the existing text didn't emphasize that enough. I also took the opportunity to reword the intro to more generally explain what the ABI string does. A followup PR will further clarify some of the confusing use of the word "default" in the specific ABI definitions. --- src/items/external-blocks.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index afe6d1945..b9b28488e 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -98,14 +98,19 @@ r[items.extern.abi] ## ABI r[items.extern.abi.intro] -By default external blocks assume that the library they are calling uses the -standard C ABI on the specific platform. Other ABIs may be specified using an -`abi` string, as shown here: +The `extern` keyword can be followed by an optional ABI string. The ABI specifies the calling convention of the functions in the block. The calling convention defines a low-level interface for functions, such as how arguments are placed in registers or on the stack, how return values are passed, and who is responsible for cleaning up the stack. -```rust -// Interface to the Windows API -unsafe extern "system" { } -``` +> [!EXAMPLE] +> ```rust +> // Interface to the Windows API +> unsafe extern "system" { } +> ``` + +r[items.extern.abi.default] +If the ABI string is not specified, it defaults to `"C"`. + +> [!NOTE] +> It is recommended to always specify the ABI to make it clear which ABI is used. Future versions of Rust may make this a requirement, see [#134986](https://github.com/rust-lang/rust/issues/134986). r[items.extern.abi.standard] The following ABI strings are supported on all platforms: From d0d0612da7c8796c122c2a6466fd1288e8fff0f8 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Tue, 16 Sep 2025 23:57:19 +0000 Subject: [PATCH 2/3] Revise wording on explicit extern ABI change --- src/items/external-blocks.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index b9b28488e..e7e45cb78 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -102,15 +102,17 @@ The `extern` keyword can be followed by an optional // Interface to the Windows API. +> unsafe extern "system" { /* ... */ } > ``` r[items.extern.abi.default] If the ABI string is not specified, it defaults to `"C"`. > [!NOTE] -> It is recommended to always specify the ABI to make it clear which ABI is used. Future versions of Rust may make this a requirement, see [#134986](https://github.com/rust-lang/rust/issues/134986). +> The `extern` syntax without an explicit ABI is being phased out, so it's better to always write the ABI explicitly. +> +> For more details, see [Rust issue #134986](https://github.com/rust-lang/rust/issues/134986). r[items.extern.abi.standard] The following ABI strings are supported on all platforms: From fefcd8e7b88596a7056faf5af05f478801c1438e Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Wed, 17 Sep 2025 06:03:37 +0000 Subject: [PATCH 3/3] Add glossary entry for ABI and use it Rather than using an `abbr` tag when mentioning ABI, let's add a glossary entry for ABI and link to that. --- src/glossary.md | 10 ++++++++++ src/items/external-blocks.md | 3 ++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/src/glossary.md b/src/glossary.md index fa5edee20..fd865dcc4 100644 --- a/src/glossary.md +++ b/src/glossary.md @@ -11,6 +11,14 @@ The alignment of a value specifies what addresses values are preferred to start at. Always a power of two. References to a value must be aligned. [More][alignment]. +r[glossary.abi] +### Application binary interface (ABI) + +An *application binary interface* (ABI) defines how compiled code interacts with other compiled code. With [`extern` blocks] and [`extern fn`], *ABI strings* affect: + +- **Calling convention**: How function arguments are passed, values are returned (e.g., in registers or on the stack), and who is responsible for cleaning up the stack. +- **Unwinding**: Whether stack unwinding is allowed. For example, the `"C-unwind"` ABI allows unwinding across the FFI boundary, while the `"C"` ABI does not. + ### Arity Arity refers to the number of arguments a function or operator takes. @@ -287,6 +295,8 @@ uninhabited type is "empty" in the sense that there are no values of the type. T example of an uninhabited type is the [never type] `!`, or an enum with no variants `enum Never { }`. Opposite of [Inhabited](#inhabited). +[`extern` blocks]: items.extern +[`extern fn`]: items.fn.extern [alignment]: type-layout.md#size-and-alignment [associated item]: #associated-item [attributes]: attributes.md diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index e7e45cb78..25a265350 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -98,7 +98,7 @@ r[items.extern.abi] ## ABI r[items.extern.abi.intro] -The `extern` keyword can be followed by an optional ABI string. The ABI specifies the calling convention of the functions in the block. The calling convention defines a low-level interface for functions, such as how arguments are placed in registers or on the stack, how return values are passed, and who is responsible for cleaning up the stack. +The `extern` keyword can be followed by an optional [ABI] string. The ABI specifies the calling convention of the functions in the block. The calling convention defines a low-level interface for functions, such as how arguments are placed in registers or on the stack, how return values are passed, and who is responsible for cleaning up the stack. > [!EXAMPLE] > ```rust @@ -479,6 +479,7 @@ r[items.extern.attributes.fn-parameters] Attributes on extern function parameters follow the same rules and restrictions as [regular function parameters]. +[ABI]: glossary.abi [PE Format]: https://learn.microsoft.com/windows/win32/debug/pe-format#import-name-type [UEFI]: https://uefi.org/specifications [WebAssembly module]: https://webassembly.github.io/spec/core/syntax/modules.html