Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

bootstrap readme: fix, improve, update #122330

Merged
merged 1 commit into from
Mar 11, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 14 additions & 13 deletions src/bootstrap/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# rustbuild - Bootstrapping Rust

This README is aimed at helping to explain how Rust is bootstrapped and in general,
some of the technical details of the build system.
This README is aimed at helping to explain how Rust is bootstrapped,
and some of the technical details of the build system.

Note that this README only covers internal information, not how to use the tool.
Please check [bootstrapping dev guide][bootstrapping-dev-guide] for further information.
Expand All @@ -10,12 +10,12 @@ Please check [bootstrapping dev guide][bootstrapping-dev-guide] for further info

## Introduction

The build system defers most of the complicated logic managing invocations
The build system defers most of the complicated logic of managing invocations
of rustc and rustdoc to Cargo itself. However, moving through various stages
and copying artifacts is still necessary for it to do. Each time rustbuild
is invoked, it will iterate through the list of predefined steps and execute
each serially in turn if it matches the paths passed or is a default rule.
For each step rustbuild relies on the step internally being incremental and
For each step, rustbuild relies on the step internally being incremental and
parallel. Note, though, that the `-j` parameter to rustbuild gets forwarded
to appropriate test harnesses and such.

Expand All @@ -24,7 +24,7 @@ to appropriate test harnesses and such.
The rustbuild build system goes through a few phases to actually build the
compiler. What actually happens when you invoke rustbuild is:

1. The entry point script(`x` for unix like systems, `x.ps1` for windows systems,
1. The entry point script (`x` for unix like systems, `x.ps1` for windows systems,
`x.py` cross-platform) is run. This script is responsible for downloading the stage0
compiler/Cargo binaries, and it then compiles the build system itself (this folder).
Finally, it then invokes the actual `bootstrap` binary build system.
Expand Down Expand Up @@ -107,12 +107,13 @@ build/

# Location where the stage0 Cargo and Rust compiler are unpacked. This
# directory is purely an extracted and overlaid tarball of these two (done
# by the bootstrap python script). In theory, the build system does not
# by the bootstrap Python script). In theory, the build system does not
# modify anything under this directory afterwards.
stage0/

# These to-build directories are the cargo output directories for builds of
# the standard library and compiler, respectively. Internally, these may also
# the standard library, the test system, the compiler, and various tools,
# respectively. Internally, these may also
# have other target directories, which represent artifacts being compiled
# from the host to the specified target.
#
Expand Down Expand Up @@ -169,17 +170,17 @@ read by the other.

Some general areas that you may be interested in modifying are:

* Adding a new build tool? Take a look at `bootstrap/tool.rs` for examples of
other tools.
* Adding a new build tool? Take a look at `bootstrap/src/core/build_steps/tool.rs`
for examples of other tools.
* Adding a new compiler crate? Look no further! Adding crates can be done by
adding a new directory with `Cargo.toml` followed by configuring all
adding a new directory with `Cargo.toml`, followed by configuring all
`Cargo.toml` files accordingly.
* Adding a new dependency from crates.io? This should just work inside the
compiler artifacts stage (everything other than libtest and libstd).
* Adding a new configuration option? You'll want to modify `bootstrap/flags.rs`
for command line flags and then `bootstrap/config.rs` to copy the flags to the
* Adding a new configuration option? You'll want to modify `bootstrap/src/core/config/flags.rs`
for command line flags and then `bootstrap/src/core/config/config.rs` to copy the flags to the
`Config` struct.
* Adding a sanity check? Take a look at `bootstrap/sanity.rs`.
* Adding a sanity check? Take a look at `bootstrap/src/core/sanity.rs`.

If you make a major change on bootstrap configuration, please remember to:

Expand Down
Loading