From b9b5d695e1b21d91bc3ac6dfbbd779d625948780 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 23 Jan 2021 13:47:33 -0500 Subject: [PATCH 1/3] Move 'force-unstable-if-unmarked' to the bootstrapping chapter --- src/building/bootstrapping.md | 30 ++++++++++++++++++++++++++++++ src/stability.md | 31 ------------------------------- 2 files changed, 30 insertions(+), 31 deletions(-) diff --git a/src/building/bootstrapping.md b/src/building/bootstrapping.md index 9da24e4c6..b292f19de 100644 --- a/src/building/bootstrapping.md +++ b/src/building/bootstrapping.md @@ -313,12 +313,42 @@ of the public API of the standard library, but are used to implement it. `rustlib` is part of the search path for linkers, but `lib` will never be part of the search path. +#### -Z force-unstable-if-unmarked + Since `rustlib` is part of the search path, it means we have to be careful about which crates are included in it. In particular, all crates except for the standard library are built with the flag `-Z force-unstable-if-unmarked`, which means that you have to use `#![feature(rustc_private)]` in order to load it (as opposed to the standard library, which is always available). +The `-Z force-unstable-if-unmarked` flag has a variety of purposes to help +enforce that the correct crates are marked as unstable. 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. Normally a crate would need a `#![feature(rustc_private)]` + attribute to use other unstable crates. However, that would make it + impossible for a crate from crates.io to access its own dependencies since + that crate won't have a `feature(rustc_private)` attribute, but *everything* + is compiled with `-Z force-unstable-if-unmarked`. + +Code which does not use `-Z force-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`. + You can find more discussion about sysroots in: - The [rustdoc PR] explaining why it uses `extern crate` for dependencies loaded from sysroot - [Discussions about sysroot on Zulip](https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp/topic/deps.20in.20sysroot/) diff --git a/src/stability.md b/src/stability.md index 69e434c07..a1d293ff9 100644 --- a/src/stability.md +++ b/src/stability.md @@ -130,35 +130,4 @@ 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 - -## -Z force-unstable-if-unmarked - -The `-Z force-unstable-if-unmarked` flag has a variety of purposes to help -enforce that the correct crates are marked as unstable. 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. Normally a crate would need a `#![feature(rustc_private)]` - attribute to use other unstable crates. However, that would make it - impossible for a crate from crates.io to access its own dependencies since - that crate won't have a `feature(rustc_private)` attribute, but *everything* - is compiled with `-Z force-unstable-if-unmarked`. - -Code which does not use `-Z force-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 From cf568f3618bf13e4431e19723af5e4c2d2b72f90 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 23 Jan 2021 13:49:38 -0500 Subject: [PATCH 2/3] Document how to stabilize a library feature Note that features can't be stabilized until they go through FCP and that FCP happens on the tracking issue, not the PR. --- src/stability.md | 24 +++++++++++++++++++----- src/stabilization_guide.md | 5 +++++ 2 files changed, 24 insertions(+), 5 deletions(-) diff --git a/src/stability.md b/src/stability.md index a1d293ff9..cfb4efd89 100644 --- a/src/stability.md +++ b/src/stability.md @@ -44,12 +44,8 @@ prevents breaking dependencies by leveraging Cargo's lint capping. [rustc bug]: https://github.com/rust-lang/rust/issues/15702 ## stable - The `#[stable(feature = "foo", "since = "1.420.69")]` attribute explicitly -marks an item as stabilized. To do this, follow the instructions in -[Stabilizing Features](./stabilization_guide.md). - -Note that stable functions may use unstable things in their body. +marks an item as stabilized. Note that stable functions may use unstable things in their body. ## rustc_const_unstable @@ -72,6 +68,24 @@ even on an `unstable` function, if that function is called from another Furthermore this attribute is needed to mark an intrinsic as callable from `rustc_const_stable` functions. +## Stabilizing a library feature + +To stabilize a feature, follow these steps: + +0. Ask a **@T-libs** member to start an FCP on the tracking issue and wait for + the FCP to complete (with `disposition-merge`). +1. Change `#[unstable(...)]` to `#[stable(since = "version")]`. + `version` should be the *current nightly*, i.e. stable+2. You can see which version is + the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). +2. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the + compiler or tools, remove it from there as well. +3. If applicable, change `#[rustc_const_unstable(...)]` to + `#[rustc_const_stable(since = "version")]`. +4. Open a PR against `rust-lang/rust`. + - Add the appropriate labels: `@rustbot modify labels: +T-libs`. + - Link to the tracking issue and say "Closes #XXXXX". + +You can see an example of stabilizing a feature at [#75132](https://github.com/rust-lang/rust/pull/75132). ## allow_internal_unstable diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index f4f58c392..a6203a3c6 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -1,5 +1,10 @@ # Request for stabilization +**NOTE**: this page is about stabilizing language features. +For stabilizing *library* features, see [Stabilizing a library feature]. + +[Stabilizing a library feature]: ./stability.md#stabilizing-a-library-feature + Once an unstable feature has been well-tested with no outstanding concern, anyone may push for its stabilization. It involves the following steps: From 25d4201ddeba2609046e8084c7cd64f68a5e5529 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sun, 24 Jan 2021 09:36:58 -0500 Subject: [PATCH 3/3] Fix wrong glob By default `**` behaves the same as two `*` side by side, i.e. it only globs file paths, not directories. `shopt -s globstar` needs to be set for it to mean a directory. I didn't notice this before now because `globstar` is set by default in interactive mode, but not otherwise. --- ci/check_line_lengths.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/ci/check_line_lengths.sh b/ci/check_line_lengths.sh index 8ecb8a309..31cda5c65 100755 --- a/ci/check_line_lengths.sh +++ b/ci/check_line_lengths.sh @@ -10,6 +10,7 @@ if [ "$MAX_LINE_LENGTH" == "" ]; then fi if [ "$1" == "" ]; then + shopt -s globstar files=( src/**/*.md ) else files=( "$@" )