#### Beyond Linux® From Scratch (systemd Edition) - Version r13.0-491

### Chapter 13. Programming

- Prev

  Ruby-4.0.3

- Next

  rust-bindgen-0.72.1

- Up
- Home

# Rustc-1.95.0

## Introduction to Rust

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

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 must have an internet connection to build this package.

### 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 they will not be usable and will waste space. The editors recommend placing the files in the `/opt` directory. In particular, if you have to rebuild this package 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 installation to leave a broken cargo program. If this occurs, you should either remove the existing installation first, or use a different prefix such as /opt/rustc-1.95.0-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 ./x.py and using the `CARGO_BUILD_JOBS=<N>` environment variable. 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. If your machine lacks DRAM (typically, less than 2 GB DRAM per core), that might be an alternative to taking CPUs offline. Read the section called “Use Linux Control Group to Limit the Resource Usage” for information on how to use a cgroup.

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 are going to develop rust crates, this build may not be sufficient 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.

### Note

Development versions of BLFS may not build or run some packages properly if LFS or dependencies have been updated since the most recent stable versions of the books.

### Package Information

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

- Download MD5 sum: c206536bb0e11bbf2ebae91504096e34

- Download size: 228 MB

- Estimated disk space required: 10 GB (324 MB installed); add 11 GB if running the tests

- Estimated build time: 10 SBU (including download time; add 15 SBU for tests, both using parallelism=8)

### Additional Downloads

- OpenSSL Rust binding updated to support OpenSSL 4: https://github.com/lfs-book/rust-openssl/archive/v0.10.78/rust-openssl-v0.10.78.tar.gz

- Download MD5 sum: 8bfcc36cba65c98380f7ac1ec07efdb4

### Note

On GitHub we've forked the upstream repository into our own `lfs-book` namespace and recreated a tag for the release. This is done to ensure the downloaded tarball file name to be correct and consistent (i.e. it shouldn't change when using the browser instead of a tool like wget). Our tag and the upstream release tag are on the same commit, so we've not introduced any change to the tarball content except the name of its top-level directory (that Git does not track).

### Rust Dependencies

#### Required

CMake-4.3.2 and cURL-8.19.0

### Note

An Internet connection is needed for building this package. The system certificate store may need to be set up with make-ca-1.16.1 before building this package.

#### Recommended

libssh2-1.11.1 and LLVM-22.1.0 (built with -D LLVM_LINK_LLVM_DYLIB=ON so that rust can link to the system installed version of LLVM instead of building its shipped version)

### Note

If a recommended dependency is not installed, you will need to modify the instructions to build and use a shipped copy in the Rustc source tarball instead. See the Command Explanations section for more details.

#### Optional

GDB-17.1 (used by the test suite if it is present), git-2.53.0 (required by the test suite), cranelift, jemalloc, libgccjit (read the Command Explanations in GCC-15.2.0), and libgit2

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

## Installation of Rust

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.95.0      &&
    ln -svfn rustc-1.95.0 /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 `bootstrap.toml` file which will configure the build.

    cat << EOF > bootstrap.toml
    # See bootstrap.toml.example for more possible options,
    # and see src/bootstrap/defaults/bootstrap.dist.toml for a few options
    # automatically set when building from a release tarball
    # (unfortunately, we have to override many of them).

    # Tell x.py that the editors have reviewed the content of this file
    # and updated it to follow the major changes of the building system,
    # so x.py will not warn users to review that information.
    change-id = 148671

    [llvm]
    # When using the system installed copy of LLVM, prefer the shared libraries
    link-shared = true

    # If building the shipped LLVM source, only enable the x86 target
    # instead of all the targets supported by LLVM.
    targets = "X86"

    [build]
    description = "for BLFS r13.0-491"

    # Omit the documentation to save time and space (the default is to build them).
    docs = false

    # Only install these extended tools. Cargo, clippy, rustdoc, and rustfmt
    # are installed by a default rustup installation, and rust-src is needed
    # to build the Rust code in Linux kernel (in case you need such a kernel
    # feature).
    tools = ["cargo", "clippy", "rustdoc", "rustfmt", "src"]

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

    [rust]
    channel = "stable"

    # Enable the same optimizations as the official upstream build.
    lto = "thin"
    codegen-units = 1

    # Don't build llvm-bitcode-linker which is only useful for the NVPTX
    # backend that we don't enable.
    llvm-bitcode-linker = false

    [target.x86_64-unknown-linux-gnu]
    llvm-config = "/usr/bin/llvm-config"

    [target.i686-unknown-linux-gnu]
    llvm-config = "/usr/bin/llvm-config"
    EOF

