From ed299300e3fb0bf9931bd3c1e02d271df067c298 Mon Sep 17 00:00:00 2001 From: scawful Date: Sun, 28 Sep 2025 00:00:12 -0400 Subject: [PATCH] Update build instructions and enhance Windows development setup - Revised build instructions to include comprehensive Windows support with automated setup scripts and Visual Studio integration. - Added detailed sections for Windows development, including recommended setup scripts and manual options for vcpkg integration. - Improved clarity on build commands and troubleshooting steps for CMake and Visual Studio issues. - Introduced new scripts for testing CMake configuration and streamlined project generation processes. --- docs/02-build-instructions.md | 244 +++++++++++++++++++++++++++++++--- docs/index.md | 2 + docs/vcpkg-integration.md | 2 + docs/visual-studio-setup.md | 2 + 4 files changed, 232 insertions(+), 18 deletions(-) diff --git a/docs/02-build-instructions.md b/docs/02-build-instructions.md index 50665666..9653a8e7 100644 --- a/docs/02-build-instructions.md +++ b/docs/02-build-instructions.md @@ -1,8 +1,6 @@ # Build Instructions -YAZE uses CMake 3.16+ with modern target-based configuration. For VSCode users, install the CMake extensions: -- https://marketplace.visualstudio.com/items?itemName=twxs.cmake -- https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools +YAZE uses CMake 3.16+ with modern target-based configuration. The project includes comprehensive Windows support with Visual Studio integration, vcpkg package management, and automated setup scripts. ## Quick Start @@ -12,13 +10,26 @@ cmake --preset debug cmake --build build ``` -### Linux / Windows +### Linux ```bash cmake -B build -DCMAKE_BUILD_TYPE=Debug cmake --build build ``` -### Minimal Build +### Windows (Recommended) +```powershell +# Automated setup (first time only) +.\scripts\setup-windows-dev.ps1 + +# Generate Visual Studio projects +.\scripts\generate-vs-projects.ps1 + +# Or use CMake directly +cmake --preset windows-debug +cmake --build build --preset windows-debug +``` + +### Minimal Build (CI/Fast) ```bash cmake -B build -DYAZE_MINIMAL_BUILD=ON cmake --build build @@ -55,25 +66,49 @@ sudo apt-get install -y build-essential cmake ninja-build pkg-config \ ``` ### Windows -**Option 1 - Minimal (Recommended for CI):** + +#### Automated Setup (Recommended) +The project includes comprehensive setup scripts for Windows development: + +```powershell +# Complete development environment setup +.\scripts\setup-windows-dev.ps1 + +# Generate Visual Studio project files +.\scripts\generate-vs-projects.ps1 + +# Test CMake configuration +.\scripts\test-cmake-config.ps1 +``` + +**What the setup script installs:** +- Chocolatey package manager +- CMake 3.16+ +- Git, Ninja, Python 3 +- Visual Studio 2022 detection and verification + +#### Manual Setup Options + +**Option 1 - Minimal (CI/Fast Builds):** - Visual Studio 2019+ with C++ CMake tools - No additional dependencies needed (all bundled) -**Option 2 - Full Development with vcpkg (Recommended):** +**Option 2 - Full Development with vcpkg:** - Visual Studio 2019+ with C++ CMake tools -- Install vcpkg and dependencies from `vcpkg.json` +- vcpkg package manager for dependency management -#### vcpkg Setup (Option 2) -Run the setup script to automatically configure vcpkg: -```cmd -# Command Prompt -scripts\setup-vcpkg-windows.bat +#### vcpkg Integration +**Automatic Setup:** +```powershell # PowerShell -.\scripts\setup-vcpkg-windows.ps1 +.\scripts\setup-windows-dev.ps1 + +# Command Prompt +scripts\setup-windows-dev.bat ``` -Or manually: +**Manual vcpkg Setup:** ```cmd git clone https://github.com/Microsoft/vcpkg.git cd vcpkg @@ -82,21 +117,40 @@ cd vcpkg set VCPKG_ROOT=%CD% ``` +**Dependencies (vcpkg.json):** +- zlib (compression) +- libpng (PNG support) +- sdl2 (graphics/input) +- abseil (Google C++ libraries) +- gtest (testing framework) + #### Windows Build Commands + +**Using CMake Presets:** ```cmd -# Debug build with vcpkg (minimal, no tests) +# Debug build (minimal, no tests) cmake --preset windows-debug cmake --build build --preset windows-debug -# Development build with vcpkg (includes Google Test) +# Development build (includes Google Test) cmake --preset windows-dev cmake --build build --preset windows-dev -# Release build with vcpkg (optimized, no tests) +# Release build (optimized, no tests) cmake --preset windows-release cmake --build build --preset windows-release ``` +**Using Visual Studio Projects:** +```powershell +# Generate project files +.\scripts\generate-vs-projects.ps1 + +# Open YAZE.sln in Visual Studio +# Select configuration (Debug/Release) and platform (x64/x86/ARM64) +# Press F5 to build and run +``` + **Build Types:** - **windows-debug**: Minimal debug build, no Google Test - **windows-dev**: Development build with Google Test and ROM testing @@ -141,6 +195,27 @@ cmake -B build -DCMAKE_BUILD_TYPE=Release # All platforms ## IDE Integration +### Visual Studio (Windows) +**Recommended approach:** +```powershell +# Setup development environment +.\scripts\setup-windows-dev.ps1 + +# Generate Visual Studio project files +.\scripts\generate-vs-projects.ps1 + +# Open YAZE.sln in Visual Studio 2022 +# Select configuration (Debug/Release) and platform (x64/x86/ARM64) +# Press F5 to build and run +``` + +**Features:** +- Full IntelliSense support +- Integrated debugging +- vcpkg dependency management +- Multi-platform support (x64, x86, ARM64) +- Automatic asset copying + ### VS Code 1. Install CMake Tools extension 2. Open project, select "Debug" preset @@ -156,6 +231,46 @@ cmake --preset debug -G Xcode open build/yaze.xcodeproj ``` +## Windows Development Scripts + +The project includes several PowerShell and Batch scripts to streamline Windows development: + +### Setup Scripts +- **`setup-windows-dev.ps1`**: Complete development environment setup +- **`setup-windows-dev.bat`**: Batch version of setup script + +**What they install:** +- Chocolatey package manager +- CMake 3.16+ +- Git, Ninja, Python 3 +- Visual Studio 2022 detection + +### Project Generation Scripts +- **`generate-vs-projects.ps1`**: Generate Visual Studio project files +- **`generate-vs-projects.bat`**: Batch version of project generation + +**Features:** +- Automatic CMake detection and installation +- Visual Studio 2022 detection +- Multi-architecture support (x64, x86, ARM64) +- vcpkg integration +- CMake compatibility fixes + +### Testing Scripts +- **`test-cmake-config.ps1`**: Test CMake configuration without full build + +**Usage:** +```powershell +# Test configuration +.\scripts\test-cmake-config.ps1 + +# Test with specific architecture +.\scripts\test-cmake-config.ps1 -Architecture x86 + +# Clean test build +.\scripts\test-cmake-config.ps1 -Clean +``` + ## Features by Build Type | Feature | Debug | Release | Minimal (CI) | @@ -168,8 +283,83 @@ open build/yaze.xcodeproj | Test Suite | ✅ | ❌ | ✅ (limited) | | UI Testing | ✅ | ❌ | ❌ | +## CMake Compatibility + +### Submodule Compatibility Issues +YAZE includes several submodules (abseil-cpp, SDL) that may have CMake compatibility issues. The project automatically handles these with: + +**Automatic Policy Management:** +- `CMAKE_POLICY_VERSION_MINIMUM=3.5` (handles SDL requirements) +- `CMAKE_POLICY_VERSION_MAXIMUM=3.28` (prevents future issues) +- `CMAKE_WARN_DEPRECATED=OFF` (suppresses submodule warnings) +- `ABSL_PROPAGATE_CXX_STD=ON` (handles Abseil C++ standard propagation) +- `THREADS_PREFER_PTHREAD_FLAG=OFF` (fixes Windows pthread issues) + +**Manual Configuration (if needed):** +```bash +cmake -B build \ + -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \ + -DCMAKE_POLICY_VERSION_MAXIMUM=3.28 \ + -DCMAKE_WARN_DEPRECATED=OFF \ + -DABSL_PROPAGATE_CXX_STD=ON \ + -DTHREADS_PREFER_PTHREAD_FLAG=OFF \ + -DCMAKE_BUILD_TYPE=Debug +``` + ## Troubleshooting +### Windows CMake Issues + +**CMake Not Found:** +```powershell +# Run the setup script +.\scripts\setup-windows-dev.ps1 + +# Or install manually via Chocolatey +choco install cmake +``` + +**Submodule Compatibility Errors:** +```powershell +# Test CMake configuration +.\scripts\test-cmake-config.ps1 + +# Clean build with compatibility flags +Remove-Item -Recurse -Force build +cmake -B build -DCMAKE_POLICY_VERSION_MINIMUM=3.5 -DCMAKE_WARN_DEPRECATED=OFF +``` + +**Visual Studio Project Issues:** +```powershell +# Regenerate project files +.\scripts\generate-vs-projects.ps1 + +# Clean and rebuild +Remove-Item -Recurse -Force build +cmake --preset windows-debug +``` + +### vcpkg Issues + +**Dependencies Not Installing:** +```cmd +# Check vcpkg installation +vcpkg version + +# Reinstall dependencies +vcpkg install --triplet x64-windows zlib libpng sdl2 abseil gtest + +# Check installed packages +vcpkg list +``` + +**Visual Studio Integration:** +```cmd +# Re-integrate vcpkg +cd C:\vcpkg +.\vcpkg.exe integrate install +``` + ### Architecture Errors (macOS) ```bash # Clean and use ARM64-only preset @@ -191,3 +381,21 @@ Use minimal build configuration that matches CI: cmake -B build -DYAZE_MINIMAL_BUILD=ON -DYAZE_ENABLE_UI_TESTS=OFF cmake --build build ``` + +### Common Error Solutions + +**"CMake Deprecation Warning" from submodules:** +- This is automatically handled by the project's CMake configuration +- If you see these warnings, they can be safely ignored + +**"pthread_create not found" on Windows:** +- The project automatically sets `THREADS_PREFER_PTHREAD_FLAG=OFF` +- This is normal for Windows builds + +**"Abseil C++ std propagation" warnings:** +- Automatically handled with `ABSL_PROPAGATE_CXX_STD=ON` +- Ensures proper C++ standard handling + +**Visual Studio "file not found" errors:** +- Run `.\scripts\generate-vs-projects.ps1` to regenerate project files +- Ensure CMake configuration completed successfully first diff --git a/docs/index.md b/docs/index.md index 95bde98f..aafe2984 100644 --- a/docs/index.md +++ b/docs/index.md @@ -37,6 +37,8 @@ Yet Another Zelda3 Editor - A comprehensive ROM editor for The Legend of Zelda: - ZSCustomOverworld v3 support for enhanced overworld editing - Cross-platform support (Windows, macOS, Linux) - Modern C++23 codebase with comprehensive testing +- **Windows Development**: Automated setup scripts, Visual Studio integration, vcpkg package management +- **CMake Compatibility**: Automatic handling of submodule compatibility issues (abseil-cpp, SDL) --- diff --git a/docs/vcpkg-integration.md b/docs/vcpkg-integration.md index e256c2ca..9014530e 100644 --- a/docs/vcpkg-integration.md +++ b/docs/vcpkg-integration.md @@ -1,5 +1,7 @@ # vcpkg Integration for Windows Builds +> **Note**: This document provides detailed vcpkg information. For the most up-to-date build instructions, see [Build Instructions](02-build-instructions.md). + This document describes how to use vcpkg for Windows builds in Visual Studio with YAZE. ## Overview diff --git a/docs/visual-studio-setup.md b/docs/visual-studio-setup.md index 0c52a946..49e2e05c 100644 --- a/docs/visual-studio-setup.md +++ b/docs/visual-studio-setup.md @@ -1,5 +1,7 @@ # Visual Studio Setup Guide +> **Note**: This document provides detailed Visual Studio setup information. For the most up-to-date build instructions, see [Build Instructions](02-build-instructions.md). + This guide will help Visual Studio users set up and build the yaze project on Windows. ## Prerequisites