fix: override host-specific variables when reading headers config.gypi

[iFwu]

Background

getBaseConfigGypi reads \$nodedir/include/node/config.gypi verbatim whenever --disturl, --dist-url, or --nodedir is set (and --force-process-config is not). This was introduced in #2497 to let Electron / NW.js builds pick up target build config from custom headers.

The official Node release headers tarball is, however, a single universal artifact shipped to all platforms, and its embedded config.gypi reflects the build host of the Node release-engineering machine (currently a Linux x64 / GCC box). When a consumer on a different host inherits it verbatim, host-specific fields end up wrong.

Symptom on macOS arm64

Field-by-field diff between the cached headers' config.gypi and process.config.variables on darwin/arm64 with Node v24.13.1:

field	cache	process.config
host_arch	x64	arm64
clang	0	1
llvm_version	"0.0"	"16.0"
xcode_version	<undef>	"16.0"
arm_fpu	<undef>	"neon"
gas_version	"2.38"	<undef>
shlib_suffix	"so.137"	"137.dylib"

The killer is clang=0: Node's common.gypi gates -std=gnu++20 (and several other flags) on clang==1. With clang=0 those branches never fire, C++ compilation falls back to C++03, and any addon using node-addon-api immediately fails with:

```
node-addon-api/napi.h: error: a space is required between consecutive right angle brackets (use '> >')
node-addon-api/napi.h: error: no template named 'initializer_list' in namespace 'std'
node-addon-api/napi.h: error: unknown type name 'constexpr'
```

For comparison, on Linux x64 / Node v24.13.1 the same diff shows all 7 host-specific fields are identical between cache and process.config (the cache literally is a Linux x64 build farm fingerprint), so the fix in this PR is a strict no-op there.

Minimal repro (no Electron required)

```bash
mkdir /tmp/repro && cd /tmp/repro
cat > package.json <<'EOF'
{"name":"r","dependencies":{"node-addon-api":"^8.0.0"}}
EOF
cat > binding.gyp <<'EOF'
{"targets":[{"target_name":"r","sources":["r.cc"],
"include_dirs":["<!@(node -p \"require('node-addon-api').include\")"],
"dependencies":["<!(node -p \"require('node-addon-api').gyp\")"]}]}
EOF
echo '#include <napi.h>' > r.cc
npm install --ignore-scripts

Works:

npx node-gyp rebuild

Fails (anywhere disturl is set):

npm_config_disturl=https://npmmirror.com/mirrors/node npx node-gyp rebuild
```

Affected scope

Anyone with `disturl` set in `~/.npmrc`, project `.npmrc`, or as `npm_config_disturl` env var. Common cases:

• China mirrors: `npmmirror.com`, `taobao`
• Self-hosted: Nexus, JFrog, Verdaccio with `disturl` rewriting
• Electron projects via `electron-rebuild` (the symptom most users hit; reported separately as GYP's host_arch is always x64 regardless of host architecture electron/rebuild#1209)

Why `--force-process-config` is not a real fix

• It throws away the target build config that the headers tarball legitimately carries (the entire point of feat: build with config.gypi from node headers #2497 / The generated config.gypi file should inherit from $nodedir/config.gypi instead of process.config #2490).
• For Electron native modules it produces a node_module_version mismatch — Electron then refuses to load the addon. See Revert setting of --force-process-config… pulsar-edit/ppm#162 (2025-12, reverting --force-process-config after exactly this).
• Electron's own blog post restricts the flag to "old Electron (<=13, <14.2.0, <15.3.0)".

Fix

Override only the host-specific variables from process.config.variables after parsing the headers' config.gypi:

```js
const HOST_SPECIFIC_VARIABLES = [
'host_arch',
'clang',
'llvm_version',
'xcode_version',
'arm_fpu',
'gas_version',
'shlib_suffix'
]
```

PR #2497's intent is preserved — target build config (v8 features, bundled vs shared deps, node_module_version, etc.) still comes from the headers tarball; only host (build machine) fields are corrected.

Verification

• All existing tests pass (npm test: 108 passing, 6 pending — unchanged from main).
• Two new tests added in test/test-create-config-gypi.js covering the override behaviour and --force-process-config back-compat, with a new fixture test/fixtures/nodedir-mismatched-host/ that mimics a Linux x64 build farm headers tarball.
• No-op verified on Linux x64 (all 7 host fields already match cache / process.config).
• Necessary verified on macOS arm64 (all 7 fields mismatched).
• npm run lint clean for changed files.

Open questions for maintainers

1. Is the HOST_SPECIFIC_VARIABLES set complete? It was derived from a full diff on macOS arm64; would appreciate a sanity check on Windows arm64 / FreeBSD / AIX.
2. Should an upstream fix in Node release engineering (ship platform-specific headers, or strip host-specific keys before packaging the universal tarball) take priority? That would fix every node-gyp version retroactively, but turnaround is much slower.

Related

• feat: build with config.gypi from node headers #2497 / The generated config.gypi file should inherit from $nodedir/config.gypi instead of process.config #2490 — original introduction of the code path
• GYP's host_arch is always x64 regardless of host architecture electron/rebuild#1209 — first user report (filed in the wrong repo, no traction)
• Revert setting of --force-process-config… pulsar-edit/ppm#162 — --force-process-config side-effect on Electron module_version

Made with Cursor