Rustc-1.67.1

Introduction to Rust

The Rust programming language is designed to be a safe, concurrent, practical language.

This package is updated on a six-weekly release cycle. Because it is such a large and slow package to build, is at the moment only required by a few packages in this book, and particularly because newer versions tend to break older mozilla packages, the BLFS editors take the view that it should only be updated when that is necessary (either to fix problems, or to allow a new version of a package to build).

As with many other programming languages, rustc (the rust compiler) needs a binary from which to bootstrap. It will download a stage0 binary at the start of the build, so you cannot compile it without an Internet connection.

[Note]

Note

Although BLFS usually installs in /usr, when you later upgrade to a newer version of rust the old libraries in /usr/lib/rustlib will remain, with various hashes in their names, but will not be usable and will waste space. The editors recommend placing the files in the /opt directory. In particular, if you have reason to rebuild with a modified configuration (e.g. using the shipped LLVM after building with shared LLVM, perhaps to compile crates for architectures which the BLFS LLVM build does not support) it is possible for the install to leave a broken cargo program. In such a situation, either remove the existing installation first, or use a different prefix such as /opt/rustc-1.67.1-build2.

If you prefer, you can of course change the prefix to /usr.

The current rustbuild build-system will use all processors, although it does not scale well and often falls back to just using one core while waiting for a library to compile. However it can be mostly limited to a specified number of processors by a combination of adding the switch --jobs <N> (e.g. '--jobs 4' to limit to 4 processors) on each invocation of python3 ./x.py and using an environment variable CARGO_BUILD_JOBS=<N>. At the moment this is not effective when some of the rustc tests are run.

The current version of rust's num_cpus crate now recognizes that cgroups can be used to restrict which processors it is allowed to use. So if your machine lacks DRAM (typically, less than 2GB DRAM per core) that might be an alternative to taking CPUs offline. In sysv systems cgroups requires libcgroup.

At the moment Rust does not provide any guarantees of a stable ABI.

[Note]

Note

Rustc defaults to building for ALL supported architectures, using a shipped copy of LLVM. In BLFS the build is only for the X86 architecture. If you intend to develop rust crates, this build may not be good enough for your purposes.

The build times of this version when repeated on the same machine are often reasonably consistent, but as with all compilations using rustc there can be some very slow outliers.

This package is known to build and work properly using an LFS 11.3 platform.

Package Information

  • Download (HTTP): https://static.rust-lang.org/dist/rustc-1.67.1-src.tar.xz

  • Download MD5 sum: e5e47e53c52574ce89ea200e52819f81

  • Download size: 136 MB

  • Estimated disk space required: 8.5 GB (501 MB installed); add 7.5 GB if running the tests

  • Estimated build time: 13 SBU (including download time; add 16 SBU for tests, both using parallelism=4)

Rust Dependencies

Required

CMake-3.25.2

Recommended

[Note]

Note

If a recommended dependency is not installed, a shipped copy in the Rustc source tarball will be built and used.

Optional

GDB-13.1 (used by the test suite if it is present) and libgit2

User Notes: https://wiki.linuxfromscratch.org/blfs/wiki/rust

Installation of Rust

[Note]

Note

Currently Rust compiler produces SSE2 instructions for 32-bit x86, causing the generated code broken on 32-bit systems without a SSE2-capable processor. All x86 processor models released after 2004 should be SSE2-capable. Run lscpu | grep sse2 as a test. If it outputs anything, your CPU is SSE2-capable and OK. Otherwise you may try to build this package on a SSE2-capable system with the following fix applied:

sed 's@pentium4@pentiumpro@' -i \
    compiler/rustc_target/src/spec/i686_unknown_linux_gnu.rs

And copy the resulting /opt/rustc-1.67.1 to the system without SSE2 capability. But this change is still under upstream review and not tested by BLFS editors.

To install into the /opt directory, remove any existing /opt/rustc symlink and create a new directory (i.e. with a different name if trying a modified build of the same version). As the root user:

mkdir -pv /opt/rustc-1.67.1      &&
ln -svfn rustc-1.67.1 /opt/rustc
[Note]

Note

If multiple versions of Rust are installed in /opt, changing to another version only requires changing the /opt/rustc symbolic link and then running ldconfig.

Create a suitable config.toml file which will configure the build.

cat << EOF > config.toml
# see config.toml.example for more possible options
# See the 8.4 book for an old example using shipped LLVM
# e.g. if not installing clang, or using a version before 13.0

# tell x.py to not keep printing an annoying warning
changelog-seen = 2

[llvm]
# by default, rust will build for a myriad of architectures
targets = "X86"

# When using system llvm prefer shared libraries
link-shared = true

[build]
# omit docs to save time and space (default is to build them)
docs = false

# install extended tools: cargo, clippy, etc
extended = true

# Do not query new versions of dependencies online.
locked-deps = true

# Specify which extended tools (those from the default install).
tools = ["cargo", "clippy", "rustfmt"]

# Use the source code shipped in the tarball for the dependencies.
# The combination of this and the "locked-deps" entry avoids downloading
# many crates from Internet, and makes the Rustc build more stable.
vendor = true

[install]
prefix = "/opt/rustc-1.67.1"
docdir = "share/doc/rustc-1.67.1"

[rust]
channel = "stable"
description = "for BLFS 11.3"

# BLFS used to not install the FileCheck executable from llvm,
# so disabled codegen tests.  The assembly tests rely on FileCheck
# and cannot easily be disabled, so those will anyway fail if
# FileCheck has not been installed.
#codegen-tests = false

[target.x86_64-unknown-linux-gnu]
# NB the output of llvm-config (i.e. help options) may be
# dumped to the screen when config.toml is parsed.
llvm-config = "/usr/bin/llvm-config"

