source: general/prog/rust.xml@ 67687b75

<?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        "7272ddba14f512e6d2612ef60460bed8">
  <!ENTITY rust-size          "53 MB">
  <!ENTITY rust-buildsize     "4.1 GB (437 MB installed), (add 1.2GB for tests) including 226MB of ~/.cargo files for both the builder and root (from the install)">
  <!ENTITY rust-time          "48 SBU (add 12 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 several cargo files (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>
        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. Also, both the builder
        and the user running the install will need to download the cargo crates
        if they are not already present in <filename>~/.cargo</filename>.
      </para>
      <para>
        If you use a DESTDIR method to install, you will only need to download
        the crates once, for the build, saving about one-third of the build and
        install time (but using extra space for the install). Similarly if you
        were to build as root, or if your user is allowed to run <command>sudo
        ./x.py install</command> - but those methods are dangerous.
      </para>
    </note>

    &lfs82_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"/>,
<!-- if changing this to use python3, also add python2 as a required
 dependency for firefox, because at the moment it picks that up from here -->
      <xref linkend="python2"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="gdb"/> (used by debuginfo-gdb in 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 used
        by two 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"

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

[install]
prefix = "/usr"
docdir = "share/doc/rustc-&rust-version;"

[rust]
channel = "stable"
rpath = false
EOF</userinput></screen>

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

<screen><userinput>./x.py build</userinput></screen>

    <para>
      To run the tests issue
      <command>./x.py test --verbose --no-fail-fast &gt;../rustc-testlog</command>:
      as with the build, that will use all available CPUs.  This runs many suites
      of tests (in an apparently random order), three may fail:
      compile-fail/issue-37131.rs and run-make/target-without-atomics both try to
      compile for the thumbv6m-none-eabi target, but the BLFS build does not cater for
      that, and all 105 tests in debuginfo-gdb will fail if
      <application>gdb</application> has not been installed. Several other tests in
      run-make can also fail. With <application>glibc-2.27</application> the stack
      guard page has been moved to just beyond the stack, instead of within it. That
      causes three run-pass tests (out-of-stack.rs, stack-probes-lto.rs,
      stack-probes.rs) to 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 14854 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>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>./x.py 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).
    </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>--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>
      <option>PYTHON=/usr/bin/python3 ... tee buildlog</option>: Because rust
      can use <application>Python3</application> which was installed in LFS,
      this command tells it to use that instead of the deprecated
      <application>Python2</application>. For the moment this should be regarded
      as experimental and problems may be encountered. Because
      <application>rust</application> will use all CPUs, if an error happened the
      message may have scrolled out of the terminal's buffer. Logging makes it
      possible to find out what was reported.
    </para>

  </sect2>

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

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

      <seglistitem>
        <seg>
          cargo, rls, rust-gdb, rust-lldb, rustc, rustdoc.
        </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">
        <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="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 Python wrapper script for gdb.
          </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 Python wrapper script for LLDB (the LLVM debugger).
          </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="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>