Revise Visual Studio setup documentation and enhance project generation script

- Updated the Visual Studio setup guide to recommend using a project generation script for easier configuration. - Added detailed instructions for the new script, including features and usage examples. - Improved the script to check for vcpkg installation and automatically install dependencies if missing. - Introduced a test script to verify the project generation process with different configurations. - Enhanced error handling and output messages in the project generation script for better user experience.
2025-09-28 11:02:25 -04:00
parent 20a93bc491
commit f321b2350c
3 changed files with 268 additions and 34 deletions
--- a/docs/visual-studio-setup.md
+++ b/docs/visual-studio-setup.md
@@ -53,29 +53,39 @@ vcpkg install abseil:x64-windows
 vcpkg install gtest:x64-windows
 ```

-### 3. Configure Build System
+### 3. Generate Visual Studio Project Files

-#### Option A: Using Visual Studio Project File (Easiest)
-1. Open Visual Studio 2022
-2. Select "Open a project or solution"
-3. Navigate to the yaze project folder and open `yaze.sln`
-4. The project is pre-configured with vcpkg integration and proper dependencies
+#### 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: Using CMake with Visual Studio (Recommended for developers)
+#### 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)

-#### Option C: Using Command Line
-```cmd
-mkdir build
-cd build
-cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake
-```
-
 ### 4. Build Configuration

 #### Using Visual Studio Project File (.vcxproj)
@@ -95,9 +105,63 @@ cmake --build . --config Release --target yaze
 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: zlib Import Errors
+### 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:**
@@ -111,12 +175,12 @@ cmake --build . --config Debug --target yaze_test
   vcpkg list zlib
   ```

-### Issue 2: Executable Runs Tests Instead of Main App
+### 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 3: SDL2 Configuration Issues
+### Issue 4: SDL2 Configuration Issues
 **Problem:** SDL2 not found or linking errors

 **Solution:**
