From f321b2350cf3c9aa6b9be721d71842df16606ba5 Mon Sep 17 00:00:00 2001 From: scawful Date: Sun, 28 Sep 2025 11:02:25 -0400 Subject: [PATCH] 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. --- docs/visual-studio-setup.md | 100 +++++++++++++++++---- scripts/generate-vs-projects.ps1 | 147 +++++++++++++++++++++++++++---- scripts/test-vs-generation.ps1 | 55 ++++++++++++ 3 files changed, 268 insertions(+), 34 deletions(-) create mode 100644 scripts/test-vs-generation.ps1 diff --git a/docs/visual-studio-setup.md b/docs/visual-studio-setup.md index 49e2e05c..413d334d 100644 --- 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:** diff --git a/scripts/generate-vs-projects.ps1 b/scripts/generate-vs-projects.ps1 index 48b7382c..d72ebbdb 100644 --- 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 diff --git a/scripts/test-vs-generation.ps1 b/scripts/test-vs-generation.ps1 new file mode 100644 index 00000000..038a6014 --- /dev/null +++ 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