347 lines
8.7 KiB
Markdown
347 lines
8.7 KiB
Markdown
# 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)
|