rustc

1. Bootstrap the Rust Language

This section builds the prerequisite(s) for the rust programming language. All of these prerequisites are ephemera; after the final rust compiler is built and installed, everything built here will be destroyed.

We need this process because the rust compiler is written in rust; the rust project team makes sure that each minor version of the rust compiler can be built by the prior minor version. At the time I’m writing this, in March of 2025, the current version of rust — which is what the rust blueprint builds — is 1.85.0, which can be built by the 1.84 release, and so on. That being the case, I only know of two paths to bootstrap rust entirely from source code:

you can start with OCaml,^[1] use it to compile rust 0.7, and then step up through all the versions of rust to 1.84.1; or
you can use a C++ compiler to build mrustc, use mrustc to build rust 1.74.0, and then step up through the versions from there to 1.84.1.

Obviously, we’re going to use the latter approach.

The creation of this blueprint was enormously simplified by David Tolnay’s rust bootstrap project at https://github.com/dtolnay/bootstrap, which does essentially the same thing we’re doing here. (The main difference being, that project runs on a minimal debian userspace constructed with debootstrap, while this one runs on Little Blue Linux. This process is also a lot less generous with storage space: you can perform the entire build with only about 25 GiB of space avaialble for it.) I doubt I would have attempted to support the rust language in LB Linux at all without having that project to use as a starting point.

Be aware that this process takes quite a while! I run it on an AMD64 virtual machine with 18 CPU cores. The LibreSSL build takes only a couple of minutes; mrustc takes almost an hour; and each of the rustc stages from 1.75 to 1.84 takes about half an hour. Figure around six hours for the full bootstrap. So far, I’ve been unable to get the bootstrap to work on my Orange Pi ARM computer, so I can’t give timing details for that.

[bootstrap-sources-rustc] == Source Code For The Rust Bootstrap

As I described earlier, in [bootstrap-sources-go], my practice is to package all the source code for ephemeral versions of packages needed for these bootstrap processes in a tarred-up git repository. Here’s how to create the bootstrap source archive for rust, if you want to do that rather than simply using the one I’ve built.

First, create an empty repository in a bootstrap-rustc-1.85.0 directory. I always create an empty first commit, so I will do that here.

mkdir bootstrap-rustc-1.85.0; cd bootstrap-rustc-1.85.0
git init
git commit --allow-empty -m "commit zero"

Now, for each version of each package that you need during the bootstrap, create a branch and import it.

The mrustc compiler can be found at https://github.com/thepowersgang/mrustc.

All versions of the rust compiler sources can be found at https://static.rust-lang.org/dist/rustc-x.yy.z-src.tar.xz (where x.yy.z is the release number you want). You can also obtain GPG signatures by adding .asc to that URL. These are not the same as the source archives you can find at https://github.com/rust-lang/rust — as far as I’m aware, those archives won’t work properly with this process.

git checkout -b mrustc-0.11.2
tar -x --strip-components=1 -f /full/path/to/mrustc-0.11.2.tar.*
git add -f .
git commit -m "mrustc 0.11.2"
git checkout master

Repeat those steps for rustc-1.74.0 through rustc-1.84.1.

There are two patches to apply for each rustc version; my practice is to apply those patches as commits on the branches in this git repository, because there’s really no reason to do anything else.

First, one of the vendored libraries included with rustc is openssl-sys, and old versions of that library — some of which are present in the rustc distribution files — have a version check that says they do not work with LibreSSL 4.0. Since that’s the version used in CBL, we either have to include an old version of LibreSSL for use by rustc, or modify the version check so that it allows LibreSSL 4.0 to be used. I prefer the latter approach, so that’s a patch I apply to each version of rustc. To compose those patches, modify all versions^[2] of vendor/openssl-sys*/build/main.rs. In the validate_headers function, there’s a list of LibreSSL versions that includes things like:

(3, 7, _) => ('3', '7', 'x'),
(3, 8, 0) => ('3', '8', '0'),

Just add these lines:

(4, 0, 0) => ('4', '0', '0'),
(4, 0, _) => ('4', '0', 'x'),

in that same block.

There’s one other irritation related to the vendored source packages

