AGENTS.md

1# V8 C++ API Implementation Guide
2 
3This directory contains Bun's implementation of the V8 C++ API on top of JavaScriptCore. This allows native Node.js modules that use V8 APIs to work with Bun.
4 
5## Architecture Overview
6 
7Bun implements V8 APIs by creating a compatibility layer that:
8 
9- Maps V8's `Local<T>` handles to JSC's `JSValue` system
10- Uses handle scopes to manage memory lifetimes similar to V8
11- Provides V8-compatible object layouts that inline V8 functions can read
12- Manages tagged pointers for efficient value representation
13 
14For detailed background, see the blog series:
15 
16- [Part 1: Introduction and challenges](https://bun.com/blog/how-bun-supports-v8-apis-without-using-v8-part-1.md)
17- [Part 2: Memory layout and object representation](https://bun.com/blog/how-bun-supports-v8-apis-without-using-v8-part-2.md)
18- [Part 3: Garbage collection and primitives](https://bun.com/blog/how-bun-supports-v8-apis-without-using-v8-part-3.md)
19 
20## Directory Structure
21 
22```
23src/jsc/bindings/v8/
24├── v8.h                    # Main header with V8_UNIMPLEMENTED macro
25├── v8_*.h                  # V8 compatibility headers
26├── V8*.h                   # V8 class headers (Number, String, Object, etc.)
27├── V8*.cpp                 # V8 class implementations
28├── shim/                   # Internal implementation details
29│   ├── Handle.h            # Handle and ObjectLayout implementation
30│   ├── HandleScopeBuffer.h # Handle scope memory management
31│   ├── TaggedPointer.h     # V8-style tagged pointer implementation
32│   ├── Map.h               # V8 Map objects for inline function compatibility
33│   ├── GlobalInternals.h   # V8 global state management
34│   ├── InternalFieldObject.h # Objects with internal fields
35│   └── Oddball.h           # Primitive values (undefined, null, true, false)
36├── node.h                  # Node.js module registration compatibility
37└── real_v8.h              # Includes real V8 headers when needed
38```
39 
40## Implementing New V8 APIs
41 
42### 1. Create Header and Implementation Files
43 
44Create `V8NewClass.h`:
45 
46```cpp
47#pragma once
48 
49#include "v8.h"
50#include "V8Local.h"
51#include "V8Isolate.h"
52 
53namespace v8 {
54 
55class NewClass : public Data {
56public:
57    BUN_EXPORT static Local<NewClass> New(Isolate* isolate, /* parameters */);
58    BUN_EXPORT /* return_type */ SomeMethod() const;
59 
60    // Add other methods as needed
61};
62 
63} // namespace v8
64```
65 
66Create `V8NewClass.cpp`:
67 
68```cpp
69#include "V8NewClass.h"
70#include "V8HandleScope.h"
71#include "v8_compatibility_assertions.h"
72 
73ASSERT_V8_TYPE_LAYOUT_MATCHES(v8::NewClass)
74 
75namespace v8 {
76 
77Local<NewClass> NewClass::New(Isolate* isolate, /* parameters */)
78{
79    // Implementation - typically:
80    // 1. Create JSC value
81    // 2. Get current handle scope
82    // 3. Create local handle
83    return isolate->currentHandleScope()->createLocal<NewClass>(isolate->vm(), /* JSC value */);
84}
85 
86/* return_type */ NewClass::SomeMethod() const
87{
88    // Implementation - typically:
89    // 1. Convert this Local to JSValue via localToJSValue()
90    // 2. Perform JSC operations
91    // 3. Return converted result
92    auto jsValue = localToJSValue();
93    // ... JSC operations ...
94    return /* result */;
95}
96 
97} // namespace v8
98```
99 
100### 2. Add Symbol Exports
101 
102For each new C++ method, you must add the mangled symbol names to multiple files:
103 
104#### a. Add to `src/runtime/napi/napi_body.rs`
105 
106Find the `v8_api` module and add entries to both the `#[cfg(not(windows))]` (Itanium) and `#[cfg(windows)]` (MSVC) `extern "C"` blocks:
107 
108```rust
109#[cfg(not(windows))]
110mod v8_api {
111    use core::ffi::c_void;
112    unsafe extern "C" {
113        // ... existing functions ...
114        pub(super) fn _ZN2v88NewClass3NewEPNS_7IsolateE/* parameters */() -> *mut c_void;
115        pub(super) fn _ZNK2v88NewClass10SomeMethodEv() -> *mut c_void;
116    }
117}
118#[cfg(windows)]
119mod v8_api {
120    use core::ffi::c_void;
121    unsafe extern "C" {
122        // ... existing functions ...
123        #[link_name = "?New@NewClass@v8@@SA?AV?$Local@VNewClass@v8@@@2@PEAVIsolate@2@/* parameters */@Z"]
124        pub(super) fn NewClass_New() -> *mut c_void;
125        #[link_name = "?SomeMethod@NewClass@v8@@QEBA/* return_type */XZ"]
126        pub(super) fn NewClass_SomeMethod() -> *mut c_void;
127    }
128}
129```
130 
131**To get the correct mangled names:**
132 
133For **GCC/Clang** (Unix):
134 
135```bash
136# Build your changes first
137bun bd --help  # This compiles your code
138 
139# Extract symbols
140nm build/CMakeFiles/bun-debug.dir/src/jsc/bindings/v8/V8NewClass.cpp.o | grep &quot;T _ZN2v8&quot;
141```
142 
143For **MSVC** (Windows):
144 
145```powershell
146# Use the provided PowerShell script in the comments:
147dumpbin .\build\CMakeFiles\bun-debug.dir\src\jsc\bindings\v8\V8NewClass.cpp.obj /symbols | where-object { $_.Contains(' v8::') } | foreach-object { (($_ -split "\|")[1] -split " ")[1] } | ForEach-Object { "#[link_name = `"${_}`"] pub(super) fn ___() -> *mut c_void;" }
148```
149 
150#### b. Add to Symbol Files
151 
152Add to `src/symbols.txt` (without leading underscore):
153 
154```
155_ZN2v88NewClass3NewEPNS_7IsolateE...
156_ZNK2v88NewClass10SomeMethodEv
157```
158 
159Add to `src/symbols.dyn` (with leading underscore and semicolons):
160 
161```
162{
163    __ZN2v88NewClass3NewEPNS_7IsolateE...;
164    __ZNK2v88NewClass10SomeMethodEv;
165}
166```
167 
168**Note:** `src/symbols.def` is Windows-only and typically doesn't contain V8 symbols.
169 
170### 3. Add Tests
171 
172Create tests in `test/v8/v8-module/main.cpp`:
173 
174```cpp
175void test_new_class_feature(const FunctionCallbackInfo<Value> &info) {
176    Isolate* isolate = info.GetIsolate();
177 
178    // Test your new V8 API
179    Local<NewClass> obj = NewClass::New(isolate, /* parameters */);
180    auto result = obj->SomeMethod();
181 
182    // Print results for comparison with Node.js
183    std::cout << "Result: " << result << std::endl;
184 
185    info.GetReturnValue().Set(Undefined(isolate));
186}
187```
188 
189Add the test to the registration section:
190 
191```cpp
192void Init(Local<Object> exports, Local<Value> module, Local<Context> context) {
193    // ... existing functions ...
194    NODE_SET_METHOD(exports, "test_new_class_feature", test_new_class_feature);
195}
196```
197 
198Add test case to `test/v8/v8.test.ts`:
199 
200```typescript
201describe("NewClass", () => {
202  it("can use new feature", async () => {
203    await checkSameOutput("test_new_class_feature", []);
204  });
205});
206```
207 
208### 4. Handle Special Cases
209 
210#### Objects with Internal Fields
211 
212If implementing objects that need internal fields, extend `InternalFieldObject`:
213 
214```cpp
215// In your .h file
216class MyObject : public InternalFieldObject {
217    // ... implementation
218};
219```
220 
221#### Primitive Values
222 
223For primitive values, ensure they work with the `Oddball` system in `shim/Oddball.h`.
224 
225#### Template Classes
226 
227For `ObjectTemplate` or `FunctionTemplate` implementations, see existing patterns in `V8ObjectTemplate.cpp` and `V8FunctionTemplate.cpp`.
228 
229## Memory Management Guidelines
230 
231### Handle Scopes
232 
233- All V8 values must be created within an active handle scope
234- Use `isolate->currentHandleScope()->createLocal<T>()` to create handles
235- Handle scopes automatically clean up when destroyed
236 
237### JSC Integration
238 
239- Use `localToJSValue()` to convert V8 handles to JSC values
240- Use `JSC::WriteBarrier` for heap-allocated references
241- Implement `visitChildren()` for custom heap objects
242 
243### Tagged Pointers
244 
245- Small integers (±2^31) are stored directly as Smis
246- Objects use pointer tagging with map pointers
247- Doubles are stored in object layouts with special maps
248 
249## Testing Strategy
250 
251### Comprehensive Testing
252 
253The V8 test suite compares output between Node.js and Bun for the same C++ code:
254 
2551. **Install Phase**: Sets up identical module builds for Node.js and Bun
2562. **Build Phase**: Compiles native modules using node-gyp
2573. **Test Phase**: Runs identical C++ functions and compares output
258 
259### Test Categories
260 
261- **Primitives**: undefined, null, booleans, numbers, strings
262- **Objects**: creation, property access, internal fields
263- **Arrays**: creation, length, iteration, element access
264- **Functions**: callbacks, templates, argument handling
265- **Memory**: handle scopes, garbage collection, external data
266- **Advanced**: templates, inheritance, error handling
267 
268### Adding New Tests
269 
2701. Add C++ test function to `test/v8/v8-module/main.cpp`
2712. Register function in the module exports
2723. Add test case to `test/v8/v8.test.ts` using `checkSameOutput()`
2734. Run with: `bun bd test test/v8/v8.test.ts -t "your test name"`
274 
275## Debugging Tips
276 
277### Build and Test
278 
279```bash
280# Build debug version (takes ~5 minutes)
281bun bd --help
282 
283# Run V8 tests
284bun bd test test/v8/v8.test.ts
285 
286# Run specific test
287bun bd test test/v8/v8.test.ts -t &quot;can create small integer&quot;
288```
289 
290### Common Issues
291 
292**Symbol Not Found**: Ensure mangled names are correctly added to `napi_body.rs` and symbol files.
293 
294**Segmentation Fault**: Usually indicates inline V8 functions are reading incorrect memory layouts. Check `Map` setup and `ObjectLayout` structure.
295 
296**GC Issues**: Objects being freed prematurely. Ensure proper `WriteBarrier` usage and `visitChildren()` implementation.
297 
298**Type Mismatches**: Use `v8_compatibility_assertions.h` macros to verify type layouts match V8 expectations.
299 
300### Debug Logging
301 
302Use `V8_UNIMPLEMENTED()` macro for functions not yet implemented:
303 
304```cpp
305void MyClass::NotYetImplemented() {
306    V8_UNIMPLEMENTED();
307}
308```
309 
310## Advanced Topics
311 
312### Inline Function Compatibility
313 
314Many V8 functions are inline and compiled into native modules. The memory layout must exactly match what these functions expect:
315 
316- Objects start with tagged pointer to `Map`
317- Maps have instance type at offset 12
318- Handle scopes store tagged pointers
319- Primitive values at fixed global offsets
320 
321### Cross-Platform Considerations
322 
323- Symbol mangling differs between GCC/Clang and MSVC
324- Handle calling conventions (JSC uses System V on Unix)
325- Ensure `BUN_EXPORT` visibility on all public functions
326- Test on all target platforms via CI
327 
328## Contributing
329 
330When contributing V8 API implementations:
331 
3321. **Follow existing patterns** in similar classes
3332. **Add comprehensive tests** that compare with Node.js
3343. **Update all symbol files** with correct mangled names
3354. **Document any special behavior** or limitations
336 
337For questions about V8 API implementation, refer to the blog series linked above or examine existing implementations in this directory.
338