source: general/genlib/spidermonkey.xml

trunk
Last change on this file was 55c9a18, checked in by Douglas R. Reno <renodr@…>, 12 days ago

Update to spidermonkey-115.10.0 (Security Update)

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