Skip to content

Commit 79da145

Browse files
joyeecheungRafaelGSS
authored andcommitted
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: #57087 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
1 parent 792959d commit 79da145

File tree

1 file changed

+33
-7
lines changed

1 file changed

+33
-7
lines changed

BUILDING.md

Lines changed: 33 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ file a new issue.
3131
* [Building a debug build](#building-a-debug-build)
3232
* [Building an ASan build](#building-an-asan-build)
3333
* [Speeding up frequent rebuilds when developing](#speeding-up-frequent-rebuilds-when-developing)
34+
* [ccache](#ccache)
35+
* [Loading JS files from disk instead of embedding](#loading-js-files-from-disk-instead-of-embedding)
3436
* [Troubleshooting Unix and macOS builds](#troubleshooting-unix-and-macos-builds)
3537
* [Windows](#windows)
3638
* [Windows Prerequisites](#windows-prerequisites)
@@ -543,6 +545,8 @@ make test-only
543545

544546
#### Speeding up frequent rebuilds when developing
545547

548+
##### ccache
549+
546550
Tips: The `ccache` utility is widely used and should generally work fine.
547551
If you encounter any difficulties, consider disabling `mold` as a
548552
troubleshooting step.
@@ -578,17 +582,26 @@ export CXX="ccache c++" # add to ~/.zshrc or other shell config file
578582

579583
On Windows:
580584

581-
Tips: follow <https://github.com/ccache/ccache/wiki/MS-Visual-Studio>, and you
582-
should notice that obj file will be bigger the normal one.
585+
Follow <https://github.com/ccache/ccache/wiki/MS-Visual-Studio>, and you
586+
should notice that obj file will be bigger than the normal one.
583587

584-
First, install ccache, assume ccache install to c:\ccache, copy
585-
c:\ccache\ccache.exe to c:\ccache\cl.exe with this command
588+
First, install ccache. Assuming the installation of ccache is in `c:\ccache`
589+
(where you can find `ccache.exe`), copy `c:\ccache\ccache.exe` to `c:\ccache\cl.exe`
590+
with this command.
586591

587592
```powershell
588593
cp c:\ccache\ccache.exe c:\ccache\cl.exe
589594
```
590595

591-
When building Node.js provide a path to your ccache via the option
596+
With newer version of Visual Studio, it may need the copy to be `clang-cl.exe`
597+
instead. If the output of `vcbuild.bat` suggestion missing `clang-cl.exe`, copy
598+
it differently:
599+
600+
```powershell
601+
cp c:\ccache\ccache.exe c:\ccache\clang-cl.exe
602+
```
603+
604+
When building Node.js, provide a path to your ccache via the option:
592605

593606
```powershell
594607
.\vcbuild.bat ccache c:\ccache\
@@ -597,6 +610,14 @@ When building Node.js provide a path to your ccache via the option
597610
This will allow for near-instantaneous rebuilds when switching branches back
598611
and forth that were built with cache.
599612

613+
To use it with ClangCL, run this instead:
614+
615+
```powershell
616+
.\vcbuild.bat clang-cl ccache c:\ccache\
617+
```
618+
619+
##### Loading JS files from disk instead of embedding
620+
600621
When modifying only the JS layer in `lib`, it is possible to externally load it
601622
without modifying the executable:
602623

@@ -681,14 +702,19 @@ Optional requirements for compiling for Windows on ARM (ARM64):
681702
* Visual C++ ATL for ARM64
682703
* Windows 10 SDK 10.0.17763.0 or newer
683704

684-
Optional requirements for compiling with ClangCL:
705+
Optional requirements for compiling with ClangCL (search for `clang` in Visual Studio
706+
Installer's "individual component" tab):
685707

686-
* Visual Studio optional components
708+
* Visual Studio individual components
687709
* C++ Clang Compiler for Windows
688710
* MSBuild support for LLVM toolset
689711

690712
NOTE: Currently we only support compiling with Clang that comes from Visual Studio.
691713

714+
When building with ClangCL, if the output from `vcbuild.bat` shows that the components are not installed
715+
even when the Visual Studio Installer shows that they are installed, try removing the components
716+
first and then reinstalling them again.
717+
692718
##### Option 2: Automated install with WinGet
693719

694720
[WinGet configuration files](https://github.com/nodejs/node/tree/main/.configurations)

0 commit comments

Comments
 (0)