doc: update clang-cl on Windows building guide

- Mention that when the individual components cannot be found
  despite already being installed, try re-installing.
- Mention that with newer version of Visual Studio, ccache
  should be copied to `clang-cl.exe` instead.
- Mention how to use clang-cl with ccache

PR-URL: https://github.com/nodejs/node/pull/57087
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
This commit is contained in:
Joyee Cheung 2025-02-18 02:29:22 +01:00 committed by GitHub
parent 4afc136efa
commit b755ae1fe7
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -31,6 +31,8 @@ file a new issue.
* [Building a debug build](#building-a-debug-build) * [Building a debug build](#building-a-debug-build)
* [Building an ASan build](#building-an-asan-build) * [Building an ASan build](#building-an-asan-build)
* [Speeding up frequent rebuilds when developing](#speeding-up-frequent-rebuilds-when-developing) * [Speeding up frequent rebuilds when developing](#speeding-up-frequent-rebuilds-when-developing)
* [ccache](#ccache)
* [Loading JS files from disk instead of embedding](#loading-js-files-from-disk-instead-of-embedding)
* [Troubleshooting Unix and macOS builds](#troubleshooting-unix-and-macos-builds) * [Troubleshooting Unix and macOS builds](#troubleshooting-unix-and-macos-builds)
* [Windows](#windows) * [Windows](#windows)
* [Windows Prerequisites](#windows-prerequisites) * [Windows Prerequisites](#windows-prerequisites)
@ -540,6 +542,8 @@ make test-only
#### Speeding up frequent rebuilds when developing #### Speeding up frequent rebuilds when developing
##### ccache
Tips: The `ccache` utility is widely used and should generally work fine. Tips: The `ccache` utility is widely used and should generally work fine.
If you encounter any difficulties, consider disabling `mold` as a If you encounter any difficulties, consider disabling `mold` as a
troubleshooting step. troubleshooting step.
@ -575,17 +579,26 @@ export CXX="ccache c++" # add to ~/.zshrc or other shell config file
On Windows: On Windows:
Tips: follow <https://github.com/ccache/ccache/wiki/MS-Visual-Studio>, and you Follow <https://github.com/ccache/ccache/wiki/MS-Visual-Studio>, and you
should notice that obj file will be bigger the normal one. should notice that obj file will be bigger than the normal one.
First, install ccache, assume ccache install to c:\ccache, copy First, install ccache. Assuming the installation of ccache is in `c:\ccache`
c:\ccache\ccache.exe to c:\ccache\cl.exe with this command (where you can find `ccache.exe`), copy `c:\ccache\ccache.exe` to `c:\ccache\cl.exe`
with this command.
```powershell ```powershell
cp c:\ccache\ccache.exe c:\ccache\cl.exe cp c:\ccache\ccache.exe c:\ccache\cl.exe
``` ```
When building Node.js provide a path to your ccache via the option With newer version of Visual Studio, it may need the copy to be `clang-cl.exe`
instead. If the output of `vcbuild.bat` suggestion missing `clang-cl.exe`, copy
it differently:
```powershell
cp c:\ccache\ccache.exe c:\ccache\clang-cl.exe
```
When building Node.js, provide a path to your ccache via the option:
```powershell ```powershell
.\vcbuild.bat ccache c:\ccache\ .\vcbuild.bat ccache c:\ccache\
@ -594,6 +607,14 @@ When building Node.js provide a path to your ccache via the option
This will allow for near-instantaneous rebuilds when switching branches back This will allow for near-instantaneous rebuilds when switching branches back
and forth that were built with cache. and forth that were built with cache.
To use it with ClangCL, run this instead:
```powershell
.\vcbuild.bat clang-cl ccache c:\ccache\
```
##### Loading JS files from disk instead of embedding
When modifying only the JS layer in `lib`, it is possible to externally load it When modifying only the JS layer in `lib`, it is possible to externally load it
without modifying the executable: without modifying the executable:
@ -678,14 +699,19 @@ Optional requirements for compiling for Windows on ARM (ARM64):
* Visual C++ ATL for ARM64 * Visual C++ ATL for ARM64
* Windows 10 SDK 10.0.17763.0 or newer * Windows 10 SDK 10.0.17763.0 or newer
Optional requirements for compiling with ClangCL: Optional requirements for compiling with ClangCL (search for `clang` in Visual Studio
Installer's "individual component" tab):
* Visual Studio optional components * Visual Studio individual components
* C++ Clang Compiler for Windows * C++ Clang Compiler for Windows
* MSBuild support for LLVM toolset * MSBuild support for LLVM toolset
NOTE: Currently we only support compiling with Clang that comes from Visual Studio. NOTE: Currently we only support compiling with Clang that comes from Visual Studio.
When building with ClangCL, if the output from `vcbuild.bat` shows that the components are not installed
even when the Visual Studio Installer shows that they are installed, try removing the components
first and then reinstalling them again.
##### Option 2: Automated install with WinGet ##### Option 2: Automated install with WinGet
[WinGet configuration files](https://github.com/nodejs/node/tree/main/.configurations) [WinGet configuration files](https://github.com/nodejs/node/tree/main/.configurations)