source: general/genlib/js68.xml@ f3d9ce9

<?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 js68-download-http "&mozilla-http;/firefox/releases/&firefox-version;esr/source/firefox-&firefox-version;esr.source.tar.xz">
  <!ENTITY js68-download-ftp  " ">
  <!-- FIXME (that gets a highlight) - md5sum and size should match firefox -->
  <!ENTITY firefox-md5sum     "a1156aed941b28a06115a9450a46563d">
  <!ENTITY firefox-size       "303 MB">
  <!ENTITY js68-buildsize     "2.8 GB (31 MB installed after removing 31MB static lib)">
  <!ENTITY js68-time          "2.4 SBU (with parallelism = 4)">
]>

<!--<sect1 id="js68" xreflabel="js68-&JS68-version;">-->
<sect1 id="js68" xreflabel="js68-&firefox-version;">
  <?dbhtml filename="js68.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

<!--<title>JS-&JS68-version;</title>-->
  <title>JS-&firefox-version;</title>

  <indexterm zone="js68">
    <primary sortas="a-js68">js68</primary>
  </indexterm>

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

    <para>
      <application>JS</application> is Mozilla's JavaScript engine
      written in C. JS68 is taken from Firefox.
    </para>

    <!-- JS68 is only used by gjs at the moment -->

    <!-- We'll need to remember to update js68 anytime there is a firefox
         ESR update. -->

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&js68-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&js68-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &firefox-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &firefox-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &js68-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &js68-time;
        </para>
      </listitem>
    </itemizedlist>

    <!--
    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/js68-&JS68-version;-python_3-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>
    -->

    <bridgehead renderas="sect3">JS68 Dependencies</bridgehead>

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

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="llvm"/> (with <application>Clang</application>) and
      <xref linkend="doxygen"/>
    </para>

    <para condition="html" role="usernotes">
      User Notes: <ulink url="&blfs-wiki;/js68"/>
    </para>
  </sect2>

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

    <caution>
      <para>
        If you are upgrading JS68 from a previously installed old version,
        save all work and exit your GNOME Session if you have one running.
        Replacing the JS68 binary will cause the GNOME Shell to crash and
        return you to your display manager or TTY. After installing the new
        version, if GNOME Shell still doesn't work, reinstall
        <xref linkend="gjs"/>.
      </para>
    </caution>

    <note>
      <para>
        Unlike most other packages in BLFS, the instructions below require you
        to untar <filename>firefox-&firefox-version;esr.tar.xz</filename> and
        change into the <filename>firefox-&firefox-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>
      First, apply a patch so we can run the shipped build scripts with
      Python 3, instead of the EOL'ed Python 2:
    </para>

<screen><userinput remap="pre">patch -Np1 -i ../js68-&JS68-version;-python_3-1.patch</userinput></screen>
    -->
    <para>
      Install <application>JS</application> by running the following
      commands:
    </para>

<!--    &shell-env;-->

     <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"/>
     </note>


<screen><userinput>sed '21,+4d' -i js/moz.configure &amp;&amp;

mkdir obj &amp;&amp;
cd    obj &amp;&amp;

CC=gcc CXX=g++ LLVM_OBJDUMP=/bin/false       \
../js/src/configure --prefix=/usr            \
                    --with-intl-api          \
                    --with-system-zlib       \
                    --with-system-icu        \
                    --disable-jemalloc       \
                    --disable-debug-symbols  \
                    --enable-readline        \
                    --enable-unaligned-private-values &amp;&amp;
make</userinput></screen>

    <para>
      This package does not come with a working test suite.
    </para>

    <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</userinput></screen>

  </sect2>

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

    <para>
      <command>sed '21,+4d' js/moz.configure</command>: Firefox building
      system searches for <command>rustc</command> and
      <command>cargo</command>.
      Since we are building the standalone JS engine instead of the entire
      browser, they are not actually used.
      Remove the reference to them so we can
      build JS68 without <xref role="nodep" linkend="rust"/> installed.
    </para>

    <para>
      <envar>CC=gcc CXX=g++</envar>: Upstream now prefers
      <application>clang</application>, override it like other Mozilla
      packages in BLFS book.
    </para>

    <para>
      <envar>LLVM_OBJDUMP=/bin/false</envar>: Firefox building system
      searches for <command>llvm-objdump</command>.
      Since we are building the standalone JS engine instead of the entire
      browser, they are not actually used.
      Override it so we can build JS68 without
      <xref role="nodep" linkend="llvm"/> installed.
    </para>

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

    <para>
      <parameter>--enable-readline</parameter>: This switch enables Readline
      support in the JS shell.
    </para>
    
    <para>
      <parameter>--disable-jemalloc</parameter>: This switch disables the
      internal memory allocator used in JS68. jemalloc causes a conflict with glibc.
    </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 JS68.
    </para>

    <para>
      <parameter>--enable-unaligned-private-values</parameter>: This switch
      allows the code using JS68 not to align all pointers in the same way
      JS68 does.  <xref linkend="gjs"/> requires JS68 to be built with this
      switch.
    </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>

  </sect2>

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

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

      <seglistitem>
        <seg>
          js68 and js68-config
        </seg>
        <seg>
          libmozjs-68.so and libjs_static.ajs <!-- The AJS file doesn't
          conflict with the one from js52 like originally thought -->
        </seg>
        <seg>
          /usr/include/mozjs-68
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="js6-js68">
        <term><command>js68</command></term>
        <listitem>
          <para>
            provides a command line interface to the
            <application>JavaScript</application> engine.
          </para>
          <indexterm zone="js68 js68">
            <primary sortas="b-js68">js68</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="js68-config">
        <term><command>js68-config</command></term>
        <listitem>
          <para>
            is used to find the JS compiler and linker flags.
          </para>
          <indexterm zone="js68 js68-config">
            <primary sortas="b-js68-config">js68-config</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libmozjs-68">
        <term><filename class="libraryfile">libmozjs-68.so</filename></term>
        <listitem>
          <para>
            contains the Mozilla JavaScript API functions.
          </para>
          <indexterm zone="js68 libmozjs-68">
            <primary sortas="c-libmozjs68">libmozjs-68.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect2>
</sect1>