Rustc-1.58.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 and many cargo crates (these are actually .tar.gz source
          archives) at the start of the build, so you cannot compile it
          without an internet connection.
        
        
          These crates will then remain in various forms (cache, directories
          of extracted source), in ~/.cargo for
          ever more. It is common for large rust packages to use multiple versions of some
          crates. If you purge the files before updating this package, very
          few crates will need to be updated by the packages in this book
          which use it (and they will be downloaded as required). But if you
          retain an older version as a fallback option and then use it (when
          not building in /usr), it is likely that it will then have to
          re-download some crates. For a full download (i.e. starting with an
          empty or missing ~/.cargo)
          downloading the external cargo files for this version only takes a
          minute or so on a fast network.
        
        
          ![[Note]](../images/note.png) 
          
            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.58.1-build2.
          
          
            If you prefer, you can of course change the prefix to
            /usr and omit the ldconfig and the actions to add
            rustc to the PATH.
          
         
        
          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]](../images/note.png) 
          
            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.
          
          
            Unusually, a DESTDIR-style method is being used to install this
            package. This is because running the install as root not only
            downloads all of the cargo files again (to /root/.cargo), it then spends a very long time
            recompiling. Using this method saves a lot of time, at the cost
            of extra disk space.
          
         
        
          This package is known to build and work properly using an LFS-11.1
          platform.
        
        
          Package Information
        
        
          
            - 
              
                Download (HTTP): https://static.rust-lang.org/dist/rustc-1.58.1-src.tar.gz
               
- 
              
                Download MD5 sum: 275744c77bf07fd07abe0fd829e6dafb
               
- 
              
                Download size: 176 MB
               
- 
              
                Estimated disk space required: 8.7 GB (417 MB installed)
                including 296 MB of ~/.cargo files for the user building
                this. Add 6.5 GB including extra 281 MB of ~/.cargo files if
                running the tests
               
- 
              
                Estimated build time: 25 SBU (including download time; add 13
                SBU for tests, both on a 4-core machine)
               
 
        
          Rust Dependencies
        
        
          Required
        
        
          cURL-7.81.0, CMake-3.22.2, and libssh2-1.10.0
        
        
          Recommended
        
        
          clang from LLVM-13.0.1 (built with
          -DLLVM_LINK_LLVM_DYLIB=ON so that rust can link to system LLVM
          instead of building its shipped version)
        
        
          Optional
        
        
          GDB-11.2 (used
          by the testsuite if it is present)
        
        
          User Notes: https://wiki.linuxfromscratch.org/blfs/wiki/rust
        
       
      
        
          Installation of Rust
        
        
          To install into the /opt directory,
          remove the symlink and create a new directory (i.e. with a
          different name if trying a modified build). As the root user:
        
        mkdir /opt/rustc-1.58.1             &&
ln -svfin rustc-1.58.1 /opt/rustc
        
          ![[Note]](../images/note.png) 
          
            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 example using shipped LLVM
