home | help 
MBLD(1) 		     General Commands Manual			 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 op-
	    tion does not affect the search path for local usefiles,  which  are
	    always  searched  relative	to the compiler's current working direc-
	    tory. Without any options, the  search  path  defaults  to	/usr/in-
	    clude/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 runtime rt.  If the runtime name given is
	    none, then no runtime will be linked. If this  option  is  not  pro-
	    vided,  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  de-
     scribing  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 commands will be run.

     clean  The clean action will remove all compiled files and non-durable gen-
	    erated inputs from the build directories.

     install
	    The install action will copy the generated sources,  manpages,  data
	    files,  and  anything else installable into the appropriate directo-
	    ries 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.

     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 consist of a target
     type.  This  is usually followed by target name, an attribute list, and the
     list of inputs.

     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.

     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 appro-
     priate  library  dependencies  and  building  any	libraries from the local
     source directories. Bin targets are installed to ${BASEDIR}/bin when invok-
     ing mbld install.	Test and bench targets 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 mbldinstall.

     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 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.

     ldscript
	    Link the target using an ldscript. This is a  system  dependent  op-
	    tion, 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 spectacu-
	    larly 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  argu-
	    ment 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.

	 mbld -l foo bar.myr baz.myr

     The command above will ignore bld.proj and produce  a  library  named  lib-
     foo.a, consisting of the files bar.myr and baz.myr

ENVIRONMENT VARIABLES
     DESTDIR
	    prepends $DESTDIR to the path to install to. For example, if the in-
	    stallgg  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 hte 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.eigen-
     state.org/git/ori/mc.git and lives in the mbld/ directory within the source
     tree.

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

BUGS
     None known.

									 MBLD(1)
home | help