From a7efecf830065c8ac171da97a46852b85df91d20 Mon Sep 17 00:00:00 2001 From: scawful Date: Sun, 28 Sep 2025 15:19:46 -0400 Subject: [PATCH] Remove outdated documentation files for vcpkg integration and Visual Studio setup - Deleted `vcpkg-integration.md`, `vcpkg-triplet-setup.md`, `visual-studio-setup.md`, and `windows-development-guide.md` to streamline documentation and eliminate redundancy. - These files were replaced by more concise and updated build instructions, ensuring users have access to the latest setup information. --- docs/vcpkg-integration.md | 160 -------------- docs/vcpkg-triplet-setup.md | 117 ---------- docs/visual-studio-setup.md | 348 ------------------------------ docs/windows-development-guide.md | 346 ----------------------------- 4 files changed, 971 deletions(-) delete mode 100644 docs/vcpkg-integration.md delete mode 100644 docs/vcpkg-triplet-setup.md delete mode 100644 docs/visual-studio-setup.md delete mode 100644 docs/windows-development-guide.md diff --git a/docs/vcpkg-integration.md b/docs/vcpkg-integration.md deleted file mode 100644 index 31a3990d..00000000 --- a/docs/vcpkg-integration.md +++ /dev/null @@ -1,160 +0,0 @@ -# vcpkg Integration for Windows Builds - -> **Note**: This document provides detailed vcpkg information. For the most up-to-date build instructions, see [Build Instructions](02-build-instructions.md). - -This document describes how to use vcpkg for Windows builds in Visual Studio with YAZE. - -## Overview - -vcpkg is Microsoft's C++ package manager that simplifies dependency management for Windows builds. YAZE now includes full vcpkg integration with manifest mode support for automatic dependency resolution. - -## Features - -- **Manifest Mode**: Dependencies are automatically managed via `vcpkg.json` -- **Visual Studio Integration**: Seamless integration with Visual Studio 2022 -- **Generated Project Files**: Visual Studio project files with proper vcpkg integration -- **CMake Presets**: Pre-configured build presets for Windows -- **Automatic Setup**: Setup scripts for easy vcpkg installation - -## Quick Start - -### 1. Setup vcpkg - -Run the automated setup script: -```powershell -# PowerShell (recommended) -.\scripts\setup-windows-dev.ps1 -``` - -This will: -- Set up vcpkg -- Install dependencies (SDL2) -- Generate Visual Studio project files with proper vcpkg integration - -### 2. Build with Visual Studio - -```powershell -# Generate project files (if not already done) -python scripts/generate-vs-projects.py - -# Open YAZE.sln in Visual Studio 2022 -# Select configuration and platform, then build -``` - -### 3. Alternative: Build with CMake - -Use the Windows presets in CMakePresets.json: - -```cmd -# Debug build -cmake --preset windows-debug -cmake --build build --preset windows-debug - -# Release build -cmake --preset windows-release -cmake --build build --preset windows-release -``` - -## Configuration Details - -### vcpkg.json Manifest - -The `vcpkg.json` file defines all dependencies: - -```json -{ - "name": "yaze", - "version": "0.3.1", - "description": "Yet Another Zelda3 Editor", - "dependencies": [ - { - "name": "zlib", - "platform": "!uwp" - }, - { - { - "name": "sdl2", - "platform": "!uwp", - "features": ["vulkan"] - } - ], - "builtin-baseline": "2024.12.12" -} -``` - -### CMake Configuration - -vcpkg integration is handled in several files: - -- **CMakeLists.txt**: Automatic toolchain detection -- **cmake/vcpkg.cmake**: vcpkg-specific settings -- **CMakePresets.json**: Windows build presets - -### Build Presets - -Available Windows presets: - -- `windows-debug`: Debug build with vcpkg -- `windows-release`: Release build with vcpkg - -## Dependencies - -vcpkg automatically installs these dependencies: - -- **sdl2**: Graphics and input handling (with Vulkan support) - -**Note**: Abseil and gtest are now built from source via CMake rather than through vcpkg to avoid compatibility issues. - -## Environment Variables - -Set `VCPKG_ROOT` to point to your vcpkg installation: - -```cmd -set VCPKG_ROOT=C:\path\to\vcpkg -``` - -## Troubleshooting - -### Common Issues - -1. **vcpkg not found**: Ensure `VCPKG_ROOT` is set or vcpkg is in the project directory -2. **Dependencies not installing**: Check internet connection and vcpkg bootstrap -3. **Visual Studio integration**: Run `vcpkg integrate install` from vcpkg directory - -### Manual Setup - -If automated setup fails: - -```cmd -git clone https://github.com/Microsoft/vcpkg.git -cd vcpkg -.\bootstrap-vcpkg.bat -.\vcpkg.exe integrate install -``` - -## Benefits - -- **Consistent Dependencies**: Same versions across development environments -- **Easy Updates**: Update dependencies via vcpkg.json -- **CI/CD Friendly**: Reproducible builds -- **Visual Studio Integration**: Native IntelliSense support -- **No Manual Downloads**: Automatic dependency resolution - -## Advanced Usage - -### Custom Triplets - -Override the default x64-windows triplet: - -```cmd -cmake --preset windows-debug -DVCPKG_TARGET_TRIPLET=x86-windows -``` - -### Static Linking - -For static builds, modify `cmake/vcpkg.cmake`: - -```cmake -set(VCPKG_LIBRARY_LINKAGE static) -set(VCPKG_CRT_LINKAGE static) -``` diff --git a/docs/vcpkg-triplet-setup.md b/docs/vcpkg-triplet-setup.md deleted file mode 100644 index 5d1b7c45..00000000 --- a/docs/vcpkg-triplet-setup.md +++ /dev/null @@ -1,117 +0,0 @@ -# Installing vcpkg Triplets for Windows - -This guide explains how to install the `x64-windows` triplet that's required for building YAZE on Windows. - -## What is a vcpkg Triplet? - -A triplet defines the target platform, architecture, and linking configuration for vcpkg packages. The `x64-windows` triplet is the most common one for 64-bit Windows development. - -## Method 1: Install via Package (Recommended) - -The easiest way to ensure the triplet is available is to install any package with that triplet: - -```cmd -# Navigate to your vcpkg directory -cd C:\path\to\your\vcpkg - -# Install a package with the x64-windows triplet -vcpkg install sdl2:x64-windows -``` - -This will automatically create the triplet configuration if it doesn't exist. - -## Method 2: Create Triplet File Manually - -If you need to create the triplet configuration manually: - -1. **Navigate to vcpkg triplets directory:** - ```cmd - cd C:\path\to\your\vcpkg\triplets - ``` - -2. **Create or verify `x64-windows.cmake` exists:** - ```cmd - dir x64-windows.cmake - ``` - -3. **If it doesn't exist, create it with this content:** - ```cmake - set(VCPKG_TARGET_ARCHITECTURE x64) - set(VCPKG_CRT_LINKAGE dynamic) - set(VCPKG_LIBRARY_LINKAGE dynamic) - - set(VCPKG_CMAKE_SYSTEM_NAME Windows) - ``` - -## Method 3: Check Available Triplets - -To see what triplets are currently available on your system: - -```cmd -vcpkg help triplet -``` - -Or list all available triplet files: - -```cmd -vcpkg help triplet | findstr "Available" -``` - -## Method 4: Install YAZE Dependencies - -Since YAZE uses several vcpkg packages, installing them will ensure the triplet is properly set up: - -```cmd -# From the YAZE project root -vcpkg install --triplet x64-windows sdl2 -``` - -## Common Issues and Solutions - -### Issue: "Invalid triplet" -**Solution:** Make sure vcpkg is properly installed and in your PATH: -```cmd -vcpkg version -``` - -### Issue: "Triplet not found" -**Solution:** Install a package with that triplet first: -```cmd -vcpkg install zlib:x64-windows -``` - -### Issue: "Permission denied" -**Solution:** Run Command Prompt as Administrator, or install vcpkg in a user-writable location. - -## Alternative Triplets - -If `x64-windows` doesn't work, you can try these alternatives: - -- `x64-windows-static` - Static linking -- `x86-windows` - 32-bit Windows -- `x64-windows-static-md` - Static runtime, dynamic CRT - -## Verification - -To verify the triplet is working: - -```cmd -vcpkg list --triplet x64-windows -``` - -This should show installed packages for that triplet. - -## For YAZE Build - -Once the triplet is installed, you can build YAZE using CMake presets: - -```cmd -cmake --preset=windows-release -cmake --build build --config Release -``` - -Or with the Visual Studio solution: -```cmd -# Open yaze.sln in Visual Studio -# Build normally (F5 or Ctrl+Shift+B) -``` diff --git a/docs/visual-studio-setup.md b/docs/visual-studio-setup.md deleted file mode 100644 index 3054f390..00000000 --- a/docs/visual-studio-setup.md +++ /dev/null @@ -1,348 +0,0 @@ -# Visual Studio Setup Guide - -> **Note**: This document provides detailed Visual Studio setup information. For the most up-to-date build instructions, see [Build Instructions](02-build-instructions.md). - -This guide will help Visual Studio users set up and build the yaze project on Windows. - -## Prerequisites - -### Required Software -1. **Visual Studio 2022** (Community, Professional, or Enterprise) - - Install with "Desktop development with C++" workload - - Ensure CMake tools are included - - Install Git for Windows (or use built-in Git support) - -2. **vcpkg** (Package Manager) - - Download from: https://github.com/Microsoft/vcpkg - - Follow installation instructions to integrate with Visual Studio - -3. **CMake** (3.16 or later) - - Usually included with Visual Studio 2022 - - Verify with: `cmake --version` - -### Environment Setup - -1. **Set up vcpkg environment variable:** - ```cmd - set VCPKG_ROOT=C:\vcpkg - ``` - -2. **Integrate vcpkg with Visual Studio:** - ```cmd - cd C:\vcpkg - .\vcpkg integrate install - ``` - -## Project Setup - -### 1. Clone the Repository -```cmd -git clone --recursive https://github.com/your-username/yaze.git -cd yaze -``` - -### 2. Install Dependencies via vcpkg -The project uses `vcpkg.json` for automatic dependency management. Dependencies will be installed automatically during CMake configuration. - -Manual installation (if needed): -```cmd -vcpkg install zlib:x64-windows -# PNG support removed -vcpkg install sdl2[vulkan]:x64-windows -vcpkg install abseil:x64-windows -vcpkg install gtest:x64-windows -``` - -### 3. Generate Visual Studio Project Files - -#### Option A: Using the Project Generation Script (Recommended) -1. Open PowerShell in the yaze project directory -2. Run the project generation script: - ```powershell - .\scripts\generate-vs-projects.ps1 - ``` -3. The script will: - - Check for CMake and Visual Studio installation - - Configure vcpkg integration - - Generate proper Visual Studio project files with all include paths - - Test the build to ensure everything works -4. Open the generated `YAZE.sln` in Visual Studio -5. Select your desired build configuration (Debug/Release) and platform (x64/x86) -6. Press F5 to build and run, or Ctrl+Shift+B to build only - -#### Option B: Manual CMake Configuration -1. Open PowerShell in the yaze project directory -2. Create build directory and configure: - ```powershell - mkdir build-vs - cd build-vs - cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake - ``` -3. Open the generated `YAZE.sln` in Visual Studio - -#### Option C: Using CMake with Visual Studio (For advanced users) -1. Open Visual Studio 2022 -2. Select "Open a local folder" and navigate to the yaze project folder -3. Visual Studio will automatically detect the CMake project -4. Wait for CMake configuration to complete (check Output window) - -### 4. Build Configuration - -#### Using Visual Studio Project File (.vcxproj) -- **Debug Build:** Select "Debug" configuration and press F5 or Ctrl+Shift+B -- **Release Build:** Select "Release" configuration and press F5 or Ctrl+Shift+B -- **Platform:** Choose x64 (recommended) or x86 from the platform dropdown - -#### Using CMake (Command Line) -```cmd -# For Development (Debug Build) -cmake --build . --config Debug --target yaze - -# For Release Build -cmake --build . --config Release --target yaze - -# For Testing (Optional) -cmake --build . --config Debug --target yaze_test -``` - -## Project Generation Script - -The `generate-vs-projects.ps1` script automates the Visual Studio project setup process: - -### Script Features -- **Automatic CMake Detection:** Finds and configures CMake installation -- **Visual Studio Integration:** Detects Visual Studio 2022 installation -- **vcpkg Configuration:** Automatically configures vcpkg toolchain -- **Dependency Installation:** Installs required packages via vcpkg -- **Project Validation:** Tests the generated project to ensure it builds -- **Include Path Verification:** Checks that all required include paths are present - -### Script Usage -```powershell -# Basic usage (Debug x64) -.\scripts\generate-vs-projects.ps1 - -# Release build -.\scripts\generate-vs-projects.ps1 -Configuration Release - -# x86 build -.\scripts\generate-vs-projects.ps1 -Architecture x86 - -# Clean build -.\scripts\generate-vs-projects.ps1 -Clean - -# With vcpkg -.\scripts\generate-vs-projects.ps1 -UseVcpkg - -# Show help -.\scripts\generate-vs-projects.ps1 -Help -``` - -### Testing the Setup -Use the test script to verify the project generation works: -```powershell -.\scripts\test-vs-generation.ps1 -``` - -## Common Issues and Solutions - -### Issue 1: Missing Include Files (SDL.h, etc.) -**Problem:** `fatal error C1083: Cannot open include file: 'SDL.h'` or similar - -**Solution:** -1. Use the project generation script: `.\scripts\generate-vs-projects.ps1` -2. Ensure vcpkg is properly installed and configured -3. Check that dependencies are installed: - ```cmd - vcpkg list - ``` -4. If using manual setup, ensure the vcpkg toolchain file is set: - ```cmd - cmake .. -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake - ``` - -### Issue 2: zlib Import Errors -**Problem:** `fatal error C1083: Cannot open include file: 'zlib.h'` - -**Solution:** -1. Ensure vcpkg is properly integrated with Visual Studio -2. Verify the vcpkg toolchain file is set: - ```cmd - cmake .. -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake - ``` -3. Check that zlib is installed: - ```cmd - vcpkg list zlib - ``` - -### Issue 3: Executable Runs Tests Instead of Main App -**Problem:** Running `yaze.exe` starts the test framework instead of the application - -**Solution:** This has been fixed in the latest version. The issue was caused by linking `gtest_main` to the main executable. The fix removes `gtest_main` from the main application while keeping `gtest` for testing capabilities. - -### Issue 4: SDL2 Configuration Issues -**Problem:** SDL2 not found or linking errors - -**Solution:** -1. Install SDL2 with vcpkg: - ```cmd - vcpkg install sdl2[vulkan]:x64-windows - ``` -2. Ensure the project uses the vcpkg toolchain file - -### Issue 5: Build Errors with Abseil -**Problem:** Missing Abseil symbols or linking issues - -**Solution:** -1. Install Abseil via vcpkg: - ```cmd - vcpkg install abseil:x64-windows - ``` -2. The project is configured to use Abseil 20240116.2 (see vcpkg.json overrides) - -## Visual Studio Configuration - -### CMake Settings -Create or modify `.vscode/settings.json` or use Visual Studio's CMake settings: - -```json -{ - "cmake.configureArgs": [ - "-DCMAKE_TOOLCHAIN_FILE=${env:VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake", - "-Dyaze_BUILD_TESTS=ON", - "-Dyaze_BUILD_APP=ON", - "-Dyaze_BUILD_LIB=ON" - ], - "cmake.buildDirectory": "${workspaceFolder}/build" -} -``` - -### Build Presets -The project includes CMake presets in `CMakePresets.json`. Use these in Visual Studio: - -1. **Debug Build:** `debug` preset -2. **Release Build:** `release` preset -3. **Development Build:** `dev` preset (includes ROM testing) - -## Running the Application - -### Using Visual Studio Project File -1. Open `yaze.sln` in Visual Studio -2. Set `yaze` as the startup project (should be default) -3. Configure command line arguments in Project Properties > Debugging > Command Arguments - - Example: `--rom_file=C:\path\to\your\zelda3.sfc` -4. Press F5 to build and run, or Ctrl+F5 to run without debugging - -### Command Line -```cmd -cd build/bin/Debug # or Release -yaze.exe --rom_file=path/to/your/zelda3.sfc -``` - -### Visual Studio (CMake) -1. Set `yaze` as the startup project -2. Configure command line arguments in Project Properties > Debugging -3. Press F5 to run - -## Testing - -### Run Unit Tests -```cmd -cd build -ctest --build-config Debug -``` - -### Run Specific Test Suite -```cmd -cd build/bin/Debug -yaze_test.exe -``` - -## Troubleshooting - -### Clean Build -If you encounter persistent issues: -```cmd -rmdir /s build -mkdir build -cd build -cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake -cmake --build . --config Debug -``` - -### Check Dependencies -Verify all dependencies are properly installed: -```cmd -vcpkg list -``` - -### CMake Cache Issues -Clear CMake cache: -```cmd -del CMakeCache.txt -cmake .. -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake -``` - -## Visual Studio Project File Features - -The included `yaze.vcxproj` and `yaze.sln` files provide: - -### **Automatic Dependency Management** -- **vcpkg Integration:** Automatically installs and links dependencies from `vcpkg.json` -- **Platform Support:** Pre-configured for both x64 and x86 builds -- **Library Linking:** Automatically links SDL2 and system libraries - -### **Build Configuration** -- **Debug Configuration:** Includes debugging symbols and runtime checks -- **Release Configuration:** Optimized for performance with full optimizations -- **C++23 Standard:** Uses modern C++ features and standard library - -### **Asset Management** -- **Automatic Asset Copying:** Post-build events copy themes and assets to output directory -- **ROM File Handling:** Automatically copies `zelda3.sfc` if present in project root -- **Resource Organization:** Properly structures output directory for distribution - -### **Development Features** -- **IntelliSense Support:** Full code completion and error detection -- **Debugging Integration:** Native Visual Studio debugging support -- **Project Properties:** Easy access to compiler and linker settings - -## CI/CD Integration - -The Visual Studio project files are fully integrated into the CI/CD pipeline: - -### **Automated Validation** -- **Pre-commit checks:** Visual Studio builds are validated on every pull request -- **Release validation:** Both CMake and Visual Studio builds are tested before release -- **Multi-platform testing:** x64 and x86 builds are validated on Windows -- **Dependency verification:** vcpkg integration is tested automatically - -### **Build Matrix** -The CI/CD pipeline tests: -- **Windows x64 Debug/Release** using Visual Studio 2022 -- **Windows x86 Debug/Release** using Visual Studio 2022 -- **CMake builds** alongside Visual Studio builds for compatibility -- **Asset copying** and executable functionality - -### **Quality Assurance** -- **Test main detection:** Prevents the test framework from hijacking the main application -- **Asset validation:** Ensures themes and resources are properly copied -- **Executable testing:** Verifies the application starts correctly -- **Dependency checking:** Validates all required libraries are properly linked - -## Additional Notes - -- The project supports both x64 and x86 builds (use appropriate vcpkg triplets) -- For ARM64 Windows builds, use `arm64-windows` triplet -- The CI/CD pipeline validates both CMake and Visual Studio builds -- Development builds include additional debugging features and ROM testing capabilities -- The `.vcxproj` file provides the easiest setup for Visual Studio users who prefer traditional project files over CMake -- All builds are automatically validated to ensure they produce working executables - -## Support - -If you encounter issues not covered in this guide: -1. Check the project's GitHub issues -2. Verify your Visual Studio and vcpkg installations -3. Ensure all dependencies are properly installed via vcpkg -4. Try a clean build following the troubleshooting steps above diff --git a/docs/windows-development-guide.md b/docs/windows-development-guide.md deleted file mode 100644 index e6712501..00000000 --- a/docs/windows-development-guide.md +++ /dev/null @@ -1,346 +0,0 @@ -# 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 (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)