src/doc/rustc-guide/src/stability.md

   1 # Stability attributes
   2
   3 This section is about the stability attributes and schemes that allow stable APIs to use unstable
   4 APIs internally in the rustc standard library.
   5
   6 For instructions on stabilizing a language feature see
   7 [Stabilizing Features](./stabilization_guide.md).
   8
   9 ## unstable
  10
  11 The `#[unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")]` attribute explicitly
  12 marks an item as unstable. Items that are marked as "unstable" cannot be used
  13 without a corresponding `#![feature]` attribute on the crate, even on a
  14 nightly compiler. This restriction only applies across crate boundaries, unstable
  15 items may be used within the crate they are defined.
  16
  17 The `unstable` attribute infects all sub-items, where the attribute doesn't have to be
  18 reapplied. So if you apply this to a module, all items in the module will be unstable.
  19
  20 You can make specific sub-items stable by using the `#[stable]` attribute on them.
  21 The stability scheme works similarly to how `pub` works. You can have public functions of
  22 nonpublic modules and you can have stable functions in unstable modules or vice versa.
  23
  24 Note, however, that due to a [rustc bug], stable items inside unstable modules
  25 *are* available to stable code in that location!  So, for example, stable code
  26 can import `core::intrinsics::transmute` even though `intrinsics` is an unstable
  27 module.  Thus, this kind of nesting should be avoided when possible.
  28
  29 The `unstable` attribute may also have the `soft` value, which makes it a
  30 future-incompatible deny-by-default lint instead of a hard error. This is used
  31 by the `bench` attribute which was accidentally accepted in the past. This
  32 prevents breaking dependencies by leveraging Cargo's lint capping.
  33
  34 [rustc bug]: https://github.com/rust-lang/rust/issues/15702
  35
  36 ## stable
  37
  38 The `#[stable(feature = "foo", "since = "1.420.69")]` attribute explicitly marks an item as
  39 stabilized. To do this, follow the instructions in
  40 [Stabilizing Features](./stabilization_guide.md).
  41
  42 Note that stable functions may use unstable things in their body.
  43
  44 ## allow_internal_unstable
  45
  46 Macros, compiler desugarings and `const fn`s expose their bodies to the call site. To
  47 work around not being able to use unstable things in the standard library's macros, there's the
  48 `#[allow_internal_unstable(feature1, feature2)]` attribute that whitelists the given features for
  49 usage in stable macros or `const fn`s.
  50
  51 Note that `const fn`s are even more special in this regard. You can't just whitelist any feature,
  52 the features need an implementation in `qualify_min_const_fn.rs`. For example the `const_fn_union`
  53 feature gate allows accessing fields of unions inside stable `const fn`s. The rules for when it's
  54 ok to use such a feature gate are that behavior matches the runtime behavior of the same code
  55 (see also [this blog post][blog]). This means that you may not create a
  56 `const fn` that e.g. transmutes a memory address to an integer, because the addresses of things
  57 are nondeterministic and often unknown at compile-time.
  58
  59 Always ping @oli-obk, @RalfJung, and @Centril if you are adding more `allow_internal_unstable`
  60 attributes to any `const fn`
  61
  62 ## staged_api
  63
  64 Any crate that uses the `stable`, `unstable`, or `rustc_deprecated` attributes
  65 must include the `#![feature(staged_api)]` attribute on the crate.
  66
  67 ## rustc_deprecated
  68
  69 The deprecation system shares the same infrastructure as the stable/unstable
  70 attributes. The `rustc_deprecated` attribute is similar to the [`deprecated`
  71 attribute]. It was previously called `deprecated`, but was split off when
  72 `deprecated` was stabilized. The `deprecated` attribute cannot be used in a
  73 `staged_api` crate, `rustc_deprecated` must be used instead. The deprecated
  74 item must also have a `stable` or `unstable` attribute.
  75
  76 `rustc_deprecated` has the following form:
  77
  78 ```rust,ignore
  79 #[rustc_deprecated(
  80     since = "1.38.0",
  81     reason = "explanation for deprecation",
  82     suggestion = "other_function"
  83 )]
  84 ```
  85
  86 The `suggestion` field is optional. If given, it should be a string that can
  87 be used as a machine-applicable suggestion to correct the warning. This is
  88 typically used when the identifier is renamed, but no other significant
  89 changes are necessary.
  90
  91 Another difference from the `deprecated` attribute is that the `since` field
  92 is actually checked against the current version of `rustc`. If `since` is in a
  93 future version, then the `deprecated_in_future` lint is triggered which is
  94 default `allow`, but most of the standard library raises it to a warning with
  95 `#![warn(deprecated_in_future)]`.
  96
  97 [`deprecated` attribute]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute
  98
  99 ## -Zforce-unstable-if-unmarked
 100
 101 The `-Zforce-unstable-if-unmarked` flag has a variety of purposes to help
 102 enforce that the correct crates are marked as unstable. It was introduced
 103 primarily to allow rustc and the standard library to link to arbitrary crates
 104 on crates.io which do not themselves use `staged_api`. `rustc` also relies on
 105 this flag to mark all of its crates as unstable with the `rustc_private`
 106 feature so that each crate does not need to be carefully marked with
 107 `unstable`.
 108
 109 This flag is automatically applied to all of `rustc` and the standard library
 110 by the bootstrap scripts. This is needed because the compiler and all of its
 111 dependencies are shipped in the sysroot to all users.
 112
 113 This flag has the following effects:
 114
 115 - Marks the crate as "unstable" with the `rustc_private` feature if it is not
 116   itself marked as stable or unstable.
 117 - Allows these crates to access other forced-unstable crates without any need
 118   for attributes. Normally a crate would need a `#![feature(rustc_private)]`
 119   attribute to use other unstable crates. However, that would make it
 120   impossible for a crate from crates.io to access its own dependencies since
 121   that crate won't have a `feature(rustc_private)` attribute, but *everything*
 122   is compiled with `-Zforce-unstable-if-unmarked`.
 123
 124 Code which does not use `-Zforce-unstable-if-unmarked` should include the
 125 `#![feature(rustc_private)]` crate attribute to access these force-unstable
 126 crates. This is needed for things that link `rustc`, such as `miri`, `rls`, or
 127 `clippy`.
 128
 129 [blog]: https://www.ralfj.de/blog/2018/07/19/const.html