source: general/prog/rust.xml@ 8e99a05

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 8e99a05 was 8e99a05, checked in by Ken Moffat <ken@…>, 3 years ago

rust - remove -sysllvm from the prefix,
it breaks the build and leaked in from my testing.

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

  • Property mode set to 100644
File size: 24.2 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 system 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# e.g. if not installing clang, or using a version before 8.0.
229[llvm]
230# by default, rust will build for a myriad of architectures
231targets = "X86"
232
233# When using system llvm prefer shared libraries
234link-shared = true
235
236[build]
237# omit docs to save time and space (default is to build them)
238docs = false
239
240# install cargo as well as rust
241extended = true
242
243[install]
244prefix = "/opt/rustc-1.35.0"
245docdir = "share/doc/rustc-1.35.0"
246
247[rust]
248channel = "stable"
249rpath = false
250
251# BLFS does not install the FileCheck executable from llvm,
252# so disable codegen tests
253codegen-tests = false
254
255[target.x86_64-unknown-linux-gnu]
256# NB the output of llvm-config (i.e. help options) may be
257# dumped to the screen when config.toml is parsed.
258llvm-config = "/usr/bin/llvm-config"
259</literal>
260EOF</userinput></screen>
261
262 <para>
263 Now compile <application>Rust</application> by running the following
264 commands:
265 </para>
266
267<screen><userinput>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi" &amp;&amp;
268python3 ./x.py build --exclude src/tools/miri</userinput></screen>
269
270 <note>
271 <para>
272 The testsuite will generate some messages in the
273 <phrase revision="sysv">system log</phrase>
274 <phrase revision="systemd">systemd journal</phrase>
275 for traps on invalid opcodes, and for segmentation faults.
276 In themselves these are nothing to worry about, just a way for the
277 test to be terminated.
278 </para>
279 </note>
280
281 <para>
282 To run the tests issue <command>python3 ./x.py test --verbose
283 --no-fail-fast | tee rustc-testlog</command>: as with the build, that
284 will use all available CPUs.
285 </para>
286
287 <para>
288 The instructions above do not build ARM compilers, so the testsuite
289 <emphasis>will</emphasis> fail and the tests will be reported to end in
290 error, with a backtrace of the last failing test. On a good run, 3 tests
291 which need Thumb (ARM) compilers will fail, all in <filename
292 class="directory">ui/issues</filename> for issues 37131, 49851 and 50993.
293 A fourth test,
294 <filename>run-make-fulldeps/sysroot-crates-are-unstable</filename>
295 fails, presumably because we are using only stable features.
296 If gdb has been installed, in some circumstances tests in
297 <filename class="directory">debuginfo</filename> may fail. As with all
298 large testsuites, other tests might
299 fail on some machines - if the number of failures is in the single digits,
300 check the log for 'FAILED' and review lines above that, particularly the
301 'stderr:' lines. Any mention of
302 SIGSEGV or signal 11 in a failing test is a cause for concern.
303 </para>
304
305 <para>+
306 Therefore, you should determine the number of tests, failures, etc. The
307 total number of tests which were considered is found by running:
308 </para>
309
310<screen><command>grep 'running .* tests' rustc-testlog | awk '{ sum += $2 } END { print sum }'</command></screen>
311
312 <para>
313 That should report 16499 tests. Similarly, the total tests which failed can
314 be found by running:
315 </para>
316
317<screen><command>grep '^test result:' rustc-testlog | awk '{ sum += $6 } END { print sum }'</command></screen>
318
319 <para>
320 And similarly for the tests which passed use $4, for those which were ignored
321 (i.e. skipped) use $8 (and $10 for 'measured', $12 for 'filtered out' but both
322 are probably zero). The breakdown does not quite match the overall total.
323 </para>
324
325 <para>
326 Still as your normal user, do a DESTDIR install:
327 </para>
328
329<screen><userinput>export LIBSSH2_SYS_USE_PKG_CONFIG=1 &amp;&amp;
330DESTDIR=${PWD}/install python3 ./x.py install &amp;&amp;
331unset LIBSSH2_SYS_USE_PKG_CONFIG</userinput></screen>
332
333 <para>
334 Now, as the <systemitem class="username">root</systemitem> user
335 install the files from the DESTDIR:
336 </para>
337
338<screen role="root"><userinput>chown -R root:root install &amp;&amp;
339cp -a install/* /</userinput></screen>
340
341 </sect2>
342
343 <sect2 role="commands">
344 <title>Command Explanations</title>
345
346 <para>
347 <command>ln -svfn rustc-&rust-version; /opt/rustc</command>: if this is
348 not the first use of the <filename class="directory">/opt/rustc</filename>
349 symlink, overwrite it by forcing, and use the '-n' flag to avoid getting
350 confusing results from e.g. <command>ls -l</command>.
351 </para>
352
353 <para>
354 <command>targets = "X86"</command>: this avoids building all the available
355 linux cross-compilers (Aarch64, MIPS, PowerPC, SystemZ, etc). Unfortunately,
356 rust insists on installing source files for these below
357 <filename class="directory">/usr/lib/rustlib/src</filename>.
358 </para>
359
360 <para>
361 <command>extended = true</command>: this installs Cargo alongside Rust.
362 </para>
363
364 <para>
365 <command>channel = "stable"</command>: this ensures only stable features
366 can be used, the default in <filename>config.toml</filename> is to use
367 development features, which is not appropriate for a released version.
368 </para>
369
370 <para>
371 <command>rpath = false</command>: by default, <command>rust</command> can
372 be run from where it was built, without being installed. That adds DT_RPATH
373 entries to all of the ELF files, which produces very messy output from
374 <command>ldd</command>, showing the libraries in the place they were built,
375 even if they have been deleted from there after the install.
376 </para>
377
378 <!-- comment while using shipped LLVM
379 <para>
380 <command>[target.x86_64-unknown-linux-gnu]</command>: the syntax of
381 <filename>config.toml</filename> requires an <literal>llvm-config</literal>
382 entry for each target for which system-llvm is to be used. Change the target
383 to <literal>[target.i686-unknown-linux-gnu]</literal> if you are building
384 on 32-bit x86. This whole section may be omitted if you wish to build
385 against the shipped llvm, or do not have clang, but the resulting build will
386 be larger and take longer.
387 </para>-->
388
389 <para>
390 <command>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi"</command>:
391 This adds a link to libffi to any RUSTFLAGS you may already be passing
392 to the build. On some systems, linking fails to include libffi unless
393 this is used. The reason why this is needed is not clear.
394 </para>
395
396 <para>
397 <command>--exclude src/tools/miri</command>: For a long time, the miri
398 crate (an interpreter for the Midlevel Intermediate Representation)
399 has failed to build on releases. It is optional, but the failure
400 messages can persuade people that the whole build failed. However,
401 although it is not built in the main compile, with rustc-1.35.0 it
402 now gets compiled during the install, but it is broken in this version.
403 <!-- might be unbroken in 1.36.0, if so remove broken from description
404 of miri below. https://github.com/rust-lang/rust/issues/61830 -->
405 </para>
406
407 <para>
408 <command>--verbose</command>: this switch can sometimes provide more
409 information about a test which fails.
410 </para>
411
412 <para>
413 <command>--no-fail-fast</command>: this switch ensures that the testsuite
414 will not stop at the first error.
415 </para>
416
417 <para>
418 <command>export LIBSSH2_SYS_USE_PKG_CONFIG=1</command>: On some systems,
419 cairo fails to link during the install because it cannot find libssh2.
420 This seems to fix it, but again the reason why the problem occurs is not
421 understood.
422 </para>
423
424 <para>
425 <command>DESTDIR=${PWD}/install python3 ./x.py install</command>: This
426 effects a DESTDIR-style install in the source tree,creating an <filename
427 class="directory">install</filename> directory. Note that DESTDIR installs
428 need an absolute path, passing 'install' will not work.
429 </para>
430
431 <para>
432 <command>chown -R root:root install</command>: the DESTDIR install
433 was run by a regular user, who owns the files. For security, change their
434 owner before doing a simple copy to install them.
435 </para>
436
437 </sect2>
438
439 <sect2 role="configuration">
440 <title>Configuring Rust</title>
441
442 <sect3 id="rustc-config">
443 <title>Configuration Information</title>
444
445 <para>
446 If you installed <application>rustc</application> in
447 <filename class="directory">/opt</filename>, you need to update the
448 following configuration files so that <application>rustc</application> is
449 correctly found by other packages and system processes.
450 </para>
451
452 <para>
453 As the <systemitem class="username">root</systemitem> user, update
454 the <filename>/etc/ld.so.conf</filename> file and the dynamic linker's
455 run-time cache file:
456 </para>
457
458<screen role="root"><userinput>cat &gt;&gt; /etc/ld.so.conf &lt;&lt; EOF
459<literal># Begin rustc addition
460
461/opt/rustc/lib
462
463# End rustc addition</literal>
464EOF
465
466ldconfig</userinput></screen>
467
468 <indexterm zone="rustc rustc-config">
469 <primary sortas="e-etc-ld.so.conf">/etc/ld.so.conf</primary>
470 </indexterm>
471
472 <para>
473 As the <systemitem class="username">root</systemitem> user, create
474 the <filename>/etc/profile.d/rustc.sh</filename> file:
475 </para>
476
477<screen role="root"><userinput>cat &gt; /etc/profile.d/rustc.sh &lt;&lt; "EOF"
478<literal># Begin /etc/profile.d/rustc.sh
479
480pathprepend /opt/rustc/bin PATH
481
482# End /etc/profile.d/rustc.sh</literal>
483EOF</userinput></screen>
484
485 <para>Immediately after installation, update the current PATH
486 for your current shell as a normal user:</para>
487
488<screen><userinput>source /etc/profile.d/rustc.sh</userinput></screen>
489
490 </sect3>
491 </sect2>
492
493
494 <sect2 role="content">
495 <title>Contents</title>
496
497 <segmentedlist>
498 <segtitle>Installed Programs</segtitle>
499 <segtitle>Installed Libraries</segtitle>
500 <segtitle>Installed Directories</segtitle>
501
502 <seglistitem>
503 <seg>
504 cargo-clippy, cargo-fmt, cargo-miri, cargo, clippy-driver, miri, rls, rust-gdb, rust-lldb, rustc, rustdoc, rustfmt.
505 </seg>
506 <seg>
507 Many lib*&lt;16-byte-hash&gt;.so libraries.
508 </seg>
509 <seg>
510 ~/.cargo,
511 /usr/lib/rustlib,
512 /usr/share/doc/rustc-&rust-version;, and
513 /usr/share/zsh/site-functions/
514 </seg>
515 </seglistitem>
516 </segmentedlist>
517
518 <variablelist>
519 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
520 <?dbfo list-presentation="list"?>
521 <?dbhtml list-presentation="table"?>
522
523 <varlistentry id="cargo-clippy">
524 <term><command>cargo-clippy</command></term>
525 <listitem>
526 <para>
527 provides lint checks for a cargo package.
528 </para>
529 <indexterm zone="rust cargo-clippy">
530 <primary sortas="b-cargo-clippy">cargo-clippy</primary>
531 </indexterm>
532 </listitem>
533 </varlistentry>
534
535 <varlistentry id="cargo-fmt">
536 <term><command>cargo-fmt</command></term>
537 <listitem>
538 <para>
539 formats all bin and lib files of the current crate using
540 rustfmt.
541 </para>
542 <indexterm zone="rust cargo-fmt">
543 <primary sortas="b-cargo-fmt">cargo-fmt</primary>
544 </indexterm>
545 </listitem>
546 </varlistentry>
547
548 <varlistentry id="cargo-miri">
549 <term><command>cargo-miri</command></term>
550 <listitem>
551 <para>
552 <!-- FIXME reword to 'is used by' if Miri installed
553 AND works enough to report its \-\-help -->
554 is for use by Miri to interpret bin crates and tests
555 </para>
556 <indexterm zone="rust cargo-miri">
557 <primary sortas="b-cargo-miri">cargo-miri</primary>
558 </indexterm>
559 </listitem>
560 </varlistentry>
561
562 <varlistentry id="cargo">
563 <term><command>cargo</command></term>
564 <listitem>
565 <para>
566 is the Package Manager for Rust.
567 </para>
568 <indexterm zone="rust cargo">
569 <primary sortas="b-cargo">cargo</primary>
570 </indexterm>
571 </listitem>
572 </varlistentry>
573
574 <varlistentry id="clippy-driver">
575 <term><command>clippy-driver</command></term>
576 <listitem>
577 <para>
578 provides lint checks for Rust.
579 </para>
580 <indexterm zone="rust clippy-driver">
581 <primary sortas="b-clippy-driver">clippy-driver</primary>
582 </indexterm>
583 </listitem>
584 </varlistentry>
585
586 <varlistentry id="miri">
587 <term><command>miri</command></term>
588 <listitem>
589 <para>
590 is an interpreter for Rust's mid-level intermediate representation
591 (MIR). It is broken in this version.
592 </para>
593 <indexterm zone="rust miri">
594 <primary sortas="b-miri">miri</primary>
595 </indexterm>
596 </listitem>
597 </varlistentry>
598
599 <varlistentry id="rls">
600 <term><command>rls</command></term>
601 <listitem>
602 <para>
603 is the Rust Language Server. This can run in the background to
604 provide IDEs, editors, and other tools with information about Rust
605 programs.
606 </para>
607 <indexterm zone="rust rls">
608 <primary sortas="b-rls">rls</primary>
609 </indexterm>
610 </listitem>
611 </varlistentry>
612
613 <varlistentry id="rust-gdb">
614 <term><command>rust-gdb</command></term>
615 <listitem>
616 <para>
617 is a wrapper script for gdb, pulling in Python
618 pretty-printing modules installed in <filename
619 class="directory">/usr/lib/rustlib/etc</filename>.
620 </para>
621 <indexterm zone="rust rust-gdb">
622 <primary sortas="b-rust-gdb">rust-gdb</primary>
623 </indexterm>
624 </listitem>
625 </varlistentry>
626
627 <varlistentry id="rust-lldb">
628 <term><command>rust-lldb</command></term>
629 <listitem>
630 <para>
631 is a wrapper script for LLDB (the LLVM debugger)
632 pulling in the Python pretty-printing modules.
633 </para>
634 <indexterm zone="rust rust-lldb">
635 <primary sortas="b-rust-lldb">rust=lldb</primary>
636 </indexterm>
637 </listitem>
638 </varlistentry>
639
640 <varlistentry id="rustc">
641 <term><command>rustc</command></term>
642 <listitem>
643 <para>
644 is the rust compiler.
645 </para>
646 <indexterm zone="rust rustc">
647 <primary sortas="b-rustc">rustc</primary>
648 </indexterm>
649 </listitem>
650 </varlistentry>
651
652 <varlistentry id="rustdoc">
653 <term><command>rustdoc</command></term>
654 <listitem>
655 <para>
656 generates documentation from rust source code.
657 </para>
658 <indexterm zone="rust rustdoc">
659 <primary sortas="b-rustdoc">rustdoc</primary>
660 </indexterm>
661 </listitem>
662 </varlistentry>
663
664 <varlistentry id="rustfmt">
665 <term><command>rustfmt</command></term>
666 <listitem>
667 <para>
668 formats rust code.
669 </para>
670 <indexterm zone="rust rustfmt">
671 <primary sortas="b-rustfmt">rustfmt</primary>
672 </indexterm>
673 </listitem>
674 </varlistentry>
675
676 <varlistentry id="libstd">
677 <term><filename class="libraryfile">libstd-&lt;16-byte-hash&gt;.so</filename></term>
678 <listitem>
679 <para>
680 is the Rust Standard Library, the foundation of portable Rust software.
681 </para>
682 <indexterm zone="rust libstd">
683 <primary sortas="c-libstd">libstd-&lt;16-byte-hash&gt;.so</primary>
684 </indexterm>
685 </listitem>
686 </varlistentry>
687 </variablelist>
688 </sect2>
689</sect1>
Note: See TracBrowser for help on using the repository browser.