SpiderMonkey Build Documentation

  • Revision slug: SpiderMonkey/Build_Documentation
  • Revision title: SpiderMonkey Build Documentation
  • Revision id: 39213
  • Created:
  • Creator: pbiggar
  • Is current revision? No
  • Comment 2 words added

Revision Content

Building SpiderMonkey

{{ jsapi_minversion_header("1.8.1") }}

Use these instructions to build the latest SpiderMonkey sources fetched from the Mercurial repository.

Before you begin, make sure you have right build tools for your computer: LinuxWindowsMacothers. In addition, you will need NSPR, which is easy to install.

And of course you'll need to get the SpiderMonkey source code.

Easy build

Once you have the source code and build prerequisites, you can build current versions of SpiderMonkey like so:

cd js/src
autoconf-2.13
./configure
make

Note that autoconf version 2.13 is required. No later version will work.

If this does not work correctly due to NSPR problems, see Troubleshooting NSPR.

This builds an executable named js in the current directory. At this point, you're ready to run and try out the shell.

On Mac, Linux, or UNIX, you can install SpiderMonkey on your system with the additional command make install. This installs the js executable, the shared library, and C header files to /usr/local/{bin,lib,include}.

Advanced build

For developing and debugging SpiderMonkey itself, it is best to have both a debug build (for everyday debugging) and an optimized build (for performance testing), in separate build directories.

cd js/src
autoconf-2.13

mkdir build-release
cd build-release
../configure
make
cd ..

mkdir build-debug
cd build-debug
../configure --enable-debug --disable-optimize
make

