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/windows-development-guide.md
+++ b/docs/windows-development-guide.md
@@ -0,0 +1,346 @@
+# Windows Development Guide for YAZE
+
+This guide will help you set up a Windows development environment for YAZE and build the project successfully.
+
+## Prerequisites
+
+### Required Software
+
+1. **Visual Studio 2022** (Community, Professional, or Enterprise)
+   - Download from: https://visualstudio.microsoft.com/downloads/
+   - Required workloads:
+     - Desktop development with C++
+     - Game development with C++ (optional, for additional tools)
+
+2. **Git for Windows**
+   - Download from: https://git-scm.com/download/win
+   - Use default installation options
+
+3. **Python 3.8 or later**
+   - Download from: https://www.python.org/downloads/
+   - Make sure to check "Add Python to PATH" during installation
+
+### Optional Software
+
+- **PowerShell 7** (recommended for better script support)
+- **Windows Terminal** (for better terminal experience)
+
+## Quick Setup
+
+### Automated Setup
+
+The easiest way to get started is to use our automated setup script:
+
+```powershell
+# Run from the YAZE project root directory
+.\scripts\setup-windows-dev.ps1
+```
+
+This script will:
+- Check for required software (Visual Studio 2022, Git, Python)
+- Set up vcpkg and install dependencies (zlib, libpng, SDL2)
+- Generate Visual Studio project files with proper vcpkg integration
+- Perform a test build to verify everything works
+
+### Manual Setup
+
+If you prefer to set up manually or the automated script fails:
+
+#### 1. Clone the Repository
+
+```bash
+git clone https://github.com/your-username/yaze.git
+cd yaze
+```
+
+#### 2. Set up vcpkg
+
+```bash
+# Clone vcpkg
+git clone https://github.com/Microsoft/vcpkg.git vcpkg
+
+# Bootstrap vcpkg
+cd vcpkg
+.\bootstrap-vcpkg.bat
+cd ..
+
+# Install dependencies
+.\vcpkg\vcpkg.exe install --triplet x64-windows
+```
+
+#### 3. Generate Visual Studio Project Files
+
+The generation script creates project files with proper vcpkg integration:
+
+```bash
+python scripts/generate-vs-projects.py
+```
+
+This creates:
+- `YAZE.sln` - Visual Studio solution file
+- `YAZE.vcxproj` - Visual Studio project file with vcpkg integration
+- Proper vcpkg triplet settings for all platforms (x86, x64, ARM64)
+
+#### 4. Build the Project
+
+```bash
+# Using PowerShell script (recommended)
+.\scripts\build-windows.ps1 -Configuration Release -Platform x64
+
+# Or using batch script
+.\scripts\build-windows.bat Release x64
+
+# Or using Visual Studio
+# Open YAZE.sln in Visual Studio 2022 and build
+```
+
+## Building the Project
+
+### Using Visual Studio
+
+1. Open `YAZE.sln` in Visual Studio 2022
+2. Select your desired configuration:
+   - **Debug**: For development and debugging
+   - **Release**: For optimized builds
+   - **RelWithDebInfo**: Release with debug information
+   - **MinSizeRel**: Minimal size release
+3. Select your platform:
+   - **x64**: 64-bit (recommended)
+   - **x86**: 32-bit
+   - **ARM64**: ARM64 (if supported)
+4. Build the solution (Ctrl+Shift+B)
+
+### Using Command Line
+
+#### PowerShell Script (Recommended)
+
+```powershell
+# Build Release x64 (default)
+.\scripts\build-windows.ps1
+
+# Build Debug x64
+.\scripts\build-windows.ps1 -Configuration Debug -Platform x64
+
+# Build Release x86
+.\scripts\build-windows.ps1 -Configuration Release -Platform x86
+
+# Clean build
+.\scripts\build-windows.ps1 -Clean
+
+# Verbose output
+.\scripts\build-windows.ps1 -Verbose
+```
+
+#### Batch Script
+
+```batch
+REM Build Release x64 (default)
+.\scripts\build-windows.bat
+
+REM Build Debug x64
+.\scripts\build-windows.bat Debug x64
+
+REM Build Release x86
+.\scripts\build-windows.bat Release x86
+```
+
+#### Direct MSBuild
+
+```bash
+# Build Release x64
+msbuild YAZE.sln /p:Configuration=Release /p:Platform=x64 /p:VcpkgEnabled=true /p:VcpkgManifestInstall=true /m
+
+# Build Debug x64
+msbuild YAZE.sln /p:Configuration=Debug /p:Platform=x64 /p:VcpkgEnabled=true /p:VcpkgManifestInstall=true /m
+```
+
+## Project Structure
+
+```
+yaze/
+├── YAZE.sln              # Visual Studio solution file (generated)
+├── YAZE.vcxproj          # Visual Studio project file (generated)
+├── vcpkg.json            # vcpkg dependencies
+├── scripts/              # Build and setup scripts
+│   ├── build-windows.ps1 # PowerShell build script
+│   ├── build-windows.bat # Batch build script
+│   ├── setup-windows-dev.ps1 # Automated setup script
+│   └── generate-vs-projects.py # Project file generator
+├── src/                  # Source code
+├── incl/                 # Public headers
+├── assets/               # Game assets
+└── docs/                 # Documentation
+```
+
+**Note**: The Visual Studio project files (`YAZE.sln`, `YAZE.vcxproj`) are generated automatically and should not be edited manually. If you need to modify project settings, update the generation script instead.
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. MSBuild Not Found
+
+**Error**: `'msbuild' is not recognized as an internal or external command`
+
+**Solution**: 
+- Install Visual Studio 2022 with C++ workload
+- Or add MSBuild to your PATH:
+  ```bash
+  # Add to PATH (adjust path as needed)
+  C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin
+  ```
+
+#### 2. vcpkg Integration Issues
+
+**Error**: `vcpkg.json not found` or dependency resolution fails
+
+**Solution**:
+- Ensure vcpkg is properly set up:
+  ```bash
+  .\scripts\setup-windows-dev.ps1
+  ```
+- Or manually set up vcpkg as described in the manual setup section
+
+#### 3. ZLIB or Other Dependencies Not Found
+
+**Error**: `Could NOT find ZLIB (missing: ZLIB_LIBRARY ZLIB_INCLUDE_DIR)`
+
+**Solution**:
+- This usually means vcpkg integration isn't working properly
+- Regenerate project files with proper vcpkg integration:
+  ```bash
+  python scripts/generate-vs-projects.py
+  ```
+- Ensure vcpkg is installed and dependencies are available:
+  ```bash
+  .\vcpkg\vcpkg.exe install --triplet x64-windows
+  ```
+
+#### 4. Python Script Execution Policy
+
+**Error**: `execution of scripts is disabled on this system`
+
+**Solution**:
+```powershell
+# Run as Administrator
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+#### 5. Missing Dependencies
+
+**Error**: Linker errors about missing libraries
+
+**Solution**:
+- Ensure all dependencies are installed via vcpkg:
+  ```bash
+  .\vcpkg\vcpkg.exe install --triplet x64-windows
+  ```
+- Regenerate project files:
+  ```bash
+  python scripts/generate-vs-projects.py
+  ```
+
+#### 6. Build Failures
+
+**Error**: Compilation or linking errors
+
+**Solution**:
+- Clean and rebuild:
+  ```powershell
+  .\scripts\build-windows.ps1 -Clean
+  ```
+- Check that all source files are included in the project
+- Verify that include paths are correct
+
+### Getting Help
+
+If you encounter issues not covered here:
+
+1. Check the [main build instructions](02-build-instructions.md)
+2. Review the [troubleshooting section](02-build-instructions.md#troubleshooting)
+3. Check the [GitHub Issues](https://github.com/your-username/yaze/issues)
+4. Create a new issue with:
+   - Your Windows version
+   - Visual Studio version
+   - Complete error message
+   - Steps to reproduce
+
+## Development Workflow
+
+### Making Changes
+
+1. Make your changes to the source code
+2. If you added new source files, regenerate project files:
+   ```bash
+   python scripts/generate-vs-projects.py
+   ```
+3. Build the project:
+   ```powershell
+   .\scripts\build-windows.ps1 -Configuration Debug -Platform x64
+   ```
+4. Test your changes
+
+### Debugging
+
+1. Set breakpoints in Visual Studio
+2. Build in Debug configuration
+3. Run with debugger (F5)
+4. Use Visual Studio's debugging tools
+
+### Testing
+
+1. Build the project
+2. Run the executable:
+   ```bash
+   .\build\bin\Debug\yaze.exe
+   ```
+3. Test with a ROM file:
+   ```bash
+   .\build\bin\Debug\yaze.exe --rom_file=path\to\your\rom.sfc
+   ```
+
+## Performance Tips
+
+### Build Performance
+
+- Use the `/m` flag for parallel builds
+- Use SSD storage for better I/O performance
+- Exclude build directories from antivirus scanning
+- Use Release configuration for final builds
+
+### Development Performance
+
+- Use Debug configuration for development
+- Use incremental builds (default in Visual Studio)
+- Use RelWithDebInfo for performance testing with debug info
+
+## Advanced Configuration
+
+### Custom Build Configurations
+
+You can create custom build configurations by modifying the Visual Studio project file or using CMake directly.
+
+### Cross-Platform Development
+
+While this guide focuses on Windows, YAZE also supports:
+- Linux (Ubuntu/Debian)
+- macOS
+
+See the main build instructions for other platforms.
+
+## Contributing
+
+When contributing to YAZE on Windows:
+
+1. Follow the [coding standards](B1-contributing.md)
+2. Test your changes on Windows
+3. Ensure the build scripts still work
+4. Update documentation if needed
+5. Submit a pull request
+
+## Additional Resources
+
+- [Visual Studio Documentation](https://docs.microsoft.com/en-us/visualstudio/)
+- [vcpkg Documentation](https://vcpkg.readthedocs.io/)
+- [CMake Documentation](https://cmake.org/documentation/)
+- [YAZE API Reference](04-api-reference.md)