Multi-target builds & libunwind expanded, various wording tightened

Author: adamgemmell

text/0000-build-std/2-history.md

@@ -174,6 +174,13 @@ categories:
    symbols provided by `libc`. compiler-builtins is also built with a large
    number of compilation units to force each function into a different unit.
 
+   ['unwind'][wg-cargo-std-aware-29] will, by default, link to the system's
+   version of libunwind. The feature `llvm-libunwind` or certain compiler flags
+   such as `-Clink-self-contained` or `-Ctarget-feature=+crt-static` may cause
+   Rust to statically link to the in-tree version of `libunwind`, which is built
+   by bootstrap. Previously, this used to be built by `unwind`'s `build.rs`
+   file.
+
    [Sanitizers][wg-cargo-std-aware#17], when enabled, require a sanitizer
    runtime to be present. These are currently built by bootstrap and part of
    LLVM.

text/0000-build-std/4-stage-1a.md

@@ -43,7 +43,7 @@ useful for users of tier three targets.
 > as is feasible.
 
 Alongside `build-std`, a `build-std-crate` key will be introduced
-([?][rationale-build-std-crate]), which can be used to specify which crate from
+([?][rationale-build-std-crate]), which can be used to specify which "level" of
 the standard library is to be built. Only "core", "alloc" and "std" are valid
 values for `build-std-crate`.
 
@@ -57,6 +57,9 @@ will not be used unless explicitly set and the crate graph's dependencies on the
 standard library will determine which crates are built instead. Otherwise,
 `build-std-crate` will default to "std".
 
+If `std` is to be built and Cargo is building a test using the default test
+harness then Cargo will also build the `test` crate.
+
 > [!NOTE]
 >
 > Inspired by the concept of [opaque dependencies][Opaque dependencies], the
@@ -71,21 +74,20 @@ standard library will determine which crates are built instead. Otherwise,
 >   the dependencies of the `core`, `alloc` or `std` standard library crates
 >   individually (via profile overrides, for example).
 > 
-> - The profiles defined by the standard library will be used.
+> - The profile defined by the standard library will be used.
 >
 > Cargo will resolves the dependencies of opaque dependencies, such as the
-> standard library, separately in their own workspaces. The "roots" of such a
-> resolve are defined as the unified set of packages that any crate in the
-> dependency graph has a explicit dependency on and those which Cargo infers a
-> direct dependency on. A dependency on the roots are added to all crates in the
-> "parent" resolve.
+> standard library, separately in their own workspaces. The root of such a
+> resolve will be the crate specified in `build-std-crates`, or, if stage 1b is
+> implemented, the unified set of packages that any crate in the dependency
+> a direct dependency on. A dependency on the relevant roots are added to all
+> crates in the "parent" resolve.
 >
 > Regardless of which standard library crates are being built, Cargo will build
 > the `sysroot` crate of the standard library workspace. `alloc` and `std` will
 > be optional dependencies of the `sysroot` crate which will be enabled when the
-> user has requested them. The sysroot always depends on the `proc_macro` and
-> `test` crates. Panic runtimes are dependencies of `std` and will be enabled
-> depending on the features that Cargo passes to `std` (see
+> user has requested them. Panic runtimes are dependencies of `std` and will be
+> enabled depending on the features that Cargo passes to `std` (see
 > [*Panic strategies*][panic-strategies]).
 >
 > rustc loads panic runtimes in a different way to most dependencies, and
@@ -96,13 +98,14 @@ standard library will determine which crates are built instead. Otherwise,
 >
 > The standard library will always be a non-incremental build
 > ([?][rationale-incremental]), with no `depinfo` produced, and only a `rlib`
-> produced (no `dylib`) ([?][rationale-no-dylib]). It will be built into the
-> `target` directory of the crate or workspace like any other dependency.
+> produced (no `dylib`) ([?][rationale-no-dylib]). It will be built in Cargo's
+> "target" directory of the crate or workspace like any other dependency.
 
 The host pre-built standard library will always be used for procedural macros
-and build scripts ([?][rationale-sysroot-for-host-deps]). Artifact dependencies
-use the same standard library as the rest of the crate (pre-built or
-newly-built, as appropriate).
+and build scripts ([?][rationale-sysroot-for-host-deps]). Multi-target projects
+(resulting from the "target" field in artifact dependencies or the use of
+`per-pkg-target` fields) may result in the standard library being built multiple
+times - once for each target in the project.
 
 *See the following sections for rationale/alternatives:*
 
@@ -127,10 +130,10 @@ newly-built, as appropriate).
 ## Interactions with `#![no_std]`
 [interactions-with-no_std]: #interactions-with-no_std
 
-Behaviour of crates using `#![no_std]` will change even if the standard library
-is rebuilt and passed via `--extern` to rustc. Due to `#![no_std]`, rustc will
-not automatically attempt to load std, but if the user writes `extern crate std`
-then the rebuilt std will be found.
+Behaviour of crates using `#![no_std]` will not change whether or not `std` is
+rebuilt and passed via `--extern` to rustc, and `#![no_std]` will still be
+required in order for `rustc` to not attempt to load `std` and add it to the
+extern prelude.
 
 *See the following sections for rationale/alternatives:*
 
@@ -198,8 +201,9 @@ explicit and implicit standard library dependencies.
 When it is necessary to build the standard library, Cargo will look for sources
 in a fixed location in the sysroot ([?][rationale-custom-src-path]):
 `lib/rustlib/src`. rustup's `rust-src` component downloads standard library
-sources to this location. If the sources are not found, Cargo will emit an error
-and recommend the user download `rust-src` if using rustup.
+sources to this location and will be made a default component. If the sources
+are not found, Cargo will emit an error and recommend the user download
+`rust-src` if using rustup.
 
 `rust-src` will contain the sources for the standard library crates as well as
 its vendored dependencies ([?][rationale-vendoring]). As a consequence sources
@@ -217,12 +221,6 @@ of standard library dependencies will not need be fetched from crates.io.
 - [*Why vendor standard library dependencies?*][rationale-vendoring]
 - [*Why not check if `rust-src` has been modified?*][rationale-src-modifications]
 
-### `libunwind`
-[libunwind]: #libunwind
-
-`libunwind`'s sources are included in the `rust-src` component so that they can
-be used as part of the standard library build on targets which require it.
-
 ## Panic strategies
 [panic-strategies]: #panic-strategies
 
@@ -261,6 +259,18 @@ In line with Cargo's stance on not parsing the `RUSTFLAGS` environment variable,
 it will not be checked for compilation flags that would require additional
 crates to be built for compilation to succeed.
 
+> [!NOTE]
+>
+> This RFC does not propose building `libunwind` locally as `unwind`'s build
+> script [used to do][rust#84124]. The `unwind` crate usually links to the
+> system's `libunwind`, in which case any target modifiers used should be set
+> correctly to match compilation flags to match this artifact. Certain flags
+> such as `-Clink-self-contained=yes` may cause `rustc` to find `libunwind` in
+> the sysroot, in which case any set target modifiers may break linking.
+>
+> This could be treated similarly to the `compiler_builtins` manual `c` feature
+> in the future.
+
 *See the following sections for future possibilities:*
 
 - [*Avoid building `panic_unwind` unnecessarily*][future-panic_unwind]
@@ -284,7 +294,7 @@ A handful of targets require linking against special object files, such as
 `windows-gnu`, `linux-musl` and `wasi` targets. For example, `linux-musl`
 targets require `crt1.o`, `crti.o`, `crtn.o`, etc.
 
-Since [rust#76185]/[compiler-team#343], the compiler has a stable
+Since [rust#76158]/[compiler-team#343], the compiler has a stable
 `-Clink-self-contained` flag which will look for special object files in
 expected locations, typically populated by the `rust-std` components. Its
 behaviour can be forced by `-Clink-self-contained=true`, but is force-enabled
@@ -313,7 +323,8 @@ missing special object files.
 [compiler-builtins]: #compiler-builtins
 
 `compiler-builtins` is always built with `-Ccodegen-units=10000` to force each
-intrinsic into its own object file to avoid symbol clashes with libgcc.
+intrinsic into its own object file to avoid symbol clashes with libgcc. This is
+currently enforced with a profile override in the standard library's workspace.
 
 rustc will automatically use a large number of codegen units for the
 `compiler-builtins` crate, unless manually specified using the `-Ccodegen-units`
@@ -352,14 +363,15 @@ It will not be enabled by default because it is possible that the target
 platform does not have a suitable C compiler available. The user being able to
 enable this manually will be enabled through work on features (see
 [*Allow enabling/disabling features with build-std*][future-features] from Stage
-1b).
+1b). This will require the user to manually configure `CFLAGS` to ensure that
+the c components will link with Rust code.
 
 ## Caching
 [caching]: #caching
 
 Standard library artifacts built by build-std will not be shared between crates
-or workspaces, as they only exist in the `target` directory of a specific crate
-or workspace ([?][rationale-caching]).
+or workspaces, as they only exist in Cargo's target directory for a specific
+crate or workspace ([?][rationale-caching]).
 
 *See the following sections for rationale/alternatives:*
 
@@ -511,7 +523,7 @@ There are various alternatives to putting `build-std` in the Cargo configuration
 
 2. build-std could be enabled or disabled in the `Cargo.toml`. However, under
    which conditions the standard library is rebuilt is better determined by the
-   user of Cargo, rather than the project being built.
+   user of Cargo, rather than the package being built.
 
    A user may want to never rebuild the standard library so as to avoid
    invalidating the guarantees of their qualified toolchain, or may want to
@@ -672,9 +684,9 @@ which further limits potential use cases to those without `target-modifiers`.
 [rationale-replace-no_std]: #why-not-replace-no_std-as-the-source-of-truth-for-whether-a-crate-depends-on-std
 
 Crates can currently use the crate attribute `#![no_std]` to indicate a lack of
-dependency on `std`. With `Cargo.toml` being used to express a dependency on the
-standard library (or lack thereof), it is unintuitive for there to be two
-sources-of-truth for this information.
+dependency on `std`. With Cargo being used to express a dependency (or lack
+thereof) on the standard library (and further so in [stage1b]) it is unintuitive
+for there to be two sources-of-truth for this information.
 
 `#![no_std]` serves two purposes - it stops the compiler from loading `std` from
 the sysroot and adding `extern crate std`, and it prevents the user from
@@ -757,14 +769,17 @@ providing an empty path.
 ### Why use `noprelude` with `--extern`?
 [rationale-noprelude-with-extern]: #why-use-noprelude-with---extern
 
-The `noprelude` modifier for `--extern` is necessary for use of the `--extern`
-flag to be equivalent to using a modified sysroot.
+Rustc has logic specific to the standard library that decides when to add those
+crates to the extern prelude which will not be changed as part of this RFC.
+Adding The `noprelude` modifier for `--extern` is necessary for use of the
+`--extern` flag to be equivalent to loading from a sysroot.
 
 Without `noprelude`, rustc implicitly inserts a `extern crate $name` when using
 `--extern`. As a consequence, if a newly-built `alloc` were passed using
-`--extern alloc=alloc.rlib` then `extern crate alloc` would not be required, but
-it would be if the pre-built `alloc` could be used. This difference in how a
-crate is made available to rustc should not be observable to the user.
+`--extern alloc=alloc.rlib` then `extern crate alloc` would not be required to
+use the locall-built `alloc`, but it would be to use the pre-built `alloc`. This
+difference in how a crate is made available to rustc should not be observable to
+the user.
 
 ↩ [*Preventing implicit sysroot dependencies*][preventing-implicit-sysroot-dependencies]
 
@@ -832,19 +847,23 @@ included.
 [rationale-implied-bootstrap]: #why-allow-building-from-the-sysroot-with-implied-rustc_bootstrap
 
 Cargo needs to be able to build the standard library crates, which inherently
-require a nightly toolchain. It could set `RUSTC_BOOTSTRAP` internally to do
-this with a stable toolchain, however this is a shared requirement with other
-build systems that wish to build an unmodified standard library and want to work
-on stable toolchains.
-
-For example, Rust's project goal to enable Rust for Linux to build using only a
-stable toolchain would require that it be possible to build `core` without
-nightly.
+require a nightly toolchain. This is a shared requirement with other build
+systems that wish to build an unmodified standard library and want to work
+on stable toolchains. For example, Rust's project goal to enable Rust for Linux
+to build using only a stable toolchain would require that it be possible to
+build `core` without nightly.
+
+Cargo could continue to set `RUSTC_BOOTSTRAP` internally when building standard
+library crates with a stable toolchain, but the Rust project
+[does not wish to encourage][rustc-bootstrap-docs] widespread usage of this
+"escape-hatch" where possible. Allowing crate sources in the sysroot to use
+nightly features is a compromise and fits into the model of the sysroot being
+unique to that version of the toolchain.
 
 It is not sufficient for rustc to special-case the `core`, `alloc` and `std`
-crate names as when being built as part of the standard library, dependencies of
-the standard library also use unstable features and so these crate would also
-need such special-casing, which is not practical.
+crate names as when being built as part of the standard library dependencies of
+the standard library also use unstable features. These crates would also need
+such special-casing, which is not practical.
 
 ↩ [*Building the standard library on a stable toolchain*][building-the-standard-library-on-a-stable-toolchain]
 
@@ -964,11 +983,13 @@ produced by build-std.
 
 [compiler-builtins#411]: https://github.com/rust-lang/compiler-builtins/pull/411
 [compiler-team#343]: https://github.com/rust-lang/compiler-team/issues/343
-[rust#76185]: https://github.com/rust-lang/rust/pull/76185
+[rust#76158]: https://github.com/rust-lang/rust/pull/76158
 [rust#71009]: https://github.com/rust-lang/rust/pull/71009
+[rust#84124]: https://github.com/rust-lang/rust/pull/84124
 [rust#135395]: https://github.com/rust-lang/rust/pull/135395
 
 [std-build.rs]: https://github.com/rust-lang/rust/blob/f315e6145802e091ff9fceab6db627a4b4ec2b86/library/std/build.rs#L17
+[rustc-bootstrap-docs]: https://doc.rust-lang.org/nightly/unstable-book/compiler-environment-variables/RUSTC_BOOTSTRAP.html#stability-policy
 
 [cargo-add]: https://doc.rust-lang.org/cargo/commands/cargo-add.html
 [cargo-bench]: https://doc.rust-lang.org/cargo/commands/cargo-bench.html

text/0000-build-std/5-stage-1b.md

@@ -328,10 +328,10 @@ and cannot otherwise be found in the registry.
 >
 > The keys `req`, `registry` and `package` from `deps` are not required per the
 > limitations on builtin dependencies.
-> 
+>
 > The key is optional and its default value will be the implicit builtin
 > dependencies:
-> 
+>
 > ```json
 > "builtin_deps" : [
 >     {
@@ -679,7 +679,7 @@ circumstance, then they would be located in a `-L dependency=` directory, which
 rustc would not search when loading a crate from `extern crate`.
 
 > [!NOTE]
-> 
+>
 > `alloc` and `core` must always be passed with `--extern`.
 
 ↩ [*Proposal*][proposal]

text/0000-build-std/6-stage-2.md

@@ -61,6 +61,18 @@ As with the "always" option, the exact crates from the standard library to be
 built are determined by the `build-std-crate` option or explicit dependencies on
 the standard library if [*Stage 1b*][stage1b] was implemented.
 
+Multi-target projects (resulting from the "target" field in artifact
+dependencies or the use of `per-pkg-target` fields) results in the decision to
+rebuild the standard library being made multiple times - once for each target in
+the project.
+
+> [!NOTE]
+>
+> Because Cargo does not have per-target profiles nor a way to change the
+> standard library's profile at this stage the only way to configure the
+> standard library differently for different targets is with the use of the
+> `[target]` sections in the Cargo config.
+
 *See the following sections for rationale/alternatives:*
 
 - [*Why default to "compatible"?*][rationale-default]
@@ -143,7 +155,7 @@ It could be named "target-modifiers" or "automatic".
 ## What should the interface to rustc compatibility checking be?
 [unresolved-rustc-compat-interface]: #what-should-the-interface-to-rustc-compatibility-checking-be
 
-Should it an `--emit` flag? a `--print` flag?
+Should it be an `--emit` flag? A `--print` flag?
 
 ↩ [*Proposal*][proposal]