source: general/genlib/spidermonkey.xml@ 97cecf5

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY spidermonkey-download-http "&mozilla-http;/firefox/releases/&spidermonkey-version;esr/source/firefox-&spidermonkey-version;esr.source.tar.xz">
  <!ENTITY spidermonkey-download-ftp  " ">
  <!ENTITY spidermonkey-md5sum        "c8deec3a0e558a1882f11bbea2fbd462">
  <!ENTITY spidermonkey-size          "484 MB">
  <!ENTITY spidermonkey-buildsize     "3.3 GB (39 MB installed after removing 36MB static lib; additional 0.4 GB for the tests)">
  <!ENTITY spidermonkey-time          "2.0 SBU (with parallelism=4; additional 3.8 SBU for the tests)">
]>

<sect1 id="spidermonkey" xreflabel="SpiderMonkey from Firefox-&spidermonkey-version;">
  <?dbhtml filename="spidermonkey.html"?>


  <title>SpiderMonkey from Firefox-&spidermonkey-version;</title>

  <indexterm zone="spidermonkey">
    <primary sortas="a-spidermonkey">SpiderMonkey</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to SpiderMonkey</title>

    <para>
      <application>SpiderMonkey</application> is Mozilla's JavaScript and
      WebAssembly Engine, written in C++ and Rust.
      In BLFS, the source code of SpiderMonkey is taken from Firefox.
    </para>

    <!-- To editors: make sure polkit works with mozjs when
         tagging SpiderMonkey or upgrading it to a new major version.  -->
    &lfs120_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&spidermonkey-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&spidermonkey-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &spidermonkey-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &spidermonkey-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &spidermonkey-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &spidermonkey-time;
        </para>
      </listitem>
    </itemizedlist>
<!--
    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/js-&JS91-version;-python_3_10-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>
-->
    <bridgehead renderas="sect3">SpiderMonkey Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="icu"/>,
      <xref linkend="rust"/>, and
      <xref linkend="which"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <!-- If clang is installed, it will be used instead of gcc.
           gcc does not work for 32-bit system w/o -msse2 -mfpmath=sse:
           https://bugzilla.mozilla.org/show_bug.cgi?id=1729459 -->
      <xref linkend="llvm"/> (with <application>Clang</application>,
      required for 32-bit systems without SSE2 capabilities)
    </para>

    <important>
      <para>
        If you are building this package on a 32-bit system, and Clang
        is not installed or you're overriding the default compiler choice
        with the environment variable <envar>CXX</envar>, please read the
        Command Explanations section first.
      </para>
    </important>

    <!-- It seems nasm is only used for aarch64-win64. -->
    <!--bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="nasm"/>
    </para-->

  </sect2>

  <sect2 role="installation">
    <title>Installation of SpiderMonkey</title>

    <note>
      <para>
        Unlike most other packages in BLFS, the instructions below require
        you to untar
        <filename>firefox-&spidermonkey-version;esr.tar.xz</filename> and
        change into the <filename>firefox-&spidermonkey-version;</filename>
        folder.
      </para>

      <para>
        Extracting the tarball
        will reset the permissions of the current directory to 0755 if you
        have permission to do that. If you do this in a directory where
        the sticky bit is set, such
        as <filename class="directory">/tmp</filename> it will end with error
        messages:
      </para>

<literallayout>tar: .: Cannot utime: Operation not permitted
tar: .: Cannot change mode to rwxr-xr-t: Operation not permitted
tar: Exiting with failure status due to previous errors
</literallayout>

      <para>
        This does finish with non-zero status, but it does
        <emphasis>NOT</emphasis> mean there is a real problem.
        Do not untar as the <systemitem class="username">root</systemitem> user
        in a directory where the sticky bit is set - that will unset it.
      </para>

    </note>

    <para>
      Install <application>SpiderMonkey</application> by running the following
      commands:
    </para>

    <note>
      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
         href="../../xincludes/mozshm.xml"/>

      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
         href="../../xincludes/mozconfigure.xml"/>

      <para>
        Compiling the C++ code respects $MAKEFLAGS and defaults to 'j1',
        the rust code will use all processors.
      </para>
    </note>

<screen><userinput>mkdir obj &amp;&amp;
cd    obj &amp;&amp;

../js/src/configure --prefix=/usr            \
                    --with-intl-api          \
                    --with-system-zlib       \
                    --with-system-icu        \
                    --disable-jemalloc       \
                    --disable-debug-symbols  \
                    --enable-readline        &amp;&amp;
make</userinput></screen>

    <para>
      To run the SpiderMonkey test suite, issue:
      <command>make -C js/src check-jstests
      JSTESTS_EXTRA_ARGS="--timeout 300 --wpt=disabled"</command>.
      It's recommended to redirect the output into a log.
      <!-- recheck when ICU gets upgraded -->
      Because we are building with system ICU, 8 tests
      (out of a total of more than 50,000) are known to fail.
    </para>
    <para>
      The JIT test suite can use a large amount of system memory.
      Running the JIT test suite without enough memory may invoke the
      the kernel OOM killer and causes stability issues. To run the JIT test
      suite, ensure the amount of available system memory is at least 16 GB,
      <!-- When I run it within a cgroup with 8 GB memory assigned, the test
           is OOM killed.  Increasing the assigned memory to 16 GB makes
           all tests pass.  -->
      then issue: <command>make -C js/src check-jit-test
      JITTEST_EXTRA_ARGS="--timeout 300"</command>.
    </para>

    <caution>
      <para>
        An issue in the installation process causes any running program which
        links to SpiderMonkey shared library (for example, GNOME Shell) to
        crash if SpiderMonkey is reinstalled, or upgraded or downgraded
        without a change of the the major version number
        (&spidermonkey-major; in &spidermonkey-version;).  To work around
        this issue, remove the old version of the SpiderMonkey shared
        library before installation:
      </para>

