config

this page is the narrative tour of how mp's config system fits together. mp.conf.example (repo root, alongside this docs/ directory) is the exhaustive, copyable, key-by-key reference -- this page explains the shape, that one explains every key.

layering, lowest precedence to highest, each one strictly overriding the last:

1. PROFILE=<name>, a shippable base config (searched across every configured repo, like a port lookup) -- despite being read early, it only fills in keys nothing above it already set, so a local override always wins over it. a profile can itself set PROFILE=<other> to chain to a further base, one hop lower each time.
2. /etc/mp.conf, the system config.
3. ~/.mp.conf, layered on top.
4. --config=<file> overlays, on the command line.
5. WD/pkgconf.conf, the mp-managed overlay: everything mp hold, mp mask, mp unmask, and mp use +flag/-flag persist. never hand-edited -- regenerated wholesale on every sugar-command run.
6. a --sysroot=<name> invocation's own overlay, if one applies -- the single highest-precedence layer of all, since it's a deliberate, specific request for that one invocation.

any of 1-4 can itself pull in further files via OVERLAYS=<file> <file> ..., chained, with cycle detection and diamond-safe (two files both pulling in one shared file is a legitimate shape, not an error).

per-package sections. a "<name>:" header inside any of the above scopes the indented keys under it to just that one port, until the next "<name>:" header or the next unindented key=value line:

TARGET_libc=meta/null    # global
examplepkg:
	TARGET_libc=musl     # examplepkg alone resolves %libc to musl
	CC=clang              # exported as env to examplepkg's phases
JOBS=1                    # unindented -- back to global scope

a section is looked up under a port's full canon first (curl:ssl, say), falling back to its bare name (curl) -- the fallback matters because a pkg_slot_use-composed canon doesn't exist yet at the moment you'd write the section, so the bare name is the only thing you could plausibly have written. write under the bare name to apply to every slot of that name alike; write under the exact "name:slot" canon for an override that should fire for just one specific coexisting slot.

patches.conf and hooks.conf, the two closely related conditional-file grammars: both use the same "<name>:"-sectioned format as mp.conf itself, and both support AFTER=<item> <item> (a topologically-sorted ordering prerequisite among whatever's actually running, cycle-checked) and IF_USE=<flag> (gates on the current package's use-flag state, or the global USE= for a canon-less hook like pre_sync). patches.conf adds IF_DEP= and IF_VER= (a patch's own condition can check the port's actual resolved dependencies and version) and DEPS+=<dep> <dep> (a patch's own condition pulling in an extra dependency exactly when that patch applies). see patches.conf.example's closing example for a full "one use flag drives a patch, a dependency, and a hook together" walkthrough tying all of this together at once.

hooks specifically: pre_ and post_ pairs around every phase (fetch, patch, build, check, install), plus whole-operation boundaries (install, remove, sync) and a best-effort on_fail, fired from a plain hook_<phase>= config key, every executable file in HOOKS_DIR/<phase>/ (filtered/ordered by hooks.conf if present), or both together. a phase script can fire its own named custom event too, via $MP_HOOK, running through the exact same machinery as any built-in phase.