yaze/docs/windows-development-guide.md

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:

# 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

git clone https://github.com/your-username/yaze.git
cd yaze

2. Set up vcpkg

# 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:

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

# 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)

# 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

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

# 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:

  # 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:

  .\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:

  python scripts/generate-vs-projects.py
  

• Ensure vcpkg is installed and dependencies are available:

  .\vcpkg\vcpkg.exe install --triplet x64-windows
  

4. Python Script Execution Policy

Error: execution of scripts is disabled on this system

Solution:

# 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:

  .\vcpkg\vcpkg.exe install --triplet x64-windows
  

• Regenerate project files:

  python scripts/generate-vs-projects.py
  

6. Build Failures

Error: Compilation or linking errors

Solution:

• Clean and rebuild:

  .\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
2. Review the troubleshooting section
3. Check the GitHub 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:

   python scripts/generate-vs-projects.py
   

3. Build the project:

   .\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:

   .\build\bin\Debug\yaze.exe
   

3. Test with a ROM file:

   .\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
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
• vcpkg Documentation
• CMake Documentation
• YAZE API Reference