<screen role="root"><userinput>rm -fv /usr/lib/libmozjs-&spidermonkey-major;.so</userinput></screen>
    </caution>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install &amp;&amp;
rm -v /usr/lib/libjs_static.ajs &amp;&amp;
sed -i '/@NSPR_CFLAGS@/d' /usr/bin/js&spidermonkey-major;-config</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <parameter>--with-intl-api</parameter>: This enables the
      internationalization functions required by
      <application>Gjs</application>.
    </para>

    <para>
      <parameter>--with-system-*</parameter>: These parameters allow the build system
      to use system versions of the above libraries. These are required for
      stability.
    </para>

    <para>
      <parameter>--enable-readline</parameter>: This switch enables Readline
      support in the SpiderMonkey command line interface.
    </para>

    <para>
      <parameter>--disable-jemalloc</parameter>: This switch disables the
      internal memory allocator used in SpiderMonkey. jemalloc is only
      intended for the Firefox browser environment. For other applications
      using SpiderMonkey, the application may crash as items allocated in
      the jemalloc allocator are freed on the system (glibc) allocator.
    </para>

    <para>
      <parameter>--disable-debug-symbols</parameter>: Don't generate debug
      symbols since they are very large and most users won't need it. Remove
      it if you want to debug SpiderMonkey.
    </para>

    <para>
      <command>rm -v /usr/lib/libjs_static.ajs</command>: Remove a large
      static library which is not used by any BLFS package.
    </para>

    <para>
      <command>sed -i '/@NSPR_CFLAGS@/d'
      /usr/bin/js&spidermonkey-major;-config</command>:
      Prevent <command>js&spidermonkey-major;-config</command> from using
      buggy CFLAGS.
    </para>

    <para>
      <option><envar>CC=gcc CXX=g++</envar></option>: BLFS used to
      prefer to use gcc and g++ instead of upstream's defaults of the
      <application>clang</application> programs. With the release of
      gcc-12 the build takes longer with gcc and g++, primarily because
      of extra warnings, and is bigger. Pass these environment variables
      to the configure script if you wish to continue to use gcc, g++
      (by exporting them and unset them after the installation, or simply
      prepending them before the
      <command>../js/src/configure</command> command).  If you are
      building on a 32-bit system, also see below.
    </para>

    <para>
      <option><envar>CXXFLAGS="-msse2 -mfpmath=sse"</envar></option>:
      Use SSE2 instead of 387 for double-precision floating-point
      operations.  It's needed by GCC to satisfy the expectations of
      upstream (Mozilla) developers with floating-point arithmetic.
      Use it if you are building this package on a 32-bit system with
      GCC (if Clang is not installed or GCC is explicitly specified).
      Note that this will cause SpiderMonkey to crash on a processor without
      SSE2 capability.  If you are running the system on such an old
      processor, Clang is strictly needed.  This setting is not needed on
      64-bit systems because all 64-bit x86 processors support SSE2 and the
      64-bit compilers (both Clang and GCC) use SSE2 by default.
    </para>
  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          js&spidermonkey-major; and js&spidermonkey-major;-config
        </seg>
        <seg>
          libmozjs-&spidermonkey-major;.so
        </seg>
        <seg>
          /usr/include/mozjs-&spidermonkey-major;
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="js&spidermonkey-major;">
        <term><command>js&spidermonkey-major;</command></term>
        <listitem>
          <para>
            provides a command line interface to the
            <application>JavaScript</application> engine
          </para>
          <indexterm zone="spidermonkey js&spidermonkey-major;">
            <primary sortas="b-js&spidermonkey-major;">
              js&spidermonkey-major;
            </primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="js&spidermonkey-major;-config">
        <term><command>js&spidermonkey-major;-config</command></term>
        <listitem>
          <para>
            is used to find the SpiderMonkey compiler and linker flags
          </para>
          <indexterm zone="spidermonkey js&spidermonkey-major;-config">
            <primary sortas="b-js&spidermonkey-major;-config">i
              js&spidermonkey-major;-config
            </primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libmozjs-&spidermonkey-major;">
        <term>
          <filename class="libraryfile">
            libmozjs-&spidermonkey-major;.so
          </filename>
        </term>
        <listitem>
          <para>
            contains the Mozilla JavaScript API functions
          </para>
          <indexterm zone="spidermonkey libmozjs-&spidermonkey-major;">
            <primary sortas="c-libmozjs&spidermonkey-major;">
              libmozjs-&spidermonkey-major;.so
            </primary>
          </indexterm>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect2>

</sect1>