source: general/prog/rust.xml@ 6bcd464

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 6bcd464 was 6bcd464, checked in by Ken Moffat <ken@…>, 4 years ago

Rust: I was mistaken about the Ryzen problem with the testsuite, traps and a few segfaults are normal but nobody usually looks at the syslog.

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

  • Property mode set to 100644
File size: 16.9 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 "6790c24fe5e8fb5a5f7efbfbcc6fea65">
10 <!ENTITY rust-size "101 MB">
11 <!ENTITY rust-buildsize "6.5 GB (679 MB installed) including 270MB of ~/.cargo files for the user building this (add 1.4GB if running the tests)">
12 <!ENTITY rust-time "27 SBU (add 13 SBU for tests, both with 4 processors)">
13]>
14
15<sect1 id="rust" xreflabel="rustc-&rust-version;">
16 <?dbhtml filename="rust.html"?>
17
18 <sect1info>
19 <othername>$LastChangedBy$</othername>
20 <date>$Date$</date>
21 </sect1info>
22
23 <title>Rustc-&rust-version;</title>
24
25 <indexterm zone="rust">
26 <primary sortas="a-rust">Rust</primary>
27 </indexterm>
28
29 <sect2 role="package">
30 <title>Introduction to Rust</title>
31
32 <para>
33 The <application>Rust</application> programming language is designed
34 to be a safe, concurrent, practical language.
35 </para>
36
37 <para>
38 As with many other programming languages, rustc (the rust compiler)
39 needs a binary from which to bootstrap. It will download a stage0 binary
40 and many cargo crates (these are actually .tar.gz source archives) at
41 the start of the build, so you cannot compile it without an internet
42 connection.
43 </para>
44
45 <para>
46 The current <application>rustbuild</application> build-system will use
47 all available processors, although it does not scale well and often falls
48 back to just using one core while waiting for a library to compile.
49 </para>
50
51 <para>
52 At the moment <application>Rust</application> does not provide any
53 guarantees of a stable ABI.
54 </para>
55
56 <note>
57 <para>
58 Rustc defaults to building for ALL supported architectures, using a
59 shipped copy of LLVM. In BLFS the build is only for the X86 architecture.
60 If you
61 intend to develop rust crates, this build may not be good enough for your
62 purposes.
63 </para>
64 <para>
65 Repeated builds of this package on the same machine show a wide range
66 of build times. Some of this might be due to variations in downloading
67 the required cargo files if they are not already present, but this does
68 not seem to adequately explain the variations.
69 </para>
70 <para>
71 Unusually, a DESTDIR-style method is being used to install this package.
72 This is because running the install as root not only downloads all of the
73 cargo files again (to <filename>/root/.cargo</filename>), it then spends
74 a very long time recompiling. Using this method saves a lot of time, at
75 the cost of extra disk space.
76 </para>
77 </note>
78
79 &lfs83_checked;
80
81 <bridgehead renderas="sect3">Package Information</bridgehead>
82 <itemizedlist spacing="compact">
83 <listitem>
84 <para>
85 Download (HTTP): <ulink url="&rust-download-http;"/>
86 </para>
87 </listitem>
88 <listitem>
89 <para>
90 Download (FTP): <ulink url="&rust-download-ftp;"/>
91 </para>
92 </listitem>
93 <listitem>
94 <para>
95 Download MD5 sum: &rust-md5sum;
96 </para>
97 </listitem>
98 <listitem>
99 <para>
100 Download size: &rust-size;
101 </para>
102 </listitem>
103 <listitem>
104 <para>
105 Estimated disk space required: &rust-buildsize;
106 </para>
107 </listitem>
108 <listitem>
109 <para>
110 Estimated build time: &rust-time;
111 </para>
112 </listitem>
113 </itemizedlist>
114
115 <bridgehead renderas="sect3">Rust Dependencies</bridgehead>
116
117 <bridgehead renderas="sect4">Required</bridgehead>
118 <para role="required">
119 <xref linkend="curl"/>,
120 <xref linkend="cmake"/>,
121 <xref linkend="libssh2"/>, and
122 <xref linkend="python2"/>
123 </para>
124
125 <bridgehead renderas="sect4">Recommended</bridgehead>
126 <para role="recommended">
127 <package>clang</package> from <xref linkend="llvm"/>
128 (built with -DLLVM_LINK_LLVM_DYLIB=ON)
129 </para>
130
131 <bridgehead renderas="sect4">Optional</bridgehead>
132 <para role="optional">
133 <xref linkend="gdb"/> (recommended if running the testsuite)
134 </para>
135
136 <para condition="html" role="usernotes">
137 User Notes: <ulink url="&blfs-wiki;/rust"/>
138 </para>
139 </sect2>
140
141 <sect2 role="installation">
142 <title>Installation of Rust</title>
143
144 <note>
145 <para>
146 This package is updated on a six-weekly release cycle. Because it is
147 such a large and slow package to build, and is at the moment only required
148 by five packages in this book, the BLFS editors take the view that it
149 should only be updated when that is necessary.
150 </para>
151 </note>
152
153 <para>
154 First create a suitable <filename>config.toml</filename> file
155 which will configure the build :
156 </para>
157
158<screen><userinput>cat &lt;&lt; EOF &gt; config.toml
159# see config.toml.example for more possible options
160[llvm]
161targets = "X86"
162
163# When using system llvm prefer shared libraries
164link-shared = true
165
166[build]
167# install cargo as well as rust
168extended = true
169
170[install]
171prefix = "/usr"
172docdir = "share/doc/rustc-&rust-version;"
173
174[rust]
175channel = "stable"
176rpath = false
177
178# BLFS does not install the FileCheck executable from llvm,
179# so disable codegen tests
180codegen-tests = false
181
182[target.x86_64-unknown-linux-gnu]
183# delete this *section* if you are not using system llvm.
184# NB the output of llvm-config (i.e. help options) may be
185# dumped to the screen when config.toml is parsed.
186llvm-config = "/usr/bin/llvm-config"
187
188EOF</userinput></screen>
189
190 <para>
191 Now install <application>Rust</application> by running the following
192 commands:
193 </para>
194
195<screen><userinput>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi" &amp;&amp;
196./x.py build</userinput></screen>
197
198 <para>
199 The build will report it failed to compile <filename>miri</filename>
200 because of multiple potential crates for `log`, but that should be followed
201 by a message that the build completed successfully.
202 </para>
203
204 <note>
205 <para>
206 The testsuite will generate some messages in the
207 <phrase revision="sysv">system log</phrase>
208 <phrase revision="systemd">systemd journal</phrase>
209 for traps on invalid opcodes, and for segmentation faults.
210 In themselves these are nothing to worry about, although if the
211 output from the testsuite reports tests which FAIL with such faults
212 then there may be a problem.
213 </para>
214 </note>
215
216 <para>
217 To run the tests issue
218 <command>./x.py test --verbose --no-fail-fast | tee rustc-testlog</command>:
219 as with the build, that will use all available CPUs. This runs many suites
220 of tests (in an apparently random order), several will fail in BLFS:
221 compile-fail/issue-37131.rs require a thumbv6m-none-eabi compiler but the
222 BLFS build does not cater for
223 that, ui/issue-49851/compiler-builtins-error.rs and ui/issue-50993.rs (both
224 run twice) require a thumbv7em-none-eabihf compiler, and seven tests in
225 debuginfo-gdb will fail because gdb-8.1 changed the output format. If
226 <application>gdb</application> has not been installed, most of the gdb tests
227 will fail.
228 </para>
229
230 <para>
231 If you wish to look at the numbers for the results, you can find the total
232 number of tests which were considered by running:
233 </para>
234
235<screen><command>grep 'running .* tests' rustc-testlog | awk '{ sum += $2 } END { print sum }'</command></screen>
236
237 <para>
238 That should report 17101 tests. Similarly, the total tests which failed can
239 be found by running:
240 </para>
241
242<screen><command>grep '^test result:' rustc-testlog | awk '{ sum += $6 } END { print sum }'</command></screen>
243
244 <para>
245 And similarly for the tests which passed use $4, for those which were ignored
246 (i.e. skipped) use $8 (and $10 for 'measured', $12 for 'filtered out' but both
247 are probably zero). The breakdown does not match the overall total.
248 </para>
249
250 <para>
251 Still as your normal user, do a DESTDIR install:
252 </para>
253
254<screen><userinput>export LIBSSH2_SYS_USE_PKG_CONFIG=1 &amp;&amp;
255DESTDIR=${PWD}/install ./x.py install &amp;&amp;
256unset LIBSSH2_SYS_USE_PKG_CONFIG</userinput></screen>
257
258 <para>
259 Now, as the <systemitem class="username">root</systemitem> user
260 install the files from the DESTDIR:
261 </para>
262
263<screen role="root"><userinput>chown -R root:root install &amp;&amp;
264cp -a install/* /</userinput></screen>
265
266 </sect2>
267
268 <sect2 role="commands">
269 <title>Command Explanations</title>
270
271 <para>
272 <command>targets = "X86"</command>: this avoids building all the available
273 linux cross-compilers (Aarch64, MIPS, PowerPC, SystemZ, etc). Unfortunately,
274 rust insists on installing source files for these below
275 <filename class="directory">/usr/lib/rustlib/src</filename>.
276 </para>
277
278 <para>
279 <command>extended = true</command>: this installs Cargo alongside Rust.
280 </para>
281
282 <para>
283 <command>channel = "stable"</command>: this ensures only stable features
284 can be used, the default in <filename>config.toml</filename> is to use
285 development features, which is not appropriate for a released version.
286 </para>
287
288 <para>
289 <command>rpath = false</command>: by default, <command>rust</command> can
290 be run from where it was built, without being installed. That adds DT_RPATH
291 entries to all of the ELF files, which produces very messy output from
292 <command>ldd</command>, showing the libraries in the place they were built,
293 even if they have been deleted from there after the install.
294 </para>
295
296 <para>
297 <command>[target.x86_64-unknown-linux-gnu]</command>: the syntax of
298 <filename>config.toml</filename> requires an <literal>llvm-config</literal>
299 entry for each target for which system-llvm is to be used. Change the target
300 to <literal>[target.i686-unknown-linux-gnu]</literal> if you are building
301 on 32-bit x86. This whole section may be omitted if you wish to build
302 against the shipped llvm, or do not have clang, but the resulting build will
303 be larger and take longer.
304 </para>
305
306 <para>
307 <command>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi"</command>:
308 This adds a link to libffi to any RUSTFLAGS you may already be passing
309 to the build. On some systems, linking fails to include libffi unless
310 this is used. The reason why this is needed is not clear.
311 </para>
312
313 <para>
314 <command>--verbose</command>: this switch can sometimes provide more
315 information about a test which fails.
316 </para>
317
318 <para>
319 <command>--no-fail-fast</command>: this switch ensures that the testsuite
320 will not stop at the first error.
321 </para>
322
323 <para>
324 <command>export LIBSSH2_SYS_USE_PKG_CONFIG=1</command>: On some systems,
325 cairo fails to link during the install because it cannot find libssh2.
326 This seems to fix it, but again the reason why the problem occurs is not
327 understood.
328 </para>
329
330 <para>
331 <command>DESTDIR=${PWD}/install ./x.py install</command>: This effects a
332 DESTDIR-style install in the source tree,creating an <filename
333 class="directory">install</filename> directory. Note that DESTDIR installs
334 need an absolute path, passing 'install' will not work.
335 </para>
336
337 <para>
338 <command>chown -R root:root install</command>: the DESTDIR install
339 was run by a regular user, who owns the files. For security, change their
340 owner before doing a simple copy to install them.
341 </para>
342
343 </sect2>
344
345 <sect2 role="content">
346 <title>Contents</title>
347
348 <segmentedlist>
349 <segtitle>Installed Programs</segtitle>
350 <segtitle>Installed Libraries</segtitle>
351 <segtitle>Installed Directories</segtitle>
352
353 <seglistitem>
354 <seg>
355 cargo-clippy, cargo-fmt, cargo, clippy-driver, rls, rust-gdb, rust-lldb, rustc, rustdoc, rustfmt.
356 </seg>
357 <seg>
358 Many lib*&lt;16-byte-hash&gt;.so libraries.
359 </seg>
360 <seg>
361 ~/.cargo,
362 /usr/lib/rustlib,
363 /usr/share/doc/rustc-&rust-version;, and
364 /usr/share/zsh/site-functions/
365 </seg>
366 </seglistitem>
367 </segmentedlist>
368
369 <variablelist>
370 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
371 <?dbfo list-presentation="list"?>
372 <?dbhtml list-presentation="table"?>
373
374 <varlistentry id="cargo-clippy">
375 <term><command>cargo-clippy</command></term>
376 <listitem>
377 <para>
378 provides lint checks for a cargo package.
379 </para>
380 <indexterm zone="rust cargo-clippy">
381 <primary sortas="b-cargo-clippy">cargo-clippy</primary>
382 </indexterm>
383 </listitem>
384 </varlistentry>
385
386 <varlistentry id="cargo-fmt">
387 <term><command>cargo-fmt</command></term>
388 <listitem>
389 <para>
390 formats all bin and lib files of the current crate using
391 rustfmt.
392 </para>
393 <indexterm zone="rust cargo-fmt">
394 <primary sortas="b-cargo-fmt">cargo-fmt</primary>
395 </indexterm>
396 </listitem>
397 </varlistentry>
398
399 <varlistentry id="cargo">
400 <term><command>cargo</command></term>
401 <listitem>
402 <para>
403 is the Package Manager for Rust.
404 </para>
405 <indexterm zone="rust cargo">
406 <primary sortas="b-cargo">cargo</primary>
407 </indexterm>
408 </listitem>
409 </varlistentry>
410
411 <varlistentry id="clippy-driver">
412 <term><command>clippy-driver</command></term>
413 <listitem>
414 <para>
415 provides lint checks for Rust.
416 </para>
417 <indexterm zone="rust clippy-driver">
418 <primary sortas="b-clippy-driver">clippy-driver</primary>
419 </indexterm>
420 </listitem>
421 </varlistentry>
422
423 <varlistentry id="rls">
424 <term><command>rls</command></term>
425 <listitem>
426 <para>
427 is the Rust Language Server. This can run in the background to
428 provide IDEs, editors, and other tools with information about Rust
429 programs.
430 </para>
431 <indexterm zone="rust rls">
432 <primary sortas="b-rls">rls</primary>
433 </indexterm>
434 </listitem>
435 </varlistentry>
436
437 <varlistentry id="rust-gdb">
438 <term><command>rust-gdb</command></term>
439 <listitem>
440 <para>
441 is a wrapper script for gdb, pulling in Python
442 pretty-printing modules installed in <filename
443 class="directory">/usr/lib/rustlib/etc</filename>.
444 </para>
445 <indexterm zone="rust rust-gdb">
446 <primary sortas="b-rust-gdb">rust-gdb</primary>
447 </indexterm>
448 </listitem>
449 </varlistentry>
450
451 <varlistentry id="rust-lldb">
452 <term><command>rust-lldb</command></term>
453 <listitem>
454 <para>
455 is a wrapper script for LLDB (the LLVM debugger)
456 pulling in the Python pretty-printing modules.
457 </para>
458 <indexterm zone="rust rust-lldb">
459 <primary sortas="b-rust-lldb">rust=lldb</primary>
460 </indexterm>
461 </listitem>
462 </varlistentry>
463
464 <varlistentry id="rustc">
465 <term><command>rustc</command></term>
466 <listitem>
467 <para>
468 is the rust compiler.
469 </para>
470 <indexterm zone="rust rustc">
471 <primary sortas="b-rustc">rustc</primary>
472 </indexterm>
473 </listitem>
474 </varlistentry>
475
476 <varlistentry id="rustdoc">
477 <term><command>rustdoc</command></term>
478 <listitem>
479 <para>
480 generates documentation from rust source code.
481 </para>
482 <indexterm zone="rust rustdoc">
483 <primary sortas="b-rustdoc">rustdoc</primary>
484 </indexterm>
485 </listitem>
486 </varlistentry>
487
488 <varlistentry id="rustfmt">
489 <term><command>rustfmt</command></term>
490 <listitem>
491 <para>
492 formats rust code.
493 </para>
494 <indexterm zone="rust rustfmt">
495 <primary sortas="b-rustfmt">rustfmt</primary>
496 </indexterm>
497 </listitem>
498 </varlistentry>
499
500 <varlistentry id="libstd">
501 <term><filename class="libraryfile">libstd-&lt;16-byte-hash&gt;.so</filename></term>
502 <listitem>
503 <para>
504 is the Rust Standard Library, the foundation of portable Rust software.
505 </para>
506 <indexterm zone="rust libstd">
507 <primary sortas="c-libstd">libstd-&lt;16-byte-hash&gt;.so</primary>
508 </indexterm>
509 </listitem>
510 </varlistentry>
511 </variablelist>
512 </sect2>
513</sect1>
Note: See TracBrowser for help on using the repository browser.