source: general/genlib/spidermonkey.xml@ 2658a0d

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 2658a0d was 4b795d34, checked in by Ken Moffat <ken@…>, 9 months ago

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