source: general/prog/rust.xml@ a7b1bddc

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

Rustc-1.25.0.
NB this is now using a DESTDIR install, and the book does not delete that. Be aware of this if you are copying the commands into a script: if you rebuild with different settings, or later follow the instructions for a newer version, trying to create the existing directory will fail.

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

  • Property mode set to 100644
File size: 16.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 "d8d4d30c8d0b905f978bee3fdd618db5">
10 <!ENTITY rust-size "95 MB">
11 <!ENTITY rust-buildsize "5.1 GB (440 MB installed) including 379MB of ~/.cargo files for the user building this and 440MB of files in the DESTDIR (add 1.2GB if running the tests)">
12 <!ENTITY rust-time "33 SBU (add 17 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 Repeated builds of this package on the same machine show a wide range
59 of build times. Some of this might be due to variations in downloading
60 the required cargo files if they are not already present, but this does
61 not seem to adequately explain the variations.
62 </para>
63 <para>
64 Unusually, a DESTDIR method is being used to install this package. This
65 is because running the install as root not only downloads all of the
66 cargo files again (to <filename>/root/.cargo</filename>), it then spends
67 a very long time recompiling. Using a DESTDIR method saves 30 SBU on the
68 4-core machine where this was tested, at the cost of an extra 60MB of
69 disk space for the extra files.
70 </para>
71 </note>
72
73 &lfs82_checked;
74
75 <bridgehead renderas="sect3">Package Information</bridgehead>
76 <itemizedlist spacing="compact">
77 <listitem>
78 <para>
79 Download (HTTP): <ulink url="&rust-download-http;"/>
80 </para>
81 </listitem>
82 <listitem>
83 <para>
84 Download (FTP): <ulink url="&rust-download-ftp;"/>
85 </para>
86 </listitem>
87 <listitem>
88 <para>
89 Download MD5 sum: &rust-md5sum;
90 </para>
91 </listitem>
92 <listitem>
93 <para>
94 Download size: &rust-size;
95 </para>
96 </listitem>
97 <listitem>
98 <para>
99 Estimated disk space required: &rust-buildsize;
100 </para>
101 </listitem>
102 <listitem>
103 <para>
104 Estimated build time: &rust-time;
105 </para>
106 </listitem>
107 </itemizedlist>
108
109 <bridgehead renderas="sect3">Rust Dependencies</bridgehead>
110
111 <bridgehead renderas="sect4">Required</bridgehead>
112 <para role="required">
113 <xref linkend="curl"/>,
114 <xref linkend="cmake"/>,
115<!-- Although this appears to build with python3, there are sometimes strange
116 script errors in the compilation (i.e. it exits after the build, without
117 any obvious errors and with a good status. Also ,it ships with a configure
118 script which invokes python2.7 to create config.toml, and some of the files
119 in the package use python2.7. -->
120 <xref linkend="python2"/>
121 </para>
122
123 <bridgehead renderas="sect4">Recommended</bridgehead>
124 <para role="recommended">
125 <package>clang</package> from <xref linkend="llvm"/>
126 </para>
127
128 <bridgehead renderas="sect4">Optional</bridgehead>
129 <para role="optional">
130 <xref linkend="gdb"/> (used by debuginfo-gdb in the testsuite)
131 </para>
132
133 <para condition="html" role="usernotes">
134 User Notes: <ulink url="&blfs-wiki;/rust"/>
135 </para>
136 </sect2>
137
138 <sect2 role="installation">
139 <title>Installation of Rust</title>
140
141 <note>
142 <para>
143 This package is updated on a six-weekly release cycle. Because it is
144 such a large and slow package to build, and is at the moment only used
145 by two packages in this book, the BLFS editors take the view that it
146 should only be updated when that is necessary.
147 </para>
148 </note>
149
150 <para>
151 First create a suitable <filename>config.toml</filename> file
152 which will configure the build :
153 </para>
154
155<screen><userinput>cat &lt;&lt;EOF &gt; config.toml
156# see config.toml.example for more possible options
157[llvm]
158targets = "X86"
159
160# When using system llvm prefer shared libraries
161link-shared = true
162
163[build]
164# install cargo as well as rust
165extended = true
166
167[install]
168prefix = "/usr"
169docdir = "share/doc/rustc-&rust-version;"
170
171[rust]
172channel = "stable"
173rpath = false
174
175# get reasonably clean output from the test harness
176quiet-tests = true
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>./x.py build</userinput></screen>
196
197 <para>
198 The build will report it failed to compile <filename>miri</filename>
199 because of multiple potential crates for `log`, but that should be followed
200 by a message that the build completed successfully.
201 </para>
202
203 <caution>
204 <para>
205 On AMD Ryzen processors (family 17h), the non-optimized version of libstd
206 which is compiled at the start of the tests contains two opcodes which are
207 not implemented on this CPU family. These will be logged in the
208 <phrase revision="sysv">system log</phrase>
209 <phrase revision="systemd">systemd journal</phrase>
210 and will be followed a few minutes later by segmentation faults. Despite
211 that, the tests continue to run, apparently normally. But the system may
212 reboot before the tests have completed. The normal optimized libraries
213 run without this problem.
214 </para>
215 <para>
216 A mitigation is to install gdb
217 <!-- systemd apparently handles this with systemd-coredump -->
218 <phrase revision="sysv">and to run the tests with 'ulimit -C disabled'</phrase>
219 but this does not always prevent the system rebooting.
220 </para>
221 </caution>
222
223 <para>
224 To run the tests issue
225 <command>./x.py test --verbose --no-fail-fast &gt;../rustc-testlog</command>:
226 as with the build, that will use all available CPUs. This runs many suites
227 of tests (in an apparently random order), at least one will fail:
228 compile-fail/issue-37131.rs tries to
229 compile for the thumbv6m-none-eabi target but the BLFS build does not cater for
230 that, and many tests in debuginfo-gdb will fail if
231 <application>gdb</application> has not been installed. A few other tests might
232 fail.
233 </para>
234
235 <para>
236 If you wish to look at the numbers for the results, you can find the total
237 number of tests which were considered by running:
238 </para>
239
240<screen><command>grep 'running .* tests' ../rustc-testlog | awk '{ sum += $2 } END { print sum }'</command></screen>
241
242 <para>
243 That should report 13224 tests. Similarly, the total tests which failed can
244 be found by running:
245 </para>
246
247<screen><command>grep '^test result:' ../rustc-testlog | awk '{ sum += $6 } END { print sum }'</command></screen>
248
249 <para>
250 And similarly for the tests which passed use $4, for those which were ignored
251 (i.e. skipped) use $8 (and $10 for 'measured', $12 for 'filtered out' but both
252 are probably zero). The breakdown does not match the overall total.
253 </para>
254
255 <para>
256 Still as your normal user, do a DESTDIR install:
257 </para>
258
259<screen><userinput>mkdir -v /sources/RUST &amp;&amp;
260DESTDIR=/sources/RUST ./x.py install</userinput></screen>
261
262 <para>
263 Now, as the <systemitem class="username">root</systemitem> user
264 install the files from the DESTDIR:
265 </para>
266
267<screen role="root"><userinput>chown -R root:root /sources/RUST &amp;&amp;
268cp -a /sources/RUST/* /</userinput></screen>
269
270 </sect2>
271
272 <sect2 role="commands">
273 <title>Command Explanations</title>
274
275 <para>
276 <command>targets = "X86"</command>: this avoids building all the available
277 linux cross-compilers (Aarch64, MIPS, PowerPC, SystemZ, etc). Unfortunately,
278 rust insists on installing source files for these below
279 <filename class="directory">/usr/lib/rustlib/src</filename>.
280 </para>
281
282 <para>
283 <command>extended = true</command>: this installs Cargo alongside Rust.
284 </para>
285
286 <para>
287 <command>channel = "stable"</command>: this ensures only stable features
288 can be used, the default in <filename>config.toml</filename> is to use
289 development features, which is not appropriate for a released version.
290 </para>
291
292 <para>
293 <command>rpath = false</command>: by default, <command>rust</command> can
294 be run from where it was built, without being installed. That adds DT_RPATH
295 entries to all of the ELF files, which produces very messy output from
296 <command>ldd</command>, showing the libraries in the place they were built,
297 even if they have been deleted from there after the install.
298 </para>
299
300 <para>
301 <command>[target.x86_64-unknown-linux-gnu]</command>: the syntax of
302 <filename>config.toml</filename> requires an <literal>llvm-config</literal>
303 entry for each target for which system-llvm is to be used. Change the target
304 to <literal>[target.i686-unknown-linux-gnu]</literal> if you are building
305 on 32-bit x86. This whole section may be omitted if you wish to build
306 against the shipped llvm, or do not have clang, but the resulting build will
307 be larger and take a little longer.
308 </para>
309
310 <para>
311 <command>--verbose</command>: this switch can sometimes provide more
312 information about a test which fails.
313 </para>
314
315 <para>
316 <command>--no-fail-fast</command>: this switch ensures that the testsuite
317 will not stop at the first error.
318 </para>
319
320 <para>
321 <command>mkdir -v /sources/RUST</command>: this is not strictly necessary,
322 but it confirms that your regular user can write there, and that there is
323 not an existing directory of this name left over from a previous install.
324 By convention, BLFS builds in <filename class="directory">/sources</filename>
325 but you can change this to another location where you can write (and
326 similarly change the commands used by
327 <systemitem class="username">root</systemitem>). Note that DESTDIR installs
328 need an absolute path, passing e.g. ../RUST will not work.
329 </para>
330
331 <para>
332 <command>chown -R root:root /sources/RUST</command>: the DESTDIR install
333 was run by a regular user, who owns the files. For security, change their
334 owner before doing a simple copy to install them.
335 </para>
336
337 </sect2>
338
339 <sect2 role="content">
340 <title>Contents</title>
341
342 <segmentedlist>
343 <segtitle>Installed Programs</segtitle>
344 <segtitle>Installed Libraries</segtitle>
345 <segtitle>Installed Directories</segtitle>
346
347 <seglistitem>
348 <seg>
349 cargo-fmt, cargo, rls, rust-gdb, rust-lldb, rustc, rustdoc, rustfmt.
350 </seg>
351 <seg>
352 Many lib*&lt;16-byte-hash&gt;.so libraries.
353 </seg>
354 <seg>
355 ~/.cargo,
356 /usr/lib/rustlib,
357 /usr/share/doc/rustc-&rust-version;, and
358 /usr/share/zsh/site-functions/
359 </seg>
360 </seglistitem>
361 </segmentedlist>
362
363 <variablelist>
364 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
365 <?dbfo list-presentation="list"?>
366 <?dbhtml list-presentation="table"?>
367
368 <varlistentry id="cargo-fmt">
369 <term><command>cargo-fmt</command></term>
370 <listitem>
371 <para>
372 formats all bin and lib files of the current crate using
373 rustfmt.
374 </para>
375 <indexterm zone="rust cargo-fmt">
376 <primary sortas="b-cargo-fmt">cargo-fmt</primary>
377 </indexterm>
378 </listitem>
379 </varlistentry>
380
381 <varlistentry id="cargo">
382 <term><command>cargo</command></term>
383 <listitem>
384 <para>
385 is the Package Manager for Rust.
386 </para>
387 <indexterm zone="rust cargo">
388 <primary sortas="b-cargo">cargo</primary>
389 </indexterm>
390 </listitem>
391 </varlistentry>
392
393 <varlistentry id="rls">
394 <term><command>rls</command></term>
395 <listitem>
396 <para>
397 is the Rust Language Server. This can run in the background to
398 provide IDEs, editors, and other tools with information about Rust
399 programs.
400 </para>
401 <indexterm zone="rust rls">
402 <primary sortas="b-rls">rls</primary>
403 </indexterm>
404 </listitem>
405 </varlistentry>
406
407 <varlistentry id="rust-gdb">
408 <term><command>rust-gdb</command></term>
409 <listitem>
410 <para>
411 is a wrapper script for gdb, pulling in Python
412 pretty-printing modules installed in <filename
413 class="directory">/usr/lib/rustlib/etc</filename>.
414 </para>
415 <indexterm zone="rust rust-gdb">
416 <primary sortas="b-rust-gdb">rust-gdb</primary>
417 </indexterm>
418 </listitem>
419 </varlistentry>
420
421 <varlistentry id="rust-lldb">
422 <term><command>rust-lldb</command></term>
423 <listitem>
424 <para>
425 is a wrapper script for LLDB (the LLVM debugger)
426 pulling in the Python pretty-printing modules.
427 </para>
428 <indexterm zone="rust rust-lldb">
429 <primary sortas="b-rust-lldb">rust=lldb</primary>
430 </indexterm>
431 </listitem>
432 </varlistentry>
433
434 <varlistentry id="rustc">
435 <term><command>rustc</command></term>
436 <listitem>
437 <para>
438 is the rust compiler.
439 </para>
440 <indexterm zone="rust rustc">
441 <primary sortas="b-rustc">rustc</primary>
442 </indexterm>
443 </listitem>
444 </varlistentry>
445
446 <varlistentry id="rustdoc">
447 <term><command>rustdoc</command></term>
448 <listitem>
449 <para>
450 generates documentation from rust source code.
451 </para>
452 <indexterm zone="rust rustdoc">
453 <primary sortas="b-rustdoc">rustdoc</primary>
454 </indexterm>
455 </listitem>
456 </varlistentry>
457
458 <varlistentry id="rustfmt">
459 <term><command>rustfmt</command></term>
460 <listitem>
461 <para>
462 formats rust code.
463 </para>
464 <indexterm zone="rust rustfmt">
465 <primary sortas="b-rustfmt">rustfmt</primary>
466 </indexterm>
467 </listitem>
468 </varlistentry>
469
470 <varlistentry id="libstd">
471 <term><filename class="libraryfile">libstd-&lt;16-byte-hash&gt;.so</filename></term>
472 <listitem>
473 <para>
474 is the Rust Standard Library, the foundation of portable Rust software.
475 </para>
476 <indexterm zone="rust libstd">
477 <primary sortas="c-libstd">libstd-&lt;16-byte-hash&gt;.so</primary>
478 </indexterm>
479 </listitem>
480 </varlistentry>
481 </variablelist>
482 </sect2>
483</sect1>
Note: See TracBrowser for help on using the repository browser.