Update build instructions and enhance Windows development setup

- Revised build instructions to include comprehensive Windows support with automated setup scripts and Visual Studio integration. - Added detailed sections for Windows development, including recommended setup scripts and manual options for vcpkg integration. - Improved clarity on build commands and troubleshooting steps for CMake and Visual Studio issues. - Introduced new scripts for testing CMake configuration and streamlined project generation processes.
2025-09-28 00:00:12 -04:00
parent 3af69c5ae2
commit ed299300e3
4 changed files with 232 additions and 18 deletions
--- a/docs/02-build-instructions.md
+++ b/docs/02-build-instructions.md
@@ -1,8 +1,6 @@
 # Build Instructions

-YAZE uses CMake 3.16+ with modern target-based configuration. For VSCode users, install the CMake extensions:
- https://marketplace.visualstudio.com/items?itemName=twxs.cmake
- https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
+YAZE uses CMake 3.16+ with modern target-based configuration. The project includes comprehensive Windows support with Visual Studio integration, vcpkg package management, and automated setup scripts.

 ## Quick Start

@@ -12,13 +10,26 @@ cmake --preset debug
 cmake --build build
 ```

-### Linux / Windows
+### Linux
 ```bash
 cmake -B build -DCMAKE_BUILD_TYPE=Debug
 cmake --build build
 ```

-### Minimal Build
+### Windows (Recommended)
+```powershell
+# Automated setup (first time only)
+.\scripts\setup-windows-dev.ps1
+
+# Generate Visual Studio projects
+.\scripts\generate-vs-projects.ps1
+
+# Or use CMake directly
+cmake --preset windows-debug
+cmake --build build --preset windows-debug
+```
+
+### Minimal Build (CI/Fast)
 ```bash
 cmake -B build -DYAZE_MINIMAL_BUILD=ON
 cmake --build build
@@ -55,25 +66,49 @@ sudo apt-get install -y build-essential cmake ninja-build pkg-config \
 ```

 ### Windows
-**Option 1 - Minimal (Recommended for CI):**
+
+#### Automated Setup (Recommended)
+The project includes comprehensive setup scripts for Windows development:
+
+```powershell
+# Complete development environment setup
+.\scripts\setup-windows-dev.ps1
+
+# Generate Visual Studio project files
+.\scripts\generate-vs-projects.ps1
+
+# Test CMake configuration
+.\scripts\test-cmake-config.ps1
+```
+
+**What the setup script installs:**
+- Chocolatey package manager
+- CMake 3.16+
+- Git, Ninja, Python 3
+- Visual Studio 2022 detection and verification
+
+#### Manual Setup Options
+
+**Option 1 - Minimal (CI/Fast Builds):**
 - Visual Studio 2019+ with C++ CMake tools
 - No additional dependencies needed (all bundled)

-**Option 2 - Full Development with vcpkg (Recommended):**
+**Option 2 - Full Development with vcpkg:**
 - Visual Studio 2019+ with C++ CMake tools
- Install vcpkg and dependencies from `vcpkg.json`
+- vcpkg package manager for dependency management

-#### vcpkg Setup (Option 2)
-Run the setup script to automatically configure vcpkg:
-```cmd
-# Command Prompt
-scripts\setup-vcpkg-windows.bat
+#### vcpkg Integration

+**Automatic Setup:**
+```powershell
 # PowerShell
-.\scripts\setup-vcpkg-windows.ps1
+.\scripts\setup-windows-dev.ps1
+
+# Command Prompt
+scripts\setup-windows-dev.bat
 ```

-Or manually:
+**Manual vcpkg Setup:**
 ```cmd
 git clone https://github.com/Microsoft/vcpkg.git
 cd vcpkg
@@ -82,21 +117,40 @@ cd vcpkg
 set VCPKG_ROOT=%CD%
 ```

+**Dependencies (vcpkg.json):**
+- zlib (compression)
+- libpng (PNG support)
+- sdl2 (graphics/input)
+- abseil (Google C++ libraries)
+- gtest (testing framework)
+
 #### Windows Build Commands
+
+**Using CMake Presets:**
 ```cmd
-# Debug build with vcpkg (minimal, no tests)
+# Debug build (minimal, no tests)
 cmake --preset windows-debug
 cmake --build build --preset windows-debug

-# Development build with vcpkg (includes Google Test)
+# Development build (includes Google Test)
 cmake --preset windows-dev
 cmake --build build --preset windows-dev

-# Release build with vcpkg (optimized, no tests)
+# Release build (optimized, no tests)
 cmake --preset windows-release
 cmake --build build --preset windows-release
 ```

+**Using Visual Studio Projects:**
+```powershell
+# Generate project files
+.\scripts\generate-vs-projects.ps1
+
+# Open YAZE.sln in Visual Studio
+# Select configuration (Debug/Release) and platform (x64/x86/ARM64)
+# Press F5 to build and run
+```
+
 **Build Types:**
 - **windows-debug**: Minimal debug build, no Google Test
 - **windows-dev**: Development build with Google Test and ROM testing
@@ -141,6 +195,27 @@ cmake -B build -DCMAKE_BUILD_TYPE=Release  # All platforms

 ## IDE Integration

+### Visual Studio (Windows)
+**Recommended approach:**
+```powershell
+# Setup development environment
+.\scripts\setup-windows-dev.ps1
+
+# Generate Visual Studio project files
+.\scripts\generate-vs-projects.ps1
+
+# Open YAZE.sln in Visual Studio 2022
+# Select configuration (Debug/Release) and platform (x64/x86/ARM64)
+# Press F5 to build and run
+```
+
+**Features:**
+- Full IntelliSense support
+- Integrated debugging
+- vcpkg dependency management
+- Multi-platform support (x64, x86, ARM64)
+- Automatic asset copying
+
 ### VS Code
 1. Install CMake Tools extension
 2. Open project, select "Debug" preset
