'\" t
.\"	aegis - project change supervisor
.\"	Copyright (C) 1991-2008 Peter Miller
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 3 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program. If not, see
.\"	<http://www.gnu.org/licenses/>.
.\"
.so z_name.so
.TH "\*(n) -Build" 1 \*(N) "Reference Manual"
.SH NAME
\*(n) -Build \- build a change
.XX "aeb(1)" "build a change"
.SH SYNOPSIS
.B \*(n)
.B -Build
[
.IR option ...
][
.IR filename ...
]
.br
.B \*(n)
.B -Build
.B -List
[
.IR option ...
]
.br
.B \*(n)
.B -Build
.B -Help
.SH DESCRIPTION
The
.I \*(n)
.I -Build
command is used to
build a project.
The project configuration file is consulted for the
appropriate build command,
and that command is executed
(see
the \fIbuild_\% command\fP
and \fIintegration_\%build_\%command\fP
fields in
.IR aepconf (5)
for more information.)
Output of the command is automatically logged to the
.I \*(n).log
file at the root of the development directory tree.
The build command will be executed with its current directory being
the root of the development directory,
irrespective of there the
.I "\*(n) -Build"
command was executed.
.PP
If the change is in the
.I "being integrated"
state,
references to the development directory, above,
should be read as the integration directory.
Integration build commands are executed with the user and group
set to the project's owning user and group.
That is,
it is not necessary for an integrator to log in as someone else,
the project account for instance,
in order to do an integration.
.SS "No Build Required"
It is possible to configure your project so that no build is required.
To do this, set the following
.RS
build_command = "exit 0";
.RE
in the project configuration file.
.SS Process Side Effects
This command will cancel any test registrations,
because building the project logically invalidates them.
If the project
configuration
file was deleted,
any diff registration will also be canceled.
.SS Notification
The actions of the command are controlled by the \fIbuild_\% command\fP
and \fIintegration_\%build_\%command\fP fields of the project \fIconfig\fP
file.  See \fIaepconf\fP(5) for more information.
.so z_promotion.so
.SH PARTIAL BUILD
If files are named on the command line,
these files are appended to the build command.
This is known as a partial build.
Partial builds are not legal in the
.I "being integrated"
state,
but can often be useful in the
.I "being developed"
state.
Partial builds are not recorded in the change status,
because builds are decoupled from aegis it is not
possible for aegis to know if any set of partial builds is equivalent
to a full build.
.PP
Warning:
no change state lock is taken for a partial build,
only a baseline read lock.
.so z_intuit.so
.so o_symlnk.so
.so z_bl_lock.so
.so z_metrics.so
.SH OPTIONS
The following options are understood:
.TP 8n
\fIname\fP\fB=\fP\fIvalue\fP
Command line arguments of this form are assumed to be variable assignments
for the build tool.  They are passed through unchanged.  They imply a
partial build.
.so o_baserel.so
.so o_change.so
.so o_help.so
.so o_list.so
.TP 8n
\fB\-MINImum\fP
This option may be used to request a source-only
\fIdevelopment_\%directory_\%style\fP.  This is useful if you
want to simulate something like \fIaeib \-minimum\fP in the
development directory.  This option is only meaningful if
\fIdevelopment_\%directory_\%style\fP is being used.  If the change
is in the \fIbeing integrated\fP state, and the developer specified
\fB\-MINImum\fP when issuing the \fI\*(n) \-Integrate_Begin\fP command,
then this option is set by default.
.so o_nolog.so
.so o_project.so
.so o_terse.so
.so o_verbose.so
.so o_symlnk_vfy.so
.so o_wait.so
.so o__rules.so
.SH RECOMMENDED ALIAS
The recommended alias for this command is
.nf
.ta 8n 16n
csh%	alias aeb '\*(n) -b \e!* -v'
sh$	aeb(){\*(n) -b "$@" -v}
.fi
.SH ERRORS
It is an error if
the change is not assigned to the current user.
.br
It is an error if
the change is not in one of the
.I "being developed"
or
.I "being integrated"
states.
.br
It is an error if
a partial build is requested and the change is in the
.I "being integrated"
state.
.so z_exit.so
.br
.ne 1i
.SH SEE ALSO
.TP 8n
.IR aedb (1)
begin development of a change
.TP 8n
.IR aecp (1)
file copy also takes a baseline read lock (non-exclusive)
.TP 8n
.IR aeib (1)
begin integration of a change
.TP 8n
.IR aeipass (1)
integrate pass takes a baseline write lock (exclusive)
.TP 8n
.IR aet (1)
run tests
.TP 8n
.IR aemetrics (5)
metrics values file format
.TP 8n
.IR aepconf (5)
project configuration file format
.TP 8n
.IR aeuconf (5)
user configuration file format
.so z_cr.so