JS engine modularization

	THIS PAGE IS OBSOLETE
	This article is in parts, or in its entirety, outdated. Hence, the information presented on this page may be incorrect, and should be treated with due caution. Visit SpiderMonkey.dev for more up to date information.

The goal of this project is to incrementally tease apart JS engine source code into separate "modules" so that:

• it is easier to understand a module in isolation
• it is easier to get a high-level breakdown of SM code
• module dependencies are DAG-y as opposed to clique-y or spaghetti (as it is now)

The plan isn't to do anything radical to simulate "modules" in C++. Rather, we can just say a "module" X is a triple: X.cpp, X.h, X-inl.h. Here, X.h acts as the "module interface" to the rest of the code-base. X-inl.h contains inline files that are pulled out of X.h so that:

• X.h is more readable as a whole and
• we can reduce average translation unit size (which right now is hard because of the dependency clique).

The granularity of modules isn't fixed; the goal is to try to have a module encapsulate a coherent hunk of interdependent logic and implementation details. This may be a single type (e.g., js::Value) or a set of related types (the stack types in vm/Stack.h).

Additionally, we can use directories to group related modules. Again, this is primarily useful to assist newcomers in developing a hierarchical understanding of the code.

This is an incremental project. As developers work on a hunk of code, things tend to be rewritten/refactored into the new SpiderMonkey C++ style. Reviewers should require new code or major alterations to follow the new style unless it would be impractical.

Plan of Record

A meta bug tracks bugs for individual pieces. This document serves to collect consensus of the direction we'd like things to head.

Preliminary directory/module structure:

• js/src
  • JSAPI implementation (jsapi.cpp, js::Invoke, js::Execute)
  • Interpreter (ideally, if we had maximum code reuse, this would be just the one function calling lots of module (inline) functions)
  • Grotty bits and bobs that don't make sense to modularize
• js/src/ds
  • LifoAlloc, Vector, HashMap/Set, ...
• js/src/jit
• js/src/vm: central, execution-mode-independent data structures: types and operations
  • Stack: execution stack (done)
  • Value: JS value representation
  • String: JS string value representation
  • Perhaps these next two need short distinctive names:
    • Low-level object representation: property tree, shapes, and raw object storage
    • General high-level objects: high level generic set/get/call operations respecting JS semantics
  • Class-specific high-level objects: statically typed interfaces for native objects of a given class
    • Global: the global object
    • Arguments: object accessed through 'arguments' keyword
    • Function: (object) perhaps also contains closely-related JSFunctino/JSScript/Bindings?
• js/src/gc: garbage collector data structures and algorithms
• js/src/frontend: scanning, parsing, and emitting
• js/src/builtin: builtins specified by JS language spec (e.g., String, Array.prototype.sort)
  • String
  • Number
  • Boolean
  • Array
  • Date
  • Math
  • ...
• js/src/devtools: code, config files and scripts that are generally useful to SM developers but not part of the official build