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

refactor: reorganize submodule structure and enhance CMake configuration

Browse Source 
- Moved all third-party libraries (SDL, ImGui, Asar, etc.) from `src/lib/` and `third_party/` to a new `ext/` directory for better organization and clarity in dependency management.
- Updated CMake configuration to reflect the new paths, ensuring all targets and includes point to the `ext/` directory.
- Enhanced CMake presets to support new build options for AI and gRPC features, improving modularity and build flexibility.
- Added new feature flags for agent UI and remote automation, allowing for more granular control over build configurations.
- Updated documentation to reflect changes in the project structure and build options, ensuring clarity for contributors and users.
This commit is contained in:
scawful
2025-11-16 18:27:37 -05:00
parent 8635660d9d
commit a5d98ad83c
39 changed files with 654 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
docs/public/build/build-from-source.md
View File

@@ -13,6 +13,7 @@ yaze uses a modern CMake build system with presets for easy configuration. This
# With automatic fixes
.\scripts\verify-build-environment.ps1 -FixIssues
```
> Tip: After verification, run `.\scripts\setup-vcpkg-windows.ps1` to bootstrap vcpkg, ensure `clang-cl`/Ninja are installed, and cache the `x64-windows` triplet.
### macOS & Linux (Bash)
```bash
@@ -53,6 +54,10 @@ cmake --preset win-dbg
# Build the project
cmake --build --preset win-dbg
# Enable the full AI/gRPC stack
cmake --preset win-ai
cmake --build --preset win-ai
```
### AI-Enabled Build (All Platforms)
@@ -67,10 +72,31 @@ cmake --preset win-ai
cmake --build --preset win-ai
```
## Feature Toggles & Windows Profiles
### Windows Presets
| Preset | Purpose |
| --- | --- |
| `win-dbg`, `win-rel`, `ci-windows` | Core builds without agent UI, gRPC, or AI runtimes. Fastest option for MSVC/clang-cl. |
| `win-ai`, `win-vs-ai` | Full agent stack for local development (UI panels + remote automation + AI runtime). |
| `ci-windows-ai` | Nightly/weekly CI preset that exercises the entire automation stack on Windows. |
### Agent Feature Flags
| Option | Default | Effect |
| --- | --- | --- |
| `YAZE_BUILD_AGENT_UI` | `ON` when `YAZE_BUILD_GUI=ON` | Builds the ImGui widgets used by the chat/agent panels. |
| `YAZE_ENABLE_REMOTE_AUTOMATION` | `ON` for `*-ai` presets | Adds gRPC/protobuf services plus GUI automation clients. |
| `YAZE_ENABLE_AI_RUNTIME` | `ON` for `*-ai` presets | Enables Gemini/Ollama transports, proposal planning, and advanced routing logic. |
| `YAZE_ENABLE_AGENT_CLI` | `ON` when `YAZE_BUILD_CLI=ON` | Compiles the conversational agent stack consumed by `z3ed`. |
Combine these switches to match your workflow: keep everything `OFF` for lightweight GUI hacking or turn them `ON` for automation-heavy work with sketchybar/yabai/skhd, tmux, or remote runners.
## 3. Dependencies
- **Required**: CMake 3.16+, C++23 Compiler (GCC 13+, Clang 16+, MSVC 2019+), Git.
- **Bundled**: All other dependencies (SDL2, ImGui, Abseil, Asar, GoogleTest, etc.) are included as Git submodules or managed by CMake's `FetchContent`. No external package manager is required for a basic build.
- **Bundled**: All other dependencies (SDL2, ImGui, Asar, nlohmann/json, cpp-httplib, GoogleTest, etc.) live under the `ext/` directory or are managed by CMake's `FetchContent`. No external package manager is required for a basic build.
- **Optional**:
- **gRPC**: For GUI test automation. Can be enabled with `-DYAZE_WITH_GRPC=ON`.
- **vcpkg (Windows)**: Can be used for faster gRPC builds on Windows (optional).
@@ -95,7 +121,8 @@ sudo apt-get install -y build-essential cmake ninja-build pkg-config \
### Windows
- **Visual Studio 2022** is required, with the "Desktop development with C++" workload.
- The `verify-build-environment.ps1` script will help identify any missing components.
- The updated `verify-build-environment.ps1` script checks clang-cl, Ninja, vcpkg caches, and ROM assets.
- Run `.\scripts\setup-vcpkg-windows.ps1` once per machine to bootstrap vcpkg and prefetch SDL2/yaml-cpp.
- For building with gRPC, see the "Windows Build Optimization" section below.
## 5. Testing
@@ -171,6 +198,7 @@ open build/yaze.xcodeproj
- **vcpkg**: Only fast packages (SDL2, yaml-cpp) - 2 minutes
- **gRPC**: Built via FetchContent (v1.75.1) - cached after first build
- **Caching**: Aggressive multi-tier caching (vcpkg + FetchContent + sccache)
- **Agent matrix**: A dedicated `ci-windows-ai` job runs outside pull requests to exercise the full gRPC + AI runtime stack.
- **Expected time**:
- First build: ~10-15 minutes
- Cached build: ~3-5 minutes
@@ -188,9 +216,8 @@ open build/yaze.xcodeproj
For desktop development, you can use vcpkg for faster gRPC builds:
```powershell
# Install vcpkg
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg && .\bootstrap-vcpkg.bat
# Bootstrap vcpkg and prefetch packages
.\scripts\setup-vcpkg-windows.ps1
# Configure with vcpkg
cmake -B build -DYAZE_USE_VCPKG_GRPC=ON -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake

7
docs/public/developer/dependency-architecture.md
View File

@@ -18,6 +18,10 @@ can treat it as a quick reference while editing.
| `YAZE_ENABLE_GRPC` | `OFF` | Pulls in gRPC/protobuf for automation and remote control features. |
| `YAZE_MINIMAL_BUILD` | `OFF` | Skips optional editors/assets. Useful for CI smoke builds. |
| `YAZE_BUILD_LIB` | `OFF` | Produces the `yaze_core` INTERFACE target used by external tooling. |
| `YAZE_BUILD_AGENT_UI` | `ON` when `YAZE_BUILD_GUI` is `ON` | Compiles ImGui chat widgets. Disable for lighter GUI builds. |
| `YAZE_ENABLE_REMOTE_AUTOMATION` | `OFF` in `win-*` core presets | Builds gRPC servers/clients plus proto generation. |
| `YAZE_ENABLE_AI_RUNTIME` | `OFF` in `win-*` core presets | Enables Gemini/Ollama transports, proposal planning, and advanced routing code. |
| `YAZE_ENABLE_AGENT_CLI` | `ON` when `YAZE_BUILD_CLI` is `ON` | Compiles the conversational agent stack used by `z3ed`. |
Use the canned presets from `CMakePresets.json` so these options stay consistent across
platforms: `mac-dbg`, `mac-ai`, `lin-dbg`, `win-dbg`, etc. The `*-ai` presets enable both
@@ -58,12 +62,13 @@ alone. Touching editor UI code does **not** require rebuilding `yaze_emulator`.
### 4. Tooling & Export Targets
- **`yaze_agent`** (`src/cli/agent`): shared logic behind the CLI and AI workflows. Built whenever
`YAZE_BUILD_Z3ED` is enabled.
`YAZE_ENABLE_AGENT_CLI` is enabled (automatically true when `YAZE_BUILD_Z3ED=ON`). When both the CLI and the agent UI are disabled, CMake now emits a lightweight stub target so GUI-only builds don't drag in unnecessary dependencies.
- **`z3ed` binary** (`src/cli/z3ed.cmake`): links `yaze_agent`, `yaze_zelda3`, `yaze_gfx`, and
Abseil/FTXUI.
- **`yaze_core_lib`** (`src/core`): static library that exposes project management helpers and the
Asar integration. When `YAZE_BUILD_LIB=ON` it can be consumed by external tools.
- **`yaze_test_support`** (`src/app/test`): harness for the in-editor dashboard and `yaze_test`.
- **`yaze_grpc_support`**: server-only aggregation of gRPC/protobuf code, gated by `YAZE_ENABLE_REMOTE_AUTOMATION`. CLI clients (`cli/service/gui/**`, `cli/service/planning/**`) now live solely in `yaze_agent` so GUI builds can opt out entirely.
### 5. Final Binaries
- **`yaze`**: GUI editor. Links every layer plus `yaze_test_support` when tests are enabled.