%general-entities; ]> $Date$ 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. 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-&rust-version;-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. 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. 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. &lfs112_checked; Package Information Download (HTTP): Download (FTP): Download MD5 sum: &rust-md5sum; Download size: &rust-size; Estimated disk space required: &rust-buildsize; Estimated build time: &rust-time; Rust Dependencies Required , , and Recommended (built with -DLLVM_LINK_LLVM_DYLIB=ON so that rust can link to system LLVM instead of building its shipped version) Optional (used by the testsuite if it is present) User Notes: 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-&rust-version; 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 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-&rust-version; && ln -svfn rustc-&rust-version; /opt/rustc 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-&rust-version;" docdir = "share/doc/rustc-&rust-version;" [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 The testsuite will generate some messages in the system log 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 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, 51 tests will fail: all 46 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 5 other tests, 4 of which involve the rustdoc-ui/issue-98690.rs file, and another one, 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 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/* / ln -svfn rustc-&rust-version; /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. Even if this switch is not given, miri is not installed. --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. 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 /etc/ld.so.conf 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 Installed Programs Installed Libraries Installed Directories cargo-clippy, cargo-fmt, cargo-miri (optional), cargo, clippy-driver, miri (optional), rls, rust-analyzer, rust-demangler, rust-gdb, rust-gdbgui, rust-lldb, rustc, rustdoc, and rustfmt librustc-driver-<16-byte-hash>.so, libstd-<16-byte-hash>.so, and libtest-<16-byte-hash>.so ~/.cargo, /opt/rustc, symbolic link to /opt/rustc-&rust-version; Short Descriptions cargo-clippy provides lint checks for a cargo package cargo-clippy cargo-fmt formats all bin and lib files of the current crate using rustfmt cargo-fmt cargo-miri is for use by Miri to interpret bin crates and tests. It is not installed by default. cargo-miri cargo is the Package Manager for Rust cargo clippy-driver provides lint checks for Rust clippy-driver miri is an interpreter for Rust's mid-level intermediate representation (MIR). It is not installed by default. miri rls is the Rust Language Server. This can run in the background to provide IDEs, editors, and other tools with information about Rust programs rls rust-analyzer is an implementation of Language Server Protocol for the Rust programming language. rust-analyzer rust-demangler converts a list of Rust mangled symbols into a corresponding list of demangled symbols rust-demangler rust-gdb is a wrapper script for gdb, pulling in Python pretty-printing modules installed in /opt/rustc-&rust-version;/lib/rustlib/etc rust-gdb rust-gdbgui is a wrapper script for a graphical front end to gdb that runs in a browser rust-gdbgui rust-lldb is a wrapper script for LLDB (the LLVM debugger) pulling in the Python pretty-printing modules rust=lldb rustc is the rust compiler rustc rustdoc generates documentation from rust source code rustdoc rustfmt formats rust code rustfmt libstd-<16-byte-hash>.so is the Rust Standard Library, the foundation of portable Rust software libstd-<16-byte-hash>.so