source: general/genlib/spidermonkey.xml

trunk
Last change on this file was e1092747, checked in by Xi Ruoyao <xry111@…>, 3 weeks ago

mozilla: Disable Rust SIMD

It won't work with rustc >= 1.78.0 :(. We need to wait for Mozilla to
port the SIMD code to use std::simd and Rust team to stablize std::simd.
  • Property mode set to 100644
File size: 15.7 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
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 spidermonkey-download-http "&mozilla-http;/firefox/releases/&spidermonkey-version;esr/source/firefox-&spidermonkey-version;esr.source.tar.xz">
8 <!ENTITY spidermonkey-download-ftp " ">
9 <!ENTITY spidermonkey-md5sum "150ac3fe6200f01879148ef32c5dd16f">
10 <!ENTITY spidermonkey-size "484 MB">
11 <!ENTITY spidermonkey-buildsize "3.6 GB (40 MB installed after removing 36MB static lib; add 34 MB for the main tests and 37 MB for the jit tests)">
12 <!ENTITY spidermonkey-time "1.9 SBU (with parallelism=4; add 1.1 SBU for the main tests and 3.7 SBU for the jit tests)">
13]>
14
15<sect1 id="spidermonkey" xreflabel="SpiderMonkey from Firefox-&spidermonkey-version;">
16 <?dbhtml filename="spidermonkey.html"?>
17
18
19 <title>SpiderMonkey from firefox-&spidermonkey-version;</title>
20
21 <indexterm zone="spidermonkey">
22 <primary sortas="a-spidermonkey">SpiderMonkey</primary>
23 </indexterm>
24
25 <sect2 role="package">
26 <title>Introduction to SpiderMonkey</title>
27
28 <para>
29 <application>SpiderMonkey</application> is Mozilla's JavaScript and
30 WebAssembly Engine, written in C++ and Rust.
31 In BLFS, the source code of SpiderMonkey is taken from Firefox.
32 </para>
33
34 <!-- To editors: make sure polkit works with mozjs when
35 tagging SpiderMonkey or upgrading it to a new major version. -->
36 &lfs121_checked;
37
38 <bridgehead renderas="sect3">Package Information</bridgehead>
39 <itemizedlist spacing="compact">
40 <listitem>
41 <para>
42 Download (HTTP): <ulink url="&spidermonkey-download-http;"/>
43 </para>
44 </listitem>
45 <listitem>
46 <para>
47 Download (FTP): <ulink url="&spidermonkey-download-ftp;"/>
48 </para>
49 </listitem>
50 <listitem>
51 <para>
52 Download MD5 sum: &spidermonkey-md5sum;
53 </para>
54 </listitem>
55 <listitem>
56 <para>
57 Download size: &spidermonkey-size;
58 </para>
59 </listitem>
60 <listitem>
61 <para>
62 Estimated disk space required: &spidermonkey-buildsize;
63 </para>
64 </listitem>
65 <listitem>
66 <para>
67 Estimated build time: &spidermonkey-time;
68 </para>
69 </listitem>
70 </itemizedlist>
71<!--
72 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
73 <itemizedlist spacing="compact">
74 <listitem>
75 <para>
76 Required patch:
77 <ulink url="&patch-root;/js-&JS91-version;-python_3_10-1.patch"/>
78 </para>
79 </listitem>
80 </itemizedlist>
81-->
82 <bridgehead renderas="sect3">SpiderMonkey Dependencies</bridgehead>
83
84 <bridgehead renderas="sect4">Required</bridgehead>
85 <para role="required">
86 <xref linkend="icu"/>,
87 <xref linkend="rust"/>, and
88 <!--<xref linkend="six"/>, and-->
89 <xref linkend="which"/>
90 </para>
91
92 <bridgehead renderas="sect4">Recommended</bridgehead>
93 <para role="recommended">
94 <!-- If clang is installed, it will be used instead of gcc.
95 gcc does not work for 32-bit system w/o -msse2 -mfpmath=sse:
96 https://bugzilla.mozilla.org/show_bug.cgi?id=1729459 -->
97 <xref linkend="llvm"/> (with <application>Clang</application>,
98 required for 32-bit systems without SSE2 capabilities)
99 </para>
100
101 <important>
102 <para>
103 If you are building this package on a 32-bit system, and Clang
104 is not installed or you're overriding the default compiler choice
105 with the environment variable <envar>CXX</envar>, please read the
106 Command Explanations section first.
107 </para>
108 </important>
109
110 <!-- It seems nasm is only used for aarch64-win64. -->
111 <!--bridgehead renderas="sect4">Optional</bridgehead>
112 <para role="optional">
113 <xref linkend="nasm"/>
114 </para-->
115
116 </sect2>
117
118 <sect2 role="installation">
119 <title>Installation of SpiderMonkey</title>
120
121 <note>
122 <para>
123 Unlike most other packages in BLFS, the instructions below require
124 you to untar
125 <filename>firefox-&spidermonkey-version;esr.tar.xz</filename> and
126 change into the <filename>firefox-&spidermonkey-version;</filename>
127 folder.
128 </para>
129
130 <para>
131 Extracting the tarball
132 will reset the permissions of the current directory to 0755 if you
133 have permission to do that. If you do this in a directory where
134 the sticky bit is set, such
135 as <filename class="directory">/tmp</filename> it will end with error
136 messages:
137 </para>
138
139<literallayout>tar: .: Cannot utime: Operation not permitted
140tar: .: Cannot change mode to rwxr-xr-t: Operation not permitted
141tar: Exiting with failure status due to previous errors
142</literallayout>
143
144 <para>
145 This does finish with non-zero status, but it does
146 <emphasis>NOT</emphasis> mean there is a real problem.
147 Do not untar as the <systemitem class="username">root</systemitem> user
148 in a directory where the sticky bit is set - that will unset it.
149 </para>
150
151 </note>
152<!--
153 <para>
154 The building system ships several internal copies of the Python 3
155 module <filename>six.py</filename>. The shipped copies are too old
156 to work well with Python 3.12 or later. Replace them with the
157 symlinks to <xref linkend='six'/> already installed on the system:
158 </para>
159
160<screen><userinput>for i in $(find -name six.py); do
161 ln -sfv /usr/lib/python&python3-majorver;/site-packages/six.py $i;
162done</userinput></screen>
163-->
164 <para>
165 Install <application>SpiderMonkey</application> by running the following
166 commands:
167 </para>
168
169 <note>
170 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
171 href="../../xincludes/mozshm.xml"/>
172 <para>
173 Compiling the C++ code respects $MAKEFLAGS and defaults to 'j1',
174 the rust code will use all processors.
175 </para>
176 </note>
177
178<screen><userinput>mkdir obj &amp;&amp;
179cd obj &amp;&amp;
180
181../js/src/configure --prefix=/usr \
182 --disable-debug-symbols \
183 --disable-jemalloc \
184 --enable-readline \
185 --with-intl-api \
186 --with-system-icu \
187 --with-system-zlib &amp;&amp;
188make</userinput></screen>
189
190 <para>
191 To run the SpiderMonkey test suite, issue:
192 <command>make -C js/src check-jstests
193 JSTESTS_EXTRA_ARGS="--timeout 300 --wpt=disabled"</command>.
194 It's recommended to redirect the output into a log.
195 <!-- recheck when ICU gets upgraded -->
196 Because we are building with system ICU, 39 tests
197 (out of a total of more than 50,000) are known to fail.
198 The test suite is executed with all CPU cores available: even in a
199 cgroup with less cores assigned, it still attempts to spawn as many
200 testing jobs as the number of <emphasis>all</emphasis> cores in the
201 system; fortunately the kernel still won't run these jobs on cores
202 not assigned to the cgroup so the CPU usage is still controlled.
203 </para>
204 <para>
205 To run the JIT test suite, issue: <command>make -C js/src
206 check-jit-test JITTEST_EXTRA_ARGS="--timeout 300"</command>.
207 Like the SpiderMonkey test suite, the number of test jobs is same as
208 the number of all CPU cores in the system even if a cgroup is used. To
209 make things worse, there are six tests each of them will use 3 GB
210 of system memory, so the peak memory usage may be up to 18 GB if the
211 number of cores is six or more. Running the JIT test suite without
212 enough memory may invoke the kernel OOM killer and cause stability
213 issues. If you don't have enough system memory available, append
214 <option>-jN</option> after <option>--timeout 300</option> with N
215 replaced by the number of parallel test jobs you want to start. For
216 example, if you have 16 GB system memory available and 8 CPU cores,
217 issue <command>make -C js/src check-jit-test
218 JITTEST_EXTRA_ARGS="--timeout=300 -j5"</command> to run the test with
219 5 parallel jobs so the memory usage won't exceed 15 GB.
220 <!-- TL;DR: DO NOT REMOVE MEMORY USAGE NOTE W/O MY CONFIRMATION!
221
222 "six tests": bug1782468-ptrdiff-veclen.js, it's ran with 6
223 different configurations.
224
225 "may": this is stochasitic (like all parallelization issue),
226 don't remove the note about memory usage simply because "I cannot
227 reproduce it".
228
229 "peak": the time period using so much memory is very short, so
230 don't just watch the output of "top" or "free" with eyesight.
231 Run the test in a cgroup and read the "memory.peak" psuedo file
232 for a proper measurement.
233
234 Q: Why not just document some test failures?
235 A: This *really* can cause stability issue because the kernel
236 may OOM kill another process if the test is not ran in a
237 cgroup with memory.max set. Even if running it in a cgroup,
238 the kernel may still OOM kill the "main" process controlling
239 the test process instead of a single test job, causing a
240 incomplete test.
241
242 - xry111
243 -->
244 </para>
245
246 <caution>
247 <para>
248 An issue in the installation process causes any running program which
249 links to SpiderMonkey shared library (for example, GNOME Shell) to
250 crash if SpiderMonkey is reinstalled, or upgraded or downgraded
251 without a change of the major version number
252 (&spidermonkey-major; in &spidermonkey-version;). To work around
253 this issue, remove the old version of the SpiderMonkey shared
254 library before installation:
255 </para>
256
257<screen role="root"><userinput>rm -fv /usr/lib/libmozjs-&spidermonkey-major;.so</userinput></screen>
258 </caution>
259
260 <para>
261 Now, as the <systemitem class="username">root</systemitem> user:
262 </para>
263
264<screen role="root"><userinput>make install &amp;&amp;
265rm -v /usr/lib/libjs_static.ajs &amp;&amp;
266sed -i '/@NSPR_CFLAGS@/d' /usr/bin/js&spidermonkey-major;-config</userinput></screen>
267
268 </sect2>
269
270 <sect2 role="commands">
271 <title>Command Explanations</title>
272
273 <para>
274 <parameter>--disable-debug-symbols</parameter>: Don't generate debug
275 symbols since they are very large and most users won't need it. Remove
276 it if you want to debug SpiderMonkey.
277 </para>
278
279 <para>
280 <parameter>--disable-jemalloc</parameter>: This switch disables the
281 internal memory allocator used in SpiderMonkey. jemalloc is only
282 intended for the Firefox browser environment. For other applications
283 using SpiderMonkey, the application may crash as items allocated in
284 the jemalloc allocator are freed on the system (glibc) allocator.
285 </para>
286
287 <para>
288 <parameter>--enable-readline</parameter>: This switch enables Readline
289 support in the SpiderMonkey command line interface.
290 </para>
291 <!--
292 <para>
293 <parameter>- -enable-rust-simd</parameter>: This switch enables SIMD
294 optimization in the shipped encoding_rs crate.
295 </para>
296 -->
297 <para>
298 <parameter>--with-intl-api</parameter>: This enables the
299 internationalization functions required by
300 <application>Gjs</application>.
301 </para>
302
303 <para>
304 <parameter>--with-system-*</parameter>: These parameters allow the build system
305 to use system versions of the above libraries. These are required for
306 stability.
307 </para>
308
309 <para>
310 <command>rm -v /usr/lib/libjs_static.ajs</command>: Remove a large
311 static library which is not used by any BLFS package.
312 </para>
313
314 <para>
315 <command>sed -i '/@NSPR_CFLAGS@/d'
316 /usr/bin/js&spidermonkey-major;-config</command>:
317 Prevent <command>js&spidermonkey-major;-config</command> from using
318 buggy CFLAGS.
319 </para>
320
321 <para>
322 <option><envar>CC=gcc CXX=g++</envar></option>: BLFS used to
323 prefer to use gcc and g++ instead of upstream's defaults of the
324 <application>clang</application> programs. With the release of
325 gcc-12 the build takes longer with gcc and g++, primarily because
326 of extra warnings, and is bigger. Pass these environment variables
327 to the configure script if you wish to continue to use gcc, g++
328 (by exporting them and unset them after the installation, or simply
329 prepending them before the
330 <command>../js/src/configure</command> command). If you are
331 building on a 32-bit system, also see below.
332 </para>
333
334 <para>
335 <option><envar>CXXFLAGS="-msse2 -mfpmath=sse"</envar></option>:
336 Use SSE2 instead of 387 for double-precision floating-point
337 operations. It's needed by GCC to satisfy the expectations of
338 upstream (Mozilla) developers with floating-point arithmetic.
339 Use it if you are building this package on a 32-bit system with
340 GCC (if Clang is not installed or GCC is explicitly specified).
341 Note that this will cause SpiderMonkey to crash on a processor without
342 SSE2 capability. If you are running the system on such an old
343 processor, Clang is strictly needed. This setting is not needed on
344 64-bit systems because all 64-bit x86 processors support SSE2 and the
345 64-bit compilers (both Clang and GCC) use SSE2 by default.
346 </para>
347 </sect2>
348
349 <sect2 role="content">
350 <title>Contents</title>
351
352 <segmentedlist>
353 <segtitle>Installed Programs</segtitle>
354 <segtitle>Installed Libraries</segtitle>
355 <segtitle>Installed Directories</segtitle>
356
357 <seglistitem>
358 <seg>
359 js&spidermonkey-major; and js&spidermonkey-major;-config
360 </seg>
361 <seg>
362 libmozjs-&spidermonkey-major;.so
363 </seg>
364 <seg>
365 /usr/include/mozjs-&spidermonkey-major;
366 </seg>
367 </seglistitem>
368 </segmentedlist>
369
370 <variablelist>
371 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
372 <?dbfo list-presentation="list"?>
373 <?dbhtml list-presentation="table"?>
374
375 <varlistentry id="js&spidermonkey-major;">
376 <term><command>js&spidermonkey-major;</command></term>
377 <listitem>
378 <para>
379 provides a command line interface to the
380 <application>JavaScript</application> engine
381 </para>
382 <indexterm zone="spidermonkey js&spidermonkey-major;">
383 <primary sortas="b-js&spidermonkey-major;">
384 js&spidermonkey-major;
385 </primary>
386 </indexterm>
387 </listitem>
388 </varlistentry>
389
390 <varlistentry id="js&spidermonkey-major;-config">
391 <term><command>js&spidermonkey-major;-config</command></term>
392 <listitem>
393 <para>
394 is used to find the SpiderMonkey compiler and linker flags
395 </para>
396 <indexterm zone="spidermonkey js&spidermonkey-major;-config">
397 <primary sortas="b-js&spidermonkey-major;-config">i
398 js&spidermonkey-major;-config
399 </primary>
400 </indexterm>
401 </listitem>
402 </varlistentry>
403
404 <varlistentry id="libmozjs-&spidermonkey-major;">
405 <term>
406 <filename class="libraryfile">
407 libmozjs-&spidermonkey-major;.so
408 </filename>
409 </term>
410 <listitem>
411 <para>
412 contains the Mozilla JavaScript API functions
413 </para>
414 <indexterm zone="spidermonkey libmozjs-&spidermonkey-major;">
415 <primary sortas="c-libmozjs&spidermonkey-major;">
416 libmozjs-&spidermonkey-major;.so
417 </primary>
418 </indexterm>
419 </listitem>
420 </varlistentry>
421 </variablelist>
422 </sect2>
423
424</sect1>
Note: See TracBrowser for help on using the repository browser.