source: general/prog/rust.xml@ 38489aa0

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

Tags

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

  • Property mode set to 100644
File size: 23.4 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"/> (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)
190 </para>
191
192 <para condition="html" role="usernotes">
193 User Notes: <ulink url="&blfs-wiki;/rust"/>
194 </para>
195 </sect2>
196
197 <sect2 role="installation">
198 <title>Installation of Rust</title>
199
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
212 <note>
213 <para>
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>.
218 </para>
219 </note>
220
221 <para>
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.
228 </para>
229
230<screen><userinput>cat &lt;&lt; EOF &gt; config.toml
231# see config.toml.example for more possible options
232[llvm]
233
234# use ninja
235ninja = true
236
237targets = "X86"
238# When compiling LLVM, the experimental targets (WebAssembly
239# and RISCV) are built by default - omit them
240experimental-targets = ""
241
242[build]
243# omit HTML docs to save time and space (comment this to build them)
244docs = false
245
246# install cargo as well as rust
247extended = true
248
249[install]
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
255docdir = "share/doc/rustc-&rust-version;"
256
257[rust]
258channel = "stable"
259rpath = false
260
261# BLFS does not install the FileCheck executable from llvm,
262# so disable codegen tests
263codegen-tests = false
264
265# get a trace if there is an Internal Compiler Exception
266backtrace-on-ice = true
267
268EOF</userinput></screen>
269
270 <para>
271 Now install <application>Rust</application> by running the following
272 commands:
273 </para>
274
275<screen><userinput>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi" &amp;&amp;
276python3 ./x.py build --exclude src/tools/miri</userinput></screen>
277
278 <note>
279 <para>
280 The testsuite will generate some messages in the
281 <phrase revision="sysv">system log</phrase>
282 <phrase revision="systemd">systemd journal</phrase>
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:
316 </para>
317
318<screen><command>grep 'running .* tests' rustc-testlog | awk '{ sum += $2 } END { print sum }'</command></screen>
319
320 <para>
321 That should report 15795 tests. Similarly, the total tests which failed can
322 be found by running:
323 </para>
324
325<screen><command>grep '^test result:' rustc-testlog | awk '{ sum += $6 } END { print sum }'</command></screen>
326
327 <para>
328 And similarly for the tests which passed use $4, for those which were ignored
329 (i.e. skipped) use $8 (and $10 for 'measured', $12 for 'filtered out' but both
330 are probably zero). The breakdown does not quite match the overall total.
331 </para>
332
333 <para>
334 Still as your normal user, do a DESTDIR install:
335 </para>
336
337<screen><userinput>export LIBSSH2_SYS_USE_PKG_CONFIG=1 &amp;&amp;
338DESTDIR=${PWD}/install python3 ./x.py install &amp;&amp;
339unset LIBSSH2_SYS_USE_PKG_CONFIG</userinput></screen>
340
341 <para>
342 Now, as the <systemitem class="username">root</systemitem> user
343 install the files from the DESTDIR:
344 </para>
345
346<screen role="root"><userinput>chown -R root:root install &amp;&amp;
347cp -a install/* /</userinput></screen>
348
349 </sect2>
350
351 <sect2 role="commands">
352 <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>
360
361 <para>
362 <command>targets = "X86"</command>: this avoids building all the available
363 linux cross-compilers (Aarch64, MIPS, PowerPC, SystemZ, etc). Unfortunately,
364 rust insists on installing source files for these below
365 <filename class="directory">/usr/lib/rustlib/src</filename>.
366 </para>
367
368 <para>
369 <command>extended = true</command>: this installs Cargo alongside Rust.
370 </para>
371
372 <para>
373 <command>channel = "stable"</command>: this ensures only stable features
374 can be used, the default in <filename>config.toml</filename> is to use
375 development features, which is not appropriate for a released version.
376 </para>
377
378 <para>
379 <command>rpath = false</command>: by default, <command>rust</command> can
380 be run from where it was built, without being installed. That adds DT_RPATH
381 entries to all of the ELF files, which produces very messy output from
382 <command>ldd</command>, showing the libraries in the place they were built,
383 even if they have been deleted from there after the install.
384 </para>
385
386 <!-- comment while using shipped LLVM
387 <para>
388 <command>[target.x86_64-unknown-linux-gnu]</command>: the syntax of
389 <filename>config.toml</filename> requires an <literal>llvm-config</literal>
390 entry for each target for which system-llvm is to be used. Change the target
391 to <literal>[target.i686-unknown-linux-gnu]</literal> if you are building
392 on 32-bit x86. This whole section may be omitted if you wish to build
393 against the shipped llvm, or do not have clang, but the resulting build will
394 be larger and take longer.
395 </para>-->
396
397 <para>
398 <command>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi"</command>:
399 This adds a link to libffi to any RUSTFLAGS you may already be passing
400 to the build. On some systems, linking fails to include libffi unless
401 this is used. The reason why this is needed is not clear.
402 </para>
403
404 <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>
412 <command>--verbose</command>: this switch can sometimes provide more
413 information about a test which fails.
414 </para>
415
416 <para>
417 <command>--no-fail-fast</command>: this switch ensures that the testsuite
418 will not stop at the first error.
419 </para>
420
421 <para>
422 <command>export LIBSSH2_SYS_USE_PKG_CONFIG=1</command>: On some systems,
423 cairo fails to link during the install because it cannot find libssh2.
424 This seems to fix it, but again the reason why the problem occurs is not
425 understood.
426 </para>
427
428 <para>
429 <command>DESTDIR=${PWD}/install python3 ./x.py install</command>: This
430 effects a DESTDIR-style install in the source tree,creating an <filename
431 class="directory">install</filename> directory. Note that DESTDIR installs
432 need an absolute path, passing 'install' will not work.
433 </para>
434
435 <para>
436 <command>chown -R root:root install</command>: the DESTDIR install
437 was run by a regular user, who owns the files. For security, change their
438 owner before doing a simple copy to install them.
439 </para>
440
441 </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
497
498 <sect2 role="content">
499 <title>Contents</title>
500
501 <segmentedlist>
502 <segtitle>Installed Programs</segtitle>
503 <segtitle>Installed Libraries</segtitle>
504 <segtitle>Installed Directories</segtitle>
505
506 <seglistitem>
507 <seg>
508 cargo-clippy, cargo-fmt, cargo, clippy-driver, rls, rust-gdb, rust-lldb, rustc, rustdoc, rustfmt.
509 </seg>
510 <seg>
511 Many lib*&lt;16-byte-hash&gt;.so libraries.
512 </seg>
513 <seg>
514 ~/.cargo,
515 /usr/lib/rustlib,
516 /usr/share/doc/rustc-&rust-version;, and
517 /usr/share/zsh/site-functions/
518 </seg>
519 </seglistitem>
520 </segmentedlist>
521
522 <variablelist>
523 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
524 <?dbfo list-presentation="list"?>
525 <?dbhtml list-presentation="table"?>
526
527 <varlistentry id="cargo-clippy">
528 <term><command>cargo-clippy</command></term>
529 <listitem>
530 <para>
531 provides lint checks for a cargo package.
532 </para>
533 <indexterm zone="rust cargo-clippy">
534 <primary sortas="b-cargo-clippy">cargo-clippy</primary>
535 </indexterm>
536 </listitem>
537 </varlistentry>
538
539 <varlistentry id="cargo-fmt">
540 <term><command>cargo-fmt</command></term>
541 <listitem>
542 <para>
543 formats all bin and lib files of the current crate using
544 rustfmt.
545 </para>
546 <indexterm zone="rust cargo-fmt">
547 <primary sortas="b-cargo-fmt">cargo-fmt</primary>
548 </indexterm>
549 </listitem>
550 </varlistentry>
551
552 <varlistentry id="cargo">
553 <term><command>cargo</command></term>
554 <listitem>
555 <para>
556 is the Package Manager for Rust.
557 </para>
558 <indexterm zone="rust cargo">
559 <primary sortas="b-cargo">cargo</primary>
560 </indexterm>
561 </listitem>
562 </varlistentry>
563
564 <varlistentry id="clippy-driver">
565 <term><command>clippy-driver</command></term>
566 <listitem>
567 <para>
568 provides lint checks for Rust.
569 </para>
570 <indexterm zone="rust clippy-driver">
571 <primary sortas="b-clippy-driver">clippy-driver</primary>
572 </indexterm>
573 </listitem>
574 </varlistentry>
575
576 <varlistentry id="rls">
577 <term><command>rls</command></term>
578 <listitem>
579 <para>
580 is the Rust Language Server. This can run in the background to
581 provide IDEs, editors, and other tools with information about Rust
582 programs.
583 </para>
584 <indexterm zone="rust rls">
585 <primary sortas="b-rls">rls</primary>
586 </indexterm>
587 </listitem>
588 </varlistentry>
589
590 <varlistentry id="rust-gdb">
591 <term><command>rust-gdb</command></term>
592 <listitem>
593 <para>
594 is a wrapper script for gdb, pulling in Python
595 pretty-printing modules installed in <filename
596 class="directory">/usr/lib/rustlib/etc</filename>.
597 </para>
598 <indexterm zone="rust rust-gdb">
599 <primary sortas="b-rust-gdb">rust-gdb</primary>
600 </indexterm>
601 </listitem>
602 </varlistentry>
603
604 <varlistentry id="rust-lldb">
605 <term><command>rust-lldb</command></term>
606 <listitem>
607 <para>
608 is a wrapper script for LLDB (the LLVM debugger)
609 pulling in the Python pretty-printing modules.
610 </para>
611 <indexterm zone="rust rust-lldb">
612 <primary sortas="b-rust-lldb">rust=lldb</primary>
613 </indexterm>
614 </listitem>
615 </varlistentry>
616
617 <varlistentry id="rustc">
618 <term><command>rustc</command></term>
619 <listitem>
620 <para>
621 is the rust compiler.
622 </para>
623 <indexterm zone="rust rustc">
624 <primary sortas="b-rustc">rustc</primary>
625 </indexterm>
626 </listitem>
627 </varlistentry>
628
629 <varlistentry id="rustdoc">
630 <term><command>rustdoc</command></term>
631 <listitem>
632 <para>
633 generates documentation from rust source code.
634 </para>
635 <indexterm zone="rust rustdoc">
636 <primary sortas="b-rustdoc">rustdoc</primary>
637 </indexterm>
638 </listitem>
639 </varlistentry>
640
641 <varlistentry id="rustfmt">
642 <term><command>rustfmt</command></term>
643 <listitem>
644 <para>
645 formats rust code.
646 </para>
647 <indexterm zone="rust rustfmt">
648 <primary sortas="b-rustfmt">rustfmt</primary>
649 </indexterm>
650 </listitem>
651 </varlistentry>
652
653 <varlistentry id="libstd">
654 <term><filename class="libraryfile">libstd-&lt;16-byte-hash&gt;.so</filename></term>
655 <listitem>
656 <para>
657 is the Rust Standard Library, the foundation of portable Rust software.
658 </para>
659 <indexterm zone="rust libstd">
660 <primary sortas="c-libstd">libstd-&lt;16-byte-hash&gt;.so</primary>
661 </indexterm>
662 </listitem>
663 </varlistentry>
664 </variablelist>
665 </sect2>
666</sect1>
Note: See TracBrowser for help on using the repository browser.