source: general/prog/rust.xml@ 67687b75

10.0 10.1 11.0 11.1 11.2 8.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 67687b75 was 67687b75, checked in by Ken Moffat <ken@…>, 5 years ago

Rustc - note that three more tests fail with glibc-2.27. Possibly this will be fixed in rustc-1.25.0, https://github.com/rust-lang/rust/issues/47863.

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

  • Property mode set to 100644
File size: 12.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 "7272ddba14f512e6d2612ef60460bed8">
10 <!ENTITY rust-size "53 MB">
11 <!ENTITY rust-buildsize "4.1 GB (437 MB installed), (add 1.2GB for tests) including 226MB of ~/.cargo files for both the builder and root (from the install)">
12 <!ENTITY rust-time "48 SBU (add 12 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 several cargo files (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. Also, both the builder
62 and the user running the install will need to download the cargo crates
63 if they are not already present in <filename>~/.cargo</filename>.
64 </para>
65 <para>
66 If you use a DESTDIR method to install, you will only need to download
67 the crates once, for the build, saving about one-third of the build and
68 install time (but using extra space for the install). Similarly if you
69 were to build as root, or if your user is allowed to run <command>sudo
70 ./x.py install</command> - but those methods are dangerous.
71 </para>
72 </note>
73
74 &lfs82_checked;
75
76 <bridgehead renderas="sect3">Package Information</bridgehead>
77 <itemizedlist spacing="compact">
78 <listitem>
79 <para>
80 Download (HTTP): <ulink url="&rust-download-http;"/>
81 </para>
82 </listitem>
83 <listitem>
84 <para>
85 Download (FTP): <ulink url="&rust-download-ftp;"/>
86 </para>
87 </listitem>
88 <listitem>
89 <para>
90 Download MD5 sum: &rust-md5sum;
91 </para>
92 </listitem>
93 <listitem>
94 <para>
95 Download size: &rust-size;
96 </para>
97 </listitem>
98 <listitem>
99 <para>
100 Estimated disk space required: &rust-buildsize;
101 </para>
102 </listitem>
103 <listitem>
104 <para>
105 Estimated build time: &rust-time;
106 </para>
107 </listitem>
108 </itemizedlist>
109
110 <bridgehead renderas="sect3">Rust Dependencies</bridgehead>
111
112 <bridgehead renderas="sect4">Required</bridgehead>
113 <para role="required">
114 <xref linkend="curl"/>,
115 <xref linkend="cmake"/>,
116<!-- if changing this to use python3, also add python2 as a required
117 dependency for firefox, because at the moment it picks that up from here -->
118 <xref linkend="python2"/>
119 </para>
120
121 <bridgehead renderas="sect4">Optional</bridgehead>
122 <para role="optional">
123 <xref linkend="gdb"/> (used by debuginfo-gdb in the testsuite)
124 </para>
125
126 <para condition="html" role="usernotes">
127 User Notes: <ulink url="&blfs-wiki;/rust"/>
128 </para>
129 </sect2>
130
131 <sect2 role="installation">
132 <title>Installation of Rust</title>
133
134 <note>
135 <para>
136 This package is updated on a six-weekly release cycle. Because it is
137 such a large and slow package to build, and is at the moment only used
138 by two packages in this book, the BLFS editors take the view that it
139 should only be updated when that is necessary.
140 </para>
141 </note>
142
143 <para>
144 First create a suitable <filename>config.toml</filename> file
145 which will configure the build :
146 </para>
147
148<screen><userinput>cat &lt;&lt;EOF &gt; config.toml
149# see config.toml.example for more possible options
150[llvm]
151targets = "X86"
152
153[build]
154# install cargo as well as rust
155extended = true
156
157[install]
158prefix = "/usr"
159docdir = "share/doc/rustc-&rust-version;"
160
161[rust]
162channel = "stable"
163rpath = false
164EOF</userinput></screen>
165
166 <para>
167 Now install <application>Rust</application> by running the following
168 commands:
169 </para>
170
171<screen><userinput>./x.py build</userinput></screen>
172
173 <para>
174 To run the tests issue
175 <command>./x.py test --verbose --no-fail-fast &gt;../rustc-testlog</command>:
176 as with the build, that will use all available CPUs. This runs many suites
177 of tests (in an apparently random order), three may fail:
178 compile-fail/issue-37131.rs and run-make/target-without-atomics both try to
179 compile for the thumbv6m-none-eabi target, but the BLFS build does not cater for
180 that, and all 105 tests in debuginfo-gdb will fail if
181 <application>gdb</application> has not been installed. Several other tests in
182 run-make can also fail. With <application>glibc-2.27</application> the stack
183 guard page has been moved to just beyond the stack, instead of within it. That
184 causes three run-pass tests (out-of-stack.rs, stack-probes-lto.rs,
185 stack-probes.rs) to fail.
186 </para>
187
188 <para>
189 If you wish to look at the numbers for the results, you can find the total
190 number of tests which were considered by running:
191 </para>
192
193<screen><command>grep 'running .* tests' ../rustc-testlog | awk '{ sum += $2 } END { print sum }'</command></screen>
194
195 <para>
196 That should report 14854 tests. Similarly, the total tests which failed can
197 be found by running:
198 </para>
199
200<screen><command>grep '^test result:' ../rustc-testlog | awk '{ sum += $6 } END { print sum }'</command></screen>
201
202 <para>
203 And similarly for the tests which passed use $4, for those which were ignored
204 (i.e. skipped) use $8 (and $10 for 'measured', $12 for 'filtered out' but both
205 are probably zero). The breakdown does not match the overall total.
206 </para>
207
208 <para>
209 Now, as the <systemitem class="username">root</systemitem> user:
210 </para>
211
212<screen role="root"><userinput>./x.py install</userinput></screen>
213 </sect2>
214
215 <sect2 role="commands">
216 <title>Command Explanations</title>
217
218 <para>
219 <command>targets = "X86"</command>: this avoids building all the available
220 linux cross-compilers (Aarch64, MIPS, PowerPC, SystemZ, etc).
221 </para>
222
223 <para>
224 <command>extended = true</command>: this installs Cargo alongside Rust.
225 </para>
226
227 <para>
228 <command>channel = "stable"</command>: this ensures only stable features
229 can be used, the default in <filename>config.toml</filename> is to use
230 development features, which is not appropriate for a released version.
231 </para>
232
233 <para>
234 <command>rpath = false</command>: by default, <command>rust</command> can
235 be run from where it was built, without being installed. That adds DT_RPATH
236 entries to all of the ELF files, which produces very messy output from
237 <command>ldd</command>, showing the libraries in the place they were built,
238 even if they have been deleted from there after the install.
239 </para>
240
241 <para>
242 <command>--verbose</command>: this switch can sometimes provide more
243 information about a test which fails.
244 </para>
245
246 <para>
247 <command>--no-fail-fast</command>: this switch ensures that the testsuite
248 will not stop at the first error.
249 </para>
250
251 <para>
252 <option>PYTHON=/usr/bin/python3 ... tee buildlog</option>: Because rust
253 can use <application>Python3</application> which was installed in LFS,
254 this command tells it to use that instead of the deprecated
255 <application>Python2</application>. For the moment this should be regarded
256 as experimental and problems may be encountered. Because
257 <application>rust</application> will use all CPUs, if an error happened the
258 message may have scrolled out of the terminal's buffer. Logging makes it
259 possible to find out what was reported.
260 </para>
261
262 </sect2>
263
264 <sect2 role="content">
265 <title>Contents</title>
266
267 <segmentedlist>
268 <segtitle>Installed Programs</segtitle>
269 <segtitle>Installed Libraries</segtitle>
270 <segtitle>Installed Directories</segtitle>
271
272 <seglistitem>
273 <seg>
274 cargo, rls, rust-gdb, rust-lldb, rustc, rustdoc.
275 </seg>
276 <seg>
277 Many lib*&lt;16-byte-hash&gt;.so libraries.
278 </seg>
279 <seg>
280 ~/.cargo,
281 /usr/lib/rustlib,
282 /usr/share/doc/rustc-&rust-version;, and
283 /usr/share/zsh/site-functions/
284 </seg>
285 </seglistitem>
286 </segmentedlist>
287
288 <variablelist>
289 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
290 <?dbfo list-presentation="list"?>
291 <?dbhtml list-presentation="table"?>
292
293 <varlistentry id="cargo">
294 <term><command>cargo</command></term>
295 <listitem>
296 <para>
297 is the Package Manager for Rust.
298 </para>
299 <indexterm zone="rust cargo">
300 <primary sortas="b-cargo">cargo</primary>
301 </indexterm>
302 </listitem>
303 </varlistentry>
304
305 <varlistentry id="rls">
306 <term><command>rls</command></term>
307 <listitem>
308 <para>
309 is the Rust Language Server. This can run in the background to
310 provide IDEs, editors, and other tools with information about Rust
311 programs.
312 </para>
313 <indexterm zone="rust rls">
314 <primary sortas="b-rls">rls</primary>
315 </indexterm>
316 </listitem>
317 </varlistentry>
318
319 <varlistentry id="rust-gdb">
320 <term><command>rust-gdb</command></term>
321 <listitem>
322 <para>
323 is a Python wrapper script for gdb.
324 </para>
325 <indexterm zone="rust rust-gdb">
326 <primary sortas="b-rust-gdb">rust-gdb</primary>
327 </indexterm>
328 </listitem>
329 </varlistentry>
330
331 <varlistentry id="rust-lldb">
332 <term><command>rust-lldb</command></term>
333 <listitem>
334 <para>
335 is a Python wrapper script for LLDB (the LLVM debugger).
336 </para>
337 <indexterm zone="rust rust-lldb">
338 <primary sortas="b-rust-lldb">rust=lldb</primary>
339 </indexterm>
340 </listitem>
341 </varlistentry>
342
343 <varlistentry id="rustc">
344 <term><command>rustc</command></term>
345 <listitem>
346 <para>
347 is the rust compiler.
348 </para>
349 <indexterm zone="rust rustc">
350 <primary sortas="b-rustc">rustc</primary>
351 </indexterm>
352 </listitem>
353 </varlistentry>
354
355 <varlistentry id="rustdoc">
356 <term><command>rustdoc</command></term>
357 <listitem>
358 <para>
359 generates documentation from rust source code.
360 </para>
361 <indexterm zone="rust rustdoc">
362 <primary sortas="b-rustdoc">rustdoc</primary>
363 </indexterm>
364 </listitem>
365 </varlistentry>
366
367 <varlistentry id="libstd">
368 <term><filename class="libraryfile">libstd-&lt;16-byte-hash&gt;.so</filename></term>
369 <listitem>
370 <para>
371 is the Rust Standard Library, the foundation of portable Rust software.
372 </para>
373 <indexterm zone="rust libstd">
374 <primary sortas="c-libstd">libstd-&lt;16-byte-hash&gt;.so</primary>
375 </indexterm>
376 </listitem>
377 </varlistentry>
378 </variablelist>
379 </sect2>
380</sect1>
Note: See TracBrowser for help on using the repository browser.