Subject: Aegis Frequently Asked Questions (FAQ)
From: Peter Miller <[email-masked]>
Newsgroups: comp.software-eng,comp.software.config-mgmt,comp.software.testing,comp.sources.d,alt.sources.d

Submitted-by: Peter Miller <[email-masked]>
Archive-name: aegis.2.3/FAQ

This  message  contains  answers to a number of frequently asked ques-
tions about Aegis.  If you don't know what Aegis is, read on.

Suggestions for additions or improvements to this FAQ  are  most  wel-
come.

			       Contents
1.   What is Aegis?
1.1.   What operating systems are supported?
1.2.   Where can I get Aegis?
1.3.   Is Aegis actively being maintained?
1.4.   Is there an Aegis mailing list?
1.5.   How does Aegis compare with program X?
2.   Configuration and initial build problems
2.1.   Changing Makefile and common/congig.h
2.2.   RCS
2.3.   SCCS
3.   Testing
3.1.   Can I use something besides a shell script?
3.2.   Testing curses programs
3.3.   Testing X11 programs
3.3.1.   replayXt
3.4.   Testing embedded systems
4.   Miscellaneous
4.1.   How do you pronounce ``Aegis''?
4.2.   How do I automate the integration queue?
4.3.   How do I enforce coding standards?
4.4.   How do I get dates printed before and after build commands?
4.5.   How do I stop Aegis automatically merging?
4.6.   Do I have to type all the config examples in the User Guide?
4.7.   Is there a way to recreate a previous baseline?

----------------------------------------------------------------------

Subject: 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  inte-
grating these changes back into the master source of the program, with
as little disruption as possible.

For a more complete description, see  the  README  file  or  the  User
Guide.  Both are available from the anonymous FTP site (see below).

------------------------------

Subject: 1.1.  What operating systems are supported?

Aegis  will  run on almost any version of UNIX.  The distribution con-
tains a configure script generate by GNU autoconf  to  adapt  to  your
site.

There  is no Aegis port to OS/2, MS-DOS or VMS.  The author has no ex-
pertise 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.

------------------------------

Subject: 1.2.  Where can I get Aegis?

Aegis is available by anonymous FTP from
	   Host:   ftp.nau.edu
	   Dir:    /pub/Aegis
	   File:   aegis.2.3.README
	   File:   aegis.2.3.tar.gz   # the complete source
	   File:   aegis.2.3.ps.gz    # the User Guide
	   File:   aegis.2.3.faq      # this FAQ list

------------------------------

Subject: 1.3.  Is Aegis actively being maintained?

Yes, Aegis is actively being maintained by the author.  You  can  con-
tact him by email
		  Peter Miller <[email-masked]>

------------------------------

Subject: 1.4.  Is there an Aegis mailing list?

Yes.   Discussion  may  include, but is not limited to: bugs, enhance-
ments, and applications.  The list is not moderated.

The address of the mailing list is
	[email-masked]

DO NOT send email to the list if you wish to subscribe.

To subscribe to this mailing list, send an email message  to  majordo-
[email-masked] with a message body containing the single line
	subscribe aegis-users
Please  note  that  agso.gov.au is an Internet site, so 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:
	subscribe aegis-users address
where address is an email address which makes sense from  an  Internet
site.

The software which handles this mailing list CANNOT send you a copy of
Aegis.  Please use FTP or ftp-by-email, instead.

------------------------------

Subject: 1.5.  How does Aegis compare with program X?

For all X, ``The author has no experience with X.  If you wish to con-
tribute  a  comparison  between Aegis and X, it will be considered for
addition here.''

------------------------------

Subject: 2.  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.

------------------------------

Subject: 2.1.  Changing Makefile and common/congig.h

It is a Bad Idea to change the Makefile or the common/config  file  by
hand.   This  is because much of the work done by the configure script
in inter-related.

In particular, if you change the C compiler (CC) you  absolutely  must
do this with the involvement of the configure script.

------------------------------

Subject: 2.2.  RCS

The tests distributed with Aegis use RCS as their history tool.  It is
important that you use version 5.6 or later.

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.

------------------------------

Subject: 2.3.  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.

------------------------------

Subject: 3.  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 pre-project.

Please note that even if Aegis' testing framework  is  not  useful  to
your project, the other aspects of Aegis' process still are (e.g. con-
current development, mandatory reviews, etc.).

------------------------------

Subject: 3.1.  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 aepconf(5) for more information.

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 di-
rectory 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.

------------------------------

Subject: 3.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.

If  anyone  has found suitable curses testers, even commercial ones, I
would be happy to list (FTP) locations here.

