Exploring Zig (zig cc) as a unified C/C++ cross-compiler toolchain for Node.js builds

[KoHaRxnP]

Summary

I would like to initiate a discussion around exploring and evaluating zig cc / zig c++ as an alternative/supplementary C/C++ cross-compiler toolchain for Node.js builds.

Context & Motivation

Cross-compiling Node.js across various architectures (e.g., ARM64, RISC-V, x64) currently relies on managing complex platform-specific C/C++ toolchain matrices (GCC/Clang setups).

Since Zig ships with an embedded, hermetic Clang toolchain, zig cc can act as a drop-in C/C++ compiler for almost any target without needing separate cross-compilation toolchains installed on the host machine.

Potential Benefits

1. Simplified CI/CD & Build Matrix: zig cc provides out-of-the-box cross-compilation support for many target triples, potentially simplifying Node.js build infrastructure.
2. Reproducibility & DX: Helps unify local cross-building environments across operating systems without heavy Docker or toolchain setups.
3. No Core Code Changes Required: Since this approach focuses purely on using Zig as a compiler wrapper for existing C/C++ code, it requires zero changes to Node.js's underlying codebase or runtime behavior.

Proposed Next Steps / Discussion Points

• Has the Node.js build/tooling team evaluated zig cc in the past? If so, were there any specific blockers (e.g., flags compatibility, V8 build constraints, libuv issues)?
• Would there be interest in running a small benchmark/PoC to compare zig cc build results against the existing GCC/Clang pipeline for target platforms?

I’d love to hear your thoughts and any historical context from the build team!

[avivkeller]

Would there be interest in running a small benchmark/PoC to compare zig cc build results against the existing GCC/Clang pipeline for target platforms?

I would be interested to see if:

1. This toolchain is faster than the current toolchain
2. This toolchain can build for all CI platforms
3. This toolchain has support for ccache and ninja, or is faster than them
4. This toolchain can handle all of our different build configurations (e.g. building without i18n, etc)

[KoHaRxnP]

Thank you for the quick and encouraging response! These 4 points are extremely helpful and define a clear success criteria for the PoC.

I will set up a local testing pipeline to evaluate zig cc against these requirements:

1. Build Speed: Benchmark clean and incremental build times compared to GCC/Clang.
2. CI Platforms & Configs: Test compilation across key architectures and run ./configure with various flags (e.g., --without-intl).
3. Tooling Integration: Verify seamless integration with ccache and ninja.

I’ll work on running these initial tests and report back here with the preliminary benchmark results and any findings!

[KoHaRxnP]

Build Condition

• OS: Ubuntu 24.04.3 LTS (WSL2)
• CPU: Intel(R) Core(TM) 7 240H
• Concurrency: -j4
• Opt-Level: Auto (Default)
• GCC Version: 13.3.0
  -Zig Version: 0.16.0

GCC Build

make clean || make distclean
unset CC CXX CFLAGS CXXFLAGS LDFLAGS

./configure
time make -j4

• Total Build Time: 74m28.701s (User: 281m53.351s, Sys: 12m53.464s)

• Link Step Time: 1m07.794s (User: 2m55.751s, Sys: 0m19.568s)

Zig Build

make clean || make distclean
unset CC CXX CFLAGS CXXFLAGS LDFLAGS

export CC="zig cc -target x86_64-linux-gnu"
export CXX="zig c++ -target x86_64-linux-gnu"

export CFLAGS="-mno-avx512f -D_GNU_SOURCE"
export CXXFLAGS="-mno-avx512f -DSIMDUTF_IMPLEMENTATION_ICELAKE=0 -DSIMDUTF_HAS_AVX512F=0 -DSIMDJSON_IMPLEMENTATION_ICELAKE=0 -DSIMDJSON_HAS_AVX512F=0 -include stdlib.h -D_GNU_SOURCE"
export LDFLAGS="$(gcc -print-file-name=libgcc.a)"

./configure
time make -j4

