SpiderMonkey Build Documentation

  • Revision slug: SpiderMonkey/Build_Documentation
  • Revision title: SpiderMonkey Build Documentation
  • Revision id: 39190
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment 16 words added, 5 words removed

Revision Content

{{ warning("Note for experienced JSAPI users: Read this entire document. Several important things have changed since the 1.7 release. Most notably, where to get SpiderMonkey, how to build it, and how to compile and link your application.") }}

 

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.

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.

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}.

Note: To build SpiderMonkey 1.8.0 or earlier (the version of SpiderMonkey in CVS) requires different commands:

cd js/src
make -f Makefile.ref

This builds the executable and stores the supporting files in a subdirectory named depending on your system (for example, Linux_All_DBG.OBJ if you are on Linux). To install this on your system, see manual SpiderMonkey installation instructions.

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.)

For a list of other available build options, type:

./configure --help

Multithreaded applications require a special, thread-safe build of SpiderMonkey. See the additional build instructions at JS_THREADSAFE.

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.

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
    ...
    $

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 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:

  • Versions of SpiderMonkey built with Makefile.ref require your application to define preprocessor macros visible to jsapi.h when you are building your own object files.  These macros might have included XP_UNIX, JS_THREADSAFE, and so forth. With the new configure-based build, these are no longer needed, and you should remove them from your build system. The jsapi.h header now includes js-config.h, which is created at configure time. This header #defines all necessary preprocessor macros so that your objects build with an ABI that is compatible with the library built with the same invocation of configure.
  • The SpiderMonkey developers frequently and purposefully 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.
  • The ABI for SpiderMonkey with and without thread support is different.  Be sure that your js-config.h header matches your library in this regard. There is currently no runtime test to determine if the ABIs match.
  • 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 
    $ 

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, in some circumstances).

    $ ./js-config --libs
    -L/usr/local/lib -lmozjs  -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 following commands to start the test suite.

    cd ../../tests
    perl jsDriver.pl -L lc2 -L lc3 -L slow-n.tests \
        -L spidermonkey-n.tests -L spidermonkey-n-1.9.1.tests \
        -k -e smopt -s ../src/build-release/js
    • Warning: The test suite could run up to 30-40 minutes and eats up a lot of CPU cycles.
    • The tests run noticeably faster against an optimized build, but a debug build is more likely to catch regressions (because assertions are enabled).
  • If there are any failures, they will be recorded in a file, something like results-2007-08-23-010815-smopt-failures.txt. Rename this file to spidermonkey-known-failures-n.tests.

    (As of 2007-08-23, there are around 175-200 failing tests. Tests fail for various reasons. Some are testing obsolete features that have been deleted from SpiderMonkey. Some tests are a bit bogus in various ways, so innocent changes to SpiderMonkey break them. Decompiler tests in particular tend to be overly strict.)

  • In subsequent test runs, you can add the option -L spidermonkey-known-failures-n.tests to the above test suite run command to ignore these failing tests. This way, you can make sure your code changes haven't broken anything which was previously working.

{{ jsapi_todo("public-failures.txt should be documented here.") }}

Revision Source

