Refactor monolithic Makefile into modular domain-focused structure

[pbalduino]

Dependencies

This issue depends on #23 (Refactor code structure).

The Makefile refactoring should be done after the code structure is finalized to avoid having to update the build rules multiple times as files are moved and reorganized during the #23 refactoring phases.

Status: Blocked until #23 phases 7-10 are complete.

---

Overview

Break the monolithic Makefile into a thin dispatcher plus domain-focused includes to improve maintainability and navigation without touching behavior.

Proposed Structure

The root Makefile will wire .PHONY targets to namespaces and include mk/*.mk files, exposing high-level targets first for newcomers.

Module Breakdown

• mk/core/config.mk: Environment/toolchain detection, shared flags, helper macros
• mk/core/docker.mk: Docker helpers and host/Docker branching
• mk/sdk/sdk.mk: SDK staging rules, object patterns, stamps
• mk/kernel/build.mk: Kernel object discovery, build flags, Limine/image creation
• mk/userland/apps.mk: User program targets and installer loop
• mk/runtime/run.mk: Launch targets (run, console, shell, QEMU config)
• mk/testing/host.mk: Host-test harness
• mk/assets/doom.mk: Optional assets download and bundling
• mk/external/binutils.mk: Toolchain rebuild flow
• mk/helpers/macros.mk (optional): Reusable recipes for Docker-vs-host handling

Approach

Extract one section at a time (starting with SDK as suggested), update Makefile to include it, and verify with make <target> before proceeding.

Sub-tasks

Foundational (no dependencies)

• [ ] #353 Extract environment and toolchain configuration to mk/core/config.mk
• [ ] #354 Extract Docker helpers and host/Docker branching to mk/core/docker.mk
• [ ] #359 Extract host-test harness to mk/testing/host.mk (independent)
• [ ] #360 Extract assets download and bundling to mk/assets/doom.mk (independent)

Build Modules (depend on core config + docker)

• [ ] #355 Extract SDK staging rules to mk/sdk/sdk.mk (recommended first)
• [ ] #356 Extract kernel build logic to mk/kernel/build.mk
• [ ] #357 Extract userland application build to mk/userland/apps.mk
• [ ] #361 Extract external toolchain build to mk/external/binutils.mk

Runtime (depends on kernel)

• [ ] #358 Extract runtime and launch targets to mk/runtime/run.mk

Optional (depends on all others)

• [ ] #362 Create optional mk/helpers/macros.mk for reusable recipes

Success Criteria

• [ ] All functionality preserved (no behavioral changes)
• [ ] Each domain has a dedicated, focused file
• [ ] Root Makefile is thin and readable
• [ ] Build/test targets continue to work
• [ ] Future changes are easier to locate and maintain

Implementation Order

1. Phase 1 - Foundations: #353, #354 (core modules needed by others)
2. Phase 2 - First Extraction: #355 (SDK - validate approach)
3. Phase 3 - Build Modules: #356, #357, #361 (parallel work possible)
4. Phase 4 - Independent: #359, #360 (parallel work possible)
5. Phase 5 - Runtime: #358 (after kernel)
6. Phase 6 - Cleanup: #362 (optional, after patterns emerge)

Related Issues

• Blocked by: #23 (Refactor code structure - phases 7-10 must complete first)
• Related:
  • #414 - Migrate NASM to GAS (related build system cleanup)