• Total Build Time: 52m36.155s (User: 176m20.132s, Sys: 13m19.834s)

• Link Step Time: 1m10.148s (User: 3m24.839s, Sys: 0m42.277s)

Step	GCC	Zig
Compile	73m 21s	51m 26s
Link	1m 07s	1m 10s
Total Build	74m 28s	52m 36s

• However, since the zig build is compiled with the AVX flag set to 0, I think it’s possible that the amount of code being compiled is reduced as a result, which may lead to a slight increase in speed.

Notes & Issues with zig cc / zig c++
GCC built without issues, but moving to zig hit a few snags:

1. Clang strictness in simdutf: Needs explicit SIMD flags like -mevex512 under zig c++. GCC is a bit more forgiving with target feature inlining by default.

2. configure.py macro extraction: ./configure crashed on OpenSSL version check (TypeError: 'NoneType' object is not subscriptable). This happens because of how zig cc handles stdin/pipe macro dumps (-E -dM).

• I fixed this locally by writing macros to a temporary file instead: patch gist. It doesn't touch runtime code and works fine with normal GCC/Clang too. Let me know if a PR for this is welcome.

3. Missing includes (spdlog, LIEF): Clang needs explicit standard headers (worked around via -include stdlib.h).

4. -O0 -O1 breaks inlining: Lowering -O levels causes always_inline errors in V8 and ada. The code strictly expects standard optimization passes.

5. AVX-512 behavior: GCC safely skips unsupported AVX-512 paths at runtime, but zig c++ tries to inline them anyway. Passing -mavx512... globally gets it to compile, but causes SIGILL on CPUs without AVX-512 (like Raptor Lake).

---

What's Next
Got about a ~30% compilation speedup with Zig on a clean build, so next I'm planning to check:

• ccache and ninja integration for incremental builds

• --without-intl and other build flags

• Cross-compilation via zig cc -target

Let me know if anyone has specific flags or setups they'd like tested!

[KoHaRxnP]

In the Zig build process, the build command used previously relied on the local gcc for the export LDFLAGS="$(gcc -print-file-name=libgcc.a)" portion. However, we discovered that we can work around the issue where __cpu_model is undefined by temporarily generating a dummy object file as shown below. This should enable cross-compilation to a variety of environments.

echo 'struct {unsigned int a, b, c, d;} __cpu_model={0,0,0,{0}}; void __cpu_indicator_init(void){}' \
| zig cc -target x86_64-linux-gnu -x c -c - -o /tmp/cpu_model_dummy.o

make clean || make distclean

unset CC CXX CFLAGS CXXFLAGS LDFLAGS

export CC="zig cc -target x86_64-linux-gnu"
export CXX="zig c++ -target x86_64-linux-gnu"

export CFLAGS="-mno-avx512f -D_GNU_SOURCE"
export CXXFLAGS="-mno-avx512f -DSIMDUTF_IMPLEMENTATION_ICELAKE=0 -DSIMDUTF_HAS_AVX512F=0 -DSIMDJSON_IMPLEMENTATION_ICELAKE=0 -DSIMDJSON_HAS_AVX512F=0 -include stdlib.h -D_GNU_SOURCE"

export LDFLAGS="/tmp/cpu_model_dummy.o"

./configure
time make -j4

[AntonAzer]

Hi there,

This is a very interesting proposal. Using zig cc / zig c++ as a cross-compilation driver has gained significant traction in the C/C++ ecosystem due to its bundled headers and ability to target specific glibc / musl ABIs effortlessly without setting up complex crosstool-ng or Docker toolchains.

Here is some context regarding how this interacts with Node.js's build system and potential challenges to keep in mind for a PoC:

---

1. Key Technical Considerations & Potential Blockers

• Host vs. Target Toolchain (Cross-compiling Generators):
  Node.js's build process generates host tools during compilation (such as V8's torque, bytecode_builtins_list_generator, and mksemm). When cross-compiling, configure and gyp need distinct CC / CXX for the target and CC_host / CXX_host for the host. zig cc makes this conceptually simple, but you must ensure gyp passes the correct -target <triple> to target invocation without leaking host flags.

