Proposal: Makefile for unified build orchestration

[dougborg]

Summary

This is a proposal / proof-of-concept — not intended for immediate merge. It demonstrates what a Make-driven build system would look like for this project.

• Add Makefile with dependency-tracked targets and stamp files (.stamps/) so asset generation (icons, splash) always runs before builds, and skips when fresh
• Simplify CI workflows — each job collapses flutter pub get + dart run ... + flutter build into a single make call
• Remove gen_icons_splashes.sh — superseded by make generate-assets
• Keep do_builds.sh and app2ipa.sh — they handle release signing and credential logic that doesn't belong in Make

What changes in CI

PR workflow (pr.yml):

• Validate job: make ci (runs analyze + test)
• New: build-debug-apk and build-ios-simulator jobs with artifact upload — these are intentional additions (PR binary builds are needed for an upcoming change)

Release workflow (workflow.yml):

• Each build job replaces 3-4 flutter/dart steps with make test + make release-*
• CI-specific steps (keystore decode, certificate install, export options) stay in the workflow unchanged

Dependency graph

pubspec.yaml + pubspec.lock
       ↓
.stamps/pub-get               (flutter pub get)
       ↓
.stamps/generate-assets       (icons + splash)
    ↓         ↓         ↓
APK_DEBUG  IOS_SIM   APK_RELEASE ...

Key design decisions

• File targets with stamp files: Make compares timestamps to skip fresh work. .stamps/ tracks steps that produce many scattered files
• Dep checks: check-deps, check-android-deps, check-ios-deps verify tools are installed once per clean checkout
• FLUTTER_BUILD_ARGS: CI passes --dart-define flags for secrets without hardcoding them in the Makefile
• .DELETE_ON_ERROR: Cleans up partial outputs if a recipe fails

Open question — is Make the right tool?

Option	Pros	Cons
Make (this PR)	Ubiquitous, zero install, file-timestamp tracking built in, pre-installed on CI runners	Tab-sensitivity trips people up, no built-in cross-platform story
Gradle	Already a dependency (Android builds need Java/Gradle), rich task model with up-to-date checks, single tool for Android + orchestration	Heavier than needed for wrapping CLI commands, iOS contributors wouldn't otherwise need Java, Gradle boot time (~3-5s) on every invocation
Shell script (build.sh)	Simplest to understand, no new concepts	No dependency tracking (always re-runs everything), hard to compose individual targets

Test plan

• make runs analyze + test
• make all builds debug APK + iOS simulator
• make generate-assets is a no-op when stamps are fresh
• make clean removes build outputs, stamps, and generated assets
• make help prints all targets
• CI workflow passes with make targets

🤖 Generated with Claude Code