.TH @BUILD 8
.SH NAME
@build, @clone, @ls, @make, @sh \- manage build trees
.SH SYNOPSIS
.B @build
.RI [ command
.RI [ arg " ...]]"
.br
.BI @ command
.RI [ arg " ...]"
.SH DESCRIPTION
.B @build
executes a command in the build tree.  The build tree is a directory full
of links to the files in the current directory, the name of this
directory is found by replacing the first
.B src
in the current working directory in
.BR build .
So /usr/src becomes /usr/build, and /usr/local/src becomes /usr/local/build.
.PP
These build trees, or "link farms" as they are often called, are used to
keep the object files and executables out of the source tree to keep the
source tree clean.
.PP
The major disadvantage of link farms is that links are easily broken by
changes in the source tree, sometimes by too smart editors, or by
running
.BR patch (1).
When that happens
.BR clone (1)
needs to be run from the build tree with the source directory name as
its argument.
.B @build
offers to do this for you if the build (sub)directory doesn't exists.
.PP
.B @build
is normally linked to the names
.BR @make ,
.BR @sh ,
.BR @ls ,
and
.BR @clone .
These
.BI @ cmd
commands are simply shorthands for
.B @build
.IR cmd ,
except that
.B @clone
is special, it gets the source directory as its argument if called
without arguments.
.SH "SEE ALSO"
.BR clone (1).
.SH BUGS
Shell metacharacters are expanded more than once.
.SH AUTHOR
Kees J. Bot (kjb@cs.vu.nl)