Use a newer version of the OpenSSL Rust binding to allow building this package with OpenSSL 4:

    tar xf ../rust-openssl-v0.10.78.tar.gz &&

    cat >> src/tools/cargo/Cargo.toml << EOF &&
    [patch.crates-io]
    openssl = { path = "../../../rust-openssl-0.10.78/openssl" }
    openssl-sys = { path = "../../../rust-openssl-0.10.78/openssl-sys" }
    EOF

    sed -ri src/tools/cargo/Cargo.lock \
        -e '/name = "openssl-sys"/,/^$/{/source|checksum/d;s/0.9.111/0.9.114/}' \
        -e '/name = "openssl"/,/^$/{/source|checksum/d;s/0.10.75/0.10.78/}'     \
        -e '/name = "openssl-macros"/,/^$/{/source|checksum/d}'

Compile Rust by running the following commands:

    export LIBSSH2_SYS_USE_PKG_CONFIG=1
    export LIBSQLITE3_SYS_USE_PKG_CONFIG=1
    ./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, and they are just a way for a test to be terminated.

To run the tests, issue:

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

In the `rustdoc-ui` tests, the test named `track-diagnostics.rs` is known to fail because it hard codes paths non-exist on LFS, and the test named `ice-bug-report-url.rs` is known to fail for unknown reason. In the `run-make` tests, the test named `remap-path-prefix-std` is known to fail because it does not work with LTO enabled, the test named `rustdoc-target-modifiers` is known to fail because we've not enabled the AArch64 target in LLVM-22.1.0, and the test named `short-ice` is known to fail for unknown reason.

As with all large test suites, some 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 a 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` and `LIBSQLITE3_SYS_USE_PKG_CONFIG` are correctly passed or the following command may rebuild cargo with shipped copies of libssh2 and sqlite. For sudo, use the `--preserve-env=LIB{SSH2,SQLITE3}_SYS_USE_PKG_CONFIG` option. For su, do not use the `-` or `--login` options.

    ./x.py install

Still as the `root` user, fix the installation of the documentation, symlink a Zsh completion file into the correct location, and move a Bash completion file into the location recommended by the Bash completion maintainers:

    rm -fv /opt/rustc-1.95.0/share/doc/rustc-1.95.0/*.old   &&
    install -vm644 README.md                                \
                   /opt/rustc-1.95.0/share/doc/rustc-1.95.0 &&

    install -vdm755 /usr/share/zsh/site-functions      &&
    ln -sfv /opt/rustc/share/zsh/site-functions/_cargo \
            /usr/share/zsh/site-functions

    mv -v /etc/bash_completion.d/cargo /usr/share/bash-completion/completions

Finally, unset the exported environment variables:

    unset LIB{SSH2,SQLITE3}_SYS_USE_PKG_CONFIG

## Command Explanations

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

`tools = ["cargo", "clippy", "rustdoc", "rustfmt"]`: only build the tools from the 'default' profile from the 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 that only stable features are used. The default in `bootstrap.toml` is to use development features, which are not appropriate for a released version of rust.

`[target.x86_64-unknown-linux-gnu]`: the syntax of `bootstrap.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 should be omitted if you wish to build against the shipped llvm, but the resulting build will be larger and take longer.

export LIBSSH2_SYS_USE_PKG_CONFIG=1: Allow cargo to link to the system installed copy of libssh2. Omit this command if you've not installed libssh2-1.11.1.

export LIBSQLITE3_SYS_USE_PKG_CONFIG=1: Allow cargo to link to the system installed copy of sqlite.

`--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

    # 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 and libstd-<16-byte-hash>.so
Installed Directories: ~/.cargo, /opt/rustc, symbolic link to /opt/rustc-1.95.0

### Short Descriptions

cargo-clippy | performs lint checks on 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 | performs lint checks on Rust code
rust-gdb | is a wrapper script for gdb which pulls in the Python pretty-printing modules installed in `/opt/rustc-1.95.0/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) which pulls 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

- Prev

  Ruby-4.0.3

- Next

  rust-bindgen-0.72.1

- Up
- Home