torque

# V8 Torque 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. ## Execution Pipeline To debug failures, you must understand its multi-stage build: 1. **Generation**: The Torque compiler reads `.tq` files and generates C++ CodeStubAssembler files (`.cc`, `.h`, `.inc`) in `out/<config>/gen/torque-generated/`. 2. **Compilation**: `mksnapshot` (or the `d8` build) compiles the generated C++ files. 3. **Snapshotting**: `mksnapshot` executes the generated C++ code (via TurboFan or Maglev) to emit highly-optimized raw machine code. 4. **Linking**: The machine code is serialized into a snapshot and linked into V8, meaning Torque builtins run with zero translation overhead at runtime. ## Implementation Patterns Common Torque syntax, keywords, and linkage definitions: ```cpp // 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; ``` ## Mandatory verification workflow The task is **incomplete** until you successfully execute this sequence: ### 1. Build Run the `gm.py` wrapper to trigger the Torque generator and C++ compilation. ```bash tools/dev/gm.py quiet {arch}.{type} ``` (e.g., `x64.optdebug` or `arm64.release`). Use `optdebug` for logic/debugging, `release` for performance/benchmarking. ### 2. Verify with Tests Run the relevant test suite (usually `mjsunit` for JavaScript-exposed builtins) to ensure correctness. Match the `{arch}.{type}` to your build. ```bash tools/run-tests.py --progress dots --outdir=out/{arch}.{type} mjsunit/<test_name> ``` ### 3. Debug (If Necessary) 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/`.