Merge pull request #361 from japaric/used

document #[used]

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)

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

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