Description

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.

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 aepro-rcs.ae and usually obtained from http://aegis.sourceforge.net/ 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 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 login again. (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 ``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
...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;
integrate_pass_notify_command = "${shell} ${source scripts/fold_change.sh}";

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 aepro-rcs.ae -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/build.sh 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/get_progres.sh 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
...you will see commands which build the project...
%

Things that can go wrong...
This is the first release of AePro, so something is guaranteed to go wrong. As I am unaware what that is, I need your help to send any troubles you encountered thus far and I will try to have them fixed next release.
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 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 ...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 "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):
LICENSE config ./database: 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. ./design: A general directory to store any functional designs etc. ./etc: This directory holds configuration info for AePro, and the templates directory. ./etc/template: 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 ./scripts: This directory holds all shell scripts. Most act as a wrappper between Aegis and AePro / progress. ./src: this directory contains all progres sources to AePro. Their objects are places in r-code after compilation ./test: contains all the tests for aepro in the form of shell scripts, progress sources and datafiles. ./www: 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.
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 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.)

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 build.sh 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.