docs/reference/config.btft

[table class="topnav"]
[tr]
[td class="logotab"]mp[e]
[td][see name="index"]index[e][e]
[td][see name="guide/index"]guide[e][e]
[td][see name="reference/index"]reference[e][e]
[e]
[e]
 
[h1]config[e]
 
this page is the narrative tour of how mp's config system fits together. [see name="reference/mp-conf-example"]mp.conf.example[e] (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.
[br]
2. /etc/mp.conf, the system config.
[br]
3. ~/.mp.conf, layered on top.
[br]
4. --config=<file> overlays, on the command line.
[br]
5. WD/pkgconf.conf, the mp-managed overlay: everything mp hold, mp mask, mp unmask, mp use +flag/-flag, and mp conflicts +token/-token persist. never hand-edited -- regenerated wholesale on every sugar-command run.
[br]
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:
 
[code]
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
[e]
 
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 [see name="reference/patches-conf-example"]patches.conf.example[e]'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. HOOKS_<phase>=<file> <file> ... (global, or per-package -- same "<name>:" section grammar as anything else here) is a further, OPTIONAL manual override on top of whatever hooks.conf's own IF_USE already computed: a bare list is the complete, explicit set of filenames to run regardless of IF_USE; a +file/-file delta is layered atop the IF_USE-computed set instead, so "HOOKS_post_install=-20-notify" disables one hook file by name without deleting it or touching hooks.conf, and "+30-extra-check" forces one back on despite its own IF_USE condition. no dedicated command persists this -- hand-edit mp.conf.
 
blockers: pkg_conflicts (a port's own field, "pkg" or "!!pkg" hard-blocking, "!pkg" soft-warning-only) is what a port author declares. CONFLICTS=<token> <token> ... in mp.conf, per-package only (no global form -- a conflict is a relationship between two specific packages, not a system-wide toggle), is the user-facing override on top of it: same +/- delta convention as USE=/HOOKS_<phase>= -- a bare list replaces the port's declared conflicts outright, a +token/-token delta is applied atop them instead (the token after +/- carries pkg_conflicts' own '!'/'!!' markers verbatim, so lifting a declared soft entry needs the same leading '!' the declaration used: "-!somepkg", not "-somepkg"). "mp conflicts pkgname" lists what's currently effective; "mp conflicts pkgname +token/-token" toggles and persists it, mirroring "mp use" exactly, empty-set round-trip included.
 
these three (USE=, HOOKS_<phase>=, CONFLICTS=) all share one convention: a plain bare-name list is always the complete, literal value (exactly this, nothing else), and a +name/-name token is always a delta layered on top of whatever the port/system would otherwise compute by default -- never both mixed in the same value. a dedicated command (mp use, mp conflicts) exists for two of the three purely as a convenience wrapper that computes and persists this same result; it's never the only way to express it, since the config format itself is always equally capable, hand-edited directly.
 
/etc/mpx.env, a different kind of file entirely from everything above: not parsed by mpx at all, just sourced as-is (arbitrary shell, not a KEY="value" grammar) into the wrapper shell that runs every single add.sh/del.sh, right before it execs the phase script. mpx.conf's own keys (TARGET_*, JOBS, SANDBOX, ...) cover the specific things mpx itself understands and exports -- mpx.env is the escape hatch for anything else a site needs every build to see: an extra env var no mpx.conf key covers, a PATH prepend, whatever. no per-package sections (it fires identically for every port, every phase), and it runs under the same "set -e" as any phase script, so a failing command in it aborts that phase loudly rather than silently skipping the sourcing. absent entirely -- the default, and the common case -- is a silent no-op. see [see name="reference/mpx-env-example"]mpx.env.example[e] (repo root) for the exact format and a couple of worked examples.