mirror
/
rustc-dev-guide
mirror of https://github.com/rust-lang/rustc-dev-guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rewrap stability.md to column 79

This commit is contained in:
Ross MacArthur 2019-12-22 17:20:48 +02:00 committed by Who? Me?!
parent 3190f2a1e4
commit 01158c3620
1 changed files with 42 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
src/stability.md
View File

@ -1,30 +1,32 @@
# Stability attributes # Stability attributes
This section is about the stability attributes and schemes that allow stable APIs to use unstable This section is about the stability attributes and schemes that allow stable
APIs internally in the rustc standard library. APIs to use unstable APIs internally in the rustc standard library.
For instructions on stabilizing a language feature see For instructions on stabilizing a language feature see [Stabilizing
[Stabilizing Features](./stabilization_guide.md). Features](./stabilization_guide.md).
## unstable ## unstable
The `#[unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")]` attribute explicitly The `#[unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")]`
marks an item as unstable. Items that are marked as "unstable" cannot be used attribute explicitly marks an item as unstable. Items that are marked as
without a corresponding `#![feature]` attribute on the crate, even on a "unstable" cannot be used without a corresponding `#![feature]` attribute on
nightly compiler. This restriction only applies across crate boundaries, unstable the crate, even on a nightly compiler. This restriction only applies across
items may be used within the crate they are defined. crate boundaries, unstable items may be used within the crate they are defined.
The `unstable` attribute infects all sub-items, where the attribute doesn't have to be The `unstable` attribute infects all sub-items, where the attribute doesn't
reapplied. So if you apply this to a module, all items in the module will be unstable. have to be reapplied. So if you apply this to a module, all items in the module
will be unstable.
You can make specific sub-items stable by using the `#[stable]` attribute on them. You can make specific sub-items stable by using the `#[stable]` attribute on
The stability scheme works similarly to how `pub` works. You can have public functions of them. The stability scheme works similarly to how `pub` works. You can have
nonpublic modules and you can have stable functions in unstable modules or vice versa. public functions of nonpublic modules and you can have stable functions in
unstable modules or vice versa.
Note, however, that due to a [rustc bug], stable items inside unstable modules Note, however, that due to a [rustc bug], stable items inside unstable modules
*are* available to stable code in that location! So, for example, stable code *are* available to stable code in that location! So, for example, stable code
can import `core::intrinsics::transmute` even though `intrinsics` is an unstable can import `core::intrinsics::transmute` even though `intrinsics` is an
module. Thus, this kind of nesting should be avoided when possible. unstable module. Thus, this kind of nesting should be avoided when possible.
The `unstable` attribute may also have the `soft` value, which makes it a The `unstable` attribute may also have the `soft` value, which makes it a
future-incompatible deny-by-default lint instead of a hard error. This is used future-incompatible deny-by-default lint instead of a hard error. This is used
@ -35,29 +37,32 @@ prevents breaking dependencies by leveraging Cargo's lint capping.
## stable ## stable
The `#[stable(feature = "foo", "since = "1.420.69")]` attribute explicitly marks an item as The `#[stable(feature = "foo", "since = "1.420.69")]` attribute explicitly
stabilized. To do this, follow the instructions in marks an item as stabilized. To do this, follow the instructions in
[Stabilizing Features](./stabilization_guide.md). [Stabilizing Features](./stabilization_guide.md).
Note that stable functions may use unstable things in their body. Note that stable functions may use unstable things in their body.
## allow_internal_unstable ## allow_internal_unstable
Macros, compiler desugarings and `const fn`s expose their bodies to the call site. To Macros, compiler desugarings and `const fn`s expose their bodies to the call
work around not being able to use unstable things in the standard library's macros, there's the site. To work around not being able to use unstable things in the standard
`#[allow_internal_unstable(feature1, feature2)]` attribute that whitelists the given features for library's macros, there's the `#[allow_internal_unstable(feature1, feature2)]`
usage in stable macros or `const fn`s. attribute that whitelists the given features for usage in stable macros or
`const fn`s.
Note that `const fn`s are even more special in this regard. You can't just whitelist any feature, Note that `const fn`s are even more special in this regard. You can't just
the features need an implementation in `qualify_min_const_fn.rs`. For example the `const_fn_union` whitelist any feature, the features need an implementation in
feature gate allows accessing fields of unions inside stable `const fn`s. The rules for when it's `qualify_min_const_fn.rs`. For example the `const_fn_union` feature gate allows
ok to use such a feature gate are that behavior matches the runtime behavior of the same code accessing fields of unions inside stable `const fn`s. The rules for when it's
(see also [this blog post][blog]). This means that you may not create a ok to use such a feature gate are that behavior matches the runtime behavior of
`const fn` that e.g. transmutes a memory address to an integer, because the addresses of things the same code (see also [this blog post][blog]). This means that you may not
are nondeterministic and often unknown at compile-time. create a `const fn` that e.g. transmutes a memory address to an integer,
because the addresses of things are nondeterministic and often unknown at
compile-time.
Always ping @oli-obk, @RalfJung, and @Centril if you are adding more `allow_internal_unstable` Always ping @oli-obk, @RalfJung, and @Centril if you are adding more
attributes to any `const fn` `allow_internal_unstable` attributes to any `const fn`
## staged_api ## staged_api
@ -83,13 +88,13 @@ item must also have a `stable` or `unstable` attribute.
)] )]
``` ```
The `suggestion` field is optional. If given, it should be a string that can The `suggestion` field is optional. If given, it should be a string that can be
be used as a machine-applicable suggestion to correct the warning. This is used as a machine-applicable suggestion to correct the warning. This is
typically used when the identifier is renamed, but no other significant typically used when the identifier is renamed, but no other significant changes
changes are necessary. are necessary.
Another difference from the `deprecated` attribute is that the `since` field Another difference from the `deprecated` attribute is that the `since` field is
is actually checked against the current version of `rustc`. If `since` is in a actually checked against the current version of `rustc`. If `since` is in a
future version, then the `deprecated_in_future` lint is triggered which is future version, then the `deprecated_in_future` lint is triggered which is
default `allow`, but most of the standard library raises it to a warning with default `allow`, but most of the standard library raises it to a warning with
`#![warn(deprecated_in_future)]`. `#![warn(deprecated_in_future)]`.