.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1995, 1997-1999, 2002 Peter Miller;
.\"	All rights reserved.
.\"
.\"	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 2 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, write to the Free Software
.\"	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
.\"
.\" MANIFEST: Frequently Asked Questions, with answers
.\"
.\" The output of processing this document is meant to
.\" be in USENET Digest format, as described in RFC1153.
.\"
.ll 70
.ds sep ----------------------------------------------------------------------
.de H
.ft R
.in 0
.sp
\\*[sep]
.ds sep ------------------------------
.sp
.nr hd*level 0\\$1
.\"
.\" clear lower counters
.nr hd*i 1 1
.while \\n+[hd*i]<8 .if \\n[hd*level]<\\n[hd*i] .nr H\\n[hd*i] 0 1
.\"
.\" increment current counter
.nr H\\n[hd*level] +1
.\"
.\" hd*mark is the text written to the left of the header.
.ds hd*mark \\n[H1].
.nr hd*i 1 1
.while \\n+[hd*i]<8 .if \\n[hd*level]>(\\n[hd*i]-1) .as hd*mark \\n[H\\n[hd*i]].
Subject: \\*[hd*mark]
'in 8n
\\$2
.in 0
.sp
..
.de e(
.ft R
.in +8n
.ft CW
.nf
..
.de e)
.fi
.ft R
.in -8n
..
.so version.so
.hy 0
.ad l
.nf
Subject: Aegis Frequently Asked Questions (FAQ)
From: Peter Miller <millerp@canb.auug.org.au>
Newsgroups: comp.software-eng,comp.software.config-mgmt,
	comp.software.testing,comp.sources.d,alt.sources.d
