v8-structure

name	v8-structure
description	Maps the V8 dir/folder structure, component locations, and local documentation. Use when locating specific subsystems, mapping src/ code to docs/ design files, or understanding repository architecture.

V8 Folder Structure

Use this skill to understand the layout of the V8 repository and locate specific components.

Main Directories

• src/: The main source folder providing the implementation of the virtual machine. Key subdirectories include:
  • src/api/: Implements the V8 public C++ API, as declared in include/.
  • src/ast/: Defines the Abstract Syntax Tree (AST) used to represent parsed JavaScript, including nodes, scopes, and variables.
  • src/base/: Provides fundamental, low-level utilities, data structures, and a platform abstraction layer for the entire V8 project.
  • src/baseline/: Implements the Sparkplug baseline compiler, which generates machine code directly from bytecode for a fast performance boost.
  • src/bigint/: The implementation of BigInt operations.
  • src/builtins/: Implementation of JavaScript built-in functions (e.g., Array.prototype.map).
  • src/codegen/: Code generation, including direct machine code generation via macro assemblers, higher level codegen via CodeStubAssembler, definitions of machine code metadata like safepoint tables and source position tables, and compiler.cc which defines entry points into the compilers. This contains subdirectories for architecture specific implementations, which should be kept in sync with each other as much as possible.
  • src/common/: Common definitions and utilities.
  • src/compiler/: The TurboFan optimizing compiler, including the Turboshaft CFG compiler.
  • src/d8/: The d8 shell implementation, for running V8 in a CLI.
  • src/debug/: The debugger and debug protocol implementation.
  • src/deoptimizer/: The deoptimizer implementation, which translates optimized frames into unoptimized ones.
  • src/execution/: The definitions of the execution environment, including the Isolate, frame definitions, microtasks, stack guards, tiering, and on-stack argument handling.
  • src/handles/: The handle implementation for GC-safe object references.
  • src/heap/: The garbage collector and memory management code.
  • src/ic/: The Inline Caching implementation.
  • src/init/: The V8 initialization code.
  • src/inspector/: The inspector protocol implementation.
  • src/interpreter/: The Ignition bytecode compiler and interpreter.
  • src/json/: The JSON parser and serializer.
  • src/libplatform/: The platform abstraction layer, for task runners and worker threads.
  • src/logging/: The logging implementation.
  • src/maglev/: The Maglev mid-tier optimizing compiler.
  • src/numbers/: Implementations of various numeric operations.
  • src/objects/: The representation and behaviour of V8 internal and JavaScript objects.
  • src/parsing/: The parser and scanner implementation.
  • src/profiler/: The in-process profiler implementations, for heap snapshots, allocation tracking, and a sampling CPU profiler.
  • src/regexp/: The regular expression implementation. This contains subdirectories for architecture specific implementations, which should be kept in sync with each other as much as possible.
  • src/runtime/: C++ functions that can be called from JavaScript at runtime.
  • src/sandbox/: The implementation of the sandbox, which is a security feature that attempts to limit V8 memory operations to be within a single guarded virtual memory allocation, such that corruptions of objects within the sandbox cannot lead to corruption of objects outside of it.
  • src/snapshot/: The snapshot implementation, for both the startup snapshot (read-only, startup heap, and startup context), as well as the code-serializer, which generates code caches for caching of user script code.
  • src/strings/: Implementations of string helpers, such as predicates for characters, unicode processing, hashing and string building.
  • src/torque/: The Torque language implementation.
  • src/tracing/: The tracing implementation.
  • src/trap-handler/: Implementations of trap handlers.
  • src/wasm/: The WebAssembly implementation.
  • src/zone/: The implementation of a simple bump-pointer region-based zone allocator.
• test/: Folder containing most of the tests and testing code.
• include/: Folder containing all of V8's publicAPI that is used when V8 is embedded in other projects such as e.g. the Blink rendering engine.
• out/: Folder containing the results of a build. Usually organized in sub folders for the respective configurations.
• docs/: Contains V8 documentation, including high-level, cross-cutting concept guides at the root, and subsystem-specific directories.
  • Root Documentation: Documents cross-cutting concerns such as embedding (docs/embed.md), debugging (docs/gdb.md), profiling (docs/profile.md), security mitigations (docs/untrusted-code-mitigations.md), and building V8 (docs/build.md).
  • Subsystem Directories (often containing deep design docs):
    • docs/builtins/: V8 built-ins and CodeStubAssembler.
    • docs/codegen/: Code generation.
    • docs/compiler/: Compilers (Sparkplug, Maglev, TurboFan, Turboshaft).
    • docs/heap/: Memory management and Garbage Collector.
    • docs/interpreter/: Ignition interpreter.
    • docs/objects/: Object layout and Map representations.
    • docs/parsing/: JavaScript parsing and AST.
    • docs/regexp/: Regular expression engine.
    • docs/runtime/: Runtime functions and execution model.
    • docs/sandbox/: V8 Security Sandbox.
    • docs/security/: Security triaging and design principles.
    • docs/snapshot/: Snapshot and serialization.
    • docs/torque/: Torque language and builtins.
    • docs/wasm/: WebAssembly implementation.