builder
Build applications that require compilation. Use this skill before testing or running apps that need a build phase (e.g., C++ desktop app).
When & Why to Use This Skill
The Builder skill automates the compilation and build process for software applications, specifically those requiring a dedicated build phase like C++ desktop apps. It streamlines the development workflow by managing dependencies, environment configuration, and error handling, ensuring that the latest source code is correctly compiled before testing or deployment.
Use Cases
- Automating the compilation of C++ desktop applications after code changes to ensure the executable is up-to-date.
- Setting up and configuring build environments for new projects, including prerequisite checks and dependency synchronization.
- Resolving common build-time issues such as file locks, missing tools, or linker errors through automated clean builds and process management.
- Integrating mandatory build steps into testing pipelines to prevent running tests against stale or uncompiled code.
| name | builder |
|---|---|
| description | Build applications that require compilation. Use this skill before testing or running apps that need a build phase (e.g., C++ desktop app). |
Builder
Compile applications before testing or deployment.
Reference Documentation
| Reference | When to Read |
|---|---|
references/desktop-build.md |
Building desktop C++ app |
When to Build
Build is required when:
- Source code has changed
- Dependencies have been updated
- First time setting up the project
- After pulling new changes from git
Workflow
STEP 1: IDENTIFY APP
Determine which app needs building:
| App | Build Required | Reference |
|---|---|---|
desktop/ |
Yes (C++) | references/desktop-build.md |
backend/ |
No (Python) | Just uv sync for deps |
STEP 2: CHECK PREREQUISITES
Before building, verify:
- Required tools are installed
- Environment is configured
- Dependencies are available
See app-specific reference for prerequisites.
STEP 3: CONFIGURE (if needed)
Run configuration step on:
- First build
- After changing build configuration
- After updating dependencies
STEP 4: BUILD
Execute build command. Handle common issues:
- Kill running processes (file locks)
- Clean build if needed
- Check for errors
STEP 5: VERIFY
Confirm build succeeded:
- Check for executable/output
- Run basic health check
- Note any warnings
Quick Reference
Desktop App
cd D:\projects\buddy\desktop
# First time or after config changes
.\configure.ps1
# Build (kills running process automatically)
.\build.ps1
# Verify
.\build\Debug\BuddyDesktop.exe --version
Backend (no build needed)
cd backend
uv sync # Install/update dependencies
uv run uvicorn backend.main:app # Run directly
Build Errors
Common Issues
| Error | Cause | Solution |
|---|---|---|
| File in use | App still running | Kill process, retry |
| Missing tool | Not installed | Install prerequisite |
| Linker errors | ABI mismatch | Clean build, reconfigure |
| Dependency fail | Package issue | Check vcpkg/npm logs |
When to Clean Build
# Desktop - remove build directory
Remove-Item -Recurse -Force desktop/build
.\configure.ps1
.\build.ps1
Clean build when:
- Switching branches with major changes
- Updating build configuration
- Unexplained linker errors
- Dependency version conflicts
Integration with Testing
Always build before running tests:
# Desktop workflow
.\desktop\build.ps1 # Build first
.\desktop\build\Debug\BuddyDesktop.exe --debug # Run in debug mode
python desktop/tests/T00022/T00022-01.py # Then test
Critical Rules
- Build before test - Always compile latest code
- Check for errors - Don't ignore warnings
- Kill running processes - Prevents file lock issues
- Clean when stuck - Fresh build solves many issues
- Document build issues - In
5-progress-and-issues.md