# 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/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](https://chromium.googlesource.com/chromium/src/+/main/styleguide/styleguide.md).
- 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.
