Description

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

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-cook-fhist.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.10 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 Cook according to the instructions. If you haven't, you need to before you can proceed. (You need Cook 2.8 or later.)
It's probably a good idea to have to Cook manuals handy, too. They're not essential, but it helps if you're trying to read the Howto.cook file.
It is assumed that you have downloaded and installed FHist according to the instructions. If you haven't, you need to before you can proceed.
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 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-cook-fhist.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 "Howto.cook" 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 Cook installed, the build command (aeb) will fail.
If you don't have GNU bison installed, you need to edit the Howto.cook file 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 Howto.cook file 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).
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 fhist... 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):
Howto.cook 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 empty. However, the Howto.cook file always removes targets before running recipes, this is to ensure the the integration directory (see the Aegis manual) can't damage the baseline.
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. The copy of the file to be modified is placed in the development directory in the same relative location as it appears in the baseline.
Similarly, you create new files using the ``aenf'' command (it's mnemonic). Again, this way Aegis knows which files you are creating.
Anything which isn't present in the development directory is obtained from the baseline. If there is, for example, an include file in the development directory, the baseline source files will be recompiled and the new object files placed in the development directory.
Whole Project Builds
The method used to build the project is to perform ``whole project'' builds. 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 one thing.
Two 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.)

The Howto.cook file will notice the new program automatically, provided you put its source files in a directory under the prog directory. You do not need to edit the Howto.cook file to tell it about the new program.
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 cook command. To build your new program, it is only necessary to use the
% aeb aegis: cook -b Howto.cook 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 Howto.cook file 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 library 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.

The Howto.cook file will automatically notice the new library, proveded you place its source files in a directory leblow the lib directory. You do not need to edit the Howto.cook file to tell it about the new library.
However, for each program which uses this new library (in the Programs section of the Howto.cook file) you need to add a line of the form
bin/fred_libs = lib/libnurk.a;

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 Howto.cook file 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 Howto.cook file 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.