source: general/prog/rust.xml@ 31ee0ed

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY rust-download-http "https://static.rust-lang.org/dist/rustc-&rust-version;-src.tar.gz">
  <!ENTITY rust-download-ftp  " ">
  <!ENTITY rust-md5sum        "6790c24fe5e8fb5a5f7efbfbcc6fea65">
  <!ENTITY rust-size          "101 MB">
  <!ENTITY rust-buildsize     "6.5 GB (679 MB installed) including 270MB of ~/.cargo files for the user building this (add 1.4GB if running the tests)">
  <!ENTITY rust-time          "27 SBU (add 13 SBU for tests, both with 4 processors)">
]>

<sect1 id="rust" xreflabel="rustc-&rust-version;">
  <?dbhtml filename="rust.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Rustc-&rust-version;</title>

  <indexterm zone="rust">
    <primary sortas="a-rust">Rust</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Rust</title>

    <para>
      The <application>Rust</application> programming language is designed
      to be a safe, concurrent, practical language.
    </para>

    <para>
      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.
    </para>

    <para>
      The current <application>rustbuild</application> build-system will use
      all available processors, although it does not scale well and often falls
      back to just using one core while waiting for a library to compile.
    </para>

    <para>
      At the moment <application>Rust</application> does not provide any
      guarantees of a stable ABI.
    </para>

    <note>
      <para>
        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.
      </para>
      <para>
        Repeated builds of this package on the same machine show a wide range
        of build times. Some of this might be due to variations in downloading
        the required cargo files if they are not already present, but this does
        not seem to adequately explain the variations.
      </para>
      <para>
        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 <filename>/root/.cargo</filename>), it then spends
        a very long time recompiling. Using this method saves a lot of time, at
        the cost of extra disk space.
      </para>
    </note>

    &lfs83_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&rust-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&rust-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &rust-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &rust-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &rust-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &rust-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Rust Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="curl"/>,
      <xref linkend="cmake"/>,
      <xref linkend="libssh2"/>, and
      <xref linkend="python2"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <package>clang</package> from <xref linkend="llvm"/>
      (built with -DLLVM_LINK_LLVM_DYLIB=ON)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="gdb"/> (recommended if running the testsuite)
    </para>

    <para condition="html" role="usernotes">
      User Notes: <ulink url="&blfs-wiki;/rust"/>
    </para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of Rust</title>

    <note>
      <para>
        This package is updated on a six-weekly release cycle. Because it is
        such a large and slow package to build, and is at the moment only required
        by five packages in this book, the BLFS editors take the view that it
        should only be updated when that is necessary.
      </para>
    </note>

    <para>
      First create a suitable <filename>config.toml</filename> file
      which will configure the build :
    </para>

<screen><userinput>cat &lt;&lt; EOF &gt; config.toml
# see config.toml.example for more possible options
[llvm]
targets = "X86"

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

[build]
# install cargo as well as rust
extended = true

[install]
prefix = "/usr"
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]
# delete this *section* if you are not using system llvm.
# 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</userinput></screen>

    <para>
      Now install <application>Rust</application> by running the following
      commands:
    </para>

<screen><userinput>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi" &amp;&amp;
./x.py build</userinput></screen>

    <para>
      The build will report it failed to compile <filename>miri</filename>
      because of multiple potential crates for `log`, but that should be followed
      by a message that the build completed successfully.
    </para>

    <caution>
      <para>
        On AMD Ryzen processors (family 17h), the non-optimized version of libstd
        which is compiled at the start of the tests contains one or more opcodes
        which are not implemented on this CPU family. These will be logged in the
        <phrase revision="sysv">system log</phrase>
        <phrase revision="systemd">systemd journal</phrase>
        and will be followed a few minutes later by segmentation faults. Despite
        that, the tests continue to run, apparently normally. But the system may
        reboot before the tests have completed. The normal optimized libraries
        run without this problem.
      </para>
      <para>
        A mitigation is to install gdb
        <!-- systemd apparently handles this with systemd-coredump -->
        <phrase revision="sysv">and to run the tests with 'ulimit -C disabled'</phrase>
        but this does not always prevent the system rebooting.
      </para>
    </caution>

    <para>
      To run the tests issue
      <command>./x.py test --verbose --no-fail-fast | tee rustc-testlog</command>:
      as with the build, that will use all available CPUs.  This runs many suites
      of tests (in an apparently random order), several will fail in BLFS:
      compile-fail/issue-37131.rs require a thumbv6m-none-eabi compiler but the
      BLFS build does not cater for
      that, ui/issue-49851/compiler-builtins-error.rs and ui/issue-50993.rs (both
      run twice) require a thumbv7em-none-eabihf compiler, and seven tests in
      debuginfo-gdb will fail because gdb-8.1 changed the output format.  If
      <application>gdb</application> has not been installed, most of the gdb tests
      will fail.
    </para>

    <para>
      If you wish to look at the numbers for the results, you can find the total
      number of tests which were considered by running:
    </para>

<screen><command>grep 'running .* tests' rustc-testlog | awk '{ sum += $2 } END { print sum }'</command></screen>

    <para>
      That should report 17101 tests. Similarly, the total tests which failed can
      be found by running:
    </para>

<screen><command>grep '^test result:' rustc-testlog | awk  '{ sum += $6 } END { print sum }'</command></screen>

    <para>
      And similarly for the tests which 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). The breakdown does not match the overall total.
    </para>

    <para>
      Still as your normal user, do a DESTDIR install:
    </para>

