JavaScript:SpiderMonkey:Directories

This page describes how we want to organize the SpiderMonkey source code, in subdirectories under js/src.

The reason we have this document is that currently it's not organized this way. It's a bit of a mess just now.

Directories under js/src

The directories under js/src should be like this:

• gc - Heap allocation and garbage collection.

• vm - JS value representation and code execution. Files that definitely belong there:

       Stack.*, Script.*, Interpreter.*, Opcodes.h, PIC.*
       String.*, Symbol.*, Atom.*, Value.cpp, Id.cpp
       Shape.*, Object.*, ShapedObject.*, NativeObject.*, Shape.*, ObjectGroup.*, TypeInference.*
       Context.*, Runtime.*, Realm.*, GlobalObject.*

The vm directory will also hold a bunch of stuff that is not so "core" but still mainly vm-related, like UbiNode.cpp, SelfHosting.*, TemplateRegistry.h, Xdr.*, maybe StructuredClone.*

• builtin - JS-facing stuff. Lots of JSNatives and Classes; self-hosted code. Ideally, each file in here is fairly peripheral to the core business of the JS engine, but it will remain common for the JITs to need to see JSNative function pointers, and for builtins to need access to non-public GC primitives, etc. etc.

• jit - The JITs.

• frontend - Compiling JS code to bytecode.

• ds - Data structures.

• shell - The repl.

• editline, perf, vtune - It's OK that we have extra directories for these bits and pieces.

• irregexp - Vendored libraries are OK too.

• util - New junk-drawer directory, read on for rationale.

Focusing the vm directory on VM stuff

There's a lot of great stuff in js/src/vm, like JSONPrinter.h and Time.h, that is VM-related in no way whatsoever. It seems we have already decided to have a util directory; maybe then we should call it js/src/util and reserve js/src/vm for the actual VM.

We should move most of the Object subclasses out of vm. There's a spectrum of how silly it is to have them in there:

Very Silly Indeed

• DateObject -> builtin/, times a million
• RegExpObject -> builtin/

On Consideration, Pretty Silly

• BooleanObject, NumberObject, StringObject -> builtin/
• ErrorObject -> builtin/

Not Quite So Silly

• ArrayObject, TypedArrayObject, SharedArrayObject: We would love to move this to builtin/ eventually. I'm not sure we're ready. Certainly there is no clear abstraction boundary.
• Function, AsyncFunction: The same. (I moved Function in here myself in this patch stack...)

Barely Silly

• ArgumentsObject and GlobalObject: Very tied to the interpreter; we can leave them in vm.
• EnvironmentObject: Even more so.

Everything with JSPropertySpecs would ideally live in js/src/builtin.