------------------------------

Subject: 3.3.  Testing X11 programs

I don't have an X11 program tester, however  several  commercial  ones
seem to be advertised heavily.

If  anyone  has  found  suitable  X11 testers, even commercial ones, I
would be happy to list additional (FTP) locations here.

------------------------------

Subject: 3.3.1.  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 <[email-masked]>

replayXt is available by anonymous FTP from
		     Host:   ftp.x.org
		     Dir:    /contrib/devel_tools
		     File:   replayXt.README
		     File:   replayXt.1.1.tar.z

The  author  has  not  personally used this system, and so can make no
comment  on  it.   This  entry  originated  from  Simon  Pickup   <si-
[email-masked]>

------------------------------

Subject: 3.4.  Testing embedded systems

Yes,  embedded system can be developed with Aegis, Naturally, you will
need a suitable cross compiler.

To test embedded software, you will need suitable testing hardware:

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.

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.

3.  you  will  probably have to write the testing program yourself, to
allow scripting the inputs and outputs.

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.

The author has worked in an environment like this, and Aegis is  defi-
nitely intended to be useful in this situation.

------------------------------

Subject: 4.  Miscellaneous

This  section contains a whole bunch of things which do not yet belong
anywhere else.

------------------------------

Subject: 4.1.  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, encyclopaedia, 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".

------------------------------

Subject: 4.2.  How do I automate the integration queue?

There  is  a  shell  script  in  the  aegis library directory (usually
/usr/local/lib/aegis/integrate_q.sh) which can  be  run  from  cron(1)
daily,  or  whatever.   This shell script is a good starting point for
customising automatic integrations.

Please note that the integration phase also serves to answer the ques-
tion  ``who reviews the reviewers?''  Monitoring review quality is es-
sential to maintain product quality.

------------------------------

Subject: 4.3.  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 files for any source file, the change  may  not
leave the being developed state.

For  example,  if you wanted to check that line lengths were always 80
characters or less, you could run the hypothetical  ``cklinlen''  com-
mand at diff time, using
	diff_command = "cklinlen $in && fcomp -w -s $orig $in -o $out";
Checking other coding standards are also possible using the same basic
method.

------------------------------

Subject: 4.4.  How do I get dates printed before and after build  com-
	mands?

Just  as  the  diff_command file of the project config file can be ex-
tended, so can the build_command field.
	build_command = "set +e; date; cook ...; x=$?; date; exit $x";
You need to be careful about the -e flag, because  Aegis  invokes  the
shell to run the commands with the -e option, to abort after the first
error.

------------------------------

Subject: 4.5.  How do I stop Aegis automatically merging?

The merging behaviour is controlled by the  ``diff_preference''  field
of  the user config file.  See aeuconf(5) for more information.  There
are also three command line options to the aed(1)  command  which  can
override the preferences, see aed(1) for more information.

To stop the automatic merging, add the line
	diff_preference = no_merge;
to  the .aegisrc file in your more directory.  To specifically perform
a merge after that, you will need to use the ``aed -merge_only''  com-
mand.

------------------------------

Subject:  4.6.   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 inserying
into your project config file.

------------------------------

Subject: 4.7.  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 re-
build the baseline from 30 changes ago to help track down the error?

Yes,  it  is  possible  to reacreate a previous baseline.  You need to
follow these steps:

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.

2. Create a change a change (you want to fix  the  bug,  right?)   and
start developing it.

3. Copy all of the project files into the change, using the delta num-
ber determined in step 1.  Use these commands:
	aecd
	aecp . -delta N
where N is the delta number from the first step.  Files created  since
the  delta  will  be  copied into you chage as empty files, leave them
alone for a while.

Note that you need Aegis 2.3 for directory copying to work  correctly.
Eariler versions will need to use
	aecd
	aecp `aegis -list project_files -terse` -delta N
Note the backward quotes.  The above can be abbreviated, its just long
so you can see what it is doing.

4. Build the change as normal.  This will completely rebuild the  ver-
sion  sent  to  the customer.  Note that a number of things are beyonf
Aegis' scope, like operating  system  updates  and  compiler  updates.
These  can  have  an effect in accurately reproducing what was sent to
the customer.

5. Find the bug and fix it, as you would normally do.

5. Merge the change.  This will bring the files up to the most  recent
version, and merge the bug fix with the current version.

6. You can no uncopy all of the files which are unchanged.  Aegis pro-
vides a fast way to do this
	aecpu -unchanged
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.

------------------------------

End of aegis.2.3.faq Digest
***************************