BuildSystem Implementation Plan
Date: May 16, 2026
** Status:** In Progress
**Milestone:**M4 — Advanced Tools & Polish
Issue: #123
Reference Design: docs/plans/2026-05-16-buildsystem-design.md
Overview#
This plan breaks down the BuildSystem Integration into 8 bite-sized implementation tasks, each designed to compile and integrate cleanly. Each task includes acceptance criteria and verification steps.
Task Breakdown#
Task 1: Create BuildSystem Core Header (5 min)#
File: doppio-archived/src/doppio/editor/BuildSystem.hpp
What to do:
- Define namespace
Caffeine::Editor - Declare enums:
BuildPlatform,BuildStatus - Declare structs:
BuildSettings,BuildProgress - Declare
class BuildSystemwith public static methods:static void ExecuteBuild(const BuildSettings& settings);static void CancelBuild();static BuildProgress GetProgress();static bool IsBuilding();
- Private methods (forward declarations only):
ValidateSettings(),PrepareOutput(),CompileScripts(),CookAssets(),LinkExecutable(),GenerateProject(),RunGameAndWait()
Key types to include:
- BuildPlatform:
Windows_x64 = 0, Linux_x64 = 1 - BuildStatus:
Idle, Validating, PreparingOutput, CompilingScripts, CookingAssets, LinkingExecutable, GeneratingProject, Success, Failed, Cancelled - BuildSettings with fields:
projectName,outputDir,platform,isDebug,incrementalBuild,runAfterBuild,scenesToInclude,executableName,icon,version - BuildProgress with fields:
progress,status,shouldCancel,currentTask
Acceptance Criteria:
- Header compiles without errors
- All enums and structs defined exactly per design doc
- No implementation in header (only declarations)
Verification:
cd build && cmake .. && make BuildSystem.hpp.o 2>&1 | grep -i error
# Should have 0 errors
Task 2: Create BuildSystem Core Implementation (10 min)#
File: doppio-archived/src/doppio/editor/BuildSystem.cpp
What to do:
- Implement all 7 pipeline stages as private static methods
- Use
progressatomic variable to update UI thread-safely - Each stage:
- Check
shouldCancelflag at start - Log "Starting [stage]"
- Update
progressandcurrentTask - Perform stage logic (stub for now, return true)
- Log "[stage] complete"
- On failure: call
CleanupOnFailure()and return false
- Check
- Implement
ExecuteBuild()to call stages sequentially - Implement
GetProgress()to return current progress safely - Implement
IsBuilding()to return status != Idle - Implement
CancelBuild()to setshouldCancel = true - Implement
CleanupOnFailure(outputDir)to remove entire directory
Key implementation details:
- Use
std::filesystem::remove_all()for cleanup - Progress increments: Validate(0%), Prepare(5%), Scripts(20%), Assets(65 %), Link(85 %), Generate(95%), Success(100 %)
- Log to
ConsoleWindowusing existing log system - On any failure, cleanup and set status = Failed
Acceptance Criteria:
- Compiles without type errors
- All pipeline stages callable
- Progress updates atomically
- Cleanup removes output directory on failure
- Cancellation works between stages
Verification:
cd build && cmake .. && make
# Should compile with 0 errors
lsp_diagnostics /home/pedro/repo/caffeine/src/editor/BuildSystem.cpp
# Should show 0 errors
Task 3: Create BuildDialog Header (5 min)#
File: doppio-archived/src/doppio/editor/BuildDialog.hpp
What to do:
- Declare
class BuildDialog : public EditorPanel(inherit from existing panel class) - Declare member variables:
BuildSettings m_settings;BuildProgress& m_progress;(reference to BuildSystem progress)std::string m_outputPath;std::vector<std::string> m_scenesToInclude;bool m_showBuildLog;
- Declare public methods:
void render()- Main UI renderBuildDialog();constructor
- Declare private helper methods (stubs):
renderConfigSection()- Platform, paths, settingsrenderAdvancedSection()- Icon, version, executable namerenderProgressSection()- Progress bar, status, taskrenderLogSection()- Build log displayonBuildClicked()- Handle Build buttononCancelClicked()- Handle Cancel button
Acceptance Criteria:
- Header compiles
- Inherits from EditorPanel correctly
- All methods declared with correct signatures
Verification:
cd build && cmake .. && make
# Should compile
Task 4: Create BuildDialog Implementation Part 1 (10 min)#
File: doppio-archived/src/doppio/editor/BuildDialog.cpp — Builder and render()
What to do:
- Implement
BuildDialog()constructor:- Initialize settings with defaults (project name, output dir = "./build", platform = Windows_x64)
- Initialize
m_showBuildLog = true
- Implement
render()method as main ImGui window:- Create ImGui window titled "Build & Run"
- Call
renderConfigSection(),renderAdvancedSection(),renderProgressSection(),renderLogSection()in order - Render "Build & Run" and "Cancel" buttons at bottom
- Handle button clicks via
onBuildClicked()andonCancelClicked()
- Implement
onBuildClicked():- Validate settings (output path not empty, project name not empty)
- Call
BuildSystem::ExecuteBuild(m_settings)to start build - Log "Build started" to console
- Implement
onCancelClicked():- Call
BuildSystem::CancelBuild() - Log "Build cancelled" to console
- Call
Key implementation details:
- Use ImGui::Begin/End for window
- Use ImGui::Button for buttons with click detection
- Log to existing ConsoleWindow
Acceptance Criteria:
- ImGui window renders
- Buttons are clickable and trigger callbacks
- No crashes on button click
Verification:
cd build && cmake .. && make
lsp_diagnostics /home/pedro/repo/caffeine/src/editor/BuildDialog.cpp
# Should compile, 0 errors
Task 5: Create BuildDialog Implementation Part 2 (8 min)#
File: doppio-archived/src/doppio/editor/BuildDialog.cpp — UI Sections
What to do:
- Implement
renderConfigSection():- ImGui::Separator()
- ImGui::Text("Configuration")
- ImGui::InputText("Project Name", &m_settings.projectName)
- ImGui::InputText("Output Directory", &m_outputPath) with folder icon
- ImGui::Combo("Platform", platform selector: Windows_x64 / Linux_x64)
- ImGui::Checkbox("Debug Build", &m_settings.isDebug)
- ImGui::Checkbox("Incremental Build", &m_settings.incrementalBuild)
- ImGui::Checkbox("Run After Build", &m_settings.runAfterBuild)
- Implement
renderAdvancedSection():- ImGui::Separator()
- ImGui::Text("Advanced")
- ImGui::InputText("Executable Name", &m_settings.executableName)
- ImGui::InputText("Icon Path", &m_settings.icon)
- ImGui::InputText("Version", &m_settings.version)
- Implement
renderProgressSection():- Only show if
BuildSystem::IsBuilding() - ImGui::ProgressBar(m_progress.progress)
- ImGui::Text("Status: %s", StatusToString(m progress.status))
- ImGui::Text("Task: %s", m progress.currentTask.c str())
- Only show if
- Implement
renderLogSection():- ImGui::BeginChild("Build Log")
- Display build log from ConsoleWindow
- ImGui::EndChild()
Helper function:
- Implement
StatusToString(BuildStatus)to convert enum to string
Acceptance Criteria:
- All UI sections render without crashes
- Input fields are editable
- Progress bar appears during builds
- Status text updates
Verification:
cd build && cmake .. && make
# No compile errors expected
Task 6: Create AssetCooker Header & Stubs (8 min)#
File: doppio-archived/src/doppio/editor/AssetCooker.hpp + doppio-archived/src/doppio/editor/AssetCooker.cpp
Header What to do:
- Declare
class AssetCooker - Public static methods:
static bool CookTextures(const std::string& assetsDir, const std::string& outputDir, BuildProgress& progress);static bool CookShaders(const std::string& assetsDir, const std::string& outputDir, BuildProgress& progress);static bool LoadBuildCache(const std::string& cacheFile);static bool SaveBuildCache(const std::string& cacheFile);
- Private:
- Helper for cache checking:
shouldCookAsset(const std::string& assetPath)
- Helper for cache checking:
Implementation What to do:
- Implement all methods as stubs that:
- Return
true(success) - Update
progress.progressincrementally - Log placeholder messages like "Cooking textures... [N assets]"
- Skip actual texture/shader compilation for now
- Return
Cache structure (stub for now):
- Cache file format: JSON at
outputDir/.build_cache/build_cache.json - Load/save functions stub (return true, don't actually load/save yet)
Acceptance Criteria:
- Compiles without errors
- Methods callable from BuildSystem
- Returns bool success/failure
Verification:
cd build && cmake .. && make
lsp_diagnostics /home/pedro/repo/caffeine/src/editor/AssetCooker.cpp
# Should compile, 0 errors
Task 7: Wire BuildDialog into Editor (5 min)#
File: apps/doppio/main.cpp (the editor app)
What to do:
- Find where
ConsoleWindow,InspectorPanel, etc. are created in the editor loop - Add instantiation of
BuildDialog:
static BuildDialog buildDialog;
- Call
buildDialog.render()in the main editor ImGui render loop (alongside other panel renders) - Ensure BuildDialog renders after ConsoleWindow so logs are visible
Acceptance Criteria:
- Editor compiles
- BuildDialog window appears in editor UI
- No crashes on startup
Verification:
cd build && cmake .. && make doppio
./bin/doppio
# Editor launches, "Build & Run" window visible (can resize/close like other panels)
Task 8: Integration Test & Full Build (10 min)#
File: Integration verification (no new files)
What to do:
- Launch editor:
./bin/doppio - Locate "Build & Run" window
- Set output directory to
./build/test_game - Click "Build & Run"
- Verify:
- Progress bar appears
- Status changes: Validating → Preparing → Compiling → Cooking → Linking → Generating → Success
- Console logs all stages
- Dialog shows "Build complete" message
./build/test_game/directory exists with placeholder files
- Test cancellation:
- Click "Build & Run" again
- Click "Cancel" mid-build
- Verify
./build/test_game/is cleaned up (removed) - Verify status shows "Cancelled"
Acceptance Criteria:
- Full build pipeline executes without crashes
- Progress updates visibly in UI
- Cancellation works and cleans up
- Log shows all 7 stages completed
Verification:
./bin/doppio
# Manual UI testing - no automated test yet
# Then run:
cd build && make test # Ensure no regression in other tests
Sequential Execution Order#
- Task 1 → BuildSystem header (5 min)
- Task 2 → BuildSystem implementation (10 min)
- Task 3 → BuildDialog header (5 min)
- Task 4 → BuildDialog constructor + render (10 min)
- Task 5 → BuildDialog UI sections (8 min)
- Task 6 → AssetCooker studs (8 min)
- Task 7 → Wire into main.cpp editor (5 min)
- Task 8 → Integration test (10 min)
**Total estimated time: ** ~60 minutes
Commit Strategy#
After each task, commit atomically:
# After Task 1
git add src/editor/BuildSystem.hpp
git commit -m "feat: add BuildSystem header with enums and struct definitions"
# After Task 2
git add src/editor/BuildSystem.cpp
git commit -m "feat: implement BuildSystem 7-stage pipeline with progress tracking"
# After Tasks 3-5
git add src/editor/BuildDialog.hpp src/editor/BuildDialog.cpp
git commit -m "feat: implement BuildDialog ImGui panel with configuration and progress sections"
# After Task 6
git add src/editor/AssetCooker.hpp src/editor/AssetCooker.cpp
git commit -m "feat: add AssetCooker stub with texture and shader cooking interfaces"
# After Task 7
git add apps/doppio/main.cpp
git commit -m "feat: wire BuildDialog into editor UI rendering loop"
# After Task 8
git add -A # If any changes
git commit -m "test: verify BuildSystem integration and full build pipeline execution"
Verification Checklist#
Before marking each task complete:
- [ ] File compiles:
cmake .. && make - [ ] No LSP diagnostics:
lsp_diagnostics /path/to/file - [ ] Methods are callable from dependent code
- [ ] No breaking changes to existing codebase
Next Session (After This Plan)#
- Asset cooking implementations: Actual texture/shader compilation using TextureCompiler and ShaderCompiler APIs
- Build cache implementation: Load/save JSON, mtime/hash checking
- Game execution: Platform-specific process launching (CreateProcess for Windows, fork/execv for Linux)
- Integration with ProjectManager: Load scenes and project settings from
project.caffeine
Plan created: May 16, 2026 Plan approved by: Implementation phase Expected completion: Same day (~1 hour total)