docs/reference/extensions.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]writing an extension[e]
 
an extension (a plugin, in mk/b.sh's own naming) is just a normal mp command script, dropped in plugins/ instead of src/. mk/b.sh installs plugins/<name>.pl as "mp.<name>", exactly the same way it installs src/<name>.pl -- same naming convention, same dispatch. mp itself does not distinguish an extension from a core command at run time; the only difference is plugins.list, generated at build time, which lets mp and mp help list extensions separately under their own heading.
 
nothing differs from writing a core command in src/. write it exactly the same way:
 
[code lang="perl"]
#!/usr/bin/env perl
use strict;
use warnings;
use FindBin;
use lib "$FindBin::Bin";
use mplib::config qw($CFG);
use mplib::util qw(fail ok);
use mplib::resolve qw(init);
 
my $flags = mplib::config::parse_flags(\@ARGV);
mplib::config::load($flags);
init();
# ... your command, using whatever mplib::* modules you need ...
[e]
 
FindBin::Bin resolves to the directory the installed mp.<name> symlink lives in -- the top-level build output, where mp, mplib, and every other mp.<cmd> also live, not to plugins/ or src/ themselves. this line is identical regardless of which source directory your .pl file lives in.
 
see hello.pl in the plugins/ directory for a complete, runnable example -- run mp hello after a rebuild.
 
an extension named the same as an existing core command is skipped at build time. a warning prints, and the core command wins. an extension can never silently shadow a built-in.
 
whether an extension actually gets installed at all is a USE flag, on meta/mp itself: pkg_use declares "+ext_<name>" (default on) for every extension currently in plugins/, plus a master "+extensions" that gates all of them together regardless of their own individual flag. every core command gets the identical treatment, one "+<cmd>" flag each plus its own master "+commands". "mp use mp -ext_hello" excludes just mp.hello on the next reinstall of mp; "mp use mp -extensions" excludes every extension at once; "mp use mp -commands" excludes every core command at once. see meta/mp's own pkg.conf (in the ports tree, not this repo) for the two real risks this opens up (excluding install/remove/reinstall/update/use/commands, or hook) before touching any of them -- "commands" carries the first risk at its worst: verified by actually hitting it, "mp use mp -commands" then a reinstall removes mp.use itself along with everything else, leaving no other mp.<command> to undo it with. "mp rescue" is the built-in answer: hardcoded directly into mp.pl's own dispatch (never a separate mp.<command> file, so no USE flag can ever exclude it), it rebuilds mp from source and reinstalls every command and extension unconditionally, then clears any USE= override on "mp" itself so the very next ordinary reinstall doesn't just strip everything straight back out again. verified the same way: ran it against exactly this broken state and confirmed the full recovery for real.