ref: ce6e4a562c00e9c86f3249ff60ca2875b679ef0f
parent: 172ac611f5271a020a8081dd6768e01ed8dd5e55
author: Ori Bernstein <ori@markovcorp.com>
date: Fri Nov 24 07:06:44 EST 2017
Document the targets types.
--- a/mbld/mbld.1
+++ b/mbld/mbld.1
@@ -28,6 +28,50 @@
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,74 +135,6 @@
.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
@@ -165,6 +141,15 @@
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 @@
.EX
bldfile : bldent+
- bldent : "bin" target
+ bldent
+ : "bin" target
| "lib" target
| "test" target
| "bench" target
@@ -188,7 +174,8 @@
| "man" flist
| "sub" flist
| option
- option : "incpath" "=" list
+ option
+ : "incpath" "=" list
| "libdeps" "=" list
| "testdeps" "=" list
| "runtime" word
@@ -200,6 +187,76 @@
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 @@
.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 @@
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/