Improve mbld manpage.

1 files changed, 185 insertions, 12 deletions

diff --git a/mbld/mbld.1 b/mbld/mbld.1
index ddfef1c..8519fe3 100644
--- a/mbld/mbld.1
+++ b/mbld/mbld.1
@@ -25,11 +25,73 @@ option '-b' or '-l', it will build a binary or library, respectively, from
 the arguments specified on the command lines.
 
 .PP
-Myrbuild will default to building for the current architecture and operating
+Mbld will default to building for the current architecture and operating
 system.
 
-.PP
-The myrbuild options are:
+.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|?]
@@ -38,7 +100,7 @@ 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, myrbuild will create a binary called 'a.out'.
+the '-l' option are given, mbld will create a binary called 'a.out'.
 
 .TP
 .B -I \fIpath\fP
@@ -97,14 +159,125 @@ muse.
 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 DESTDIR
-Specified that when the files installed by
-.I mbld install
-are put into place, the paths are prefixed with
-.I DESTDIR.
-This fits with the conventions of many package systems,
-allowing Myrddin code to be packaged more easily.
+.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
 
@@ -142,7 +315,7 @@ and \fIbaz.myr\fP
 The source for muse is available from
 .B git://git.eigenstate.org/git/ori/mc.git
 and lives in the
-.I myrbuild/
+.I mbld/
 directory within the source tree.
 
 .SH SEE ALSO