.sp
Submitted-by: Peter Miller <millerp@canb.auug.org.au>
Archive-name: aegis.\*(v)/FAQ
.fi
.sp
This message contains answers to a number of frequently
asked questions about Aegis.
If you don't know what Aegis is, read on.
.sp
Suggestions for additions or improvements to this FAQ are most welcome.
.sp 2
.ce 1
Contents
.nf
.so toc.so
.fi
.H 1 "What is Aegis?"
Aegis is a transaction-based software configuration management system.
It provides a framework within which
a team of developers may work on many changes to a
program independently, and Aegis coordinates integrating
these changes back into the master source of the program,
with as little disruption as possible.
.sp
For a more complete description,
see the README file or the User Guide.
Both are available from the anonymous FTP site (see below).
.H 2 "What operating systems are supported?"
Aegis will run on almost any version of UNIX.
The distribution contains a configure script generate by GNU autoconf
to adapt to your site.
.sp
There is no Aegis port to NT, OS/2, MS-DOS or VMS.
The author has no expertise is these operating systems.
If you do have such expertise, you are welcome to donate a port of Aegis,
and I will try to include your work in the next release.
.H 3 "Cygwin"
There is a very capable UNIX emulation layer known as Cygwin available
from Cygnus.  Please see http://sourceware.cygnus.com/cygwin/ for more
information.  But before you get too excited, see the next item.
.H 3 "Windows NT"
Aegis depends on the underlying security provided by the operating
system (rather than re-invent yet another security mechanism).
However, in order to do this, Aegis uses the POSIX \fIseteuid\fP system
call, which has no direct equivalent on Windows NT.  This makes porting
difficult.  Single-user ports are possible (\fIe.g.\fP using Cygwin),
but are not usually what folks want.
.sp
Compounding this is the fact that many sites want to develop their
software for both Unix and Windows NT simultaneously.  This means that
the security of the repository needs to be guaranteed to be handled
in the same way by both operating systems, otherwise one can act as a
\&``back door'' into the repository.  Many sites do not have the same
users and permissions (sourced from the same network register of users)
on both Unix and Windows NT, making the mapping almost impossible even
if the security models did actually correspond.
.sp
Most sites using Aegis and Windows NT together do so by running
Aegis on the Unix systems, but building and testing on the NT
systems.  The work areas and repository are accessed via Samba or
NFS.
.H 2 "Where can I get Aegis?"
Aegis is available by WWW from
.in +4m
.TS
tab(;);
l l s
l l l.
URL:;http://www.canb.auug.org.au/~millerp/
File:;aegis.\*(v).README;# the README file from the tar set
File:;aegis.\*(v).faq;# Frequently Asked Questions
File:;aegis.\*(v).lsm;# description in LSM format
File:;aegis.\*(v).rm.ps.gz;# PostScript of the Reference Manual
File:;aegis.\*(v).tar.gz;# the complete source
File:;aegis.\*(v).ug.ps.gz;# PostScript of the User Guide
.TE
.in -4m
.sp
The above site has a very slow network link to the outside world.
Aegis is also carried by sunsite.unc.edu in its Linux archives.
You will be able to find Aegis on any of its mirrors.
.in +4m
.TS
tab(;);
l l s
l l s
l l l.
Host:;sunsite.unc.edu
Dir:;/pub/Linux/devel/vc
File:;aegis.\*(v).README;# the README file from the tar set
File:;aegis.\*(v).faq;# Frequently Asked Questions
File:;aegis.\*(v).lsm;# description in LSM format
File:;aegis.\*(v).rm.ps.gz;# PostScript of the Reference Manual
File:;aegis.\*(v).tar.gz;# the complete source
File:;aegis.\*(v).ug.ps.gz;# PostScript of the User Guide
.TE
.in -4m
.sp
For those of you without FTP,
I recommend the use of a local ftp-by-email server.
Here is a list of a few (there are many more):
.in +4m
.TS
l l.
ftpmail@cs.uow.edu.au	Australia
ftpmail@grasp.insa-lyon.fr	France
ftpmail@ftp.uni-stuttgart.de	Germany
ftpmail@doc.ic.ac.uk	Great Britain
ftpmail@ieunet.ie	Ireland
ftpmail@decwrl.dec.com	USA
ftpmail@ftp.uu.net	USA
ftpmail@sunsite.unc.edu	USA
.TE
.in -4m
.sp
In general, you can get a help message about how to use each system
by sending email with a subject of "help"
and a message body containing just the word "help".
.H 2 "Is Aegis actively being maintained?"
Yes, Aegis is actively being maintained by the author.
You can contact him by email
.ce 1
Peter Miller <millerp@canb.auug.org.au>
.H 2 "Is there an Aegis mailing list?"
Yes.
Discussion may include,
but is not limited to:
bugs, enhancements, and applications.
The list is not moderated.
.sp
The address of the mailing list is
.e(
aegis-users@canb.auug.org.au
.e)
.sp
.if n DO NOT
.if t \fB Do not\fP
send email to the list if you wish to subscribe.
.sp
To subscribe to this mailing list,
send an email message to \f(CWmajordomo@canb.auug.org.au\fP with
a message body containing the single line
.e(
subscribe aegis-users
.e)
If you have an address which is not readily derived from
your mail headers (majordomo is only a Perl program, after all)
you will need to use a message of the form:
.e(
subscribe aegis-users \fIaddress\fP
.e)
where \fIaddress\fP is an email address to which
you want messages sent.
.sp
The mailing list is archived at eGroups.
The URL is
http://www.egroups.com/list/aegis-users/info.html
and then follow the links.
.sp
The software which handles this mailing list
.if n CANNOT
.if t \fBcannot\fP
send you a copy of \fIAegis\fP.
Please use FTP or ftp-by-email, instead.
.H 2 "How does Aegis compare with program X?"
For all X, ``The author has no experience with X.
If you wish to contribute a comparison between Aegis and X,
it will be considered for addition here.''
.H 1 "Configuration and initial build problems"
Aegis is accompanied by a set of regression tests,
and the BUILDING instructions included in the distribution
detail how to run these tests.
.H 2 "Changing Makefile and common/config.h"
It is a Bad Idea to change the Makefile or the common/config.h file by hand.
This is because much of the work done by the configure script
is inter-related.
.sp
In particular, if you change the C compiler (CC)
you absolutely must do this with the involvement of the configure script.
.H 2 "RCS"
The tests distributed with Aegis use RCS as their history tool.
It is important that you use version 5.6 or later.
.sp
There seems to be a problem with the version of RCS distributed with HP/UX,
even though it claims to be RCS-5.6.0.1.
You will need to get the latest GNU RCS if you are on a HP box.
.H 2 "SCCS"
The tests do not automatically detect that you have SCCS.
You will need to go out and grab RCS even if you already have
SCCS installed at your site.
.H 1 "Testing"
One of the things many sites like about Aegis,
is that it provides mandatory testing.
This enforcement of testing is optional,
and is configurable per-project.
.sp
Please note that even if Aegis' testing framework is
not useful to your project,
the other aspects of Aegis' process still are
(e.g. concurrent development, mandatory reviews, etc.).
.H 2 "Can I use something besides a shell script?"
Yes, the ``test_command'' field of the project config file
may be set to whatever command you like,
see \fIaepconf\fP(5) for more information.
.sp
A shell script is the default,
because you can run anything out of the shell script.
In particular, you can set up a temporary directory
within which to run the tests.
If you ``cd'' into this temporary directory when running tests,
cleanup, no matter what the fallout, even a core dump,
is thus a simple matter of ``rm -rf'' of the temporary directory.
.H 2 "Testing curses programs"
I don't have a curses program tester,
nor do I know of one.
It seems to me that the ``screen'' program contains all the necessary elements,
however additional code would be required to make it a suitable test harness.
.sp
If anyone has found suitable curses testers, even commercial ones,
I would be happy to list (FTP) locations here.
.H 3 "Expect"
Some sites have been using ``expect'' to test curses programs.
You need to be careful about terminal types.
The author is Don Libes <libes@nist.gov>
.sp
expect is available by anonymous FTP from
.in +4m
.TS
tab(;);
l l.
Host:;sunsite.unc.edu
Dir:;pub/Linux/system/Shells
File:;expect-5.12.tgz
.TE
.in -4m
.sp
The author has not personally used this system,
and so can make no comment on it.
.H 2 "Testing X11 programs"
I don't have an X11 program tester,
however several commercial ones seem to be advertised heavily.
.sp
If anyone has found suitable X11 testers, even commercial ones,
I would be happy to list additional (FTP) locations here.
.H 3 "replayXt"
ReplayXt is a library that allows Intrinsics (or Xt) based application
to be executed from a script file.  In particular, applications based
on the Athena and the Motif toolkits can be played.
The author is Jan Newmarch <jan@pandonia.canberra.edu.au>
.sp
replayXt is available by anonymous FTP from
.in +4m
.TS
tab(;);
l l.
Host:;ftp.x.org
Dir:;/contrib/devel_tools
File:;replayXt.README
File:;replayXt.1.1.tar.z
.TE
.in -4m
.sp
The author has not personally used this system,
and so can make no comment on it.
This entry originated from Simon Pickup <simon@adacel.com.au>
.H 2 "Testing embedded systems"
Yes, embedded system can be developed with Aegis.
Naturally,
you will need a suitable cross compiler.
.sp
To test embedded software,
you will need suitable testing hardware:
.sp
1. you will need to be able to (automatically) download the software into
suitable hardware - probably with RAM emulating the ROM of the
distributed product.
.sp
2. you will need to be able to simulate the various inputs
and capture the various outputs,
if you don't want to do manual testing.
.sp
3. you will probably have to write the testing program yourself,
to allow scripting the inputs and outputs.
.sp
4. The gotcha is that in diverting input and output,
you will need to manually test the device drivers, because the tests
will probably not exercise them.
.sp
The author has worked in an environment like this,
and Aegis is definitely intended to be useful in this situation.
.H 2 "Do I really need to test my software?"
No, you do not.
There are alternatives, as this quote demonstrates:
.in +4n
.sp
New York, NJ, Sept. 24 -- People for the Ethical Treatment of
Software (PETS) announced today that seven more software companies
have been added to the group's "watch list" of companies that
regularly practice software testing.
.sp
"There is no need for software to be mistreated in this way so that
companies like these can market new products," said Ken Granola,
spokesperson for PETS.
"Alternative methods of testing these products are available."
.sp
According to PETS,
these companies force software to undergo lengthly and arduous tests,
often without rest for hours or days at a time.
Employees are assigned to "break" the software by any means
necessary, and inside sources report that they often joke about
"torturing" the software.
.sp
"It's no joke," said Granola.
"Innocent programs,
from the day they are compiled,
are cooped up in tiny rooms and 'crashed' for hours on end.
They spend their whole lives on dirty,
ill-maintained computers,
and are unceremoniously deleted when they're not needed anymore."
.sp
Granola said the software is kept in unsanitary conditions and is
infested with bugs.
.sp
"We know alternatives to this horror exist," he said,
citing industry giant Microsoft Corp. as
a company that has become extremely successful
without resorting to software testing.
.in -4n
.sp
If anyone has an accurate attribution for the above quote,
I would like to include it here.
.H 1 "Miscellaneous"
This section contains a whole bunch of things which do not yet belong
anywhere else.
.H 2 "How do you pronounce ``Aegis''?"
There are many alternatives for pronouncing this word,
and all focus on the myriad of sounds available for the "ae" vowel.
Alternatives include: maestro, aerial, algae, etc.
The author has chosen the pronunciation found in the
majority of dictionaries: ee.j.iz.
That is "ee" as in "tree",
a "j" as in "job",
and "iz" as in "prism".
.H 2 "How do I automate the integration queue?"
There is a Perl script distributed with Aegis called \fIaeintegratq\fP(1)
which can be run from \fIcron\fP(1) daily, or whatever.
This Perl script is a good starting point
for customizing automatic integrations.
.sp
Please note that the integration phase also serves to answer the question
``who reviews the reviewers?''
Monitoring review quality is essential to maintain product quality.
Automating the integration queue potentially denies you this quality
opportunity.
.H 2 "How do I enforce coding standards?"
The ``diff_command'' field of the project config file
need not only difference the file,
it can also be overloaded to do other things.
If the difference command fails
for any source file,
the change may not leave the being developed state.
.sp
For example,
if you wanted to check that line lengths were always 80 characters or less,
you could run the hypothetical ``cklinlen'' command
at diff time, using
.e(
diff_command = "cklinlen $in && fcomp -w -s $orig $in -o $out";
.e)
Checking other coding standards are also possible
using the same basic method.
.H 2 "How do I get dates printed before and after build commands?"
Just as the diff_command file of the project config file
can be extended, so can the build_command field.
.e(
build_command = "set +e; date; cook ...; x=$?; date; exit $x";
.e)
You need to be careful about the \f(CW-e\fP flag,
because Aegis invokes the shell to run
the commands with the \f(CW-e\fP option,
to abort after the first error.
.sp
You may want to upgrade to Aegis 3.0.
In this version, the times are automatically printed as part of the
verbose commencement and completion messages.
.H 2 "How do I stop Aegis automatically merging?"
The merging behavior is controlled by the ``diff_preference'' field
of the user config file.
See \fIaeuconf\fP(5) for more information.
There are also three command line options
to the \fIaed\fP(1) command which can override the preferences,
see \fIaed\fP(1) for more information.
.sp
To stop the automatic merging, add the line
.e(
diff_preference = no_merge;
.e)
to the .aegisrc file in your more directory.
To specifically perform a merge after that,
you will need to use the ``aed -merge_only'' command.
There is an ``aem'' alias for your convenience.
.H 2 "How do I modify which developer is assigned to a change?"
There have been times when we have one developer
working on a change and,
for one reason or another,
we need assign that change to different developer
before the change is at a point where it can be integrated.
Is there a way to tell Aegis
that a new developer has been assigned to the change so that it would
change files permissions accordingly?
(My thanks to Mark Meuer <markm@endo.com> for this question.)
.sp
Yes, you need to use the \fIaechown\fP(1) command.
This command may be run by a project administrator
to reassign a change to a different developer.
Because \fIchown\fP(2) does not work over NFS,
a new development directory owned by the new developer is created,
and the change files are copied,
before the old development directory is deleted.
.H 2 "Do I have to type all the config examples in the User Guide?"
No, you do not.
The lib/config.example directory contains a number of files
with the config command from the User Guide ready for inserting into your
project config file.
.H 2 "Is there a way to recreate a previous baseline?"
For example, let's say we have shipped one version to
a customer and since then made 30 changes to the baseline.
When the customer calls in with a failure report that we can't reproduce,
how can I easily rebuild the baseline from 30 changes ago to help track
down the error?
.sp
Yes, it is possible to recreate a previous baseline.
You need to follow these steps:
.sp
1. Determine which delta was shipped to the customer.
This is easiest if you embed the version supplied by Aegis
into your executables at build time.
.sp
2. Create a change a change (you want to fix the bug, right?)
and start developing it.
.sp
3. Copy all of the project files into the change,
using the delta number determined in step 1.
Use these commands:
.e(
aecd
aecp . -delta N
.e)
where N is the delta number from the first step.
Files created since the delta will be copied into your change as empty files,
leave them alone for a while.
.sp
Note that you need Aegis 2.3 for directory copying to work correctly.
Earlier versions will need to use
.e(
aecd
aecp `aegis -list project_files -terse` -delta N
.e)
Note the backward quotes.  The above can be abbreviated,
its just long so you can see what it is doing.
.sp
4. Build the change as normal.
This will completely rebuild the version sent to the customer.
Note that a number of things are beyond Aegis' scope,
like operating system updates and compiler updates.
These can have an effect in accurately reproducing what was
sent to the customer.
.sp
5. Find the bug and fix it, as you would normally do.
.sp
5. Merge the change.
This will bring the files up to the most recent version,
and merge the bug fix with the current version.
.sp
6. You can now uncopy all of the files which are unchanged.
Aegis provides a fast way to do this
.e(
aecpu -unchanged
.e)
This command behaves like aecpu, but it goes hunting for files which
are the same between the baseline and the development directory.
Note that you must do this step after the merge.
.H 2 "How do I stop it using the pager?"
Aegis automatically redirects the output of listing and help into
the pager program described in the $PAGER environment variable,
or \fImore\fP if not set.
This is only done if aegis is running in the foreground
and the output is a terminal.
.sp
The simplest way to stop the use of the pager is to pipe the output through cat.
A more elegant method is to use the -No_Pager option.
.sp
If you want to permanently disable the pager,
set the following line in your \f(CW.aegisrc\fP file:
.e(
pager_preference = never;
.e)
If you want to use the pager now, you will need to use the -PAGer option.
.H 2 "Why does develop end complain about builds?"
Why does aede complain that
"this change must successfully complete an 'aegis -Build'
before it can end development"
but I have just done a successful build?
.sp
There are two possibilities:
time stamps and architectures.
.H 3 "Build Time Stamps"
Aegis tracks time stamps on files and builds, etc,
to determine when files are out of date.
If time clocks on various networked machines disagree,
it is possible for Aegis to conclude that a file or files
are logically out of date.
.sp
This problem is mentioned in the User Guide.
Essentially, you need to install NTP or XNTP.
If you can't do that,
run \fIrdate\fP(1) on your client machines from cron,
to sync their clocks with the file server's clock.
.H 3 "Build Architectures"
The ``aede'' can also complain about builds when
you have changed the architecture field
of the project "config" file,
but have not yet updated the change's attributes to match.
This can also happen when a separate change updates the architecture
field, and all existing changes suddenly get this mystery error.
.sp
It happens because the default architecture is "unspecified"
in the change attributes (use ``aeca -l'' to take a look).
When the config file changes, the required architecture,
according to the change's attributes, is still "unspecified".
To fix, use ``aeca -e'' and edit the change's attributes
to match the architecture names in the "config" file.
.sp
You may wish to upgrade to version 3.0,
which checks for this, and prints a suitable error message,
with a suggestion to edit either the project ``config'' file
or the change attributes.
.H 1 "Internationalization"
This section discusses a number of issues surrounding internationalization,
and the effect it has has upon Aegis and its error messages.
.H 2 "Say What?"
Internationalization is the process of modifying code so that it may produce
messages in the native language of the user.
A data file is supplied for each supported language,
containing the strings
to be substituted for error messages and other text produces by a program.
.H 2 "So why are the error messages So Bad, now?"
There is a set of default error messages in the code itself.
These error messages are used if the localization file
cannot be found, or if the message is absent from the localization
file for some reason.
These messages tend to be in the ``programmer cryptic'' language,
and the English localization has probably not been installed correctly.
The English localization
.if n *needs*
.if t \fIneeds\fP
to be installed.
.sp
There is also a small, slight, tiny (cough)
possibility that the necessary code changes have
introduced bugs into some error reporting.
(And we need bugs there like we need a third arm pit.)
Please report any problems immediately to the author.
.H 2 "What controls which language is used?"
There are a range of environment variables, depending on your operating system.
The most common is the LANG environment variable.
The default is ``en'' (for English) if nothing is specified.
.H 2 "What localizations are available?"
Only English is available at this writing.
.sp
More may become available if there are any generous bilingual
Aegis users out there,
who want to provide a localization file in another language.
.H 2 "So can I change the text of error messages?"
Yes, you can, but it is not advised.
Seriously.
(I'm going to regret admitting this,
so I'm not going to tell you how.)
If you have suggestions for improving error messages,
please email them to the author.
.H 1 "Branches"
This section discusses a number of issued surrounding branching.
.H 2 "What is a Branch?"
Aegis treats branches as ``big changes''.  This allows much of Aegis'
development model be be applied unchanged, but still allow the development
of projects to be broken down into fine grained pieces, or aggregated
into large ``release sized'' chunks.
.H 2 "What is an Anabranch?"
Aegis' branches can end.  This is a consequence of treating branches as
``big changes''.  Logical places to end branches are times like when a
release of the software is made.  The geographic term for a stream which
breaks off and rejoins downstream is an anabranch.
.sp
Because branches can end, combined with the fact that branches are
``big changes'', this means that you use ``aede'' to end development
of the branch.  After that, it is just like any other change on its
parent branch.
.H 2 "Do branches have to end?"
No.  You are not required to end development of a branch, just as you
are not required to end development of a change.  In particular, the
project trunk is an unnumbered branch which never ends.  How you manage
your project is up to you.
.H 2 "Why are branches called projects?"
In order for the branches to be ``big changes'', there are times when you
will refer to the branch as a change to its parent project.  In order
for branches to have changes, there are times when you will refer to
them as a project.
.sp
The conversion between the two is intended to be simple.  When you need to
refer to a branch in its project role, join the branch's parent project
name to the branch's number with a dot;
\fIe.g.\fP ``-p aegis.1.2''.
When you need to refer to a branch in its change role, separate the
branch's project name from the branch's number at the last dot;
\fIe.g.\fP ``-p aegis.1 -c 2''.
.H 2 "Why must aed be used when integrating a branch?"
Because branches are ``big changes'' and follow \fIall\fP of the things
a change must do, including aed.  The only time a branch is writable is
at integration time for a change on that branch.  Thus, the aed for the
branch is done between aeib and aeipass.  The trunk doesn't require it,
because you never say aede to the trunk.
.H 2 "How come the branch baseline is incomplete?"
The branch baseline is the development directory for the ``big change''
represented by the branch.  Just as a developers development directory
only contains the things being worked on, and their implications, so
does the branch baseline.
.sp
This means that wherever you specify a search path (-I, VPATH, \fIetc\fP)
to look first in your development directory and then in the baseline,
it must also look in each of the branch's ancestors' baselines.
Aegis provides a ``$search_path'' substitution telling you where to
search; this is usually used in the ``build_command'' field of
the project \fIconfig\fP file.
.sp
The ``aefind'' command may also be used to perform actions similar to
use usual Unix find(1), but across the Aegis search path.
.\"
.\" This is the end of the digest.
.\" All contents must be before this point.
.\"
.sp
\*[sep]
.sp
End of aegis.\*(v).faq Digest
.br
***************************
