Update WindowsPort.md as per #129 and other advisories

docs/Ports/WindowsPort.md

@@ -1,35 +1,42 @@
 # Windows port
 
-It is using [cairo](https://www.cairographics.org/) for the graphics backend, [libcurl](https://curl.se/libcurl/) for the network backend.
+It is using [skia](https://skia.org/) for the graphics backend, [libcurl](https://curl.se/libcurl/) for the network backend.
 It supports only 64 bit Windows.
 
+## Cloning Webkit
+Ensure that you are NOT cloning under an ancestor directory that is a git repository. This may confuse the `build-webkit` script and result in failure.
+A shallow clone of the WebKit repository at a detached hash may work if you are just building and not intending to develop WebKit. Official Apple release tags are unlikely to work.
+
 ## Installing Development Tools
 
-Install [the latest Visual Studio with "Desktop development with C++" workload](https://learn.microsoft.com/en-us/cpp/build/vscpp-step-0-installation).
+Install [the latest Visual Studio with "Desktop development with C++" workload](https://learn.microsoft.com/en-us/cpp/build/vscpp-step-0-installation). Ensure that "vcpkg" has been included. 
 
-[Activate Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development#activate-developer-mode).
-build-webkit script creates a symlink to a generated compile_commands.json.
+If you have included *C++ Clang Tools for Windows* for the workload, it's Llvm will take precedence and the build may fail. For this scenario, explicitilty provide the full path to an alternative Windows Llvm's `clang-cl.exe` in the Webkit Command Prompt script.
 
-Install CMake, Perl, Python, Ruby, gperf \([GnuWin32 Gperf](https://gnuwin32.sourceforge.net/packages/gperf.htm)\), LLVM, and Ninja.
-Python 3.12 has [a problem for WebKit at the moment](https://webkit.org/b/261113). Use Python 3.11.
+[Activate Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development#activate-developer-mode).
+`build-webkit` script creates a symlink to a generated compile_commands.json.
 
+Install Perl, Python, Ruby, gperf \([GnuWin32 Gperf](https://gnuwin32.sourceforge.net/packages/gperf.htm)\), LLVM, and Ninja.
+- Python 3.12+ potentially has [a problem for WebKit in some contexts](https://webkit.org/b/261113). Use Python 3.11.x if you experience issues.
+- We use CMake 3.x that is bundled with the "Desktop development with C++" workload. Downstream vcpkg Woff2 has problems compiling with CMake 4+.
+
 You can use [Chocolatey](https://community.chocolatey.org/) to install the tools.
 [ActivePerl chocolatey package](https://community.chocolatey.org/packages/ActivePerl) has a problem and no package maintainer now.
 XAMPP includes Perl, and running layout tests needs XAMPP. Install XAMPP instead.
 
-```
-choco install -y xampp-81 python311 ruby git cmake gperf llvm ninja
+```powershell
+choco install -y xampp-81 python ruby git gperf llvm ninja
 ```
 
 Install pywin32 Python module for run-webkit-tests and git-webkit.
 
-```
+```powershell
 python -m pip install pywin32
 ```
 
 Windows Git enables `autocrlf` by default. But, some layout tests files have to be checked out as LF line end style. See [Bug 240158](https://bugs.webkit.org/show_bug.cgi?id=240158).
 
-```
+```powershell
 git config --global core.autocrlf input
 ```
 
@@ -39,7 +46,7 @@ If you prefer [WinGet](https://learn.microsoft.com/en-us/windows/package-manager
 Invoke the following command in an elevated PowerShell or cmd prompt.
 
 ```
-winget install --scope=machine --id Git.Git Kitware.CMake Ninja-build.Ninja Python.Python.3.11 RubyInstallerTeam.Ruby.3.2 ApacheFriends.Xampp.8.2 LLVM.LLVM
+winget install --scope=machine --id Git.Git Ninja-build.Ninja Python.Python.3.11 RubyInstallerTeam.Ruby.3.2 ApacheFriends.Xampp.8.2 LLVM.LLVM
 winget install --id GnuWin32.Gperf
 ```
 
@@ -62,7 +69,6 @@ cd %~dp0
 
 path C:\xampp\apache\bin;%path%
 path C:\xampp\perl\bin;%path%
-path %ProgramFiles%\CMake\bin;%path%
 path %ProgramFiles(x86)%\Microsoft Visual Studio\Installer;%path%
 for /F "usebackq delims=" %%I in (`vswhere.exe -latest -property installationPath`) do set VSPATH=%%I
 
@@ -73,6 +79,8 @@ set DUMPRENDERTREE_TEMP=%TEMP%
 
 set CC=clang-cl
 set CXX=clang-cl
+rem set CC=<path-to-llvm>\clang-cl.exe
+rem set CXX=<path-to-llvm>\clang-cl.exe
 
 rem set http_proxy=http://your-proxy:8080
 rem set https_proxy=%http_proxy%
@@ -87,7 +95,13 @@ rem set JSC_useDOMJIT=0
 rem You can show check TextureMapper FPS via WEBKIT_SHOW_FPS.
 rem set WEBKIT_SHOW_FPS=1
 
+rem You can use ccache with pre-compiled headers @see https://ccache.dev/manual/latest.html#_precompiled_headers
+rem set CCACHE_SLOPPINESS=pch_defines,time_macros,include_file_mtime,include_file_ctime
+
 call "%VSPATH%\VC\Auxiliary\Build\vcvars64.bat"
+rem Set PATH to use the VS toolchain bundled CMake 3.x. This ensures that downstream vcpkg builds will succeed.
+path %DevEnvDir%CommonExtensions\\Microsoft\\CMake\\CMake\\bin;%path%
+
 cd %~dp0
 start powershell
 ```