<p>{{ warning("<strong>Note for experienced JSAPI users:</strong> Read this entire document. Several important things have changed since the 1.7 release. Most notably, where to get SpiderMonkey, how to build it, and how to compile and link your application.") }}</p>
<p> </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. Before you begin, make sure you have right build tools for your computer: <a href="/en/Linux_Build_Prerequisites" title="en/Linux_Build_Prerequisites">Linux</a>, <a href="/en/Windows_Build_Prerequisites" title="en/Windows_Build_Prerequisites">Windows</a>, <a href="/en/Mac_OS_X_Build_Prerequisites" title="en/Mac_OS_X_Build_Prerequisites">Mac</a>, <a href="/en/Build_Documentation" title="en/Build_Documentation">others</a>.</p>
<p>And of course you'll need to <a href="/En/SpiderMonkey/Getting_SpiderMonkey_source_code" title="En/SpiderMonkey/Getting_SpiderMonkey_source_code">get the SpiderMonkey source code</a>.</p>
<h2 name="Build">Easy build</h2>
<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>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>
<div class="note">
<p>Note: To build SpiderMonkey 1.8.0 or earlier (the version of SpiderMonkey in CVS) requires different commands:</p>
<pre class="eval">cd js/src
make -f Makefile.ref
</pre>
<p>This builds the executable and stores the supporting files in a subdirectory named depending on your system (for example, <code>Linux_All_DBG.OBJ</code> if you are on Linux). To install this on your system, see <a class="external" href="http://dt.in.th/2008-03-03.spidermonkey-linux.html">manual SpiderMonkey installation instructions</a>.</p>
</div>
<h2>Advanced build</h2>
<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>For a list of other available build options, type:</p>
<pre class="eval">./configure --help
</pre>
<p>Multithreaded applications require a special, thread-safe build of SpiderMonkey. See the additional build instructions at <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_THREADSAFE" title="en/SpiderMonkey/JSAPI Reference/JS THREADSAFE"><code>JS_THREADSAFE</code></a>.</p>
<h2>Specifying installation directories</h2>
<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>
<h2>Specifying compilers and compiler flags</h2>
<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>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 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>Versions of SpiderMonkey built with Makefile.ref require your application to define preprocessor macros visible to <code>jsapi.h</code> when you are building your own object files.  These macros might have included <code>XP_UNIX</code>, <code>JS_THREADSAFE</code>, and so forth. With the new <code>configure</code>-based build, these are no longer needed, and you should remove them from your build system. The <code>jsapi.h</code> header now includes <code>js-config.h</code>, which is created at <code>configure</code> time. This header <code>#define</code>s all necessary preprocessor macros so that your objects build with an ABI that is compatible with the library built with the same invocation of configure.</li> <li>The SpiderMonkey developers frequently and purposefully 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>The ABI for SpiderMonkey with and without thread support is different.  Be sure that your<span style="font-family: Courier New;"> js-config.h </span>header matches your library in this regard. There is currently no runtime test to determine if the ABIs match.</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 configure's <span style="font-family: Courier New;">--prefix</span> option, as described above. Failure to do so may break your <span style="font-family: Courier New;">js-config.h</span> header or <span style="font-family: Courier New;">js-config</span> script.</li> <li>Some features detected by the <code>configure</code> script do not work for cross-compilation.</li>
</ul>
<h2>Using the js-config script</h2>
<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 
    $ </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, in some circumstances).</p>
<pre class="eval">    $ <strong>./js-config --libs</strong>
    -L/usr/local/lib -lmozjs  -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 following commands to start the test suite.</p> <pre>cd ../../tests
perl jsDriver.pl -L lc2 -L lc3 -L slow-n.tests \
    -L spidermonkey-n.tests -L spidermonkey-n-1.9.1.tests \
    -k -e smopt -s ../src/build-release/js</pre> <ul> <li><em>Warning</em>: The test suite could run up to 30-40 minutes and eats up a lot of CPU cycles.</li> <li>The tests run noticeably faster against an optimized build, but a debug build is more likely to catch regressions (because assertions are enabled).</li> </ul> </li> <li> <p>If there are any failures, they will be recorded in a file, something like <code>results-2007-08-23-010815-smopt-failures.txt</code>. Rename this file to <code>spidermonkey-known-failures-n.tests</code>.</p> <p>(As of 2007-08-23, there are around 175-200 failing tests. Tests fail for various reasons. Some are testing obsolete features that have been deleted from SpiderMonkey. Some tests are a bit bogus in various ways, so innocent changes to SpiderMonkey break them. Decompiler tests in particular tend to be overly strict.)</p> </li> <li> <p>In subsequent test runs, you can add the option <code>-L spidermonkey-known-failures-n.tests</code> to the above test suite run command to ignore these failing tests. This way, you can make sure your code changes haven't broken anything which was previously working.</p> </li>
</ul>
<p>{{ jsapi_todo("public-failures.txt should be documented here.") }}</p>
Revert to this revision