From 377f6dfebaea174499e34cf1f8914f44b8e11a6e Mon Sep 17 00:00:00 2001
From: Jan Svabenik <jan@svabi.ch>
Date: Thu, 19 Mar 2026 09:10:30 +0100
Subject: [PATCH] docs: document Windows CGO toolchain limits

---
 build-windows-cuda-app.ps1    |  2 +-
 build-windows-default.ps1     | 14 +++++++++++
 docs/build-cuda.md            |  2 +-
 docs/windows-cgo-msvc-note.md | 46 +++++++++++++++++++++++++++++++++++
 4 files changed, 62 insertions(+), 2 deletions(-)
 create mode 100644 build-windows-default.ps1
 create mode 100644 docs/windows-cgo-msvc-note.md

diff --git a/build-windows-cuda-app.ps1 b/build-windows-cuda-app.ps1
index d540661..6b94a06 100644
--- a/build-windows-cuda-app.ps1
+++ b/build-windows-cuda-app.ps1
@@ -24,7 +24,7 @@ powershell -ExecutionPolicy Bypass -File tools\build-gpudemod-kernel.ps1
 if ($LASTEXITCODE -ne 0) { throw "kernel build failed" }
 
 Write-Host "Building Windows CUDA app with MSVC-oriented CGO path..." -ForegroundColor Cyan
-Write-Host "NOTE: This path is experimental. Go's CGO runtime still emits GCC-style warning flags that MSVC rejects in this environment." -ForegroundColor Yellow
+Write-Host "NOTE: This path is experimental. In this environment even 'go build runtime/cgo' emits GCC-style flags that MSVC rejects." -ForegroundColor Yellow
 & cmd.exe /c "call `"$vcvars`" && go build -x -tags `"sdrplay,cufft`" ./cmd/sdrd"
 if ($LASTEXITCODE -ne 0) {
   throw "windows cuda app build failed (current blocker: Go CGO emits GCC-style flags that cl.exe rejects, e.g. -Werror / -Wall / -fno-stack-protector)"
diff --git a/build-windows-default.ps1 b/build-windows-default.ps1
new file mode 100644
index 0000000..e21f615
--- /dev/null
+++ b/build-windows-default.ps1
@@ -0,0 +1,14 @@
+$ErrorActionPreference = 'Stop'
+
+$gcc = 'C:\msys64\mingw64\bin'
+if (-not (Test-Path (Join-Path $gcc 'gcc.exe'))) {
+  throw "gcc not found at $gcc"
+}
+
+$env:PATH = "$gcc;" + $env:PATH
+$env:CGO_ENABLED = '1'
+
+Write-Host "Building default Windows app path (no CUDA artifact integration assumptions)..." -ForegroundColor Cyan
+go build ./cmd/sdrd
+if ($LASTEXITCODE -ne 0) { throw "default windows build failed" }
+Write-Host "Done." -ForegroundColor Green
diff --git a/docs/build-cuda.md b/docs/build-cuda.md
index b6c92ad..66e994a 100644
--- a/docs/build-cuda.md
+++ b/docs/build-cuda.md
@@ -44,4 +44,4 @@ Prefer a GCC/NVCC-oriented build path:
 - `go test -tags cufft ./internal/demod/gpudemod` passes with NVCC/MSVC setup
 - `build-sdrplay.ps1` has progressed past the original invalid `#cgo LDFLAGS` issue
 - Remaining Windows blocker in the default path is a toolchain mismatch between MSVC-built CUDA artifacts and MinGW final linking
-- Experimental full-MSVC CGO path (`build-windows-cuda-app.ps1`) also currently blocks because Go's CGO runtime emits GCC-style flags (`-Wall`, `-Werror`, `-fno-stack-protector`) that `cl.exe` rejects in this environment
+- Experimental full-MSVC CGO path (`build-windows-cuda-app.ps1`) also currently blocks because even `go build runtime/cgo` emits GCC-style flags (`-Wall`, `-Werror`, `-fno-stack-protector`) that `cl.exe` rejects in this environment; this is a toolchain/Go integration issue, not a project-specific one
diff --git a/docs/windows-cgo-msvc-note.md b/docs/windows-cgo-msvc-note.md
new file mode 100644
index 0000000..8eb850f
--- /dev/null
+++ b/docs/windows-cgo-msvc-note.md
@@ -0,0 +1,46 @@
+# Windows CGO + MSVC note
+
+## Verified blocker
+
+On this machine, with:
+
+- Go on Windows
+- `CC=cl.exe`
+- `CXX=cl.exe`
+- Visual Studio 2019 Build Tools environment loaded via `vcvars64.bat`
+
+The following already fails before project code is involved:
+
+```powershell
+cmd /c "call \"C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat\" && set CC=cl.exe && set CXX=cl.exe && set CGO_ENABLED=1 && go build -x runtime/cgo"
+```
+
+Failure shape:
+
+- Go/cgo invokes `cl.exe`
+- but still passes GCC-style flags such as:
+  - `-Wall`
+  - `-Werror`
+  - `-fno-stack-protector`
+- MSVC rejects them, e.g.:
+  - `cl : command line error D8021: invalid numeric argument '/Werror'`
+
+## Conclusion
+
+A fully MSVC-oriented CGO build path for the CUDA+SDRplay app is currently blocked in this environment by the Go/CGO toolchain behavior itself, not by repository code.
+
+## Practical impact
+
+- CUDA kernel artifact preparation on Windows works
+- package-level `cufft` tests work
+- full app build with MinGW linker + MSVC-built CUDA artifacts fails due to ABI/runtime mismatch
+- full app build with `CC=cl.exe` also fails because `runtime/cgo` already breaks
+
+## Recommendation
+
+Treat this as an environment/toolchain constraint. Continue to:
+
+- keep the repository build logic clean and separated by platform
+- preserve the working default non-CUDA Windows build path
+- preserve Windows CUDA artifact preparation
+- prefer Linux for the first end-to-end CUDA-enabled application build if full Windows CGO/MSVC compatibility remains blocked