GEMINI.md

1# Gemini Workspace for V8
2 
3This is the workspace configuration for V8 when using Gemini.
4 
5Documentation can be found at https://v8.dev/docs.
6 
7## Key Commands
8 
9-   **Build (Debug):** `tools/dev/gm.py quiet x64.debug tests`
10-   **Build (Optimized Debug):** `tools/dev/gm.py quiet x64.optdebug tests`
11-   **Build (Release):** `tools/dev/gm.py quiet x64.release tests`
12-   **Run All Tests:** `tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug`
13-   **Run C++ Tests:** `tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug cctest unittests`
14-   **Run JavaScript Tests:** `tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug mjsunit`
15-   **Format Code:** `git cl format`
16 
17Some hints:
18- You are an expert C++ developer.
19- 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.
20- 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.
21 
22## Folder structure
23 
24- `src/`: The main source folder providing the implementation of the virtual machine. Key subdirectories include:
25    - `src/api/`: Implements the V8 public C++ API, as declared in `include/`.
26    - `src/asmjs/`: Contains V8's Asm.js pipeline, which compiles the Asm.js subset of JavaScript into WebAssembly.
27    - `src/ast/`: Defines the Abstract Syntax Tree (AST) used to represent parsed JavaScript, including nodes, scopes, and variables.
28    - `src/base/`: Provides fundamental, low-level utilities, data structures, and a platform abstraction layer for the entire V8 project.
29    - `src/baseline/`: Implements the Sparkplug baseline compiler, which generates machine code directly from bytecode for a fast performance boost.
30    - `src/bigint/`: The implementation of BigInt operations.
31    - `src/builtins/`: Implementation of JavaScript built-in functions (e.g., `Array.prototype.map`).
32    - `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.
33    - `src/common/`: Common definitions and utilities.
34    - `src/compiler/`: The TurboFan optimizing compiler, including the Turboshaft CFG compiler.
35    - `src/d8/`: The `d8` shell implementation, for running V8 in a CLI.
36    - `src/debug/`: The debugger and debug protocol implementation.
37    - `src/deoptimizer/`: The deoptimizer implementation, which translates optimized frames into unoptimized ones.
38    - `src/execution/`: The definitions of the execution environment, including the Isolate, frame definitions, microtasks, stack guards, tiering, and on-stack argument handling.
39    - `src/handles/`: The handle implementation for GC-safe object references.
40    - `src/heap/`: The garbage collector and memory management code.
41    - `src/ic/`: The Inline Caching implementation.
42    - `src/init/`: The V8 initialization code.
43    - `src/inspector/`: The inspector protocol implementation.
44    - `src/interpreter/`: The Ignition bytecode compiler and interpreter.
45    - `src/json/`: The JSON parser and serializer.
46    - `src/libplatform/`: The platform abstraction layer, for task runners and worker threads.
47    - `src/logging/`: The logging implementation.
48    - `src/maglev/`: The Maglev mid-tier optimizing compiler.
49    - `src/numbers/`: Implementations of various numeric operations.
50    - `src/objects/`: The representation and behaviour of V8 internal and JavaScript objects.
51    - `src/parsing/`: The parser and scanner implementation.
52    - `src/profiler/`: The in-process profiler implementations, for heap snapshots, allocation tracking, and a sampling CPU profiler.
53    - `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.
54    - `src/runtime/`: C++ functions that can be called from JavaScript at runtime.
55    - `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.
56    - `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.
57    - `src/strings/`: Implementations of string helpers, such as predicates for characters, unicode processing, hashing and string building.
58    - `src/torque/`: The Torque language implementation.
59    - `src/tracing/`: The tracing implementation.
60    - `src/trap-handler/`: Implementations of trap handlers.
61    - `src/wasm/`: The WebAssembly implementation.
62    - `src/zone/`: The implementation of a simple bump-pointer region-based zone allocator.
63- `test/`: Folder containing most of the tests and testing code.
64- `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.
65- `out/`: Folder containing the results of a build. Usually organized in sub folders for the respective configurations.
66 
67## Building
68 
69The full documentation for building using GN can be found at https://v8.dev/docs/build-gn.
70 
71Once the initial dependencies are installed, V8 can be built using `gm.py`, which is a wrapper around GN and Ninja.
72 
73```bash
74# List all available build configurations and targets
75tools/dev/gm.py
76 
77# Build the d8 shell for x64 in release mode
78tools/dev/gm.py quiet x64.release
79 
80# Build d8 for x64 in debug mode
81tools/dev/gm.py quiet x64.debug
82```
83 
84- **release:** Optimized for performance, with debug information stripped. Use for benchmarking.
85- **debug:** Contains full debug information and enables assertions. Slower, but essential for debugging.
86- **optdebug:** A compromise with optimizations enabled and debug information included. Good for general development.
87 
88Make 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.
89 
90## Debugging
91 
92For debugging, it is recommended to use a `debug` or `optdebug` build. You can run `d8` with GDB or LLDB for native code debugging.
93 
94```bash
95# Example of running d8 with gdb
96gdb --args out/x64.debug/d8 --my-flag my-script.js
97```
98 
99V8 also provides a rich set of flags for diagnostics. Some of the most common ones are:
100- `--trace-opt`: Log optimized functions.
101- `--trace-deopt`: Log when and why functions are deoptimized.
102- `--trace-gc`: Log garbage collection events.
103- `--allow-natives-syntax`: Enables calling of internal V8 functions (e.g. `%OptimizeFunctionOnNextCall(f)`) from JavaScript for testing purposes.
104 
105A 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.
106 
107When 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.
108 
109## Testing
110 
111The 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:
112- **unittests:** C++ unit tests for V8's internal components.
113- **cctest:** Another, older format for C++ unit tests (deprecated, in the process of being moved to unittests).
114- **mjsunit:** JavaScript-based tests for JavaScript language features and builtins.
115 
116```bash
117# Run all standard tests for the x64.optdebug build
118tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug
119 
120# Run a specific test suite (e.g., cctest)
121tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug cctest
122 
123# Run a specific test file
124tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug cctest/test-heap
125```
126 
127It's important to pass `--progress dots` so that there is minimal progress reporting, to avoid cluttering the output.
128 
129If there are any failing tests, they will be reported along their stderr and a command to reproduce them e.g.
130 
131```
132=== mjsunit/maglev/regress-429656023 ===
133--- stderr ---
134#
135# Fatal error in ../../src/heap/local-factory.h, line 41
136# unreachable code
137#
138#
139#
140...stack trace...
141Received signal 6
142Command: 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
143```
144 
145You 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).
146 
147The full testing documentation is at https://v8.dev/docs/test.
148 
149## Coding and Committing
150 
151- Always follow the style conventions used in code surrounding your changes.
152- Otherwise, follow [Chromium's C++ style guide](https://chromium.googlesource.com/chromium/src/+/main/styleguide/styleguide.md).
153- Use `git cl format` to automatically format your changes.
154 
155### Commit Messages
156Commit messages should follow the convention described at https:/v8.dev/docs/contribute#commit-messages. A typical format is:
157 
158```
159[component]: Short description of the change
160 
161Longer description explaining the "why" of the change, not just
162the "what". Wrap lines at 72 characters.
163 
164Bug: 123456
165```
166 
167- The `component` is the area of the codebase (e.g., `compiler`, `runtime`, `api`).
168- The `Bug:` line is important for linking to issues in the tracker at https://crbug.com/
169 
170## Working with Torque
171 
172Torque is a V8-specific language used to write V8 builtins and some V8 object definitions. It provides a higher-level syntax that compiles down to CSA code.
173 
174### Key Concepts
175 
176-   **Purpose:** Simplify the creation of V8 builtins and object definitions by providing a more abstract language than writing CodeStubAssembler code directly.
177-   **File Extension:** `.tq`
178-   **Location:** Torque files are primarily located in `src/builtins` and `src/objects`.
179-   **Compilation:** Torque files are compiled by the `torque` compiler, which generates C++ and Code Stub Assembler (CSA) files. These generated files are placed in the `out/<build-config>/gen/torque-generated/` directory and then compiled as part of the normal V8 build process.
180    -   **C++ files** `*.tq` files will generate filenames like `*-tq.inc`, `*-tq.cc`, and `*-tq-inl.inc`. Additionally, there are top-level files:
181        -   `class-forward-declarations.h`: Forward declarations for all Torque-defined classes.
182        -   `builtin-definitions.h`: A list of all defined builtins.
183        -   `csa-types.h`: Type definitions for the Code Stub Assembler.
184        -   `factory.cc` and `factory.inc`: Factory functions for creating instances of Torque-defined classes.
185        -   `class-verifiers.h` and `.cc`: Heap object verification functions (for debug builds).
186        -   `exported-macros-assembler.h` and `.cc`: C++ declarations and definitions for exported Torque macros.
187        -   `objects-body-descriptors-inl.inc`: Inline definitions for object body descriptors, which define the memory layout of objects.
188        -   `objects-printer.cc`: Object printer functions for debugging.
189        -   `instance-types.h`: The `InstanceType` enum, used to identify object types at runtime.
190        -   `interface-descriptors.inc`: Definitions for call interface descriptors, which manage function call conventions.
191    -   **CSA files** These have filenames like `*-csa.cc` and `*-csa.h`. They contain the C++ code that uses the `CodeStubAssembler` API to generate the low-level implementation of builtins.
192 
193### Syntax and Features
194 
195-   **Typescript-like Syntax:** Torque's syntax is similar to Typescript with support for functions (macros and builtins), variables, types, and control flow.
196-   **Macros and Builtins:**
197    -   `macro`: Inlined functions for reusable logic.
198    -   `builtin`: Non-inlined functions, callable from other builtins or JavaScript.
199-   **`extern` Keyword:** Used to call C++ defined CSA functions from Torque. This is how Torque code interfaces with the rest of the V8 codebase.
200-   **`transitioning` and `javascript` Keywords:**
201    -   `transitioning`: Indicates a function can cause an object's map to change (e.g., when a property is added to a JSObject).
202    -   `javascript`: Marks a builtin as being directly callable from JavaScript, with Javascript linkage.
203-   **Type System:** Torque has a strong type system that mirrors the V8 object hierarchy. This allows for compile-time type checking and safer code.
204-   **Labels and `goto`:** Torque uses a `labels` and `goto` system for control flow, which is particularly useful for handling exceptional cases and optimizing performance.
205 
206### Workflow for Modifying Torque Files
207 
2081.  **Identify the relevant `.tq` file:** Builtins are in `src/builtins`, and object definitions are in `src/objects`.
2092.  **Modify the Torque code:** Make the necessary changes to the `.tq` file, following the existing syntax and conventions.
2103.  **Rebuild V8:** Run the appropriate `gm.py` command (e.g., `tools/dev/gm.py x64.release`) to recompile V8. This will automatically run the Torque compiler and build the generated C++ files.
2114.  **Test your changes:** Run the relevant tests to ensure that your changes are correct and have not introduced any regressions.
212 
213### Example
214 
215A simple Torque macro to add two SMIs might look like this:
216 
217```torque
218macro AddTwoSmis(a: Smi, b: Smi): Smi {
219  return a + b;
220}
221```
222 
223A more complex example showing a JavaScript-callable builtin:
224 
225```torque
226transitioning javascript builtin MyAwesomeBuiltin(
227    js-implicit context: NativeContext)(x: JSAny): Number {
228  // ... implementation ...
229}
230```
231 
232## Common Pitfalls & Best Practices
233 
234-   **Always format before committing:** Run `git cl format` before creating a commit to ensure your code adheres to the style guide.
235-   **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).
236-   **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).
237-   **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.
238-   **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.
239-   **Keep related functions together:** When adding a new function, try to insert it near related functions, to keep similar behaviour close.
240-   **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.
241-   **Be careful with forward declarations:** Many types are forward declared; if you want to use them, you'll need to find the definition.
242-   **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.
243