Ignore:
Timestamp:
02/03/2019 06:37:53 PM (5 years ago)
Author:
DJ Lucas <dj@…>
Branches:
elogind
Children:
4d176c4f
Parents:
8f6f10e
Message:

Merge to HEAD 21080.

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/branches/BOOK-elogind@21081 af4574ff-66df-0310-9fd7-8a98e5e911e0

File:
1 edited

Legend:

Unmodified
Added
Removed

  • general/prog/rust.xml

    r8f6f10e rd60cd837  
    77  <!ENTITY rust-download-http "https://static.rust-lang.org/dist/rustc-&rust-version;-src.tar.gz">
    88  <!ENTITY rust-download-ftp  " ">
    9   <!ENTITY rust-md5sum        "6790c24fe5e8fb5a5f7efbfbcc6fea65">
    10   <!ENTITY rust-size          "101 MB">
    11   <!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)">
    12   <!ENTITY rust-time          "27 SBU (add 13 SBU for tests, both with 4 processors)">
     9  <!ENTITY rust-md5sum        "366f049777e00d0d6f15d25895485efb">
     10  <!ENTITY rust-size          "152 MB">
     11  <!-- Gentle Reminder: buildsize is how much the user requires for the real
     12       install, i.e. the source with its DESTDIR *plus* the DESTDIR.  You
     13       can 'mkdir /tmp/RUST ; cp -a install/* /tmp/RUST' and then run 'du -sch'
     14       to measure it. -->
     15
     16  <!ENTITY rust-buildsize     "6.2 GB (475 MB installed) including 295MB of ~/.cargo files for the user building this. Add 1.5GB if installing the documentation (an extra 314MB is installed), and 2.0GB if running the tests">
     17  <!ENTITY rust-time          "34 SBU (add 3 SBU if installing the documentation and 15 SBU for tests, both with 4 processors)">
    1318]>
    1419
    … …  
    3338      The <application>Rust</application> programming language is designed
    3439      to be a safe, concurrent, practical language.
     40    </para>
     41
     42    <para>
     43      This package is updated on a six-weekly release cycle. Because it is
     44      such a large and slow package to build, and is at the moment only required
     45      by five packages in this book, the BLFS editors take the view that it
     46      should only be updated when that is necessary (either to fix problems,
     47      or to allow a new version of <application>firefox</application> to build).
    3548    </para>
    3649
    … …  
    4457
    4558    <para>
     59      These crates will then remain in various forms (cache, directories of
     60      extracted source), in <filename class="directory">~/.cargo</filename> for
     61      ever more. It is common for large <application>rust</application> packages
     62      to use multiple versions of some crates. If you purge the files before
     63      updating this package, very few crates will need to be updated by the
     64      packages in this book which use it (and they will be downloaded as
     65      required). But if you retain an older version as a fallback option and
     66      then use it (when <emphasis>not</emphasis> building in
     67      <filename class="directory">/usr</filename>), it is likely that it will
     68      then have to re-download some crates. For a full download (i.e. starting
     69      with an empty or missing <filename class="directory">~/.cargo</filename>)
     70      downloading the external cargo files for this version only takes a minute
     71      or so on a fast network.
     72    </para>
     73
     74    <note>
     75      <para>
     76        Although BLFS usually installs in <filename
     77        class="directory">/usr</filename>, when you later upgrade to a newer
     78        version of <application>rust</application> the old libraries in <filename
     79        class="directory">/usr/lib/rustlib</filename> will remain, with various
     80        hashes in their names, but will not be usable and will waste space. The
     81        editors recommend placing the files in the <filename
     82        class="directory">/opt</filename> directory.  In particular, if you
     83        have reason to rebuild with a modified configuration (e.g. using the
     84        shipped LLVM after building with shared LLVM, but perhaps also the
     85        reverse situation) it it possible for the install to leave a broken
     86        <command>cargo</command> program. In such a situation, either remove
     87        the existing installation first, or use a different prefix such as
     88        /opt/rustc-&rust-version;-build2.
     89      </para>
     90
     91      <para>
     92        If you prefer, you can of course change the prefix to <filename
     93        class="directory">/usr</filename> and omit the
     94        <command>ldconfig</command> and the actions to add rustc to the PATH.
     95      </para>
     96    </note>
     97
     98    <para>
    4699      The current <application>rustbuild</application> build-system will use
    47100      all available processors, although it does not scale well and often falls
    … …  
    57110      <para>
    58111        Rustc defaults to building for ALL supported architectures, using a
    59         shipped copy of LLVM. In BLFS the build is only for the X86 architecture.
    60         Rustc still claims to require Python2, but that is only really necessary
    61         when building some other architectures with the shipped LLVM. If you
    62         intend to develop rust crates, this build may not be good enough for your
    63         purposes.
    64       </para>
    65       <para>
    66         Repeated builds of this package on the same machine show a wide range
    67         of build times. Some of this might be due to variations in downloading
    68         the required cargo files if they are not already present, but this does
    69         not seem to adequately explain the variations.
     112        shipped copy of LLVM. In BLFS the build is only for the X86
     113        architecture. Rustc still claims to require Python 2, but that is only
     114        really necessary when building some other architectures with the
     115        shipped LLVM.
     116        If you intend to develop rust crates, this build may not be good
     117        enough for your purposes.
     118      </para>
     119      <para>
     120        Unlike with previous versions, the build times of this version when
     121       repeated on the same machine seem reasonably consistent.
    70122      </para>
    71123      <para>
    … …  
    119171    <para role="required">
    120172      <xref linkend="curl"/>,
    121       <xref linkend="cmake"/>,
     173      <xref linkend="cmake"/>, and
    122174      <xref linkend="libssh2"/>
    123 <!--  <xref linkend="python2"/> -->
    124     </para>
    125 
     175    </para>
     176
     177<!-- comment out while using shipped LLVM
    126178    <bridgehead renderas="sect4">Recommended</bridgehead>
    127179    <para role="recommended">
    128180      <package>clang</package> from <xref linkend="llvm"/>
    129181      (built with -DLLVM_LINK_LLVM_DYLIB=ON)
    130     </para>
     182    </para>-->
    131183
    132184    <bridgehead renderas="sect4">Optional</bridgehead>
    133185    <para role="optional">
    134       <xref linkend="gdb"/> (recommended if running the testsuite)
     186      <xref linkend="gdb"/> (used by the testsuite if it is present) and
     187      <xref linkend="python2"/> (if gdb is present, it must have been built
     188      with Python 2 support to prevent some tests failing. Furthermore, another
     189      test fails if Python 2 is not present)
    135190    </para>
    136191
    … …  
    143198    <title>Installation of Rust</title>
    144199
     200    <para>
     201      To install into the
     202      <filename class="directory">/opt</filename> directory, remove the symlink
     203      and create a new directory (i.e. with a different name if trying a
     204      modified build).
     205      As the <systemitem class="username">root</systemitem>
     206      user:
     207    </para>
     208
     209<screen role="root"><userinput>mkdir /opt/rustc-&rust-version;             &amp;&amp;
     210ln -svfin rustc-&rust-version; /opt/rustc</userinput></screen>
     211
    145212    <note>
    146213      <para>
    147         This package is updated on a six-weekly release cycle. Because it is
    148         such a large and slow package to build, and is at the moment only required
    149         by three packages in this book, the BLFS editors take the view that it
    150         should only be updated when that is necessary.
     214        If multiple versions of <application>Rust</application> are installed
     215        in <filename class="directory">/opt</filename>, changing to another
     216        version only requires changing the <filename> /opt/rustc</filename>
     217        symbolic link and then running <command>ldconfig</command>.
    151218      </para>
    152219    </note>
    153220
    154221    <para>
    155       First create a suitable <filename>config.toml</filename> file
    156       which will configure the build :
     222      Create a suitable <filename>config.toml</filename> file which will
     223      configure the build. Unlike with previous releases, where even quite old
     224      system versions of <application>LLVM</application>worked well, this
     225      version ships with a development version and using the current <xref
     226      linkend="llvm"/> release is known to result in breakage in some
     227      circumstances.
    157228    </para>
    158229
    … …  
    160231# see config.toml.example for more possible options
    161232[llvm]
     233
     234# use ninja
     235ninja = true
     236
    162237targets = "X86"
    163 
    164 # When using system llvm prefer shared libraries
    165 link-shared = true
     238# When compiling LLVM, the experimental targets (WebAssembly
     239# and RISCV) are built by default - omit them
     240experimental-targets = ""
    166241
    167242[build]
     243# omit HTML docs to save time and space (comment this to build them)
     244docs = false
     245
    168246# install cargo as well as rust
    169247extended = true
    170248
    171249[install]
    172 prefix = "/usr"
     250# Adjust the prefix for the desired destination
     251#prefix = "/usr"
     252prefix = "/opt/rustc-&rust-version;"
     253
     254# docdir is used even if the full awesome docs are not installed
    173255docdir = "share/doc/rustc-&rust-version;"
    174256
    … …  
    181263codegen-tests = false
    182264
    183 [target.x86_64-unknown-linux-gnu]
    184 # delete this *section* if you are not using system llvm.
    185 # NB the output of llvm-config (i.e. help options) may be
    186 # dumped to the screen when config.toml is parsed.
    187 llvm-config = "/usr/bin/llvm-config"
     265# get a trace if there is an Internal Compiler Exception
     266backtrace-on-ice = true
    188267
    189268EOF</userinput></screen>
    … …  
    195274
    196275<screen><userinput>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi" &amp;&amp;
    197 python3 ./x.py build</userinput></screen>
    198 
    199     <para>
    200       The build will report it failed to compile <filename>miri</filename>
    201       because of multiple potential crates for `log`, but that should be followed
    202       by a message that the build completed successfully.
    203     </para>
    204 
    205     <caution>
    206       <para>
    207         On AMD Ryzen processors (family 17h), the non-optimized version of libstd
    208         which is compiled at the start of the tests contains two opcodes which are
    209         not implemented on this CPU family. These will be logged in the
     276python3 ./x.py build --exclude src/tools/miri</userinput></screen>
     277
     278    <note>
     279      <para>
     280        The testsuite will generate some messages in the
    210281        <phrase revision="sysv">system log</phrase>
    211282        <phrase revision="systemd">systemd journal</phrase>
    212         and will be followed a few minutes later by segmentation faults. Despite
    213         that, the tests continue to run, apparently normally. But the system may
    214         reboot before the tests have completed. The normal optimized libraries
    215         run without this problem.
    216       </para>
    217       <para>
    218         A mitigation is to install gdb
    219         <!-- systemd apparently handles this with systemd-coredump -->
    220         <phrase revision="sysv">and to run the tests with 'ulimit -C disabled'</phrase>
    221         but this does not always prevent the system rebooting.
    222       </para>
    223     </caution>
    224 
    225     <para>
    226       To run the tests issue
    227       <command>python3 ./x.py test --verbose --no-fail-fast | tee rustc-testlog</command>:
    228       as with the build, that will use all available CPUs.  This runs many suites
    229       of tests (in an apparently random order), several will fail in BLFS:
    230       compile-fail/issue-37131.rs require a thumbv6m-none-eabi compiler but the
    231       BLFS build does not cater for
    232       that, ui/issue-49851/compiler-builtins-error.rs and ui/issue-50993.rs (both
    233       run twice) require a thumbv7em-none-eabihf compiler, and seven tests in
    234       debuginfo-gdb will fail because gdb-8.1 changed the output format.  If
    235       <application>gdb</application> has not been installed, most of the gdb tests
    236       will fail.
    237     </para>
    238 
    239     <para>
    240       If you wish to look at the numbers for the results, you can find the total
    241       number of tests which were considered by running:
     283        for traps on invalid opcodes, and for segmentation faults.
     284        In themselves these are nothing to worry about, just a way for the
     285        test to be terminated. But if the output from the testsuite reports tests
     286        which FAIL with segmentation faults (signal 11) then there may be a
     287        problem.
     288      </para>
     289    </note>
     290
     291    <para>
     292      To run the tests issue <command>python3 ./x.py test --verbose
     293      --no-fail-fast | tee rustc-testlog</command>: as with the build, that
     294      will use all available CPUs.
     295    </para>
     296
     297    <para>
     298      The instructions above do not build ARM compilers, so the testsuite
     299      <emphasis>will</emphasis> fail and the tests will be reported to end in
     300      error, with a backtrace of the last failing test. On a good run, 3 tests
     301      which need Thumb (ARM) compilers will fail, all in <filename
     302      class="directory">ui/issues</filename> for issues 37131, 49851 and 50993.
     303      Occasionally a fourth test,
     304      <filename>run-make-fulldeps/sysroot-crates-are-unstable</filename>
     305      fails. If gdb has been installed, in some circumstances three tests in
     306      <filename class="directory">debuginfo</filename> also fail. As with all
     307      large testsuites, other tests might
     308      fail on some machines - if the number of failures is in the single digits,
     309      check the log for 'FAILED' and review lines above that. Any mention of
     310      SIGSEGV or signal 11 in a failing test is a cause for concern.
     311    </para>
     312
     313    <para>
     314      Therefore, you should determine the number of tests, failures, etc. The
     315      total number of tests which were considered is found by running:
    242316    </para>
    243317
    … …  
    245319
    246320    <para>
    247       That should report 17101 tests. Similarly, the total tests which failed can
     321      That should report 15795 tests. Similarly, the total tests which failed can
    248322      be found by running:
    249323    </para>
    … …  
    254328      And similarly for the tests which passed use $4, for those which were ignored
    255329      (i.e. skipped) use $8 (and $10 for 'measured', $12 for 'filtered out' but both
    256       are probably zero). The breakdown does not match the overall total.
     330      are probably zero). The breakdown does not quite match the overall total.
    257331    </para>
    258332
    … …  
    277351  <sect2 role="commands">
    278352    <title>Command Explanations</title>
     353
     354    <para>
     355      <command>ln -svfn rustc-&rust-version; /opt/rustc</command>: if this is
     356      not the first use of the <filename class="directory">/opt/rustc</filename>
     357      symlink, overwrite it by forcing, and use the '-n' flag to avoid getting
     358      confusing results from e.g. <command>ls -l</command>.
     359    </para>
    279360
    280361    <para>
    … …  
    303384    </para>
    304385
     386    <!-- comment while using shipped LLVM
    305387    <para>
    306388      <command>[target.x86_64-unknown-linux-gnu]</command>: the syntax of
    … …  
    311393      against the shipped llvm, or do not have clang, but the resulting build will
    312394      be larger and take longer.
    313     </para>
     395    </para>-->
    314396
    315397    <para>
    … …  
    321403
    322404    <para>
     405      <command>--exclude src/tools/miri</command>: For a long time, the miri
     406      crate (an interpreter for the Midlevel Intermediate Representation)
     407      has failed to build on releases. It is optional, but the failure
     408      messages can persuade people that the whole build failed.
     409    </para>
     410
     411    <para>
    323412      <command>--verbose</command>: this switch can sometimes provide more
    324413      information about a test which fails.
    … …  
    338427
    339428    <para>
    340       <command>DESTDIR=${PWD}/install ./x.py install</command>: This effects a
    341       DESTDIR-style install in the source tree,creating an <filename
     429      <command>DESTDIR=${PWD}/install python3 ./x.py install</command>: This
     430      effects a DESTDIR-style install in the source tree,creating an <filename
    342431      class="directory">install</filename> directory. Note that DESTDIR installs
    343432      need an absolute path, passing 'install' will not work.
    … …  
    351440
    352441  </sect2>
     442
     443  <sect2 role="configuration">
     444    <title>Configuring Rust</title>
     445
     446    <sect3 id="rustc-config">
     447      <title>Configuration Information</title>
     448
     449      <para>
     450        If you installed <application>rustc</application> in
     451        <filename class="directory">/opt</filename>, you need to update the
     452        following configuration files so that <application>rustc</application> is
     453        correctly found by other packages and system processes.
     454      </para>
     455
     456      <para>
     457        As the <systemitem class="username">root</systemitem> user, update
     458        the <filename>/etc/ld.so.conf</filename> file and the dynamic linker's
     459        run-time cache file:
     460      </para>
     461
     462<screen role="root"><userinput>cat &gt;&gt; /etc/ld.so.conf &lt;&lt; EOF
     463<literal># Begin rustc addition
     464
     465/opt/rustc/lib
     466
     467# End rustc addition</literal>
     468EOF
     469
     470ldconfig</userinput></screen>
     471
     472      <indexterm zone="rustc rustc-config">
     473        <primary sortas="e-etc-ld.so.conf">/etc/ld.so.conf</primary>
     474      </indexterm>
     475
     476      <para>
     477        As the <systemitem class="username">root</systemitem> user, create
     478        the <filename>/etc/profile.d/rustc.sh</filename> file:
     479      </para>
     480
     481<screen role="root"><userinput>cat &gt; /etc/profile.d/rustc.sh &lt;&lt; "EOF"
     482<literal># Begin /etc/profile.d/rustc.sh
     483
     484pathprepend /opt/rustc/bin           PATH
     485
     486# End /etc/profile.d/rustc.sh</literal>
     487EOF</userinput></screen>
     488
     489      <para>Immediately after installation, update the current PATH
     490      for your current shell as a normal user:</para>
     491
     492<screen><userinput>source /etc/profile.d/rustc.sh</userinput></screen>
     493
     494    </sect3>
     495  </sect2>
     496
    353497
    354498  <sect2 role="content">
Note: See TracChangeset for help on using the changeset viewer.