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
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.71.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.
That can be achieved by using systemd-run command with
-p User=$(whoami)
and
-p AllowedCPUs=0-x
(with x
replaced with the number of CPU
cores you want to use minus one) options.
At the moment Rust does not
provide any guarantees of a stable ABI.
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 12.0
platform.
Package Information
-
Download (HTTP): https://static.rust-lang.org/dist/rustc-1.71.1-src.tar.xz
-
Download MD5 sum: b6f9973de878e37a589f0989e4138480
-
Download size: 145 MB
-
Estimated disk space required: 8.9 GB (292 MB installed); add
6.4 GB if running the tests
-
Estimated build time: 6.7 SBU (including download time; add
6.2 SBU for tests, both using parallelism=8)
Rust Dependencies
Required
CMake-3.27.2 and cURL-8.2.1
Note
An Internet connection is needed for building this package.
Recommended
libssh2-1.11.0 and LLVM-16.0.5 (built with
-DLLVM_LINK_LLVM_DYLIB=ON so that rust can link to system LLVM
instead of building its shipped version)
Note
If a recommended dependency is not installed, a shipped copy in
the Rustc source tarball will be built and used.
Optional
GDB-13.2 (used
by the test suite if it is present), git-2.41.0 (required by the test
suite), and libgit2
Editor Notes: https://wiki.linuxfromscratch.org/blfs/wiki/rust
Installation of Rust
Note
Currently the rust compiler produces SSE2 instructions for 32-bit
x86, causing the generated code to be 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.71.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.71.1 &&
ln -svfn rustc-1.71.1 /opt/rustc
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", "rustdoc", "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.71.1"
docdir = "share/doc/rustc-1.71.1"
[rust]
channel = "stable"
description = "for BLFS 12.0"
# 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
The test suite will generate some messages in the systemd journal 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:
SSL_CERT_DIR=/etc/ssl/certs \
python3 ./x.py test --verbose --no-fail-fast | tee rustc-testlog
Some ui
tests may fail (the number of
failures depends on the length of the absolute path to the
rustc-1.71.1-src
directory). These
failures can be identified by viewing the rustc-testlog
file and search for the
note: the full type name has been
written to
... messages and they can be safely ignored.
If FileCheck from
LLVM has not been installed, all
47 tests from the “assembly” suite will fail.
On some systems, scripting the tests may result in the tests
hanging on test:
combine_install_with_separate_uninstall
. If this happens,
the problem can be worked around by pressing the Enter key. The
test can also be removed with:
sed -e '/runtest combine_install_with/s/^/#/g' -i src/tools/rust-installer/test.sh
As with all large test suites, other tests might fail on some
machines - if the number of additional failures is low, 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
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
The building system attempts to install some files twice, and
during the second attempt it renames the old one (installed in the
first attempt) with the .old
suffix.
As the root
user, remove these
files:
find /opt/rustc-1.71.1 -name "*.old" -delete
Still as the root
user, symlink a
Zsh completion file into the
correct location:
install -vdm755 /usr/share/zsh/site-functions &&
ln -sfv /opt/rustc/share/zsh/site-functions/_cargo \
/usr/share/zsh/site-functions
Command Explanations
ln -svfn rustc-1.71.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", "rustdoc",
"rustfmt"]
: only build the tools from the 'default' profile
in binary command rustup which are recommended for
most users. The other tools are unlikely to be useful unless using
(old) code analyzers or editing the standard library.
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.
SSL_CERT_DIR=/etc/ssl/certs
: Work around
an issue causing test failures with the CA certificate store layout
used by make-ca-1.12.
--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.