Document the targets types.

1 files changed, 153 insertions, 73 deletions

diff --git a/mbld/mbld.1 b/mbld/mbld.1
index 8519fe3..58728b9 100644
--- a/mbld/mbld.1
+++ b/mbld/mbld.1
@@ -28,6 +28,50 @@ the arguments specified on the command lines.
 Mbld will default to building for the current architecture and operating
 system.
 
+.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 ACTIONS
 
 Mbld already knows how to do most of the common commands. Given a file
@@ -91,80 +135,21 @@ 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.
 
+Each Myrddin source file may have a corresponding implicit
+test. If a source file
+.I foo.myr
+is built, then the corresponding
+.I test/foo.myr
+is used as the testcase for
+.I foo.myr
+if it exists.
+
 A typical build file may look something like:
 
 .EX
@@ -178,7 +163,8 @@ The full grammar is listed below:
 
 .EX
   bldfile	: bldent+
-  bldent	: "bin" target
+  bldent
+	: "bin" target
   	| "lib" target
   	| "test" target
   	| "bench" target
@@ -188,7 +174,8 @@ The full grammar is listed below:
   	| "man" flist
   	| "sub" flist
   	| option
-  option	: "incpath" "=" list
+  option
+	: "incpath" "=" list
   	| "libdeps" "=" list
   	| "testdeps" "=" list
   	| "runtime" word
@@ -200,6 +187,76 @@ The full grammar is listed below:
   name	: <nonspace> | <quoted word>
 .EE
 
+.PP
+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 
+.I ${BASEDIR}/bin
+when invoking
+.I mbld install.
+Test and bench targets built and run
+when invoking
+.I mbld bench.
+Tests are run with the
+.I cwd
+set to the directory that contains
+the test source
+
+.PP
+Lib targets also resemble bin targets, but instead of
+producing a binary, they produce a
+.I .use
+and
+.I .a
+file pair. These files are installed to
+.I ${BASEDIR}/lib/myr
+when invoking
+.I mbld install.
+
+.PP
+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.
+
+.PP
+On the other targets are not invoked implicitly at all,
+unless they have an attribute such as
+.I test
+or
+.I bench.
+Instead, they are invoked explicitly by the user, bundling
+up some useful command or another, possibly providing system
+specific variants.
+
+.PP
+Data targets allow the specification of bundled static data.
+This data may be generated from a
+.I 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
+.I ${BASEDIR}/share.
+
+.PP
+Man targets are installed to the system-appropriate manual
+directory. The section is determined by the manpage suffix.
+For example
+.I foo.1
+would be installed into section 1 of the manual.
+
+.PP
+Sub targets include a
+.I bld.sub
+or
+.I bld.proj
+from a subdirectory. If the file in the subdirectory is
+.I bld.proj
+then the root of the project is changed for that subbuild.
+
 .SH ATTRIBUTES
 
 Many targets support attributes. These are the valid
@@ -277,7 +334,7 @@ target should be re-run when the argument changes.
 .B path=path
 When specified on a data target, provides the desired
 installation directory. Defaults to
-.I ${PREFIX}/share .
+.I ${BASEDIR}/share.
 
 .SH FILES
 
@@ -310,9 +367,32 @@ named \fIlibfoo.a\fP, consisting of the files \fIbar.myr\fP
 and \fIbaz.myr\fP
 
 
+.SH ENVIRONMENT VARIABLES
 
-.SH FILES
-The source for muse is available from
+.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 SOURCES
+The source for mbld is available from
 .B git://git.eigenstate.org/git/ori/mc.git
 and lives in the
 .I mbld/