265 lines
8.5 KiB
Markdown
265 lines
8.5 KiB
Markdown
# YAZE Build Guide
|
|
|
|
**Status**: CI/CD Overhaul Complete ✅
|
|
**Last Updated**: October 2025
|
|
**Platforms**: macOS (ARM64/Intel), Linux, Windows
|
|
|
|
## Quick Start
|
|
|
|
### macOS (Apple Silicon)
|
|
```bash
|
|
# Basic debug build
|
|
cmake --preset mac-dbg && cmake --build --preset mac-dbg
|
|
|
|
# With AI features (z3ed agent, gRPC, JSON)
|
|
cmake --preset mac-ai && cmake --build --preset mac-ai
|
|
|
|
# Release build
|
|
cmake --preset mac-rel && cmake --build --preset mac-rel
|
|
```
|
|
|
|
### Linux
|
|
```bash
|
|
# Debug build
|
|
cmake --preset lin-dbg && cmake --build --preset lin-dbg
|
|
|
|
# With AI features
|
|
cmake --preset lin-ai && cmake --build --preset lin-ai
|
|
```
|
|
|
|
### Windows (Visual Studio)
|
|
```bash
|
|
# Debug build
|
|
cmake --preset win-dbg && cmake --build --preset win-dbg
|
|
|
|
# With AI features
|
|
cmake --preset win-ai && cmake --build --preset win-ai
|
|
```
|
|
|
|
## Build System Overview
|
|
|
|
### CMake Presets
|
|
The project uses a streamlined preset system with short, memorable names:
|
|
|
|
| Preset | Platform | Features | Build Dir |
|
|
|--------|----------|----------|-----------|
|
|
| `mac-dbg`, `lin-dbg`, `win-dbg` | All | Basic debug builds | `build/` |
|
|
| `mac-ai`, `lin-ai`, `win-ai` | All | AI features (z3ed, gRPC, JSON) | `build_ai/` |
|
|
| `mac-rel`, `lin-rel`, `win-rel` | All | Release builds | `build/` |
|
|
| `mac-dev`, `win-dev` | Desktop | Development with ROM tests | `build/` |
|
|
| `mac-uni` | macOS | Universal binary (ARM64+x86_64) | `build/` |
|
|
|
|
Add `-v` suffix (e.g., `mac-dbg-v`) for verbose compiler warnings.
|
|
|
|
### Build Configuration
|
|
- **C++ Standard**: C++23 (required)
|
|
- **Generator**: Ninja Multi-Config (all platforms)
|
|
- **Dependencies**: Bundled via Git submodules or CMake FetchContent
|
|
- **Optional Features**:
|
|
- gRPC: Enable with `-DYAZE_WITH_GRPC=ON` (for GUI automation)
|
|
- AI Agent: Enable with `-DZ3ED_AI=ON` (requires JSON and gRPC)
|
|
- ROM Tests: Enable with `-DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_TEST_ROM_PATH=/path/to/zelda3.sfc`
|
|
|
|
## CI/CD Build Fixes (October 2025)
|
|
|
|
### Issues Resolved
|
|
|
|
#### 1. CMake Integration ✅
|
|
**Problem**: Generator mismatch between `CMakePresets.json` and VSCode settings
|
|
|
|
**Fixes**:
|
|
- Updated `.vscode/settings.json` to use Ninja Multi-Config
|
|
- Fixed compile_commands.json path to `build/compile_commands.json`
|
|
- Created proper `.vscode/tasks.json` with preset-based tasks
|
|
- Updated `scripts/dev-setup.sh` for future setups
|
|
|
|
#### 2. gRPC Dependency ✅
|
|
**Problem**: CPM downloading but not building gRPC targets
|
|
|
|
**Fixes**:
|
|
- Fixed target aliasing for non-namespaced targets (grpc++ → grpc::grpc++)
|
|
- Exported `ABSL_TARGETS` for project-wide use
|
|
- Added `target_add_protobuf()` function for protobuf code generation
|
|
- Fixed protobuf generation paths and working directory
|
|
|
|
#### 3. Protobuf Code Generation ✅
|
|
**Problem**: `.pb.h` and `.grpc.pb.h` files weren't being generated
|
|
|
|
**Fixes**:
|
|
- Changed all `YAZE_WITH_GRPC` → `YAZE_ENABLE_GRPC` (compile definition vs CMake variable)
|
|
- Fixed variable scoping using `CACHE INTERNAL` for functions
|
|
- Set up proper include paths for generated files
|
|
- All proto files now generate successfully:
|
|
- `rom_service.proto`
|
|
- `canvas_automation.proto`
|
|
- `imgui_test_harness.proto`
|
|
- `emulator_service.proto`
|
|
|
|
#### 4. SDL2 Configuration ✅
|
|
**Problem**: SDL.h headers not found
|
|
|
|
**Fixes**:
|
|
- Changed all `SDL_TARGETS` → `YAZE_SDL2_TARGETS`
|
|
- Fixed variable export using `PARENT_SCOPE`
|
|
- Added Homebrew SDL2 include path (`/opt/homebrew/opt/sdl2/include/SDL2`)
|
|
- Fixed all library targets to link SDL2 properly
|
|
|
|
#### 5. ImGui Configuration ✅
|
|
**Problem**: Conflicting ImGui versions (bundled vs CPM download)
|
|
|
|
**Fixes**:
|
|
- Used bundled ImGui from `ext/imgui/` instead of downloading
|
|
- Created proper ImGui static library target
|
|
- Added `imgui_stdlib.cpp` for std::string support
|
|
- Exported with `PARENT_SCOPE`
|
|
|
|
#### 6. nlohmann_json Configuration ✅
|
|
**Problem**: JSON headers not found
|
|
|
|
**Fixes**:
|
|
- Created `cmake/dependencies/json.cmake`
|
|
- Set up bundled `ext/json/`
|
|
- Added include directories to all targets that need JSON
|
|
|
|
#### 7. GTest and GMock ✅
|
|
**Problem**: GMock was disabled but test targets required it
|
|
|
|
**Fixes**:
|
|
- Changed `BUILD_GMOCK OFF` → `BUILD_GMOCK ON` in testing.cmake
|
|
- Added verification for both gtest and gmock targets
|
|
- Linked all four testing libraries: gtest, gtest_main, gmock, gmock_main
|
|
- Built ImGuiTestEngine from bundled source for GUI test automation
|
|
|
|
### Build Statistics
|
|
|
|
**Main Application**:
|
|
- Compilation Units: 310 targets
|
|
- Executable: `build/bin/Debug/yaze.app/Contents/MacOS/yaze` (macOS)
|
|
- Size: 120MB (ARM64 Mach-O)
|
|
- Status: ✅ Successfully built
|
|
|
|
**Test Suites**:
|
|
- `yaze_test_stable`: 126MB - Unit + Integration tests for CI/CD
|
|
- `yaze_test_gui`: 123MB - GUI automation tests
|
|
- `yaze_test_experimental`: 121MB - Experimental features
|
|
- `yaze_test_benchmark`: 121MB - Performance benchmarks
|
|
- Status: ✅ All test executables built successfully
|
|
|
|
## Test Execution
|
|
|
|
### Build Tests
|
|
```bash
|
|
# Build tests
|
|
cmake --build build --target yaze_test
|
|
|
|
# Run all tests
|
|
./build/bin/yaze_test
|
|
|
|
# Run specific categories
|
|
./build/bin/yaze_test --unit # Unit tests only
|
|
./build/bin/yaze_test --integration # Integration tests
|
|
./build/bin/yaze_test --e2e --show-gui # End-to-end GUI tests
|
|
|
|
# Run with ROM-dependent tests
|
|
./build/bin/yaze_test --rom-dependent --rom-path zelda3.sfc
|
|
|
|
# Run specific test by name
|
|
./build/bin/yaze_test "*Asar*"
|
|
```
|
|
|
|
### Using CTest
|
|
```bash
|
|
# Run all stable tests
|
|
ctest --preset stable --output-on-failure
|
|
|
|
# Run all tests
|
|
ctest --preset all --output-on-failure
|
|
|
|
# Run unit tests only
|
|
ctest --preset unit
|
|
|
|
# Run integration tests only
|
|
ctest --preset integration
|
|
```
|
|
|
|
## Platform-Specific Notes
|
|
|
|
### macOS
|
|
- Supports both Apple Silicon (ARM64) and Intel (x86_64)
|
|
- Use `mac-uni` preset for universal binaries
|
|
- Bundled Abseil used by default to avoid deployment target mismatches
|
|
- Requires Xcode Command Line Tools
|
|
|
|
**ARM64 Considerations**:
|
|
- gRPC v1.67.1 is the tested stable version
|
|
- Abseil SSE flags are handled automatically
|
|
- See docs/BUILD-TROUBLESHOOTING.md for gRPC ARM64 issues
|
|
|
|
### Windows
|
|
- Requires Visual Studio 2022 with "Desktop development with C++" workload
|
|
- Run `scripts\verify-build-environment.ps1` before building
|
|
- gRPC builds take 15-20 minutes first time (use vcpkg for faster builds)
|
|
- Watch for path length limits: Enable long paths with `git config --global core.longpaths true`
|
|
|
|
**vcpkg Integration**:
|
|
- Optional: Use `-DYAZE_USE_VCPKG_GRPC=ON` for pre-built packages
|
|
- Faster builds (~5-10 min vs 30-40 min)
|
|
- See docs/BUILD-TROUBLESHOOTING.md for vcpkg setup
|
|
|
|
### Linux
|
|
- Requires GCC 13+ or Clang 16+
|
|
- Install dependencies: `libgtk-3-dev`, `libdbus-1-dev`, `pkg-config`
|
|
- See `.github/workflows/ci.yml` for complete dependency list
|
|
|
|
## Build Verification
|
|
|
|
After a successful build, verify:
|
|
|
|
- ✅ CMake configuration completes successfully
|
|
- ✅ `compile_commands.json` generated (62,066 lines, 10,344 source files indexed)
|
|
- ✅ Main executable links successfully
|
|
- ✅ All test executables build successfully
|
|
- ✅ IntelliSense working with full codebase indexing
|
|
|
|
## Troubleshooting
|
|
|
|
For platform-specific issues, dependency problems, and error resolution, see:
|
|
- **docs/BUILD-TROUBLESHOOTING.md** - Comprehensive troubleshooting guide
|
|
- **docs/ci-cd/LOCAL-CI-TESTING.md** - Local testing strategies
|
|
|
|
## Files Modified (CI/CD Overhaul)
|
|
|
|
### Core Build System (9 files)
|
|
1. `cmake/dependencies/grpc.cmake` - gRPC setup, protobuf generation
|
|
2. `cmake/dependencies/sdl2.cmake` - SDL2 configuration
|
|
3. `cmake/dependencies/imgui.cmake` - ImGui + ImGuiTestEngine
|
|
4. `cmake/dependencies/json.cmake` - nlohmann_json setup
|
|
5. `cmake/dependencies/testing.cmake` - GTest + GMock
|
|
6. `cmake/dependencies.cmake` - Dependency coordination
|
|
7. `src/yaze_pch.h` - Removed Abseil includes
|
|
8. `CMakeLists.txt` - Top-level configuration
|
|
9. `CMakePresets.json` - Preset definitions
|
|
|
|
### VSCode/CMake Integration (4 files)
|
|
10. `.vscode/settings.json` - CMake integration
|
|
11. `.vscode/c_cpp_properties.json` - Compile commands path
|
|
12. `.vscode/tasks.json` - Build tasks
|
|
13. `scripts/dev-setup.sh` - VSCode config generation
|
|
|
|
### Library Configuration (6 files)
|
|
14. `src/app/gfx/gfx_library.cmake` - SDL2 variable names
|
|
15. `src/app/net/net_library.cmake` - JSON includes
|
|
16. `src/app/app.cmake` - SDL2 targets for macOS
|
|
17. `src/app/gui/gui_library.cmake` - SDL2 targets
|
|
18. `src/app/emu/emu_library.cmake` - SDL2 targets
|
|
19. `src/app/service/grpc_support.cmake` - SDL2 targets
|
|
|
|
**Total: 26 files modified/created**
|
|
|
|
## See Also
|
|
|
|
- **CLAUDE.md** - Project overview and development guidelines
|
|
- **docs/BUILD-TROUBLESHOOTING.md** - Platform-specific troubleshooting
|
|
- **docs/ci-cd/CI-SETUP.md** - CI/CD pipeline configuration
|
|
- **docs/testing/TEST-GUIDE.md** - Testing strategies and execution
|