MarshallOfSound

#53139: build: add electron_xcache host tool for cross-target V8 code caches

Merged
Created: Aug 23, 2026, 6:15:03 PM
Merged: Aug 24, 2026, 10:23:45 AM
2 comments
Target: main

Important

This tool is intentionally left undocumented until it's usage is validated and tested at scale. The intention is to allow folks to generate code caches for their scripts without having to run builds on all three platforms.

Description of Change

Adds electron_xcache, a standalone host tool (//electron:electron_xcache) that compiles a JS file and emits a V8 code cache for the main process of a target Electron build of the same version — any OS/arch — given that build's V8 startup snapshot blob (or the binary embedding its Node startup snapshot: electron, electron.exe, Electron Framework).

  • A code cache's only build-specific content is its header (version/flag hashes, RO-snapshot checksum) and ReadOnlyHeapRef offsets, all properties of the snapshot the consuming isolate was created from — so the tool creates its isolate from the target's blob, runs no JS beyond context setup, uses an inert external-reference table, and serializes.
  • --mode script|function|module, --eager, --v8-flags / --extra-v8-flags (defaults to the main process's non-default set), --expect-flag-hash, --list to show the blobs found in a binary.
  • Links only //v8, //v8:v8_libplatform, //third_party/zlib: one compile + one link on top of an existing build (~15 s incremental in a ThinLTO release dir).
  • xcache.zip (binary + icudtl.dat + licenses; stripped on Linux official builds) is part of testing_build/release_build on every non-MAS build, staged with the other generated artifacts, and uploaded on publish as xcache-<version>-{darwin,linux,win32}-{x64,arm64}.zip. Any of them can target any platform; they differ only in which host they run on.
  • spec/xcache-spec.ts (when the binary is present next to the build) checks the tool finds the running build's Node snapshot and that its script/function caches are accepted and execute correctly in the main process — guards the default flag set against drift.

Validated against 45.0.0-nightly.20260821: boots from all six desktop targets' embedded Node snapshots; output accepted and behaviourally identical to an uncached compile in the linux-x64, darwin-arm64 and darwin-x64 main processes (32/32 test scripts each, incl. lodash and typescript.js).

Checklist

  • PR description included
  • npm test passes

Release Notes

Notes: none

Backports

44-x-y
Merged
PR Number
#53149
Merged At
Aug 24, 2026, 11:18:06 AM
Released In
Not yet
Release Date
Not yet

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