backend-infra-engineer: Release v0.3.1 snapshot

2025-09-28 03:07:45 -04:00
parent e32ac75b9c
commit 4371618a9b
88 changed files with 17940 additions and 4600 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 (with proper vcpkg integration)
+python scripts/generate-vs-projects.py
+
+# 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,12 +66,95 @@ 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 (with proper vcpkg integration)
+python scripts/generate-vs-projects.py
+
+# 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:**
- Install vcpkg and dependencies from `vcpkg.json`
+**Option 2 - Full Development with vcpkg:**
+- Visual Studio 2019+ with C++ CMake tools
+- vcpkg package manager for dependency management
+
+#### vcpkg Integration
+
+**Automatic Setup:**
+```powershell
+# PowerShell
+.\scripts\setup-windows-dev.ps1
+
+# Command Prompt
+scripts\setup-windows-dev.bat
+```
+
+**Manual vcpkg Setup:**
+```cmd
+git clone https://github.com/Microsoft/vcpkg.git
+cd vcpkg
+.\bootstrap-vcpkg.bat
+.\vcpkg.exe integrate install
+set VCPKG_ROOT=%CD%
+```
+
+**Dependencies (vcpkg.json):**
+- zlib (compression)
+- libpng (PNG support)
+- sdl2 (graphics/input with Vulkan support)
+
+**Note**: Abseil and gtest are built from source via CMake rather than through vcpkg to avoid compatibility issues.
+
+#### Windows Build Commands
+
+**Using CMake Presets:**
+```cmd
+# Debug build (minimal, no tests)
+cmake --preset windows-debug
+cmake --build build --preset windows-debug
+
+# Development build (includes Google Test)
+cmake --preset windows-dev
+cmake --build build --preset windows-dev
+
+# Release build (optimized, no tests)
+cmake --preset windows-release
+cmake --build build --preset windows-release
+```
+
+**Using Visual Studio Projects:**
+```powershell
+# Generate project files (with proper vcpkg integration)
+python scripts/generate-vs-projects.py
+
+# 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
+- **windows-release**: Optimized release build, no Google Test

 ## Build Targets

@@ -101,6 +195,28 @@ 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 (with proper vcpkg integration)
+python scripts/generate-vs-projects.py
+
+# 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
+- Automatic vcpkg dependency management (zlib, libpng, SDL2)
+- Multi-platform support (x64, ARM64)
+- Automatic asset copying
+- Generated project files stay in sync with CMake configuration
+
 ### VS Code
 1. Install CMake Tools extension
 2. Open project, select "Debug" preset
@@ -116,6 +232,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.py`**: Generate Visual Studio project files with proper vcpkg integration
+- **`generate-vs-projects.bat`**: Batch version of project generation
+
+**Features:**
+- Automatic CMake detection and installation
+- Visual Studio 2022 detection
+- Multi-architecture support (x64, 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) |
@@ -128,8 +284,135 @@ 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
+```
+
+## CI/CD and Release Builds
+
+### GitHub Actions Workflows
+
+The project includes three release workflows with different levels of complexity:
+
+- **`release-simplified.yml`**: Fast, basic release builds
+- **`release.yml`**: Standard release builds with fallback mechanisms
+- **`release-complex.yml`**: Comprehensive release builds with multiple fallback strategies
+
+### vcpkg Fallback Mechanisms
+
+All Windows CI/CD builds include automatic fallback mechanisms:
+
+**When vcpkg succeeds:**
+- Full build with all dependencies (zlib, libpng, SDL2)
+- Complete feature set available
+
+**When vcpkg fails (network issues):**
+- Automatic fallback to minimal build configuration
+- Uses source-built dependencies (Abseil, etc.)
+- Still produces functional executables
+
+### Supported Architectures
+
+**Windows:**
+- x64 (64-bit) - Primary target for modern systems
+- ARM64 - For ARM-based Windows devices (Surface Pro X, etc.)
+
+**macOS:**
+- Universal binary (Apple Silicon + Intel)
+
+**Linux:**
+- x64 (64-bit)
+
 ## 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
+
+# Check installed packages
+vcpkg list
+```
+
+**Network/Download Failures:**
+- The CI/CD workflows automatically fall back to minimal builds
+- For local development, ensure stable internet connection
+- If vcpkg consistently fails, use minimal build mode:
+  ```bash
+  cmake -B build -DYAZE_MINIMAL_BUILD=ON
+  ```
+
+**Visual Studio Integration:**
+```cmd
+# Re-integrate vcpkg
+cd C:\vcpkg
+.\vcpkg.exe integrate install
+```
+
+**ZLIB or Other Dependencies Not Found:**
+```bash
+# Regenerate project files with proper vcpkg integration
+python scripts/generate-vs-projects.py
+
+# Ensure vcpkg is properly set up
+.\scripts\setup-windows-dev.ps1
+```
+
 ### Architecture Errors (macOS)
 ```bash
 # Clean and use ARM64-only preset
@@ -151,3 +434,26 @@ 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 `python scripts/generate-vs-projects.py` to regenerate project files
+- Ensure CMake configuration completed successfully first
+
+**CI/CD Build Failures:**
+- Check if vcpkg download failed (network issues)
+- The workflows automatically fall back to minimal builds
+- For persistent issues, check the workflow logs for specific error messages