1 Building and testing SpiderMonkey
2 =================================
4 **The first step is to run our “bootstrap” script to help ensure you have the
5 right build tools for your operating system. This will also help you get a copy
6 of the source code. You do not need to run the “mach build” command just yet
9 * :ref:`Building Firefox On Linux`
10 * :ref:`Building Firefox On Windows`
11 * :ref:`Building Firefox On MacOS`
13 This guide shows you how to build SpiderMonkey using ``mach``, which is
14 Mozilla's multipurpose build tool. This replaces old guides that advised
15 running the "configure" script directly.
17 These instructions assume you have a clone of `mozilla-unified` and are
18 interested in building the JS shell.
20 Developer (debug) build
21 ~~~~~~~~~~~~~~~~~~~~~~~
23 For developing and debugging SpiderMonkey itself, it is best to have
24 both a debug build (for everyday debugging) and an optimized build (for
25 performance testing), in separate build directories. We'll start by
26 covering how to create a debug build.
28 Setting up a MOZCONFIG
29 -----------------------
31 First, we will create a ``MOZCONFIG`` file. This file describes the characteristics
32 of the build you'd like `mach` to create. Since it is likely you will have a
33 couple of ``MOZCONFIGs``, a directory like ``$HOME/mozconfigs`` is a useful thing to
36 A basic ``MOZCONFIG`` file for doing a debug build, put into ``$HOME/mozconfigs/debug`` looks like this
40 # Build only the JS shell
41 ac_add_options --enable-project=js
43 # Enable the debugging tools: Assertions, debug only code etc.
44 ac_add_options --enable-debug
46 # Enable optimizations as well so that the test suite runs much faster. If
47 # you are having trouble using a debugger, you should disable optimization.
48 ac_add_options --enable-optimize
50 # Use a dedicated objdir for SpiderMonkey debug builds to avoid
51 # conflicting with Firefox build with default configuration.
52 mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-debug-@CONFIG_GUESS@
54 To activate a particular ``MOZCONFIG``, set the environment variable:
58 export MOZCONFIG=$HOME/mozconfigs/debug
63 Once you have activated a ``MOZCONFIG`` by setting the environment variable
64 you can then ask ``mach``, located in the top directory of your checkout,
69 $ cd <path to mozilla-central>
74 If you are on Mac and baldrdash fails to compile with something similar to
78 /usr/local/Cellar/llvm/7.0.1/lib/clang/7.0.1/include/inttypes.h:30:15: fatal error: 'inttypes.h' file not found
80 This is because, starting from Mojave, headers are no longer
81 installed in ``/usr/include``. Refer the `release
82 notes <https://developer.apple.com/documentation/xcode_release_notes/xcode_10_release_notes>`__ under
83 Command Line Tools -> New Features
85 The release notes also states that this compatibility package will no longer be provided in the near
86 future, so the build system on macOS will have to be adapted to look for headers in the SDK
88 Until then, the following should help,
92 open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pk
94 Once you have successfully built the shell, you can run it using ``mach run``.
99 Once built, you can then use ``mach`` to run the ``jit-tests``:
105 Similarly you can use also run ``jstests``. These include a local,
106 intermittently updated, copy of all `test262 <https://github.com/tc39/test262/>`_
113 See :doc:`Running Automated JavaScript Tests<test>` for more details.
118 To switch to an optimized build, such as for performance testing, one need only
119 have an optimized build ``MOZCONFIG``, and then activate it. An example
120 ``$HOME/mozconfigs/optimized`` ``MOZCONFIG`` looks like this:
124 # Build only the JS shell
125 ac_add_options --enable-project=js
127 # Enable optimization for speed
128 ac_add_options --enable-optimize
130 # Disable debug checks to better match a release build of Firefox.
131 ac_add_options --disable-debug
133 # Use a separate objdir for optimized builds to allow easy
134 # switching between optimized and debug builds while developing.
135 mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-opt-@CONFIG_GUESS@
137 SpiderMonkey on Android aarch64
138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
140 Building SpiderMonkey on Android
141 --------------------------------
143 - First, run `mach bootstrap` and answer `GeckoView/Firefox for Android` when
144 asked which project you want to build. This will download a recent Android
145 NDK, make sure all the build dependencies required to compile on Android are
147 - Make sure that `$MOZBUILD_DIR/android-sdk-linux/platform-tools` is present in
148 your `PATH` environment. You can do this by running the following line in a
149 shell, or adding it to a shell profile init file:
153 $ export PATH="$PATH:~/.mozbuild/android-sdk-linux/platform-tools"
155 - Create a typical `mozconfig` file for compiling SpiderMonkey, as outlined in
156 the :ref:`Setting up a MOZCONFIG` documentation, and include the following
161 $ ac_add_options --target=aarch64-linux-android
163 - Then compile as usual with `mach build` with this `MOZCONFIG` file.
165 Running jit-tests on Android
166 ----------------------------
168 - Plug your Android device to the machine which compiled the shell for aarch64
169 as described above, or make sure it is on the same subnetwork as the host. It
170 should appear in the list of devices seen by `adb`:
176 This command should show you a device ID with the name of the device. If it
177 doesn't, make sure that you have enabled Developer options on your device, as
178 well as `enabled USB debugging on the device <https://developer.android.com/studio/debug/dev-options>`_.
180 - Run `mach jit-test --remote {JIT_TEST_ARGS}` with the android-aarch64
181 `MOZCONFIG` file. This will upload the JS shell and its dependencies to the
182 Android device, in a temporary directory (`/data/local/tmp/test_root/bin` as
183 of 2020-09-02). Then it will start running the jit-test suite.
185 Debugging jit-tests on Android
186 ------------------------------
188 Debugging on Android uses the GDB remote debugging protocol, so we'll set up a
189 GDB server on the Android device, that is going to be controlled remotely by
192 - Upload the `gdbserver` precompiled binary from the NDK from the host machine
193 to the Android device, using this command on the host:
198 ~/.mozbuild/android-ndk-r23c/prebuilt/android-arm64/gdbserver/gdbserver \
199 /data/local/tmp/test_root/bin
201 - Make sure that the `ncurses5` library is installed on the host. On
202 Debian-like distros, this can be done with `sudo apt install -y libncurses5`.
204 - Set up port forwarding for the GDB port, from the Android device to the host,
205 so we can connect to a local port from the host, without needing to find what
206 the IP address of the Android device is:
210 $ adb forward tcp:5039 tcp:5039
212 - Start `gdbserver` on the phone, passing the JS shell command line arguments
217 $ adb shell export LD_LIBRARY_PATH=/data/local/tmp/test_root/bin '&&' /data/local/tmp/test_root/bin/gdbserver :5039 /data/local/tmp/test_root/bin/js /path/to/test.js
221 Note this will make the gdbserver listen on the 5039 port on all the
222 network interfaces. In particular, the gdbserver will be reachable from
223 every other devices on the same networks as your phone. Since the gdbserver
224 protocol is unsafe, it is strongly recommended to double-check that the
225 gdbserver process has properly terminated when exiting the shell, and to
226 not run it more than needed.
230 You can find the full command line that the `jit_test.py` script is
231 using by giving it the `-s` parameter, and copy/paste it as the final
232 argument to the gdbserver invocation above.
234 - On the host, start the precompiled NDK version of GDB that matches your host
235 architecture, passing it the path to the shell compiled with `mach` above:
239 $ ~/.mozbuild/android-ndk-r23c/prebuilt/linux-x86_64/bin/gdb /path/to/objdir-aarch64-linux-android/dist/bin/js
241 - Then connect remotely to the GDB server that's listening on the Android
246 $(gdb) target remote :5039