source: general/genlib/spidermonkey.xml@ 3636c57e

12.1 ken/TL2024 ken/tuningfonts lazarus plabs/newcss python3.11 rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18
Last change on this file since 3636c57e was c12fd0f, checked in by Xi Ruoyao <xry111@…>, 8 months ago

spidermonkey: Enable rust SIMD optimization

Arch and Gentoo do this for Firefox, Thunderbird, and SpiderMonkey.
I've tested SpiderMonkey with this for a while. I'll enable this
for Firefox and Thunderbird too after testing them.

Sort all the switches (but --prefix) and explanations in alphabetic
order by the way.
  • Property mode set to 100644
File size: 15.9 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 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 "93fb7e0baa3e99209e870f7c032ca513">
10 <!ENTITY spidermonkey-size "482 MB">
11 <!ENTITY spidermonkey-buildsize "3.5 GB (40 MB installed after removing 36MB static lib; additional 29 MB for the main tests and 31 MB for the jit tests with 4 cores online)">
12 <!ENTITY spidermonkey-time "2.5 SBU (with parallelism=4; additional 1.8 SBU for the main test and 4.4 SBU for the jit test)">
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 &lfs120_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"/>,
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
173 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
174 href="../../xincludes/mozconfigure.xml"/>
175
176 <para>
177 Compiling the C++ code respects $MAKEFLAGS and defaults to 'j1',
178 the rust code will use all processors.
179 </para>
180 </note>
181
182<screen><userinput>mkdir obj &amp;&amp;
183cd obj &amp;&amp;
184
185../js/src/configure --prefix=/usr \
186 --disable-debug-symbols \
187 --disable-jemalloc \
188 --enable-readline \
189 --enable-rust-simd \
190 --with-intl-api \
191 --with-system-icu \
192 --with-system-zlib &amp;&amp;
193make</userinput></screen>
194
195 <para>
196 To run the SpiderMonkey test suite, issue:
197 <command>make -C js/src check-jstests
198 JSTESTS_EXTRA_ARGS="--timeout 300 --wpt=disabled"</command>.
199 It's recommended to redirect the output into a log.
200 <!-- recheck when ICU gets upgraded -->
201 Because we are building with system ICU, 41 tests
202 (out of a total of more than 50,000) are known to fail.
203 The test suite is executed with all CPU cores available: even in a
204 cgroup with less cores assigned, it still attempts to spawn as many
205 testing jobs as the number of <emphasis>all</emphasis> cores in the
206 system; fortunately the kernel still won't run these jobs on cores
207 not assigned to the cgroup so the CPU usage is still controlled.
208 </para>
209 <para>
210 To run the JIT test suite, issue: <command>make -C js/src
211 check-jit-test JITTEST_EXTRA_ARGS="--timeout 300"</command>.
212 Like the SpiderMonkey test suite, the number of test jobs is same as
213 the number of all CPU cores in the system even if a cgroup is used. To
214 make things worse, there are six tests each of them will use 3 GB
215 of system memory, so the peak memory usage may be up to 18 GB if the
216 number of cores is six or more. Running the JIT test suite without
217 enough memory may invoke the kernel OOM killer and cause stability
218 issues. If you don't have enough system memory available, append
219 <option>-jN</option> after <option>--timeout 300</option> with N
220 replaced by the number of parallel test jobs you want to start. For
221 example, if you have 16 GB system memory available and 8 CPU cores,
222 issue <command>make -C js/src check-jit-test
223 JITTEST_EXTRA_ARGS="--timeout=300 -j5"</command> to run the test with
224 5 parallel jobs so the memory usage won't exceed 15 GB.
225 <!-- TL;DR: DO NOT REMOVE MEMORY USAGE NOTE W/O MY CONFIRMATION!
226
227 "six tests": bug1782468-ptrdiff-veclen.js, it's ran with 6
228 different configurations.
229
230 "may": this is stochasitic (like all parallelization issue),
231 don't remove the note about memory usage simply because "I cannot
232 reproduce it".
233
234 "peak": the time period using so much memory is very short, so
235 don't just watch the output of "top" or "free" with eyesight.
236 Run the test in a cgroup and read the "memory.peak" psuedo file
237 for a proper measurement.
238
239 Q: Why not just document some test failures?
240 A: This *really* can cause stability issue because the kernel
241 may OOM kill another process if the test is not ran in a
242 cgroup with memory.max set. Even if running it in a cgroup,
243 the kernel may still OOM kill the "main" process controlling
244 the test process instead of a single test job, causing a
245 incomplete test.
246
247 - xry111
248 -->
249 </para>
250
251 <caution>
252 <para>
253 An issue in the installation process causes any running program which
254 links to SpiderMonkey shared library (for example, GNOME Shell) to
255 crash if SpiderMonkey is reinstalled, or upgraded or downgraded
256 without a change of the major version number
257 (&spidermonkey-major; in &spidermonkey-version;). To work around
258 this issue, remove the old version of the SpiderMonkey shared
259 library before installation:
260 </para>
261
262<screen role="root"><userinput>rm -fv /usr/lib/libmozjs-&spidermonkey-major;.so</userinput></screen>
263 </caution>
264
265 <para>
266 Now, as the <systemitem class="username">root</systemitem> user:
267 </para>
268
269<screen role="root"><userinput>make install &amp;&amp;
270rm -v /usr/lib/libjs_static.ajs &amp;&amp;
271sed -i '/@NSPR_CFLAGS@/d' /usr/bin/js&spidermonkey-major;-config</userinput></screen>
272
273 </sect2>
274
275 <sect2 role="commands">
276 <title>Command Explanations</title>
277
278 <para>
279 <parameter>--disable-debug-symbols</parameter>: Don't generate debug
280 symbols since they are very large and most users won't need it. Remove
281 it if you want to debug SpiderMonkey.
282 </para>
283
284 <para>
285 <parameter>--disable-jemalloc</parameter>: This switch disables the
286 internal memory allocator used in SpiderMonkey. jemalloc is only
287 intended for the Firefox browser environment. For other applications
288 using SpiderMonkey, the application may crash as items allocated in
289 the jemalloc allocator are freed on the system (glibc) allocator.
290 </para>
291
292 <para>
293 <parameter>--enable-readline</parameter>: This switch enables Readline
294 support in the SpiderMonkey command line interface.
295 </para>
296
297 <para>
298 <parameter>--enable-rust-simd</parameter>: This switch enables SIMD
299 optimization in the shipped encoding_rs crate.
300 </para>
301
302 <para>
303 <parameter>--with-intl-api</parameter>: This enables the
304 internationalization functions required by
305 <application>Gjs</application>.
306 </para>
307
308 <para>
309 <parameter>--with-system-*</parameter>: These parameters allow the build system
310 to use system versions of the above libraries. These are required for
311 stability.
312 </para>
313
314 <para>
315 <command>rm -v /usr/lib/libjs_static.ajs</command>: Remove a large
316 static library which is not used by any BLFS package.
317 </para>
318
319 <para>
320 <command>sed -i '/@NSPR_CFLAGS@/d'
321 /usr/bin/js&spidermonkey-major;-config</command>:
322 Prevent <command>js&spidermonkey-major;-config</command> from using
323 buggy CFLAGS.
324 </para>
325
326 <para>
327 <option><envar>CC=gcc CXX=g++</envar></option>: BLFS used to
328 prefer to use gcc and g++ instead of upstream's defaults of the
329 <application>clang</application> programs. With the release of
330 gcc-12 the build takes longer with gcc and g++, primarily because
331 of extra warnings, and is bigger. Pass these environment variables
332 to the configure script if you wish to continue to use gcc, g++
333 (by exporting them and unset them after the installation, or simply
334 prepending them before the
335 <command>../js/src/configure</command> command). If you are
336 building on a 32-bit system, also see below.
337 </para>
338
339 <para>
340 <option><envar>CXXFLAGS="-msse2 -mfpmath=sse"</envar></option>:
341 Use SSE2 instead of 387 for double-precision floating-point
342 operations. It's needed by GCC to satisfy the expectations of
343 upstream (Mozilla) developers with floating-point arithmetic.
344 Use it if you are building this package on a 32-bit system with
345 GCC (if Clang is not installed or GCC is explicitly specified).
346 Note that this will cause SpiderMonkey to crash on a processor without
347 SSE2 capability. If you are running the system on such an old
348 processor, Clang is strictly needed. This setting is not needed on
349 64-bit systems because all 64-bit x86 processors support SSE2 and the
350 64-bit compilers (both Clang and GCC) use SSE2 by default.
351 </para>
352 </sect2>
353
354 <sect2 role="content">
355 <title>Contents</title>
356
357 <segmentedlist>
358 <segtitle>Installed Programs</segtitle>
359 <segtitle>Installed Libraries</segtitle>
360 <segtitle>Installed Directories</segtitle>
361
362 <seglistitem>
363 <seg>
364 js&spidermonkey-major; and js&spidermonkey-major;-config
365 </seg>
366 <seg>
367 libmozjs-&spidermonkey-major;.so
368 </seg>
369 <seg>
370 /usr/include/mozjs-&spidermonkey-major;
371 </seg>
372 </seglistitem>
373 </segmentedlist>
374
375 <variablelist>
376 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
377 <?dbfo list-presentation="list"?>
378 <?dbhtml list-presentation="table"?>
379
380 <varlistentry id="js&spidermonkey-major;">
381 <term><command>js&spidermonkey-major;</command></term>
382 <listitem>
383 <para>
384 provides a command line interface to the
385 <application>JavaScript</application> engine
386 </para>
387 <indexterm zone="spidermonkey js&spidermonkey-major;">
388 <primary sortas="b-js&spidermonkey-major;">
389 js&spidermonkey-major;
390 </primary>
391 </indexterm>
392 </listitem>
393 </varlistentry>
394
395 <varlistentry id="js&spidermonkey-major;-config">
396 <term><command>js&spidermonkey-major;-config</command></term>
397 <listitem>
398 <para>
399 is used to find the SpiderMonkey compiler and linker flags
400 </para>
401 <indexterm zone="spidermonkey js&spidermonkey-major;-config">
402 <primary sortas="b-js&spidermonkey-major;-config">i
403 js&spidermonkey-major;-config
404 </primary>
405 </indexterm>
406 </listitem>
407 </varlistentry>
408
409 <varlistentry id="libmozjs-&spidermonkey-major;">
410 <term>
411 <filename class="libraryfile">
412 libmozjs-&spidermonkey-major;.so
413 </filename>
414 </term>
415 <listitem>
416 <para>
417 contains the Mozilla JavaScript API functions
418 </para>
419 <indexterm zone="spidermonkey libmozjs-&spidermonkey-major;">
420 <primary sortas="c-libmozjs&spidermonkey-major;">
421 libmozjs-&spidermonkey-major;.so
422 </primary>
423 </indexterm>
424 </listitem>
425 </varlistentry>
426 </variablelist>
427 </sect2>
428
429</sect1>
Note: See TracBrowser for help on using the repository browser.