source: general/prog/rust.xml@ 4f9e45d9

10.0 10.1 11.0 9.0 9.1 ken/refactor-virt lazarus qt5new trunk upgradedb xry111/git-date xry111/git-date-for-trunk xry111/git-date-test
Last change on this file since 4f9e45d9 was 4f9e45d9, checked in by Ken Moffat <ken@…>, 3 years ago

Rustc-1.35.0.

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

  • Property mode set to 100644
File size: 24.1 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY rust-download-http "https://static.rust-lang.org/dist/rustc-&rust-version;-src.tar.gz">
8 <!ENTITY rust-download-ftp " ">
9 <!ENTITY rust-md5sum "f43af67a139ce21ff5f530bbd2f486aa">
10 <!ENTITY rust-size "145 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 "5.6 GB (423 MB installed) including 407MB of ~/.cargo files for the user building this. Add 1.8 GB if running the tests">
17 <!ENTITY rust-time "24 SBU (add 15 SBU for tests, both with 4 processors)">
18]>
19
20<sect1 id="rust" xreflabel="rustc-&rust-version;">
21 <?dbhtml filename="rust.html"?>
22
23 <sect1info>
24 <othername>$LastChangedBy$</othername>
25 <date>$Date$</date>
26 </sect1info>
27
28 <title>Rustc-&rust-version;</title>
29
30 <indexterm zone="rust">
31 <primary sortas="a-rust">Rust</primary>
32 </indexterm>
33
34 <sect2 role="package">
35 <title>Introduction to Rust</title>
36
37 <para>
38 The <application>Rust</application> programming language is designed
39 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).
48 </para>
49
50 <para>
51 As with many other programming languages, rustc (the rust compiler)
52 needs a binary from which to bootstrap. It will download a stage0 binary
53 and many cargo crates (these are actually .tar.gz source archives) at
54 the start of the build, so you cannot compile it without an internet
55 connection.
56 </para>
57
58 <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>
99 The current <application>rustbuild</application> build-system will use
100 all available processors, although it does not scale well and often falls
101 back to just using one core while waiting for a library to compile.
102 </para>
103
104 <para>
105 At the moment <application>Rust</application> does not provide any
106 guarantees of a stable ABI.
107 </para>
108
109 <note>
110 <para>
111 Rustc defaults to building for ALL supported architectures, using a
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 The build times of this version when repeated on the same machine are
121 often reasonably consistent, but as with all compilations using
122 <command>rustc</command> there can be some very slow outliers.
123 </para>
124 <para>
125 Unusually, a DESTDIR-style method is being used to install this package.
126 This is because running the install as root not only downloads all of the
127 cargo files again (to <filename>/root/.cargo</filename>), it then spends
128 a very long time recompiling. Using this method saves a lot of time, at
129 the cost of extra disk space.
130 </para>
131 </note>
132
133 &lfs84_checked;
134
135 <bridgehead renderas="sect3">Package Information</bridgehead>
136 <itemizedlist spacing="compact">
137 <listitem>
138 <para>
139 Download (HTTP): <ulink url="&rust-download-http;"/>
140 </para>
141 </listitem>
142 <listitem>
143 <para>
144 Download (FTP): <ulink url="&rust-download-ftp;"/>
145 </para>
146 </listitem>
147 <listitem>
148 <para>
149 Download MD5 sum: &rust-md5sum;
150 </para>
151 </listitem>
152 <listitem>
153 <para>
154 Download size: &rust-size;
155 </para>
156 </listitem>
157 <listitem>
158 <para>
159 Estimated disk space required: &rust-buildsize;
160 </para>
161 </listitem>
162 <listitem>
163 <para>
164 Estimated build time: &rust-time;
165 </para>
166 </listitem>
167 </itemizedlist>
168
169 <bridgehead renderas="sect3">Rust Dependencies</bridgehead>
170
171 <bridgehead renderas="sect4">Required</bridgehead>
172 <para role="required">
173 <xref linkend="curl"/>,
174 <xref linkend="cmake"/>, and
175 <xref linkend="libssh2"/>
176 </para>
177
178 <bridgehead renderas="sect4">Recommended</bridgehead>
179 <para role="recommended">
180 <package>clang</package> from <xref linkend="llvm"/>
181 (built with -DLLVM_LINK_LLVM_DYLIB=ON so that rust can link to
182 systel LLVM instead of building its shipped version)
183 </para>
184
185 <bridgehead renderas="sect4">Optional</bridgehead>
186 <para role="optional">
187 <xref linkend="gdb"/> (used by the testsuite if it is present) and
188 <xref linkend="python2"/> (used by the testsuite)
189 </para>
190
191 <para condition="html" role="usernotes">
192 User Notes: <ulink url="&blfs-wiki;/rust"/>
193 </para>
194 </sect2>
195
196 <sect2 role="installation">
197 <title>Installation of Rust</title>
198
199 <para>
200 To install into the
201 <filename class="directory">/opt</filename> directory, remove the symlink
202 and create a new directory (i.e. with a different name if trying a
203 modified build).
204 As the <systemitem class="username">root</systemitem>
205 user:
206 </para>
207
208<screen role="root"><userinput>mkdir /opt/rustc-&rust-version; &amp;&amp;
209ln -svfin rustc-&rust-version; /opt/rustc</userinput></screen>
210
211 <note>
212 <para>
213 If multiple versions of <application>Rust</application> are installed
214 in <filename class="directory">/opt</filename>, changing to another
215 version only requires changing the <filename> /opt/rustc</filename>
216 symbolic link and then running <command>ldconfig</command>.
217 </para>
218 </note>
219
220 <para>
221 Create a suitable <filename>config.toml</filename> file which will
222 configure the build.
223 </para>
224
225<screen><userinput>cat &lt;&lt; EOF &gt; config.toml
226<literal># see config.toml.example for more possible options
227# See the 8.4 book for an example using shipped LLVM
228[llvm]
229# by default, rust will build for a myriad of architectures
230targets = "X86"
231
232# When using system llvm prefer shared libraries
233link-shared = true
234
235[build]
236# omit docs to save time and space (default is to build them)
237docs = false
238
239# install cargo as well as rust
240extended = true
241
242[install]
243prefix = "/opt/rustc-1.35.0-sysllvm"
244docdir = "share/doc/rustc-1.35.0"
245
246[rust]
247channel = "stable"
248rpath = false
249
250# BLFS does not install the FileCheck executable from llvm,
251# so disable codegen tests
252codegen-tests = false
253
254[target.x86_64-unknown-linux-gnu]
255# NB the output of llvm-config (i.e. help options) may be
256# dumped to the screen when config.toml is parsed.
257llvm-config = "/usr/bin/llvm-config"
258</literal>
259EOF</userinput></screen>
260
261 <para>
262 Now compile <application>Rust</application> by running the following
263 commands:
264 </para>
265
266<screen><userinput>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi" &amp;&amp;
267python3 ./x.py build --exclude src/tools/miri</userinput></screen>
268
269 <note>
270 <para>
271 The testsuite will generate some messages in the
272 <phrase revision="sysv">system log</phrase>
273 <phrase revision="systemd">systemd journal</phrase>
274 for traps on invalid opcodes, and for segmentation faults.
275 In themselves these are nothing to worry about, just a way for the
276 test to be terminated.
277 </para>
278 </note>
279
280 <para>
281 To run the tests issue <command>python3 ./x.py test --verbose
282 --no-fail-fast | tee rustc-testlog</command>: as with the build, that
283 will use all available CPUs.
284 </para>
285
286 <para>
287 The instructions above do not build ARM compilers, so the testsuite
288 <emphasis>will</emphasis> fail and the tests will be reported to end in
289 error, with a backtrace of the last failing test. On a good run, 3 tests
290 which need Thumb (ARM) compilers will fail, all in <filename
291 class="directory">ui/issues</filename> for issues 37131, 49851 and 50993.
292 A fourth test,
293 <filename>run-make-fulldeps/sysroot-crates-are-unstable</filename>
294 fails, presumably because we are using only stable features.
295 If gdb has been installed, in some circumstances tests in
296 <filename class="directory">debuginfo</filename> may fail. As with all
297 large testsuites, other tests might
298 fail on some machines - if the number of failures is in the single digits,
299 check the log for 'FAILED' and review lines above that, particularly the
300 'stderr:' lines. Any mention of
301 SIGSEGV or signal 11 in a failing test is a cause for concern.
302 </para>
303
304 <para>+
305 Therefore, you should determine the number of tests, failures, etc. The
306 total number of tests which were considered is found by running:
307 </para>
308
309<screen><command>grep 'running .* tests' rustc-testlog | awk '{ sum += $2 } END { print sum }'</command></screen>
310
311 <para>
312 That should report 16499 tests. Similarly, the total tests which failed can
313 be found by running:
314 </para>
315
316<screen><command>grep '^test result:' rustc-testlog | awk '{ sum += $6 } END { print sum }'</command></screen>
317
318 <para>
319 And similarly for the tests which passed use $4, for those which were ignored
320 (i.e. skipped) use $8 (and $10 for 'measured', $12 for 'filtered out' but both
321 are probably zero). The breakdown does not quite match the overall total.
322 </para>
323
324 <para>
325 Still as your normal user, do a DESTDIR install:
326 </para>
327
328<screen><userinput>export LIBSSH2_SYS_USE_PKG_CONFIG=1 &amp;&amp;
329DESTDIR=${PWD}/install python3 ./x.py install &amp;&amp;
330unset LIBSSH2_SYS_USE_PKG_CONFIG</userinput></screen>
331
332 <para>
333 Now, as the <systemitem class="username">root</systemitem> user
334 install the files from the DESTDIR:
335 </para>
336
337<screen role="root"><userinput>chown -R root:root install &amp;&amp;
338cp -a install/* /</userinput></screen>
339
340 </sect2>
341
342 <sect2 role="commands">
343 <title>Command Explanations</title>
344
345 <para>
346 <command>ln -svfn rustc-&rust-version; /opt/rustc</command>: if this is
347 not the first use of the <filename class="directory">/opt/rustc</filename>
348 symlink, overwrite it by forcing, and use the '-n' flag to avoid getting
349 confusing results from e.g. <command>ls -l</command>.
350 </para>
351
352 <para>
353 <command>targets = "X86"</command>: this avoids building all the available
354 linux cross-compilers (Aarch64, MIPS, PowerPC, SystemZ, etc). Unfortunately,
355 rust insists on installing source files for these below
356 <filename class="directory">/usr/lib/rustlib/src</filename>.
357 </para>
358
359 <para>
360 <command>extended = true</command>: this installs Cargo alongside Rust.
361 </para>
362
363 <para>
364 <command>channel = "stable"</command>: this ensures only stable features
365 can be used, the default in <filename>config.toml</filename> is to use
366 development features, which is not appropriate for a released version.
367 </para>
368
369 <para>
370 <command>rpath = false</command>: by default, <command>rust</command> can
371 be run from where it was built, without being installed. That adds DT_RPATH
372 entries to all of the ELF files, which produces very messy output from
373 <command>ldd</command>, showing the libraries in the place they were built,
374 even if they have been deleted from there after the install.
375 </para>
376
377 <!-- comment while using shipped LLVM
378 <para>
379 <command>[target.x86_64-unknown-linux-gnu]</command>: the syntax of
380 <filename>config.toml</filename> requires an <literal>llvm-config</literal>
381 entry for each target for which system-llvm is to be used. Change the target
382 to <literal>[target.i686-unknown-linux-gnu]</literal> if you are building
383 on 32-bit x86. This whole section may be omitted if you wish to build
384 against the shipped llvm, or do not have clang, but the resulting build will
385 be larger and take longer.
386 </para>-->
387
388 <para>
389 <command>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi"</command>:
390 This adds a link to libffi to any RUSTFLAGS you may already be passing
391 to the build. On some systems, linking fails to include libffi unless
392 this is used. The reason why this is needed is not clear.
393 </para>
394
395 <para>
396 <command>--exclude src/tools/miri</command>: For a long time, the miri
397 crate (an interpreter for the Midlevel Intermediate Representation)
398 has failed to build on releases. It is optional, but the failure
399 messages can persuade people that the whole build failed. However,
400 although it is not built in the main compile, with rustc-1.35.0 it
401 now gets compiled during the install, but it is broken in this version.
402 <!-- might be unbroken in 1.36.0, if so remove broken from description
403 of miri below. https://github.com/rust-lang/rust/issues/61830 -->
404 </para>
405
406 <para>
407 <command>--verbose</command>: this switch can sometimes provide more
408 information about a test which fails.
409 </para>
410
411 <para>
412 <command>--no-fail-fast</command>: this switch ensures that the testsuite
413 will not stop at the first error.
414 </para>
415
416 <para>
417 <command>export LIBSSH2_SYS_USE_PKG_CONFIG=1</command>: On some systems,
418 cairo fails to link during the install because it cannot find libssh2.
419 This seems to fix it, but again the reason why the problem occurs is not
420 understood.
421 </para>
422
423 <para>
424 <command>DESTDIR=${PWD}/install python3 ./x.py install</command>: This
425 effects a DESTDIR-style install in the source tree,creating an <filename
426 class="directory">install</filename> directory. Note that DESTDIR installs
427 need an absolute path, passing 'install' will not work.
428 </para>
429
430 <para>
431 <command>chown -R root:root install</command>: the DESTDIR install
432 was run by a regular user, who owns the files. For security, change their
433 owner before doing a simple copy to install them.
434 </para>
435
436 </sect2>
437
438 <sect2 role="configuration">
439 <title>Configuring Rust</title>
440
441 <sect3 id="rustc-config">
442 <title>Configuration Information</title>
443
444 <para>
445 If you installed <application>rustc</application> in
446 <filename class="directory">/opt</filename>, you need to update the
447 following configuration files so that <application>rustc</application> is
448 correctly found by other packages and system processes.
449 </para>
450
451 <para>
452 As the <systemitem class="username">root</systemitem> user, update
453 the <filename>/etc/ld.so.conf</filename> file and the dynamic linker's
454 run-time cache file:
455 </para>
456
457<screen role="root"><userinput>cat &gt;&gt; /etc/ld.so.conf &lt;&lt; EOF
458<literal># Begin rustc addition
459
460/opt/rustc/lib
461
462# End rustc addition</literal>
463EOF
464
465ldconfig</userinput></screen>
466
467 <indexterm zone="rustc rustc-config">
468 <primary sortas="e-etc-ld.so.conf">/etc/ld.so.conf</primary>
469 </indexterm>
470
471 <para>
472 As the <systemitem class="username">root</systemitem> user, create
473 the <filename>/etc/profile.d/rustc.sh</filename> file:
474 </para>
475
476<screen role="root"><userinput>cat &gt; /etc/profile.d/rustc.sh &lt;&lt; "EOF"
477<literal># Begin /etc/profile.d/rustc.sh
478
479pathprepend /opt/rustc/bin PATH
480
481# End /etc/profile.d/rustc.sh</literal>
482EOF</userinput></screen>
483
484 <para>Immediately after installation, update the current PATH
485 for your current shell as a normal user:</para>
486
487<screen><userinput>source /etc/profile.d/rustc.sh</userinput></screen>
488
489 </sect3>
490 </sect2>
491
492
493 <sect2 role="content">
494 <title>Contents</title>
495
496 <segmentedlist>
497 <segtitle>Installed Programs</segtitle>
498 <segtitle>Installed Libraries</segtitle>
499 <segtitle>Installed Directories</segtitle>
500
501 <seglistitem>
502 <seg>
503 cargo-clippy, cargo-fmt, cargo-miri, cargo, clippy-driver, miri, rls, rust-gdb, rust-lldb, rustc, rustdoc, rustfmt.
504 </seg>
505 <seg>
506 Many lib*&lt;16-byte-hash&gt;.so libraries.
507 </seg>
508 <seg>
509 ~/.cargo,
510 /usr/lib/rustlib,
511 /usr/share/doc/rustc-&rust-version;, and
512 /usr/share/zsh/site-functions/
513 </seg>
514 </seglistitem>
515 </segmentedlist>
516
517 <variablelist>
518 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
519 <?dbfo list-presentation="list"?>
520 <?dbhtml list-presentation="table"?>
521
522 <varlistentry id="cargo-clippy">
523 <term><command>cargo-clippy</command></term>
524 <listitem>
525 <para>
526 provides lint checks for a cargo package.
527 </para>
528 <indexterm zone="rust cargo-clippy">
529 <primary sortas="b-cargo-clippy">cargo-clippy</primary>
530 </indexterm>
531 </listitem>
532 </varlistentry>
533
534 <varlistentry id="cargo-fmt">
535 <term><command>cargo-fmt</command></term>
536 <listitem>
537 <para>
538 formats all bin and lib files of the current crate using
539 rustfmt.
540 </para>
541 <indexterm zone="rust cargo-fmt">
542 <primary sortas="b-cargo-fmt">cargo-fmt</primary>
543 </indexterm>
544 </listitem>
545 </varlistentry>
546
547 <varlistentry id="cargo-miri">
548 <term><command>cargo-miri</command></term>
549 <listitem>
550 <para>
551 <!-- FIXME reword to 'is used by' if Miri installed
552 AND works enough to report its \-\-help -->
553 is for use by Miri to interpret bin crates and tests
554 </para>
555 <indexterm zone="rust cargo-miri">
556 <primary sortas="b-cargo-miri">cargo-miri</primary>
557 </indexterm>
558 </listitem>
559 </varlistentry>
560
561 <varlistentry id="cargo">
562 <term><command>cargo</command></term>
563 <listitem>
564 <para>
565 is the Package Manager for Rust.
566 </para>
567 <indexterm zone="rust cargo">
568 <primary sortas="b-cargo">cargo</primary>
569 </indexterm>
570 </listitem>
571 </varlistentry>
572
573 <varlistentry id="clippy-driver">
574 <term><command>clippy-driver</command></term>
575 <listitem>
576 <para>
577 provides lint checks for Rust.
578 </para>
579 <indexterm zone="rust clippy-driver">
580 <primary sortas="b-clippy-driver">clippy-driver</primary>
581 </indexterm>
582 </listitem>
583 </varlistentry>
584
585 <varlistentry id="miri">
586 <term><command>miri</command></term>
587 <listitem>
588 <para>
589 is an interpreter for Rust's mid-level intermediate representation
590 (MIR). It is broken in this version.
591 </para>
592 <indexterm zone="rust miri">
593 <primary sortas="b-miri">miri</primary>
594 </indexterm>
595 </listitem>
596 </varlistentry>
597
598 <varlistentry id="rls">
599 <term><command>rls</command></term>
600 <listitem>
601 <para>
602 is the Rust Language Server. This can run in the background to
603 provide IDEs, editors, and other tools with information about Rust
604 programs.
605 </para>
606 <indexterm zone="rust rls">
607 <primary sortas="b-rls">rls</primary>
608 </indexterm>
609 </listitem>
610 </varlistentry>
611
612 <varlistentry id="rust-gdb">
613 <term><command>rust-gdb</command></term>
614 <listitem>
615 <para>
616 is a wrapper script for gdb, pulling in Python
617 pretty-printing modules installed in <filename
618 class="directory">/usr/lib/rustlib/etc</filename>.
619 </para>
620 <indexterm zone="rust rust-gdb">
621 <primary sortas="b-rust-gdb">rust-gdb</primary>
622 </indexterm>
623 </listitem>
624 </varlistentry>
625
626 <varlistentry id="rust-lldb">
627 <term><command>rust-lldb</command></term>
628 <listitem>
629 <para>
630 is a wrapper script for LLDB (the LLVM debugger)
631 pulling in the Python pretty-printing modules.
632 </para>
633 <indexterm zone="rust rust-lldb">
634 <primary sortas="b-rust-lldb">rust=lldb</primary>
635 </indexterm>
636 </listitem>
637 </varlistentry>
638
639 <varlistentry id="rustc">
640 <term><command>rustc</command></term>
641 <listitem>
642 <para>
643 is the rust compiler.
644 </para>
645 <indexterm zone="rust rustc">
646 <primary sortas="b-rustc">rustc</primary>
647 </indexterm>
648 </listitem>
649 </varlistentry>
650
651 <varlistentry id="rustdoc">
652 <term><command>rustdoc</command></term>
653 <listitem>
654 <para>
655 generates documentation from rust source code.
656 </para>
657 <indexterm zone="rust rustdoc">
658 <primary sortas="b-rustdoc">rustdoc</primary>
659 </indexterm>
660 </listitem>
661 </varlistentry>
662
663 <varlistentry id="rustfmt">
664 <term><command>rustfmt</command></term>
665 <listitem>
666 <para>
667 formats rust code.
668 </para>
669 <indexterm zone="rust rustfmt">
670 <primary sortas="b-rustfmt">rustfmt</primary>
671 </indexterm>
672 </listitem>
673 </varlistentry>
674
675 <varlistentry id="libstd">
676 <term><filename class="libraryfile">libstd-&lt;16-byte-hash&gt;.so</filename></term>
677 <listitem>
678 <para>
679 is the Rust Standard Library, the foundation of portable Rust software.
680 </para>
681 <indexterm zone="rust libstd">
682 <primary sortas="c-libstd">libstd-&lt;16-byte-hash&gt;.so</primary>
683 </indexterm>
684 </listitem>
685 </varlistentry>
686 </variablelist>
687 </sect2>
688</sect1>
Note: See TracBrowser for help on using the repository browser.