diff --git a/src/SUMMARY.md b/src/SUMMARY.md index bf479ca31..3cbae0714 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -111,6 +111,8 @@ - [Constant Evaluation](const_eval.md) +- [Application Binary Interface](abi.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..451bdda1b --- /dev/null +++ b/src/abi.md @@ -0,0 +1,62 @@ +# Application Binary Interface (ABI) + +This section documents features that affect the ABI of the compiled output of +a crate. + +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. + +## The `used` attribute + +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` 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 +``` + +[`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 32d555c9e..caaffacd3 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 @@ -629,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