NAME
aegis integrate pass - pass a change integration
SYNOPSIS
aegis -Integrate_Pass [ option... ]
aegis -Integrate_Pass -List [ option... ]
aegis -Integrate_Pass -Help
DESCRIPTION
The aegis -Integrate_Pass command is used to notify aegis that a change
has passed integration. The change is advanced from the being
integrated state to the completed state. boxwid = 1 down box "being"
"integrated" arrow " integrate" ljust " pass" ljust box "completed"
This command updates the file histories, so that future aecp(1)
commands may extract previous file versions from history, and so that
future aed(1) commands may merge out-of-date files. The history is
updated using the history_create_command and history_put_command fields
of the project configuration file (see aepconf(5) for more
information). The integrate pass will abort with an error if one of
these history commands should fail, e.g. by running out of disk space.
If this should happen, the change will remain in the being integrated
state, and the integration directory is unaltered.
Once the history has been updated, the integration directory is renamed
as the baseline directory, and the old baseline directory is deleted.
Once integrate pass is complete the change is no longer assigned to the
current user.
History Tools Modify Files
Many history tools (e.g. RCS and SCCS) can modify the contents of the
file when it is committed. This usually requires the use of specific
“keyword” 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.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 history_put_trashes_file field of
aepconf(5) for more information.
File Modification Times
The modification times of all files modified since the beginning of
integration (see 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.
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.
The build_time_adjust field of the project config file controls Aegis’
behavior in this case. (See aepconf(5) for more information.) There
are three settings:
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.
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
aeintegratq(1). Development builds may perform redundant
builds, however aet -reg should not produce false negatives.
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
before one or more development builds; the commonest symptom
being that development builds do not always cause a relink of
the necessary executables, and aet -reg may give false
negatives. It is strongly recommended that you do not use this
setting.
If you use cook(1), see the time-adjust-back flag for how to compress
the time range even further. This usually makes the sleep (or the
warning period) significantly shorter.
Notification
On successful completion of this command, after the directory rename
has ocurred and after the database has been updated, the integration_
pass_notify_command field of the project attributes is run, if set.
See aepattr(5) and aepa(1) for more information. This command is run
as the project owner.
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.
Other commands run by this command include the history_create_command,
history_put_command and history_query_command fields of the project
config file. See aepconf(5) for more information.
THE BASELINE LOCK
The baseline lock is used to ensure that the baseline remains in a
consistent state for the duration of commands which need to read the
contents of files in the baseline.
The commands which require the baseline to be consistent (these include
the aeb(1), aecp(1) and aed(1) commands) take a baseline read lock.
This is a non-exclusive lock, so the concurrent development of changes
is not hindered.
The command which modifies the baseline, aeipass(1), takes a baseline
write lock. This is an exclusive lock, forcing aeipass(1) to block
until there are no active baseline read locks.
It is possible that one of the above development commands will block
until an in-progress aegis -Integrate_PASS completes. This is usually
of short duration while the project history is updated. The delay is
essential so that these commands receive a consistent view of the
baseline. No other integration command will cause the above
development commands to block.
When aegis’ branch functionality is in use, a read (non-exclusive) lock
is taken on the branch baseline and also each of the "parent"
baselines. However, a baseline write (exclusive) lock is only taken on
the branch baseline; the "parent" baselines are only read (non-
exclusive) locked.
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 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.
TEST CORRELATIONS
The “aegis -Test -SUGgest” command may be used to have aegis suggest
suitable regression tests for your change, based on the source files in
your change. This automatically focuses testing effort to relevant
tests, reducing the number of regression tests necessary to be
confident that you have not introduced a bug.
The test correlations are generated by the “aegis -Integrate_Pass”
command, which associates each test in the change with each source file
in the change. Thus, each source file accumulates a list of tests
which have been associated with it in the past. This is not as exact
as code coverage analysis, but is a reasonable approximation in
practice.
The aecp(1) and aenf(1) commands are used to associate files with a
change. While they do not actively perform the association, these are
the files used by aeipass(1) and aet(1) to determine which source files
are associated with which tests.
Test Correlation Accuracy
Assuming that the testing correlations are accurate and that the tests
are evenly distributed across the function space, there will be a less
than 1/number chance that a relevant test has not been run by the
“aegis -Test -SUGgest number” command. A small amount of noise is
added to the test weighting, so that unexpected things are sometimes
tested, and the same tests are not run every time.
Test correlation accuracy can be improved by ensuring that:
· Each change should be strongly focused, with no gratuitous file
inclusions. This avoids spurious correlations.
· Each item of new functionality should be added in an individual
change, rather than several together. This strongly correlates tests
with functionality.
· Each bug should be fixed in an individual change, rather than several
together. This strongly correlates tests with functionality.
· Test correlations will be lost if files are moved. This is because
correlations are by name.
The best way for tests to correlate accurately with source files is
when a change contains a test and exactly those files relating to the
functionality under test. Too many spurious files will weaken the
usefulness of the testing correlations.
METRICS
Aegis is capable of recording metrics as part of the file attributes of
a change. This allows various properties of files to be recorded for
later trend analysis, or other uses.
The specific metrics are not dictated by Aegis. It is expected that
the integration build will create a metrics file for each of the source
files the change. These metrics files must be in the format specified
by aemetrics(5).
The name of the metrics file defaults to “filename,S”, however it may
be varied, by setting the metrics_filename_pattern field of the project
config file. See aepconf(5) for more information.
If such a metrics file exists, for each source file in a change, it
will be read and remembered at integrate pass time. If it does not
exist, Aegis assumes there are no relevant metrics for that file, and
proceeds silently; it is not an error.
OPTIONS
The following options are understood:
-Change number
This option may be used to specify a particular change within a
project. See aegis(1) for a complete description of this
option.
-Help
This option may be used to obtain more information about how to
use the aegis program.
-List
This option may be used to obtain a list of suitable subjects
for this command. The list may be more general than expected.
-Not_Logging
This option may be used to disable the automatic logging of
output and errors to a file. This is often useful when several
aegis commands are combined in a shell script.
-Project name
This option may be used to select the project of interest.
When no -Project option is specified, the AEGIS_PROJECT
environment variable is consulted. If that does not exist, the
user’s $HOME/.aegisrc file is examined for a default project
field (see aeuconf(5) for more information). If that does not
exist, when the user is only working on changes within a single
project, the project name defaults to that project. Otherwise,
it is an error.
-REAson text
This option may be used to attach a comment to the change
history generated by this command. You will need to use quotes
to insulate the spaces from the shell.
-TERse
This option may be used to cause listings to produce the bare
minimum of information. It is usually useful for shell
scripts.
-Verbose
This option may be used to cause aegis to produce more output.
By default aegis only produces output on errors. When used
with the -List option this option causes column headings to be
added.
-Wait This option may be used to require Aegis commands to wait for
access locks, if they cannot be obtained immediately. Defaults
to the user’s lock_wait_preference if not specified, see
aeuconf(5) for more information.
-No_Wait
This option may be used to require Aegis commands to emit a
fatal error if access locks cannot be obtained immediately.
Defaults to the user’s lock_wait_preference if not specified,
see aeuconf(5) for more information.
See also aegis(1) for options common to all aegis commands.
All options may be abbreviated; the abbreviation is documented as the
upper case letters, all lower case letters and underscores (_) are
optional. You must use consecutive sequences of optional letters.
All options are case insensitive, you may type them in upper case or
lower case or a combination of both, case is not important.
For example: the arguments "-project, "-PROJ" and "-p" are all
interpreted to mean the -Project option. The argument "-prj" will not
be understood, because consecutive optional characters were not
supplied.
Options and other command line arguments may be mixed arbitrarily on
the command line, after the function selectors.
The GNU long option names are understood. Since all option names for
aegis are long, this means ignoring the extra leading ’-’. The
"--option=value" convention is also understood.
RECOMMENDED ALIAS
The recommended alias for this command is
csh% alias aeipass ’aegis -ipass \!* -v’
sh$ aeipass(){aegis -ipass "$@" -v}
ERRORS
It is an error if the change is not assigned to the current user.
It is an error if The change is not in the being integrated state.
It is an error if there has been no successful aegis -Build command
for the integration.
It is an error if there has been no successful aegis -Test command
for the integration.
It is an error if there has been no successful aegis -Test -BaseLine
command for the integration.
EXIT STATUS
The aegis command will exit with a status of 1 on any error. The aegis
command will only exit with a status of 0 if there are no errors.
ENVIRONMENT VARIABLES
See aegis(1) for a list of environment variables which may affect this
command. See aepconf(5) for the project configuration file’s project_
specific field for how to set environment variables for all commands
executed by Aegis.
SEE ALSO
aeib(1) begin integration of a change
aeifail(1)
fail integration of a change
aemeasure(1)
simple file metrics
aemetrics(5)
metrics values file format
aeuconf(5)
user configuration file format
COPYRIGHT
aegis version 4.24.3.D001
Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Peter
Miller
The aegis program comes with ABSOLUTELY NO WARRANTY; for details use
the ’aegis -VERSion License’ command. This is free software and you
are welcome to redistribute it under certain conditions; for details
use the ’aegis -VERSion License’ command.
AUTHOR
Peter Miller E-Mail: millerp@canb.auug.org.au
/\/\* WWW: http://www.canb.auug.org.au/~millerp/