Expert guidance for navigating, implementing, and verifying V8 Torque (.tq) builtins and object layouts.
Torque is an Ahead-of-Time (AOT) generator that transforms .tq DSL into highly-optimized C++ CodeStubAssembler (CSA) code, which is then compiled into the mksnapshot binary.
To debug failures, you must understand its multi-stage build:
.tq files and generates C++ CodeStubAssembler files (.cc, .h, .inc) in out/<config>/gen/torque-generated/.mksnapshot (or the d8 build) compiles the generated C++ files.mksnapshot executes the generated C++ code (via TurboFan or Maglev) to emit highly-optimized raw machine code.Common Torque syntax, keywords, and linkage definitions:
// 1. Type Casting & Checks
const array = Cast<JSArray>(object) otherwise GotoLabel;
if (Is<JSArray>(object)) { ... }
// 2. Control Flow
try {
const smi = Cast<Smi>(input) otherwise IsNotSmi;
} label IsNotSmi deferred {
return runtime::DoSomething(context, input);
}
// 3. Signatures & Keywords
// 'macro': Inlined functions for reusable logic.
transitioning macro Name(implicit context: Context)(arg: JSAny): JSAny
// 'builtin': Non-inlined functions, callable from other builtins or JavaScript.
transitioning builtin Name(implicit context: Context)(arg: JSAny): JSAny
// 'javascript': Marks a builtin as directly callable from JavaScript, with JS linkage.
transitioning javascript builtin Name(js-implicit context: NativeContext, receiver: JSAny)(arg: JSAny): JSAny
// 'transitioning': Indicates a function can cause an object's map to change (e.g. adding properties).
// 'extern': Used to call C++ defined CSA functions from Torque.
extern transitioning macro NameInCpp(Context, JSAny): JSAny;
If you create a new .tq file, you MUST register it in the root BUILD.gn.
v8_torque_files list in BUILD.gn.v8_torque_files = [
"src/builtins/array-join.tq",
"src/builtins/my-new-builtin.tq", # Your addition
...
]
Note: Modifications to existing files do not require registration changes.
The task is incomplete until you successfully execute this sequence:
Run the gm.py wrapper to trigger the Torque generator and C++ compilation.
tools/dev/gm.py quiet {arch}.{type}
(e.g., x64.optdebug or arm64.release). Use optdebug for logic/debugging, release for performance/benchmarking.
Run the relevant test suite (usually mjsunit for JavaScript-exposed builtins) to ensure correctness. Match the {arch}.{type} to your build.
tools/run-tests.py --progress dots --outdir=out/{arch}.{type} mjsunit/<test_name>
If the build fails during "Generation", inspect the .tq syntax. If it fails during "Compilation", check the generated C++ in out/<config>/gen/torque-generated/.