Merge bitcoin/bitcoin#32858: doc: Add workaround for vcpkg issue with paths with embedded spaces

0a1af44 doc: Add workaround for vcpkg issue with paths with embedded spaces (Hennadii Stepanov)

Pull request description:

  This PR is an alternative to bitcoin/bitcoin#32397 suggested in bitcoin/bitcoin#32397 (comment).

ACKs for top commit:
  sipsorcery:
    ACK 0a1af44.

Tree-SHA512: 09efc3f8b8c38eb8d8de1022c5b11685fba334cdb950209d35b3b0d907fa50de3f85f45c66ac3670b5b104d5bb0b01461c36a0c1e595327b5e62c6abca323deb

Author: fanquake

doc/build-windows-msvc.md

@@ -59,17 +59,6 @@ ctest --test-dir build --build-config Release  # Append "-j N" for N parallel te
 cmake --install build --config Release         # Optional.
 ```
 
-If building with `BUILD_GUI=ON`, vcpkg installation during the build
-configuration step might fail because of extremely long paths required during
-vcpkg installation if your vcpkg instance is installed in the default Visual
-Studio directory. This can be avoided without modifying your vcpkg root
-directory by changing vcpkg's intermediate build directory with the
-`--x-buildtrees-root` argument to something shorter, for example:
-
-```powershell
-cmake -B build --preset vs2022-static -DVCPKG_INSTALL_OPTIONS="--x-buildtrees-root=C:\vcpkg"
-```
-
 ### 5. Building with Dynamic Linking without GUI
 
 ```
@@ -78,9 +67,30 @@ cmake --build build --config Release           # Append "-j N" for N parallel jo
 ctest --test-dir build --build-config Release  # Append "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available.
 ```
 
+### 6. vcpkg-specific Issues and Workarounds
+
+vcpkg installation during the configuration step might fail for various reasons unrelated to Bitcoin Core.
+
+If the failure is due to a "Buildtrees path … is too long" error, which is often encountered when building
+with `BUILD_GUI=ON` and using the default vcpkg installation provided by Visual Studio, you can
+specify a shorter path to store intermediate build files by using
+the [`--x-buildtrees-root`](https://learn.microsoft.com/en-us/vcpkg/commands/common-options#buildtrees-root) option:
+
+```powershell
+cmake -B build --preset vs2022-static -DVCPKG_INSTALL_OPTIONS="--x-buildtrees-root=C:\vcpkg"
+```
+
+If vcpkg installation fails with the message "Paths with embedded space may be handled incorrectly", which
+can occur if your local Bitcoin Core repository path contains spaces, you can override the vcpkg install directory
+by setting the [`VCPKG_INSTALLED_DIR`](https://github.com/microsoft/vcpkg-docs/blob/main/vcpkg/users/buildsystems/cmake-integration.md#vcpkg_installed_dir) variable:
+
+```powershell
+cmake -B build --preset vs2022-static -DVCPKG_INSTALLED_DIR="C:\path_without_spaces"
+```
+
 ## Performance Notes
 
-### 6. vcpkg Manifest Default Features
+### 7. vcpkg Manifest Default Features
 
 One can skip vcpkg manifest default features to speedup the configuration step.
 For example, the following invocation will skip all features except for "wallet" and "tests" and their dependencies:
@@ -90,6 +100,6 @@ cmake -B build --preset vs2022 -DVCPKG_MANIFEST_NO_DEFAULT_FEATURES=ON -DVCPKG_M
 
 Available features are listed in the [`vcpkg.json`](/vcpkg.json) file.
 
-### 7. Antivirus Software
+### 8. Antivirus Software
 
 To improve the build process performance, one might add the Bitcoin repository directory to the Microsoft Defender Antivirus exclusions.