# e.g. if not installing clang, or using a version before 10.0
[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 cargo as well as rust
extended = true
[install]
prefix = "/opt/rustc-1.58.1"
docdir = "share/doc/rustc-1.58.1"
[rust]
channel = "stable"
rpath = false
# BLFS does not install the FileCheck executable from llvm,
# so disable codegen tests
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:
        
        export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi" &&
python3 ./x.py build --exclude src/tools/miri
        
          ![[Note]](../images/note.png) 
          
            Note
          
          
            The testsuite 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 issue python3 ./x.py
          test --verbose --no-fail-fast | tee rustc-testlog:
          as with the build, that will use all available CPUs.
        
        
          At a minimum, 49 tests will fail: all 48 of the tests in the
          “assembly” suite which are not skipped
          (various lints cause the warnings in these tests to be treated as
          errors), and run-make-fulldeps/long-linker-command-lines.
        
        
          As with all large testsuites, 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 failed can be found by running:
        
        grep '^test result:' rustc-testlog | awk  '{ sum += $6 } END { print sum }'
        
          And similarly if you care about how many tests passed use $4, for
          those which were ignored (i.e. skipped) use $8 (and $10 for
          'measured', $12 for 'filtered out' but both are probably zero).
        
        
          Still as your normal user, do a DESTDIR install:
        
        export LIBSSH2_SYS_USE_PKG_CONFIG=1 &&
DESTDIR=${PWD}/install python3 ./x.py install &&
unset LIBSSH2_SYS_USE_PKG_CONFIG
        
          Now, as the root user install the
          files from the DESTDIR:
        
        chown -R root:root install &&
cp -a install/* /
       
      
        
          Command Explanations
        
        
          ln -svfn rustc-1.58.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 Cargo alongside Rust.
        
        
          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.
        
        
          rpath = false: by
          default, rust can be
          run from where it was built, without being installed. That adds
          DT_RPATH entries to all of the ELF files, which produces very messy
          output from ldd,
          showing the libraries in the place they were built, even if they
          have been deleted from there after the install.
        
        
          [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 RUSTFLAGS="$RUSTFLAGS -C
          link-args=-lffi": This adds a link to libffi to any
          RUSTFLAGS you may already be passing to the build. On some systems,
          linking fails to include libffi unless this is used. The reason why
          this is needed is not clear.
        
        
          --exclude
          src/tools/miri: For a long time, the miri crate (an
          interpreter for the Midlevel Intermediate Representation) has
          failed to build on releases. It is optional, but the failure
          messages can persuade people that the whole build failed. However,
          although it is not built in the main compile, with rustc-1.35.0 it
          now got compiled during the install, but it was broken in that
          version. Omitting it should save a little time.
        
        
          --verbose: this
          switch can sometimes provide more information about a test which
          fails.
        
        
          --no-fail-fast: this
          switch ensures that the testsuite will not stop at the first error.
        
        
          export
          LIBSSH2_SYS_USE_PKG_CONFIG=1: On some systems,
          cairo fails to link during the install because it cannot find
          libssh2. This seems to fix it, but again the reason why the problem
          occurs is not understood.
        
        
          DESTDIR=${PWD}/install python3 ./x.py
          install: This effects a DESTDIR-style install in
          the source tree,creating an install
          directory. Note that DESTDIR installs need an absolute path,
          passing 'install' will not work.
        
        
          chown -R root:root
          install: the DESTDIR install was run by a regular
          user, who owns the files. For security, change their owner before
          doing a simple copy to install them.
        
       
      
        
          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, update the
            /etc/ld.so.conf file and the
            dynamic linker's run-time cache file:
          
          cat >> /etc/ld.so.conf << EOF
# Begin rustc addition
/opt/rustc/lib
# End rustc addition
EOF
ldconfig
          
            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-miri
              (optional), cargo, clippy-driver, miri (optional), rls,
              rust-demangler, rust-gdb, rust-gdbgui, rust-lldb, rustc,
              rustdoc, 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.58.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-miri
                   | 
                    is for use by Miri to interpret bin crates and tests
                   | 
              
                | 
                    cargo
                   | 
                    is the Package Manager for Rust
                   | 
              
                | 
                    clippy-driver
                   | 
                    provides lint checks for Rust
                   | 
              
                | 
                    miri
                   | 
                    is an interpreter for Rust's mid-level intermediate
                    representation (MIR). It is broken in this version
                   | 
              
                | 
                    rls
                   | 
                    is the Rust Language Server. This can run in the
                    background to provide IDEs, editors, and other tools with
                    information about Rust programs
                   | 
              
                | 
                    rust-analyzer
                   | 
                    is an implementation of Language Server Protocol for the
                    Rust programming language.
                   | 
              
                | 
                    rust-gdb
                   | 
                    is a wrapper script for gdb, pulling in Python
                    pretty-printing modules installed in /opt/rustc-1.58.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
                   | 
            
          
         
       
      
        Last updated on