ref: 172ac611f5271a020a8081dd6768e01ed8dd5e55
parent: 12f30002c5d31a56779700bdb95fffbcef02d440
author: Ori Bernstein <ori@markovcorp.com>
date: Fri Nov 24 06:42:15 EST 2017
Improve mbld manpage.
--- a/mbld/mbld.1
+++ b/mbld/mbld.1
@@ -25,13 +25,75 @@
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|?]
Print a summary of the available options.
@@ -38,7 +100,7 @@
.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,15 +159,126 @@
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
.TP
@@ -142,7 +315,7 @@
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