source: general/prog/rust.xml@ bc625a7d

10.0 10.1 11.0 11.1 11.2 9.0 9.1 lazarus plabs/python-mods qt5new trunk upgradedb xry111/intltool xry111/soup3 xry111/test-20220226
Last change on this file since bc625a7d was bc625a7d, checked in by Xi Ruoyao <xry111@…>, 4 years ago

Rephrase the optional dependency to P2 of rustc

Now we always build GDB with P3 so we should not refer to a GDB built with P2.

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

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