From 5133f0a7f8e1148168f0895f4752f19d5175745f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 2 Jun 2025 17:08:50 -0700 Subject: [PATCH 1/5] Unwrap used --- src/abi.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/abi.md b/src/abi.md index c0f7ed78a6..42a7abae8d 100644 --- a/src/abi.md +++ b/src/abi.md @@ -13,13 +13,9 @@ r[abi.used] ## The `used` attribute r[abi.used.intro] -The *`used` attribute* can only be applied to [`static` items]. This [attribute] forces the -compiler to keep the variable in the output object file (.o, .rlib, etc. excluding final binaries) -even if the variable is not used, or referenced, by any other item in the crate. -However, the linker is still free to remove such an item. +The *`used` attribute* can only be applied to [`static` items]. This [attribute] forces the compiler to keep the variable in the output object file (.o, .rlib, etc. excluding final binaries) even if the variable is not used, or referenced, by any other item in the crate. However, the linker is still free to remove such an item. -Below is an example that shows under what conditions the compiler keeps a `static` item in the -output object file. +Below is an example that shows under what conditions the compiler keeps a `static` item in the output object file. ``` rust // foo.rs From 5a3e6211690e55d611ed973b35c5b66c400c5fff Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 2 Jun 2025 17:13:21 -0700 Subject: [PATCH 2/5] Slightly reword the used intro --- src/abi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/abi.md b/src/abi.md index 42a7abae8d..7e5e893472 100644 --- a/src/abi.md +++ b/src/abi.md @@ -13,7 +13,7 @@ r[abi.used] ## The `used` attribute r[abi.used.intro] -The *`used` attribute* can only be applied to [`static` items]. This [attribute] forces the compiler to keep the variable in the output object file (.o, .rlib, etc. excluding final binaries) even if the variable is not used, or referenced, by any other item in the crate. However, the linker is still free to remove such an item. +The *`used` [attribute]* forces a [`static` item][items.static] to be kept in the output object file (.o, .rlib, etc. excluding final binaries) even if the static is never used, or referenced, by an other item in the crate. However, the linker is still free to remove such an item. Below is an example that shows under what conditions the compiler keeps a `static` item in the output object file. @@ -131,7 +131,6 @@ r[abi.export_name.edition2024] > [!EDITION-2024] > Before the 2024 edition it is allowed to use the `export_name` attribute without the `unsafe` qualification. -[`static` items]: items/static-items.md [attribute]: attributes.md [extern functions]: items/functions.md#extern-function-qualifier [external blocks]: items/external-blocks.md From c7ba07a45cbf276fdbfd3cc73800c3d4cd1e3b65 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 2 Jun 2025 17:14:10 -0700 Subject: [PATCH 3/5] Move used example into an example block --- src/abi.md | 83 +++++++++++++++++++++++++++--------------------------- 1 file changed, 42 insertions(+), 41 deletions(-) diff --git a/src/abi.md b/src/abi.md index 7e5e893472..8d252a872d 100644 --- a/src/abi.md +++ b/src/abi.md @@ -15,47 +15,48 @@ r[abi.used] r[abi.used.intro] The *`used` [attribute]* forces a [`static` item][items.static] to be kept in the output object file (.o, .rlib, etc. excluding final binaries) even if the static is never used, or referenced, by an other item in the crate. However, the linker is still free to remove such an item. -Below is an example that shows under what conditions the compiler keeps a `static` item in the output object file. - -``` rust -// foo.rs - -// This is kept because of `#[used]`: -#[used] -static FOO: u32 = 0; - -// This is removable because it is unused: -#[allow(dead_code)] -static BAR: u32 = 0; - -// This is kept because it is publicly reachable: -pub static BAZ: u32 = 0; - -// This is kept because it is referenced by a public, reachable function: -static QUUX: u32 = 0; - -pub fn quux() -> &'static u32 { - &QUUX -} - -// This is removable because it is referenced by a private, unused (dead) function: -static CORGE: u32 = 0; - -#[allow(dead_code)] -fn corge() -> &'static u32 { - &CORGE -} -``` - -``` console -$ rustc -O --emit=obj --crate-type=rlib foo.rs - -$ nm -C foo.o -0000000000000000 R foo::BAZ -0000000000000000 r foo::FOO -0000000000000000 R foo::QUUX -0000000000000000 T foo::quux -``` +> [!EXAMPLE] +> This example that shows under what conditions the compiler keeps a `static` item in the output object file. +> +> ```rust +> // foo.rs +> +> // This is kept because of `#[used]`: +> #[used] +> static FOO: u32 = 0; +> +> // This is removable because it is unused: +> #[allow(dead_code)] +> static BAR: u32 = 0; +> +> // This is kept because it is publicly reachable: +> pub static BAZ: u32 = 0; +> +> // This is kept because it is referenced by a public, reachable function: +> static QUUX: u32 = 0; +> +> pub fn quux() -> &'static u32 { +> &QUUX +> } +> +> // This is removable because it is referenced by a private, unused (dead) function: +> static CORGE: u32 = 0; +> +> #[allow(dead_code)] +> fn corge() -> &'static u32 { +> &CORGE +> } +> ``` +> +> ```console +> $ rustc -O --emit=obj --crate-type=rlib foo.rs +> +> $ nm -C foo.o +> 0000000000000000 R foo::BAZ +> 0000000000000000 r foo::FOO +> 0000000000000000 R foo::QUUX +> 0000000000000000 T foo::quux +> ``` r[abi.no_mangle] ## The `no_mangle` attribute From 36aa4af40df94dba79f9ab3f45b747fa7f67a15e Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 2 Jun 2025 17:21:12 -0700 Subject: [PATCH 4/5] Add attribute template rules for used --- src/abi.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/abi.md b/src/abi.md index 8d252a872d..981fadfd93 100644 --- a/src/abi.md +++ b/src/abi.md @@ -58,6 +58,18 @@ The *`used` [attribute]* forces a [`static` item][items.static] to be kept in th > 0000000000000000 T foo::quux > ``` +r[abi.used.syntax] +The `used` attribute uses the [MetaWord] syntax and thus does not take any inputs. + +r[abi.used.allowed-positions] +The `used` attribute may only be applied to [`static` items][items.static]. + +r[abi.used.duplicates] +Only the first instance of `used` on an item is honored. Subsequent `used` attributes are ignored. + +> [!NOTE] +> `rustc` currently warns on subsequent duplicate `used` attributes. + r[abi.no_mangle] ## The `no_mangle` attribute From 83d0f84bd48ff506055f4a97b7952debc072154d Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 22 Sep 2025 13:18:25 -0700 Subject: [PATCH 5/5] Minor update of `used` More closely align with the template, and some minor word tweaks. --- src/abi.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/abi.md b/src/abi.md index 981fadfd93..0e6cbb29b7 100644 --- a/src/abi.md +++ b/src/abi.md @@ -9,6 +9,7 @@ See *[extern functions]* for information on specifying the ABI for exporting functions. See *[external blocks]* for information on specifying the ABI for linking external libraries. + r[abi.used] ## The `used` attribute @@ -59,16 +60,16 @@ The *`used` [attribute]* forces a [`static` item][items.static] to be kept in th > ``` r[abi.used.syntax] -The `used` attribute uses the [MetaWord] syntax and thus does not take any inputs. +The `used` attribute uses the [MetaWord] syntax. r[abi.used.allowed-positions] The `used` attribute may only be applied to [`static` items][items.static]. r[abi.used.duplicates] -Only the first instance of `used` on an item is honored. Subsequent `used` attributes are ignored. +The `used` attribute may be used any number of times on a form. > [!NOTE] -> `rustc` currently warns on subsequent duplicate `used` attributes. +> `rustc` lints against any use following the first. r[abi.no_mangle] ## The `no_mangle` attribute