v8-commands
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.
Source facts
- Repository
- nodejs/node
- Last source activity
- October 4, 2026 at 21:04
- Detected SKILL.md language
- English
- Stars
- 122,301
- Forks
- 39,450
Install options
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Review the source files
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Showing SKILL.md
SKILL.md
Source instructions · Read-only preview- 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`
View on GitHub