This is a template Aegis project for developing progres4gl code. 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.


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 and usually obtained from using your favorite web browser.

Assumed Environment

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

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 ``aegis'' and a project called ``aepro.''

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

% aenpr aepro.0.1
aegis: project "aepro": created
aegis: project "aepro.0": created
aegis: project "aepro.0.1": 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 aepro.0.1 you
aegis: project "aepro.0.1": user "you" is now an administrator
% aend -p aepro.0.1 you
aegis: project "aepro.0.1": user "you" is now a developer
% aenrv -p aepro.0.1 you
aegis: project "aepro.0.1": user "you" is now a reviewer
% aeni -p aepro.0.1 you
aegis: project "aepro.0.1": user "you" is now an integrator

The .forward file of the ``aepro'' 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 ``aepro'' user's password field to ``*''. This effectively prevents the ``aepro'' 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 aepro.0.1

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

% aepa -e 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;
integrate_pass_notify_command = "${shell} ${source scripts/}";

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 -p aepro.0.1
...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. For your own protection, aedist stops at this point. You may want to inspect this file before continuing.

Now you have to change some code to configure aepro to your particular environment. A future release might have a proper installer, but for now you'll have to do it by hand. You have to create a database to store the xref and branch info in, and you have to tell AePro where your version of progress lives.
First you should create a database to hold your xref and branch information. Create it from the .st and .df files given in the databases directory. Now you have to let AePro know where this database resides. Unfortunately that info still is dispersed around several files in the repository. The most important is scripts/ but there are some others too. Just do a grep for DATABASES and replace the string that is assigned to it with a colonseparated string containing the absolute pathnames to your required databases. Any databases that you need for compilation should go here too.
The last thing you should do before you can build the change, is tell AePro where your version of progress resides. Open the file scripts/ in an editor and change the value fro the DLC variable to point at your progres install.

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

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

Things that can go wrong...

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 will see commands which "diff" the project...

Things that can go wrong...

Now you will need to test the change. This is because this change set includes a number of tests for the aepro 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 "aepro.0.1": 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 aepro.0.1 -c 10
aegis: project "aepro.0.1": 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 aepro.0.1 -c 10 
% aeb will see commands which build the project...
% aed will see commands which "diff" the project...
% aet
...lots of output...
% aet -bl
...lots of output...
% cd
% aeipass will see commands committing the files to RCS...
aegis: project "aepro.0.1": 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):


Database definitions and structure files go here.
A next release will build the databases defined here automatically so aech compilation
can have its own database for speed.

A general directory to store any functional designs etc.

This directory holds configuration info for AePro, and the templates directory.

This directory holds templates for sourcefiles.
When a new file is created in aegis with aenf,
aegis looks in the config file for any matching patterns in the template section,
and copies the matching template to the new file.the

This directory holds all shell scripts.
Most act as a wrappper between Aegis and AePro / progress.

this directory contains all progres sources to AePro.
Their objects are places in r-code after compilation

contains all the tests for aepro in the form of shell scripts, progress sources and datafiles.

html files for the website.

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.

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.

  1. 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.

  2. 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 src/fred/fred.p
    or similar. There could be many .p .w and .i 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.)

  3. The program will be build when you aeb the change, and the resulting r-code placed in the directory r-code. If you wish your program r-code to be stored in another directory, you can add a rule to the etc/compiler.conf file. This file holds the tranformation rules that transform the path to the sourcefile into the path to the r-code file. Have a look at the src/substitute_path.p file to see how it works.

Aegis wants to know if your program builds, and so it watches the exit status of the command. To build your new program, it is only necessary to use the

% aeb
aegis: make -f makefile project=aepro.0.1 change=11
...lots of output...
aegis: project "aepro.0.1": change 11: development build complete
command. This will compile all of the modules and place the r-code in the desired 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.