yaze/docs/visual-studio-setup.md

Visual Studio Setup Guide for YAZE

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:

   set VCPKG_ROOT=C:\vcpkg
   

2. Integrate vcpkg with Visual Studio:

   cd C:\vcpkg
   .\vcpkg integrate install
   

Project Setup

1. Clone the Repository

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

vcpkg install zlib:x64-windows
vcpkg install libpng:x64-windows
vcpkg install sdl2[vulkan]:x64-windows
vcpkg install abseil:x64-windows
vcpkg install gtest:x64-windows

3. Configure CMake

Option A: Using Visual Studio (Recommended)

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)

Option B: Using Command Line

mkdir build
cd build
cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake

4. Build Configuration

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

Common Issues and Solutions

Issue 1: 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:

   cmake .. -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake
   

3. Check that zlib is installed:

   vcpkg list zlib
   

Issue 2: 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 3: SDL2 Configuration Issues

Problem: SDL2 not found or linking errors

Solution:

1. Install SDL2 with vcpkg:

   vcpkg install sdl2[vulkan]:x64-windows
   

2. Ensure the project uses the vcpkg toolchain file

Issue 4: Build Errors with Abseil

Problem: Missing Abseil symbols or linking issues

Solution:

1. Install Abseil via vcpkg:

   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:

{
    "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

Command Line

cd build/bin/Debug  # or Release
yaze.exe --rom_file=path/to/your/zelda3.sfc

Visual Studio

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

cd build
ctest --build-config Debug

Run Specific Test Suite

cd build/bin/Debug
yaze_test.exe

Troubleshooting

Clean Build

If you encounter persistent issues:

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:

vcpkg list

CMake Cache Issues

Clear CMake cache:

del CMakeCache.txt
cmake .. -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake

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 uses minimal builds to avoid dependency issues
• Development builds include additional debugging features and ROM testing capabilities

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