codebytere

#52874: build: generate the Node startup snapshot on cross-arch builds too

Merged
Created: Aug 16, 2026, 4:12:11 PM
Merged: Aug 16, 2026, 8:05:15 PM
6 comments
Target: main

Description of Change

node_use_node_snapshot / node_use_node_code_cache were gated to host_cpu == target_cpu, so the targets we cross-build — linux arm64 and win arm64 (x64 hosts) and mac x64 (arm64 hosts) — ship without the embedded Node startup snapshot from #51703 and its builtin code cache, and every process there still runs the full Node bootstrap.

node_mksnapshot already builds in v8_snapshot_toolchain, like mksnapshot and v8_context_snapshot_generator. Unlike those it executes target-CPU code (the Node bootstrap runs in JS), so what it needs is a snapshot toolchain that can run what its V8 emits: V8's arm64 simulator on x64 hosts (//build/toolchain/linux:clang_x64_v8_arm64, the win host toolchain with v8_target_cpu = "arm64"), or an x64 binary under Rosetta on arm64 macs — which is what our v8_snapshot_toolchain="//build/toolchain/mac:clang_x64" override for mac x64 in build-electron/action.yml already provides. The one same-OS combination that cannot work is V8's default for mac arm64 → x64, clang_arm64_v8_x64 (an arm64 binary emitting x64 code, no simulator) — that is the crash the old TODO in node.gni described. Neither the snapshot nor the code cache contains machine code, so what a cross node_mksnapshot produces is valid on the target; the js2c code cache is already generated cross-arch the same way.

So this gates both flags on host_os == target_os except that toolchain, gives the node_snapshot / node_snapshot_stub source_sets the //base:debugging_buildflags dependency that node_builtins.h's base/dcheck_is_on.h include needs (a fresh out dir building only third_party/electron_node:node_snapshot fails on the missing generated header otherwise), and updates the patch description.

Verified on a linux x64 host with target_cpu = "arm64": node_mksnapshot runs under the simulator (blob 4.9 MB, 392-entry / 2.8 MB code cache — same shape as native), the snapshot-keyed browser js2c cache tool runs against it, and electron links with the snapshot embedded. I have not booted the result on arm64 hardware; the arm64 test legs cover it (process.config.variables.node_use_node_snapshot, and the js2c code-cache spec's browser assertions only pass if the browser isolate really came from the snapshot). mac x64 and win arm64 are by construction and untested locally, so I'd like to see all the cross legs green here before merging.

Checklist

  • PR description included and stakeholders cc'd
  • npm test passes

Release Notes

Notes: Linux arm64, Windows arm64 and macOS x64 builds now start the main process from the embedded Node.js startup snapshot like the other platforms, improving startup time.

Backports

42-x-y
In-flight
PR Number
#52880
Waiting to be merged
43-x-y
In-flight
PR Number
#52881
Waiting to be merged
44-x-y
In-flight
PR Number
#52879
Waiting to be merged

Semver Impact

Major
Breaking changes
Minor
New features
Patch
Bug fixes
None
Docs, tests, etc.

Semantic Versioning helps users understand the impact of updates:

  • Major (X.y.z): Breaking changes that may require code modifications
  • Minor (x.Y.z): New features that maintain backward compatibility
  • Patch (x.y.Z): Bug fixes that don't change the API
  • None: Changes that don't affect using facing parts of Electron