The `build-target` program

Interface

  build-target opts target

where opts is a set of arguments as listed below, and target is a build target.

Options

-b: borrow (default): Borrow target files if possible.
-B: no borrow: Do not borrow target files.
-q: quiet: Do not print compilation commands.
-v: verbose (default): Print compilation commands.
-V: extra verbose: Print trace and compilation commands.
--: terminate the option list.

By default, build-target compiles the it target.

File Name Restrictions

Source file names ending in .do (do files) and file names containing = (control files) are reserved to control compilation of targets.

Do not use special shell characters or whitespace in your source file names.

Do Files

There are two types of do files: exact and default. An exact do file for target is named target.do. A default do file for targets with the file extension ext is named default.ext.do. For files without extension, the default do file is default.do. In each case, ext may not contain a period.

To compile a target, build-target looks first for an exact do file, then for a default do file, and then for default.do, and executes instructions from the first one it finds.

If build-target cannot compile target, and if target does not exist in the project directory, build-target invokes build-borrow to copy target into the project directory. If that fails, build-target tries to borrow a do file for target, looking for an exact do file, a default do file, or default.do.

If the do file already exists in the project directory, then build-target tries to borrow a control file for the target, using the control-file extensions listed in conf-control. Directories are listed one per line, and the first empty line ends the list. Anything following the first empty line is ignored.

If conf-control does not exist, then build-target obtains the extension list from /package/host/superscript.com/prog/build/conf/control. If it finds an appropriate control file, build-target makes another attempt to compile the target.

If all else fails, build-target complains to standard error and exits nonzero.

Do File Instructions

A do file consists of dependency statements makefile instructions, and compiling instructions, in this order.

A do file is executed with three arguments:

$1 is target.
$2 is target stripped of its extension, if any.
$3 is the temporary file target.tmp.

A do file must exit 0 if compilation succeeds, and nonzero otherwise. An exit code of 99 indicates that build-target should repeat the attempt to build a target. Other nonzero exit codes cause build-target to abandon the effort and exit nonzero.

A do file is executed under sh -e; a nonzero command exit causes the script to exit.

Dependency statements

A dependency statement has one of two forms:

  dependon dep ...

for a target dependency dep, or

  dependcc file.c

for some C source file file.c. Note that the argument list for dependon or dependcc may be produced by a subshell.

dependon invokes build-target for each of its arguments

dependcc generates a list of dependencies for a C source file, and calls dependon with this list as arguments. Dependencies are assumed to match the awk regular expression

  ^[ \t]*#[ \t]*include[ \t][ \t]*"[^"]*"[ \t]*$

Makefile instructions

The command formake records its arguments as a line of makefile instructions for the current target. Multiple formake commands in a do file produce multiple instruction lines for the corresponding makefile target.

Compiling instructions

Compiling instructions follow makefile lines in the do file. They compile target, writing the results to standard output, which is redirected to point at $3, which build-target moves to $1 if compilation succeeds.

If the compilation instructions produce target directly, as the product of invoking a compiler or linker, for example, the do file should invoke directtarget, which tells build-target not to move the temporary file to target.

When a do file cannot determine how to create target, it should invoke nosuchtarget. This will trigger the attempts to borrow target, a do file, or a control files, as described above.

Control Files

Some do files look at control files for auxiliary information, including dependency lists and compilation types. A control file for target has the form $2=type, following the do file argument conventions. For example, the control file for the target unix.a is unix=l, and the control file for build-target is build-target=s.

The significance of a control file is determined not by build-target but by the compiling instructions in a do file. At present, the do files in djblib and weblib recognize the following type strings:

d (default.do): The target is not one of the types listed below. The control file lists dependencies for the target. Use of the dependencies is target specific.
l (default.a.do): The target is a library. The control file lists object files to archive.
m (default.o.do): The target is an object file. Assemble source code in $2.s rather than compiling $2.o, the default means of .o-file creation.
s (default.do): The target is a script. If nonempty, the control file lists files to concatenate to form the target script. If empty, the control file indicates that the implicit dependency file $2.sh contains the body of the Bourne shell script.
x (default.do): The target is an executable file. The control file lists object files and libraries to link to create the target. The object $2.o is implicit, and should not be listed in the control file.

The build-target program