Description

This is a template Aegis project. It provides a general and robust framework from which a great number of projects may be formed.

If you want to get started using Aegis, this provides a simple and rapid way of setting-up a project.

Download

This template project is distributed in the form of an aedist change set, a special way of packaging an Aegis change.

The project template is in a file called example-make-rcs.ae and usually obtained from http://aegis.sourceforge.net/ (or one of its mirrors) using your favorite web browser.

Assumed Environment

In order to follow these instructions, there are several software packages you will need.

It is assumed that you have downloaded and installed Aegis according to the instructions. If you haven't, you need to before you can proceed. (You need Aegis 4.20 or later.)
It is a really really good idea to print a copy of the Aegis User Guide (which describes how Aegis works and how it is used) and the Aegis Reference Manual (which contains all of the man pages). Keep them handy as you work through these instructions, especially if this is your first time.
It is assumed that you have downloaded and installed GNU make according to the instructions.
It is assumed that you have downloaded and installed Bison according to the instructions. (This is optional if your system already as a yacc of some sort.)
It is assumed that you have downloaded and installed Flex according to the instructions. (This is optional if your system already as a lex of some sort.)
It is assumed that you have downloaded and installed RCS according to the instructions.
It is assumed that you have downloaded and installed fhist according to the instructions. (This is optional if you already have a human-friendly whole-file-as-context diff of some sort.)
It is assumed that your account is configured appropriately. In particular, you need access to the Aegis aliases. If the command ``ael p'' gives the error "ael: command not found", then you probably need to add the line
```
. /usr/local/lib/aegis/profile
```
to the .profile file in your home directory, and reboot. (The actual path may vary, depending on where you installed Aegis.) Many Linux systems do this automagically, by adding a suitable symbolic link at /etc/profile.d/aegis.sh

Creating the Repository

For the best results, as this protects against the greatest number of kinds of accidents, you are recommended to create a separate user account for your repository. Usually, this account has the same name as your project. These instructions assume a user account called ``example'' and a project also called ``example.''

As the example user, you need to execute the following commands. The typical response is shown here also. The first command creates the project.

% aenpr example
aegis: project "example": created
aegis: project "example.1": created
aegis: project "example.1.0": created
%

The next command adds your normal login as a project administrator, and other development roles. (Your normal login as assumed to be ``you'' for this example.)

% aena -p example.1.0 you
aegis: project "example.1.0": user "you" is now an administrator
% aend -p example.1.0 you
aegis: project "example.1.0": user "you" is now a developer
% aenrv -p example.1.0 you
aegis: project "example.1.0": user "you" is now a reviewer
% aeni -p example.1.0 you
aegis: project "example.1.0": user "you" is now an integrator
%

The .forward file of the ``example'' user needs to be set to someone appropriate to read mail directed at the project.

You can now ask your system administrator to set the ``example'' user's password field to ``*''. This effectively prevents the ``example'' user from logging in. Aegis is designed to make this unnecessary from now on.

The rest of the commands may be executed under your usual account. By adding your normal account as an administrator, you are now authorized to perform the necessary actions.

You can set a short-cut to the project you are interested in by using the ae_p command to set the AEGIS_PROJECT environment variable:

% ae_p example.1.0
%

You need to edit the project attributes to reflect your needs. The project attributes are edited using the following command

% aepa -e
...you are placed into the editor...
%

