ref: 172ac611f5271a020a8081dd6768e01ed8dd5e55
dir: /mbld/mbld.1/
.TH MBLD 1
.SH NAME
mbld
.SH SYNOPSIS
.B mbld
.I [all | clean | install | uninstall | test]
.I -[?csSfr]
.I [-b bin]
.I [-l lib]
.I [-R src]
.I [-I inc]
.I [-B base]
.I [-r runtime]
.I [file... | targets...]
.br
.SH DESCRIPTION
.PP
The 'mbld' tool 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.
.PP
By default, it reads from an input file called 'bld.proj', but if given the
option '-b' or '-l', it will build a binary or library, respectively, from
the arguments specified on the command lines.
.PP
Mbld will default to building for the current architecture and operating
system.
.SH 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.
.TP
.B all
The
.I 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.
.TP
.B clean
The
.I clean
action will remove all compiled files and non-durable generated inputs
from the build directories.
.TP
.B install
The
.I install
action will copy the generated sources, manpages, data files, and anything
else installable into the appropriate directories for the current system.
If the
.I DESTDIR
environment variable is set, then its contexts will be prepended to the
install path.
.TP
.B uninstall
The
.I uninstall
action will remove the files installed by the
.I install
action.
.TP
.B test
The
.I 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.
.TP
.B bench
The
.I 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.
.TP
.B list
The
.I list
action lists all available targets for the build.
.SH OPTIONS
.TP
.B -[h|?]
Print a summary of the available options.
.TP
.B -b \fIbinname\fP
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'.
.TP
.B -I \fIpath\fP
Add 'path' to the search path for unquoted use statments. 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.
.TP
.B -l
.I libname
Compile source given into a library called 'lib\fIname\fP.a' (or the equivalent
for the target platform), and a matching usefile called 'name'. Only static
libraries are currently supported. Ignores the contents of \fIbld.proj\fP
and \fIbld.sub\fP if they exist.
.TP
.B -R
.I src
Compile source given into a binary in temporary storage, and then execute it
with the command line arguments passed in.
.TP
.B -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.
.TP
\fB-r \fIruntime
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.
.SH ENVIRONMENT VARIABLES
.TP
.B DESTDIR
prepends $DESTDIR to the path to install to. For example, if the installgg
prefix is /usr, the binary path is bin/, then binaries will get copied
to $DESTDIR/usr/bin on
.B mbld install
.TP
.B MYR_MC
Compiles the binaries with '$MYR_MC' instead of the default value of
6m.
.TP
.B MYR_MUSE
Merges usefiles with '$MYR_MUSE' instead of hte default value of
muse.
.TP
.B MYR_RT
Links with the runtime $MYR_RT instead of the default of
prefix/lib/myr/_myrrt.o.
.SH 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.
A typical build file may look something like:
.EX
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 ;;
.EE
The full grammar is listed below:
.EX
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>
.EE
.SH ATTRIBUTES
Many targets support attributes. These are the valid
attributes allowed in the targets.
.TP
.B ldscript
Link the target using an ldscript. This is a system
dependent option, and should be avoided. Valid on binary
targets.
.TP
.B runtime
Link the target using a custom runtime. Valid on binary
targets
.TP
.B inc=path
Add a path to the include
.I path .
Valid on binary targets.
.TP
.B tag=tagname
Build this target only when the build tag
.I tag
is specified.
.TP
.B inst
Install this target. This is the default for all non-test
targets.
.TP
.B noinst
Do not install this target when running
.I mbld install.
.TP
.B test
This target should run as a test. This is how command targets
are turned into test runners.
.TP
.B bench
This target is run as a benchmark. This is how command targets
are turned into benchmark runners.
.TP
.B 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.
.TP
.B durable
The file generated by this
.I gen
or
.I cmd
target should not be removed with
.I mbld clean.
This is useful for keeping around files where the user may not
have or want to run the generation code.
.TP
.B dep=path
Specifies that a
.I gen
or
.I cmd
target should be re-run when the argument changes.
.TP
.B path=path
When specified on a data target, provides the desired
installation directory. Defaults to
.I ${PREFIX}/share .
.SH FILES
.TP
.I bld.proj
The root project file. All paths in bldfiles are relative
to the most recent one in the directory heirarchy.
.TP
.I bld.sub
A sub build. This contains targets, and may specify dependencies
on other targets within the same project.
.SH EXAMPLE
.EX
mbld
.EE
.PP
The command above will load bld.proj and all associated sub builds,
and run the commands to incrementally rebuild the code.
.EX
mbld -l foo bar.myr baz.myr
.EE
.PP
The command above will ignore bld.proj and produce a library
named \fIlibfoo.a\fP, consisting of the files \fIbar.myr\fP
and \fIbaz.myr\fP
.SH FILES
The source for muse is available from
.B git://git.eigenstate.org/git/ori/mc.git
and lives in the
.I mbld/
directory within the source tree.
.SH SEE ALSO
.IR 6m(1)
.IR muse(1)
.IR ld(1)
.IR as(1)
.SH BUGS
.PP
None known.