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 an ASan build](#building-an-asan-build)
* [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)
* [Windows](#windows)
* [Windows Prerequisites](#windows-prerequisites)
@ -540,6 +542,8 @@ make test-only
#### Speeding up frequent rebuilds when developing
##### ccache
Tips: The `ccache` utility is widely used and should generally work fine.
If you encounter any difficulties, consider disabling `mold` as a
troubleshooting step.
@ -575,17 +579,26 @@ export CXX="ccache c++" # add to ~/.zshrc or other shell config file
On Windows:
Tips: follow <https://github.com/ccache/ccache/wiki/MS-Visual-Studio>, and you
should notice that obj file will be bigger the normal one.
Follow <https://github.com/ccache/ccache/wiki/MS-Visual-Studio>, and you
should notice that obj file will be bigger than the normal one.
First, install ccache, assume ccache install to c:\ccache, copy
c:\ccache\ccache.exe to c:\ccache\cl.exe with this command
First, install ccache. Assuming the installation of ccache is in `c:\ccache`
(where you can find `ccache.exe`), copy `c:\ccache\ccache.exe` to `c:\ccache\cl.exe`
with this command.
```powershell
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
.\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
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
without modifying the executable:
@ -678,14 +699,19 @@ Optional requirements for compiling for Windows on ARM (ARM64):
* Visual C++ ATL for ARM64
* 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
* MSBuild support for LLVM toolset
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
[WinGet configuration files](https://github.com/nodejs/node/tree/main/.configurations)