OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

manual: many fixes

Browse Source 
Mostly around attributes and language items.
This commit is contained in:
Corey Richardson 2014-03-30 08:30:25 -04:00
parent a410833a7f
commit 2eccb1d0c2
1 changed files with 170 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
src/doc/rust.md
View File

@ -611,7 +611,7 @@ Attributes on the anonymous crate module define important metadata that influenc
the behavior of the compiler.
~~~~
// Package ID
// Crate ID
#[ crate_id = "projx#2.5" ];
// Additional metadata attributes
@ -792,7 +792,7 @@ extern crate std; // equivalent to: extern crate std = "std";
extern crate ruststd = "std"; // linking to 'std' under another name
extern crate foo = "some/where/rust-foo#foo:1.0"; // a full package ID for external tools
extern crate foo = "some/where/rust-foo#foo:1.0"; // a full crate ID for external tools
~~~~
##### Use declarations
@ -1505,11 +1505,9 @@ specified name.
extern { }
~~~~
The type of a function
declared in an extern block
is `extern "abi" fn(A1, ..., An) -> R`,
where `A1...An` are the declared types of its arguments
and `R` is the decalred return type.
The type of a function declared in an extern block is `extern "abi" fn(A1,
..., An) -> R`, where `A1...An` are the declared types of its arguments and
`R` is the declared return type.
## Visibility and Privacy
@ -1680,41 +1678,43 @@ import public items from their destination, not private items.
## Attributes
~~~~ {.notrust .ebnf .gram}
attribute : '#' '[' attr_list ']' ;
attr_list : attr [ ',' attr_list ]* ;
attribute : '#' '!' ? '[' attr_list ']'
attr_list : attr [ ',' attr_list ]*
attr : ident [ '=' literal
| '(' attr_list ')' ] ? ;
| '(' attr_list ')' ] ?
~~~~
Static entities in Rust -- crates, modules and items -- may have _attributes_
applied to them. ^[Attributes in Rust are modeled on Attributes in ECMA-335,
C#]
An attribute is a general, free-form metadatum that is interpreted according to name, convention, and language and compiler version.
Attributes may appear as any of
applied to them. Attributes in Rust are modeled on Attributes in ECMA-335, C#.
An attribute is a general, free-form metadatum that is interpreted according
to name, convention, and language and compiler version. Attributes may appear
as any of:
* A single identifier, the attribute name
* An identifier followed by the equals sign '=' and a literal, providing a key/value pair
* An identifier followed by the equals sign '=' and a literal, providing a
key/value pair
* An identifier followed by a parenthesized list of sub-attribute arguments
Attributes terminated by a semi-colon apply to the entity that the attribute is declared
within. Attributes that are not terminated by a semi-colon apply to the next entity.
Attributes with a bang ("!") after the hash ("#") apply to the item that the
attribute is declared within. Attributes that do not have a bang after the
hash by a semi-colon apply to the next item.
An example of attributes:
~~~~ {.ignore}
~~~~
// General metadata applied to the enclosing module or crate.
#[license = "BSD"];
#![license = "BSD"]
// A function marked as a unit test
#[test]
fn test_foo() {
...
/* ... */
}
// A conditionally-compiled module
#[cfg(target_os="linux")]
mod bar {
...
/* ... */
}
// A lint attribute used to suppress a warning/error
@ -1727,29 +1727,85 @@ pub type int8_t = i8;
> effectively no difference between an attribute handled by a loadable syntax
> extension and the compiler.
Some significant attributes include:
### Crate-only attributes
* The `doc` attribute, for documenting code in-place.
* The `cfg` attribute, for conditional-compilation by build-configuration (see
[Conditional compilation](#conditional-compilation)).
* The `crate_id` attribute, for describing the package ID of a crate.
* The `lang` attribute, for custom definitions of traits and functions that are
known to the Rust compiler (see [Language items](#language-items)).
* The `link` attribute, for describing linkage metadata for a extern blocks.
* The `test` attribute, for marking functions as unit tests.
* The `allow`, `warn`, `forbid`, and `deny` attributes, for
controlling lint checks (see [Lint check attributes](#lint-check-attributes)).
* The `deriving` attribute, for automatically generating implementations of
certain traits.
* The `inline` attribute, for expanding functions at caller location (see
[Inline attributes](#inline-attributes)).
* The `static_assert` attribute, for asserting that a static bool is true at
compiletime.
* The `thread_local` attribute, for defining a `static mut` as a thread-local.
Note that this is only a low-level building block, and is not local to a
*task*, nor does it provide safety.
- `crate_type` - see [linkage](#linkage).
- `feature` - see [compiler features](#compiler-features).
- `no_start` - disable linking to the `native` crate, which specifies the
"start" language item.
- `no_main` - disable emitting the `main` symbol. Useful when some
other object being linked to defines `main`.
- `no_std` - disable linking to the `std` crate.
- `crate_id` - specify the this crate's crate ID.
Other attributes may be added or removed during development of the language.
### Module-only attributes
- `path` - specifies the file to load the module from. `#[path="foo.rs"] mod
bar;` is equivalent to `mod bar { /* contents of foo.rs */ }`
- `macro_escape` - macros defined in this module will be visible in the
module's parent, after this module has been included.
- `no_implicit_prelude` - disable injecting `use std::prelude::*` in this
module.
### Function-only attributes
- `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.
- `main` - indicates that this function should be passed to the entry point,
rather than the function in the crate root named `main`.
- `macro_registrar` - when using loadable syntax extensions, mark this
function as the registration point for the current crate's syntax
extensions.
### Static-only attributes
- `thread_local` - on a `static mut`, this signals that the value of this
static may change depending on the current thread. The exact consequences of
this are implementation-defined.
- `address_insignificant` - references to this static may alias with
references to other statics, potentially of unrelated type.
### FFI attributes
On an `extern` block, the following attributes are interpreted:
- `link` - indicate that a native library should be linked to for the
declarations in this block to be linked correctly. See [external
blocks](#external-blocks)
- `link_args` - specify arguments to the linker, rather than just the library
name and type. This is feature gated and the exact behavior is
implementation-defined (due to variety of linker invocation syntax).
On declarations inside an `extern` block, the following attributes are
interpreted:
- `link_name` - the name of the symbol that this function or static should be
imported as.
- `linkage` - on a static, this specifies the [linkage
type](http://llvm.org/docs/LangRef.html#linkage-types).
### Miscellaneous attributes
- `simd` - on certain tuple structs, derive the arithmetic operators, which
lower to the target's SIMD instructions, if any.
- `link_section` - on statics and functions, this specifies the section of the
object file that this item's contents will be placed into.
- `static_assert` - on statics whose type is `bool`, terminates compilation
with an error if it is not initialized to `true`.
- `repr` - on C-like enums, this sets the underlying type used for
representation. Useful for FFI.
- `no_mangle` - on any item, do not apply the standard name mangling. Set the
symbol for this item to its identifier.
- `packed` - on structs or enums, eliminate any padding that would be used to
align fields.
- `unsafe_destructor` - allow implementations of the "drop" language item
where the type it is implemented for does not implement the "send" language
item.
- `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.
- `macro_export` - export a macro for cross-crate usage.
### Conditional compilation
@ -1791,9 +1847,7 @@ one of `foo` and `bar` to be defined (this resembles in the disjunctive normal
form). Additionally, one can reverse a condition by enclosing it in a
`not(...)`, like e. g. `#[cfg(not(target_os = "win32"))]`.
To pass a configuration option which triggers a `#[cfg(identifier)]` one can use
`rustc --cfg identifier`. In addition to that, the following configurations are
pre-defined by the compiler:
The following configurations must be defined by the implementation:
* `target_arch = "..."`. Target CPU architecture, such as `"x86"`, `"x86_64"`
`"mips"`, or `"arm"`.
@ -1805,8 +1859,8 @@ pre-defined by the compiler:
* `target_os = "..."`. Operating system of the target, examples include
`"win32"`, `"macos"`, `"linux"`, `"android"` or `"freebsd"`.
* `target_word_size = "..."`. Target word size in bits. This is set to `"32"`
for 32-bit CPU targets, and likewise set to `"64"` for 64-bit CPU targets.
* `test`. Only set in test builds (`rustc --test`).
for targets with 32-bit pointers, and likewise set to `"64"` for 64-bit
pointers.
* `unix`. See `target_family`.
* `windows`. See `target_family`.
@ -1823,7 +1877,7 @@ For any lint check `C`:
* `allow(C)` overrides the check for `C` so that violations will go
unreported,
* `forbid(C)` is the same as `deny(C)`, but also forbids uses of
`allow(C)` within the entity.
`allow(C)` within the attribute.
The lint checks supported by the compiler can be found via `rustc -W help`,
along with their default settings.
@ -1881,11 +1935,11 @@ mod m3 {
### Language items
Some primitive Rust operations are defined in Rust code,
rather than being implemented directly in C or assembly language.
The definitions of these operations have to be easy for the compiler to find.
The `lang` attribute makes it possible to declare these operations.
For example, the `str` module in the Rust standard library defines the string equality function:
Some primitive Rust operations are defined in Rust code, rather than being
implemented directly in C or assembly language. The definitions of these
operations have to be easy for the compiler to find. The `lang` attribute
makes it possible to declare these operations. For example, the `str` module
in the Rust standard library defines the string equality function:
~~~~ {.ignore}
#[lang="str_eq"]
@ -1900,16 +1954,23 @@ when generating calls to the string equality function.
A complete list of the built-in language items follows:
#### Traits
#### Built-in Traits
`const`
: Cannot be mutated.
`owned`
: Are uniquely owned.
`durable`
: Contain references.
`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.
`share`
: Able to be safely shared between tasks when aliased.
`drop`
: Have finalizers.
: Have destructors.
#### Operators
These language items are traits:
`add`
: Elements can be added (for example, integers and floats).
`sub`
@ -1940,17 +2001,54 @@ A complete list of the built-in language items follows:
: Elements can be compared for equality.
`ord`
: Elements have a partial ordering.
`deref`
: `*` can be applied, yielding a reference to another type
`deref_mut`
: `*` can be applied, yielding a mutable reference to another type
#### Operations
These are functions:
`str_eq`
: Compare two strings for equality.
: Compare two strings (`&str`) for equality.
`uniq_str_eq`
: Compare two owned strings for equality.
`annihilate`
: Destroy a box before freeing it.
`log_type`
: Generically print a string representation of any type.
: Compare two owned strings (`~str`) for equality.
`strdup_uniq`
: Return a new unique string
containing a copy of the contents of a unique string.
#### Types
`unsafe`
: A type whose contents can be mutated through an immutable reference
`type_id`
: The type returned by the `type_id` intrinsic.
#### 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
`no_copy_bound`
: This type does not implement "copy", even if eligible
`no_share_bound`
: This type does not implement "share", even if eligible
`managed_bound`
: This type implements "managed"
`fail_`
: Abort the program with an error.
`fail_bounds_check`
@ -1963,15 +2061,6 @@ A complete list of the built-in language items follows:
: Allocate memory on the managed heap.
`free`
: Free memory that was allocated on the managed heap.
`borrow_as_imm`
: Create an immutable reference to a mutable value.
`return_to_mut`
: Release a reference created with `return_to_mut`
`check_not_borrowed`
: Fail if a value has existing references to it.
`strdup_uniq`
: Return a new unique string
containing a copy of the contents of a unique string.
> **Note:** This list is likely to become out of date. We should auto-generate it
> from `librustc/middle/lang_items.rs`.
@ -2039,6 +2128,7 @@ Supported traits for `deriving` are:
* `Show`, to format a value using the `{}` formatter.
### Stability
One can indicate the stability of an API using the following attributes:
* `deprecated`: This item should no longer be used, e.g. it has been
@ -2101,10 +2191,10 @@ necessarily ready for every-day use. These features are often of "prototype
quality" or "almost production ready", but may not be stable enough to be
considered a full-fleged language feature.
For this reason, rust recognizes a special crate-level attribute of the form:
For this reason, Rust recognizes a special crate-level attribute of the form:
~~~~ {.ignore}
#[feature(feature1, feature2, feature3)]
#![feature(feature1, feature2, feature3)]
~~~~
This directive informs the compiler that the feature list: `feature1`,
@ -2112,7 +2202,7 @@ This directive informs the compiler that the feature list: `feature1`,
crate-level, not at a module-level. Without this directive, all features are
considered off, and using the features will result in a compiler error.
The currently implemented features of the compiler are:
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