docs/reference/mpx-env-example.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]mpx.env.example[e]
 
[quote class="note"]
generated from mpx.env.example -- do not edit this page directly, edit that file and regenerate ("mk . d" / "sh mk/d.sh") instead. see [see name="reference/config"]reference/config[e] for the narrative tour this page doesn't replace.
[e]
 
optional arbitrary shell, sourced from /etc/mpx.env into every single add.sh/del.sh invocation, right before it runs.
 
unlike mpx.conf (a fixed KEY="value" grammar, parsed by mpx itself, with a specific known set of keys), this file is not parsed at all -- it's sourced as real shell into the same wrapper shell that then execs the phase script, so it can do anything a shell script can: export an arbitrary env var no mpx.conf key covers, run a command, set up something the whole build tree relies on, whatever a specific site needs that isn't one of mpx.conf's own TARGET_*/JOBS/SANDBOX keys.
 
absent entirely (the common case, and the default -- this file does not exist until you copy this example to /etc/mpx.env yourself) is a silent no-op: nothing about a build changes. present, it always runs, for every port, every phase -- there is no per-package section built into ITS OWN grammar the way mpx.conf has (this file has no grammar at all, just plain shell), but see this file's own mpx.env.d/ convention further down for a way to get the same effect anyway.
 
it runs under "set -e" (same as every add.sh/del.sh): a failing command in here aborts the phase loudly, the same "fail loud, not silent" rule as everywhere else in mpx -- so keep it simple, and don't put anything in here you wouldn't want to block every single build if it broke.
 
example: export a var every add.sh/del.sh script can rely on being set, without adding a new mpx.conf key just for it:
 
[code]
export MY_SITE_MIRROR="https://mirror.example.internal"
[e]
 
example: make sure a tool every build needs is on PATH, without relying on whatever PATH mpx happened to inherit from whoever invoked it:
 
[code]
PATH="/opt/local-toolchain/bin:$PATH"
export PATH
[e]
 
[h2]per-package override files[e]
 
per-package override files: mpx.conf has a real per-package "<name>:" section built into its own KEY="value" grammar; this file has no grammar at all (just plain shell), so it can't have that same syntax -- but it can get the same EFFECT anyway. mpx always exports MP_PKG (the port's own pkg_name, e.g. "zstd" -- see mplib::hooks::port_env_args, shared by every phase of every port) into this script's own environment before it runs, so a same-named file under mpx.env.d/ can just be sourced conditionally, giving exactly mpx.conf's per-package section override semantics but for arbitrary shell/env content instead of a fixed key set. placed LAST (not first) so a per-package file's own exports win over anything set globally above -- same "more specific wins" precedence mpx.conf's own per-package sections already have. absent entirely (no mpx.env.d/ directory, or no file for this particular package) is a silent no-op, same as this whole file being absent.
 
MUST be an "if", not a bare "A && B && C" statement: this whole file runs under "set -e" (see above), and busybox ash -- unlike the POSIX text some other shells go by -- aborts the ENTIRE script the moment ANY command in a bare "&&" list fails, not just the last one. written as a plain "[ -f ... ] && [ -f ... ] && . ..." line, this construct broke EVERY SINGLE BUILD ON THE SYSTEM the moment it was tried for real, the instant a package with no override file of its own (i.e. nearly every package) hit the middle "[ -f ... ]" test and failed it -- caught only by actually running it, not by reasoning about the POSIX spec text. an "if" condition is unconditionally exempt from -e in every shell, which a bare AND-OR list statement is not guaranteed to be.
 
[code]
if [ -n "${MP_PKG:-}" ] && [ -f "/etc/mpx.env.d/$MP_PKG.env" ]; then
	. "/etc/mpx.env.d/$MP_PKG.env"
fi
[e]