[target.i686-unknown-linux-gnu]
# NB the output of llvm-config (i.e. help options) may be
# dumped to the screen when config.toml is parsed.
llvm-config = "/usr/bin/llvm-config"


EOF

Compile Rust by running the following commands:

{ [ ! -e /usr/include/libssh2.h ] ||
  export LIBSSH2_SYS_USE_PKG_CONFIG=1; } &&
python3 ./x.py build
[Note]

Note

The test suite will generate some messages in the system log for traps on invalid opcodes, and for segmentation faults. In themselves these are nothing to worry about, just a way for the test to be terminated.

To run the tests (again using all available CPUs) issue:

python3 ./x.py test --verbose --no-fail-fast | tee rustc-testlog

If FileCheck from LLVM has not been installed, all 47 tests from the assembly suite will fail.

As with all large test suites, other tests might fail on some machines - if the number of additional failures is in the single digits, check the log for 'failures:' and review lines above that, particularly the 'stderr:' lines. Any mention of SIGSEGV or signal 11 in a failing test is a cause for concern.

If you get any other failing test which reports an issue number then you should search for that issue. For example, when rustc >= 1.41.1 was built with a version of sysllvm before 10.0 the test for issue 69225 failed https://github.com/rust-lang/rust/issues/69225 and that should be regarded as a critical failure (they released 1.41.1 because of it). Most other failures will not be critical.

Therefore, you should determine the number of failures.

The number of tests which passed and failed can be found by running:

grep '^test result:' rustc-testlog |
 awk '{sum1 += $4; sum2 += $6} END { print sum1 " passed; " sum2 " failed" }'

The other available fields are $8 for those which were ignored (i.e. skipped), $10 for 'measured' and $12 for 'filtered out' but both those last two are probably zero.

Now, as the root user, install the package:

[Note]

Note

If sudo or su is invoked for switching to the root user, ensure LIBSSH2_SYS_USE_PKG_CONFIG is correctly passed or the following command may completely rebuild this package. For sudo, use the --preserve-env=LIBSSH2_SYS_USE_PKG_CONFIG option. For su, do not use the - or --login.

python3 ./x.py install

Command Explanations

ln -svfn rustc-1.67.1 /opt/rustc: if this is not the first use of the /opt/rustc symlink, overwrite it by forcing, and use the '-n' flag to avoid getting confusing results from e.g. ls -l.

targets = "X86": this avoids building all the available linux cross-compilers (AArch64, MIPS, PowerPC, SystemZ, etc). Unfortunately, rust insists on installing source files for these below /opt/rustc/lib/src.

extended = true: this installs several tools (specified by the tools entry) alongside rustc.

tools = ["cargo", "clippy", "rustfmt"]: if the tools are not scecified, the absence of Miri now causes the install to fail. But Miri is not built in the stable channel. Some of the other tools are unlikely to be useful unless using (old) code analyzers or editing the standard library. This set match those from the 'default' profile in binary command rustup which are recommended for most users, except that the documentation was disabled at the start of the '[build]' section.

channel = "stable": this ensures only stable features can be used, the default in config.toml is to use development features, which is not appropriate for a released version.

[target.x86_64-unknown-linux-gnu]: the syntax of config.toml requires an llvm-config entry for each target for which system-llvm is to be used. Change the target to [target.i686-unknown-linux-gnu] if you are building on 32-bit x86. This whole section may be omitted if you wish to build against the shipped llvm, or do not have clang, but the resulting build will be larger and take longer.

export LIBSSH2_SYS_USE_PKG_CONFIG=1: Allow cargo to link to system libssh2.

--verbose: this switch can sometimes provide more information about a test which fails.

--no-fail-fast: this switch ensures that the test suite will not stop at the first error.

Configuring Rust

Configuration Information

If you installed rustc in /opt, you need to update the following configuration files so that rustc is correctly found by other packages and system processes.

As the root user, create the /etc/profile.d/rustc.sh file:

cat > /etc/profile.d/rustc.sh << "EOF"
# Begin /etc/profile.d/rustc.sh

pathprepend /opt/rustc/bin           PATH

# Include /opt/rustc/man in the MANPATH variable to access manual pages
pathappend  /opt/rustc/share/man     MANPATH

# End /etc/profile.d/rustc.sh
EOF

Immediately after installation, update the current PATH for your current shell as a normal user:

source /etc/profile.d/rustc.sh

Contents

Installed Programs: cargo-clippy, cargo-fmt, cargo, clippy-driver, rust-gdb, rust-gdbgui, rust-lldb, rustc, rustdoc, and rustfmt
Installed Libraries: librustc-driver-<16-byte-hash>.so, libstd-<16-byte-hash>.so, and libtest-<16-byte-hash>.so
Installed Directories: ~/.cargo, /opt/rustc, symbolic link to /opt/rustc-1.67.1

Short Descriptions

cargo-clippy

provides lint checks for a cargo package

cargo-fmt

formats all bin and lib files of the current crate using rustfmt

cargo

is the Package Manager for Rust

clippy-driver

provides lint checks for Rust

rust-gdb

is a wrapper script for gdb, pulling in Python pretty-printing modules installed in /opt/rustc-1.67.1/lib/rustlib/etc

rust-gdbgui

is a wrapper script for a graphical front end to gdb that runs in a browser

rust-lldb

is a wrapper script for LLDB (the LLVM debugger) pulling in the Python pretty-printing modules

rustc

is the rust compiler

rustdoc

generates documentation from rust source code

rustfmt

formats rust code

libstd-<16-byte-hash>.so

is the Rust Standard Library, the foundation of portable Rust software