Spidershim (modern refresh)

This repository experiments with building a SpiderMonkey embedder that exposes a V8-like API surface. The intention is to recreate what projects such as SpiderNode (also known as SpiderShim) provided in the past: the ability to run software written for V8 on top of Mozilla's SpiderMonkey engine.

Repository structure

.
├── spidershim        # modern SpiderMonkey proof-of-concept + shim sources
│   ├── build.sh
│   ├── include/v8.h
│   ├── main.cpp
│   └── src/v8.cc
├── examples          # V8 API samples runnable on either backend
│   ├── build.sh
│   ├── run.sh
│   ├── hello_world/main.cpp
│   └── v8_hello/     # V8 parity sample (kept to verify shimmed APIs)
├── legacy
│   └── spidershim-old # archived SpiderShim sources
└── AGENTS.md / README.md / ...

Active development code lives under spidershim/ and historical sources in legacy/, making it clearer where to iterate versus where to reference prior art. This refresh currently targets Mozilla's SpiderMonkey 140 (mozjs-140) and mirrors the V8 13.5 API surface.

Quick start

SpiderMonkey shim

1. Ensure you have SpiderMonkey 140 installed and set SPIDERMONKEY_PREFIX to the install prefix (defaults to /opt/homebrew/Cellar/spidermonkey/140.6.0).
   Adjust the include/library paths inside spidershim/build.sh if your installation lives elsewhere.

2. Build and run the demo:

   cd spidershim
   ./build.sh
   ./js_test

   You should see Result: Hello, SpiderShim! and Number API value: 42 as the V8-style sample drives the SpiderMonkey-backed shim (include/v8.h, src/v8.cc).
   Set SPIDERMONKEY_PREFIX before running build.sh if SpiderMonkey is installed elsewhere.

Static monolith (libv8_monolith.a)

Build a static archive that bundles the shim objects together with SpiderMonkey so other projects can link directly against the V8 headers exposed in spidershim/include:

cd spidershim
./build_monolith.sh

Outputs:

• spidershim/out/libv8_monolith.a (only if a static libmozjs-140.a is available).
• spidershim/out/libv8_shim.a (always). Use this with the SpiderMonkey dynamic library.

Linking:

• With static SpiderMonkey available: -Ispidershim/include -Lspidershim/out -lv8_monolith.
• With only the SpiderMonkey dylib (Homebrew default on macOS): -Ispidershim/include -Lspidershim/out -lv8_shim -L$SPIDERMONKEY_PREFIX/lib -lmozjs-140 plus any extra flags from pkg-config --libs mozjs-140.

If you need a fully static monolith on macOS, rebuild SpiderMonkey from source with static libraries enabled and point MOZJS_STATIC (or SPIDERMONKEY_PREFIX) at that build.

V8 reference example

1. Install V8 13.5 (or compatible) and update V8_PREFIX inside examples/build.sh (or export it) if necessary.

2. Build and run:

   cd examples
   ./build.sh v8 v8_hello
   ./run.sh v8 v8_hello

Use the V8 sample to compare behavior and verify that the shimmed API surface behaves just like the native V8 embedder.

Shared examples (shim + V8)

The examples/ directory hosts API samples that compile against both the SpiderShim V8 interface and a real V8 installation using the same source code.

cd examples
# Build for both backends (shim + real V8)
./build.sh both

# Run a specific backend (rebuilds as needed)
./run.sh shim
./run.sh v8

Override SPIDERMONKEY_PREFIX and V8_PREFIX if your local installations live somewhere else.

Test suite (gtest + CMake)

The tests/ directory contains a small GoogleTest harness that exercises whichever backend you point it at.
Prereqs: CMake ≥ 3.16, GoogleTest 1.17 (set GTEST_ROOT if it is installed in a non-default location), and either SpiderMonkey 140 or V8 13.5, depending on the backend (SPIDERMONKEY_PREFIX / V8_PREFIX).

cd tests
mkdir -p build
cd build

# SpiderShim backend (default)
cmake -DSPIDERSHIM_BACKEND=ON ..
cmake --build .
ctest

# Native V8 backend
cmake -DSPIDERSHIM_BACKEND=OFF ..
cmake --build .
ctest

Change SPIDERMONKEY_PREFIX, V8_PREFIX, or GTEST_ROOT via environment variables when the libraries are installed outside of their defaults.

Legacy sources

legacy/spidershim-old contains the previous SpiderShim implementation. Keep it untouched and reference it when porting behavior into the new embedder.

Goals and next steps

• Flesh out a compatibility layer that maps the SpiderMonkey APIs to V8 equivalents, taking cues from the legacy sources in legacy/spidershim-old.
• Incrementally port the previous SpiderShim behavior into the modern toolchain while keeping the SpiderMonkey embedder compiling and runnable.
• Keep the V8 sample healthy so regressions in the public API can be caught earlier.

Feel free to open issues or PRs with ideas, compatibility reports, or documentation improvements.