CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

V8 uses GN + Ninja build system. The primary development tool is tools/dev/gm.py:

# Quick build and test
tools/dev/gm.py x64.release         # Build release mode
tools/dev/gm.py x64.debug           # Build debug mode
tools/dev/gm.py x64.release.check   # Build and run tests

# Direct build commands
gn gen out/x64.release --args='is_debug=false target_cpu="x64"'
ninja -C out/x64.release d8

# Common build configurations
gn gen out/x64.debug --args='is_debug=true v8_enable_verify_heap=true'
gn gen out/arm64.release --args='is_debug=false target_cpu="arm64"'

Running Tests

# Run all tests
tools/run-tests.py --outdir out/x64.release

# Run specific test suites
tools/run-tests.py --outdir out/x64.release mjsunit cctest unittests

# Run specific test patterns
tools/run-tests.py --outdir out/x64.release mjsunit/array-*

# Run single test file
tools/run-tests.py --outdir out/x64.release test/mjsunit/specific-test.js

# Use gm.py for automatic build detection
tools/dev/gm.py x64.release mjsunit/array-*

Test files can specify V8 flags via comments: // Flags: --allow-natives-syntax

Code Architecture

Execution Pipeline

Parser → Ignition (interpreter) → Sparkplug (baseline) → Maglev (mid-tier) → TurboFan (optimizing)

Key Source Directories

• src/execution/ - Isolates, frames, stack management
• src/interpreter/ - Ignition bytecode interpreter
• src/compiler/ - TurboFan optimizing compiler
• src/maglev/ - Maglev mid-tier compiler
• src/heap/ - Garbage collector and memory management
• src/objects/ - V8 object system
• src/builtins/ - JavaScript built-in implementations
• src/wasm/ - WebAssembly implementation
• src/codegen/{arch}/ - Architecture-specific code generation

Platform Support

Architecture-specific code in src/codegen/ subdirectories:

• x64, ia32, arm, arm64, riscv32, riscv64, ppc64, s390x, loong64, mips64

Testing Structure

• test/mjsunit/ - Main JavaScript unit tests
• test/cctest/ - C++ unit tests
• test/unittests/ - Isolated unit tests
• test/inspector/ - DevTools protocol tests
• test/wasm/ - WebAssembly tests

Development Workflows

Common Debug Flags

• --allow-natives-syntax - Enable test/debug intrinsics
• --trace-gc - Trace garbage collection
• --print-opt-code - Print optimized code
• --trace-deopt - Trace deoptimizations
• --verify-heap - Enable heap verification

Debugging with d8

# Run d8 shell
out/x64.release/d8

# Run script with debugging
out/x64.debug/d8 --trace-gc --verify-heap script.js

Code Style

Follows Google C++ Style Guide. Check style with:

tools/cpplint.py src/your-file.cc

Important Concepts

Memory Management

• Handles: Use Local, Persistent, or Global handles for GC-safe object references
• Heap Spaces: Young generation, old generation, large object space
• GC: Generational, concurrent, and incremental collection

V8 Sandbox

Security feature that isolates V8's heap. Enable with v8_enable_sandbox=true in build args.

Object Layout

V8 objects defined in src/objects/. Key classes:

• HeapObject - Base for all heap-allocated objects
• JSObject - JavaScript objects
• Map - Hidden class describing object layout