You will be placed into an editor (controlled by the VISUAL environment variable, or ``vi'' if it isn't set). You need to edit the attributes file to look like this:

description = "an example project";
developer_may_review = true;
developer_may_integrate = true;
reviewer_may_integrate = true;
developers_may_create_changes = true;
umask = 022;

You should set the description to something appropriate for you project (be very careful about the end quote and semicolon). You will also notice that the staff roles are set for a single-person project. When you decide to tighten things up, you should start by setting developer_may_review = false.

The project is now ready for adding the template project change set you downloaded.

If you need to add more staff to the project, because your normal account is an authorized project administrator, use the aend (et al) commands to do this from your normal account.

Apply the Change-set

The downloaded change set is applied using the following command

% aedist --receive -f example-make-rcs.ae -p example.1.0
...lots of output...
%

You must give the project name on the command line, or aedist will try to use the project name it finds in the change set - and it wont find it.

The aedist command will, in turn, issue a number of other commands. These are all normal Aegis commands you could issue yourself, if you were familiar with Aegis. It will, however, stop with a moderately alarming message:

Warning: This change contains files which could host a Trojan horse attack. You should review it before building it or testing it or completing development. This change remains in the being_developed state.

This message comes because in order to build the project, you are going to have to execute a number of commands contained in the project "config" file, and in the "Makefile" file. For your own protection, aedist stops at this point. You may want to inspect these two files before continuing.

In order to complete development of the change set, you must first build it...

% aecd
% aeb
...you will see commands which build the project...
%

Things that can go wrong...
If you don't have GNU Make installed, the build command (aeb) will fail. If you have GNU Make installed as ``gmake'' you need to edit the build_command field of the config file to know this.
If you don't have GNU bison installed, you need to edit the Makefile to use yacc instead. Look for ``Section: Using Yacc'', and use the commented-out assignment.
If you don't have GNU Flex installed, you need to edit the Makefile to use lex instead. Look for ``Section: Using Lex'', and use the commented-out assignments.
Once the change builds, you need to difference it (this is a little redundant for this first command, but you'll see how useful it is later).
% aed ...you will see commands which "diff" the project... %

Things that can go wrong...
If you don't have the fhist package installed, the difference (aed) will fail. The fcomp command it is looking for is a whole-file context difference command (the GNU diff -c is a bit too terse for humans). You can edit the config file and replace the \fIdiff_command\fP field if you are confident.
Now you will need to test the change. This is because this change set includes a number of tests for the example programs. They give you an idea of what is meant to happen when developing software using Aegis - none of the tests should fail.
% aet ...lots of output... % aet -bl ...lots of output... %

The change is now ready to end development.
% aede aegis: project "example.1.0": change 10: development complete %

The change set is now ready to be reviewed. In a single-person project like this one, you can review your own work. Obviously this is a conflict of interest, and larger projects are usually configured to have Aegis prevent this.
% aerpass -p example.1.0 -c 10 aegis: project "example.1.0": change 10: review pass %

The change is now ready to be integrated. Only when integration is complete are the files actually committed to the repository.
% aeib -p example.1.0 -c 10 % aeb ...you will see commands which build the project... % aed ...you will see commands which "diff" the project... % aet ...lots of output... % aet -bl ...lots of output... % cd % aeipass ...you will see commands committing the files to RCS... aegis: project "example.1.0": change 10: integrate pass %

The ``cd'' command you see is actually important: you need to be out of the development directory and integration directory so that they can be cleaned up (deleted) when the change completes.
Where to from here
If you go this far, your example project is ready for use.
It is strongly suggested that you complete the first change ``as is'' and perform your own customizations in later changes, rather than trying to get the project started and customize it at the same time.
The rest of this file describes how to perform various common changes to the example project.
Directory Structure
Now that the example project is in a fit state to be worked on, you will need to know where it expects things to be parked.
The directory structure as it presently stands looks something like this (only primary source files are shown):
Makefile include/ version.h lib/ name1/ source1.c version.c name2/ source2.c man/ man1/ progA.1 progB.1 prog/ progA/ main.c progB/ main.c
In addition, the compiled executables are placed under the ``bin'' directory. This permits, for example, adding the bin directory from the baseline to your command search PATH environment variable.
When a development directory is created for an Aegis change, it is initially populated with symbolic links into the baseline. Thus, it looks like your development directory contains all of the baseline files, with exactly the same directory structure. However, if you try to edit any of them, you will be told "Permission denied".
In order to modify a file, you need to work on a copy, obtained via Aegis using the ``aecp'' command (named after the "cp" command). This way Aegis knows which files you are modifying.
Similarly, you create new files using the ``aenf'' command (it's mnemonic). Again, this way Aegis knows which files you are creating.
Whole Project Builds
The method used to build the project is to perform ``whole project'' builds. It does not use the ``recursive'' make technique. For an explanation of advantages of the whole project build concept, you may want to read the Recursive Make Considered Harmful paper.
Adding New Programs
This section assumes that you have taken the initial change set for this template project through to completion, rather than trying to do everything at once. This is important, because some of the instructions below will fail if this isn't the case.
In order to add a new program, you must do two things.
Three things actually, but everything in Aegis is done within a change, so I won't mention it again. You create a change and begin development of it using the aenc and aedb commands. You go to the newly-created work area using the aecd command.

You need to add the source files of your new program, using the ``new file'' Aegis command. If the program were called "fred" then you would say
% aenf prog/fred/main.c %
or similar. There could be many .c and .h files, and you should create them all. Using your favorite editor, set their contents appropriately. (I'm guessing you have a particular already-working program you are experimenting on.)

You need to edit the Makefile to tell it about the new program. You do this by copying it into your change
% aecp Makefile %
and then editing it with your favorite text editor. Look for the ``Section: Programs'' line. You will need to add a line for your new program. It will look something like this

bin/fred: $(patsubst %.c,%.o,$(filter prog/fred/%.c,$(source_files)))

Notice how "fred" appears twice on this line. This says that all .c files below the prog/fred directory are to be compiled and linked together. Thus, it will adapt to new source files being added or removed, without further modification of the Makefile.
You also need to add the name of the new program to the
programs = ... fred
line, otherwise it will not be added to the list of programs to make. As you can see, all of this could be automated if only make had a richer input language.
Using the project structure provided by this Aegis project template you can't have the sources to two separate programs in the one directory. If you have two programs with a common portion, see the libraries section, below, for how to manage the common portion.
Aegis wants to know if your program builds, and so it watches the exit status of the make command. To build your new program, it is only necessary to use the
% aeb aegis: make -f makefile project=example.1.0 change=11 ...lots of output... aegis: project "example.1.0": change 11: development build complete %
command. This will compile all of the modules and link them to produce the new program. You will find the executable in the ``bin'' directory.
You may also want to add a test of your new program. This is optional, but it is one of the strengths of the Aegis process.
All that is left is to complete development of the change and to integrate it, using the normal Aegis process.
Adding New Program Modules
If you need to add another module (often a .c file) to an existing program, it is only necessary to add the new source file, viz:
% aenf prog/fred/gizmo.c prog/fred/gizmo.h %
The .c file is the implementation, and the .h file is the published API. You should put function prototypes in the .h file, and include it both into the file which defines the function, and into the files which call the function. Edit the new files with your favorite text editor to add the new functionality.
Obviously, to invoke the new functionality, it must be called from somewhere. You copy the necessary file in order to edit it.
% aecp prog/fred/main.c %
It is assumed that this file will #include the .h file (to get the function prototype), and somewhere call the new functionality.
The include dependencies are managed automatically. There is no need to edit the Makefile to make this happen.
To build the new version your program, it is only necessary to use the
% aeb ...lots of output... %
command. This will compile all of the new and changed modules and link them to produce the new version of the program. You will find the executable in the ``bin'' directory.
You may also want to add a test of your new functionality. This is optional, but it is one of the strengths of the Aegis process.
All that is left is to complete development of the change and to integrate it, using the normal Aegis process.
Adding New Libraries
In order to add a new library, you must do two things.
You need to add the source files of your new library, using the ``new file'' Aegis command. If the program were called "nurk" then you would say
% aenf lib/nurk/func.c %
or similar. Place the include files which define the published API into the include directory...
% aenf include/func.h %
(Include files which are internal to the library should be placed below the lib/nurk directory.) There could be many .c and .h files, and you should create them all. Using your favorite editor, set their contents appropriately.

You need to edit the Makefile to tell it about the new library. You do this by copying it into your change
% aecp Makefile %
and then editing it with your favorite text editor. Look for the ``Section: Libraries'' line. You will need to add a line for your new library. It will look something like this

lib/libnurk.a: $(patsubst %.c,%.o,$(filter lib/nurk/%.c,$(source_files)))

Notice how "nurk" appears twice on this line. This says that all .c files below the lib/nurk directory are to be compiled and archived together. Thus, it will adapt to new source files being added or removed, without further modification of the Makefile.
For each program which uses this new library (in the Programs section of the Makefile) you need to add a line of the form
bin/fred: lib/nurk.a
Note: this is not an assignment, it is a rule.
Using the project structure provided by this Aegis project template you can't have the sources to two separate libraries in the one directory.
To build your new library, it is only necessary to use the
% aeb ...lots of output... %
command. This will compile all of the modules and archive them to produce the new library. It will then re-build and re-link any programs which need the new library. (Note: if none use it, it won't be compiled and archived!) You will find the executables in the ``bin'' directory.
You may also want to add a test of your new functionality. This is optional, but it is one of the strengths of the Aegis process.
All that is left is to complete development of the change and to integrate it, using the normal Aegis process.
Adding New Library Modules
If you need to add another module (often a .c file) to an existing library, it is only necessary to add the new source file, viz:
% aenf lib/nurk/kermit.c include/kermit.h %
The .c file is the implementation, and the .h file is the published API. You should put function prototypes in the .h file, and include it both into the file which defines the function, and into the files which call the function. Edit the new files with your favorite text editor to add the new functionality.
Obviously, to invoke the new functionality, it must be called from somewhere. You copy the necessary file in order to edit it.
% aecp prog/fred/main.c %
It is assumed that this file will #include the .h file (to get the function prototype), and somewhere call the new functionality.
The include dependencies are managed automatically. There is no need to edit the Makefile to make this happen.
To build the new version your program, it is only necessary to use the
% aeb ...lots of output... %
command. This will compile all of the new and changed modules and link them to produce the new version of the library. You will find the executable in the ``bin'' directory.
You may also want to add a test of your new functionality. This is optional, but it is one of the strengths of the Aegis process.
All that is left is to complete development of the change and to integrate it, using the normal Aegis process.
Yacc and Lex
The Makefile included in the project understands yacc and lex. It can even cope with more than one yacc grammar in a program or library. It does this by editing the ``yy' symbols to have a prefix based on the filename. (Yes, bison and flex have arguments for this, but this technique works with other yacc and lex implementations, as well.)
Simply add your .y and .l files as you would add any other source file. It will be detected and linked, the same as other sources.