MBLD(1) MBLD(1)
NAME
mbld
SYNOPSIS
mbld [ -?hcfrSs ] [ -b bin ] [ -l lib ] [ -R src ] [ -I inc
] [ -B base ] [ -r runtime ] [ all | clean | install |
uninstall | test | file ... | target ... ]
DESCRIPTION
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.
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.
Mbld will default to building for the current architecture
and operating system.
OPTIONS
-h | -?
Print a summary of the available options.
-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.
-I path
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.
-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. Ignores the contents of bld.proj
and bld.sub if they exist.
-R src
Compile source given into a binary in temporary
storage, and then execute it with the command line
arguments passed in.
-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 given runtime. If the run-
time 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.
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 com-
mands will be run.
clean
The clean action will remove all compiled files and
non-durable generated inputs from the build direc-
tories.
install
The install action will copy the generated sources,
manpages, data files, and anything else installable
into the appropriate directories for the current sys-
tem. 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.
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.
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.
list The list action lists all available targets for the
build.
BUILD FILES
Build files contain lists of targets. Targets generally con-
sist of a target type. This is usually followed by target
name, an attribute list, and the list of inputs. Each Myrd-
din 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.
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>
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 built and run when
invoking mbld bench. Tests are run with the working direc-
tory set to the directory that contains the test source
Lib targets also resemble bin targets, but instead of pro-
ducing 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.
On 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 subdirec-
tory. 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 attri-
butes allowed in the targets.
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 tar-
gets.
tag=tagname
Build this target only when the build tag tagname 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 par-
ticularly fun to use in conjunction with test targets,
in spite of being spectacularly useless.
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 rela-
tive 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.
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.
ENVIRONMENT VARIABLES
DESTDIR
Prepends $DESTDIR to the installation path. For exam-
ple, if the installation prefix is /amd64 and the
binary path is /bin, the resulting binaries will be
copied to $DESTDIR/amd64/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.
SEE ALSO
6m(1), muse(1), make(1), mk(1)
BUGS
None known.
/plan9/man/1/