backend-infra-engineer: Release v0.3.1 snapshot
This commit is contained in:
scawful
@@ -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 (with proper vcpkg integration)
|
||||
python scripts/generate-vs-projects.py
|
||||
|
||||
# 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,12 +66,95 @@ 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 (with proper vcpkg integration)
|
||||
python scripts/generate-vs-projects.py
|
||||
|
||||
# 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:**
|
||||
- Install vcpkg and dependencies from `vcpkg.json`
|
||||
**Option 2 - Full Development with vcpkg:**
|
||||
- Visual Studio 2019+ with C++ CMake tools
|
||||
- vcpkg package manager for dependency management
|
||||
|
||||
#### vcpkg Integration
|
||||
|
||||
**Automatic Setup:**
|
||||
```powershell
|
||||
# PowerShell
|
||||
.\scripts\setup-windows-dev.ps1
|
||||
|
||||
# Command Prompt
|
||||
scripts\setup-windows-dev.bat
|
||||
```
|
||||
|
||||
**Manual vcpkg Setup:**
|
||||
```cmd
|
||||
git clone https://github.com/Microsoft/vcpkg.git
|
||||
cd vcpkg
|
||||
.\bootstrap-vcpkg.bat
|
||||
.\vcpkg.exe integrate install
|
||||
set VCPKG_ROOT=%CD%
|
||||
```
|
||||
|
||||
**Dependencies (vcpkg.json):**
|
||||
- zlib (compression)
|
||||
- libpng (PNG support)
|
||||
- sdl2 (graphics/input with Vulkan support)
|
||||
|
||||
**Note**: Abseil and gtest are built from source via CMake rather than through vcpkg to avoid compatibility issues.
|
||||
|
||||
#### Windows Build Commands
|
||||
|
||||
**Using CMake Presets:**
|
||||
```cmd
|
||||
# Debug build (minimal, no tests)
|
||||
cmake --preset windows-debug
|
||||
cmake --build build --preset windows-debug
|
||||
|
||||
# Development build (includes Google Test)
|
||||
cmake --preset windows-dev
|
||||
cmake --build build --preset windows-dev
|
||||
|
||||
# Release build (optimized, no tests)
|
||||
cmake --preset windows-release
|
||||
cmake --build build --preset windows-release
|
||||
```
|
||||
|
||||
**Using Visual Studio Projects:**
|
||||
```powershell
|
||||
# Generate project files (with proper vcpkg integration)
|
||||
python scripts/generate-vs-projects.py
|
||||
|
||||
# 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
|
||||
- **windows-release**: Optimized release build, no Google Test
|
||||
|
||||
## Build Targets
|
||||
|
||||
@@ -101,6 +195,28 @@ 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 (with proper vcpkg integration)
|
||||
python scripts/generate-vs-projects.py
|
||||
|
||||
# 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
|
||||
- Automatic vcpkg dependency management (zlib, libpng, SDL2)
|
||||
- Multi-platform support (x64, ARM64)
|
||||
- Automatic asset copying
|
||||
- Generated project files stay in sync with CMake configuration
|
||||
|
||||
### VS Code
|
||||
1. Install CMake Tools extension
|
||||
2. Open project, select "Debug" preset
|
||||
@@ -116,6 +232,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.py`**: Generate Visual Studio project files with proper vcpkg integration
|
||||
- **`generate-vs-projects.bat`**: Batch version of project generation
|
||||
|
||||
**Features:**
|
||||
- Automatic CMake detection and installation
|
||||
- Visual Studio 2022 detection
|
||||
- Multi-architecture support (x64, 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) |
|
||||
@@ -128,8 +284,135 @@ 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
|
||||
```
|
||||
|
||||
## CI/CD and Release Builds
|
||||
|
||||
### GitHub Actions Workflows
|
||||
|
||||
The project includes three release workflows with different levels of complexity:
|
||||
|
||||
- **`release-simplified.yml`**: Fast, basic release builds
|
||||
- **`release.yml`**: Standard release builds with fallback mechanisms
|
||||
- **`release-complex.yml`**: Comprehensive release builds with multiple fallback strategies
|
||||
|
||||
### vcpkg Fallback Mechanisms
|
||||
|
||||
All Windows CI/CD builds include automatic fallback mechanisms:
|
||||
|
||||
**When vcpkg succeeds:**
|
||||
- Full build with all dependencies (zlib, libpng, SDL2)
|
||||
- Complete feature set available
|
||||
|
||||
**When vcpkg fails (network issues):**
|
||||
- Automatic fallback to minimal build configuration
|
||||
- Uses source-built dependencies (Abseil, etc.)
|
||||
- Still produces functional executables
|
||||
|
||||
### Supported Architectures
|
||||
|
||||
**Windows:**
|
||||
- x64 (64-bit) - Primary target for modern systems
|
||||
- ARM64 - For ARM-based Windows devices (Surface Pro X, etc.)
|
||||
|
||||
**macOS:**
|
||||
- Universal binary (Apple Silicon + Intel)
|
||||
|
||||
**Linux:**
|
||||
- x64 (64-bit)
|
||||
|
||||
## 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
|
||||
|
||||
# Check installed packages
|
||||
vcpkg list
|
||||
```
|
||||
|
||||
**Network/Download Failures:**
|
||||
- The CI/CD workflows automatically fall back to minimal builds
|
||||
- For local development, ensure stable internet connection
|
||||
- If vcpkg consistently fails, use minimal build mode:
|
||||
```bash
|
||||
cmake -B build -DYAZE_MINIMAL_BUILD=ON
|
||||
```
|
||||
|
||||
**Visual Studio Integration:**
|
||||
```cmd
|
||||
# Re-integrate vcpkg
|
||||
cd C:\vcpkg
|
||||
.\vcpkg.exe integrate install
|
||||
```
|
||||
|
||||
**ZLIB or Other Dependencies Not Found:**
|
||||
```bash
|
||||
# Regenerate project files with proper vcpkg integration
|
||||
python scripts/generate-vs-projects.py
|
||||
|
||||
# Ensure vcpkg is properly set up
|
||||
.\scripts\setup-windows-dev.ps1
|
||||
```
|
||||
|
||||
### Architecture Errors (macOS)
|
||||
```bash
|
||||
# Clean and use ARM64-only preset
|
||||
@@ -151,3 +434,26 @@ 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 `python scripts/generate-vs-projects.py` to regenerate project files
|
||||
- Ensure CMake configuration completed successfully first
|
||||
|
||||
**CI/CD Build Failures:**
|
||||
- Check if vcpkg download failed (network issues)
|
||||
- The workflows automatically fall back to minimal builds
|
||||
- For persistent issues, check the workflow logs for specific error messages
|
||||
|
||||
@@ -228,7 +228,7 @@ absl::StatusOr<AsarPatchResult> ApplyPatch(
|
||||
|
||||
### Version Numbering
|
||||
- **Semantic Versioning**: MAJOR.MINOR.PATCH
|
||||
- **v0.3.0**: Current stable release
|
||||
- **v0.3.1**: Current stable release
|
||||
- **Pre-release**: v0.4.0-alpha, v0.4.0-beta
|
||||
|
||||
### Release Checklist
|
||||
|
||||
@@ -1,55 +0,0 @@
|
||||
# Platform Compatibility Improvements
|
||||
|
||||
Recent improvements to ensure YAZE works reliably across all supported platforms.
|
||||
|
||||
## Native File Dialog Support
|
||||
|
||||
YAZE now features native file dialogs on all platforms:
|
||||
- **macOS**: Cocoa-based file selection with proper sandboxing support
|
||||
- **Windows**: Windows Explorer integration with COM APIs
|
||||
- **Linux**: GTK3 dialogs that match system appearance
|
||||
- **Fallback**: Bespoke implementation when native dialogs unavailable
|
||||
|
||||
## Cross-Platform Build Reliability
|
||||
|
||||
Enhanced build system ensures consistent compilation:
|
||||
- **Windows**: Resolved MSVC compatibility issues and dependency conflicts
|
||||
- **Linux**: Fixed standard library compatibility for older distributions
|
||||
- **macOS**: Proper support for both Intel and Apple Silicon architectures
|
||||
- **All Platforms**: Bundled dependencies eliminate external package requirements
|
||||
|
||||
## Build Configuration Options
|
||||
|
||||
YAZE supports different build configurations for various use cases:
|
||||
|
||||
### Full Build (Development)
|
||||
Includes all features: emulator, CLI tools, UI testing framework, and optional libraries.
|
||||
|
||||
### Minimal Build
|
||||
Streamlined build excluding complex components, optimized for automated testing and CI environments.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
The build system automatically detects platform capabilities and adjusts feature sets accordingly:
|
||||
|
||||
- **File Dialogs**: Uses native platform dialogs when available, with cross-platform fallbacks
|
||||
- **Dependencies**: Bundles all required libraries to eliminate external package requirements
|
||||
- **Testing**: Separates ROM-dependent tests from unit tests for CI compatibility
|
||||
- **Architecture**: Supports both Intel and Apple Silicon on macOS without conflicts
|
||||
|
||||
## Platform-Specific Adaptations
|
||||
|
||||
### Windows
|
||||
- Complete COM-based file dialog implementation
|
||||
- MSVC compatibility improvements for modern C++ features
|
||||
- Resource file handling for proper application integration
|
||||
|
||||
### macOS
|
||||
- Cocoa-based native file dialogs with sandboxing support
|
||||
- Universal binary support for Intel and Apple Silicon
|
||||
- Proper bundle configuration for macOS applications
|
||||
|
||||
### Linux
|
||||
- GTK3 integration for native file dialogs
|
||||
- Package manager integration for system dependencies
|
||||
- Support for multiple compiler toolchains (GCC, Clang)
|
||||
308
docs/B4-release-workflows.md
Normal file
308
docs/B4-release-workflows.md
Normal file
@@ -0,0 +1,308 @@
|
||||
# Release Workflows Documentation
|
||||
|
||||
YAZE uses three different GitHub Actions workflows for creating releases, each designed for specific use cases and reliability levels. This document explains the differences, use cases, and when to use each workflow.
|
||||
|
||||
## Overview
|
||||
|
||||
| Workflow | Complexity | Reliability | Use Case |
|
||||
|----------|------------|-------------|----------|
|
||||
| **release-simplified.yml** | Low | Basic | Quick releases, testing |
|
||||
| **release.yml** | Medium | High | Standard releases |
|
||||
| **release-complex.yml** | High | Maximum | Production releases, fallbacks |
|
||||
|
||||
---
|
||||
|
||||
## 1. Release-Simplified (`release-simplified.yml`)
|
||||
|
||||
### Purpose
|
||||
A streamlined workflow for quick releases and testing scenarios.
|
||||
|
||||
### Key Features
|
||||
- **Minimal Configuration**: Basic build setup with standard dependencies
|
||||
- **No Fallback Mechanisms**: Direct dependency installation without error handling
|
||||
- **Standard vcpkg**: Uses fixed vcpkg commit without fallback options
|
||||
- **Basic Testing**: Simple executable verification
|
||||
|
||||
### Use Cases
|
||||
- **Development Testing**: Testing release process during development
|
||||
- **Beta Releases**: Quick beta or alpha releases
|
||||
- **Hotfixes**: Emergency releases that need to be deployed quickly
|
||||
- **CI/CD Validation**: Ensuring the basic release process works
|
||||
|
||||
### Configuration
|
||||
```yaml
|
||||
# Standard vcpkg setup
|
||||
vcpkgGitCommitId: 'c8696863d371ab7f46e213d8f5ca923c4aef2a00'
|
||||
# No fallback mechanisms
|
||||
# Basic dependency installation
|
||||
```
|
||||
|
||||
### Platforms Supported
|
||||
- Windows (x64, x86, ARM64)
|
||||
- macOS Universal
|
||||
- Linux x64
|
||||
|
||||
---
|
||||
|
||||
## 2. Release (`release.yml`)
|
||||
|
||||
### Purpose
|
||||
The standard production release workflow with enhanced reliability.
|
||||
|
||||
### Key Features
|
||||
- **Enhanced vcpkg**: Updated baseline and improved dependency management
|
||||
- **Better Error Handling**: More robust error reporting and debugging
|
||||
- **Comprehensive Testing**: Extended executable validation and artifact verification
|
||||
- **Production Ready**: Designed for stable releases
|
||||
|
||||
### Use Cases
|
||||
- **Stable Releases**: Official stable version releases
|
||||
- **Feature Releases**: Major feature releases with full testing
|
||||
- **Release Candidates**: Pre-release candidates for testing
|
||||
|
||||
### Configuration
|
||||
```yaml
|
||||
# Updated vcpkg baseline
|
||||
builtin-baseline: "2024.12.12"
|
||||
# Enhanced error handling
|
||||
# Comprehensive testing
|
||||
```
|
||||
|
||||
### Advantages over Simplified
|
||||
- More reliable dependency resolution
|
||||
- Better error reporting
|
||||
- Enhanced artifact validation
|
||||
- Production-grade stability
|
||||
|
||||
---
|
||||
|
||||
## 3. Release-Complex (`release-complex.yml`)
|
||||
|
||||
### Purpose
|
||||
Maximum reliability release workflow with comprehensive fallback mechanisms.
|
||||
|
||||
### Key Features
|
||||
- **Advanced Fallback System**: Multiple dependency installation strategies
|
||||
- **vcpkg Failure Handling**: Automatic fallback to manual dependency installation
|
||||
- **Chocolatey Integration**: Windows package manager fallback
|
||||
- **Comprehensive Debugging**: Extensive logging and error analysis
|
||||
- **Multiple Build Strategies**: CMake configuration fallbacks
|
||||
- **Enhanced Validation**: Multi-stage build verification
|
||||
|
||||
### Use Cases
|
||||
- **Production Releases**: Critical production releases requiring maximum reliability
|
||||
- **Enterprise Deployments**: Releases for enterprise customers
|
||||
- **Major Version Releases**: Significant version releases (v1.0, v2.0, etc.)
|
||||
- **Problem Resolution**: When other workflows fail due to dependency issues
|
||||
|
||||
### Fallback Mechanisms
|
||||
|
||||
#### vcpkg Fallback
|
||||
```yaml
|
||||
# Primary: vcpkg installation
|
||||
- name: Set up vcpkg (Windows)
|
||||
continue-on-error: true
|
||||
|
||||
# Fallback: Manual dependency installation
|
||||
- name: Install dependencies manually (Windows fallback)
|
||||
if: steps.vcpkg_setup.outcome == 'failure'
|
||||
```
|
||||
|
||||
#### Chocolatey Integration
|
||||
```yaml
|
||||
# Install Chocolatey if not present
|
||||
if (-not (Get-Command choco -ErrorAction SilentlyContinue)) {
|
||||
# Install Chocolatey
|
||||
}
|
||||
|
||||
# Install dependencies via Chocolatey
|
||||
choco install -y cmake ninja git python3
|
||||
```
|
||||
|
||||
#### Build Configuration Fallback
|
||||
```yaml
|
||||
# Primary: Full build with vcpkg
|
||||
cmake -DCMAKE_TOOLCHAIN_FILE="vcpkg.cmake" -DYAZE_MINIMAL_BUILD=OFF
|
||||
|
||||
# Fallback: Minimal build without vcpkg
|
||||
cmake -DYAZE_MINIMAL_BUILD=ON
|
||||
```
|
||||
|
||||
### Advanced Features
|
||||
- **Multi-stage Validation**: Visual Studio project validation
|
||||
- **Artifact Verification**: Comprehensive build artifact checking
|
||||
- **Debug Information**: Extensive logging for troubleshooting
|
||||
- **Environment Detection**: Automatic environment configuration
|
||||
|
||||
---
|
||||
|
||||
## Workflow Comparison Matrix
|
||||
|
||||
| Feature | Simplified | Release | Complex |
|
||||
|---------|------------|---------|---------|
|
||||
| **vcpkg Integration** | Basic | Enhanced | Advanced + Fallback |
|
||||
| **Error Handling** | Minimal | Standard | Comprehensive |
|
||||
| **Fallback Mechanisms** | None | Limited | Multiple |
|
||||
| **Debugging** | Basic | Standard | Extensive |
|
||||
| **Dependency Management** | Fixed | Updated | Adaptive |
|
||||
| **Build Validation** | Simple | Enhanced | Multi-stage |
|
||||
| **Failure Recovery** | None | Limited | Automatic |
|
||||
| **Production Ready** | No | Yes | Yes |
|
||||
| **Build Time** | Fast | Medium | Slow |
|
||||
| **Reliability** | Low | High | Maximum |
|
||||
|
||||
---
|
||||
|
||||
## When to Use Each Workflow
|
||||
|
||||
### Use Simplified When:
|
||||
- ✅ Testing release process during development
|
||||
- ✅ Creating beta or alpha releases
|
||||
- ✅ Quick hotfix releases
|
||||
- ✅ Validating basic CI/CD functionality
|
||||
- ✅ Development team testing
|
||||
|
||||
### Use Release When:
|
||||
- ✅ Creating stable production releases
|
||||
- ✅ Feature releases with full testing
|
||||
- ✅ Release candidates
|
||||
- ✅ Standard version releases
|
||||
- ✅ Most production scenarios
|
||||
|
||||
### Use Complex When:
|
||||
- ✅ Critical production releases
|
||||
- ✅ Major version releases (v1.0, v2.0)
|
||||
- ✅ Enterprise customer releases
|
||||
- ✅ When other workflows fail
|
||||
- ✅ Maximum reliability requirements
|
||||
- ✅ Complex dependency scenarios
|
||||
|
||||
---
|
||||
|
||||
## Workflow Selection Guide
|
||||
|
||||
### For Development Team
|
||||
```
|
||||
Development → Simplified
|
||||
Testing → Release
|
||||
Production → Complex
|
||||
```
|
||||
|
||||
### For Release Manager
|
||||
```
|
||||
Hotfix → Simplified
|
||||
Feature Release → Release
|
||||
Major Release → Complex
|
||||
```
|
||||
|
||||
### For CI/CD Pipeline
|
||||
```
|
||||
PR Validation → Simplified
|
||||
Nightly Builds → Release
|
||||
Release Pipeline → Complex
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### Triggering a Release
|
||||
|
||||
#### Manual Release (All Workflows)
|
||||
```bash
|
||||
# Using workflow_dispatch
|
||||
gh workflow run release.yml -f tag=v0.3.0
|
||||
gh workflow run release-simplified.yml -f tag=v0.3.0-beta
|
||||
gh workflow run release-complex.yml -f tag=v1.0.0
|
||||
```
|
||||
|
||||
#### Automatic Release (Tag Push)
|
||||
```bash
|
||||
# Creates release automatically
|
||||
git tag v0.3.0
|
||||
git push origin v0.3.0
|
||||
```
|
||||
|
||||
### Customizing Release Notes
|
||||
All workflows support automatic changelog extraction:
|
||||
```bash
|
||||
# Extract changelog for version
|
||||
python3 scripts/extract_changelog.py "0.3.0" > release_notes.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### vcpkg Failures (Windows)
|
||||
- **Simplified**: Fails completely
|
||||
- **Release**: Basic error reporting
|
||||
- **Complex**: Automatic fallback to manual installation
|
||||
|
||||
#### Dependency Conflicts
|
||||
- **Simplified**: Manual intervention required
|
||||
- **Release**: Enhanced error reporting
|
||||
- **Complex**: Multiple resolution strategies
|
||||
|
||||
#### Build Failures
|
||||
- **Simplified**: Basic error output
|
||||
- **Release**: Enhanced debugging
|
||||
- **Complex**: Comprehensive failure analysis
|
||||
|
||||
### Debug Information
|
||||
|
||||
#### Simplified Workflow
|
||||
- Basic build output
|
||||
- Simple error messages
|
||||
- Minimal logging
|
||||
|
||||
#### Release Workflow
|
||||
- Enhanced error reporting
|
||||
- Artifact verification
|
||||
- Build validation
|
||||
|
||||
#### Complex Workflow
|
||||
- Extensive debug output
|
||||
- Multi-stage validation
|
||||
- Comprehensive error analysis
|
||||
- Automatic fallback execution
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Workflow Selection
|
||||
1. **Start with Simplified** for development and testing
|
||||
2. **Use Release** for standard production releases
|
||||
3. **Use Complex** only when maximum reliability is required
|
||||
|
||||
### Release Process
|
||||
1. **Test with Simplified** first
|
||||
2. **Validate with Release** for production readiness
|
||||
3. **Use Complex** for critical releases
|
||||
|
||||
### Maintenance
|
||||
1. **Keep all workflows updated** with latest dependency versions
|
||||
2. **Monitor workflow performance** and adjust as needed
|
||||
3. **Document any custom modifications** for team knowledge
|
||||
|
||||
---
|
||||
|
||||
## Future Improvements
|
||||
|
||||
### Planned Enhancements
|
||||
- **Automated Workflow Selection**: Based on release type and criticality
|
||||
- **Enhanced Fallback Strategies**: Additional dependency resolution methods
|
||||
- **Performance Optimization**: Reduced build times while maintaining reliability
|
||||
- **Cross-Platform Consistency**: Unified behavior across all platforms
|
||||
|
||||
### Integration Opportunities
|
||||
- **Release Automation**: Integration with semantic versioning
|
||||
- **Quality Gates**: Automated quality checks before release
|
||||
- **Distribution**: Integration with package managers and app stores
|
||||
|
||||
---
|
||||
|
||||
*This documentation is maintained alongside the YAZE project. For updates or corrections, please refer to the project repository.*
|
||||
@@ -1,5 +1,64 @@
|
||||
# Changelog
|
||||
|
||||
## 0.3.1
|
||||
|
||||
### Major Features
|
||||
- **Complete Tile16 Editor Overhaul**: Professional-grade tile editing with modern UI and advanced capabilities
|
||||
- **Advanced Palette Management**: Full access to all SNES palette groups with configurable normalization
|
||||
- **Comprehensive Undo/Redo System**: 50-state history with intelligent time-based throttling
|
||||
- **ZSCustomOverworld v3 Full Support**: Complete implementation of ZScream Save.cs functionality with complex transition calculations
|
||||
- **ZEML System Removal**: Converted overworld editor from markup to pure ImGui for better performance and maintainability
|
||||
- **OverworldEditorManager**: New management system to handle complex v3 overworld features
|
||||
|
||||
### Tile16 Editor Enhancements
|
||||
- **Modern UI Layout**: Fully resizable 3-column interface (Tile8 Source, Editor, Preview & Controls)
|
||||
- **Multi-Palette Group Support**: Access to Overworld Main/Aux1/Aux2, Dungeon Main, Global Sprites, Armors, and Swords palettes
|
||||
- **Advanced Transform Operations**: Flip horizontal/vertical, rotate 90°, fill with tile8, clear operations
|
||||
- **Professional Workflow**: Copy/paste, 4-slot scratch space, live preview with auto-commit
|
||||
- **Pixel Normalization Settings**: Configurable pixel value masks (0x01-0xFF) for handling corrupted graphics sheets
|
||||
|
||||
### ZSCustomOverworld v3 Implementation
|
||||
- **SaveLargeMapsExpanded()**: Complex neighbor-aware transition calculations for all area sizes (Small, Large, Wide, Tall)
|
||||
- **Interactive Overlay System**: Full `SaveMapOverlays()` with ASM code generation for revealing holes and changing map elements
|
||||
- **SaveCustomOverworldASM()**: Complete custom overworld ASM application with feature toggles and data tables
|
||||
- **Expanded Memory Support**: Automatic detection and use of v3 expanded memory locations (0x140xxx)
|
||||
- **Area-Specific Features**: Background colors, main palettes, mosaic transitions, GFX groups, subscreen overlays, animated tiles
|
||||
- **Transition Logic**: Sophisticated camera transition calculations based on neighboring area types and quadrants
|
||||
- **Version Compatibility**: Maintains vanilla/v2 compatibility while adding full v3+ feature support
|
||||
|
||||
### Technical Improvements
|
||||
- **SNES Data Accuracy**: Proper 4-bit palette index handling with configurable normalization
|
||||
- **Bitmap Pipeline Fixes**: Corrected tile16 extraction using `GetTilemapData()` with manual fallback
|
||||
- **Real-time Updates**: Immediate visual feedback for all editing operations
|
||||
- **Memory Safety**: Enhanced bounds checking and error handling throughout
|
||||
- **ASM Version Detection**: Automatic detection of custom overworld ASM version for feature availability
|
||||
- **Conditional Save Logic**: Different save paths for vanilla, v2, and v3+ ROMs
|
||||
|
||||
### User Interface
|
||||
- **Keyboard Shortcuts**: Comprehensive shortcuts for all operations (H/V/R for transforms, Q/E for palette cycling, 1-8 for direct palette selection)
|
||||
- **Visual Feedback**: Hover preview restoration, current palette highlighting, texture status indicators
|
||||
- **Compact Controls**: Streamlined property panel with essential tools easily accessible
|
||||
- **Settings Dialog**: Advanced palette normalization controls with real-time application
|
||||
- **Pure ImGui Layout**: Removed ZEML markup system in favor of native ImGui tabs and tables for better performance
|
||||
- **v3 Settings Panel**: Dedicated UI for ZSCustomOverworld v3 features with ASM version detection and feature toggles
|
||||
|
||||
### Bug Fixes
|
||||
- **Tile16 Bitmap Display**: Fixed blank/white tile issue caused by unnormalized pixel values
|
||||
- **Hover Preview**: Restored tile8 preview when hovering over tile16 canvas
|
||||
- **Canvas Scaling**: Corrected coordinate scaling for 8x magnification factor
|
||||
- **Palette Corruption**: Fixed high-bit contamination in graphics sheets
|
||||
- **UI Layout**: Proper column sizing and resizing behavior
|
||||
- **Linux CI/CD Build**: Fixed undefined reference errors for `ShowSaveFileDialog` method
|
||||
- **ZSCustomOverworld v3**: Fixed complex area transition calculations and neighbor-aware tilemap adjustments
|
||||
- **ZEML Performance**: Eliminated markup parsing overhead by converting to native ImGui components
|
||||
|
||||
### ZScream Compatibility Improvements
|
||||
- **Complete Save.cs Implementation**: All major methods from ZScream's Save.cs now implemented in YAZE
|
||||
- **Area Size Support**: Full support for Small, Large, Wide, and Tall area types with proper transitions
|
||||
- **Interactive Overlays**: Complete overlay save system matching ZScream's functionality
|
||||
- **Custom ASM Integration**: Proper handling of ZSCustomOverworld ASM versions 1-3+
|
||||
- **Memory Layout**: Correct usage of expanded vs vanilla memory locations based on ROM type
|
||||
|
||||
## 0.3.0 (September 2025)
|
||||
|
||||
### Major Features
|
||||
|
||||
@@ -15,6 +15,7 @@ Yet Another Zelda3 Editor - A comprehensive ROM editor for The Legend of Zelda:
|
||||
- [Contributing](B1-contributing.md) - Development guidelines and standards
|
||||
- [Platform Compatibility](B2-platform-compatibility.md) - Cross-platform support details
|
||||
- [Build Presets](B3-build-presets.md) - CMake preset usage guide
|
||||
- [Release Workflows](B4-release-workflows.md) - GitHub Actions release pipeline documentation
|
||||
|
||||
## Technical Documentation
|
||||
|
||||
@@ -37,6 +38,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)
|
||||
|
||||
---
|
||||
|
||||
|
||||
165
docs/vcpkg-integration.md
Normal file
165
docs/vcpkg-integration.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# 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
|
||||
|
||||
vcpkg is Microsoft's C++ package manager that simplifies dependency management for Windows builds. YAZE now includes full vcpkg integration with manifest mode support for automatic dependency resolution.
|
||||
|
||||
## Features
|
||||
|
||||
- **Manifest Mode**: Dependencies are automatically managed via `vcpkg.json`
|
||||
- **Visual Studio Integration**: Seamless integration with Visual Studio 2022
|
||||
- **Generated Project Files**: Visual Studio project files with proper vcpkg integration
|
||||
- **CMake Presets**: Pre-configured build presets for Windows
|
||||
- **Automatic Setup**: Setup scripts for easy vcpkg installation
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Setup vcpkg
|
||||
|
||||
Run the automated setup script:
|
||||
```powershell
|
||||
# PowerShell (recommended)
|
||||
.\scripts\setup-windows-dev.ps1
|
||||
```
|
||||
|
||||
This will:
|
||||
- Set up vcpkg
|
||||
- Install dependencies (zlib, libpng, SDL2)
|
||||
- Generate Visual Studio project files with proper vcpkg integration
|
||||
|
||||
### 2. Build with Visual Studio
|
||||
|
||||
```powershell
|
||||
# Generate project files (if not already done)
|
||||
python scripts/generate-vs-projects.py
|
||||
|
||||
# Open YAZE.sln in Visual Studio 2022
|
||||
# Select configuration and platform, then build
|
||||
```
|
||||
|
||||
### 3. Alternative: Build with CMake
|
||||
|
||||
Use the Windows presets in CMakePresets.json:
|
||||
|
||||
```cmd
|
||||
# Debug build
|
||||
cmake --preset windows-debug
|
||||
cmake --build build --preset windows-debug
|
||||
|
||||
# Release build
|
||||
cmake --preset windows-release
|
||||
cmake --build build --preset windows-release
|
||||
```
|
||||
|
||||
## Configuration Details
|
||||
|
||||
### vcpkg.json Manifest
|
||||
|
||||
The `vcpkg.json` file defines all dependencies:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "yaze",
|
||||
"version": "0.3.1",
|
||||
"description": "Yet Another Zelda3 Editor",
|
||||
"dependencies": [
|
||||
{
|
||||
"name": "zlib",
|
||||
"platform": "!uwp"
|
||||
},
|
||||
{
|
||||
"name": "libpng",
|
||||
"platform": "!uwp"
|
||||
},
|
||||
{
|
||||
"name": "sdl2",
|
||||
"platform": "!uwp",
|
||||
"features": ["vulkan"]
|
||||
}
|
||||
],
|
||||
"builtin-baseline": "2024.12.12"
|
||||
}
|
||||
```
|
||||
|
||||
### CMake Configuration
|
||||
|
||||
vcpkg integration is handled in several files:
|
||||
|
||||
- **CMakeLists.txt**: Automatic toolchain detection
|
||||
- **cmake/vcpkg.cmake**: vcpkg-specific settings
|
||||
- **CMakePresets.json**: Windows build presets
|
||||
|
||||
### Build Presets
|
||||
|
||||
Available Windows presets:
|
||||
|
||||
- `windows-debug`: Debug build with vcpkg
|
||||
- `windows-release`: Release build with vcpkg
|
||||
|
||||
## Dependencies
|
||||
|
||||
vcpkg automatically installs these dependencies:
|
||||
|
||||
- **zlib**: Compression library
|
||||
- **libpng**: PNG image support
|
||||
- **sdl2**: Graphics and input handling (with Vulkan support)
|
||||
|
||||
**Note**: Abseil and gtest are now built from source via CMake rather than through vcpkg to avoid compatibility issues.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Set `VCPKG_ROOT` to point to your vcpkg installation:
|
||||
|
||||
```cmd
|
||||
set VCPKG_ROOT=C:\path\to\vcpkg
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **vcpkg not found**: Ensure `VCPKG_ROOT` is set or vcpkg is in the project directory
|
||||
2. **Dependencies not installing**: Check internet connection and vcpkg bootstrap
|
||||
3. **Visual Studio integration**: Run `vcpkg integrate install` from vcpkg directory
|
||||
|
||||
### Manual Setup
|
||||
|
||||
If automated setup fails:
|
||||
|
||||
```cmd
|
||||
git clone https://github.com/Microsoft/vcpkg.git
|
||||
cd vcpkg
|
||||
.\bootstrap-vcpkg.bat
|
||||
.\vcpkg.exe integrate install
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Consistent Dependencies**: Same versions across development environments
|
||||
- **Easy Updates**: Update dependencies via vcpkg.json
|
||||
- **CI/CD Friendly**: Reproducible builds
|
||||
- **Visual Studio Integration**: Native IntelliSense support
|
||||
- **No Manual Downloads**: Automatic dependency resolution
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Custom Triplets
|
||||
|
||||
Override the default x64-windows triplet:
|
||||
|
||||
```cmd
|
||||
cmake --preset windows-debug -DVCPKG_TARGET_TRIPLET=x86-windows
|
||||
```
|
||||
|
||||
### Static Linking
|
||||
|
||||
For static builds, modify `cmake/vcpkg.cmake`:
|
||||
|
||||
```cmake
|
||||
set(VCPKG_LIBRARY_LINKAGE static)
|
||||
set(VCPKG_CRT_LINKAGE static)
|
||||
```
|
||||
117
docs/vcpkg-triplet-setup.md
Normal file
117
docs/vcpkg-triplet-setup.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# Installing vcpkg Triplets for Windows
|
||||
|
||||
This guide explains how to install the `x64-windows` triplet that's required for building YAZE on Windows.
|
||||
|
||||
## What is a vcpkg Triplet?
|
||||
|
||||
A triplet defines the target platform, architecture, and linking configuration for vcpkg packages. The `x64-windows` triplet is the most common one for 64-bit Windows development.
|
||||
|
||||
## Method 1: Install via Package (Recommended)
|
||||
|
||||
The easiest way to ensure the triplet is available is to install any package with that triplet:
|
||||
|
||||
```cmd
|
||||
# Navigate to your vcpkg directory
|
||||
cd C:\path\to\your\vcpkg
|
||||
|
||||
# Install a package with the x64-windows triplet
|
||||
vcpkg install sdl2:x64-windows
|
||||
```
|
||||
|
||||
This will automatically create the triplet configuration if it doesn't exist.
|
||||
|
||||
## Method 2: Create Triplet File Manually
|
||||
|
||||
If you need to create the triplet configuration manually:
|
||||
|
||||
1. **Navigate to vcpkg triplets directory:**
|
||||
```cmd
|
||||
cd C:\path\to\your\vcpkg\triplets
|
||||
```
|
||||
|
||||
2. **Create or verify `x64-windows.cmake` exists:**
|
||||
```cmd
|
||||
dir x64-windows.cmake
|
||||
```
|
||||
|
||||
3. **If it doesn't exist, create it with this content:**
|
||||
```cmake
|
||||
set(VCPKG_TARGET_ARCHITECTURE x64)
|
||||
set(VCPKG_CRT_LINKAGE dynamic)
|
||||
set(VCPKG_LIBRARY_LINKAGE dynamic)
|
||||
|
||||
set(VCPKG_CMAKE_SYSTEM_NAME Windows)
|
||||
```
|
||||
|
||||
## Method 3: Check Available Triplets
|
||||
|
||||
To see what triplets are currently available on your system:
|
||||
|
||||
```cmd
|
||||
vcpkg help triplet
|
||||
```
|
||||
|
||||
Or list all available triplet files:
|
||||
|
||||
```cmd
|
||||
vcpkg help triplet | findstr "Available"
|
||||
```
|
||||
|
||||
## Method 4: Install YAZE Dependencies
|
||||
|
||||
Since YAZE uses several vcpkg packages, installing them will ensure the triplet is properly set up:
|
||||
|
||||
```cmd
|
||||
# From the YAZE project root
|
||||
vcpkg install --triplet x64-windows sdl2 zlib libpng abseil
|
||||
```
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue: "Invalid triplet"
|
||||
**Solution:** Make sure vcpkg is properly installed and in your PATH:
|
||||
```cmd
|
||||
vcpkg version
|
||||
```
|
||||
|
||||
### Issue: "Triplet not found"
|
||||
**Solution:** Install a package with that triplet first:
|
||||
```cmd
|
||||
vcpkg install zlib:x64-windows
|
||||
```
|
||||
|
||||
### Issue: "Permission denied"
|
||||
**Solution:** Run Command Prompt as Administrator, or install vcpkg in a user-writable location.
|
||||
|
||||
## Alternative Triplets
|
||||
|
||||
If `x64-windows` doesn't work, you can try these alternatives:
|
||||
|
||||
- `x64-windows-static` - Static linking
|
||||
- `x86-windows` - 32-bit Windows
|
||||
- `x64-windows-static-md` - Static runtime, dynamic CRT
|
||||
|
||||
## Verification
|
||||
|
||||
To verify the triplet is working:
|
||||
|
||||
```cmd
|
||||
vcpkg list --triplet x64-windows
|
||||
```
|
||||
|
||||
This should show installed packages for that triplet.
|
||||
|
||||
## For YAZE Build
|
||||
|
||||
Once the triplet is installed, you can build YAZE using CMake presets:
|
||||
|
||||
```cmd
|
||||
cmake --preset=windows-release
|
||||
cmake --build build --config Release
|
||||
```
|
||||
|
||||
Or with the Visual Studio solution:
|
||||
```cmd
|
||||
# Open yaze.sln in Visual Studio
|
||||
# Build normally (F5 or Ctrl+Shift+B)
|
||||
```
|
||||
284
docs/visual-studio-setup.md
Normal file
284
docs/visual-studio-setup.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# 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
|
||||
|
||||
### 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 Build System
|
||||
|
||||
#### 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
|
||||
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)
|
||||
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)
|
||||
- **Debug Build:** Select "Debug" configuration and press F5 or Ctrl+Shift+B
|
||||
- **Release Build:** Select "Release" configuration and press F5 or Ctrl+Shift+B
|
||||
- **Platform:** Choose x64 (recommended) or x86 from the platform dropdown
|
||||
|
||||
#### Using CMake (Command Line)
|
||||
```cmd
|
||||
# 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:
|
||||
```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
|
||||
|
||||
### Using Visual Studio Project File
|
||||
1. Open `yaze.sln` in Visual Studio
|
||||
2. Set `yaze` as the startup project (should be default)
|
||||
3. Configure command line arguments in Project Properties > Debugging > Command Arguments
|
||||
- Example: `--rom_file=C:\path\to\your\zelda3.sfc`
|
||||
4. Press F5 to build and run, or Ctrl+F5 to run without debugging
|
||||
|
||||
### Command Line
|
||||
```cmd
|
||||
cd build/bin/Debug # or Release
|
||||
yaze.exe --rom_file=path/to/your/zelda3.sfc
|
||||
```
|
||||
|
||||
### Visual Studio (CMake)
|
||||
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
|
||||
```
|
||||
|
||||
## Visual Studio Project File Features
|
||||
|
||||
The included `yaze.vcxproj` and `yaze.sln` files provide:
|
||||
|
||||
### **Automatic Dependency Management**
|
||||
- **vcpkg Integration:** Automatically installs and links dependencies from `vcpkg.json`
|
||||
- **Platform Support:** Pre-configured for both x64 and x86 builds
|
||||
- **Library Linking:** Automatically links SDL2, zlib, libpng, and system libraries
|
||||
|
||||
### **Build Configuration**
|
||||
- **Debug Configuration:** Includes debugging symbols and runtime checks
|
||||
- **Release Configuration:** Optimized for performance with full optimizations
|
||||
- **C++23 Standard:** Uses modern C++ features and standard library
|
||||
|
||||
### **Asset Management**
|
||||
- **Automatic Asset Copying:** Post-build events copy themes and assets to output directory
|
||||
- **ROM File Handling:** Automatically copies `zelda3.sfc` if present in project root
|
||||
- **Resource Organization:** Properly structures output directory for distribution
|
||||
|
||||
### **Development Features**
|
||||
- **IntelliSense Support:** Full code completion and error detection
|
||||
- **Debugging Integration:** Native Visual Studio debugging support
|
||||
- **Project Properties:** Easy access to compiler and linker settings
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
The Visual Studio project files are fully integrated into the CI/CD pipeline:
|
||||
|
||||
### **Automated Validation**
|
||||
- **Pre-commit checks:** Visual Studio builds are validated on every pull request
|
||||
- **Release validation:** Both CMake and Visual Studio builds are tested before release
|
||||
- **Multi-platform testing:** x64 and x86 builds are validated on Windows
|
||||
- **Dependency verification:** vcpkg integration is tested automatically
|
||||
|
||||
### **Build Matrix**
|
||||
The CI/CD pipeline tests:
|
||||
- **Windows x64 Debug/Release** using Visual Studio 2022
|
||||
- **Windows x86 Debug/Release** using Visual Studio 2022
|
||||
- **CMake builds** alongside Visual Studio builds for compatibility
|
||||
- **Asset copying** and executable functionality
|
||||
|
||||
### **Quality Assurance**
|
||||
- **Test main detection:** Prevents the test framework from hijacking the main application
|
||||
- **Asset validation:** Ensures themes and resources are properly copied
|
||||
- **Executable testing:** Verifies the application starts correctly
|
||||
- **Dependency checking:** Validates all required libraries are properly linked
|
||||
|
||||
## 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 validates both CMake and Visual Studio builds
|
||||
- Development builds include additional debugging features and ROM testing capabilities
|
||||
- The `.vcxproj` file provides the easiest setup for Visual Studio users who prefer traditional project files over CMake
|
||||
- All builds are automatically validated to ensure they produce working executables
|
||||
|
||||
## 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
|
||||
346
docs/windows-development-guide.md
Normal file
346
docs/windows-development-guide.md
Normal file
@@ -0,0 +1,346 @@
|
||||
# Windows Development Guide for YAZE
|
||||
|
||||
This guide will help you set up a Windows development environment for YAZE and build the project successfully.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Software
|
||||
|
||||
1. **Visual Studio 2022** (Community, Professional, or Enterprise)
|
||||
- Download from: https://visualstudio.microsoft.com/downloads/
|
||||
- Required workloads:
|
||||
- Desktop development with C++
|
||||
- Game development with C++ (optional, for additional tools)
|
||||
|
||||
2. **Git for Windows**
|
||||
- Download from: https://git-scm.com/download/win
|
||||
- Use default installation options
|
||||
|
||||
3. **Python 3.8 or later**
|
||||
- Download from: https://www.python.org/downloads/
|
||||
- Make sure to check "Add Python to PATH" during installation
|
||||
|
||||
### Optional Software
|
||||
|
||||
- **PowerShell 7** (recommended for better script support)
|
||||
- **Windows Terminal** (for better terminal experience)
|
||||
|
||||
## Quick Setup
|
||||
|
||||
### Automated Setup
|
||||
|
||||
The easiest way to get started is to use our automated setup script:
|
||||
|
||||
```powershell
|
||||
# Run from the YAZE project root directory
|
||||
.\scripts\setup-windows-dev.ps1
|
||||
```
|
||||
|
||||
This script will:
|
||||
- Check for required software (Visual Studio 2022, Git, Python)
|
||||
- Set up vcpkg and install dependencies (zlib, libpng, SDL2)
|
||||
- Generate Visual Studio project files with proper vcpkg integration
|
||||
- Perform a test build to verify everything works
|
||||
|
||||
### Manual Setup
|
||||
|
||||
If you prefer to set up manually or the automated script fails:
|
||||
|
||||
#### 1. Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-username/yaze.git
|
||||
cd yaze
|
||||
```
|
||||
|
||||
#### 2. Set up vcpkg
|
||||
|
||||
```bash
|
||||
# Clone vcpkg
|
||||
git clone https://github.com/Microsoft/vcpkg.git vcpkg
|
||||
|
||||
# Bootstrap vcpkg
|
||||
cd vcpkg
|
||||
.\bootstrap-vcpkg.bat
|
||||
cd ..
|
||||
|
||||
# Install dependencies
|
||||
.\vcpkg\vcpkg.exe install --triplet x64-windows
|
||||
```
|
||||
|
||||
#### 3. Generate Visual Studio Project Files
|
||||
|
||||
The generation script creates project files with proper vcpkg integration:
|
||||
|
||||
```bash
|
||||
python scripts/generate-vs-projects.py
|
||||
```
|
||||
|
||||
This creates:
|
||||
- `YAZE.sln` - Visual Studio solution file
|
||||
- `YAZE.vcxproj` - Visual Studio project file with vcpkg integration
|
||||
- Proper vcpkg triplet settings for all platforms (x86, x64, ARM64)
|
||||
|
||||
#### 4. Build the Project
|
||||
|
||||
```bash
|
||||
# Using PowerShell script (recommended)
|
||||
.\scripts\build-windows.ps1 -Configuration Release -Platform x64
|
||||
|
||||
# Or using batch script
|
||||
.\scripts\build-windows.bat Release x64
|
||||
|
||||
# Or using Visual Studio
|
||||
# Open YAZE.sln in Visual Studio 2022 and build
|
||||
```
|
||||
|
||||
## Building the Project
|
||||
|
||||
### Using Visual Studio
|
||||
|
||||
1. Open `YAZE.sln` in Visual Studio 2022
|
||||
2. Select your desired configuration:
|
||||
- **Debug**: For development and debugging
|
||||
- **Release**: For optimized builds
|
||||
- **RelWithDebInfo**: Release with debug information
|
||||
- **MinSizeRel**: Minimal size release
|
||||
3. Select your platform:
|
||||
- **x64**: 64-bit (recommended)
|
||||
- **x86**: 32-bit
|
||||
- **ARM64**: ARM64 (if supported)
|
||||
4. Build the solution (Ctrl+Shift+B)
|
||||
|
||||
### Using Command Line
|
||||
|
||||
#### PowerShell Script (Recommended)
|
||||
|
||||
```powershell
|
||||
# Build Release x64 (default)
|
||||
.\scripts\build-windows.ps1
|
||||
|
||||
# Build Debug x64
|
||||
.\scripts\build-windows.ps1 -Configuration Debug -Platform x64
|
||||
|
||||
# Build Release x86
|
||||
.\scripts\build-windows.ps1 -Configuration Release -Platform x86
|
||||
|
||||
# Clean build
|
||||
.\scripts\build-windows.ps1 -Clean
|
||||
|
||||
# Verbose output
|
||||
.\scripts\build-windows.ps1 -Verbose
|
||||
```
|
||||
|
||||
#### Batch Script
|
||||
|
||||
```batch
|
||||
REM Build Release x64 (default)
|
||||
.\scripts\build-windows.bat
|
||||
|
||||
REM Build Debug x64
|
||||
.\scripts\build-windows.bat Debug x64
|
||||
|
||||
REM Build Release x86
|
||||
.\scripts\build-windows.bat Release x86
|
||||
```
|
||||
|
||||
#### Direct MSBuild
|
||||
|
||||
```bash
|
||||
# Build Release x64
|
||||
msbuild YAZE.sln /p:Configuration=Release /p:Platform=x64 /p:VcpkgEnabled=true /p:VcpkgManifestInstall=true /m
|
||||
|
||||
# Build Debug x64
|
||||
msbuild YAZE.sln /p:Configuration=Debug /p:Platform=x64 /p:VcpkgEnabled=true /p:VcpkgManifestInstall=true /m
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
yaze/
|
||||
├── YAZE.sln # Visual Studio solution file (generated)
|
||||
├── YAZE.vcxproj # Visual Studio project file (generated)
|
||||
├── vcpkg.json # vcpkg dependencies
|
||||
├── scripts/ # Build and setup scripts
|
||||
│ ├── build-windows.ps1 # PowerShell build script
|
||||
│ ├── build-windows.bat # Batch build script
|
||||
│ ├── setup-windows-dev.ps1 # Automated setup script
|
||||
│ └── generate-vs-projects.py # Project file generator
|
||||
├── src/ # Source code
|
||||
├── incl/ # Public headers
|
||||
├── assets/ # Game assets
|
||||
└── docs/ # Documentation
|
||||
```
|
||||
|
||||
**Note**: The Visual Studio project files (`YAZE.sln`, `YAZE.vcxproj`) are generated automatically and should not be edited manually. If you need to modify project settings, update the generation script instead.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### 1. MSBuild Not Found
|
||||
|
||||
**Error**: `'msbuild' is not recognized as an internal or external command`
|
||||
|
||||
**Solution**:
|
||||
- Install Visual Studio 2022 with C++ workload
|
||||
- Or add MSBuild to your PATH:
|
||||
```bash
|
||||
# Add to PATH (adjust path as needed)
|
||||
C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin
|
||||
```
|
||||
|
||||
#### 2. vcpkg Integration Issues
|
||||
|
||||
**Error**: `vcpkg.json not found` or dependency resolution fails
|
||||
|
||||
**Solution**:
|
||||
- Ensure vcpkg is properly set up:
|
||||
```bash
|
||||
.\scripts\setup-windows-dev.ps1
|
||||
```
|
||||
- Or manually set up vcpkg as described in the manual setup section
|
||||
|
||||
#### 3. ZLIB or Other Dependencies Not Found
|
||||
|
||||
**Error**: `Could NOT find ZLIB (missing: ZLIB_LIBRARY ZLIB_INCLUDE_DIR)`
|
||||
|
||||
**Solution**:
|
||||
- This usually means vcpkg integration isn't working properly
|
||||
- Regenerate project files with proper vcpkg integration:
|
||||
```bash
|
||||
python scripts/generate-vs-projects.py
|
||||
```
|
||||
- Ensure vcpkg is installed and dependencies are available:
|
||||
```bash
|
||||
.\vcpkg\vcpkg.exe install --triplet x64-windows
|
||||
```
|
||||
|
||||
#### 4. Python Script Execution Policy
|
||||
|
||||
**Error**: `execution of scripts is disabled on this system`
|
||||
|
||||
**Solution**:
|
||||
```powershell
|
||||
# Run as Administrator
|
||||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
```
|
||||
|
||||
#### 5. Missing Dependencies
|
||||
|
||||
**Error**: Linker errors about missing libraries
|
||||
|
||||
**Solution**:
|
||||
- Ensure all dependencies are installed via vcpkg:
|
||||
```bash
|
||||
.\vcpkg\vcpkg.exe install --triplet x64-windows
|
||||
```
|
||||
- Regenerate project files:
|
||||
```bash
|
||||
python scripts/generate-vs-projects.py
|
||||
```
|
||||
|
||||
#### 6. Build Failures
|
||||
|
||||
**Error**: Compilation or linking errors
|
||||
|
||||
**Solution**:
|
||||
- Clean and rebuild:
|
||||
```powershell
|
||||
.\scripts\build-windows.ps1 -Clean
|
||||
```
|
||||
- Check that all source files are included in the project
|
||||
- Verify that include paths are correct
|
||||
|
||||
### Getting Help
|
||||
|
||||
If you encounter issues not covered here:
|
||||
|
||||
1. Check the [main build instructions](02-build-instructions.md)
|
||||
2. Review the [troubleshooting section](02-build-instructions.md#troubleshooting)
|
||||
3. Check the [GitHub Issues](https://github.com/your-username/yaze/issues)
|
||||
4. Create a new issue with:
|
||||
- Your Windows version
|
||||
- Visual Studio version
|
||||
- Complete error message
|
||||
- Steps to reproduce
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Making Changes
|
||||
|
||||
1. Make your changes to the source code
|
||||
2. If you added new source files, regenerate project files:
|
||||
```bash
|
||||
python scripts/generate-vs-projects.py
|
||||
```
|
||||
3. Build the project:
|
||||
```powershell
|
||||
.\scripts\build-windows.ps1 -Configuration Debug -Platform x64
|
||||
```
|
||||
4. Test your changes
|
||||
|
||||
### Debugging
|
||||
|
||||
1. Set breakpoints in Visual Studio
|
||||
2. Build in Debug configuration
|
||||
3. Run with debugger (F5)
|
||||
4. Use Visual Studio's debugging tools
|
||||
|
||||
### Testing
|
||||
|
||||
1. Build the project
|
||||
2. Run the executable:
|
||||
```bash
|
||||
.\build\bin\Debug\yaze.exe
|
||||
```
|
||||
3. Test with a ROM file:
|
||||
```bash
|
||||
.\build\bin\Debug\yaze.exe --rom_file=path\to\your\rom.sfc
|
||||
```
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### Build Performance
|
||||
|
||||
- Use the `/m` flag for parallel builds
|
||||
- Use SSD storage for better I/O performance
|
||||
- Exclude build directories from antivirus scanning
|
||||
- Use Release configuration for final builds
|
||||
|
||||
### Development Performance
|
||||
|
||||
- Use Debug configuration for development
|
||||
- Use incremental builds (default in Visual Studio)
|
||||
- Use RelWithDebInfo for performance testing with debug info
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Custom Build Configurations
|
||||
|
||||
You can create custom build configurations by modifying the Visual Studio project file or using CMake directly.
|
||||
|
||||
### Cross-Platform Development
|
||||
|
||||
While this guide focuses on Windows, YAZE also supports:
|
||||
- Linux (Ubuntu/Debian)
|
||||
- macOS
|
||||
|
||||
See the main build instructions for other platforms.
|
||||
|
||||
## Contributing
|
||||
|
||||
When contributing to YAZE on Windows:
|
||||
|
||||
1. Follow the [coding standards](B1-contributing.md)
|
||||
2. Test your changes on Windows
|
||||
3. Ensure the build scripts still work
|
||||
4. Update documentation if needed
|
||||
5. Submit a pull request
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Visual Studio Documentation](https://docs.microsoft.com/en-us/visualstudio/)
|
||||
- [vcpkg Documentation](https://vcpkg.readthedocs.io/)
|
||||
- [CMake Documentation](https://cmake.org/documentation/)
|
||||
- [YAZE API Reference](04-api-reference.md)
|
||||
Reference in New Issue
Block a user