Index: general/prog/rust.xml
===================================================================
--- general/prog/rust.xml	(revision 0639bb657e7b8149944d10b18be7904ccb79b77e)
+++ general/prog/rust.xml	(revision 4c6edaca9db100af4aa24fc599dedaebbf41041a)
@@ -7,8 +7,8 @@
   <!ENTITY rust-download-http "https://static.rust-lang.org/dist/rustc-&rust-version;-src.tar.gz">
   <!ENTITY rust-download-ftp  "">
-  <!ENTITY rust-md5sum        "c11d94d9e62f71838b20058f0797357a">
-  <!ENTITY rust-size          "28 MB">
-  <!ENTITY rust-buildsize     "1.5 GB (208 MB installed) plus 118MB for cargo files">
-  <!ENTITY rust-time          "14 SBU (with 4 processors)">
+  <!ENTITY rust-md5sum        "75e779670ac79edf023497a9c37eb35d">
+  <!ENTITY rust-size          "48 MB">
+  <!ENTITY rust-buildsize     "4.2 GB (362 MB installed), (add 0.6GB for tests) plus 273MB for ~/.cargo files">
+  <!ENTITY rust-time          "33 SBU (add 14 SBU for tests, both with 4 processors)">
 ]>
 
@@ -51,10 +51,8 @@
     <para>
       At the moment <application>Rust</application> does not provide any
-      guarantees of a stable ABI, and it is likely that the next few versions
-      of <application>firefox</application> will each require the latest version
-      of <application>Rust</application>.
-    </para>
-
-    &lfs80_checked;
+      guarantees of a stable ABI.
+    </para>
+
+    &lfs81_checked;
 
     <bridgehead renderas="sect3">Package Information</bridgehead>
@@ -97,19 +95,11 @@
     <para role="required">
       <xref linkend="curl"/>,
-      <xref linkend="cmake"/> (if not using the recommended <xref linkend="llvm-old"/>),
+      <xref linkend="cmake"/>,
       <xref linkend="python2"/>
-    </para>
-
-    <bridgehead renderas="sect4">Recommended</bridgehead>
-    <para role="recommended">
-      <!-- acceptable versions of llvm are listed in the tests
-           of LLVM_VERSION in configure, currently 3.{7-9}*    -->
-      <xref linkend="llvm-old"/>
     </para>
 
     <bridgehead renderas="sect4">Optional</bridgehead>
     <para role="optional">
-      <xref linkend="gdb"/> (often required for the testsuite, but some of the
-      gdb tests may still fail),
+      <xref linkend="gdb"/> (used by debuginfo-gdb in the testsuite),
       <xref linkend="ninja"/>
     </para>
@@ -123,29 +113,69 @@
     <title>Installation of Rust</title>
 
-    <para>
-      Install <application>Rust</application> by running the following
+    <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 one package 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 src/bootstrap/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-1.19.0"
+channel = "stable"
+EOF</userinput></screen>
+
+    <para>
+      Now install <application>Rust</application> by running the following
       commands:
     </para>
 
-<screen><userinput>./configure --prefix=/usr             \
-            --llvm-root=/opt/llvm3    \
-            --enable-llvm-link-shared \
-            --docdir=/usr/share/doc/rustc-&rust-version; &amp;&amp;
-./x.py build</userinput></screen>
-
-    <para>
-      The testsuite in this package selects random subsets of the
-      possible tests.  There is no correlation between how long a
-      particular run of the testsuite takes, and how many tests
-      were run. On occasion, the chosen tests will run in much
-      less than 1.0 SBU, on other occasions they may take more
-      than 20 SBU. Although it is normal to run the testsuite for
-      a compiler, in this case that is very hard to recommend.
-    </para>
-
-    <para>
-      Nevertheless, if you insist on running the tests issue
-      <command>./x.py test</command>: as with the build, that will
-      use all available CPUs.
+<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 maniy 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.
+    </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 14029 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>
 
@@ -154,8 +184,5 @@
     </para>
 
-<screen role="root"><userinput>test -f /usr/lib/libLLVM-3.9.so ||
-  ln -sv /opt/llvm3/lib/libLLVM-3.9.so /usr/lib &amp;&amp;
-
-./x.py dist --install</userinput></screen>
+<screen role="root"><userinput>./x.py dist --install</userinput></screen>
   </sect2>
 
@@ -164,38 +191,28 @@
 
     <para>
-      <command>--llvm-root=/opt/llvm3 --enable-llvm-link-shared</command>:
-      This tells rust to use the system version of llvm3 installed in
-      <filename class="directory">/opt/llvm3</filename>, linking to the
-      shared libraries.
-    </para>
-
-    <para>
-      <option>--enable-dist-host-only</option>: If you did not install a
-      system version of <xref linkend="llvm-old"/>, use this alternative command
-      to build the shipped static version of llvm. It will
-      <emphasis>compile</emphasis> for all the available linux cross-compilers
-      (Aarch64, MIPS, PowerPC, SystemZ, etc) but with this switch it will only
-      <emphasis>install</emphasis> for the host architecture.
-    </para>
-
-    <para>
-      <option>RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi"</option>: use this if
-      you need to link against a version of LLVM-3 which was compiled against
-      <xref linkend="libffi"/>.
-    </para>
-
-    <para>
-      <command>ln -sv /opt/llvm3/lib/libLLVM-3.9.so /usr/lib</command>:
-      Although the <emphasis>build</emphasis> of <application>Rust</application>
-      finds the shared library in
-      <filename class="directory">/opt/llvm3/lib</filename>, several of the steps
-      run by the <application>rustbuild</application>
-      <emphasis>installer</emphasis> do not find
-      <filename>libLLVM-3.9.so</filename>. This conditional symlink fixes that,
-      and works even if <filename>libLLVM-3.9.{0,1}</filename> has already been
-      installed in <filename class="directory">/usr</filename>.
-      <emphasis>Omit this command if you did not install a system version of
-      <xref linkend="llvm-old"/></emphasis>.
-    </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>--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>
+
   </sect2>
 
@@ -210,16 +227,14 @@
       <seglistitem>
         <seg>
-          rust-gdb, rust-lldb, rustc, rustdoc.
+          cargo, rust-gdb, rust-lldb, rustc, rustdoc.
         </seg>
         <seg>
-          Many libraries (libarena, libflate, libfmt_macros, libgetopts,
-          libgraphviz, liblog, libproc_macro, librustc*, libserialize,
-          libstd, libsyntax, libterm, libtest), all containing a hash in
-          their names.
+          Many lib*&lt;16-byte-hash&gt;.so libraries.
         </seg>
         <seg>
           ~/.cargo,
-          /usr/lib/rustlib, and
-          /usr/share/doc/rustc-&rust-version;.
+          /usr/lib/rustlib,
+          /usr/share/doc/rustc-&rust-version;, and
+          /usr/share/zsh/site-functions/
         </seg>
       </seglistitem>
@@ -231,4 +246,16 @@
       <?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="rust-gdb">
         <term><command>rust-gdb</command></term>
