Source code
Revision control
Copy as Markdown
Other Tools
# AGENTS.md
This directory is **SpiderMonkey**, the JavaScript engine inside the
Firefox/Gecko monorepo in the parent directly. Project-wide instructions live
in `../AGENTS.md` (referenced from `../CLAUDE.md`). Notes below cover what is
specific to `js/`.
## Test workflow
Tests are run from the `js` test shell, not the browser. There are three suites:
- **jit-test** (`src/jit-test/`) — JIT, GC, and engine internals, run with
`mach jit-test`.
- **jsapi-tests** (`src/jsapi-tests/`) — C++ tests of the embedding API, run with
`mach jsapi-tests`.
- **jstests** (`src/tests/`) — test262 + non262, run with `mach jstests`.
Run `python src/jit-test/jit_test.py -h` directly to see all jit-test flags
(gdb wrapper, --tbpl, --jitflags, etc.).
## High-level architecture
SpiderMonkey is organized along the pipeline a script flows through:
- **`src/frontend/`** — parser and bytecode emitter (BytecodeEmitter,
ParseNode).
- **`src/vm/`** — the runtime: interpreter, bytecode definitions,
JSContext/JSRuntime, Realm/Compartment/Zone, Shape/NativeObject, Stack,
GlobalObject, error handling.
- **`src/builtin/`** — self-hosted JS implementations of language builtins
(`.js` files compiled into the shell) and their C++ backing (Array,
String, Promise, AsyncIteration, etc.).
- **`src/jit/`** — tiered JITs and inline caches. The pipeline is Interpreter
-> Baseline Interpreter -> Baseline JIT -> Ion -> Warp. CacheIR is the
shared IC representation consumed by all tiers (BaselineCacheIRCompiler,
IonCacheIRCompiler, WarpCacheIRTranspiler). Backends live under
`jit/{x86-shared,arm,arm64,loong64,mips-shared,riscv64,wasm32}`.
- **`src/gc/`** — generational, incremental, compacting GC. Nursery + tenured
heap of Arenas/Chunks; `Allocator.{h,cpp}` is the allocation entry point;
`BufferAllocator.{h,cpp}` is the malloc-replacement used for GC-tracked
off-cell buffers; `Marking.cpp` is the mark phase; `Tracer.{h,cpp}` does
generic edge traversal; `Zone.{h,cpp}` and `Compartment.{h,cpp}` are the
unit-of-GC and unit-of-isolation respectively.
- **`src/wasm/`** — WebAssembly compiler/runtime, separate from the JS JITs
but uses Ion and the macro assembler.
- **`src/shell/`** — `js` command-line shell (`js.cpp`). Test harnesses use
this.
- **`public/` + `jsapi.h`** — public C++ embedding API. `public/friend/` +
`jsfriendapi.h` is the semi-public surface for Gecko.
- **`src/debugger/`**, **`src/proxy/`**, **`src/ds/`** (datastructures),
`src/util/`**, **`src/threading/`** — supporting subsystems.
- **`src/irregexp/`** — V8's regexp engine, imported.
GC allocated cell types inherit from `gc::Cell` / `gc::TenuredCell`. When
adding GC-managed memory, prefer using the GC's buffer allocator over raw
malloc.
## Documentation
In-tree docs are under `src/doc/`:
- `gc.rst` — GC architecture
- `build.rst` — build system details
- `test.rst` — test infrastructure
- `hacking_tips.md` — practical engine-hacking notes
- `MIR-optimizations/` — Ion MIR optimization reference
- `bytecode_checklist.md`, `feature_checklist.md` — checklists when adding
bytecodes or features
Build the rendered docs with `./mach doc --no-serve --no-open` from the repo
root.
Important in-source documentation comment blocks are tagged with '[SMDOC]'.
## Searching
`searchfox-cli` (see `../AGENTS.md`) indexes the whole tree, including this
directory. Restrict path searches with `--path 'js/...'` to stay inside the
engine.