# 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//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.