source: general/prog/rust.xml@ 88f20bb

perl-modules
Last change on this file since 88f20bb was 88f20bb, checked in by Ken Moffat <ken@…>, 4 years ago

Perl modules branch: merge revisions 20505 to 20531 from trunk.

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/branches/perl-modules@20532 af4574ff-66df-0310-9fd7-8a98e5e911e0

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