MBLD(1)

💅 MBLD(1) — the manual page, but make it make sense

okay so real talk: this is mbld, straight out of the General Commands Manual, and it's genuinely one of those tools that's lowkey iconic once you actually get what it's doing. so sit down, grab a strawberry 🍓, and let's go.

✨ NAME ✨

mbld — the build tool bestie. that's it, that's the name 💖

🎀 SYNOPSIS 🎀

mbld [-?hcfrSs] [-b bin] [-l lib] [-R src] [-I inc] [-B base]
[-r runtime]
[all | clean | install | uninstall | test | file... | target...]

(yes, -c, -f, -s and -B base are in there too — we keep everything, that's the rule 👑)

🦋 DESCRIPTION 🦋

okay so here's the vibe: mbld takes as input a list of Myrddin or assembly sources, and compiles them in the correct dependency order into either a library or an executable. it just knows the order. main character energy fr.

by default, it reads from an input file called bld.proj. but if you hand it the -b or -l option, it'll build a binary or a library (respectively) straight from the arguments you specified on the command lines instead. no project file needed, we're freestyling ✨

and mbld will default to building for the current architecture and operating system. it just matches your vibe automatically. 🫶

🔥 OPTIONS 🔥

• -h | -? — print a summary of the available options. the classic "help me help you" move.
• -b binname — compile source into a binary named name. if neither this option nor the -l option are given, mbld will create a binary called a.out. yes, a.out. it's giving vintage 💀
• -I path — add path to the search path for unquoted use statements. heads up though: this option does not affect the search path for local usefiles, which are always searched relative to the compiler's current working directory. without any options, the search path defaults to /usr/include/myr.
• -l libname — compile source given into a library called libname.a (or the equivalent for the target platform), and a matching usefile called name. only static libraries are currently supported. and yeah — it ignores the contents of bld.proj and bld.sub if they exist. like, fully ignores them. not even a glance. 🙈
• -R src — compile source given into a binary in temporary storage, and then execute it with the command line arguments passed in. build it, run it, no notes.
• -S — tell the toolchain to generate assembly for the code being compiled as well as the .o files, as though -S was passed to 6m.
• -r runtime — compile a binary using the runtime rt. if the runtime name given is none, then no runtime will be linked. if this option is not provided, then the default runtime in $INSTALL_ROOT/myr/lib/_myrrt.o will be used.

---

🌈 ACTIONS 🌈

mbld already knows how to do most of the common commands. given a file describing your project, it can build, test, clean, install, uninstall, and benchmark your code. it's the whole package, honestly.

• all — the all action will build all the non-test targets specified in the build file. if there are generated files included in the build, then their generation commands will be run.
• clean — the clean action will remove all compiled files and non-durable generated inputs from the build directories. self-care 💅
• install — the install action will copy the generated sources, manpages, data files, and anything else installable into the appropriate directories for the current system. if the DESTDIR environment variable is set, then its contexts will be prepended to the install path.
• uninstall — the uninstall action will remove the files installed by the install action. we love a reversible decision.
• test — the test action will build the test cases, and run them. if the test case exits with a non-zero status, that is counted as a failure. if a test outputs subtest data, then this target will show the output in a pretty format ✨ (pretty output is the whole point, obviously)
• bench — the bench action will build the benchmarks and run them. at the end of the run, the run statistics are shown. benchmarks must generate output in the subtest format. no subtest format, no stats, that's the deal.
• list — the list action lists all available targets for the build. window shopping 🛍️

---

🧚 BUILD FILES 🧚

build files contain lists of targets. targets generally consist of a target type. this is usually followed by target name, an attribute list, and the list of inputs. very "type, name, attrs, inputs" of them.

each Myrddin source file may have a corresponding implicit test. if a source file foo.myr is built, then the corresponding test/foo.myr is used as the testcase for foo.myr if it exists. it's automatic. it's giving clairvoyant.

a typical build file may look something like:

bin foo = main.myr gen-foo.myr ;;
man = foo.1 ;;
gen gen-foo.myr = sh -c "echo $FOO > gen-foo.myr" ;;
lib foothing = lib.myr ;;

the full grammar is listed below:

bldfile   : bldent+
bldent
   : "bin" target
     | "lib" target
     | "test" target
     | "bench" target
     | "gen" target
     | "cmd" target
     | "data" flist
     | "man" flist
     | "sub" flist
     | option
option
   : "incpath" "=" list
     | "libdeps" "=" list
     | "testdeps" "=" list
     | "runtime" word
     | "noinst"
target    : name [attrs] "=" list
flist     : [attrs] "=" list
list : name+ ";;"
attrs     : "{" (key [ "=" value])* "}"
name : <nonspace> | <quoted word>

🫶 the target types, explained 🫶

bin, test, and bench targets all behave in a very similar way. they all produce a single binary from a list of Myrddin sources, scraping the appropriate library dependencies and building any libraries from the local source directories. bin targets are installed to ${BASEDIR}/bin when invoking mbld install. test and bench targets are built and run when invoking mbld bench. tests are run with the cwd set to the directory that contains the test source.

lib targets also resemble bin targets, but instead of producing a binary, they produce a .use and .a file pair. these files are installed to ${BASEDIR}/lib/myr when invoking mbld install.

gen and cmd targets are also similar to each other, varying largely in when and how they are invoked. gen targets specify an output file, and are run in response to a target requiring their output.

the other targets are not invoked implicitly at all, unless they have an attribute such as test or bench. instead, they are invoked explicitly by the user, bundling up some useful command or another, possibly providing system specific variants.

data targets allow the specification of bundled static data. this data may be generated from a gen target, or may simply be shipped as a file. the data is installed to the system specific share directory. for example, on Unix, this may be ${BASEDIR}/share.

man targets are installed to the system-appropriate manual directory. the section is determined by the manpage suffix. for example foo.1 would be installed into section 1 of the manual.

sub targets include a bld.sub or bld.proj from a subdirectory. if the file in the subdirectory is bld.proj then the root of the project is changed for that subbuild.

---

👑 ATTRIBUTES 👑

many targets support attributes. these are the valid attributes allowed in the targets. bestie, there are a lot of them, and every single one matters:

• ldscript — link the target using an ldscript. this is a system dependent option, and should be avoided. valid on binary targets.
• runtime — link the target using a custom runtime. valid on binary targets.
• inc=path — add a path to the include path. valid on binary targets.
• tag=tagname — build this target only when the build tag tag is specified.
• inst — install this target. this is the default for all non-test targets.
• noinst — do not install this target when running mbld install.
• test — this target should run as a test. this is how command targets are turned into test runners.
• bench — this target is run as a benchmark. this is how command targets are turned into benchmark runners.
• notest — this target is not to be run as a benchmark. it's particularly fun to use in conjunction with test targets, in spite of being spectacularly useless. 💀 iconic honestly
• durable — the file generated by this gen or cmd target should not be removed with mbld clean. this is useful for keeping around files where the user may not have or want to run the generation code.
• dep=path — specifies that a gen or cmd target should be re-run when the argument changes.
• path=path — when specified on a data target, provides the desired installation directory. defaults to ${BASEDIR}/share.

---

🌸 FILES 🌸

• bld.proj — the root project file. all paths in bldfiles are relative to the most recent one in the directory heirarchy.
• bld.sub — a sub build. this contains targets, and may specify dependencies on other targets within the same project.

⭐ EXAMPLE ⭐

mbld

the command above will load bld.proj and all associated sub builds, and run the commands to incrementally rebuild the code. incremental rebuilds, we stan 🫶

mbld -l foo bar.myr baz.myr

the command above will ignore bld.proj and produce a library named libfoo.a, consisting of the files bar.myr and baz.myr. two files in, one .a out. slay.

💜 ENVIRONMENT VARIABLES 💜

• DESTDIR — prepends $DESTDIR to the path to install to. for example, if the install prefix is /usr, the binary path is bin/, then binaries will get copied to $DESTDIR/usr/bin on mbld install.
• MYR_MC — compiles the binaries with $MYR_MC instead of the default value, 6m.
• MYR_MUSE — merges usefiles with $MYR_MUSE instead of the default value muse.
• MYR_RT — links with the runtime $MYR_RT instead of the default ${BASEDIR}/lib/myr/_myrrt.o.

🍓 SOURCES 🍓

the source for mbld is available from git://git.eigenstate.org/git/ori/mc.git and lives in the mbld/ directory within the source tree. go poke around, it's fine, it's cute.

🦋 SEE ALSO 🦋

6m(1) muse(1) ld(1) as(1)

💀 BUGS 💀

none known. genuinely. not one. we're as shook as you are 😭

---

ngl the whole thing is basically "tell mbld what you want and it handles the dependency order for you" — that's the entire thesis. periodt.

okay that's the whole page, no cap, every flag and grammar rule intact 💖 this was the MBLD(1) page from the General Commands Manual — go build something iconic, bestie 🌈👑