summaryrefslogtreecommitdiffstats
path: root/js/src/doc/build.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 19:33:14 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 19:33:14 +0000
commit36d22d82aa202bb199967e9512281e9a53db42c9 (patch)
tree105e8c98ddea1c1e4784a60a5a6410fa416be2de /js/src/doc/build.rst
parentInitial commit. (diff)
downloadfirefox-esr-upstream.tar.xz
firefox-esr-upstream.zip
Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--js/src/doc/build.rst247
1 files changed, 247 insertions, 0 deletions
diff --git a/js/src/doc/build.rst b/js/src/doc/build.rst
new file mode 100644
index 0000000000..4d35343e61
--- /dev/null
+++ b/js/src/doc/build.rst
@@ -0,0 +1,247 @@
+Building and testing SpiderMonkey
+=================================
+
+**The first step is to run our “bootstrap” script to help ensure you have the
+right build tools for your operating system. This will also help you get a copy
+of the source code. You do not need to run the “mach build” command just yet
+though.**
+
+* :ref:`Building Firefox On Linux`
+* :ref:`Building Firefox On Windows`
+* :ref:`Building Firefox On MacOS`
+
+This guide shows you how to build SpiderMonkey using ``mach``, which is
+Mozilla's multipurpose build tool. This replaces old guides that advised
+running the "configure" script directly.
+
+These instructions assume you have a clone of `mozilla-unified` and are
+interested in building the JS shell.
+
+Developer (debug) 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. We'll start by
+covering how to create a debug build.
+
+Setting up a MOZCONFIG
+-----------------------
+
+First, we will create a ``MOZCONFIG`` file. This file describes the characteristics
+of the build you'd like `mach` to create. Since it is likely you will have a
+couple of ``MOZCONFIGs``, a directory like ``$HOME/mozconfigs`` is a useful thing to
+have.
+
+A basic ``MOZCONFIG`` file for doing a debug build, put into ``$HOME/mozconfigs/debug`` looks like this
+
+.. code::
+
+ # Build only the JS shell
+ ac_add_options --enable-project=js
+
+ # Enable the debugging tools: Assertions, debug only code etc.
+ ac_add_options --enable-debug
+
+ # Enable optimizations as well so that the test suite runs much faster. If
+ # you are having trouble using a debugger, you should disable optimization.
+ ac_add_options --enable-optimize
+
+ # Use a dedicated objdir for SpiderMonkey debug builds to avoid
+ # conflicting with Firefox build with default configuration.
+ mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-debug-@CONFIG_GUESS@
+
+To activate a particular ``MOZCONFIG``, set the environment variable:
+
+.. code::
+
+ export MOZCONFIG=$HOME/mozconfigs/debug
+
+Building
+--------
+
+Once you have activated a ``MOZCONFIG`` by setting the environment variable
+you can then ask ``mach``, located in the top directory of your checkout,
+to do your build:
+
+.. code::
+
+ $ cd <path to mozilla-central>
+ $ ./mach build
+
+.. note::
+
+ **Note**: If you are on Mac and baldrdash fails to compile with something similar to
+
+ ::
+
+ /usr/local/Cellar/llvm/7.0.1/lib/clang/7.0.1/include/inttypes.h:30:15: fatal error: 'inttypes.h' file not found
+
+ This is because, starting from Mojave, headers are no longer
+ installed in ``/usr/include``. Refer the `release
+ notes <https://developer.apple.com/documentation/xcode_release_notes/xcode_10_release_notes>`__  under
+ Command Line Tools -> New Features
+
+ The release notes also states that this compatibility package will no longer be provided in the near
+ future, so the build system on macOS will have to be adapted to look for headers in the SDK
+
+ Until then, the following should help,
+
+ ::
+
+ open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pk
+
+Once you have successfully built the shell, you can run it using ``mach run``.
+
+Testing
+~~~~~~~
+
+Once built, you can then use ``mach`` to run the ``jit-tests``:
+
+.. code::
+
+ $ ./mach jit-test
+
+Similarly you can use also run ``jstests``. These include a local,
+intermittently updated, copy of all `test262 <https://github.com/tc39/test262/>`_
+tests.
+
+.. code::
+
+ $ ./mach jstests
+
+See :doc:`Running Automated JavaScript Tests<test>` for more details.
+
+Optimized Builds
+~~~~~~~~~~~~~~~~
+
+To switch to an optimized build, such as for performance testing, one need only
+have an optimized build ``MOZCONFIG``, and then activate it. An example
+``$HOME/mozconfigs/optimized`` ``MOZCONFIG`` looks like this:
+
+.. code::
+
+ # Build only the JS shell
+ ac_add_options --enable-project=js
+
+ # Enable optimization for speed
+ ac_add_options --enable-optimize
+
+ # Disable debug checks to better match a release build of Firefox.
+ ac_add_options --disable-debug
+
+ # Use a separate objdir for optimized builds to allow easy
+ # switching between optimized and debug builds while developing.
+ mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-opt-@CONFIG_GUESS@
+
+SpiderMonkey on Android aarch64
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Building SpiderMonkey on Android
+--------------------------------
+
+- First, run `mach bootstrap` and answer `GeckoView/Firefox for Android` when
+ asked which project you want to build. This will download a recent Android
+ NDK, make sure all the build dependencies required to compile on Android are
+ present, etc.
+- Make sure that `$MOZBUILD_DIR/android-sdk-linux/platform-tools` is present in
+ your `PATH` environment. You can do this by running the following line in a
+ shell, or adding it to a shell profile init file:
+
+.. code::
+
+ $ export PATH="$PATH:~/.mozbuild/android-sdk-linux/platform-tools"
+
+- Create a typical `mozconfig` file for compiling SpiderMonkey, as outlined in
+ the :ref:`Setting up a MOZCONFIG` documentation, and include the following
+ line:
+
+.. code::
+
+ ac_add_options --target=aarch64-linux-android
+
+- Then compile as usual with `mach build` with this `MOZCONFIG` file.
+
+Running jit-tests on Android
+----------------------------
+
+- Plug your Android device to the machine which compiled the shell for aarch64
+ as described above, or make sure it is on the same subnetwork as the host. It
+ should appear in the list of devices seen by `adb`:
+
+.. code::
+
+ adb devices
+
+This command should show you a device ID with the name of the device. If it
+doesn't, make sure that you have enabled Developer options on your device, as
+well as `enabled USB debugging on the device <https://developer.android.com/studio/debug/dev-options>`_.
+
+- Run `mach jit-test --remote {JIT_TEST_ARGS}` with the android-aarch64
+ `MOZCONFIG` file. This will upload the JS shell and its dependencies to the
+ Android device, in a temporary directory (`/data/local/tmp/test_root/bin` as
+ of 2020-09-02). Then it will start running the jit-test suite.
+
+Debugging jit-tests on Android
+------------------------------
+
+Debugging on Android uses the GDB remote debugging protocol, so we'll set up a
+GDB server on the Android device, that is going to be controlled remotely by
+the host machine.
+
+- Upload the `gdbserver` precompiled binary from the NDK from the host machine
+ to the Android device, using this command on the host:
+
+.. code::
+
+ adb push \
+ ~/.mozbuild/android-ndk-r23c/prebuilt/android-arm64/gdbserver/gdbserver \
+ /data/local/tmp/test_root/bin
+
+- Make sure that the `ncurses5` library is installed on the host. On
+ Debian-like distros, this can be done with `sudo apt install -y libncurses5`.
+
+- Set up port forwarding for the GDB port, from the Android device to the host,
+ so we can connect to a local port from the host, without needing to find what
+ the IP address of the Android device is:
+
+.. code::
+
+ adb forward tcp:5039 tcp:5039
+
+- Start `gdbserver` on the phone, passing the JS shell command line arguments
+ to gdbserver:
+
+.. code::
+
+ 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
+
+.. note::
+
+ Note this will make the gdbserver listen on the 5039 port on all the
+ network interfaces. In particular, the gdbserver will be reachable from
+ every other devices on the same networks as your phone. Since the gdbserver
+ protocol is unsafe, it is strongly recommended to double-check that the
+ gdbserver process has properly terminated when exiting the shell, and to
+ not run it more than needed.
+
+.. note::
+
+ You can find the full command line that the `jit_test.py` script is
+ using by giving it the `-s` parameter, and copy/paste it as the final
+ argument to the gdbserver invocation above.
+
+- On the host, start the precompiled NDK version of GDB that matches your host
+ architecture, passing it the path to the shell compiled with `mach` above:
+
+.. code::
+
+ ~/.mozbuild/android-ndk-r23c/prebuilt/linux-x86_64/bin/gdb /path/to/objdir-aarch64-linux-android/dist/bin/js
+
+- Then connect remotely to the GDB server that's listening on the Android
+ device:
+
+.. code::
+
+ (gdb) target remote :5039
+ (gdb) continue