From bd875c3c5f38f626b26f96a02c3c00a1bb1646f2 Mon Sep 17 00:00:00 2001 From: scawful Date: Sat, 27 Sep 2025 21:00:28 -0400 Subject: [PATCH] Refactor vcpkg integration and enhance Windows build documentation - Removed unnecessary dependencies from vcpkg.json for a cleaner configuration. - Updated sdl2.cmake to improve handling of ZLIB and PNG dependencies for minimal builds on Windows. - Added a comprehensive Visual Studio setup guide to assist users in configuring the YAZE project on Windows, including prerequisites and troubleshooting tips. - Improved app configuration to prevent conflicts with Google Test integration, ensuring a smoother testing experience. --- cmake/sdl2.cmake | 22 +++- docs/visual-studio-setup.md | 216 +++++++++++++++++++++++++++++++ src/app/app.cmake | 6 +- src/app/editor/editor_manager.cc | 2 + vcpkg.json | 9 -- 5 files changed, 238 insertions(+), 17 deletions(-) create mode 100644 docs/visual-studio-setup.md diff --git a/cmake/sdl2.cmake b/cmake/sdl2.cmake index edc891c5..aeb1a79c 100644 --- a/cmake/sdl2.cmake +++ b/cmake/sdl2.cmake @@ -21,12 +21,24 @@ else() endif() # libpng and ZLIB dependencies -if(WIN32 AND NOT YAZE_MINIMAL_BUILD) - # Use vcpkg on Windows - find_package(ZLIB REQUIRED) - find_package(PNG REQUIRED) +if(WIN32) + # Windows builds with vcpkg + if(NOT YAZE_MINIMAL_BUILD) + find_package(ZLIB REQUIRED) + find_package(PNG REQUIRED) + else() + # For CI/minimal builds, try to find but don't require + find_package(ZLIB QUIET) + find_package(PNG QUIET) + if(NOT ZLIB_FOUND OR NOT PNG_FOUND) + message(STATUS "PNG/ZLIB not found in minimal build, some features may be disabled") + set(PNG_FOUND FALSE) + set(PNG_LIBRARIES "") + set(PNG_INCLUDE_DIRS "") + endif() + endif() elseif(YAZE_MINIMAL_BUILD) - # For CI builds, try to find but don't require + # For CI builds on other platforms, try to find but don't require find_package(ZLIB QUIET) find_package(PNG QUIET) if(NOT ZLIB_FOUND OR NOT PNG_FOUND) diff --git a/docs/visual-studio-setup.md b/docs/visual-studio-setup.md new file mode 100644 index 00000000..3faddbc8 --- /dev/null +++ b/docs/visual-studio-setup.md @@ -0,0 +1,216 @@ +# 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:** + ```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 +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 +```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 + +#### For Development (Debug Build) +```cmd +cmake --build . --config Debug --target yaze +``` + +#### For Release Build +```cmd +cmake --build . --config Release --target yaze +``` + +#### For Testing (Optional) +```cmd +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: + ```cmd + cmake .. -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake + ``` +3. Check that zlib is installed: + ```cmd + 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: + ```cmd + 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: + ```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 + +### Command Line +```cmd +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 +```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 +``` + +## 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 diff --git a/src/app/app.cmake b/src/app/app.cmake index b365f86d..879dac31 100644 --- a/src/app/app.cmake +++ b/src/app/app.cmake @@ -106,9 +106,9 @@ else() target_compile_definitions(yaze PRIVATE YAZE_ENABLE_IMGUI_TEST_ENGINE=0) endif() -# Link Google Test if available for integrated testing -if(YAZE_BUILD_TESTS AND TARGET gtest AND TARGET gtest_main) - target_link_libraries(yaze PRIVATE gtest gtest_main) +# Link Google Test if available for integrated testing (but NOT gtest_main to avoid main() conflicts) +if(YAZE_BUILD_TESTS AND TARGET gtest) + target_link_libraries(yaze PRIVATE gtest) target_compile_definitions(yaze PRIVATE YAZE_ENABLE_GTEST=1) target_compile_definitions(yaze PRIVATE YAZE_ENABLE_TESTING=1) else() diff --git a/src/app/editor/editor_manager.cc b/src/app/editor/editor_manager.cc index 5d2ed395..f6185157 100644 --- a/src/app/editor/editor_manager.cc +++ b/src/app/editor/editor_manager.cc @@ -554,6 +554,8 @@ void EditorManager::Initialize(const std::string &filename) { [&]() { [[maybe_unused]] auto status = test::TestManager::Get().RunTestsByCategory(test::TestCategory::kIntegration); }}, {absl::StrCat(ICON_MD_CLEAR_ALL, " Clear Test Results"), "", [&]() { test::TestManager::Get().ClearResults(); }}, +#else +{}, #endif {gui::kSeparator, "", nullptr, []() { return true; }}, diff --git a/vcpkg.json b/vcpkg.json index 5fbe4c1b..a88c04bd 100644 --- a/vcpkg.json +++ b/vcpkg.json @@ -15,15 +15,6 @@ "name": "sdl2", "platform": "!uwp", "features": ["vulkan"] - }, - { - "name": "abseil", - "platform": "!uwp" - }, - { - "name": "gtest", - "platform": "!uwp", - "features": ["gmock"] } ], "builtin-baseline": "c8696863d371ab7f46e213d8f5ca923c4aef2a00",