@@ -156,6 +231,46 @@ cmake --preset debug -G Xcode
 open build/yaze.xcodeproj
 ```

+## Windows Development Scripts
+
+The project includes several PowerShell and Batch scripts to streamline Windows development:
+
+### Setup Scripts
+- **`setup-windows-dev.ps1`**: Complete development environment setup
+- **`setup-windows-dev.bat`**: Batch version of setup script
+
+**What they install:**
+- Chocolatey package manager
+- CMake 3.16+
+- Git, Ninja, Python 3
+- Visual Studio 2022 detection
+
+### Project Generation Scripts
+- **`generate-vs-projects.ps1`**: Generate Visual Studio project files
+- **`generate-vs-projects.bat`**: Batch version of project generation
+
+**Features:**
+- Automatic CMake detection and installation
+- Visual Studio 2022 detection
+- Multi-architecture support (x64, x86, ARM64)
+- vcpkg integration
+- CMake compatibility fixes
+
+### Testing Scripts
+- **`test-cmake-config.ps1`**: Test CMake configuration without full build
+
+**Usage:**
+```powershell
+# Test configuration
+.\scripts\test-cmake-config.ps1
+
+# Test with specific architecture
+.\scripts\test-cmake-config.ps1 -Architecture x86
+
+# Clean test build
+.\scripts\test-cmake-config.ps1 -Clean
+```
+
 ## Features by Build Type

 | Feature | Debug | Release | Minimal (CI) |
@@ -168,8 +283,83 @@ open build/yaze.xcodeproj
 | Test Suite | ✅ | ❌ | ✅ (limited) |
 | UI Testing | ✅ | ❌ | ❌ |

+## CMake Compatibility
+
+### Submodule Compatibility Issues
+YAZE includes several submodules (abseil-cpp, SDL) that may have CMake compatibility issues. The project automatically handles these with:
+
+**Automatic Policy Management:**
+- `CMAKE_POLICY_VERSION_MINIMUM=3.5` (handles SDL requirements)
+- `CMAKE_POLICY_VERSION_MAXIMUM=3.28` (prevents future issues)
+- `CMAKE_WARN_DEPRECATED=OFF` (suppresses submodule warnings)
+- `ABSL_PROPAGATE_CXX_STD=ON` (handles Abseil C++ standard propagation)
+- `THREADS_PREFER_PTHREAD_FLAG=OFF` (fixes Windows pthread issues)
+
+**Manual Configuration (if needed):**
+```bash
+cmake -B build \
+  -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
+  -DCMAKE_POLICY_VERSION_MAXIMUM=3.28 \
+  -DCMAKE_WARN_DEPRECATED=OFF \
+  -DABSL_PROPAGATE_CXX_STD=ON \
+  -DTHREADS_PREFER_PTHREAD_FLAG=OFF \
+  -DCMAKE_BUILD_TYPE=Debug
+```
+
 ## Troubleshooting

+### Windows CMake Issues
+
+**CMake Not Found:**
+```powershell
+# Run the setup script
+.\scripts\setup-windows-dev.ps1
+
+# Or install manually via Chocolatey
+choco install cmake
+```
+
+**Submodule Compatibility Errors:**
+```powershell
+# Test CMake configuration
+.\scripts\test-cmake-config.ps1
+
+# Clean build with compatibility flags
+Remove-Item -Recurse -Force build
+cmake -B build -DCMAKE_POLICY_VERSION_MINIMUM=3.5 -DCMAKE_WARN_DEPRECATED=OFF
+```
+
+**Visual Studio Project Issues:**
+```powershell
+# Regenerate project files
+.\scripts\generate-vs-projects.ps1
+
+# Clean and rebuild
+Remove-Item -Recurse -Force build
+cmake --preset windows-debug
+```
+
+### vcpkg Issues
+
+**Dependencies Not Installing:**
+```cmd
+# Check vcpkg installation
+vcpkg version
+
+# Reinstall dependencies
+vcpkg install --triplet x64-windows zlib libpng sdl2 abseil gtest
+
+# Check installed packages
+vcpkg list
+```
+
+**Visual Studio Integration:**
+```cmd
+# Re-integrate vcpkg
+cd C:\vcpkg
+.\vcpkg.exe integrate install
+```
+
 ### Architecture Errors (macOS)
 ```bash
 # Clean and use ARM64-only preset
@@ -191,3 +381,21 @@ Use minimal build configuration that matches CI:
 cmake -B build -DYAZE_MINIMAL_BUILD=ON -DYAZE_ENABLE_UI_TESTS=OFF
 cmake --build build
 ```
+
+### Common Error Solutions
+
+**"CMake Deprecation Warning" from submodules:**
+- This is automatically handled by the project's CMake configuration
+- If you see these warnings, they can be safely ignored
+
+**"pthread_create not found" on Windows:**
+- The project automatically sets `THREADS_PREFER_PTHREAD_FLAG=OFF`
+- This is normal for Windows builds
+
+**"Abseil C++ std propagation" warnings:**
+- Automatically handled with `ABSL_PROPAGATE_CXX_STD=ON`
+- Ensures proper C++ standard handling
+
+**Visual Studio "file not found" errors:**
+- Run `.\scripts\generate-vs-projects.ps1` to regenerate project files
+- Ensure CMake configuration completed successfully first