(Note:  If you previously did the easy build, you must first delete all the files and directories it created. If you don't, the advanced build will fail with error messages about not being able to open dependency files.)

You may also build debug builds of SpiderMonkey with the JS_GC_ZEAL option, which adds a new built-in function to SpiderMonkey that lets you configure zealous garbage collection.  This can help debug memory leaks and other memory-related problems. See JS_SetGCZeal() for details.

For a list of other available build options, type:

./configure --help

Troubleshooting NSPR

By default, `./configure` will use the nspr-config program, installed as part of NSPR, to find the appropriate way to include and link to NSPR. In this case, you do not need to do anything special to make SpiderMonkey build with NSPR. However, if NSPR is not installed on the path, or you are using Windows, some extra steps are required.

If the nspr-config script is not in your path, you can also pass either --with-nspr-prefix=DIR or --with-nspr-exec-prefix=DIR, where the nspr-config script can be found in DIR/bin.

Specifying NSPR flags directly

If nspr-config does not work, or cannot be found, you must manually specify --with-nspr-cflags and --with-nspr-libs options, to specify the compiler and linker flags for NSPR directly.

The --with-nspr-cflags option takes flags telling the compiler how to find the NSPR headers. Typically, it will be specified as: --with-nspr-cflags="-I/usr/local/include/nspr", which is the gcc "-I" flag, specifying that the NSPR headers can be included from /usr/local/include/nspr.

Similary, the --with-nspr-libs option takes flags telling the linker how to link to NSPR. Typically, it will be specified as: --with-nspr-libs="-L/usr/local/lib -lplds4 -lplc4 -lnspr4". This comprises the gcc "-L" flag, specifying that the gcc should add /usr/local/lib to its list of directories to search for libraries; and the gcc "-l" flag, specifying a number of libraries which must be available for linking.

NSPR on Windows

On Windows, nspr-config returns incorrect values, and so the compiler and linker flags must be given directly. Assuming that NSPR has been installed in /usr/local/, using MozillaBuild, the following commands will build Windows:

# Configure
./configure \
   --with-nspr-cflags="-I/usr/local/include/nspr" \
   --with-nspr-libs=" \
      C:\mozilla-build\msys\local\lib\nspr4.lib \
      C:\mozilla-build\msys\local\lib\plds4.lib \
      C:\mozilla-build\msys\local\lib\plc4.lib"

# Build
make

# Run. The NSPR dlls need to be available on the PATH.
PATH="$PATH:/usr/local/lib" ./js --help

Specifying installation directories

make install puts files in the following directories by default. You can override this by passing options to the configure script:

What it is Where it gets put configure option
executables, shell scripts /usr/local/bin --bindir
libraries, data /usr/local/lib --libdir
architecture-independent data /usr/local/share --sharedir
C header files /usr/local/include --includedir

For convenience, you can pass the configure script an option of the form --prefix=PREFIXDIR, which substitutes PREFIXDIR for /usr/local in all the settings above, in one step. This is usually the least troublesome thing to do, as it preserves the typical arrangement of lib, bin, and the rest.

Note that whatever directories you pass to configure are recorded in the generated Makefile, so you don't need to specify them again until you re-run configure.

Building SpiderMonkey as a static library

By default, SpiderMonkey builds as a shared library. However, you can build SpiderMonkey as a static library by specifying the --disable-shared-js flag when running configure.

Specifying compilers and compiler flags

If you'd like to use a compiler other than the one the configure script chooses for you by default, you can set the CXX variable in the environment when you run configure. This will save the values you specify in the generated Makefile, so once you've set it, you don't need to do so again until you re-run configure.

If you'd like to pass certain flags to the compiler, you can set the CXXFLAGS environment variable when you run configure. For example, if you're using the GNU toolchain, the following will pass the -g3 flag to the compiler, causing it to emit debug information about macros; then you can use those macros in gdb commands:

    $ CXXFLAGS=-g3 $SRC/configure
    ...
    checking whether the C++ compiler (c++ -g3 ) works... yes
    ...
    $

To build a 32-bit version on a 64-bit Linux system, you can use the following:

    PKG_CONFIG_LIBDIR=/usr/lib/pkgconfig CC="gcc -m32" CXX="g++ -m32" AR=ar $SRC/configure --target=i686-pc-linux

To build a 64-bit version on a 32-bit Mac system (e.g. Mac OS X 10.5), you can use the following:

    AR=ar CC="gcc -m64" CXX="g++ -m64" ../configure --target=x86_64-apple-darwin10.0.0

Whatever compiler and flags you pass to configure are recorded in the generated Makefile, so you don't need to specify them again until you re-run configure.

Building SpiderMonkey 1.8 or earlier

Use these instructions to build SpiderMonkey from an official source release or from the old CVS repository. To build the latest SpiderMonkey sources from Mercurial, see Building SpiderMonkey above.

SpiderMonkey is easy to build from source if you have the usual Mozilla build prerequisites installed. Before you begin, make sure you have right build tools for your computer: Linux, Windows, Mac, others.

First, download a SpiderMonkey source distribution, such as SpiderMonkey 1.8 Release Candidate 1.

To build, use these commands:

tar xvzf js-1.8.0-rc1.tar.gz
cd js/src
make -f Makefile.ref

This builds a debug version of SpiderMonkey. All build files are created in a subdirectory named depending on your system (for example, Linux_All_DBG.OBJ if you are on Linux). To install this build on your system, see SpiderMonkey installation instructions.

To build an optimized (non-debug) version of SpiderMonkey:

make BUILD_OPT=1 -f Makefile.ref

To build a thread-safe version of SpiderMonkey:

make JS_DIST=/full/path/to/directory/containing/nspr JS_THREADSAFE=1 -f Makefile.ref

Building your application

While "How to build your complete application" is clearly out of scope for this document, here are some tips which will help get you on your way:

  • The SpiderMonkey developers frequently and deliberately change the JSAPI ABI. You may not use headers built for one version/configuration of JSAPI to create object files which will be linked against another.
  • Support for JS_THREADSAFE was recently removed, and threadsafe builds are now enabled by default.
  • The js-config script, described below, is the recommended way to determine correct include paths, required libraries, etc. for your embedding to use during compilation. We highly recommend calling the js-config script from your embedding's Makefile to set your CFLAGS, LDFLAGS, and so forth.
  • To install SpiderMonkey someplace other than the default, you must use configure's --prefix option, as described above. Failure to do so may break your js-config.h header or js-config script.
  • Some features detected by the configure script do not work for cross-compilation.

Using the js-config script

In addition to the SpiderMonkey libraries, header files, and shell, the SpiderMonkey build also produces a shell script named js-config which other build systems can use to find out how to compile code using the SpiderMonkey APIs, and how to link with the SpiderMonkey libraries.

When invoked with the --cflags option, js-config prints the flags that you should pass to the C compiler when compiling files that use the SpiderMonkey API; these flags ensure the compiler will find the SpiderMonkey header files.

    $ ./js-config --cflags
    -I/usr/local/include/js -I/usr/include/nspr

When invoked with the --libs option, js-config prints the flags that you should pass to the C compiler when linking an executable or shared library that uses SpiderMonkey. These flags ensure the compiler will find the SpiderMonkey libraries, along with any libraries that SpiderMonkey itself depends upon (like NSPR).

    $ ./js-config --libs
    -L/usr/local/lib -lmozjs -L/usr/lib -lplds4 -lplc4 -lnspr4 -lpthread -ldl -ldl -lm  -lm -ldl 

Test

The commands below assume you're using the advanced build.

  • Run ./js ../perfect.js and check if appropriate output is printed.

  • Run the main test suite by running ../tests/jstests.py ./js

  • Run JIT-specific tests by running: ../jit-test/jit_test.py ./js

Revision Source

<h2 id="Building_SpiderMonkey_tip">Building SpiderMonkey</h2>
<p>{{ jsapi_minversion_header("1.8.1") }}</p>
<p>Use these instructions to build the latest SpiderMonkey sources fetched from the Mercurial repository.</p>
<p>Before you begin, make sure you have right build tools for your computer: <a href="/En/Developer_Guide/Build_Instructions/Linux_Prerequisites" style="text-decoration: none; color: rgb(4, 137, 183) ! important; cursor: default;" title="en/Linux_Build_Prerequisites">Linux</a>, <a href="/En/Developer_Guide/Build_Instructions/Windows_Prerequisites" style="text-decoration: none; color: rgb(4, 137, 183) ! important; cursor: default;" title="en/Windows_Build_Prerequisites">Windows</a>, <a href="/En/Developer_Guide/Build_Instructions/Mac_OS_X_Prerequisites" style="text-decoration: none; color: rgb(4, 137, 183) ! important; cursor: default;" title="en/Mac_OS_X_Build_Prerequisites">Mac</a>, <a href="/En/Developer_Guide/Build_Instructions" style="text-decoration: none; color: rgb(4, 137, 183) ! important; cursor: default;" title="en/Build_Documentation">others</a>. In addition, you will need NSPR, which is <a class="internal" href="/En/NSPR" title="En/NSPR">easy to install</a>.</p>
<p style="margin: 0px 0px 1.7em; padding: 0px;">And of course you'll need to <a class="internal" href="/En/SpiderMonkey/Getting_SpiderMonkey_source_code#Getting_the_latest_SpiderMonkey_source_code" style="text-decoration: none; color: rgb(4, 137, 183) ! important; cursor: default;" title="En/SpiderMonkey/Getting SpiderMonkey source code#Getting the latest SpiderMonkey source code">get the SpiderMonkey source code</a>.</p>
<h3>Easy build</h3>
<p>Once you have the source code and build prerequisites, you can build current versions of SpiderMonkey like so:</p>
<pre class="eval">cd js/src
autoconf-2.13
./configure
make
</pre>
<p>Note that autoconf version 2.13 is required. No later version will work.</p>
<p>If this does not work correctly due to NSPR problems, see Troubleshooting NSPR.</p>
<p>This builds an executable named <code>js</code> in the current directory. At this point, you're ready to <a href="/En/SpiderMonkey/Introduction_to_the_JavaScript_shell" title="en/Introduction_to_the_JavaScript_shell">run and try out the shell</a>.</p>
<p>On Mac, Linux, or UNIX, you can install SpiderMonkey on your system with the additional command <code>make install</code>. This installs the <code>js</code> executable, the shared library, and C header files to <code>/usr/local/{bin,lib,include}</code>.</p>
<h3>Advanced build</h3>
<p>For developing and debugging SpiderMonkey itself, it is best to have both a debug build (for everyday debugging) and an optimized build (for performance testing), in separate build directories.</p>
<pre class="eval">cd js/src
autoconf-2.13

mkdir build-release
cd build-release
../configure
make
cd ..

mkdir build-debug
cd build-debug
../configure --enable-debug --disable-optimize
make
</pre>
<p>(Note:  If you previously did the easy build, you must first delete all the files and directories it created. If you don't, the advanced build will fail with error messages about not being able to open dependency files.)</p>
<p>You may also build debug builds of SpiderMonkey with the <code>JS_GC_ZEAL</code> option, which adds a new built-in function to SpiderMonkey that lets you configure zealous garbage collection.  This can help debug memory leaks and other memory-related problems. See <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_SetGCZeal" title="En/SpiderMonkey/JSAPI Reference/JS SetGCZeal"><code>JS_SetGCZeal()</code></a> for details.</p>
<p>For a list of other available build options, type:</p>
<pre class="eval">./configure --help
</pre>
<h2 name="Building">Troubleshooting NSPR</h2>
<p>By default, `./configure` will use the <code>nspr-config</code> program, installed as part of NSPR, to find the appropriate way to include and link to NSPR. In this case, you do not need to do anything special to make SpiderMonkey build with NSPR. However, if NSPR is not installed on the path, or you are using Windows, some extra steps are required.</p>
<p>If the <code>nspr-config</code> script is not in your path, you can also pass either <code>--with-nspr-prefix=DIR</code> or <code>--with-nspr-exec-prefix=DIR</code>, where the <code>nspr-config</code> script can be found in <code>DIR/bin</code>.</p>
<h4>Specifying NSPR flags directly</h4>
<p>If <code>nspr-config </code>does not work, or cannot be found, you must manually specify <code>--with-nspr-cflags </code>and <code>--with-nspr-libs </code>options, to specify the compiler and linker flags for NSPR directly.</p>
<p>The <code>--with-nspr-cflags</code> option takes flags telling the compiler how to find the NSPR headers. Typically, it will be specified as: <code>--with-nspr-cflags="-I/usr/local/include/nspr"</code>, which is the <code>gcc<code> </code></code>"<code>-I</code>" flag, specifying that the NSPR headers can be included from <code>/usr/local/include/nspr.</code></p>
<p>Similary, the <code>--with-nspr-libs</code> option takes flags telling the linker how to link to NSPR. Typically, it will be specified as: <code>--with-nspr-libs="-L/usr/local/lib -lplds4 -lplc4 -lnspr4"</code>. This comprises the <code>gcc<code> </code></code>"<code>-L</code>" flag, specifying that the gcc should add <code>/usr/local/lib </code>to its list of directories to search for libraries; and the <code>gcc<code> </code></code>"<code>-l</code>" flag, specifying a number of libraries which must be available for linking.</p><h4>NSPR on Windows</h4>
<p>On Windows, <code>nspr-config</code> returns incorrect values, and so the compiler and linker flags must be given directly. Assuming that NSPR has been installed in <code>/usr/local/, </code>using <a href="/En/Developer_Guide/Build_Instructions/Windows_Prerequisites#MozillaBuild" title="En/Windows Build Prerequisites#MozillaBuild">MozillaBuild</a>, the following commands will build Windows:</p>
<pre># Configure
./configure \
   --with-nspr-cflags="-I/usr/local/include/nspr" \
   --with-nspr-libs=" \
      C:\mozilla-build\msys\local\lib\nspr4.lib \
      C:\mozilla-build\msys\local\lib\plds4.lib \
      C:\mozilla-build\msys\local\lib\plc4.lib"

# Build
make

# Run. The NSPR dlls need to be available on the PATH.
PATH="$PATH:/usr/local/lib" ./js --help
</pre><h3>Specifying installation directories</h3>
<p><code>make install</code> puts files in the following directories by default. You can override this by passing options to the <code>configure</code> script:</p>
<table border="1" width="100%"> <tbody> <tr> <th>What it is</th> <th>Where it gets put</th> <th><code>configure</code> option</th> </tr> <tr> <td>executables, shell scripts</td> <td><code>/usr/local/bin</code></td> <td><code>--bindir</code></td> </tr> <tr> <td>libraries, data</td> <td><code>/usr/local/lib</code></td> <td><code>--libdir</code></td> </tr> <tr> <td>architecture-independent data</td> <td><code>/usr/local/share</code></td> <td><code>--sharedir</code></td> </tr> <tr> <td>C header files</td> <td><code>/usr/local/include</code></td> <td><code>--includedir</code></td> </tr> </tbody>
</table>
<p>For convenience, you can pass the <code>configure</code> script an option of the form <code>--prefix=PREFIXDIR</code>, which substitutes <code>PREFIXDIR</code> for <code>/usr/local</code> in all the settings above, in one step. This is usually the least troublesome thing to do, as it preserves the typical arrangement of <code>lib</code>, <code>bin</code>, and the rest.</p>
<p>Note that whatever directories you pass to <code>configure</code> are recorded in the generated <code>Makefile</code>, so you don't need to specify them again until you re-run <code>configure</code>.</p>
<h3>Building SpiderMonkey as a static library</h3>
<p>By default, SpiderMonkey builds as a shared library. However, you can build SpiderMonkey as a static library by specifying the <code>--disable-shared-js</code> flag when running <code>configure</code>.</p>
<h3>Specifying compilers and compiler flags</h3>
<p>If you'd like to use a compiler other than the one the <code>configure</code> script chooses for you by default, you can set the <code>CXX</code> variable in the environment when you run <code>configure</code>. This will save the values you specify in the generated Makefile, so once you've set it, you don't need to do so again until you re-run <code>configure</code>.</p>
<p>If you'd like to pass certain flags to the compiler, you can set the <code>CXXFLAGS</code> environment variable when you run <code>configure</code>. For example, if you're using the GNU toolchain, the following will pass the <code>-g3</code> flag to the compiler, causing it to emit debug information about macros; then you can use those macros in <code>gdb</code> commands:</p>
<pre class="eval">    $ <strong>CXXFLAGS=-g3 $SRC/configure</strong>
    <em>...</em>
    checking whether the C++ compiler (c++ -g3 ) works... yes
    <em>...</em>
    $
</pre>
<p>To build a 32-bit version on a 64-bit Linux system, you can use the following:</p>
<pre class="eval">    PKG_CONFIG_LIBDIR=/usr/lib/pkgconfig CC="gcc -m32" CXX="g++ -m32" AR=ar $SRC/configure --target=i686-pc-linux
</pre>
<p>To build a 64-bit version on a 32-bit Mac system (e.g. Mac OS X 10.5), you can use the following:</p>
<pre class="eval">    AR=ar CC="gcc -m64" CXX="g++ -m64" ../configure --target=x86_64-apple-darwin10.0.0
</pre>
<p>Whatever compiler and flags you pass to <code>configure</code> are recorded in the generated <code>Makefile</code>, so you don't need to specify them again until you re-run <code>configure</code>.</p><h2>Building SpiderMonkey 1.8 or earlier</h2>
<p><strong>Use these instructions to build SpiderMonkey from an official source release</strong> or from the old CVS repository. To build the latest SpiderMonkey sources from Mercurial, see <a href="#Building_SpiderMonkey_tip">Building SpiderMonkey </a>above.</p>
<p><a href="/en/SpiderMonkey" title="en/SpiderMonkey">SpiderMonkey</a> is easy to build from source if you have the usual Mozilla build prerequisites installed. <strong>Before you begin, make sure you have right build tools for your computer:</strong> <a href="/En/Developer_Guide/Build_Instructions/Linux_Prerequisites" title="en/Linux_Build_Prerequisites">Linux</a>, <a href="/En/Developer_Guide/Build_Instructions/Windows_Prerequisites" title="en/Windows_Build_Prerequisites">Windows</a>, <a href="/En/Developer_Guide/Build_Instructions/Mac_OS_X_Prerequisites" title="en/Mac_OS_X_Build_Prerequisites">Mac</a>, <a href="/En/Developer_Guide/Build_Instructions" title="en/Build_Documentation">others</a>.</p>
<p>First, download a SpiderMonkey source distribution, such as <a class=" external" href="http://ftp.mozilla.org/pub/mozilla.org/js/js-1.8.0-rc1.tar.gz">SpiderMonkey 1.8 Release Candidate 1</a>.</p>
<p>To build, use these commands:</p>
<pre class="eval">tar xvzf js-1.8.0-rc1.tar.gz
cd js/src
make -f Makefile.ref
</pre>
<p>This builds a debug version of SpiderMonkey. All build files are created in a subdirectory named depending on your system (for example, <code>Linux_All_DBG.OBJ</code> if you are on Linux). To install this build on your system, see <a class="external" href="http://ebixio.com/blog/2010/07/31/how-to-install-libjs-spidermonkey/" title="http://ebixio.com/blog/2010/07/31/how-to-install-libjs-spidermonkey/">SpiderMonkey installation instructions</a>.</p>
<p>To build an optimized (non-debug) version of SpiderMonkey:</p>
<pre class="eval">make BUILD_OPT=1 -f Makefile.ref</pre>
<p>To build a <a href="/en/SpiderMonkey/JSAPI_Reference/JS_THREADSAFE" title="JS_THREADSAFE">thread-safe</a> version of SpiderMonkey:</p>
<pre class="eval">make JS_DIST=/full/path/to/directory/containing/nspr JS_THREADSAFE=1 -f Makefile.ref
</pre>
<h2>Building your application</h2>
<p>While "How to build your complete application" is clearly out of scope for this document, here are some tips which will help get you on your way:</p>
<ul> <li>The SpiderMonkey developers frequently and deliberately change the JSAPI ABI. You may not use headers built for one version/configuration of JSAPI to create object files which will be linked against another.</li> <li>Support for JS_THREADSAFE was recently removed, and threadsafe builds are now enabled by default.</li> <li>The <code>js-config</code> script, described below, is the recommended way to determine correct include paths, required libraries, etc. for your embedding to use during compilation. We highly recommend calling the <code>js-config</code> script from your embedding's Makefile to set your CFLAGS, LDFLAGS, and so forth.</li> <li>To install SpiderMonkey someplace other than the default, you must use <code>configure</code>'s <code>--prefix</code> option, as described above. Failure to do so may break your <code>js-config.h</code> header or <code>js-config</code> script.</li> <li>Some features detected by the <code>configure</code> script do not work for cross-compilation.</li>
</ul>
<h4>Using the js-config script</h4>
<p>In addition to the SpiderMonkey libraries, header files, and shell, the SpiderMonkey build also produces a shell script named <code>js-config</code> which other build systems can use to find out how to compile code using the SpiderMonkey APIs, and how to link with the SpiderMonkey libraries.</p>
<p>When invoked with the <code>--cflags</code> option, <code>js-config</code> prints the flags that you should pass to the C compiler when compiling files that use the SpiderMonkey API; these flags ensure the compiler will find the SpiderMonkey header files.</p>
<pre class="eval">    $ <strong>./js-config --cflags</strong>
    -I/usr/local/include/js -I/usr/include/nspr
</pre>
<p>When invoked with the <code>--libs</code> option, <code>js-config</code> prints the flags that you should pass to the C compiler when linking an executable or shared library that uses SpiderMonkey. These flags ensure the compiler will find the SpiderMonkey libraries, along with any libraries that SpiderMonkey itself depends upon (like NSPR).</p>
<pre class="eval">    $ <strong>./js-config --libs</strong>
    -L/usr/local/lib -lmozjs -L/usr/lib -lplds4 -lplc4 -lnspr4 -lpthread -ldl -ldl -lm  -lm -ldl </pre><h2 name="Test">Test</h2>
<p>The commands below assume you're using the advanced build.</p>
<ul> <li> <p>Run <code>./js </code><code>../perfect.js</code> and check if appropriate output is printed.</p> </li> <li> <p>Run the main test suite by running <code>../tests/jstests.py ./js</code></p> </li> <li> <p>Run JIT-specific tests by running: <code>../jit-test/jit_test.py ./js</code></p> </li>
</ul>
Revert to this revision