Subject: Aegis Frequently Asked Questions (FAQ) From: Peter Miller Newsgroups: comp.software-eng,comp.software.config-mgmt,comp.software.testing,comp.sources.d,alt.sources.d Submitted-by: Peter Miller 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 ------------------------------ 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 aegis-users@agso.gov.au DO NOT send email to the list if you wish to subscribe. To subscribe to this mailing list, send an email message to majordo- mo@agso.gov.au 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 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 ------------------------------ 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 ***************************