.Dd $Mdocdate$
.Dt BUILD 1
.Os
.Sh NAME
.Nm build
.Nd follow embedded build instructions
.Sh SYNOPSIS
.Nm
.Op Fl d
.Op Fl d
.Op Fl d
.Op Fl f
.Ar file
.Op Ar ...
.Sh DESCRIPTION
.Pp
.Nm
is a program which follows simple build instructions
embedded in source files.
The number of
.Fl d
flags control the printing of debugging information.
The
.Fl f
flag disables modification time checks,
forcing the build process.
.Pp
.Nm
is decidedly not a
.Xr make 1
replacement, except in trivial cases.
In such cases, however,
it is a nice and simple solution.
The program is originally designed for generating
.Xr troff 1
documents,
but can be used with arbitrary source files.
.
.Sh SYNTAX
.Pp
The first twenty lines of each
.Ar file
are scanned for build information.
Build information is encoded in two ways:
.Bl -tag -width indent
.It command line (one or more)
[anything] <whitespace> "$ " <shell command>
.It dependency line (only one)
[anything] <whitespace> "% " <files separated by whitespace>
.El
.Pp
Within each command line,
.Nm
searches for a
.Em target :
.Bl -tag -width indent
.It target
.br
">" <filename without whitespace>
.El
.Pp
The last target found will be counted
as the real target for the build process.
If no target is found,
the commands will always be executed,
regardless of modification times.
.
.Sh OPERATION
.Pp
Unlike
.Xr make 1 ,
.Nm
executes all command lines,
joined by newlines,
in the same shell process.
This means that you can keep state across multiple commands.
Note that all commands are executed
regardless of the exit status of previous commands.
.Pp
If a command fails,
.Nm
exits with a positive status and aborts the build process.
.
.Sh EXAMPLES
.Pp
Assuming that the file
.Pa prg.c
starts with the following text,
.Bd -literal -offset indent
/**
  *  To build this program, use the following invocation:
  *     $ cc -O2 -o prg prg.c # > prg
  */
.Ed
.Pp
the invocation
.Bd -literal -offset indent
$ build prg.c
.Ed
.Pp
will build
.Pa prg .
(Because
.Xr cc 1
does not print the built file on standard output,
a commented
.Ql > prg
is necessary to set the target correctly.
.Pp
Assuming that the file
.Pa doc.t
starts with the following text,
.Bd -literal -offset indent
\&.\\" This document is built with the following shell commands:
\&.\\"    $ refer -p refs doc.t | troff -ms | dpost > doc.ps
\&.\\"    $ ps2pdf doc.ps > doc.pdf
\&.\\"    $ rm doc.ps
\&.
\&.\\" Apart from this file, it depends on the following files:
\&.\\"    % refs x.tmac
.Ed
.Pp
the invocation
.Bd -literal -offset indent
$ build doc.t
.Ed
.Pp
will build
.Pa doc.pdf ,
depending on the relative modification times of
.Pa doc.pdf ,
.Pa doc.t
and
.Pa x.tmac .
.\" .Sh DIAGNOSTICS
.\" .Sh SEE ALSO
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh AUTHORS
.Nm
is written by John Ankarström
.Aq Mt "john (at) ankarstrom.se" .
.\" .Sh BUGS