scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor Windows build instructions and remove legacy scripts

Browse Source 
- Updated `02-build-instructions.md` to enhance clarity and organization, including renaming sections for better understanding.
- Removed outdated automated setup scripts (`build-windows.bat`, `build-windows.ps1`, `setup-windows-dev.ps1`, and `validate-windows-build.ps1`) to streamline the build process.
- Introduced optional vcpkg setup for SDL2 dependency management, emphasizing the use of bundled dependencies by default.
- Improved documentation for Visual Studio CMake workflow, highlighting the recommended approach for building the project.
- Consolidated and clarified command line build instructions, ensuring a more straightforward setup experience for developers.
This commit is contained in:
scawful
2025-10-01 09:48:05 -04:00
parent 508c5402ed
commit 4df97fb812
6 changed files with 105 additions and 1037 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
scripts/README.md
View File

@@ -4,151 +4,65 @@ This directory contains build and setup scripts for YAZE development on differen
## Windows Scripts
### Setup Scripts
- **`setup-windows-dev.ps1`** - Complete Windows development environment setup (PowerShell)
- **`setup-vcpkg-windows.ps1`** - vcpkg setup only (PowerShell)
- **`setup-vcpkg-windows.bat`** - vcpkg setup only (Batch)
### vcpkg Setup (Optional)
- **`setup-vcpkg-windows.ps1`** - Setup vcpkg for SDL2 dependency (PowerShell)
- **`setup-vcpkg-windows.bat`** - Setup vcpkg for SDL2 dependency (Batch)
### Build Scripts
- **`build-windows.ps1`** - Build YAZE on Windows (PowerShell)
- **`build-windows.bat`** - Build YAZE on Windows (Batch)
**Note**: vcpkg is optional. YAZE uses bundled dependencies by default.
### Validation Scripts
- **`validate-windows-build.ps1`** - Validate Windows build environment
## Windows Build Workflow
### Project Generation
- **`generate-vs-projects.py`** - Generate Visual Studio project files (Cross-platform Python)
### Recommended: Visual Studio CMake Mode
## Windows Compiler Recommendations
**YAZE uses Visual Studio's native CMake support - no project generation needed.**
### ⚠️ Important: MSVC vs Clang on Windows
1. **Install Visual Studio 2022** with "Desktop development with C++" workload
2. **Open Visual Studio 2022**
3. **File → Open → Folder**
4. **Navigate to yaze directory**
5. **Select configuration** (Debug/Release) from toolbar
6. **Press F5** to build and run
**We strongly recommend using Clang on Windows** due to compatibility issues with MSVC and Abseil's int128 and type_traits features:
### Command Line Build
#### Why Clang is Recommended:
- ✅ **Better C++23 Support**: Full support for modern C++23 features
- ✅ **Abseil Compatibility**: No issues with `absl::int128` and type traits
- ✅ **Cross-Platform Consistency**: Same compiler across all platforms
- ✅ **Better Error Messages**: More helpful diagnostic messages
- ✅ **Faster Compilation**: Generally faster than MSVC
#### MSVC Issues:
- ❌ **C++23 Deprecation Warnings**: Abseil int128 triggers numerous deprecation warnings
- ❌ **Type Traits Problems**: Some Abseil type traits don't work correctly with MSVC
- ❌ **Int128 Limitations**: MSVC's int128 support is incomplete
- ❌ **Build Complexity**: Requires additional workarounds and flags
### Compiler Setup Options
#### Option 1: Clang (Recommended)
```powershell
# Install LLVM/Clang via winget
winget install LLVM.LLVM
# Standard CMake workflow
cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug
# Or download from: https://releases.llvm.org/
# Make sure to add Clang to PATH during installation
# Verify installation
clang --version
# Run the application
.\build\bin\Debug\yaze.exe
```
#### Option 2: MSVC with Workarounds
If you must use MSVC, the build system includes workarounds:
- Abseil int128 is automatically disabled on Windows
- C++23 deprecation warnings are silenced
- Additional compatibility flags are applied
### Compiler Notes
However, you may still encounter issues with some Abseil features.
The CMake configuration is designed to work with **MSVC** (Visual Studio's compiler). The build system includes automatic workarounds for C++23 compatibility:
- Abseil int128 is automatically excluded on Windows
- C++23 deprecation warnings are properly silenced
- Platform-specific definitions are handled automatically
## Quick Start (Windows)
### Option 1: Automated Setup (Recommended)
### Option 1: Visual Studio (Recommended)
1. Open Visual Studio 2022
2. File → Open → Folder
3. Navigate to yaze directory
4. Select configuration (Debug/Release)
5. Press F5 to build and run
### Option 2: Command Line
```powershell
.\scripts\setup-windows-dev.ps1
# Standard CMake build
cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug
```
### Option 2: Manual Setup
### Option 3: With vcpkg (Optional)
```powershell
# 1. Setup vcpkg
# Setup vcpkg for SDL2
.\scripts\setup-vcpkg-windows.ps1
# 2. Generate project files
python scripts/generate-vs-projects.py
# 3. Build
.\scripts\build-windows.ps1
```
### Option 3: Using Batch Scripts
```batch
REM Setup vcpkg
.\scripts\setup-vcpkg-windows.bat
REM Generate project files
python scripts/generate-vs-projects.py
REM Build
.\scripts\build-windows.bat
```
## Script Options
### setup-windows-dev.ps1
- `-SkipVcpkg` - Skip vcpkg setup
- `-SkipVS` - Skip Visual Studio check
- `-SkipBuild` - Skip test build
### build-windows.ps1
- `-Configuration` - Build configuration (Debug, Release, RelWithDebInfo, MinSizeRel)
- `-Platform` - Target platform (x64, x86, ARM64)
- `-Compiler` - Compiler to use (clang, msvc, auto)
- `-Clean` - Clean build directories before building
- `-Verbose` - Verbose build output
### build-windows.bat
- First argument: Configuration (Debug, Release, RelWithDebInfo, MinSizeRel)
- Second argument: Platform (x64, x86, ARM64)
- Third argument: Compiler (clang, msvc, auto)
- `clean` - Clean build directories
- `verbose` - Verbose build output
## Examples
```powershell
# Build Release x64 with Clang (recommended)
.\scripts\build-windows.ps1 -Compiler clang
# Build Release x64 with MSVC (with workarounds)
.\scripts\build-windows.ps1 -Compiler msvc
# Build Debug x64 with Clang
.\scripts\build-windows.ps1 -Configuration Debug -Platform x64 -Compiler clang
# Build Release x86 with auto-detection
.\scripts\build-windows.ps1 -Configuration Release -Platform x86 -Compiler auto
# Clean build with Clang
.\scripts\build-windows.ps1 -Clean -Compiler clang
# Verbose build with MSVC
.\scripts\build-windows.ps1 -Verbose -Compiler msvc
# Validate environment
.\scripts\validate-windows-build.ps1
```
```batch
REM Build Release x64 with Clang (recommended)
.\scripts\build-windows.bat Release x64 clang
REM Build Debug x64 with MSVC
.\scripts\build-windows.bat Debug x64 msvc
REM Build Release x86 with auto-detection
.\scripts\build-windows.bat Release x86 auto
REM Clean build with Clang
.\scripts\build-windows.bat clean clang
# Then build normally in Visual Studio or command line
```
## Troubleshooting
@@ -160,38 +74,31 @@ REM Clean build with Clang
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
2. **MSBuild Not Found**
- Install Visual Studio 2022 with C++ workload
- Or add MSBuild to PATH
2. **Visual Studio Not Detecting CMakeLists.txt**
- Ensure you opened the folder (not a solution file)
- Check that CMakeLists.txt exists in the root directory
- Try: File → Close Folder, then File → Open → Folder
3. **vcpkg Issues**
3. **vcpkg Issues (if using vcpkg)**
- Run `.\scripts\setup-vcpkg-windows.ps1` to reinstall
- Check internet connection for dependency downloads
- Note: vcpkg is optional; bundled dependencies work by default
4. **Python Not Found**
- Install Python 3.8+ from python.org
- Make sure Python is in PATH
4. **CMake Configuration Errors**
- Delete the `build/` directory
- Close and reopen the folder in Visual Studio
- Or run: `cmake -B build -DCMAKE_BUILD_TYPE=Debug`
5. **MSVC Compilation Errors**
- **Abseil int128 errors**: Use Clang instead (`-Compiler clang`)
- **C++23 deprecation warnings**: These are silenced automatically, but Clang is cleaner
- **Type traits issues**: Switch to Clang for better compatibility
- **Solution**: Install Clang and use `.\scripts\build-windows.ps1 -Compiler clang`
6. **Clang Not Found**
- Install LLVM/Clang: `winget install LLVM.LLVM`
- Or download from: https://releases.llvm.org/
- Make sure Clang is in PATH: `clang --version`
7. **Compiler Detection Issues**
- Use explicit compiler selection: `-Compiler clang` or `-Compiler msvc`
- Check available compilers: `where clang` and `where cl`
5. **Missing Git Submodules**
```powershell
git submodule update --init --recursive
```
### Getting Help
1. Run validation script: `.\scripts\validate-windows-build.ps1`
2. Check the [Windows Development Guide](../docs/windows-development-guide.md)
3. Review build output for specific error messages
1. Check the [Build Instructions](../docs/02-build-instructions.md)
2. Review CMake output for specific error messages
3. Ensure all prerequisites are installed (Visual Studio 2022 with C++ workload)
## Other Scripts