'\" tp
.\"	aegis - project change supervisor
.\"	Copyright (C) 1991-1993, 1996, 1998, 1999, 2001-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) -Integrate_Pass" 1 \*(N) "Reference Manual"
.SH NAME
\*(n) -Integrate_Pass \- pass a change integration
.XX "aeipass(1)" "pass a change integration"
.SH SYNOPSIS
.B \*(n)
.B -Integrate_Pass
[
.IR option ...
]
.br
.B \*(n)
.B -Integrate_Pass
.B -List
[
.IR option ...
]
.br
.B \*(n)
.B -Integrate_Pass
.B -Help
.SH DESCRIPTION
The
.I \*(n)
.I -Integrate_Pass
command is used to
notify \*(n) that a change has passed integration.
The change is advanced
from the
.I "being integrated"
state to the
.I "completed"
state.
.\" ------------------------------------------------------------------------
.PS
boxwid = 1
down
box "being" "integrated"
arrow " integrate" ljust " pass" ljust
box "completed"
.PE
.\" ------------------------------------------------------------------------
.PP
This command updates the file histories, so that future
.IR aecp (1)
commands may extract previous file versions from history,
and so that future
.IR aed (1)
commands may merge out-of-date files.
The history is updated using the
.I history_create_command
and
.I history_put_command
fields of the project
configuration
file (see
.IR aepconf (5)
for more information).  The integrate pass will abort with an error if
one of these history commands should fail, \fIe.g.\fP by running out of disk
space.  If this should happen, the change will remain in the
.I "being integrated"
state, and the integration directory is unaltered.
.PP
Once the history has been updated, the integration directory is renamed
as the baseline directory, and the old baseline directory is deleted.
.PP
Once integrate pass is complete
the change is no longer assigned to the current user.
.SS History Tools Modify Files
Many history tools (\fIe.g.\fP RCS and SCCS) can modify the contents of
the file when it is committed.  This usually requires the use of specific
\[lq]keyword\[rq] strings, and there are usually options to turn this behavior
off, but users familiar with version control tools (as opposed to
configuration management systems) will often use these features.
The problem is that if the commit changes the file, the source file in
the repository now no longer matches the object file in the repository.
.I I.e.
the history tool has compromised the referential integrity of the
repository.  By default, a fatal error is emitted if the file is changed
by the check-in, however this can be modified to a be warning or even
ignored completely; see the
.I history_\%put_\%trashes_\%file\fP
field of
.IR aepconf (5)
for more information.
.SS File Modification Times
The modification times of all files modified since the beginning of
integration (see
.IR aeib (1)
for more information) are updated to be since the beginning of integrate
pass.  The order of modification times will be preserved, however the
time range will be compressed to the greatest extent possible.  This
ensures that subsequent development builds will notice that baseline
files have changed.
.PP
Note that if there are many new files with all different timestamps in
the integration directory, and if the number of files with different
timestamps exceeds the number of seconds since the start of the
integrate-pass command, Aegis may have to set file modification times
into the future.
.PP
The \fIbuild_\%time_\%adjust\fP field of the project \fIconfig\fP file
controls Aegis' behavior in this case.
(See \fIaepconf\fP(5) for more information.)
There are three settings:
.TP 8n
adjust_and_sleep
This setting, which is the default, causes Aegis to sleep until the file
modification times would no longer be in the future.
This avoids both development build problems and integration build problems,
both of which which can arise as a result "interesting" file modification times.
.TP 8n
adjust_only
Aegis will issue a warning that the file modification times extend
into the future, but will not sleep.  This may cause integration
build problems, particularly if you are using \fIaeintegratq\fP(1).
Development builds may perform redundant builds, however \fIaet -reg\fP
should not produce false negatives.
.TP 8n
dont_adjust
This is highly inadvisable.
It is provided solely for some very rare circumstances.
This setting causes Aegis not to adjust the file modification times at all.
This can have very unhappy side-effects, especially of the integration
build was \fIbefore\fP one or more development builds; the commonest
symptom being that development builds do not always cause a relink of
the necessary executables, and \fIaet -reg\fP may give false negatives.
It is \fBstrongly\fP recommended that you do not use this setting.
.PP
If you use \fIcook\fP(1), see the \fItime-adjust-back\fP flag for how
to compress the time range even further.  This usually makes the sleep (or the
warning period) significantly shorter.
.SS Notification
On successful completion of this command, after the directory rename
has ocurred and after the database has been updated, the
\fIintegration_\%pass_\%notify_\%command\fP field of the project
attributes is run, if set.  See \fIaepattr\fP(5) and \fIaepa\fP(1)
for more information.
This command is run as the project owner.
.PP
Some compilers bury absolute path names into object files and executables.
The renaming of the integration directory to become the new baseline
breaks these paths.  The above command is passed an environment variable
called AEGIS_\%INTEGRATION_\%DIRECTORY so that the appropriate symlink
may be placed, if desired.
.PP
Other commands run by this command include the
\fIhistory_\%create_\%command\fP, \fIhistory_\%put_\%command\fP and
\fIhistory_\%query_\%command\fP fields of the project \fIconfig\fP file.
See \fIaepconf\fP(5) for more information.
.so z_bl_lock.so
.SS The History Lock
Where a project has a number of branches active simultaneously, it is
possible for independent integrate pass commands for different branches
to be issued very close together.
The is an exclusive
.I "history lock"
taken by integrate pass to ensure that only one branch is
updating the file history at a time,
thus preventing history file corruption.
.so z_test_corr.so
.so z_metrics.so
.SH OPTIONS
The following options are understood:
.so o_change.so
.so o_help.so
.so o_list.so
.so o_nolog.so
.so o_project.so
.so o_reason2.so
.so o_terse.so
.so o_verbose.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 aeipass '\*(n) -ipass \e!* -v'
sh$	aeipass(){\*(n) -ipass "$@" -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 the
.I "being integrated"
state.
.br
It is an error if
there has been no successful
.I "'\*(n) -Build'"
command for the integration.
.br
It is an error if
there has been no successful
.I "'\*(n) -Test'"
command for the integration.
.br
It is an error if
there has been no successful
.I "'\*(n) -Test -BaseLine'"
command for the integration.
.so z_exit.so
.br
.ne 1i
.SH SEE ALSO
.TP 8n
.IR aeib (1)
begin integration of a change
.TP 8n
.IR aeifail (1)
fail integration of a change
.TP 8n
.IR aemeasure (1)
simple file metrics
.TP 8n
.IR aemetrics (5)
metrics values file format
.TP 8n
.IR aeuconf (5)
user configuration file format
.so z_cr.so