source: general/prog/rust.xml@ 539d7c54

10.0 10.1 11.0 8.3 8.4 9.0 9.1 basic bdubbs/svn elogind ken/refactor-virt lazarus perl-modules qt5new trunk xry111/git-date xry111/git-date-for-trunk xry111/git-date-test
Last change on this file since 539d7c54 was 539d7c54, checked in by Ken Moffat <ken@…>, 3 years ago

Add libssh2.

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

  • Property mode set to 100644
File size: 16.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 "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-style method is being used to install this package.
65 This 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 this 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 <xref linkend="libssh2"/> (required by the libgit crate during
126 <emphasis>some</emphasis> stable installs, but not during others),
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"/> (used by debuginfo-gdb in 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 used
148 by two 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# get reasonably clean output from the test harness
179quiet-tests = true
180
181# BLFS does not install the FileCheck executable from llvm,
182# so disable codegen tests
183codegen-tests = false
184
185[target.x86_64-unknown-linux-gnu]
186# delete this *section* if you are not using system llvm.
187# NB the output of llvm-config (i.e. help options) may be
188# dumped to the screen when config.toml is parsed.
189llvm-config = "/usr/bin/llvm-config"
190
191EOF</userinput></screen>
192
193 <para>
194 Now install <application>Rust</application> by running the following
195 commands:
196 </para>
197
198<screen><userinput>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi" &amp;&amp;
199./x.py build</userinput></screen>
200
201 <para>
202 The build will report it failed to compile <filename>miri</filename>
203 because of multiple potential crates for `log`, but that should be followed
204 by a message that the build completed successfully.
205 </para>
206
207 <caution>
208 <para>
209 On AMD Ryzen processors (family 17h), the non-optimized version of libstd
210 which is compiled at the start of the tests contains two opcodes which are
211 not implemented on this CPU family. These will be logged in the
212 <phrase revision="sysv">system log</phrase>
213 <phrase revision="systemd">systemd journal</phrase>
214 and will be followed a few minutes later by segmentation faults. Despite
215 that, the tests continue to run, apparently normally. But the system may
216 reboot before the tests have completed. The normal optimized libraries
217 run without this problem.
218 </para>
219 <para>
220 A mitigation is to install gdb
221 <!-- systemd apparently handles this with systemd-coredump -->
222 <phrase revision="sysv">and to run the tests with 'ulimit -C disabled'</phrase>
223 but this does not always prevent the system rebooting.
224 </para>
225 </caution>
226
227 <para>
228 To run the tests issue
229 <command>./x.py test --verbose --no-fail-fast &gt;../rustc-testlog</command>:
230 as with the build, that will use all available CPUs. This runs many suites
231 of tests (in an apparently random order), at least one will fail:
232 compile-fail/issue-37131.rs tries to
233 compile for the thumbv6m-none-eabi target but the BLFS build does not cater for
234 that, and many tests in debuginfo-gdb will fail if
235 <application>gdb</application> has not been installed. A few other tests might
236 fail.
237 </para>
238
239 <para>
240 If you wish to look at the numbers for the results, you can find the total
241 number of tests which were considered by running:
242 </para>
243
244<screen><command>grep 'running .* tests' ../rustc-testlog | awk '{ sum += $2 } END { print sum }'</command></screen>
245
246 <para>
247 That should report 13224 tests. Similarly, the total tests which failed can
248 be found by running:
249 </para>
250
251<screen><command>grep '^test result:' ../rustc-testlog | awk '{ sum += $6 } END { print sum }'</command></screen>
252
253 <para>
254 And similarly for the tests which passed use $4, for those which were ignored
255 (i.e. skipped) use $8 (and $10 for 'measured', $12 for 'filtered out' but both
256 are probably zero). The breakdown does not match the overall total.
257 </para>
258
259 <para>
260 Still as your normal user, do a DESTDIR install:
261 </para>
262
263<screen><userinput>DESTDIR=${PWD}/install ./x.py install</userinput></screen>
264
265 <para>
266 Now, as the <systemitem class="username">root</systemitem> user
267 install the files from the DESTDIR:
268 </para>
269
270<screen role="root"><userinput>chown -R root:root install &amp;&amp;
271cp -a install/* /</userinput></screen>
272
273 </sect2>
274
275 <sect2 role="commands">
276 <title>Command Explanations</title>
277
278 <para>
279 <command>targets = "X86"</command>: this avoids building all the available
280 linux cross-compilers (Aarch64, MIPS, PowerPC, SystemZ, etc). Unfortunately,
281 rust insists on installing source files for these below
282 <filename class="directory">/usr/lib/rustlib/src</filename>.
283 </para>
284
285 <para>
286 <command>extended = true</command>: this installs Cargo alongside Rust.
287 </para>
288
289 <para>
290 <command>channel = "stable"</command>: this ensures only stable features
291 can be used, the default in <filename>config.toml</filename> is to use
292 development features, which is not appropriate for a released version.
293 </para>
294
295 <para>
296 <command>rpath = false</command>: by default, <command>rust</command> can
297 be run from where it was built, without being installed. That adds DT_RPATH
298 entries to all of the ELF files, which produces very messy output from
299 <command>ldd</command>, showing the libraries in the place they were built,
300 even if they have been deleted from there after the install.
301 </para>
302
303 <para>
304 <command>[target.x86_64-unknown-linux-gnu]</command>: the syntax of
305 <filename>config.toml</filename> requires an <literal>llvm-config</literal>
306 entry for each target for which system-llvm is to be used. Change the target
307 to <literal>[target.i686-unknown-linux-gnu]</literal> if you are building
308 on 32-bit x86. This whole section may be omitted if you wish to build
309 against the shipped llvm, or do not have clang, but the resulting build will
310 be larger and take a little longer.
311 </para>
312
313 <para>
314 <command>export RUSTFLAGS="$RUSTFLAGS -C link-args=-lffi"</command>:
315 This adds a link to libffi to any RUSTFLAGS you may already be passing
316 to the build. On some systems, linking fails to include libffi unless
317 this is used. The reason why this is needed is not clear.
318 </para>
319
320 <para>
321 <command>--verbose</command>: this switch can sometimes provide more
322 information about a test which fails.
323 </para>
324
325 <para>
326 <command>--no-fail-fast</command>: this switch ensures that the testsuite
327 will not stop at the first error.
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-fmt, cargo, 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-fmt">
375 <term><command>cargo-fmt</command></term>
376 <listitem>
377 <para>
378 formats all bin and lib files of the current crate using
379 rustfmt.
380 </para>
381 <indexterm zone="rust cargo-fmt">
382 <primary sortas="b-cargo-fmt">cargo-fmt</primary>
383 </indexterm>
384 </listitem>
385 </varlistentry>
386
387 <varlistentry id="cargo">
388 <term><command>cargo</command></term>
389 <listitem>
390 <para>
391 is the Package Manager for Rust.
392 </para>
393 <indexterm zone="rust cargo">
394 <primary sortas="b-cargo">cargo</primary>
395 </indexterm>
396 </listitem>
397 </varlistentry>
398
399 <varlistentry id="rls">
400 <term><command>rls</command></term>
401 <listitem>
402 <para>
403 is the Rust Language Server. This can run in the background to
404 provide IDEs, editors, and other tools with information about Rust
405 programs.
406 </para>
407 <indexterm zone="rust rls">
408 <primary sortas="b-rls">rls</primary>
409 </indexterm>
410 </listitem>
411 </varlistentry>
412
413 <varlistentry id="rust-gdb">
414 <term><command>rust-gdb</command></term>
415 <listitem>
416 <para>
417 is a wrapper script for gdb, pulling in Python
418 pretty-printing modules installed in <filename
419 class="directory">/usr/lib/rustlib/etc</filename>.
420 </para>
421 <indexterm zone="rust rust-gdb">
422 <primary sortas="b-rust-gdb">rust-gdb</primary>
423 </indexterm>
424 </listitem>
425 </varlistentry>
426
427 <varlistentry id="rust-lldb">
428 <term><command>rust-lldb</command></term>
429 <listitem>
430 <para>
431 is a wrapper script for LLDB (the LLVM debugger)
432 pulling in the Python pretty-printing modules.
433 </para>
434 <indexterm zone="rust rust-lldb">
435 <primary sortas="b-rust-lldb">rust=lldb</primary>
436 </indexterm>
437 </listitem>
438 </varlistentry>
439
440 <varlistentry id="rustc">
441 <term><command>rustc</command></term>
442 <listitem>
443 <para>
444 is the rust compiler.
445 </para>
446 <indexterm zone="rust rustc">
447 <primary sortas="b-rustc">rustc</primary>
448 </indexterm>
449 </listitem>
450 </varlistentry>
451
452 <varlistentry id="rustdoc">
453 <term><command>rustdoc</command></term>
454 <listitem>
455 <para>
456 generates documentation from rust source code.
457 </para>
458 <indexterm zone="rust rustdoc">
459 <primary sortas="b-rustdoc">rustdoc</primary>
460 </indexterm>
461 </listitem>
462 </varlistentry>
463
464 <varlistentry id="rustfmt">
465 <term><command>rustfmt</command></term>
466 <listitem>
467 <para>
468 formats rust code.
469 </para>
470 <indexterm zone="rust rustfmt">
471 <primary sortas="b-rustfmt">rustfmt</primary>
472 </indexterm>
473 </listitem>
474 </varlistentry>
475
476 <varlistentry id="libstd">
477 <term><filename class="libraryfile">libstd-&lt;16-byte-hash&gt;.so</filename></term>
478 <listitem>
479 <para>
480 is the Rust Standard Library, the foundation of portable Rust software.
481 </para>
482 <indexterm zone="rust libstd">
483 <primary sortas="c-libstd">libstd-&lt;16-byte-hash&gt;.so</primary>
484 </indexterm>
485 </listitem>
486 </varlistentry>
487 </variablelist>
488 </sect2>
489</sect1>
Note: See TracBrowser for help on using the repository browser.