<screen><userinput>export LIBSSH2_SYS_USE_PKG_CONFIG=1 &amp;&amp;
DESTDIR=${PWD}/install ./x.py install &amp;&amp;
unset LIBSSH2_SYS_USE_PKG_CONFIG</userinput></screen>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user
      install the files from the DESTDIR:
    </para>

<screen role="root"><userinput>chown -R root:root install &amp;&amp;
cp -a install/* /</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>targets = "X86"</command>: this avoids building all the available
      linux cross-compilers (Aarch64, MIPS, PowerPC, SystemZ, etc). Unfortunately,
      rust insists on installing source files for these below
      <filename class="directory">/usr/lib/rustlib/src</filename>.
    </para>

    <para>
      <command>extended = true</command>: this installs Cargo alongside Rust.
    </para>

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

    <para>
      <command>rpath = false</command>: by default, <command>rust</command> 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
      <command>ldd</command>, showing the libraries in the place they were built,
      even if they have been deleted from there after the install.
    </para>

    <para>
      <command>[target.x86_64-unknown-linux-gnu]</command>: the syntax of
      <filename>config.toml</filename> requires an <literal>llvm-config</literal>
      entry for each target for which system-llvm is to be used. Change the target
      to <literal>[target.i686-unknown-linux-gnu]</literal> 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.
    </para>

    <para>
      <command>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi"</command>:
      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.
    </para>

    <para>
      <command>--verbose</command>: this switch can sometimes provide more
      information about a test which fails.
    </para>

    <para>
      <command>--no-fail-fast</command>: this switch ensures that the testsuite
      will not stop at the first error.
    </para>

    <para>
      <command>export LIBSSH2_SYS_USE_PKG_CONFIG=1</command>: 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.
    </para>

    <para>
      <command>DESTDIR=${PWD}/install ./x.py install</command>: This effects a
      DESTDIR-style install in the source tree,creating an <filename
      class="directory">install</filename> directory. Note that DESTDIR installs
      need an absolute path, passing 'install' will not work.
    </para>

    <para>
      <command>chown -R root:root install</command>: 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.
    </para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          cargo-clippy, cargo-fmt, cargo, clippy-driver, rls, rust-gdb, rust-lldb, rustc, rustdoc, rustfmt.
        </seg>
        <seg>
          Many lib*&lt;16-byte-hash&gt;.so libraries.
        </seg>
        <seg>
          ~/.cargo,
          /usr/lib/rustlib,
          /usr/share/doc/rustc-&rust-version;, and
          /usr/share/zsh/site-functions/
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="cargo-clippy">
        <term><command>cargo-clippy</command></term>
        <listitem>
          <para>
            provides lint checks for a cargo package.
          </para>
          <indexterm zone="rust cargo-clippy">
            <primary sortas="b-cargo-clippy">cargo-clippy</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="cargo-fmt">
        <term><command>cargo-fmt</command></term>
        <listitem>
          <para>
            formats all bin and lib files of the current crate using
            rustfmt.
          </para>
          <indexterm zone="rust cargo-fmt">
            <primary sortas="b-cargo-fmt">cargo-fmt</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="cargo">
        <term><command>cargo</command></term>
        <listitem>
          <para>
            is the Package Manager for Rust.
          </para>
          <indexterm zone="rust cargo">
            <primary sortas="b-cargo">cargo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="clippy-driver">
        <term><command>clippy-driver</command></term>
        <listitem>
          <para>
            provides lint checks for Rust.
          </para>
          <indexterm zone="rust clippy-driver">
            <primary sortas="b-clippy-driver">clippy-driver</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rls">
        <term><command>rls</command></term>
        <listitem>
          <para>
            is the Rust Language Server. This can run in the background to
            provide IDEs, editors, and other tools with information about Rust
            programs.
          </para>
          <indexterm zone="rust rls">
            <primary sortas="b-rls">rls</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rust-gdb">
        <term><command>rust-gdb</command></term>
        <listitem>
          <para>
            is a wrapper script for gdb, pulling in Python
            pretty-printing modules installed in <filename
            class="directory">/usr/lib/rustlib/etc</filename>.
          </para>
          <indexterm zone="rust rust-gdb">
            <primary sortas="b-rust-gdb">rust-gdb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rust-lldb">
        <term><command>rust-lldb</command></term>
        <listitem>
          <para>
            is a wrapper script for LLDB (the LLVM debugger)
            pulling in the Python pretty-printing modules.
          </para>
          <indexterm zone="rust rust-lldb">
            <primary sortas="b-rust-lldb">rust=lldb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rustc">
        <term><command>rustc</command></term>
        <listitem>
          <para>
            is the rust compiler.
          </para>
          <indexterm zone="rust rustc">
            <primary sortas="b-rustc">rustc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rustdoc">
        <term><command>rustdoc</command></term>
        <listitem>
          <para>
            generates documentation from rust source code.
          </para>
          <indexterm zone="rust rustdoc">
            <primary sortas="b-rustdoc">rustdoc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rustfmt">
        <term><command>rustfmt</command></term>
        <listitem>
          <para>
            formats rust code.
          </para>
          <indexterm zone="rust rustfmt">
            <primary sortas="b-rustfmt">rustfmt</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libstd">
        <term><filename class="libraryfile">libstd-&lt;16-byte-hash&gt;.so</filename></term>
        <listitem>
          <para>
            is the Rust Standard Library, the foundation of portable Rust software.
          </para>
          <indexterm zone="rust libstd">
            <primary sortas="c-libstd">libstd-&lt;16-byte-hash&gt;.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect2>
</sect1>