Update WindowsPort.md as per #129 and other advisories

docs/Ports/WindowsPort.md

@@ -3,33 +3,44 @@
 It is using [cairo](https://www.cairographics.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).
 
+If 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.
+
 [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.
+`build-webkit` script creates a symlink to a generated compile_commands.json.
 
 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.
+- 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.
+- CMake 4+ has [a downstream problem for vcpkg woff2 at the moment](https://github.com/WebKit/Documentation/issues/129). Use CMake 3.x.
 
 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
+# Use the latest 3.x version of CMake available
+choco search -e cmake -a
+choco install -y cmake --version=3.x.x
+choco pin add --name="'cmake'" --version="'3.x.x'" --reason="'WebKit downstream issue building woff2 with vcpkg requires CMake < 4'"
 ```
 
 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
 ```
 
@@ -73,6 +84,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,6 +100,9 @@ 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"
 cd %~dp0
 start powershell