Skip to content

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

Merged
codebytere merged 3 commits into
44-x-yfrom
trop/44-x-y-bp-build-generate-the-node-startup-snapshot-on-cross-arch-builds-too-1786928723311
Aug 19, 2026
Merged

build: generate the Node startup snapshot on cross-arch builds too#52879
codebytere merged 3 commits into
44-x-yfrom
trop/44-x-y-bp-build-generate-the-node-startup-snapshot-on-cross-arch-builds-too-1786928723311

Conversation

@trop

@trop trop Bot commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

Backport of #52874
Backport of #52902
Backport of #52959

See those PRs for details. Rebased onto the current 44-x-y head (the earlier failing mksnapshot check was this branch predating #52878).

#52902 fixes the cross-arch snapshot #52874 introduces: without it a second node_mksnapshot run in v8_snapshot_toolchain keyed the browser js2c code cache to a snapshot the framework never shipped, so it was rejected at startup on Windows. #52959 fixes process.arch reading ia32 in the main process on linux-arm once it boots from the cross-generated snapshot (the arm test failures on the sibling backports).

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.

@trop
trop Bot requested a review from a team as a code owner August 17, 2026 01:05
@trop
trop Bot requested a review from codebytere August 17, 2026 01:05
@trop trop Bot added 44-x-y backport This is a backport PR semver/none labels Aug 17, 2026
@MarshallOfSound
MarshallOfSound enabled auto-merge (squash) August 17, 2026 01:12
@MarshallOfSound
MarshallOfSound marked this pull request as draft August 17, 2026 06:30
@MarshallOfSound

Copy link
Copy Markdown
Member

Putting this on hold for now, there's a flake being investigated on main and the CI failures on these backports look related. Will un-draft once that's sorted.

trop Bot and others added 2 commits August 18, 2026 14:44
node_use_node_snapshot / node_use_node_code_cache were gated to
host_cpu == target_cpu, so the targets Electron cross-builds -- linux
arm64 and win arm64 (x64 hosts) and mac x64 (arm64 hosts) -- shipped
without the embedded Node snapshot and its builtin code cache, and every
process there still ran 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 the requirement is a snapshot
toolchain that can run what its V8 emits: V8's arm64 simulator on x64
hosts (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 Electron CI's v8_snapshot_toolchain =
"//build/toolchain/mac:clang_x64" override for mac x64 already provides.
The one same-OS combination that cannot work is V8's default for mac
arm64 -> x64, clang_arm64_v8_x64 (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 gate both on host_os == target_os except that toolchain, and give 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 failed on the missing generated
header). Also brings the patch description up to date.

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, and
electron links with the snapshot embedded. Booting it needs arm64
hardware; the js2c code-cache spec's browser assertions and
process.config.variables.node_use_node_snapshot cover it on the arm64
test legs. mac x64 and win arm64 are by construction, untested locally.

Co-authored-by: Shelley Vohr <[email protected]>
run_node_mksnapshot was instantiated in every toolchain that pulled in
":node_snapshot", so a cross build ran it twice: once in the default
toolchain for the shipped framework, once in v8_snapshot_toolchain for the
host tool that generates the browser process's js2c code cache. Two runs
are not guaranteed to produce the same snapshot, and on Windows they do
not, so the tool built its cache against a read-only heap the framework
never embedded and V8 rejected every entry at startup with a read-only
snapshot checksum mismatch - the browser process compiled browser_init,
utility_init and node_init from source instead.

Define the action only in the default toolchain and have each toolchain's
":node_snapshot" compile that one output, so the snapshot the cache is
keyed to is the snapshot the framework ships.

Notes: none
(cherry picked from commit 3c44687)
@codebytere
codebytere force-pushed the trop/44-x-y-bp-build-generate-the-node-startup-snapshot-on-cross-arch-builds-too-1786928723311 branch from c812f14 to 2e48192 Compare August 18, 2026 14:47
Node's GN build set NODE_ARCH to "ia32" whenever the toolchain compiling
it was x86 and to target_cpu otherwise. That is the same thing for a
normal build, but not in V8's snapshot toolchain: the arm (32-bit)
snapshot is produced by an x86-hosted node_mksnapshot, which therefore
carried NODE_ARCH="ia32", and since #52874 the arm build boots its main
process from that snapshot - so process.arch read "ia32" there while
renderers and workers said "arm". Spell the ia32 special case off
target_cpu instead, which is right in the target toolchain and in every
host toolchain that builds node for the snapshot.
@codebytere
codebytere force-pushed the trop/44-x-y-bp-build-generate-the-node-startup-snapshot-on-cross-arch-builds-too-1786928723311 branch from 2e48192 to 27b25e9 Compare August 18, 2026 15:48
@codebytere
codebytere marked this pull request as ready for review August 19, 2026 07:35
@codebytere
codebytere merged commit e920e83 into 44-x-y Aug 19, 2026
121 of 123 checks passed
@codebytere
codebytere deleted the trop/44-x-y-bp-build-generate-the-node-startup-snapshot-on-cross-arch-builds-too-1786928723311 branch August 19, 2026 09:04
@release-clerk

release-clerk Bot commented Aug 19, 2026

Copy link
Copy Markdown

Release Notes Persisted

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

3 participants