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

Expand on stability documentation.

This commit is contained in:
Eric Huss 2019-10-09 09:50:07 -07:00 committed by Who? Me?!
parent 38a7872b0b
commit 226b37eaa0
1 changed files with 78 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
src/stability.md
View File

@ -3,13 +3,18 @@
This section is about the stability attributes and schemes that allow stable 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 Features](./stabilization_guide.md).
# unstable
## unstable
The `#[unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")]` attribute explicitly
marks an item as unstable. This infects all sub-items, where the attribute doesn't have to be
marks an item as unstable. Items that are marked as "unstable" cannot be used
without a corresponding `#![feature]` attribute on the crate, even on a
nightly compiler. This restriction only applies across 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
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.
@ -21,9 +26,14 @@ Note, however, that due to a [rustc bug], stable items inside unstable modules
can import `core::intrinsics::transmute` even though `intrinsics` is an 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
future-incompatible deny-by-default lint instead of a hard error. This is used
by the `bench` attribute which was accidentally accepted in the past. This
prevents breaking dependencies by leveraging Cargo's lint capping.
[rustc bug]: https://github.com/rust-lang/rust/issues/15702
# stable
## stable
The `#[stable(feature = "foo", "since = "1.420.69")]` attribute explicitly marks an item as
stabilized. To do this, follow the instructions in
@ -31,7 +41,7 @@ stabilized. To do this, follow the instructions in
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
work around not being able to use unstable things in the standard library's macros, there's the
@ -49,4 +59,67 @@ are nondeterministic and often unknown at compile-time.
Always ping @oli-obk, @RalfJung, and @Centril if you are adding more `allow_internal_unstable`
attributes to any `const fn`
## staged_api
Any crate that uses the `stable`, `unstable`, or `rustc_deprecated` attributes
must include the `#![feature(staged_api)]` attribute on the crate.
## rustc_deprecated
The deprecation system shares the same infrastructure as the stable/unstable
attributes. The `rustc_deprecated` attribute is similar to the [`deprecated`
attribute]. It was previously called `deprecated`, but was split off when
`deprecated` was stabilized. The `deprecated` attribute cannot be used in a
`staged_api` crate, `rustc_deprecated` must be used instead. The deprecated
item must also have a `stable` or `unstable` attribute.
`rustc_deprecated` has the following form:
```rust,ignore
#[rustc_deprecated(
since = "1.38.0",
reason = "explanation for deprecation",
suggestion = "other_function"
)]
```
The `suggestion` field is optional. If given, it should be a string that can
be used as a machine-applicable suggestion to correct the warning. This is
typically used when the identifier is renamed, but no other significant
changes are necessary.
Another difference from the `deprecated` attribute is that the `since` field
is 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
default `allow`, but most of the standard library raises it to a warning with
`#![warn(deprecated_in_future)]`.
[`deprecated` attribute]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute
## -Zforce-unstable-if-unmarked
The `-Zforce-unstable-if-unmarked` flag has a variety of purposes to help
enforce that the correct crates are marked as unstable, but can still use
private crates without special attributes. It was introduced primarily to
allow rustc and the standard library to link to arbitrary crates on crates.io
which do not themselves use `staged_api`. `rustc` also relies on this flag to
mark all of its crates as unstable with the `rustc_private` feature so that
each crate does not need to be carefully marked with `unstable`.
This flag is automatically applied to all of `rustc` and the standard library
by the bootstrap scripts. This is needed because the compiler and all of its
dependencies are shipped in the sysroot to all users.
This flag has the following effects:
- Marks the crate as "unstable" with the `rustc_private` feature if it is not
itself marked as stable or unstable.
- Allows these crates to access other forced-unstable crates without any need
for attributes.
Code which does not use `-Zforce-unstable-if-unmarked` should include the
`#![feature(rustc_private)]` crate attribute to access these force-unstable
crates. This is needed for things that link `rustc`, such as `miri`, `rls`, or
`clippy`.
[blog]: https://www.ralfj.de/blog/2018/07/19/const.html