VideoTools/WINDOWS_BUILD_PERFORMANCE.md

Windows Build Performance Guide

Issue: Slow Builds (5+ Minutes)

If you're experiencing very slow build times on Windows, follow these steps to dramatically improve performance.

Quick Fixes

1. Use the Optimized Build Scripts

We've updated the build scripts with performance optimizations:

# Git Bash (Most Windows users)
./scripts/build.sh

# PowerShell
.\scripts\build.ps1

# Command Prompt
.\scripts\build.bat

New Optimizations:

• -p N: Parallel compilation using all CPU cores
• -trimpath: Faster builds and smaller binaries
• -ldflags="-s -w": Strip debug symbols (faster linking)

2. Add Windows Defender Exclusions (CRITICAL!)

This is the #1 cause of slow builds on Windows.

Windows Defender scans every intermediate .o file during compilation, adding 2-5 minutes to build time.

Automated Script (Easiest - For Git Bash Users):

From Git Bash (Run as Administrator):

# Run the automated exclusion script
powershell.exe -ExecutionPolicy Bypass -File ./scripts/add-defender-exclusions.ps1

To run Git Bash as Administrator:

1. Search for "Git Bash" in Start Menu
2. Right-click → "Run as administrator"
3. Navigate to your VideoTools directory
4. Run the command above

Manual Method (GUI):

1. Open Windows Security

   • Press Win + I → Update & Security → Windows Security → Virus & threat protection

2. Add Exclusions (Manage settings → Add or remove exclusions):

   • C:\Users\YourName\go - Go package cache
   • C:\Users\YourName\AppData\Local\go-build - Go build cache
   • C:\Users\YourName\Projects\VideoTools - Your project directory
   • C:\msys64 - MinGW toolchain (if using MSYS2)

PowerShell Method (If Not Using Git Bash):

Run PowerShell as Administrator:

# Run the automated script
.\scripts\add-defender-exclusions.ps1

# Or add manually:
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\go-build"
Add-MpPreference -ExclusionPath "$env:USERPROFILE\go"
Add-MpPreference -ExclusionPath "C:\Users\$env:USERNAME\Projects\VideoTools"
Add-MpPreference -ExclusionPath "C:\msys64"

Expected improvement: 5 minutes → 30-90 seconds

3. Use Go Build Cache

Make sure Go's build cache is enabled (it should be by default):

# Check cache location
go env GOCACHE

# Should output something like: C:\Users\YourName\AppData\Local\go-build

Don't use -Clean flag unless you're troubleshooting. Clean builds are much slower.

4. Optimize MinGW/GCC

If using MSYS2/MinGW, ensure it's in your PATH before other compilers:

# Check GCC version
gcc --version

# Should show: gcc (GCC) 13.x or newer

Advanced Optimizations

1. Use Faster SSD for Build Cache

Move your Go cache to an SSD if it's on an HDD:

# Set custom cache location on fast SSD
$env:GOCACHE = "D:\FastSSD\go-build"
go env -w GOCACHE="D:\FastSSD\go-build"

2. Increase Go Build Parallelism

For high-core-count CPUs:

# Use all CPU threads
$env:GOMAXPROCS = [Environment]::ProcessorCount

# Or set specific count
$env:GOMAXPROCS = 16

3. Disable Real-Time Scanning Temporarily

Only during builds (not recommended for normal use):

# Disable (run as Administrator)
Set-MpPreference -DisableRealtimeMonitoring $true

# Build your project
.\scripts\build.ps1

# Re-enable immediately after
Set-MpPreference -DisableRealtimeMonitoring $false

Benchmarking Your Build

Time your build to measure improvements:

# PowerShell
Measure-Command { .\scripts\build.ps1 }

# Command Prompt
echo %time% && .\scripts\build.bat && echo %time%

Expected Build Times

With optimizations:

Machine Type	Clean Build	Incremental Build
Modern Desktop (8+ cores, SSD)	30-60 seconds	5-15 seconds
Laptop (4-6 cores, SSD)	60-90 seconds	10-20 seconds
Older Machine (2-4 cores, HDD)	2-3 minutes	30-60 seconds

Without Defender exclusions: Add 2-5 minutes to above times.

Still Slow?

Check for Common Issues:

1. Antivirus Software

   • Third-party antivirus can be even worse than Defender
   • Add same exclusions in your antivirus settings

2. Disk Space

   • Go cache can grow large
   • Ensure 5+ GB free space on cache drive

3. Background Processes

   • Close resource-heavy applications during builds
   • Check Task Manager for CPU/disk usage

4. Network Drives

   • Never build on network drives or cloud-synced folders
   • Move project to local SSD

5. WSL2 vs Native Windows

   • Building in WSL2 can be faster
   • But adds complexity with GUI apps

Troubleshooting Commands

# Check Go environment
go env

# Check build cache size
Get-ChildItem -Path (go env GOCACHE) -Recurse | Measure-Object -Property Length -Sum

# Clean cache if too large (>10 GB)
go clean -cache

# Verify GCC is working
gcc --version

Getting Help

If you're still experiencing slow builds after following this guide:

1. Capture build timing:

   Measure-Command { go build -v -x . } > build-log.txt 2>&1
   

2. Check system specs:

   systeminfo | findstr /C:"Processor" /C:"Physical Memory"
   

3. Report issue with:

   • Build timing output
   • System specifications
   • Windows version
   • Antivirus software in use

Summary: Quick Start for Git Bash Users

If you're using Git Bash on Windows (most users), do this:

1. Open Git Bash as Administrator

   • Right-click Git Bash → "Run as administrator"

2. Navigate to VideoTools:

   cd ~/Projects/VideoTools  # or wherever your project is
   

3. Add Defender exclusions (ONE TIME ONLY):

   powershell.exe -ExecutionPolicy Bypass -File ./scripts/add-defender-exclusions.ps1
   

4. Close and reopen Git Bash (normal, not admin)

5. Build with optimized script:

   ./scripts/build.sh
   

Expected result: 5+ minutes → 30-90 seconds

What Each Step Does:

1. ✅ Add Windows Defender exclusions (saves 2-5 minutes) - Most important!
2. ✅ Use optimized build scripts (saves 30-60 seconds) - Parallel compilation
3. ✅ Avoid clean builds (saves 1-2 minutes) - Uses Go's build cache