# Building

> Build, test, and run MAGDA DAW. Use when compiling, running tests, or launching the app. Always use Makefile commands, never raw cmake/ninja.

- Skill: `conceptual-machines/building` (Agent Skill)
- Install (CLI): `npx skillmds@latest add conceptual-machines/building`
- Raw SKILL.md: https://api.skillmd.com/api/skills/conceptual-machines/building/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Conceptual-Machines (https://skillmd.com/u/conceptual-machines)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/conceptual-machines/building

---


# Building MAGDA

Always use Makefile targets. Never use `cmake` or `ninja` directly.

## Build Commands

| Command | Purpose |
|---------|---------|
| `make debug` | Debug build (default) |
| `make release` | Release build |
| `make configure` | Force CMake reconfigure |
| `make clean` | Remove all build artifacts |
| `make rebuild` | Clean + debug build |

## Test Commands

| Command | Purpose |
|---------|---------|
| `make test` | Build and run all tests |
| `make test-build` | Build tests only |
| `make test-verbose` | Run tests with verbose output |
| `make test-list` | List all available tests |
| `make test-window` | Plugin window tests only |
| `make test-shutdown` | Shutdown sequence tests only |
| `make test-threading` | Thread safety tests only |

## Run Commands

| Command | Purpose |
|---------|---------|
| `make run` | Build and launch app (GUI) |
| `make run-console` | Build and run with stdout visible |
| `make run-profile` | Run with performance profiling |

## Code Quality

| Command | Purpose |
|---------|---------|
| `make format` | clang-format all source files |
| `make lint` | clang-tidy on all sources |
| `make lint-changed` | clang-tidy on modified files only |
| `make lint-file FILE=path` | clang-tidy on a specific file |

## Build Directories

- Debug: `cmake-build-debug/`
- Release: `cmake-build-release/`

## Key Notes

- Debug build directory is `cmake-build-debug`, NOT `build/`
- Test binary is at `cmake-build-debug/tests/magda_tests`
- App bundle is at `cmake-build-debug/magda/daw/magda_daw_app_artefacts/Debug/MAGDA.app`
- Pre-commit hooks run clang-format automatically; if commit fails due to formatting, re-stage and commit again

## When to Build

- **Small cosmetic / non-logic changes** (UI sizes, paddings, colors, icon swaps, layout tweaks, comment edits, gitignore, etc.): do NOT build automatically. The user prefers to build these themselves. Just make the change and stop.
- **Logic changes** (new functions, control flow, state management, threading, audio code, refactors, anything that could compile-fail or introduce bugs): always build to verify it compiles and to catch errors early.
- When unsure, ask the user whether they want you to build.