readme(aegis) readme(aegis) NAME aegis - project change supervisor Copyright (C) 1990, 1991, 1992, 1993, 1994 Peter Miller. All rights reserved. The aegis program is distributed under the terms of the GNU General Public License. See the LICENSE section, below, for more details. aegis (ee.j.iz) n., a protection, a defence. DESCRIPTION The aegis program is a CASE tool with a difference. In the spirit of the UNIX Operating System, the aegis program is a small component designed to work with other programs. Many CASE systems attempt to provide everything, from bubble charts to source control to compilers. Users are trapped with the components supplied by the CASE system, and if you don't like one of the components (it may be too limited, for instance), then that is just tough. In contrast, UNIX provides many components of a CASE system - compilers, editors, dependency maintenance tools (such as make), source control tools (such as RCS). You may substitute the tool of your choice if you don't like the ones supplied with the system - gcc, jove, cake, to name just a few. The aegis program adds to this list with software configuration management, and true to UNIX philosophy, the aegis program does not dictate the choice of any of the other tools (although it may stretch them to their limits). Enough hype, what is it that the aegis program does? Just what is software configuration management? This question is sufficiently broad as to require a book in answer. In essence, the aegis program is a project change supervisor. It provides a framework within which a team of developers may work on many changes to a program independently, and the aegis program coordinates integrating these changes back into the master source of the program, with as little disruption as possible. Resolution of contention for source files, a major headache for any project with more than one developer, is one of the aegis program's major functions. It should be noted that the aegis program is a developer's tool, in the same sense as make or RCS are developer's tools. It is not a manager's tool - it does not provide progress tracking or manage work allocation. 1 readme(aegis) readme(aegis) BENEFITS So why should you use the aegis program? The aegis program uses a particular model of the development of software projects. This model has a master source (or baseline) of a project, and a team of developers creating changes to be made to this baseline. When a change is complete, it is integrated with the baseline, to become the new baseline. Each change must be atomic and self-contained, no change is allowed to cause the baseline to cease to work. "Working" is defined as passing it's own tests. The tests are considered part of the baseline. The aegis program provides support for the developer so that an entire copy of the baseline need not be taken to change a few files, only those files which are to be changed need to be copied. In order to ensure that changes are unable to cause the baseline to cease to work, aegis mandates that changes be accompanied by at least one test, and that all such tests be known to complete successfully. These steadily accumulated tests form an ever increasing regression test suite for all later changes. There is also a mandatory review stage for each change to the baseline. While these requirements may be relaxed per-change or even per- project, doing so potentially compromises the "working" definition of the baseline. The win in using the aegis program is that there are O(n) interactions between developers and the baseline. Contrast this with a master source which is being edited directly by the developers - there are O(n!) interactions between developers - this makes adding "just one more" developer a potential disaster. Another win is that the project baseline always works. Always having a working baseline means that a version is always available for demonstrations, or those "pre- release snapshots" we are always forced to provide. The above advantages are all very well - for management types. Why should Joe Average Programmer use the aegis program? Recall that RCS provides file locking, but only for one file at a time. The aegis program provides the file locking, atomically, for the set of files in the change. Recall also that RCS locks the file the instant you start editing it. This makes popular files a project bottleneck. The aegis program allows concurrent editing, and a resolution mechanism just before the change must be integrated, meaning fewer delays for J.A.Programmer. 2 readme(aegis) readme(aegis) NEW IN THIS RELEASE A number of features have been added to aegis with this release. A few of them are detailed here: This release of Aegis provides 3 of the most commonly requested features: support for heterogeneous development, support for a greater range of DMTs, support for user-defined reports. * Aegis now supports heterogeneous development. Now you can be sure that your project not only always builds and tests sucessfully, but that it does so across a configurable set of system or hardware architectures. See the Heterogeneous Development secion of the Tips and Traps chapter of the User Guide for more information. * Aegis can now cope with a wider range of Dependency Maintenance Tools (DMTs). It now has the ability to fill development directories with symbolic links to all files in the baseline which are not present in the development directory. This allows DMTs to assume all files are present below the current directory, allowing DMTs such as cake and GNU Make to be used. See the Dependency Maintenance Tool section of the User Guide and aeb(1) for more information. * Aegis now has a report generator, so you can create your own reports. Many "canned" reports are included in this distribution; of particular interest to many will be the File_Activity report, which details currently active files. See aer(1) for more information. * Aegis is now configured using a shell script called configure, distributed with the package. This shell script is generated using GNU Autoconf. See the BUILDING file for more information. * The AEGIS environment variable has been renamed AEGIS_PATH, to bring it in line with the AEGIS_PROJECT and AEGIS_CHANGE environment variable names. The old name will keep working for some time, but aegis will warn you. * Filename lengths are now configurable. The 14 character portability limit is still the default, but a higher limit is configurable for each project, up to the filesystem filename limit. See aepconf(5) for more information. * It is now possible to specify that filenames must be within the minimum character set mandated by POSIX. The default is as before, to allow any printing character. See aepconf(5) for more information. 3 readme(aegis) readme(aegis) * Limits on the length of project names have been relaxed. Project names are now only limited by the filesystem filename limit. * It is now possible to specify the command to run tests, allowing a project to use a specialized test facility, rather than be forced to use shell scripts. See aet(1) and for more information. * The commands which accept the -Edit now preserve the edited text in the event of a failure. * The commands which delete files now accept a -Interactive option, which causes them to prompt the user for confirmation of file deletion. This can be made the default by an appropriate setting of the aliases or individual users preferences files. See aenfu(1), aentu(1), aecpu(1), and aeuconf(5) for more information. * The aecp(1) command now accepts directory names, allowing whole directory trees to be copied into a change. The aecpu(1) command now has a -UNChanged option which allows the unchanged files to be uncopied. * The aeb command now accepts file names, allowing partial builds to be performed. See aeb(1) for more information. * There is a new aechown(1) command to facilitate reassigning the developer of a change which is in the being developed state. * It is now possible for project administrators to assign changes to specific developers. See aedb(1) for more information. Plus the usual crop of bug fixes and tinkering. For excruciating detail, and also acknowledgements of those who generously sent me feedback, please see the aux/CHANGES.2.2 file included in this distribution. ARCHIVE SITE The latest version of aegis is available by anonymous FTP from: Host: ftp.agso.gov.au Dir: /pub/Aegis File: aegis.2.2.tar.Z # the complete source File: aegis.2.2.patch.Z # patch to take 2.1 to 2.2 File: aegis.2.2.ps.Z # PostScript of the User Guide To use anonymous FTP, give "anonymous" as the user name (omit the quotes) and your email address as the password. This directory also contains a few other pieces of software written by me. Some are referred to in the aegis documentation. Please have a look if you are interested. For those of you without FTP, I recommend the use of an ftp-by-email server. Here is a list of a few (there are many more): ftpmail@decwrl.dec.com ftpmail@cs.uow.edu.au 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". MAILING LIST A mailing list has been created so that users of aegis may exchange ideas about how to use the aegis program. Discussion may include, but is not limited to: bugs, enhancements, and applications. The list is not moderated. The address of the mailing list is aegis-users@bmr.gov.au To subscribe to this mailing list, send an email message to majordomo@bmr.gov.au with a message body containing the single line subscribe aegis-users Please note that bmr.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 the aegis program. Please use FTP or ftp- by-email, instead. BUILDING Instructions on how to build and test the aegis program are to be found in the BUILDING file included in this distribution. SOME HISTORY The idea for aegis did not come full-blown into my head in the shower, as some of my programs do, but rather from working in a software shop which used a simplistic form of something similar. That system was held together by chewing-gum and string, it was written in a disgusting 5 readme(aegis) readme(aegis) variant of Basic, and by golly the damn thing worked (mostly). The aegis program is nothing like it, owes none of its code to that system, and is far more versatile. Since that company decided to close down our section, we all moved on simultaneously (all 60 of us), sometimes working together, and sometimes not, but always keeping in touch. With suggestions and conversations with some of them early in 1990, the manual entries for aegis took shape, and formed most of the design document for aegis. Since getting the first glimmerings of a functional aegis late in 1990 it is increasingly obvious that I never want to be without it ever again. All of my sources that I modify are instantly placed under aegis, as is anything I distribute. All code I write for myself, and all new code I write for my employer, goes under aegis. Why? Because it has fewer bugs! Example: one of the sources I carry with me from job to job is "cook", my dependency maintenance tool. Cook had existed for 3 years before aegis appeared on the scene, and I used it daily. When I placed cook under aegis, I found 6 bugs! Since then I have found a few more. Not only are there now fewer bugs, but they never come back, because the regression test suite always grows. LICENSE The aegis 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. The aegis 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., 675 Mass Ave, Cambridge, MA 02139, USA. It should be in the LICENSE file included in this distribution. AUTHOR Peter Miller UUCP uunet!munnari!bmr.gov.au!pmiller /\/\* Internet pmiller@bmr.gov.au 6