DOCS(building): clarify Windows build & pre-built environments

docs/dev/build-instructions/README.md

@@ -3,11 +3,18 @@
 This documentation is version-specific. The current ``master`` branch contains the unstable code for a future release of Mumble.
 If you want to build an already released stable version of Mumble, use the respective branch.
 
+
+## Prerequisites
+
 A fundamental dependency for building Mumble is [git](https://git-scm.com/), so make sure you have it installed. If you are new to git, make sure to
 checkout [this guide](https://guides.github.com/introduction/git-handbook/) on git's basics in order to be able to follow the given instructions.
 
 Furthermore Mumble requires a **Cpp20**-conform compiler.
 
+You'll also need [`python`](https://www.python.org/downloads/). For detailed installation help, see [their Beginner's Guide](https://wiki.python.org/moin/BeginnersGuide(2f)Download.html).
+
+## Checkout the code
+
 The first step in building Mumble is to clone this repository and all the submodules via `git clone --depth 1 --recursive https://github.com/mumble-voip/mumble.git`.
 
 _Tip:_ You can also [build a specific version or commit](faq.md#build-a-specific-version-or-commit) of Mumble.

docs/dev/build-instructions/build_static.md

@@ -3,6 +3,7 @@
 These instructions are for creating a static build of Mumble. "Static" means that it bundles most (all) of its dependencies into the built library in
 order to make it run on systems that don't have the necessary dependencies installed.
 
+This will typically take 3 steps: installing dependencies, running the CMake generator, then building Mumble.
 
 ## Dependencies
 
@@ -19,7 +20,7 @@ In addition to the dependencies installed via vcpkg, you'll also need [cmake](ht
 cmake using a [PPA](https://apt.kitware.com/) and on macOS you can install it using [homebrew](https://formulae.brew.sh/formula/cmake).
 
 Furthermore you need a C++ compiler. On Linux and MacOS that'd usually be `gcc` (`g++`) or `clang`. On Windows you probably want to use MSVC
-(checkout [these instructions](setup_visual_studio.md) on how to install it).
+(check out [Setup Visual Studio](setup_visual_studio.md) on how to install it).
 
 
 ### Installing via script
@@ -34,9 +35,19 @@ If you already have vcpkg installed on your system, you should probably prefer u
 second vcpkg installation.
 
 
+### Using pre-built environments
+
+For common configurations, you can also use the [pre-built vcpkg environments](https://github.com/mumble-voip/vcpkg/releases) mentioned above instead of using the script.
+
+1. Download & unzip the appropriate environment from [the releases page](https://github.com/mumble-voip/vcpkg/releases).
+2. When using the `cmake` commands below, use the unzipped folder as `<vcpkg dir>` in the `-DCMAKE_TOOLCHAIN_FILE` and `-DIce_HOME` arguments. Use
+   the corresponding triplet for `-DVCPKG_TARGET_TRIPLET`. You'll also need to set `-Dbundled-cli11=OFF` and `-Dbundled-spdlog=OFF`
+
+For example, on Windows, after extracting `mumble_env.x64-windows-static-md.<hash>.7z` to `C:\mumble-env\`, `CMAKE_TOOLCHAIN_FILE` would be `C:\mumble-env\mumble_env.x64-windows-static-md.<hash>\scripts\buildsystems\vcpkg.cmake"`. (Replace `<hash>` with the commit hash in the filename, e.g. `b1fe4a4257`.)
+
 ### Manual installation
 
-Again, we advice to use our vcpkg fork. If you are using upstream vcpkg, you do not have access to a compatible version of ZeroC Ice, so you'll have
+Again, we advise you to use our vcpkg fork or pre-built environments. If you are using upstream vcpkg, you do not have access to a compatible version of ZeroC Ice, so you'll have
 to disable that when building the server.
 
 The current list of vcpkg packages required to build Mumble can be found at https://github.com/mumble-voip/vcpkg/blob/master/mumble_dependencies.txt.
@@ -84,6 +95,13 @@ The following is required for macOS:
 * `Xquartz`
 
 
+### Additional dependencies on Windows
+
+The following is required for Windows:
+
+* `python` (`winget install --id=Python.Python.3.13 -e`)
+
+
 ## Building Mumble
 
 After all dependencies are installed, you can follow these steps in order to actually build Mumble itself:
@@ -101,45 +119,8 @@ cmake will generate a bunch of files so you should call it from a dedicated, emp
 
 #### Windows caveats
 
-On Windows you can't use the default command-prompt (as is) as it won't have the needed development tools in its PATH. Instead you have to use
-a "Developer Command Prompt". You can find it by searching in the start-menu. If you are on a 64bit system, then special care must be taken
-that you use a "x64" version of the Developer Prompt (often these are then called "x64 Native Tools Command Prompt"). The easiest way to get a hold of
-the correct command prompt is to search for "x64" and usually that is enough to bring up the x64 developer prompt in the search results.
-
-Note also that you **have** to use the command prompt and **not** the Developer Powershell as the latter is always 32bit only.
-
-If you are on a 64bit system, then you'll know that you have opened the correct prompt, if it prints `Environment initialized for: 'x64'`.
-
-However, you can use powershell 64bit if you run the following script prior to cmake. You can either run it as required, or include it in your powershell profile. 
-
-```powershell
-# Based on the version of Visual Studio you have installed, the VC++ tools will be in a specific location.
-# Using the "x64 Native Tools Command Prompt" shortcut referenced above, you can find the root folder by viewing the properties of the shortcut.
-
-# e.g. Visual Studio 2015 path
-# "${Env:PROGRAMFILES(X86)}\Microsoft Visual Studio 14.0\VC\"
+On Windows you can't use the default command-prompt (as is) as it won't have the needed development tools in its PATH. See [Setup Visual Studio](setup_visual_studio.md) for simple ways to access the development tools.
 
-# e.g. Vistual Studio 2019 path
-# "${Env:PROGRAMFILES(X86)}\Microsoft Visual Studio\2019\Professional\VC\Auxiliary\Build\"
-
-# Here we're using VS 2015.
-$vcToolsPath = "${Env:PROGRAMFILES(X86)}\Microsoft Visual Studio 14.0\VC\"
-
-# Shift context to VS
-Push-Location $vcToolsPath
-
-$architecture = 'x64' # amd64 and x64 resolve to the same path in vcvarsall.bat and are interchangeable.
-
-# Have vcvarsall.bat load the 64 bit environment variables.
-cmd /c "vcvarsall.bat $architecture&set" |
-foreach {
-	if ($_ -match "=") {
-		$v = $_.split("="); set-item -force -path "ENV:\$($v[0])"  -value "$($v[1])"
-	}
-}
-# Go back to where we were before.
-Pop-Location
-```
 
 #### CMake Generator
 
@@ -151,35 +132,78 @@ Important configuration options
 | `CMAKE_TOOLCHAIN_FILE` | `<vcpkg_root>/scripts/buildsystems/vcpkg.cmake` | |
 | `Ice_HOME` | `<vcpkg dir>/installed/x64-windows-static-md` | Required if you build with Ice (enabled by default) |
 | `static` | `ON` | |
+| `bundled-cli11` and<br />`bundled-spdlog`|`OFF`|Required when using pre-built environments from after 2026-02. Without these flags, linker errors for unresolved CLI11/spdlog/fmt symbols will occur. See [common build errors](common_build_errors.md)|
 
-`<vcpkg dir>` is a placeholder for your prepared build environment vcpkg setup (the path to the vcpkg directory created by the get_dependency script).
+`<vcpkg dir>` is a placeholder for your prepared build environment vcpkg setup (the path to the vcpkg directory created by the get_dependency script, or the path to your pre-built environment).
 
-For Linux the cmake invokation may be (using the default generator `make`)
+For Linux the cmake invokation may be (using the default generator `make`):
 
 ```bash
-cmake "-DVCPKG_TARGET_TRIPLET=x64-linux" "-Dstatic=ON" "-DCMAKE_TOOLCHAIN_FILE=<vcpkg dir>/scripts/buildsystems/vcpkg.cmake" "-DIce_HOME=<vcpkg dir>/installed/x64-linux" "-DCMAKE_BUILD_TYPE=Release" ..
+# From your build/ directory
+cmake \
+      "-DVCPKG_TARGET_TRIPLET=x64-linux" \
+      "-Dstatic=ON" \
+      "-DCMAKE_TOOLCHAIN_FILE=<vcpkg dir>/scripts/buildsystems/vcpkg.cmake" \
+      "-DIce_HOME=<vcpkg dir>/installed/x64-linux" \
+      "-DCMAKE_BUILD_TYPE=Release" \
+      "-Dbundled-cli11=OFF" \
+      "-Dbundled-spdlog=OFF" \
+      ..
 ```
 
-For macOS the command may be
+For macOS the command may be:
 ```bash
-cmake "-DVCPKG_TARGET_TRIPLET=x64-osx" "-Dstatic=ON" "-DCMAKE_TOOLCHAIN_FILE=<vcpkg dir>/scripts/buildsystems/vcpkg.cmake" "-DIce_HOME=<vcpkg dir>/installed/x64-osx" "-DCMAKE_BUILD_TYPE=Release" ..
+# From your build/ directory
+cmake \
+      "-DVCPKG_TARGET_TRIPLET=x64-osx" \
+      "-Dstatic=ON" \
+      "-DCMAKE_TOOLCHAIN_FILE=<vcpkg dir>/scripts/buildsystems/vcpkg.cmake" \
+      "-DIce_HOME=<vcpkg dir>/installed/x64-osx" \
+      "-DCMAKE_BUILD_TYPE=Release" \
+      "-Dbundled-cli11=OFF" \
+      "-Dbundled-spdlog=OFF" \
+      ..
 ```
 
-For Windows the command may be
+For Windows the command may be:
 
-```bash
-cmake -G "NMake Makefiles" "-DVCPKG_TARGET_TRIPLET=x64-windows-static-md" "-Dstatic=ON" "-DCMAKE_TOOLCHAIN_FILE=<vcpkg_root>/scripts/buildsystems/vcpkg.cmake" "-DIce_HOME=<vcpkg_root>/installed/x64-windows-static-md" "-DCMAKE_BUILD_TYPE=Release" ..
+```powershell
+# From your build/ directory
+# See note about using `-G "Ninja"` instead.
+cmake -G "NMake Makefiles" `
+      "-DVCPKG_TARGET_TRIPLET=x64-windows-static-md" `
+      "-Dstatic=ON" `
+      "-DCMAKE_TOOLCHAIN_FILE=<vcpkg dir>/scripts/buildsystems/vcpkg.cmake" `
+      "-DIce_HOME=<vcpkg dir>/installed/x64-windows-static-md" `
+      "-DCMAKE_BUILD_TYPE=Release" `
+      -Dbundled-cli11=OFF `
+      -Dbundled-spdlog=OFF `
+      ..
 ```
 
 Optionally you can use `-G "Ninja"` to use the [Ninja buildsystem](https://ninja-build.org/) (which probably has to be installed separately).
 Especially on Windows this is recommended as the default `NMake Makefiles` only compile using a single thread (which takes quite a while).
 
+> [!NOTE]
+> If you ran previous builds that failed with missing dependencies, you may need to delete and recreate your `build/` directory before trying new approaches, or CMake will continue to struggle finding dependencies.
 
 ### Customizing the build
 
 There are various options that can be passed to cmake when performing step 6 from above. See [here](cmake_options.md) for details.
 
 
+### Building
+
+Finally, you're ready to build. From your `build/` directory:
+
+```bash
+# Or invoke your buildsystem of choice directly (e.g. `make -j $(nproc)`)
+cmake --build .
+```
+
+As you edit C++, you only need to rerun this one step to rebuild Mumble.
+
+
 ## Troubleshooting
 
 See also our [general build FAQ](faq.md) if your problem is not listed below.

docs/dev/build-instructions/build_windows.md

@@ -1,5 +1,3 @@
 # Building on Windows 
 
-On Windows we only support [static builds](build_static.md).
-
-Make sure to [install Visual Studio](setup_visual_studio.md) in order to be able to compile the necessary code.
+On Windows we only support [static builds](build_static.md). You will need to [set up Visual Studio](setup_visual_studio.md) first.

docs/dev/build-instructions/common_build_errors.md

@@ -6,3 +6,5 @@ This page is supposed to give a summary of the most common build errors that are
 | ------------- | ------------------- |
 | inlining failed in call to always_inline ‘vdupq_n_f32’: target specific option mismatch | This error message occurs when attempting to build Opus. It seems to be an issue specific to the Raspberry Pi (4) (or maybe to ARM in general). This is a [known problem in Opus](https://github.com/xiph/opus/issues/203).<br><br>It can be fixed relatively easy by specifying `-DOPUS_DISABLE_INTRINSICS=ON` when invoking CMake. |
 |CMake Error at cmake/qt-utils.cmake:6 (include):<br>  include could not find requested file:<br><br>    FindPythonInterpreter<br>Call Stack (most recent call first):<br> <br>src/murmur/CMakeLists.txt:16 (include) | Submodules are outdated<br> Run the command 'git submodule update --init' |
+|CMake Error at cmake/qt-utils.cmake:6 (include):<br>  include could not find requested file:<br><br>    CompilerFlags<br>Call Stack (most recent call first):<br> <br>CMakeLists.txt:92 (include) |Same as above|
+| `error LNK2001: unresolved external symbol` for CLI11, spdlog, or fmt symbols (e.g. `CLI::App`, `spdlog::logger`, `fmt::v12::vformat`) when using a pre-built vcpkg environment | The pre-built vcpkg environments (2026-02 and later) ship CLI11, spdlog, and fmt as **compiled static libraries** rather than header-only. Mumble's CMake defaults (`bundled-cli11=ON`, `bundled-spdlog=ON`) activate the vendored header-only versions, but the vcpkg include paths still leak in and reference compiled symbols that aren't linked.<br><br>Fix: disable the bundled versions so CMake uses the vcpkg compiled targets instead:<br>`cmake ... -Dbundled-cli11=OFF -Dbundled-spdlog=OFF` |

docs/dev/build-instructions/faq.md

@@ -1,5 +1,7 @@
 # Build FAQ
 
+For common compilation errors, see [common build errors](./common_build_errors.md).
+
 ### How to speed up the compilation
 
 Mumble supports being compiled as a [unity build](https://en.wikipedia.org/wiki/Unity_build), if you are using cmake 3.16 or newer. To use this

docs/dev/build-instructions/setup_visual_studio.md

@@ -1,8 +1,71 @@
 # Setup Visual Studio
 
-MSVC (Microsoft Visual C++) is Microsoft’s C++ compiler toolchain. It can be installed from Visual Studio Build Tools, or Visual Studio Community.
-Either can be downloaded [here](https://visualstudio.microsoft.com/downloads) (Any somewhat recent version should work).
+MSVC (Microsoft Visual C++) is Microsoft’s C++ compiler toolchain. It can be installed via the **Visual Studio Build Tools** or **Visual Studio Community**.
+Either can be downloaded at [visualstudio.microsoft.com/downloads](https://visualstudio.microsoft.com/downloads) (any somewhat recent version should work).
 
-Make sure to select the **C++ build tools** (or Development, respectively) and "**C++ MFC for latest v14[X] build tools**" (just pick the latest
-version - e.g.v142). vcpkg also requires the **English Language pack** which is found in the Language packs section of the Visual Studio Installer.
+In the Visual Studio Installer, make sure to select:
 
+*  **C++ build tools** (or Development, respectively)
+* "**C++ MFC for latest v14[X] build tools**" (just pick the latest version - e.g.v142).
+
+vcpkg also requires the **English Language pack** which is found in the Language packs section of the Visual Studio Installer.
+
+## Using MSVC
+
+Unlike most macOS or Linux tools, the MSVC build tools don't get added to the PATH by default, so you can't simply call the compiler like `cl.exe`. Instead, you need to run a script (part of Visual Studio) to add them to your PATH.
+
+The easiest way to do this, for a PowerShell window on a 64-bit machine, is to run `vcvars64.bat`:
+
+```powershell
+# Based on the version of Visual Studio you have installed, the VC++ tools will be in a specific location.
+# 
+# You can find them using `vswhere.exe`, which ships with all versions of VS since 2017
+# and is always in the same location.
+$vswhere = "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe"
+
+# e.g. Visual Studio 2015 path
+# "${Env:PROGRAMFILES(X86)}\Microsoft Visual Studio 14.0\VC\"
+# e.g. Visual Studio 2019 path
+# "${Env:PROGRAMFILES(X86)}\Microsoft Visual Studio\2019\Professional\VC\Auxiliary\Build\"
+$vcvars64 = . $vswhere -latest -products * -find "VC\Auxiliary\Build\vcvars64.bat"
+
+# Load vcvars64.bat into your PowerShell window.
+cmd /c "`"$vcvars64`" && set" |
+    ForEach-Object {
+        if ($_ -match "^([^=]+)=(.*)$") { [System.Environment]::SetEnvironmentVariable($matches[1], $matches[2]) }
+    }
+```
+
+This updates your current PowerShell window to let you use the MSVC build tools to build for x64. You can add it to your PowerShell profile, or you can simply run it as needed.
+
+See MSDN's [Use the Microsoft C++ Build Tools from the command line](https://learn.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170).
+
+### Alternatives
+
+You can also use [prebuilt shortcuts](https://learn.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#developer_command_prompt_shortcuts) like **x64 Native Tools Command Prompt**, which you can find in the Start menu after installing the MSVC.
+
+These have some caveats that recommend using the `vcvars64.bat` or `vcvarsall.bat` technique instead: only **x64 Native Tools Command Prompt** supports building in 64-bit, but it is CMD, not PowerShell. The **Developer Powershell** shortcut is 32-bit only. If you are on a 64bit system, then you'll know that you have opened the correct prompt, if it prints `Environment initialized for: 'x64'`.
+
+You can also use `vcvarsall.bat`, with args, instead of `vcvars64.bat`, to set up different environments:
+
+```powershell
+# Find the path for `vcvarsall.bat`, as before:
+$vswhere = "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe"
+$vcvarsall = . $vswhere -latest -products * -find "VC\Auxiliary\Build\vcvarsall.bat"
+$vcToolsPath = Split-Path $vcvarsall
+
+# Shift context to VS
+Push-Location $vcToolsPath
+
+$architecture = 'x64' # amd64 and x64 resolve to the same path in vcvarsall.bat and are interchangeable.
+
+# Have vcvarsall.bat load the 64 bit environment variables.
+cmd /c "vcvarsall.bat $architecture&set" |
+foreach {
+	if ($_ -match "=") {
+		$v = $_.split("="); set-item -force -path "ENV:\$($v[0])"  -value "$($v[1])"
+	}
+}
+# Go back to where we were before.
+Pop-Location
+```