Recently Node.js started to support building with clang-cl on Windows. I happened to have the chance to try it out this week and while it still needs some fixups in my case, it’s mostly working very well now. Here are some notes about this.

Background

A hand-wavy recount about how Node.js got here: for a long time (or, as far as I could remember since I started contributing to Node.js in 2016), the official Node.js release for Windows has been built with MSVC, similar to what V8 used to be built with. At some point V8 followed Chromium and switched fully to clang-cl on all platforms, including Windows, while accepting patches from embedders like Node.js to make it at least buildable with MSVC. Last September V8 followed Chromium again and dropped support for MSVC completely from V8 13.0, which means stopping to accept this kind of MSVC compatibility patches in the upstream, so that also makes it a bit more urgent for Node.js to at least start making the clang-cl build work.

There had been some earlier attempts in Node.js to switch to clang-cl since V8 made the switch, including this PR in 2020. Like most things in Node.js, this is mostly based on efforts from volunteers so it took a long time to come to fruition. Thanks to the collaboration among contributors including Michaël Zasso, Stefan Stojanovic and Daniel Lemire et al., the clang-cl build of Node.js started to take shape in late 2024 and was added to the Node.js pull request CI.

This week I happened to be helping out with the V8 13.3 upgrade in Node.js, which ran into a compilation error with clang-cl in the CI, among other issues. So I took the chance to try out the new clang-cl build locally on my less-used Windows machine.

Installing the toolchain

Installing clang-cl

As documented in the building guide, we need Visual Studio 2022 Community Edition installed with these components:

  • C++ Clang Compiler for Windows
  • MSBuild support for LLVM (clang-cl) toolset

I already had these installed some time ago, but for some reason, when I tried to build Node.js with clang-cl it didn’t just work, and the build commands were complaining that the components mentioned above were not installed, even though when I opened the Visual Studio Installer these components were clearly listed as installed. So I tried the universal magic trick - just reinstall them! :P This indeed fixed the issue for me, and I’ll list what I did:

  1. Open the Visual Studio Installer. Update to the latest version of Visual Studio 2022 Community Edition. (This alone didn’t fix it for me).
  2. Open the Visual Studio Installer again after the update. Click “Modify” for Visual Studio 2022 Community Edition, go to the “Individual components” tab, search for “clang” to find the two components mentioned above, and uncheck them. Then click “Modify” on the bottom-right to uninstall them.
  3. Re-install the two components by doing something similar to step 2, just this time they are checked instead of being unchecked.

Installing ccache

Thanks to Stefan there’s now also support for ccache on Windows. To install ccache, I just downloaded the zip file from ccache’s download page, and decompressed it to a path.

Using the Git Bash tools that are also needed to build Node.js on Windows:

1
2
3
4
5
6
7
cd C:\Users\joyee
wget -O wget https://github.com/ccache/ccache/releases/download/v4.10.2/ccache-4.10.2-windows-x86_64.zip -O ccache.zip
tar -xf ccache.zip
mv ccache-4.10.2-windows-x86_64 ccache
rm ccache.zip
cd ccache
cp ccache.exe clang-cl.exe

Note that while the ccache Visual Studio installation guide suggested to copy ccache.exe to cl.exe, when I tried to build Node.js with it locally the commands mentioned that they could not find clang-cl.exe, so that was what I copied to instead (it’s a copy instead of a symlink probably because on Windows creating symlinks requires administrator privileges which is a bit of a hassle. In any case, copying just works as well). It may have something to do with the version of the toolchain that I was using, since I used something more up-to-date after the full update mentioned before.

And then I just added C:\Users\joyee\ccache to the Path environment variable on Windows via the control panel.

Building Node.js with clang-cl

I have the Node.js repository checked out in C:\Users\joyee\node. And this was what I ran:

1
2
cd C:\Users\joyee\node
.\vcbuild.bat clang-cl ccache C:\Users\joyee\ccache\

It ran the configure script which showed that I was using clang-cl 19.1.1. And voilà, it built just fine!

So I didn’t actually reproduce the error I saw in the CI, which was using clang-cl 18.1.8, though I still managed to figure out how to fix it by looking at the compilation error. But anyway, it was a nice experiment to figure out how to build it with clang-cl, and would be useful when I need to do this again when another Windows issue comes up - I’ll probably stop using MSVC and switch to building with clang-cl on Windows from now on.