ContextQMD
Back to V8

Gemini Workspace for V8

agents/prompts/common.md

15.0.1012.1 KB
Original Source

Gemini Workspace for V8

This is the workspace configuration for V8 when using Gemini.

Documentation can be found at https://v8.dev/docs.

Key Commands

  • Build (Debug): tools/dev/gm.py quiet x64.debug tests
  • Build (Optimized Debug): tools/dev/gm.py quiet x64.optdebug tests
  • Build (Release): tools/dev/gm.py quiet x64.release tests
  • Run All Tests: tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug
  • Run C++ Tests: tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug cctest unittests
  • Run JavaScript Tests: tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug mjsunit
  • Format Code: git cl format

Some hints:

  • You are an expert C++ developer.
  • V8 is shipped to users and running untrusted code; make sure that the code is absolutely correct and bug-free as correctness bugs usually lead to security issues for end users.
  • V8 is providing support for running JavaScript and WebAssembly on the web. As such, it is critical to aim for best possible performance when optimizing V8.

Folder structure

  • 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/asmjs/: Contains V8's Asm.js pipeline, which compiles the Asm.js subset of JavaScript into WebAssembly.
    • 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.

Building

The full documentation for building using GN can be found at https://v8.dev/docs/build-gn.

Once the initial dependencies are installed, V8 can be built using gm.py, which is a wrapper around GN and Ninja.

bash
# List all available build configurations and targets
tools/dev/gm.py

# Build the d8 shell for x64 in release mode
tools/dev/gm.py quiet x64.release

# Build d8 for x64 in debug mode
tools/dev/gm.py quiet x64.debug
  • release: Optimized for performance, with debug information stripped. Use for benchmarking.
  • debug: Contains full debug information and enables assertions. Slower, but essential for debugging.
  • optdebug: A compromise with optimizations enabled and debug information included. Good for general development.
  • sync:
    • Use --sync to run gclient sync -D before building.
    • Use --sync=force to run gclient sync -D --force --reset before building.

Make sure to pass the quiet keyword unless told to otherwise, so that you don't waste tokens on compilation progress. Errors will still be reported.

Debugging

For debugging, it is recommended to use a debug or optdebug build. You can run d8 with GDB or LLDB for native code debugging.

bash
# Example of running d8 with gdb
gdb --args out/x64.debug/d8 --my-flag my-script.js

V8 also provides a rich set of flags for diagnostics. Some of the most common ones are:

  • --trace-opt: Log optimized functions.
  • --trace-deopt: Log when and why functions are deoptimized.
  • --trace-gc: Log garbage collection events.
  • --allow-natives-syntax: Enables calling of internal V8 functions (e.g. %OptimizeFunctionOnNextCall(f)) from JavaScript for testing purposes.

A comprehensive list of all flags can be found by running out/x64.debug/d8 --help. Most V8 flags are in flag-definitions.h; flags specific to the d8 shell are located in src/d8/d8.cc within the Shell::SetOptions function.

When debugging issues in Torque code, it is often useful to inspect the generated C++ files in out/<build-config>/gen/torque-generated/. This allows you to see the low-level CodeStubAssembler code that is actually being executed.

Testing

The primary script for running tests is tools/run-tests.py. You specify the build output directory and the tests you want to run. Key test suites include:

  • unittests: C++ unit tests for V8's internal components.
  • cctest: Another, older format for C++ unit tests (deprecated, in the process of being moved to unittests).
  • mjsunit: JavaScript-based tests for JavaScript language features and builtins.
bash
# Run all standard tests for the x64.optdebug build
tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug

# Run a specific test suite (e.g., cctest)
tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug cctest

# Run a specific test file
tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug cctest/test-heap

It's important to pass --progress dots so that there is minimal progress reporting, to avoid cluttering the output.

If there are any failing tests, they will be reported along their stderr and a command to reproduce them e.g.

=== mjsunit/maglev/regress-429656023 ===
--- stderr ---
#
# Fatal error in ../../src/heap/local-factory.h, line 41
# unreachable code
#
#
#
...stack trace...
Received signal 6
Command: out/x64.optdebug/d8 --test test/mjsunit/mjsunit.js test/mjsunit/maglev/regress-429656023.js --random-seed=-190258694 --nohard-abort --verify-heap --allow-natives-syntax

You can retry the test either by running the test name with tools/run-tests.py, e.g. tools/run-tests.py --progress dots --outdir=out/x64.optdebug mjsunit/maglev/regress-429656023, or by running the command directly. When running the command directly, you can add additional flags to help debug the issue, and you can try running a different build (e.g. running a debug build if a release build fails).

The full testing documentation is at https://v8.dev/docs/test.

Coding and Committing

  • Always follow the style conventions used in code surrounding your changes.
  • Otherwise, follow Chromium's C++ style guide.
  • Use git cl format to automatically format your changes.

Commit Messages

Commit messages should follow the convention described at https:/v8.dev/docs/contribute#commit-messages. A typical format is:

[component]: Short description of the change

Longer description explaining the "why" of the change, not just
the "what". Wrap lines at 72 characters.

Bug: 123456
  • The component is the area of the codebase (e.g., compiler, runtime, api).
  • The Bug: line is important for linking to issues in the tracker at https://crbug.com/

Common Pitfalls & Best Practices

  • Always format before committing: Run git cl format before creating a commit to ensure your code adheres to the style guide.
  • Do not edit generated files: Files in out/ are generated by the build process. Edits should be made to the source files (e.g., .tq files for Torque, .pdl for protocol definitions).
  • Match test configuration to build: Ensure you are running tests against the correct build type (e.g., run mjsunit from out/x64.debug if you built x64.debug).
  • Check surrounding code for conventions: Before adding new code, always study the existing patterns, naming conventions, and architectural choices in the file and directory you are working in.
  • Avoid changing unrelated code: Keep diffs small by only changing the code you intended to change. Nearby code should not be cleaned up while making a change -- if you think there is a good cleanup, suggest it to me for a separate patch.
  • Keep related functions together: When adding a new function, try to insert it near related functions, to keep similar behaviour close.
  • Don't guess header names: If you don't know where the definition of a class or function is, don't try to guess the header name, but search for it instead.
  • Be careful with forward declarations: Many types are forward declared; if you want to use them, you'll need to find the definition.
  • Be careful with inline function definitions: Many functions are declared as inline in the .h file, and defined in a -inl.h file. If you get compile errors about a missing definition, you are likely missing an #include for a -inl.h file. You can only include -inl.h files from other -inl.h files and .cc files.