Add Windows prebuilt packaging docs

Author: 0xShug0

.gitignore

@@ -21,6 +21,7 @@ __pycache__/
 /target_proj/
 /nocommit/
 /perf/
+/windows_prebuild/
 /*.wav
 /flutter/
 /.cache/

README.md

@@ -184,6 +184,8 @@ make -f Makefile.windows cuda NATIVE_CPU=OFF JOBS=16
 
 The Windows script configures `build/windows-cuda-release` by default and builds `audiocpp_cli`. CUDA presets enable CUDA, CUDA graphs, OpenMP, Ninja, `/utf-8`, `/EHsc`, MSVC OpenMP SIMD support with `/openmp:experimental`, and native CPU optimization by default. The CPU preset uses the same MSVC/Ninja/OpenMP setup without requiring CUDA. CUDA presets auto-detect the local GPU CUDA architecture when `nvidia-smi` is available. Pass `-NativeCpu OFF` or `NATIVE_CPU=OFF` to use portable CPU kernels.
 
+For Windows prebuilt release zips and CPU compatibility profiles, see [docs/windows_build.md](docs/windows_build.md).
+
 Useful variants:
 
 ```powershell
@@ -588,6 +590,7 @@ The Python-reference side of these tests usually requires more time-consuming se
 ## Projects
 
 - [Pocket TTS Browser Engine](https://github.com/jjmlovesgit/pocket-tts-browser-engine) uses audio.cpp to bring fully local PocketTTS voices into Chrome and Edge through the browser TTS API.
+- [GuideAnts](https://github.com/Elumenotion/GuideAnts) uses audio.cpp as the default local AI stack path for basic ASR and TTS, with planned reusable skills for audio.cpp scenarios and model configurations.
 
 ## Performance Metrics
 

docs/windows_build.md

@@ -0,0 +1,105 @@
+# Windows Build and Prebuilt Packages
+
+This document covers native Windows builds and release zip packaging.
+
+## Requirements for Building
+
+- Visual Studio Build Tools 2022 or newer with the C++ desktop workload
+- MSVC x64 compiler, Windows SDK, CMake, Ninja, and MSVC OpenMP components
+- Official NVIDIA CUDA Toolkit for CUDA builds
+
+The Visual Studio IDE is not required.
+
+## Native Builds
+
+CPU:
+
+```powershell
+.\scripts\build_windows.ps1 -Preset windows-cpu-release -Target audiocpp_cli -Jobs 16
+.\scripts\build_windows.ps1 -Preset windows-cpu-release -Target audiocpp_server -Jobs 16
+```
+
+CUDA:
+
+```powershell
+.\scripts\build_windows.ps1 -Preset windows-cuda-release -Target audiocpp_cli -Jobs 16
+.\scripts\build_windows.ps1 -Preset windows-cuda-release -Target audiocpp_server -Jobs 16
+```
+
+The CUDA build also includes the CPU backend, so the same binary can run with `--backend cpu` or `--backend cuda`.
+
+## CPU Architecture Profiles
+
+The Windows build script supports explicit CPU architecture selection:
+
+```powershell
+.\scripts\build_windows.ps1 -Preset windows-cpu-release -Target audiocpp_cli -CpuArch native
+.\scripts\build_windows.ps1 -Preset windows-cpu-release -Target audiocpp_cli -CpuArch avx2
+.\scripts\build_windows.ps1 -Preset windows-cpu-release -Target audiocpp_cli -CpuArch baseline
+```
+
+| Profile | Build flag | Use when | Performance |
+| --- | --- | --- | --- |
+| Fast | `-CpuArch native` | You build for your own machine or machines with very similar CPUs. | Fastest, but may use AVX512 or other host-specific instructions. |
+| Balance | `-CpuArch avx2` | You want a good default for most modern Windows PCs. | Usually close to native on many systems, more compatible than native. |
+| Portable | `-CpuArch baseline` | You want the broadest compatibility. | Slowest, avoids AVX/AVX2/AVX512 selection. |
+
+`-NativeCpu ON/OFF` is still available for compatibility, but release packaging should prefer `-CpuArch`.
+
+## Prebuilt Release Zips
+
+Use the package script to build binaries, copy runtime DLLs, generate a package README, and create zips:
+
+```powershell
+.\scripts\package_windows_prebuilt.ps1 -Package all -Profile balance -Jobs 16
+```
+
+For CUDA packages, the package script uses a multi-architecture CUDA default derived from the installed CUDA Toolkit instead of the local GPU auto-detect path. This makes release zips more suitable for unknown Windows machines. Pass `-CudaArchitectures auto` only for a local machine-specific package.
+
+Package choices:
+
+```powershell
+.\scripts\package_windows_prebuilt.ps1 -Package cpu -Profile balance -Jobs 16
+.\scripts\package_windows_prebuilt.ps1 -Package cuda -Profile balance -Jobs 16
+```
+
+Release profiles:
+
+```powershell
+.\scripts\package_windows_prebuilt.ps1 -Package all -Profile fast -Jobs 16
+.\scripts\package_windows_prebuilt.ps1 -Package all -Profile balance -Jobs 16
+.\scripts\package_windows_prebuilt.ps1 -Package all -Profile portable -Jobs 16
+```
+
+Generated zips are written under `build/prebuilt`:
+
+```text
+build/prebuilt/audiocpp-windows-cpu-balance.zip
+build/prebuilt/audiocpp-windows-cuda-balance.zip
+```
+
+## Choosing a Release Profile
+
+For public releases, `balance` is the recommended default. It avoids native CPU selection while still using AVX2-class kernels for reasonable performance on modern Windows machines.
+
+Use `fast` only when you are comfortable with a machine-specific package. If the build machine has AVX512, the resulting binary may require AVX512.
+
+Use `portable` when compatibility matters more than speed. It disables llamafile SGEMM in addition to using the baseline CPU arch, because that is the safest path for unknown user machines.
+
+## Runtime Requirements for Users
+
+CPU package:
+
+- 64-bit Windows
+- Model files downloaded separately
+
+CUDA package:
+
+- 64-bit Windows
+- NVIDIA GPU with compute capability 7.5 or newer
+- NVIDIA driver 580 or newer
+- Model files downloaded separately
+
+The package script copies MSVC/OpenMP runtime DLLs into both packages. The CUDA package also copies the CUDA DLLs used by this build, so users should not need to install the CUDA Toolkit or Visual Studio Build Tools.
+
+The CUDA package is intended for RTX 20/30/40/50 series GPUs and similar NVIDIA datacenter GPUs. Older GPUs such as GTX 10-series Pascal cards or V100-class Volta cards are not covered by the CUDA 13 package; use the CPU package or build a separate package with an older CUDA Toolkit if those GPUs must be supported.

scripts/build_windows.ps1

@@ -6,6 +6,8 @@ param(
     [switch]$ConfigureOnly,
     [switch]$Clean,
     [string]$CudaArchitectures = "auto",
+    [ValidateSet("", "native", "avx2", "baseline")]
+    [string]$CpuArch = "",
     [ValidateSet("ON", "OFF")]
     [string]$NativeCpu = $null,
     [ValidateSet("ON", "OFF")]
@@ -219,6 +221,38 @@ function Add-MsvcEnvironment {
 }
 
 function Resolve-CudaArchitectures {
+    function Get-ReleaseCudaArchitectures {
+        $nvcc = Join-Path $env:CUDA_PATH "bin\nvcc.exe"
+        $supported = @()
+        if (Test-Path -LiteralPath $nvcc) {
+            $supported = & $nvcc --list-gpu-arch 2>$null
+        }
+
+        $wanted = @(
+            @{ Compute = "compute_75"; Arch = "75-virtual" },
+            @{ Compute = "compute_80"; Arch = "80-virtual" },
+            @{ Compute = "compute_86"; Arch = "86-real" },
+            @{ Compute = "compute_89"; Arch = "89-real" },
+            @{ Compute = "compute_120"; Arch = "120a-real" },
+            @{ Compute = "compute_121"; Arch = "121a-real" }
+        )
+
+        $archs = @()
+        foreach ($item in $wanted) {
+            if ($supported -contains $item.Compute) {
+                $archs += $item.Arch
+            }
+        }
+        if ($archs.Count -eq 0) {
+            $archs = @("75-virtual", "80-virtual", "86-real")
+        }
+        return ($archs -join ";")
+    }
+
+    if ($CudaArchitectures -eq "default" -or $CudaArchitectures -eq "ggml-default") {
+        return Get-ReleaseCudaArchitectures
+    }
+
     if ($CudaArchitectures -ne "" -and $CudaArchitectures -ne "auto") {
         return $CudaArchitectures
     }
@@ -254,6 +288,57 @@ function Assert-OpenMpConfigured {
     }
 }
 
+function Get-CpuArchSettings {
+    param([AllowEmptyString()][string]$Name)
+
+    switch ($Name) {
+        "" {
+            return @{
+                Label = "preset default"
+                Native = $null
+                CMakeArgs = @()
+            }
+        }
+        "native" {
+            return @{
+                Label = "native"
+                Native = "ON"
+                CMakeArgs = @()
+            }
+        }
+        "avx2" {
+            return @{
+                Label = "AVX2"
+                Native = "OFF"
+                CMakeArgs = @(
+                    "-DGGML_AVX=ON",
+                    "-DGGML_AVX2=ON",
+                    "-DGGML_AVX512=OFF",
+                    "-DGGML_AVX512_VBMI=OFF",
+                    "-DGGML_AVX512_VNNI=OFF",
+                    "-DGGML_AVX512_BF16=OFF",
+                    "-DGGML_AVX_VNNI=OFF"
+                )
+            }
+        }
+        "baseline" {
+            return @{
+                Label = "baseline"
+                Native = "OFF"
+                CMakeArgs = @(
+                    "-DGGML_AVX=OFF",
+                    "-DGGML_AVX2=OFF",
+                    "-DGGML_AVX512=OFF",
+                    "-DGGML_AVX512_VBMI=OFF",
+                    "-DGGML_AVX512_VNNI=OFF",
+                    "-DGGML_AVX512_BF16=OFF",
+                    "-DGGML_AVX_VNNI=OFF"
+                )
+            }
+        }
+    }
+}
+
 function Get-PresetSettings {
     param([Parameter(Mandatory = $true)][string]$Name)
 
@@ -313,10 +398,14 @@ function Get-PresetSettings {
 }
 
 $settings = Get-PresetSettings $Preset
-if ($null -ne $NativeCpu) {
+$cpuArchSettings = Get-CpuArchSettings $CpuArch
+if ($null -ne $cpuArchSettings.Native) {
+    $settings.Native = $cpuArchSettings.Native
+}
+if (-not [string]::IsNullOrEmpty($NativeCpu)) {
     $settings.Native = $NativeCpu
 }
-if ($null -ne $Llamafile) {
+if (-not [string]::IsNullOrEmpty($Llamafile)) {
     $settings.Llamafile = $Llamafile
 }
 $isCudaPreset = $settings.EnableCuda -eq "ON"
@@ -364,6 +453,7 @@ Write-Host "Windows SDK: $(Split-Path $mt -Parent)"
 if ($arch -ne "") {
     Write-Host "CUDA architectures: $arch"
 }
+Write-Host "CPU architecture profile: $($cpuArchSettings.Label)"
 Write-Host "Native CPU optimization: $($settings.Native)"
 Write-Host "llamafile SGEMM: $($settings.Llamafile)"
 
@@ -400,6 +490,7 @@ $configureArgs = @(
     "-DENGINE_ENABLE_LLAMAFILE=$($settings.Llamafile)",
     "-DENGINE_BUILD_TESTS=$($settings.BuildTests)"
 )
+$configureArgs += $cpuArchSettings.CMakeArgs
 if ($settings.CFlagsDebug -ne "") {
     $configureArgs += "-DCMAKE_C_FLAGS_DEBUG=$($settings.CFlagsDebug)"
 }
@@ -414,6 +505,8 @@ if ($isCudaPreset) {
 }
 if ($isCudaPreset -and $arch -ne "") {
     $configureArgs += "-DCMAKE_CUDA_ARCHITECTURES=$arch"
+} elseif ($isCudaPreset) {
+    $configureArgs += @("-U", "CMAKE_CUDA_ARCHITECTURES")
 }
 
 Invoke-Checked $cmake $configureArgs