Skip to content

Remove unstable and 'in the future' things. #153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 5, 2017
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 6 additions & 95 deletions src/attributes.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,28 +59,17 @@ mod bar {
type int8_t = i8;
```

> **Note:** At some point in the future, the compiler will distinguish between
> language-reserved and user-available attributes. Until then, there is
> effectively no difference between an attribute handled by a loadable syntax
> extension and the compiler.

## Crate-only attributes

- `crate_name` - specify the crate's crate name.
- `crate_type` - see [linkage](linkage.html).
- `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.
- `plugin` - load a list of named crates as compiler plugins, e.g.
`#![plugin(foo, bar)]`. Optional arguments for each plugin,
i.e. `#![plugin(foo(... args ...))]`, are provided to the plugin's
registrar function. The `plugin` feature gate is required to use
this attribute.
- `recursion_limit` - Sets the maximum depth for potentially
infinitely-recursive compile-time operations like
auto-dereference or macro expansion. The default is
Expand All @@ -107,25 +96,12 @@ type int8_t = i8;

- `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][plugin], 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.
- `test` - indicates that this function is a test function, to only be compiled
in case of `--test`.
- `ignore` - indicates that this test function is disabled.
- `should_panic` - indicates that this test function should panic, inverting the success condition.
- `cold` - The function is unlikely to be executed, so optimize it (and calls
to it) differently.
- `naked` - The function utilizes a custom ABI or custom inline ASM that requires
epilogue and prologue to be skipped.

## 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.

## FFI attributes

Expand Down Expand Up @@ -171,6 +147,10 @@ On `struct`s:
remove any padding between fields (note that this is very fragile and may
break platforms which require aligned access).

On `union`s:

- `repr` - Same as per `struct`.

## Macro-related attributes

- `macro_use` on a `mod` — macros defined in this module will be visible in the
Expand Down Expand Up @@ -204,33 +184,7 @@ macro scope.
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.
- `simd` - on certain tuple structs, derive the arithmetic operators, which
lower to the target's SIMD instructions, if any; the `simd` feature gate
is necessary to use this attribute.
- `unsafe_destructor_blind_to_params` - on `Drop::drop` method, asserts that the
destructor code (and all potential specializations of that code) will
never attempt to read from nor write to any references with lifetimes
that come in via generic parameters. This is a constraint we cannot
currently express via the type system, and therefore we rely on the
programmer to assert that it holds. Adding this to a Drop impl causes
the associated destructor to be considered "uninteresting" by the
Drop-Check rule, and thus it can help sidestep data ordering
constraints that would otherwise be introduced by the Drop-Check
rule. Such sidestepping of the constraints, if done incorrectly, can
lead to undefined behavior (in the form of reading or writing to data
outside of its dynamic extent), and thus this attribute has the word
"unsafe" in its name. To use this, the
`unsafe_destructor_blind_to_params` feature gate must be enabled.
- `doc` - Doc comments such as `/// foo` are equivalent to `#[doc = "foo"]`.
- `rustc_on_unimplemented` - Write a custom note to be shown along with the error
when the trait is found to be unimplemented on a type.
You may use format arguments like `{T}`, `{A}` to correspond to the
types at the point of use corresponding to the type parameters of the
trait of the same name. `{Self}` will be replaced with the type that is supposed
to implement the trait but doesn't. You can also use the trait's name which will
be replaced with the full path for the trait, for example for the trait `Foo` in
module `Bar`, `{Foo}` can be used and will show up as `Bar::Foo`.
To use this, the `on_unimplemented` feature gate must be enabled.
- `must_use` - on structs and enums, will warn if a value of this type isn't used or
assigned to a variable. You may also include an optional message by using
`#[must_use = "message"]` which will be given alongside the warning.
Expand Down Expand Up @@ -403,15 +357,6 @@ pub 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.
The set of language items is currently considered unstable. A complete
list of the built-in language items will be added in the future.

### Inline attributes

The inline attribute suggests that the compiler should place a copy of
Expand Down Expand Up @@ -461,40 +406,6 @@ impl<T: PartialEq> PartialEq for Foo<T> {
}
```

You can implement `derive` for your own type through [procedural
macros](procedural-macros.html).

### Compiler Features

Certain aspects of Rust may be implemented in the compiler, but they're not
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-fledged language feature.

For this reason, Rust recognizes a special crate-level attribute of the form:

```rust,ignore
#![feature(feature1, feature2, feature3)]
```

This directive informs the compiler that the feature list: `feature1`,
`feature2`, and `feature3` should all be enabled. This is only recognized at a
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 reference compiler are documented in
[The Unstable Book].

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 a
feature is decided to be removed from the language, errors will be issued (if
there isn't a parser error first). The directive in this case is no longer
necessary, and it's likely that existing code will break if the feature isn't
removed.

If an unknown feature is found in a directive, it results in a compiler error.
An unknown feature is one which has never been recognized by the compiler.
You can implement `derive` for your own type through [procedural macros].

[The Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/
[unstable book plugin]: ../unstable-book/language-features/plugin.html#lint-plugins
[procedural macros]: procedural-macros.html
4 changes: 1 addition & 3 deletions src/identifiers.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
> &nbsp;&nbsp; &nbsp;&nbsp; [`a`-`z` `A`-`Z`]&nbsp;[`a`-`z` `A`-`Z` `0`-`9` `_`]<sup>\*</sup>
> &nbsp;&nbsp; | `_` [`a`-`z` `A`-`Z` `0`-`9` `_`]<sup>+</sup>

An identifier is any nonempty ASCII[^non_ascii_idents] string of the following form:
An identifier is any nonempty ASCII string of the following form:

Either

Expand All @@ -17,5 +17,3 @@ Or
* The first character is `_`
* The identifier is more than one character, `_` alone is not an identifier
* The remaining characters are alphanumeric or `_`

[^non_ascii_idents] Non-ASCII characters in identifiers are currently feature-gated. See [issue #28979](https://github.com/rust-lang/rust/issues/28979).
7 changes: 2 additions & 5 deletions src/macros.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,11 @@ A number of minor features of Rust are not central enough to have their own
syntax, and yet are not implementable as functions. Instead, they are given
names, and invoked through a consistent syntax: `some_extension!(...)`.

Users of `rustc` can define new macros in two ways:
Thre are two ways to define new macros:

* [Macros by Example] define new syntax in a higher-level,
declarative way.
* [Macros by Example] define new syntax in a higher-level, declarative way.
* [Procedural Macros] can be used to implement custom derive.

And one unstable way: [compiler plugins].

[Macros by Example]: macros-by-example.html
[Procedural Macros]: procedural-macros.html
[compiler plugins]: ../unstable-book/language-features/plugin.html
11 changes: 6 additions & 5 deletions src/procedural-macros.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
## Procedural Macros

"Procedural macros" are the second way to implement a macro. For now, the only
thing they can be used for is to implement derive on your own types. See
[the book][procedural macros] for a tutorial.

[procedural macros]: ../book/procedural-macros.html
*Procedural macros* allow creating syntax extensions as execution of a function.
Procedural macros can be used for is to implement custom [derive] on your own
types. See [the book][procedural macros] for a tutorial.

Procedural macros involve a few different parts of the language and its
standard libraries. First is the `proc_macro` crate, included with Rust,
Expand All @@ -21,3 +19,6 @@ pub fn hello_world(input: TokenStream) -> TokenStream

Finally, procedural macros must be in their own crate, with the `proc-macro`
crate type.

[derive]: attributes.html#derive
[procedural macros]: ../book/first-edition/procedural-macros.html
4 changes: 2 additions & 2 deletions src/type-coercions.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,8 +142,8 @@ Coercion is allowed between the following types:
- coerce_inner(`T`) = `U` where `T` is a concrete type which implements the
trait `U`.

In the future, coerce_inner will be recursively extended to tuples and
<!--In the future, coerce_inner will be recursively extended to tuples and
structs. In addition, coercions from sub-traits to super-traits will be
added. See [RFC 401] for more details.
added. See [RFC 401] for more details.-->
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should add the third point from Unsize.


* Non capturing closures to `fn` pointers
4 changes: 2 additions & 2 deletions src/types.md
Original file line number Diff line number Diff line change
Expand Up @@ -301,8 +301,8 @@ which are only assigned when the function is called) - so the value does not
need to contain an actual function pointer, and no indirection is needed when
the function is called.

There is currently no syntax that directly refers to a function item type, but
the compiler will display the type as something like `fn() {foo::<u32>}` in
There is no syntax that directly refers to a function item type, but the
compiler will display the type as something like `fn(u32) -> i32 {fn_name}` in
error messages.

Because the function item type explicitly identifies the function, the item
Expand Down