Description

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

Download

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

Assumed Environment

• 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.21 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 RCS according to the instructions. This is only necessary for the merge(1) program, which is used to perform 3-way merges of test files. If you have a different preferred merge tool, it's pretty easy to change it later.

• 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

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. As an administrator, “you” can add new developers, reviewers, etc, without logging in as the project owner.

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.

An easier way to do this is to use the tkaepa(1) command. It provides you with a simple GUI to edit the project attributes.

$ tkaepa
...click the OK button when you are done...
$

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

$ aedist --rec -f example-c-plus-plus.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 will not 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.

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

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

There are a number of things that could go wrong at this point...

• 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...
$

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
$

If you selected the develop end action to be goto awaiting integration then you can skip this next bit, because it talks about the review state that you have configured to project to skip.

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

Note that, when you are comfortable using Aegis, it is possible to perform the whole integration stage with a single command, see aeintegratq(1) for more information. You can even run it from cron(8).

Where to from here

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

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

Adding New Programs

In order to add a new program, you must do one thing.

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

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

3. 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
$

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

$ aenf prog/fred/gizmo.c prog/fred/gizmo.h
$

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
$

The new file is detected automatically, there is no need to edit the Howto.cook file to tell it about the new source file. 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...
$

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

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

2. The Howto.cook file will automatically notice the new library, provided 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...
$

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

$ aenf lib/nurk/kermit.c include/kermit.h
$

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
$

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

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

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.