build.rst (8681B)
1 Building and testing SpiderMonkey 2 ================================= 3 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 7 though.** 8 9 * :ref:`Building Firefox On Linux` 10 * :ref:`Building Firefox On Windows` 11 * :ref:`Building Firefox On MacOS` 12 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. 16 17 These instructions assume you have a clone of `mozilla-unified` and are 18 interested in building the JS shell. 19 20 Developer (debug) build 21 ~~~~~~~~~~~~~~~~~~~~~~~ 22 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. 27 28 Setting up a MOZCONFIG 29 ----------------------- 30 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 34 have. 35 36 A basic ``MOZCONFIG`` file for doing a debug build, put into ``$HOME/mozconfigs/debug`` looks like this 37 38 .. code:: text 39 40 # Build only the JS shell 41 ac_add_options --enable-project=js 42 43 # Enable the debugging tools: Assertions, debug only code etc. 44 ac_add_options --enable-debug 45 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 49 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@ 53 54 To activate a particular ``MOZCONFIG``, set the environment variable: 55 56 .. code:: text 57 58 export MOZCONFIG=$HOME/mozconfigs/debug 59 60 Building 61 -------- 62 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, 65 to do your build: 66 67 .. code:: console 68 69 $ cd <path to mozilla-central> 70 $ ./mach build 71 72 .. note:: 73 74 If you are on Mac and baldrdash fails to compile with something similar to 75 76 :: 77 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 79 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 84 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 87 88 Until then, the following should help, 89 90 :: 91 92 open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pk 93 94 Once you have successfully built the shell, you can run it using ``mach run``. 95 96 Testing 97 ~~~~~~~ 98 99 Once built, you can then use ``mach`` to run the ``jit-tests``: 100 101 .. code:: console 102 103 $ ./mach jit-test 104 105 Similarly you can use also run ``jstests``. These include a local, 106 intermittently updated, copy of all `test262 <https://github.com/tc39/test262/>`_ 107 tests. 108 109 .. code:: console 110 111 $ ./mach jstests 112 113 See :doc:`Running Automated JavaScript Tests<test>` for more details. 114 115 Optimized Builds 116 ~~~~~~~~~~~~~~~~ 117 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: 121 122 .. code:: text 123 124 # Build only the JS shell 125 ac_add_options --enable-project=js 126 127 # Enable optimization for speed 128 ac_add_options --enable-optimize 129 130 # Disable debug checks to better match a release build of Firefox. 131 ac_add_options --disable-debug 132 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@ 136 137 SpiderMonkey on Android aarch64 138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 139 140 Building SpiderMonkey on Android 141 -------------------------------- 142 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 146 present, etc. 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: 150 151 .. code:: console 152 153 $ export PATH="$PATH:~/.mozbuild/android-sdk-linux/platform-tools" 154 155 - Create a typical `mozconfig` file for compiling SpiderMonkey, as outlined in 156 the :ref:`Setting up a MOZCONFIG` documentation, and include the following 157 line: 158 159 .. code:: console 160 161 $ ac_add_options --target=aarch64-linux-android 162 163 - Then compile as usual with `mach build` with this `MOZCONFIG` file. 164 165 The compiled shell can be installed to `/data/local/tmp` on the device 166 using `./mach install`. 167 168 Running jit-tests on Android 169 ---------------------------- 170 171 - Plug your Android device to the machine which compiled the shell for aarch64 172 as described above, or make sure it is on the same subnetwork as the host. It 173 should appear in the list of devices seen by `adb`: 174 175 .. code:: console 176 177 $ adb devices 178 179 This command should show you a device ID with the name of the device. If it 180 doesn't, make sure that you have enabled Developer options on your device, as 181 well as `enabled USB debugging on the device <https://developer.android.com/studio/debug/dev-options>`_. 182 183 - Run `mach jit-test --remote {JIT_TEST_ARGS}` with the android-aarch64 184 `MOZCONFIG` file. This will upload the JS shell and its dependencies to the 185 Android device, in a temporary directory (`/data/local/tmp/test_root/bin` as 186 of 2020-09-02). Then it will start running the jit-test suite. 187 188 Debugging jit-tests on Android 189 ------------------------------ 190 191 Debugging on Android uses the GDB remote debugging protocol, so we'll set up a 192 GDB server on the Android device, that is going to be controlled remotely by 193 the host machine. 194 195 - Upload the `gdbserver` precompiled binary from the NDK from the host machine 196 to the Android device, using this command on the host: 197 198 .. code:: console 199 200 $ adb push \ 201 ~/.mozbuild/android-ndk-r23c/prebuilt/android-arm64/gdbserver/gdbserver \ 202 /data/local/tmp/test_root/bin 203 204 - Make sure that the `ncurses5` library is installed on the host. On 205 Debian-like distros, this can be done with `sudo apt install -y libncurses5`. 206 207 - Set up port forwarding for the GDB port, from the Android device to the host, 208 so we can connect to a local port from the host, without needing to find what 209 the IP address of the Android device is: 210 211 .. code:: console 212 213 $ adb forward tcp:5039 tcp:5039 214 215 - Start `gdbserver` on the phone, passing the JS shell command line arguments 216 to gdbserver: 217 218 .. code:: console 219 220 $ 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 222 .. note:: 223 224 Note this will make the gdbserver listen on the 5039 port on all the 225 network interfaces. In particular, the gdbserver will be reachable from 226 every other devices on the same networks as your phone. Since the gdbserver 227 protocol is unsafe, it is strongly recommended to double-check that the 228 gdbserver process has properly terminated when exiting the shell, and to 229 not run it more than needed. 230 231 .. note:: 232 233 You can find the full command line that the `jit_test.py` script is 234 using by giving it the `-s` parameter, and copy/paste it as the final 235 argument to the gdbserver invocation above. 236 237 - On the host, start the precompiled NDK version of GDB that matches your host 238 architecture, passing it the path to the shell compiled with `mach` above: 239 240 .. code:: console 241 242 $ ~/.mozbuild/android-ndk-r23c/prebuilt/linux-x86_64/bin/gdb /path/to/objdir-aarch64-linux-android/dist/bin/js 243 244 - Then connect remotely to the GDB server that's listening on the Android 245 device: 246 247 .. code:: console 248 249 $(gdb) target remote :5039 250 $(gdb) continue