From 6370f3e1481b71707ef17c42e2363e1e12fc9d28 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 2 Jun 2025 17:08:50 -0700 Subject: [PATCH 1/6] Unwrap used --- src/abi.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/abi.md b/src/abi.md index 750d7814b1..6fef9d05c7 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 7b537f551cd7bfab271f037691f9fd441859316b Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 2 Jun 2025 17:13:21 -0700 Subject: [PATCH 2/6] 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 6fef9d05c7..81b75ba314 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. @@ -145,7 +145,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 4ae0ea700290be50b3de2739b7ca83df07c12e86 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 2 Jun 2025 17:14:10 -0700 Subject: [PATCH 3/6] 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 81b75ba314..f49d3b1fba 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 97c7d7df76736e9d9d22238024e729689d70ccba Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 2 Jun 2025 17:21:12 -0700 Subject: [PATCH 4/6] 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 f49d3b1fba..66eb46cd0b 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 64b1403bc894e3b1081dafdcfffa06a13a56c339 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 22 Sep 2025 13:18:25 -0700 Subject: [PATCH 5/6] 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 66eb46cd0b..949650aabd 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 From f737c4de11dd57efd22279842f35eb8565200d06 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Mon, 27 Apr 2026 05:41:29 +0000 Subject: [PATCH 6/6] Revise `used` attribute text Let's revise the text and example a bit, mostly to tighten things up. Notably, the behavior of `rustc` and therefore the output of `nm -C` has changed since this example was originally written. We've made the necessary changes to the example and to the output. --- src/abi.md | 56 ++++++++++++++++++++++++------------------------------ 1 file changed, 25 insertions(+), 31 deletions(-) diff --git a/src/abi.md b/src/abi.md index 949650aabd..0ddd93b88f 100644 --- a/src/abi.md +++ b/src/abi.md @@ -14,59 +14,52 @@ r[abi.used] ## The `used` attribute 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. +The *`used` [attribute]* forces a [static] to be kept in the output object file (.o, .rlib, etc., excluding final binaries) even if it's never used or referenced by any other item in the crate. The linker, however, is still free to remove it. > [!EXAMPLE] -> This example that shows under what conditions the compiler keeps a `static` item in the output object file. -> > ```rust -> // foo.rs +> // lib.rs > -> // This is kept because of `#[used]`: +> // This is kept because of `#[used]`. > #[used] -> static FOO: u32 = 0; +> static S1: u8 = 0; > -> // This is removable because it is unused: +> // This is removable because it's unused. > #[allow(dead_code)] -> static BAR: u32 = 0; -> -> // This is kept because it is publicly reachable: -> pub static BAZ: u32 = 0; +> static S2: u8 = 0; > -> // This is kept because it is referenced by a public, reachable function: -> static QUUX: u32 = 0; +> // This is kept because it's publicly reachable. +> pub static S3: u8 = 0; > -> pub fn quux() -> &'static u32 { -> &QUUX -> } -> -> // This is removable because it is referenced by a private, unused (dead) function: -> static CORGE: u32 = 0; +> // This is kept because it's referenced by a publicly +> // reachable function. +> static S4: u8 = 0; +> #[unsafe(no_mangle)] pub fn f4() -> &'static u8 { &S4 } > +> // This is removable because it's referenced only by a +> // private, unused (dead) function. +> static S5: u8 = 0; > #[allow(dead_code)] -> fn corge() -> &'static u32 { -> &CORGE -> } +> fn f5() -> &'static u8 { &S5 } > ``` > > ```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 +> $ rustc -O --emit=obj --crate-type=rlib lib.rs +> $ LC_ALL=C nm -C lib.o +> 0000000000000000 R lib::S1 +> 0000000000000000 R lib::S3 +> 0000000000000000 r lib::S4 +> 0000000000000000 T f4 > ``` r[abi.used.syntax] The `used` attribute uses the [MetaWord] syntax. r[abi.used.allowed-positions] -The `used` attribute may only be applied to [`static` items][items.static]. +The `used` attribute may only be applied to [`static` items]. r[abi.used.duplicates] -The `used` attribute may be used any number of times on a form. +Only the first use of `used` on an item has effect. > [!NOTE] > `rustc` lints against any use following the first. @@ -164,4 +157,5 @@ r[abi.export_name.edition2024] [external blocks]: items/external-blocks.md [function]: items/functions.md [item]: items.md +[`static` items]: items.static [static]: items/static-items.md