feat: ship the V8 internal headers as a release artifact [skip ci]

Both runtimes' inspector glue compiles against src/inspector, src/base,
src/common and the crdtp headers. None of that is public API, and all of
it has to match the libraries or it is an ABI mismatch -- the iOS tree was
carrying 10.3 crdtp headers against a 14.9 libcrdtp until this week.

Without them in the release a consumer still needs a full V8 checkout to
re-vendor, which defeats shipping artifacts at all.

Ships the subtrees rather than a precomputed closure, since the set each
runtime needs differs. Includes the generated src/inspector/protocol/*.h,
which only exist in a build directory but sit directly in Forward.h's
include path -- verified by running the android runtime's vendoring script
against the package alone, which reproduces its current 66-file tree
exactly.

Author: edusperoni

.github/workflows/build-matrix.yml

@@ -95,6 +95,25 @@ jobs:
           path: v8-*-android-${{ matrix.abi }}.tar.gz
           retention-days: 7
 
+      # The internal headers are architecture-independent, so one job produces
+      # them. It piggybacks on a build rather than getting its own job because
+      # src/inspector/protocol/*.h are generated into gen/ and only exist once
+      # something has been built.
+      - name: Package the internal headers
+        if: matrix.abi == 'arm64-v8a'
+        run: |
+          scripts/matrix/package-src-headers.sh \
+            --gen-dir .v8/v8/out.gn/android-arm64-release/gen
+          tar -czf "v8-${{ needs.config.outputs.v8_version }}-src-headers.tar.gz" \
+            -C dist src-headers
+
+      - uses: actions/upload-artifact@v4
+        if: matrix.abi == 'arm64-v8a'
+        with:
+          name: v8-src-headers
+          path: v8-*-src-headers.tar.gz
+          retention-days: 7
+
   ios:
     needs: config
     if: ${{ github.event_name != 'workflow_dispatch' || inputs.platforms == 'all' || inputs.platforms == 'ios' }}

README.md

@@ -66,6 +66,19 @@ the NativeScript framework itself is built per platform.
 Consumers map `ios-arm64-device` onto `arm64-xros` and `ios-arm64-simulator`
 onto `arm64-xrsimulator`.
 
+### The internal headers ship too
+
+Both runtimes' inspector glue compiles against `src/inspector`, `src/base`,
+`src/common` and the crdtp headers — none of which are public API, and all of
+which have to match the libraries or they are an ABI mismatch. A release
+therefore also carries `v8-<version>-src-headers.tar.gz`, so a consumer never
+needs a V8 checkout to re-vendor them.
+
+It ships the subtrees rather than a precomputed closure, because the set each
+runtime needs differs. It includes the generated `src/inspector/protocol/*.h`,
+which live in the build directory rather than the source tree but sit directly
+in the include path of `Forward.h`.
+
 ## Releasing
 
 The matrix runs on every push to `main` and on pull requests touching the build

scripts/matrix/package-src-headers.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+set -e
+#
+# Packages the V8 *internal* headers into dist/src-headers/.
+#
+# Both runtimes' inspector glue compiles against src/inspector, src/base,
+# src/common and the crdtp headers, none of which are public API. Keeping that
+# copy on a different V8 than the libraries is an ABI mismatch, so it has to
+# travel with a release -- otherwise a consumer still needs a full V8 checkout
+# to produce it, which defeats the point of shipping artifacts at all.
+#
+# The exact set each runtime needs differs (they include different roots), so
+# this ships the subtrees and lets each consumer compute its own closure rather
+# than baking one in here.
+#
+# Usage: package-src-headers.sh [--v8-dir <path>]
+#
+
+ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+source "$ROOT_DIR/config.env"
+
+V8_DIR="$ROOT_DIR/.v8/v8"
+GEN_DIR=""
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --v8-dir)   V8_DIR="$2"; shift 2 ;;
+        --v8-dir=*) V8_DIR="${1#*=}"; shift ;;
+        --gen-dir)  GEN_DIR="$2"; shift 2 ;;
+        --gen-dir=*) GEN_DIR="${1#*=}"; shift ;;
+        -h|--help)  echo "Usage: $(basename "$0") [--v8-dir <path>] --gen-dir <path>"; exit 0 ;;
+        *)          echo "Unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+[ -d "$V8_DIR/src" ] || { echo "No V8 sources at $V8_DIR" >&2; exit 1; }
+
+DIST="$ROOT_DIR/dist/src-headers"
+rm -rf "$DIST"
+mkdir -p "$DIST"
+
+copy_headers() {
+    local subdir="$1"
+    [ -d "$V8_DIR/$subdir" ] || return 0
+    # -inc as well as -h: absl's int128 pulls in int128_*_intrinsic.inc, and
+    # several V8 headers include .inc the same way.
+    (cd "$V8_DIR" && find "$subdir" \( -name '*.h' -o -name '*.inc' \) -print0) \
+        | (cd "$V8_DIR" && tar --null -cf - -T -) \
+        | (cd "$DIST" && tar -xf -)
+}
+
+copy_headers src
+copy_headers third_party/inspector_protocol/crdtp
+copy_headers third_party/abseil-cpp/absl
+
+# src/inspector/protocol/*.h are generated into the build directory rather than
+# living in the source tree, but the closure runs straight through them
+# (Forward.h -> Protocol.h -> the per-domain headers), so a consumer cannot
+# resolve its includes without them.
+if [ -z "$GEN_DIR" ] || [ ! -d "$GEN_DIR/src/inspector/protocol" ]; then
+    echo "--gen-dir must point at a build's gen/ containing src/inspector/protocol" >&2
+    exit 1
+fi
+mkdir -p "$DIST/src/inspector/protocol"
+cp "$GEN_DIR/src/inspector/protocol/"*.h "$DIST/src/inspector/protocol/"
+
+echo "$V8_VERSION" > "$DIST/V8_VERSION"
+
+echo "packaged $(find "$DIST" -name '*.h' -o -name '*.inc' | wc -l | tr -d ' ') headers"
+du -sh "$DIST"