Immutable static items are stored in the read-only data section.
The constant value bound to a static item is, like all constant values, evaluated at compile time.
Static items have the `static` lifetime, which outlives all other lifetimes in a Rust program.
+Only values stored in the global data section (such as string constants
+and static items) can have the `static` lifetime;
+dynamically constructed values cannot safely be assigned the `static` lifetime.
Static items are declared with the `static` keyword.
A static item must have a _constant expression_ giving its definition.
- `crate_id` - specify the this crate's crate ID.
- `crate_type` - see [linkage](#linkage).
- `feature` - see [compiler features](#compiler-features).
+ - `no_builtins` - disable optimizing certain code patterns to invocations of
+ library functions that are assumed to exist
- `no_main` - disable emitting the `main` symbol. Useful when some other
object being linked to defines `main`.
- `no_start` - disable linking to the `native` crate, which specifies the
"start" language item.
- `no_std` - disable linking to the `std` crate.
- - `no_builtins` - disable optimizing certain code patterns to invocations of
- library functions that are assumed to exist
### Module-only attributes
### Function-only attributes
- - `plugin_registrar` - mark this function as the registration point for
- compiler plugins, such as loadable syntax extensions.
- `main` - indicates that this function should be passed to the entry point,
rather than the function in the crate root named `main`.
+ - `plugin_registrar` - mark this function as the registration point for
+ compiler plugins, such as loadable syntax extensions.
- `start` - indicates that this function should be used as the entry point,
overriding the "start" language item. See the "start" [language
item](#language-items) for more details.
symbol for this item to its identifier.
- `packed` - on structs or enums, eliminate any padding that would be used to
align fields.
+ - `phase` - on `extern crate` statements, allows specifying which "phase" of
+ compilation the crate should be loaded for. Currently, there are two
+ choices: `link` and `plugin`. `link` is the default. `plugin` will load the
+ crate at compile-time and use any syntax extensions or lints that the crate
+ defines. They can both be specified, `#[phase(link, plugin)]` to use a crate
+ both at runtime and compiletime.
- `repr` - on C-like enums, this sets the underlying type used for
representation. Useful for FFI. Takes one argument, which is the primitive
type this enum should be represented for, or `C`, which specifies that it
- `unsafe_no_drop_flag` - on structs, remove the flag that prevents
destructors from being run twice. Destructors might be run multiple times on
the same object with this attribute.
- - `phase` - on `extern crate` statements, allows specifying which "phase" of
- compilation the crate should be loaded for. Currently, there are two
- choices: `link` and `plugin`. `link` is the default. `plugin` will load the
- crate at compile-time and use any syntax extensions or lints that the crate
- defines. They can both be specified, `#[phase(link, plugin)]` to use a crate
- both at runtime and compiletime.
### Conditional compilation
For any lint check `C`:
- * `warn(C)` warns about violations of `C` but continues compilation,
- * `deny(C)` signals an error after encountering a violation of `C`,
* `allow(C)` overrides the check for `C` so that violations will go
unreported,
+ * `deny(C)` signals an error after encountering a violation of `C`,
* `forbid(C)` is the same as `deny(C)`, but also forbids changing the lint
- level afterwards.
+ level afterwards,
+ * `warn(C)` warns about violations of `C` but continues compilation.
The lint checks supported by the compiler can be found via `rustc -W help`,
along with their default settings.
#### Built-in Traits
+ * `copy`
+ : Types that do not move ownership when used by-value.
+ * `drop`
+ : Have destructors.
* `send`
: Able to be sent across task boundaries.
* `sized`
: Has a size known at compile time.
- * `copy`
- : Types that do not move ownership when used by-value.
* `sync`
: Able to be safely shared between tasks when aliased.
- * `drop`
- : Have destructors.
#### Operators
: Elements have a right shift operation.
* `index`
: Elements can be indexed.
+ * `index_mut`
+ : ___Needs filling in___
* `eq`
: Elements can be compared for equality.
* `ord`
* `deref_mut`
: `*` can be applied, yielding a mutable reference to another type
-
These are functions:
+ * `fn`
+ : ___Needs filling in___
+ * `fn_mut`
+ : ___Needs filling in___
+ * `fn_once`
+ : ___Needs filling in___
* `str_eq`
: Compare two strings (`&str`) for equality.
* `strdup_uniq`
#### Types
- * `unsafe`
- : A type whose contents can be mutated through an immutable reference
* `type_id`
: The type returned by the `type_id` intrinsic.
+ * `unsafe`
+ : A type whose contents can be mutated through an immutable reference
#### Marker types
These types help drive the compiler's analysis
- * `covariant_type`
- : The type parameter should be considered covariant
- * `contravariant_type`
- : The type parameter should be considered contravariant
- * `invariant_type`
- : The type parameter should be considered invariant
- * `covariant_lifetime`
- : The lifetime parameter should be considered covariant
- * `contravariant_lifetime`
- : The lifetime parameter should be considered contravariant
- * `invariant_lifetime`
- : The lifetime parameter should be considered invariant
- * `no_send_bound`
- : This type does not implement "send", even if eligible
+ * `begin_unwind`
+ : ___Needs filling in___
* `no_copy_bound`
: This type does not implement "copy", even if eligible
+ * `no_send_bound`
+ : This type does not implement "send", even if eligible
* `no_sync_bound`
: This type does not implement "sync", even if eligible
* `managed_bound`
: This type implements "managed"
-
+ * `eh_personality`
+ : ___Needs filling in___
+ * `exchange_free`
+ : Free memory that was allocated on the exchange heap.
+ * `exchange_malloc`
+ : Allocate memory on the exchange heap.
+ * `closure_exchange_malloc`
+ : ___Needs filling in___
* `fail_`
: Abort the program with an error.
* `fail_bounds_check`
: Abort the program with a bounds check error.
- * `exchange_malloc`
- : Allocate memory on the exchange heap.
- * `exchange_free`
- : Free memory that was allocated on the exchange heap.
- * `malloc`
- : Allocate memory on the managed heap.
* `free`
: Free memory that was allocated on the managed heap.
+ * `gc`
+ : ___Needs filling in___
+ * `exchange_heap`
+ : ___Needs filling in___
+ * `managed_heap`
+ : ___Needs filling in___
+ * `iterator`
+ : ___Needs filling in___
+ * `contravariant_lifetime`
+ : The lifetime parameter should be considered contravariant
+ * `covariant_lifetime`
+ : The lifetime parameter should be considered covariant
+ * `invariant_lifetime`
+ : The lifetime parameter should be considered invariant
+ * `malloc`
+ : Allocate memory on the managed heap.
+ * `opaque`
+ : ___Needs filling in___
+ * `owned_box`
+ : ___Needs filling in___
+ * `stack_exhausted`
+ : ___Needs filling in___
+ * `start`
+ : ___Needs filling in___
+ * `contravariant_type`
+ : The type parameter should be considered contravariant
+ * `covariant_type`
+ : The type parameter should be considered covariant
+ * `invariant_type`
+ : The type parameter should be considered invariant
+ * `ty_desc`
+ : ___Needs filling in___
+ * `ty_visitor`
+ : ___Needs filling in___
> **Note:** This list is likely to become out of date. We should auto-generate it
> from `librustc/middle/lang_items.rs`.
* Comparison traits: `PartialEq`, `Eq`, `PartialOrd`, `Ord`.
* Serialization: `Encodable`, `Decodable`. These require `serialize`.
* `Clone`, to create `T` from `&T` via a copy.
- * `Hash`, to iterate over the bytes in a data type.
- * `Rand`, to create a random instance of a data type.
* `Default`, to create an empty instance of a data type.
- * `Zero`, to create a zero instance of a numeric data type.
* `FromPrimitive`, to create an instance from a numeric primitive.
+ * `Hash`, to iterate over the bytes in a data type.
+ * `Rand`, to create a random instance of a data type.
* `Show`, to format a value using the `{}` formatter.
+ * `Zero`, to create a zero instance of a numeric data type.
### Stability
The currently implemented features of the reference compiler are:
- * `macro_rules` - The definition of new macros. This does not encompass
- macro-invocation, that is always enabled by default, this only
- covers the definition of new macros. There are currently
- various problems with invoking macros, how they interact with
- their environment, and possibly how they are used outside of
- location in which they are defined. Macro definitions are
- likely to change slightly in the future, so they are currently
- hidden behind this feature.
+ * `asm` - The `asm!` macro provides a means for inline assembly. This is often
+ useful, but the exact syntax for this feature along with its semantics
+ are likely to change, so this macro usage must be opted into.
+
+ * `concat_idents` - Allows use of the `concat_idents` macro, which is in many
+ ways insufficient for concatenating identifiers, and may
+ be removed entirely for something more wholsome.
+
+ * `default_type_params` - Allows use of default type parameters. The future of
+ this feature is uncertain.
* `globs` - Importing everything in a module through `*`. This is currently a
large source of bugs in name resolution for Rust, and it's not clear
whether this will continue as a feature or not. For these reasons,
the glob import statement has been hidden behind this feature flag.
- * `struct_variant` - Structural enum variants (those with named fields). It is
- currently unknown whether this style of enum variant is as
- fully supported as the tuple-forms, and it's not certain
- that this style of variant should remain in the language.
- For now this style of variant is hidden behind a feature
- flag.
+ * `intrinsics` - Allows use of the "rust-intrinsics" ABI. Compiler intrinsics
+ are inherently unstable and no promise about them is made.
- * `once_fns` - Onceness guarantees a closure is only executed once. Defining a
- closure as `once` is unlikely to be supported going forward. So
- they are hidden behind this feature until they are to be removed.
+ * `lang_items` - Allows use of the `#[lang]` attribute. Like `intrinsics`,
+ lang items are inherently unstable and no promise about
+ them is made.
- * `asm` - The `asm!` macro provides a means for inline assembly. This is often
- useful, but the exact syntax for this feature along with its semantics
- are likely to change, so this macro usage must be opted into.
+ * `link_args` - This attribute is used to specify custom flags to the linker,
+ but usage is strongly discouraged. The compiler's usage of the
+ system linker is not guaranteed to continue in the future, and
+ if the system linker is not used then specifying custom flags
+ doesn't have much meaning.
+
+ * `linkage` - Allows use of the `linkage` attribute, which is not portable.
+
+ * `log_syntax` - Allows use of the `log_syntax` macro attribute, which is a
+ nasty hack that will certainly be removed.
+
+ * `macro_rules` - The definition of new macros. This does not encompass
+ macro-invocation, that is always enabled by default, this only
+ covers the definition of new macros. There are currently
+ various problems with invoking macros, how they interact with
+ their environment, and possibly how they are used outside of
+ location in which they are defined. Macro definitions are
+ likely to change slightly in the future, so they are currently
+ hidden behind this feature.
* `managed_boxes` - Usage of `@` is gated due to many
planned changes to this feature. In the past, this has meant
now until the specification of identifiers is fully
fleshed out.
- * `thread_local` - The usage of the `#[thread_local]` attribute is experimental
- and should be seen as unstable. This attribute is used to
- declare a `static` as being unique per-thread leveraging
- LLVM's implementation which works in concert with the kernel
- loader and dynamic linker. This is not necessarily available
- on all platforms, and usage of it is discouraged (rust
- focuses more on task-local data instead of thread-local
- data).
+ * `once_fns` - Onceness guarantees a closure is only executed once. Defining a
+ closure as `once` is unlikely to be supported going forward. So
+ they are hidden behind this feature until they are to be removed.
- * `link_args` - This attribute is used to specify custom flags to the linker,
- but usage is strongly discouraged. The compiler's usage of the
- system linker is not guaranteed to continue in the future, and
- if the system linker is not used then specifying custom flags
- doesn't have much meaning.
+ * `overloaded_calls` - Allow implementing the `Fn*` family of traits on user
+ types, allowing overloading the call operator (`()`).
+ This feature may still undergo changes before being
+ stabilized.
* `phase` - Usage of the `#[phase]` attribute allows loading compiler plugins
for custom lints or syntax extensions. The implementation is considered
in need of a overhaul, and it is not clear that plugins
defined using this will continue to work.
- * `log_syntax` - Allows use of the `log_syntax` macro attribute, which is a
- nasty hack that will certainly be removed.
-
- * `trace_macros` - Allows use of the `trace_macros` macro, which is a nasty
- hack that will certainly be removed.
-
- * `concat_idents` - Allows use of the `concat_idents` macro, which is in many
- ways insufficient for concatenating identifiers, and may
- be removed entirely for something more wholsome.
-
- * `unsafe_destructor` - Allows use of the `#[unsafe_destructor]` attribute,
- which is considered wildly unsafe and will be
- obsoleted by language improvements.
-
- * `intrinsics` - Allows use of the "rust-intrinsics" ABI. Compiler intrinsics
- are inherently unstable and no promise about them is made.
-
- * `lang_items` - Allows use of the `#[lang]` attribute. Like `intrinsics`,
- lang items are inherently unstable and no promise about
- them is made.
-
- * `simd` - Allows use of the `#[simd]` attribute, which is overly simple and
- not the SIMD interface we want to expose in the long term.
-
- * `default_type_params` - Allows use of default type parameters. The future of
- this feature is uncertain.
-
* `quote` - Allows use of the `quote_*!` family of macros, which are
implemented very poorly and will likely change significantly
with a proper implementation.
- * `linkage` - Allows use of the `linkage` attribute, which is not portable.
+ * `rustc_diagnostic_macros`- A mysterious feature, used in the implementation
+ of rustc, not meant for mortals.
+
+ * `simd` - Allows use of the `#[simd]` attribute, which is overly simple and
+ not the SIMD interface we want to expose in the long term.
* `struct_inherit` - Allows using struct inheritance, which is barely
implemented and will probably be removed. Don't use this.
- * `overloaded_calls` - Allow implementing the `Fn*` family of traits on user
- types, allowing overloading the call operator (`()`).
- This feature may still undergo changes before being
- stabilized.
+ * `struct_variant` - Structural enum variants (those with named fields). It is
+ currently unknown whether this style of enum variant is as
+ fully supported as the tuple-forms, and it's not certain
+ that this style of variant should remain in the language.
+ For now this style of variant is hidden behind a feature
+ flag.
+
+ * `thread_local` - The usage of the `#[thread_local]` attribute is experimental
+ and should be seen as unstable. This attribute is used to
+ declare a `static` as being unique per-thread leveraging
+ LLVM's implementation which works in concert with the kernel
+ loader and dynamic linker. This is not necessarily available
+ on all platforms, and usage of it is discouraged (rust
+ focuses more on task-local data instead of thread-local
+ data).
+
+ * `trace_macros` - Allows use of the `trace_macros` macro, which is a nasty
+ hack that will certainly be removed.
* `unboxed_closure_sugar` - Allows using `|Foo| -> Bar` as a trait bound
meaning one of the `Fn` traits. Still
experimental.
- * `rustc_diagnostic_macros`- A mysterious feature, used in the implementation
- of rustc, not meant for mortals.
-
* `unboxed_closures` - A work in progress feature with many known bugs.
+ * `unsafe_destructor` - Allows use of the `#[unsafe_destructor]` attribute,
+ which is considered wildly unsafe and will be
+ obsoleted by language improvements.
+
If a feature is promoted to a language feature, then all existing programs will
start to receive compilation warnings about #[feature] directives which enabled
the new feature (because the directive is no longer necessary). However, if
References arise by (automatic) conversion from owning pointers, managed pointers,
or by applying the borrowing operator `&` to some other value,
including [lvalues, rvalues or temporaries](#lvalues,-rvalues-and-temporaries).
- References are written `&content`, or in some cases `&'f content` for some lifetime-variable `f`,
+ A borrow expression is written `&content`.
+
+ A reference type is written `&'f type` for some lifetime-variable `f`,
+ or just `&type` when the lifetime can be elided;
for example `&int` means a reference to an integer.
Copying a reference is a "shallow" operation:
it involves only copying the pointer itself.
projects / rust.git / commitdiff