• V8 & Flag Compatibility:
  V8 has strict requirements regarding compiler flags, warnings-as-errors (-Werror), LTO, and sanitizer configurations. Since zig cc is effectively a wrapper around Clang, most flags match directly. However, custom -Wl,... linker flags passed by Node's common.gypi might occasionally interact unexpectedly with Zig's LLD wrapper.

• glibc Symbol Versioning (Targeting ABIs):
  One of zig cc's biggest advantages is targeting older glibc versions (e.g., zig cc -target x86_64-linux-gnu.2.28). Official Node.js release binaries strictly pin minimum glibc requirements for backward compatibility across Linux distributions. Validating that zig cc produces identical or cleaner ABI boundaries than current sysroot setups would be a huge win.

• Embedded Dependencies (OpenSSL, zlib, libuv, v8):
  OpenSSL uses Perl scripts to emit platform assembly. Ensure zig cc is recognized as a Clang variant during deps/openssl configuration steps so assembler flags are passed cleanly.

---

2. Suggested Path Forward for a PoC

To test feasibility, running a PoC cross-compile for an architecture like aarch64-linux-gnu or riscv64-linux-gnu from an x64 host is the best first step.

An example invocation pattern to test in a PoC:

export CC="zig cc -target aarch64-linux-gnu"
export CXX="zig c++ -target aarch64-linux-gnu"
export CC_host="zig cc -target x86_64-linux-gnu"
export CXX_host="zig c++ -target x86_64-linux-gnu"

./configure \
  --dest-cpu=arm64 \
  --dest-os=linux \
  --cross-compiling

make -j$(nproc)

Comparing the resulting binary size, symbol exports (nm -g), glibc dependency versions (objdump -p | grep NEEDED), and running the standard test suite (make test-only) on target hardware/QEMU would provide solid benchmarks to share with the build working group.

---

Hope this provides useful context for initiating the discussion and PoC!

If this response provides helpful insights or a solid framework for your proposal, please consider marking it as the accepted as I need this a lot :)

[KoHaRxnP]

If this response provides helpful insights or a solid framework for your proposal, please consider marking it as the accepted as I need this a lot :)

Thank you for the detailed feedback regarding compatibility with gyp and V8. Before finalizing my response, I’d like to hear what others think about this integration, so I’ll keep this discussion open for a little while longer.

[KoHaRxnP]

Cross Compile

Based on the advice, I used the following command to build for ARM64, and the build was successful.

make clean || make distclean
rm -rf out/
unset CC CXX CFLAGS CXXFLAGS LDFLAGS CC_host CXX_host LDFLAGS_host
export CC="zig cc -target aarch64-linux-gnu"
export CXX="zig c++ -target aarch64-linux-gnu"
export CFLAGS="-D_GNU_SOURCE"
export CXXFLAGS="-include stdlib.h -D_GNU_SOURCE"
export LDFLAGS="/tmp/cpu_model_arm.o"
export CC_host="zig cc -target x86_64-linux-gnu"
export CXX_host="zig c++ -target x86_64-linux-gnu"
export LDFLAGS_host="/tmp/cpu_model_x86.o"
./configure \
  --dest-cpu=arm64 \
  --dest-os=linux \
  --cross-compiling
make -j4

To see if it actually works, I ran a quick test using QEMU, and the results are as follows.

user@wsl:~/node$ qemu-aarch64 -L /usr/aarch64-linux-gnu ./out/Release/node -v
v27.0.0-pre
user@wsl:~/node$ qemu-aarch64 -L /usr/aarch64-linux-gnu ./out/Release/node -e "console.log('Hello from Zig cross-compiled Node.js on ARM64')"
Hello from Zig cross-compiled Node.js on ARM64

