---
name: v8-commands
description: Key commands for building, debugging, and testing in V8. Use when needing command syntax for gm.py, d8 flags, or run-tests.py. Do not use for environment setup.
---

# V8 Key Commands

Use this skill to find the correct commands for common development tasks in V8.
This unifies the commands listed in workspace configuration and ensures
consistent usage.

## Building

V8 uses `gm.py` as a wrapper around GN and Ninja for building.

**Mandatory GN Args & Siso Remote Execution Guardrails**: Always include
`use_remoteexec = true` in your `args.gn` or via `gm.py` flags to ensure builds
utilize remote execution. Remote execution is mandatory in this environment.

**Critical Guardrail (Path Strictness)**: The target output directory must sit
exactly 2 levels deep relative to the project root (e.g., `out/x64.debug` or
`out/x64.release`).

- **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`
- **Sync DEPS Options:** Use `tools/dev/gm.py quiet x64.optdebug.d8 --sync` to
  sync DEPS when switching between branches. Use the slower `--sync=force`
  option if there are still issues with broken DEPS.

*Note: Always pass the `quiet` keyword unless told otherwise to avoid excessive
output.*

## Debugging

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
```

### Common Diagnostic Flags

- `--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.
- `--gdbjit`: Allows seeing Maglev graphs or JavaScript code in GDB backtraces.
  To debug issues involving code motion disable gdbjit (as it disables code
  motion).

A comprehensive list of all flags can be found by running
`out/x64.debug/d8 --help`.

## Testing

For detailed instructions on running tests and interpreting failures, see the
dedicated test execution guidelines.

Key commands summary:

- **Run tests:** `tools/run-tests.py --progress dots --outdir=out/x64.optdebug`