@@ -126,7 +190,7 @@ cmake --build . --config Debug --target yaze_test
   ```
 2. Ensure the project uses the vcpkg toolchain file

-### Issue 4: Build Errors with Abseil
+### Issue 5: Build Errors with Abseil
 **Problem:** Missing Abseil symbols or linking issues

 **Solution:**
--- a/scripts/generate-vs-projects.ps1
+++ b/scripts/generate-vs-projects.ps1
@@ -138,14 +138,52 @@ if (-not (Test-Path $BuildDir)) {
    New-Item -ItemType Directory -Path $BuildDir | Out-Null
 }

-# Check if vcpkg is available
+# Check if vcpkg is available and properly configured
 $VcpkgPath = Join-Path $SourceDir "vcpkg\scripts\buildsystems\vcpkg.cmake"
-$UseVcpkg = Test-Path $VcpkgPath
+$VcpkgInstalled = Join-Path $SourceDir "vcpkg\installed"
+
+# Check for vcpkg in common locations
+$VcpkgPaths = @(
+    Join-Path $SourceDir "vcpkg\scripts\buildsystems\vcpkg.cmake",
+    "$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake",
+    "$env:ProgramFiles\vcpkg\scripts\buildsystems\vcpkg.cmake",
+    "$env:ProgramFiles(x86)\vcpkg\scripts\buildsystems\vcpkg.cmake"
+)
+
+$UseVcpkg = $false
+foreach ($path in $VcpkgPaths) {
+    if (Test-Path $path) {
+        $VcpkgPath = $path
+        $UseVcpkg = $true
+        break
+    }
+}

 if ($UseVcpkg) {
    Write-Host "Using vcpkg toolchain: $VcpkgPath" -ForegroundColor Green
+    
+    # Check if vcpkg is properly installed with required packages
+    if (Test-Path $VcpkgInstalled) {
+        Write-Host "vcpkg packages directory found: $VcpkgInstalled" -ForegroundColor Green
+    } else {
+        Write-Host "vcpkg packages not installed. Installing dependencies..." -ForegroundColor Yellow
+        
+        # Try to install vcpkg dependencies
+        $VcpkgExe = Join-Path (Split-Path $VcpkgPath -Parent -Parent) "vcpkg.exe"
+        if (Test-Path $VcpkgExe) {
+            Write-Host "Installing vcpkg dependencies..." -ForegroundColor Yellow
+            & $VcpkgExe install --triplet $Architecture-windows
+            if ($LASTEXITCODE -ne 0) {
+                Write-Host "Failed to install vcpkg dependencies" -ForegroundColor Red
+                Write-Host "Please run: vcpkg install --triplet $Architecture-windows" -ForegroundColor Yellow
+            }
+        } else {
+            Write-Host "vcpkg.exe not found. Please install dependencies manually." -ForegroundColor Yellow
+        }
+    }
 } else {
    Write-Host "vcpkg not found, using system libraries" -ForegroundColor Yellow
+    Write-Host "Note: This may cause missing dependency issues. Consider installing vcpkg." -ForegroundColor Yellow
 }

 # Determine generator and architecture
@@ -171,7 +209,9 @@ $CmakeArgs = @(
    "-DYAZE_ENABLE_ROM_TESTS=OFF",
    "-DYAZE_ENABLE_EXPERIMENTAL_TESTS=ON",
    "-DYAZE_ENABLE_UI_TESTS=ON",
-    "-DYAZE_INSTALL_LIB=OFF"
+    "-DYAZE_INSTALL_LIB=OFF",
+    "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON",
+    "-DCMAKE_VERBOSE_MAKEFILE=ON"
 )

 if ($UseVcpkg) {
@@ -182,8 +222,8 @@ if ($UseVcpkg) {
    )
 }

-# Configure CMake to generate build files (but don't overwrite existing project files)
-Write-Host "Configuring CMake for build system..." -ForegroundColor Yellow
+# Configure CMake to generate Visual Studio project files
+Write-Host "Configuring CMake to generate Visual Studio project files..." -ForegroundColor Yellow
 Write-Host "Command: cmake $($CmakeArgs -join ' ')" -ForegroundColor Gray

 & cmake @CmakeArgs $SourceDir
@@ -193,13 +233,18 @@ if ($LASTEXITCODE -ne 0) {
    exit 1
 }

-# Check if the existing solution file is present and valid
-$ExistingSolutionFile = Join-Path $SourceDir "YAZE.sln"
-if (Test-Path $ExistingSolutionFile) {
-    Write-Host "✅ Using existing Visual Studio solution: $ExistingSolutionFile" -ForegroundColor Green
+# Check if CMake generated the solution file in the build directory
+$GeneratedSolutionFile = Join-Path $BuildDir "YAZE.sln"
+if (Test-Path $GeneratedSolutionFile) {
+    Write-Host "✅ CMake generated Visual Studio solution: $GeneratedSolutionFile" -ForegroundColor Green
+    
+    # Copy the generated solution to the source directory for convenience
+    $SourceSolutionFile = Join-Path $SourceDir "YAZE.sln"
+    Copy-Item $GeneratedSolutionFile $SourceSolutionFile -Force
+    Write-Host "✅ Copied solution file to project root: $SourceSolutionFile" -ForegroundColor Green
    
    # Verify the solution file is properly structured
-    $SolutionContent = Get-Content $ExistingSolutionFile -Raw
+    $SolutionContent = Get-Content $GeneratedSolutionFile -Raw
    if ($SolutionContent -match "YAZE\.vcxproj") {
        Write-Host "✅ Solution file references YAZE.vcxproj correctly" -ForegroundColor Green
        
@@ -211,25 +256,90 @@ if (Test-Path $ExistingSolutionFile) {
        }
    } else {
        Write-Host "❌ Solution file does not reference YAZE.vcxproj" -ForegroundColor Red
-        Write-Host "Please ensure the solution file includes the YAZE project" -ForegroundColor Yellow
+        Write-Host "Please check CMake configuration" -ForegroundColor Yellow
+    }
+    
+    # Check if the project file exists and has proper include paths
+    $ProjectFile = Join-Path $BuildDir "YAZE.vcxproj"
+    if (Test-Path $ProjectFile) {
+        Write-Host "✅ Project file generated: $ProjectFile" -ForegroundColor Green
+        
+        # Check for common include paths in the project file
+        $ProjectContent = Get-Content $ProjectFile -Raw
+        $IncludePaths = @(
+            "src/lib/",
+            "src/app/",
+            "src/lib/asar/src",
+            "src/lib/imgui",
+            "incl/"
+        )
+        
+        $MissingIncludes = @()
+        foreach ($include in $IncludePaths) {
+            if ($ProjectContent -notmatch [regex]::Escape($include)) {
+                $MissingIncludes += $include
+            }
+        }
+        
+        if ($MissingIncludes.Count -eq 0) {
+            Write-Host "✅ All required include paths found in project file" -ForegroundColor Green
+        } else {
+            Write-Host "⚠️  Warning: Missing include paths in project file:" -ForegroundColor Yellow
+            foreach ($missing in $MissingIncludes) {
+                Write-Host "    - $missing" -ForegroundColor Yellow
+            }
+        }
+        
+        # Check for SDL2 include paths
+        if ($ProjectContent -match "SDL2" -or $ProjectContent -match "sdl2") {
+            Write-Host "✅ SDL2 include paths found in project file" -ForegroundColor Green
+        } else {
+            Write-Host "⚠️  Warning: SDL2 include paths not found in project file" -ForegroundColor Yellow
+        }
+    } else {
+        Write-Host "❌ Project file not found: $ProjectFile" -ForegroundColor Red
    }
    
    # Open solution in Visual Studio if available
    if (Get-Command "devenv" -ErrorAction SilentlyContinue) {
        Write-Host "Opening solution in Visual Studio..." -ForegroundColor Yellow
-        & devenv $ExistingSolutionFile
+        & devenv $SourceSolutionFile
    } elseif (Get-Command "code" -ErrorAction SilentlyContinue) {
        Write-Host "Opening solution in VS Code..." -ForegroundColor Yellow
-        & code $ExistingSolutionFile
+        & code $SourceSolutionFile
    } else {
-        Write-Host "Visual Studio solution ready: $ExistingSolutionFile" -ForegroundColor Cyan
+        Write-Host "Visual Studio solution ready: $SourceSolutionFile" -ForegroundColor Cyan
    }
 } else {
-    Write-Host "❌ Existing solution file not found: $ExistingSolutionFile" -ForegroundColor Red
-    Write-Host "Please ensure YAZE.sln exists in the project root" -ForegroundColor Yellow
+    Write-Host "❌ CMake failed to generate solution file: $GeneratedSolutionFile" -ForegroundColor Red
+    Write-Host "Please check CMake configuration and dependencies" -ForegroundColor Yellow
    exit 1
 }

+# Test build to verify the project can compile
+Write-Host ""
+Write-Host "Testing build to verify project configuration..." -ForegroundColor Yellow
+
+$TestBuildArgs = @(
+    "--build", $BuildDir,
+    "--config", $Configuration,
+    "--target", "yaze"
+)
+
+Write-Host "Running test build: cmake $($TestBuildArgs -join ' ')" -ForegroundColor Gray
+& cmake @TestBuildArgs
+
+if ($LASTEXITCODE -eq 0) {
+    Write-Host "✅ Test build successful! Project is properly configured." -ForegroundColor Green
+} else {
+    Write-Host "❌ Test build failed. There may be configuration issues." -ForegroundColor Red
+    Write-Host "Please check the build output above for specific errors." -ForegroundColor Yellow
+    Write-Host "Common issues:" -ForegroundColor Yellow
+    Write-Host "  - Missing vcpkg dependencies" -ForegroundColor Gray
+    Write-Host "  - Incorrect include paths" -ForegroundColor Gray
+    Write-Host "  - Missing library dependencies" -ForegroundColor Gray
+}
+
 Write-Host ""
 Write-Host "🎉 Visual Studio project configuration complete!" -ForegroundColor Green
 Write-Host ""
@@ -249,3 +359,8 @@ Write-Host "Available architectures:" -ForegroundColor Cyan
 Write-Host "  - x64 (64-bit Intel/AMD)" -ForegroundColor Gray
 Write-Host "  - x86 (32-bit Intel/AMD)" -ForegroundColor Gray
 Write-Host "  - ARM64 (64-bit ARM)" -ForegroundColor Gray
+Write-Host ""
+Write-Host "Troubleshooting:" -ForegroundColor Cyan
+Write-Host "  - If you get missing include errors, ensure vcpkg is properly installed" -ForegroundColor Gray
+Write-Host "  - Run: vcpkg install --triplet $Architecture-windows" -ForegroundColor Gray
+Write-Host "  - Check that all dependencies are available in your environment" -ForegroundColor Gray
--- a/scripts/test-vs-generation.ps1
+++ b/scripts/test-vs-generation.ps1
@@ -0,0 +1,55 @@
+# Test script to verify Visual Studio project generation
+# This script tests the generate-vs-projects.ps1 script with different configurations
+
+param(
+    [switch]$Clean = $false,
+    [switch]$Verbose = $false
+)
+
+Write-Host "Testing Visual Studio project generation for YAZE..." -ForegroundColor Green
+
+# Test configurations
+$TestConfigs = @(
+    @{ Config = "Debug"; Arch = "x64" },
+    @{ Config = "Release"; Arch = "x64" }
+)
+
+$ScriptPath = Join-Path $PSScriptRoot "generate-vs-projects.ps1"
+
+foreach ($testConfig in $TestConfigs) {
+    Write-Host ""
+    Write-Host "Testing configuration: $($testConfig.Config) $($testConfig.Arch)" -ForegroundColor Cyan
+    
+    $TestArgs = @(
+        "-Configuration", $testConfig.Config,
+        "-Architecture", $testConfig.Arch
+    )
+    
+    if ($Clean) {
+        $TestArgs += "-Clean"
+    }
+    
+    if ($Verbose) {
+        $TestArgs += "-Verbose"
+    }
+    
+    Write-Host "Running: .\generate-vs-projects.ps1 $($TestArgs -join ' ')" -ForegroundColor Gray
+    
+    try {
+        & $ScriptPath @TestArgs
+        
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host "✅ Configuration $($testConfig.Config) $($testConfig.Arch) passed" -ForegroundColor Green
+        } else {
+            Write-Host "❌ Configuration $($testConfig.Config) $($testConfig.Arch) failed" -ForegroundColor Red
+        }
+    } catch {
+        Write-Host "❌ Configuration $($testConfig.Config) $($testConfig.Arch) failed with exception: $($_.Exception.Message)" -ForegroundColor Red
+    }
+}
+
+Write-Host ""
+Write-Host "Test complete!" -ForegroundColor Green
+Write-Host ""
+Write-Host "If all tests passed, the Visual Studio project generation is working correctly." -ForegroundColor Cyan
+Write-Host "You can now open YAZE.sln in Visual Studio and build the project." -ForegroundColor Cyan