Based on the above, it may be possible to easily cross-compile Node.js using zig as well.

[KoHaRxnP]

After building for the host environment and running make test-only, all 202 internal C++ core tests passed. However, during the subsequent parallel tests, it was discovered that the test item test-single-executable-application-asset—that is, the SEA test—could not be completed. We believe this is because the test was designed assuming the behavior of traditional linkers such as gcc and clang, whereas Zig uses a new, high-speed LLVM-based linker, which may result in slightly different alignment compared to conventional methods. Additionally, the “test-fs-rm” test also failed; however, since the test is being run on WSL, it is highly likely that this is due to a known behavior where ENOTEMPTY is returned instead of EACCES. Aside from these two issues, the remaining 4,644 tests passed without any problems. Therefore, it is safe to say that the only substantive issue in the parallel tests is the single SEA test.

[KoHaRxnP]

I also ran all the other suite tests. The results were as follows:

• cctest & parallel: As noted in my previous comment, the core functionality of the C++ layer works 100% correctly, and the sole failure (test-fs-rm) can likely be attributed to a WSL-specific difference in error codes (ENOTEMPTY vs. EACCES).
• abort / async-hooks / client-proxy / embedding / es-module / ffi / js-native-api / message / module-hooks / pseudo-tty / pummel / report / sequential / sqlite / test-runner / wasi / wasm-allocation / wpt, etc.: 100% PASS. All major core Node.js features—including ES Modules, AsyncHooks, WASI, SQLite, and Sequential—were confirmed to be functioning properly.
• sea: Crashed. This is the only substantive issue.
  It is believed that differences in binary section placement and alignment between zig cc (LLVM/lld) and traditional linkers (GCC/ld) are causing this issue.
• addons: 3 failures. This is likely due to bindings not being detected because C++ native add-ons were not pre-built using tools like node-gyp (this does not appear to be a build issue).
• doctool / benchmark: Failed. Errors occurred due to missing documentation output (out/doc/api/) and dependencies equivalent to npm install (such as unified) not being installed.
• internet: 3 failures. These may be due to the WSL network or IPv6 environment.
• node-api: 1 failure. This was a known flaky error caused by a timeout or count mismatch in test_uv_loop, influenced by timer precision issues in WSL and virtual environments.
• tick-processor: Timed out. This may have been caused by file I/O delays on WSL, which prevented the V8 profile log from being written in time, resulting in a log corruption error (BROKEN_PROFILE_FILE), but the exact cause is unclear.

[KoHaRxnP]

Dependencies on Shared Libraries

user@wsl:~/forks/node$ objdump -p out/Release/node | grep NEEDED
  NEEDED               libm.so.6
  NEEDED               libc.so.6
  NEEDED               ld-linux-x86-64.so.2
  NEEDED               libpthread.so.0
  NEEDED               libdl.so.2

Binary Size

Before Running strip

Permissions Size User     Date Modified Name
.rwxr-xr-x  1.3G korphere  4 Aug 15:17   out/Release/node

After Running strip

Permissions Size User     Date Modified Name
.rwxr-xr-x  113M korphere  4 Aug 18:12   out/Release/node

[KoHaRxnP]

Regarding the SEA issue, our investigation revealed that the problem lies within postject itself. It previously didn't handle non-default linker scenarios (such as LLD), as the tests and parsing logic were written under the strong assumption of a specific linker (ld).

I have submitted a pull request (#109) to fix this issue.

[KoHaRxnP]

Summary

Cross-compilation for aarch64 was successful, and after running the entire test suite in an x86_64 environment, nearly all tests passed; the only practical issue is an alignment problem with SEA. This is caused by hard-coding in postject; I have already submitted a pull request, but looking at the postject repository, the last push was three years ago, and it appears that it has not been maintained for several years. Therefore, it is considered more effective to apply a patch on the nodejs/node side. Additionally, the bundle size after stripping is 113 MB, which is nearly the same as that produced by gcc.

Translated with DeepL.com (free version)