source: general/prog/rust.xml@ 25997c4

10.0 10.1 11.0 11.1 11.2 8.4 9.0 9.1 bdubbs/svn lazarus plabs/python-mods qt5new trunk upgradedb xry111/intltool xry111/soup3 xry111/test-20220226
Last change on this file since 25997c4 was 25997c4, checked in by Ken Moffat <ken@…>, 4 years ago

Rustc-1.32.0. I've moved the Note about only updating when necessary into the introduction as ordinary text, added some details about deleting an older version before updating, and reworked the text about testing. That might still need a little tweaking, but best to get the updated instructions out because people have been having trouble interpreting their results. Thanks to all the people who have helped on this version, both here and on the issues at rust.

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

  • Property mode set to 100644
File size: 19.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 (that would require <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 When you upgrade to a newer version, the new libraries will have various
77 hashes in their names and therefore there will be a mix of versions but
78 only one of each will be usable. A binary distribution would use its
79 package manager to delete all the old <application>rust</application>
80 installation before updating. You may wish to do the same to save space.
81 </para>
82 </note>
83
84 <para>
85 The current <application>rustbuild</application> build-system will use
86 all available processors, although it does not scale well and often falls
87 back to just using one core while waiting for a library to compile.
88 </para>
89
90 <para>
91 At the moment <application>Rust</application> does not provide any
92 guarantees of a stable ABI.
93 </para>
94
95 <note>
96 <para>
97 Rustc defaults to building for ALL supported architectures, using a
98 shipped copy of LLVM. In BLFS the build is only for the X86 architecture.
99 If you
100 intend to develop rust crates, this build may not be good enough for your
101 purposes.
102 </para>
103 <para>
104 Unlike with previous versions, the build times of this version when
105 repeated on the same machine seem reasonably consistent.
106 </para>
107 <para>
108 Unusually, a DESTDIR-style method is being used to install this package.
109 This is because running the install as root not only downloads all of the
110 cargo files again (to <filename>/root/.cargo</filename>), it then spends
111 a very long time recompiling. Using this method saves a lot of time, at
112 the cost of extra disk space.
113 </para>
114 </note>
115
116 &lfs83_checked;
117
118 <bridgehead renderas="sect3">Package Information</bridgehead>
119 <itemizedlist spacing="compact">
120 <listitem>
121 <para>
122 Download (HTTP): <ulink url="&rust-download-http;"/>
123 </para>
124 </listitem>
125 <listitem>
126 <para>
127 Download (FTP): <ulink url="&rust-download-ftp;"/>
128 </para>
129 </listitem>
130 <listitem>
131 <para>
132 Download MD5 sum: &rust-md5sum;
133 </para>
134 </listitem>
135 <listitem>
136 <para>
137 Download size: &rust-size;
138 </para>
139 </listitem>
140 <listitem>
141 <para>
142 Estimated disk space required: &rust-buildsize;
143 </para>
144 </listitem>
145 <listitem>
146 <para>
147 Estimated build time: &rust-time;
148 </para>
149 </listitem>
150 </itemizedlist>
151
152 <bridgehead renderas="sect3">Rust Dependencies</bridgehead>
153
154 <bridgehead renderas="sect4">Required</bridgehead>
155 <para role="required">
156 <xref linkend="curl"/>,
157 <xref linkend="cmake"/>,
158 <xref linkend="libssh2"/>, and
159 <xref linkend="python2"/>
160 </para>
161
162<!-- comment out while using shipped LLVM
163 <bridgehead renderas="sect4">Recommended</bridgehead>
164 <para role="recommended">
165 <package>clang</package> from <xref linkend="llvm"/>
166 (built with -DLLVM_LINK_LLVM_DYLIB=ON)
167 </para>-->
168
169 <bridgehead renderas="sect4">Optional</bridgehead>
170 <para role="optional">
171 <xref linkend="gdb"/> (used by the testsuite if it is present)
172 </para>
173
174 <para condition="html" role="usernotes">
175 User Notes: <ulink url="&blfs-wiki;/rust"/>
176 </para>
177 </sect2>
178
179 <sect2 role="installation">
180 <title>Installation of Rust</title>
181
182 <para>
183 First create a suitable <filename>config.toml</filename> file which will
184 configure the build. Unlike with previous releases, where even quite old
185 system versions of <application>LLVM</application>worked well, this
186 version ships with a development version and using the current <xref
187 linkend="llvm"/> release is known to result in breakage in some
188 circumstances.
189 </para>
190
191<screen><userinput>cat &lt;&lt; EOF &gt; config.toml
192# see config.toml.example for more possible options
193[llvm]
194
195# use ninja
196ninja = true
197
198targets = "X86"
199# When compiling LLVM, the experimental targets (WebAssembly
200# and RISCV) are built by default - omit them
201experimental-targets = ""
202
203[build]
204# omiti HTML docs to save time and space (comment this to build them)
205docs = false
206
207# install cargo as well as rust
208extended = true
209
210[install]
211prefix = "/usr"
212# docdir is used even if the full awesome docs are not installed
213docdir = "share/doc/rustc-&rust-version;"
214
215[rust]
216channel = "stable"
217rpath = false
218
219# BLFS does not install the FileCheck executable from llvm,
220# so disable codegen tests
221codegen-tests = false
222
223# get a trace if there is an Internal Compiler Exception
224backtrace-on-ice = true
225
226EOF</userinput></screen>
227
228 <para>
229 Now install <application>Rust</application> by running the following
230 commands:
231 </para>
232
233<screen><userinput>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi" &amp;&amp;
234./x.py build --exclude src/tools/miri</userinput></screen>
235
236 <note>
237 <para>
238 The testsuite will generate some messages in the
239 <phrase revision="sysv">system log</phrase>
240 <phrase revision="systemd">systemd journal</phrase>
241 for traps on invalid opcodes, and for segmentation faults.
242 In themselves these are nothing to worry about, just a way for the
243 test to be terminated. But if the output from the testsuite reports tests
244 which FAIL with segmentation faults (signal 11) then there may be a
245 problem.
246 </para>
247 </note>
248
249 <para>
250 To run the tests issue
251 <command>./x.py test --verbose --no-fail-fast | tee rustc-testlog</command>:
252 as with the build, that will use all available CPUs.
253 </para>
254
255 <para>
256 The instructions above do not build ARM compilers, so the testsuite
257 <emphasis>will</emphasis> fail and the tests will be reported to end in
258 error, with a backtrace of the last failing test. On a good run, 3 tests
259 which need Thumb (ARM) compilers will fail, all in <filename
260 class="directory">ui/issues</filename> for issues 37131, 49851 and 50993.
261 Occasionally a fourth test, in run-make, 'sysroot-crates-are-unstable',
262 has been known to fail. That is probably harmless. As with all large
263 testsuites, other tests might fail on some machines - if the number of
264 failures is in the single digits, check the log for 'FAILED' and review
265 lines above that. Any mention of SIGSEGV or signal 11 in a failing test
266 is a cause for concern.
267 </para>
268
269 <para>
270 Therefore, you should determine the number of tests, failures, etc. The
271 total number of tests which were considered is found by running:
272 </para>
273
274<screen><command>grep 'running .* tests' rustc-testlog | awk '{ sum += $2 } END { print sum }'</command></screen>
275
276 <para>
277 That should report 15795 tests. Similarly, the total tests which failed can
278 be found by running:
279 </para>
280
281<screen><command>grep '^test result:' rustc-testlog | awk '{ sum += $6 } END { print sum }'</command></screen>
282
283 <para>
284 And similarly for the tests which passed use $4, for those which were ignored
285 (i.e. skipped) use $8 (and $10 for 'measured', $12 for 'filtered out' but both
286 are probably zero). The breakdown does not quite match the overall total.
287 </para>
288
289 <para>
290 Still as your normal user, do a DESTDIR install:
291 </para>
292
293<screen><userinput>export LIBSSH2_SYS_USE_PKG_CONFIG=1 &amp;&amp;
294DESTDIR=${PWD}/install ./x.py install &amp;&amp;
295unset LIBSSH2_SYS_USE_PKG_CONFIG</userinput></screen>
296
297 <para>
298 Now, as the <systemitem class="username">root</systemitem> user
299 install the files from the DESTDIR:
300 </para>
301
302<screen role="root"><userinput>chown -R root:root install &amp;&amp;
303cp -a install/* /</userinput></screen>
304
305 </sect2>
306
307 <sect2 role="commands">
308 <title>Command Explanations</title>
309
310 <para>
311 <command>targets = "X86"</command>: this avoids building all the available
312 linux cross-compilers (Aarch64, MIPS, PowerPC, SystemZ, etc). Unfortunately,
313 rust insists on installing source files for these below
314 <filename class="directory">/usr/lib/rustlib/src</filename>.
315 </para>
316
317 <para>
318 <command>extended = true</command>: this installs Cargo alongside Rust.
319 </para>
320
321 <para>
322 <command>channel = "stable"</command>: this ensures only stable features
323 can be used, the default in <filename>config.toml</filename> is to use
324 development features, which is not appropriate for a released version.
325 </para>
326
327 <para>
328 <command>rpath = false</command>: by default, <command>rust</command> can
329 be run from where it was built, without being installed. That adds DT_RPATH
330 entries to all of the ELF files, which produces very messy output from
331 <command>ldd</command>, showing the libraries in the place they were built,
332 even if they have been deleted from there after the install.
333 </para>
334
335 <!-- comment while using shipped LLVM
336 <para>
337 <command>[target.x86_64-unknown-linux-gnu]</command>: the syntax of
338 <filename>config.toml</filename> requires an <literal>llvm-config</literal>
339 entry for each target for which system-llvm is to be used. Change the target
340 to <literal>[target.i686-unknown-linux-gnu]</literal> if you are building
341 on 32-bit x86. This whole section may be omitted if you wish to build
342 against the shipped llvm, or do not have clang, but the resulting build will
343 be larger and take longer.
344 </para>-->
345
346 <para>
347 <command>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi"</command>:
348 This adds a link to libffi to any RUSTFLAGS you may already be passing
349 to the build. On some systems, linking fails to include libffi unless
350 this is used. The reason why this is needed is not clear.
351 </para>
352
353 <para>
354 <command>--exclude src/tools/miri</command>: For a long time, the miri
355 crate (an interpreter for the Midlevel Intermediate Representation)
356 has failed to build on releases. It is optional, but the failure
357 messages can persuade people that the whole build failed.
358 </para>
359
360 <para>
361 <command>--verbose</command>: this switch can sometimes provide more
362 information about a test which fails.
363 </para>
364
365 <para>
366 <command>--no-fail-fast</command>: this switch ensures that the testsuite
367 will not stop at the first error.
368 </para>
369
370 <para>
371 <command>export LIBSSH2_SYS_USE_PKG_CONFIG=1</command>: On some systems,
372 cairo fails to link during the install because it cannot find libssh2.
373 This seems to fix it, but again the reason why the problem occurs is not
374 understood.
375 </para>
376
377 <para>
378 <command>DESTDIR=${PWD}/install ./x.py install</command>: This effects a
379 DESTDIR-style install in the source tree,creating an <filename
380 class="directory">install</filename> directory. Note that DESTDIR installs
381 need an absolute path, passing 'install' will not work.
382 </para>
383
384 <para>
385 <command>chown -R root:root install</command>: the DESTDIR install
386 was run by a regular user, who owns the files. For security, change their
387 owner before doing a simple copy to install them.
388 </para>
389
390 </sect2>
391
392 <sect2 role="content">
393 <title>Contents</title>
394
395 <segmentedlist>
396 <segtitle>Installed Programs</segtitle>
397 <segtitle>Installed Libraries</segtitle>
398 <segtitle>Installed Directories</segtitle>
399
400 <seglistitem>
401 <seg>
402 cargo-clippy, cargo-fmt, cargo, clippy-driver, rls, rust-gdb, rust-lldb, rustc, rustdoc, rustfmt.
403 </seg>
404 <seg>
405 Many lib*&lt;16-byte-hash&gt;.so libraries.
406 </seg>
407 <seg>
408 ~/.cargo,
409 /usr/lib/rustlib,
410 /usr/share/doc/rustc-&rust-version;, and
411 /usr/share/zsh/site-functions/
412 </seg>
413 </seglistitem>
414 </segmentedlist>
415
416 <variablelist>
417 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
418 <?dbfo list-presentation="list"?>
419 <?dbhtml list-presentation="table"?>
420
421 <varlistentry id="cargo-clippy">
422 <term><command>cargo-clippy</command></term>
423 <listitem>
424 <para>
425 provides lint checks for a cargo package.
426 </para>
427 <indexterm zone="rust cargo-clippy">
428 <primary sortas="b-cargo-clippy">cargo-clippy</primary>
429 </indexterm>
430 </listitem>
431 </varlistentry>
432
433 <varlistentry id="cargo-fmt">
434 <term><command>cargo-fmt</command></term>
435 <listitem>
436 <para>
437 formats all bin and lib files of the current crate using
438 rustfmt.
439 </para>
440 <indexterm zone="rust cargo-fmt">
441 <primary sortas="b-cargo-fmt">cargo-fmt</primary>
442 </indexterm>
443 </listitem>
444 </varlistentry>
445
446 <varlistentry id="cargo">
447 <term><command>cargo</command></term>
448 <listitem>
449 <para>
450 is the Package Manager for Rust.
451 </para>
452 <indexterm zone="rust cargo">
453 <primary sortas="b-cargo">cargo</primary>
454 </indexterm>
455 </listitem>
456 </varlistentry>
457
458 <varlistentry id="clippy-driver">
459 <term><command>clippy-driver</command></term>
460 <listitem>
461 <para>
462 provides lint checks for Rust.
463 </para>
464 <indexterm zone="rust clippy-driver">
465 <primary sortas="b-clippy-driver">clippy-driver</primary>
466 </indexterm>
467 </listitem>
468 </varlistentry>
469
470 <varlistentry id="rls">
471 <term><command>rls</command></term>
472 <listitem>
473 <para>
474 is the Rust Language Server. This can run in the background to
475 provide IDEs, editors, and other tools with information about Rust
476 programs.
477 </para>
478 <indexterm zone="rust rls">
479 <primary sortas="b-rls">rls</primary>
480 </indexterm>
481 </listitem>
482 </varlistentry>
483
484 <varlistentry id="rust-gdb">
485 <term><command>rust-gdb</command></term>
486 <listitem>
487 <para>
488 is a wrapper script for gdb, pulling in Python
489 pretty-printing modules installed in <filename
490 class="directory">/usr/lib/rustlib/etc</filename>.
491 </para>
492 <indexterm zone="rust rust-gdb">
493 <primary sortas="b-rust-gdb">rust-gdb</primary>
494 </indexterm>
495 </listitem>
496 </varlistentry>
497
498 <varlistentry id="rust-lldb">
499 <term><command>rust-lldb</command></term>
500 <listitem>
501 <para>
502 is a wrapper script for LLDB (the LLVM debugger)
503 pulling in the Python pretty-printing modules.
504 </para>
505 <indexterm zone="rust rust-lldb">
506 <primary sortas="b-rust-lldb">rust=lldb</primary>
507 </indexterm>
508 </listitem>
509 </varlistentry>
510
511 <varlistentry id="rustc">
512 <term><command>rustc</command></term>
513 <listitem>
514 <para>
515 is the rust compiler.
516 </para>
517 <indexterm zone="rust rustc">
518 <primary sortas="b-rustc">rustc</primary>
519 </indexterm>
520 </listitem>
521 </varlistentry>
522
523 <varlistentry id="rustdoc">
524 <term><command>rustdoc</command></term>
525 <listitem>
526 <para>
527 generates documentation from rust source code.
528 </para>
529 <indexterm zone="rust rustdoc">
530 <primary sortas="b-rustdoc">rustdoc</primary>
531 </indexterm>
532 </listitem>
533 </varlistentry>
534
535 <varlistentry id="rustfmt">
536 <term><command>rustfmt</command></term>
537 <listitem>
538 <para>
539 formats rust code.
540 </para>
541 <indexterm zone="rust rustfmt">
542 <primary sortas="b-rustfmt">rustfmt</primary>
543 </indexterm>
544 </listitem>
545 </varlistentry>
546
547 <varlistentry id="libstd">
548 <term><filename class="libraryfile">libstd-&lt;16-byte-hash&gt;.so</filename></term>
549 <listitem>
550 <para>
551 is the Rust Standard Library, the foundation of portable Rust software.
552 </para>
553 <indexterm zone="rust libstd">
554 <primary sortas="c-libstd">libstd-&lt;16-byte-hash&gt;.so</primary>
555 </indexterm>
556 </listitem>
557 </varlistentry>
558 </variablelist>
559 </sect2>
560</sect1>
Note: See TracBrowser for help on using the repository browser.