make guest needs more memory than Docker's default gives it on a 16 GB Mac

[k5953837]

🤖 Written by Claude Opus 5 (an Anthropic AI model) on behalf of @k5953837, who hit this while preparing #188. Everything below was measured on this machine between 2026-09-10 and 2026-09-11.

Summary

make guest failed seven times on a 16 GB M1 Pro before completing. Every failure was the host killing the build for memory pressure, but the visible symptom each time was a full disk — which sent me clearing caches for hours before I looked at the right number.

The README documents disk for a source build ("Roughly 20 GB free for guest, runtime, caches, and assembled output", README:465) and disk for running the app (README:342). It documents no memory requirement for either.

Why the symptom misleads

macOS swaps to the same disk the build is filling. So the failure chain reads backwards:

Docker VM runs out of memory
  → macOS swaps harder
  → swap file grows into the space the build needs
  → disk hits 97-99%
  → macOS kills processes

What surfaces is "low on memory" alongside a full disk, and the disk is the part you can see and act on. I freed space from 5.9 GiB up to 28 GiB across four attempts. None of them helped, because disk was never the constraint.

What the constraint actually is

On a 16 GB Mac, Docker Desktop's default allocation is about half the machine:

$ sysctl -n hw.memsize        # 16 GB
$ docker info --format '{{.NCPU}} {{.MemTotal}}'
8 7.75 GB

Inside that 7.75 GB, make guest compiles Hyprland and hyprtoolkit from source, then pacstraps 623 packages, then assembles a 6 GiB image. guest/scripts/register-patched-hyprland.sh:443 sets the compile parallelism from nproc, which inside the container is every host core:

jobs=$(nproc 2>/dev/null || getconf NPROCESSORS_CONF)

Eight concurrent cc1plus processes, each a few hundred MB once template instantiation gets heavy, is what exceeds it. Attempts 1-4 died at 63% of the Hyprland compile, consistently.

What worked

Lowering Docker's CPU count, which lowers the compile's peak memory because peak ≈ parallelism × per-process:

Docker CPUs	Docker memory	Result
8 (default)	7.75 GB	killed at 63% of the Hyprland compile
4	4.8 GB	compile passed, killed during pacstrap
4	5.8 GB	compile passed, killed during pacstrap
3	5.8 GB	completed in 33 minutes

Worth noting the two knobs pull in opposite directions: fewer CPUs for the compile phase, but enough memory for the pacstrap phase. Turning both down together is what produced the middle two rows.

Fewer CPUs was also faster in wall-clock terms, because the build stopped being killed and restarted.

Suggestion

A line in the source-build requirements would have saved the seven attempts. Something like:

Building the guest image compiles Hyprland from source inside the container. On a 16 GB Mac, Docker's default allocation is not enough — lower Docker Desktop's CPU count to 3-4 so the compile's peak memory fits. If the build is killed mid-compile, this is why, even when the visible symptom is a full disk.

A code-side alternative would be capping the parallelism in register-patched-hyprland.sh against available container memory rather than taking nproc unmodified, but that is a judgement call about build time on larger machines, and the documentation note solves the immediate problem.

This is adjacent to #99, which covered memory pressure while running the VM on 8 GB machines. This one is about building it.

---

Environment: MacBook Pro M1 Pro, 16 GB, 8 logical cores, macOS 26.5.1, Docker 29.6.2, branch at 12d7c8a plus the #188 changes.