each package under vendor contains a file .cargo-checksum.json that contains SHA256 checksums of all the files in that package, and the build process checks to make sure the checksums match. So in addition to changing the build/main.rs files, you need to calculate the new checksums and modify the .cargo-checksum.json file as well. There is probably be a more idiomatic way to make changes like this; the message given if the checksum does not match is:

directory sources are not intended to be edited, if modifications are
required then it is recommended that `[patch]` is used with a forked
copy of the source

But I don’t know exactly what that means or how to do it. If you do, let me know!

After you have made this change on one branch, you might be able to save effort by cherry-picking it onto each other branch, although you’ll need to resolve conflicts and double-check the results, including the checksum changes, each time.

In addition to the openssl-sys patch, for each rustc version except the first one, you should also create a config.toml file (and put it on the same branch, as a second commit). This is used to configure the build process. For the first several versions of rustc, The config.toml file should look like this:

change-id = SOME_CHANGE_ID_NUMBER_SEE_BELOW
[build]
cargo = "/FULL/PATH/TO/PREVIOUS/CARGO"
rustc = "/FULL/PATH/TO/PREVIOUS/RUSTC"
docs = false
vendor = true
extended = true
tools = ["cargo"]
[rust]
channel = "stable"

The cargo and rustc lines are used to find the version of those programs from the previous build of rustc. The first intermediate version of rustc will be built by mrustc and does not need a config.toml file at all, because the mrustc build process will define how it should be configured and how it should find the bootstrap versions of cargo and rustc. The second intermediate version of rustc, which does need a config.toml, should specify /usr/src/rustc/bs/prev_rust/prefix/bin/cargo and /usr/src/rustc/bs/prev_rust/prefix/bin/rustc for these, to use the versions of those programs produced by the mrustc build. For all other intermediate rustc builds — and the final system rustc build — config.toml should specify cargo as /usr/src/rustc/bs/prev_rust/stage1-tools-bin/cargo and rustc as /usr/src/rustc/bs/prev_rust/stage1/bin/rustc, because that’s where this bootstrap build process will put them..

The other config.toml line that needs to differ for each version is the change-id. For rustc 1.75, there is a specific value for change-id in the config.example.toml file in the distribution, so just use that one. For all the later versions, the example config file has a note saying that the latest change ID in src/bootstrap/src/utils/change_tracker.rs should be used; so you should look at the CONFIG_CHANGE_HISTORY section of that file to find the largest change_id value, and use that.

Later versions of rustc require additional configuration directives. For the rustc 1.83 build and later, you should add an additional stanza:

[llvm]
download-ci-llvm = false

Also, for rustc 1.84 and later, you should add the directive download-rustc = false to the [rust] stanza.

Once all the branches have been added (and patched to include the config.toml file), check out the empty master branch and repack the repository to save as much space as possible:

rm .git/hooks/*.sample
git reflog expire --expire=0 --all
git gc
git prune
git pack-refs
git repack -A -d -f --depth=500 --window=500

Now create a tar archive containing bootstrap-rustc-1.85.0, compress it, and put it in the TARFILE_DIR location. That’s the source code bundle that this blueprint will use.

1.1. Rustc Package User

The convention used in CBL, when constructing dependencies for a package that needs a process like this, is to do those builds as the same package user that will then be used for the desired package. We therefore need to ensure that package user exists.

Commands:

add-package-user 'Rust Compiler' rustc

We’ll build the bootstrap ephemera in a bs (for "BootStrap") subdirectory of the package user’s home directory so that it will be easy to get rid of it all when we’re done with it.

Commands:

su -l -c 'mkdir -p $HOME/bs/' rustc
su -l -c "tar -x -C ~rustc/bs -f ${TARFILE_DIR}/bootstrap-rustc*tar.lz" \
  rustc

1.2. Building mrustc

For each stage in our bootstrap build, we’ll start with a guard clause so that if we restart the bootstrap, it won’t necessarily need to start over from the beginning.

File /tmp/build-mrustc:

#!/bin/bash
set -e
if [ -f $HOME/bs/.mrustc-complete ]
then
  echo "mrustc has already been built, skipping it"
  exit
fi

The first part of the mrustc build simply builds mrustc.