From 26d49a1f4a68299d633606cfd78d5869b06a2e07 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Wed, 20 Jun 2018 09:54:01 -0500 Subject: [PATCH 1/5] document #[used] --- src/SUMMARY.md | 3 +++ src/abi.md | 9 ++++++++ src/used.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 74 insertions(+) create mode 100644 src/abi.md create mode 100644 src/used.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index bf479ca31..6ab71e8e6 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -111,6 +111,9 @@ - [Constant Evaluation](const_eval.md) +- [Application Binary Interface](abi.md) + - [#[used]](used.md) + [Appendix: Influences](influences.md) [Appendix: As-yet-undocumented Features](undocumented.md) diff --git a/src/abi.md b/src/abi.md new file mode 100644 index 000000000..d10513a5a --- /dev/null +++ b/src/abi.md @@ -0,0 +1,9 @@ +# Application Binary Interface (ABI) + +This section documents (or will document) features that affect the ABI of a Rust program / binary, +rlib, dylib, etc. A (likely incomplete) list of such features is shown below: + +- #[used] +- #[no_mangle] +- #[link_section] +- extern "$ABI" fn diff --git a/src/used.md b/src/used.md new file mode 100644 index 000000000..8bb030aa2 --- /dev/null +++ b/src/used.md @@ -0,0 +1,62 @@ +## #[used] + +The `#[used]` attribute can only be applied to `static` variables. This attribute forces the +compiler to keep the variable in the output object file (.o, .rlib, etc.) even if the variable is +not *used*, or referenced, by any other item in the crate. Without this attribute the compiler is +free to remove variable if it's *unused*, or dead, when optimizations are enabled. + +Below is an example that shows under what conditions the compiler keeps a `static` variable in the +output object file. + +``` rust +// foo.rs + +#![feature(used)] + +// kept because of #[used] +#[used] +static FOO: u32 = 0; + +// removed because it's unused +#[allow(dead_code)] +static BAR: u32 = 0; + +// kept because it's referenced by a *public*, reachable function +pub static BAZ: u32 = 0; + +pub static QUUX: u32 = 0; + +pub fn quux() -> &'static u32 { + &QUUX +} + +// removed because it's referenced by a private, unused (dead) function +static CORGE: u32 = 0; + +#[allow(dead_code)] +fn corge() -> &'static u32 { + &CORGE +} +``` + +``` console +$ # with optimizations +$ 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 + +$ # without optimizations +$ rustc --emit=obj --crate-type=rlib foo.rs + +$ nm -C foo.o +0000000000000000 r foo::BAR +0000000000000000 R foo::BAZ +0000000000000000 r foo::FOO +0000000000000000 R foo::QUUX +0000000000000000 T foo::quux +0000000000000000 r foo::CORGE +``` From e47b2990478301d075443768dc2a8293ea2ac6b3 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Thu, 21 Jun 2018 21:40:40 -0500 Subject: [PATCH 2/5] address review comments --- src/SUMMARY.md | 1 - src/abi.md | 63 ++++++++++++++++++++++++++++++++++++++++++----- src/attributes.md | 2 ++ src/used.md | 62 ---------------------------------------------- 4 files changed, 59 insertions(+), 69 deletions(-) delete mode 100644 src/used.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 6ab71e8e6..3cbae0714 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -112,7 +112,6 @@ - [Constant Evaluation](const_eval.md) - [Application Binary Interface](abi.md) - - [#[used]](used.md) [Appendix: Influences](influences.md) diff --git a/src/abi.md b/src/abi.md index d10513a5a..bf575e8bf 100644 --- a/src/abi.md +++ b/src/abi.md @@ -1,9 +1,60 @@ # Application Binary Interface (ABI) -This section documents (or will document) features that affect the ABI of a Rust program / binary, -rlib, dylib, etc. A (likely incomplete) list of such features is shown below: +This section documents features that affect the ABI of a Rust program / binary, rlib, dylib, etc. A +list of such features is shown below: -- #[used] -- #[no_mangle] -- #[link_section] -- extern "$ABI" fn +- `#[export_name]` +- `#[link_section]` +- `#[no_mangle]` +- `#[used]` +- `extern "$ABI" fn` + +## `#[used]` + +The `#[used]` attribute can only be applied to `static` variables. This attribute forces the +compiler to keep the variable in the output object file (.o, .rlib, etc.) even if the variable is +not used, or referenced, by any other item in the crate. + +Below is an example that shows under what conditions the compiler keeps a `static` variable in the +output object file. + +``` rust +// foo.rs + +#![feature(used)] + +// kept because of #[used] +#[used] +static FOO: u32 = 0; + +// removed because it's unused +#[allow(dead_code)] +static BAR: u32 = 0; + +// kept because it's referenced by a public, reachable function +pub static BAZ: u32 = 0; + +pub static QUUX: u32 = 0; + +pub fn quux() -> &'static u32 { + &QUUX +} + +// removed because it's 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 +``` diff --git a/src/attributes.md b/src/attributes.md index 32d555c9e..d16f59b35 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -204,6 +204,8 @@ which can be used to control type layout. object file that this item's contents will be placed into. - `no_mangle` - on any item, do not apply the standard name mangling. Set the symbol for this item to its identifier. +- `used` - on statics, this forces the compiler to keep the variable in the + output object file. ### Deprecation diff --git a/src/used.md b/src/used.md deleted file mode 100644 index 8bb030aa2..000000000 --- a/src/used.md +++ /dev/null @@ -1,62 +0,0 @@ -## #[used] - -The `#[used]` attribute can only be applied to `static` variables. This attribute forces the -compiler to keep the variable in the output object file (.o, .rlib, etc.) even if the variable is -not *used*, or referenced, by any other item in the crate. Without this attribute the compiler is -free to remove variable if it's *unused*, or dead, when optimizations are enabled. - -Below is an example that shows under what conditions the compiler keeps a `static` variable in the -output object file. - -``` rust -// foo.rs - -#![feature(used)] - -// kept because of #[used] -#[used] -static FOO: u32 = 0; - -// removed because it's unused -#[allow(dead_code)] -static BAR: u32 = 0; - -// kept because it's referenced by a *public*, reachable function -pub static BAZ: u32 = 0; - -pub static QUUX: u32 = 0; - -pub fn quux() -> &'static u32 { - &QUUX -} - -// removed because it's referenced by a private, unused (dead) function -static CORGE: u32 = 0; - -#[allow(dead_code)] -fn corge() -> &'static u32 { - &CORGE -} -``` - -``` console -$ # with optimizations -$ 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 - -$ # without optimizations -$ rustc --emit=obj --crate-type=rlib foo.rs - -$ nm -C foo.o -0000000000000000 r foo::BAR -0000000000000000 R foo::BAZ -0000000000000000 r foo::FOO -0000000000000000 R foo::QUUX -0000000000000000 T foo::quux -0000000000000000 r foo::CORGE -``` From 9fd5b4d95809c1abdc48712fc3b1910e47829727 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 10 Mar 2019 18:43:04 -0700 Subject: [PATCH 3/5] Update ABI. - Address review comments. - Add links to other parts of the reference. - Remove "list of features", will move these attributes in a future PR. - Remove feature(used), not needed. - Remove `pub` from QUUX. Otherwise it is the same as BAZ. I believe this was trying to illustrate that a private static accessed from a public function counts as "used". --- src/abi.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/src/abi.md b/src/abi.md index bf575e8bf..b38fc4303 100644 --- a/src/abi.md +++ b/src/abi.md @@ -1,17 +1,15 @@ # Application Binary Interface (ABI) -This section documents features that affect the ABI of a Rust program / binary, rlib, dylib, etc. A -list of such features is shown below: +This section documents features that affect the ABI of the compiled output of +a crate. -- `#[export_name]` -- `#[link_section]` -- `#[no_mangle]` -- `#[used]` -- `extern "$ABI" fn` +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. -## `#[used]` +## The `used` attribute -The `#[used]` attribute can only be applied to `static` variables. This attribute forces the +The *`used` attribute* can only be applied to [`static` variables]. This [attribute] forces the compiler to keep the variable in the output object file (.o, .rlib, etc.) even if the variable is not used, or referenced, by any other item in the crate. @@ -21,26 +19,24 @@ output object file. ``` rust // foo.rs -#![feature(used)] - // kept because of #[used] #[used] static FOO: u32 = 0; -// removed because it's unused +// removable because it is unused #[allow(dead_code)] static BAR: u32 = 0; -// kept because it's referenced by a public, reachable function +// kept because it is referenced by a public, reachable function pub static BAZ: u32 = 0; -pub static QUUX: u32 = 0; +static QUUX: u32 = 0; pub fn quux() -> &'static u32 { &QUUX } -// removed because it's referenced by a private, unused (dead) function +// removable because it is referenced by a private, unused (dead) function static CORGE: u32 = 0; #[allow(dead_code)] @@ -58,3 +54,8 @@ $ nm -C foo.o 0000000000000000 R foo::QUUX 0000000000000000 T foo::quux ``` + +[`static` variables]: items/static-items.html +[attribute]: attributes.html +[extern functions]: items/functions.html#extern-functions +[external blocks]: items/external-blocks.html From a2f10c4a6474aab381958f0db90f39534b9a9cce Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 10 Mar 2019 19:42:28 -0700 Subject: [PATCH 4/5] Update for centril's review. --- src/abi.md | 14 +++++++------- src/attributes.md | 3 ++- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/src/abi.md b/src/abi.md index b38fc4303..05e82e1ac 100644 --- a/src/abi.md +++ b/src/abi.md @@ -9,25 +9,25 @@ linking external libraries. ## The `used` attribute -The *`used` attribute* can only be applied to [`static` variables]. This [attribute] forces the +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.) even if the variable is not used, or referenced, by any other item in the crate. -Below is an example that shows under what conditions the compiler keeps a `static` variable in the +Below is an example that shows under what conditions the compiler keeps a `static` item in the output object file. ``` rust // foo.rs -// kept because of #[used] +// This is kept because of `#[used]`: #[used] static FOO: u32 = 0; -// removable because it is unused +// This is removable because it is unused: #[allow(dead_code)] static BAR: u32 = 0; -// kept because it is referenced by a public, reachable function +// This is kept because it is referenced by a public, reachable function: pub static BAZ: u32 = 0; static QUUX: u32 = 0; @@ -36,7 +36,7 @@ pub fn quux() -> &'static u32 { &QUUX } -// removable because it is referenced by a private, unused (dead) function +// This is removable because it is referenced by a private, unused (dead) function: static CORGE: u32 = 0; #[allow(dead_code)] @@ -55,7 +55,7 @@ $ nm -C foo.o 0000000000000000 T foo::quux ``` -[`static` variables]: items/static-items.html +[`static` items]: items/static-items.html [attribute]: attributes.html [extern functions]: items/functions.html#extern-functions [external blocks]: items/external-blocks.html diff --git a/src/attributes.md b/src/attributes.md index d16f59b35..caaffacd3 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -204,7 +204,7 @@ which can be used to control type layout. object file that this item's contents will be placed into. - `no_mangle` - on any item, do not apply the standard name mangling. Set the symbol for this item to its identifier. -- `used` - on statics, this forces the compiler to keep the variable in the +- [`used`] - on statics, this forces the compiler to keep the variable in the output object file. ### Deprecation @@ -631,3 +631,4 @@ pub fn f() {} [trait or lifetime bounds]: trait-bounds.html [Expression Attributes]: expressions.html#expression-attributes [`meta` macro fragment specifier]: macros-by-example.html +[`used`]: abi.html#the-used-attribute From c31b4fa3a1a4f0dd88e1343db0e739017cf09d8c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 11 Mar 2019 10:03:17 -0700 Subject: [PATCH 5/5] Fix comment error. --- src/abi.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/abi.md b/src/abi.md index 05e82e1ac..451bdda1b 100644 --- a/src/abi.md +++ b/src/abi.md @@ -27,9 +27,10 @@ static FOO: u32 = 0; #[allow(dead_code)] static BAR: u32 = 0; -// This is kept because it is referenced by a public, reachable function: +// 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 {