Aegis 4.24
Template OSS Project

This worked example shows you how to get an existing OSS project managed by Aegis in less than 30 minutes.

Requirements

There are a number assumptions made by this example:

If your project is more complicated than this, and many are, you may be able to adapt these instructions once you understand what they are trying to achieve. I recommend you read on, and keep notes of where you will have to change things.

These instructions do not assume you are the primary maintainer of this OSS project, you just want “a local branch” for hacking on. These instructions will work just as well for a maintainer, but they do not cover migrating from the present version control tool to Aegis.

Creating a New Project

The first thing to do is create the project. In order to have good security for your project, the user account which owns the project files needs to be different than the developers. This prevents accidents where the master source could be broken accidentally.

In this example, we will call that user “repos”. Create this user in the usual way for your operating system.

Because this example is going to be talking about two accounts, the repos account, and your usual user account, this example will call your usual user account “user”.

Now, to create the project, use this command: 

user$ su - repos
password:
repos$ aegis	-new-project vgrabbj -version -
repos$
The “–version –” tells Aegis you don't want it to create a branch hierarchy just yet.

The project directory tree will be established in the repos user's home directory. You can put it somewhere else using the -directory command line option, so long as the repos user has write permissions to create that directory.

Next, add you usual user account as a project administrator, using this command: 

repos$ aegis -new-administrator user	-p vgrabbj
repos$
Remember to replace user with your actual user name.

The above command established your usual account as a project administrator. All of the remaining steps to create the project may be done from your normal account. 

repos$ exit
user$
The next step is to add yourself to all of the remaining project roles: developer, reviewer and integrator. You can do this, because you are a project administrator. 
user$ ae_p vgrabbj
user$ aend user
user$ aenrv user
user$ aeni user
user$
The next task is to set the project attributes. This is most easily done by using the tkaepa(1) command. 
user$ tkaepa
user$
Note: if you aren't using X11, the aepa(1) command will does the same job, and it's what tkaepa(1) invokes, but you will need to read the aepattr(5) man page for the expected input format. For novices, the GUI interface is easier.

You want to turn on just about everything. For a single person project, turn on

The last step is to create the branches. Assuming vgrabbj is at version 0.9.6, we will create the 0 and 0.9 branches. 

user$ aegis -new-branch	-p vgrabbj 0
user$ aegis -new-branch -p vgrabbj.0	9
user$
Things are nearly ready to go.

Establishing the Development Environment

At this point, Aegis needs some basic project configurations. These are kept in source files inside the project repository, so that they are versioned.

The necessary settings and their source file are pre-packaged for you. The following command will download the change set and apply it to the project:

user$ aedist -rec -f http://aegis.sourceforge.net/eg_oss_begin.ae -p vgrabbj -c 900 -v
user$
The change set is applied to the trunk of the project branch tree (the project name doesn't end with .0.9) because files are inherited by sub-branches, and most of these settings will not be changing.

It's worth mentioning that the Aegis project configuration established by this change set consists of five files:

aegis.conf
This file contains the directive that all files in the aegis.conf.d directory are to be read for additional configuration information.
aegis.conf.d/build
This file says how to build the project. Initial it is set to “exit 0” to indicate no build is required. This will be addressed shortly.
aegis.conf.d/diff
This file sets GNU Diff as the file difference tool.
aegis.conf.d/merge
This file sets RCS Merge as the file difference tool. It won't be used in this example, but at some point all projects will need it.
aegis.conf.d/history
This file sets the history tool to be used. For this example, the aesvt(1) program, which comes with Aegis, is used. There are example configurations included with the Aegis distribution for SCCS, RCS and FHist; this example is the wrong place to explore all of these alternatives. Note: you can not change the choice of history tool later, you must get the history tool right in the first change set; practice on little examples first, before migrating a serious project. The History Tool chapter of the Aegis User Guide has more information about the various history tools.

This change will automatically end development, and you need to integrate it. This is because Aegis breaks the commit step into several separate stages, each with its own checks and balances.

The integration step, particularly when it is not being used as a second review stage, is most simply accomplished using the aeintegratq command: 

user$ aeintegratq vgrabbj
user$
It will take about a minute, and it won't say much if nothing went wrong.

At this point, many Aegis commands are available, and you may like to try some if them out.

ael p
List the projects. This show all the projects that Aegis is managing.
ael c
List the changes. This will show change 0 (branch 0, branches are just big change sets), and change 900 which was used to add the project configuration files.
aecd -bl
Change directory to the project baseline. Take a look around using ls(1) and vi(1). You can't break anything - you don't have write permission.
The Aegis Reference Manual would be very useful to you at this point, because you can look up each of these commands, and discover the wealth of command line options not mentioned in the above examples.

Creating a New Project from Scratch

I know this example is about an existing project, but if you are creating a new project from scratch, you will probably be interested in the GNU Auto Tools change set, which establishes the build system for an empty project.
user$ aedist -rec -f http://aegis.sourceforge.net/eg_oss_aemak.ae -p vgrabbj -c 6 -v
user$
This project uses Automake, Autoconf and Libtool to do all the work. All you have to do is conform to the pretty relaxed expectations in aemakegen(1) of the project directory layout.

Skip this section if you are working with an existing project. Skip down to section “ Template Contents for New Files” if you are starting from scratch.

Unpacking the Tarball into a Change Set

Now we are ready to actually take some OSS code and commit into our shiny new repository.

You need to visit vgrabbj.sourceforge.net and download the latest tarball. This example is based on 0.9.6, but it will not matter very much of the minor version has moved on since this was written.

We created branches 0 and 0.9 before, and now we are going to use them. 

user$ ae_p vgrabbj.0.9
user$
This command sets the AEGIS_PROJECT environment variable, so you don't have to keep typing --project=vgrabbj.0.9 all the time.

Assuming that the tarball is in the current directory, the following command will unpack it into a change set:

user$ aetar --receive -f vgrabbj-0.9.6.tar.gz -c 6 --exclude-auto-tools --remove-path-prefix=1
...lots of output...
user$
The --exclude-auto-tools option says to exclude common non-source files (like ./configure) from the tarball if aetar detects the presence of their precursors (like configure.ac). These files will be created by the build system, which will be introduced in the next section. (This option can be abbreviated to -eat.)

The --remove -path-prefix=1 option says to remove the top- level directory from the filenames in the tarball. It changes with every version, and thus is not helpful when you want to track upstream versions. (This option can be abbreviated to -rpp=1.)

If you read the output of this command (scroll up your terminal window) you can see all of the commands aetar(1) executed for you. Each of the files in the tarball has been created as a source file.

You will also see that it created a private work area for you to do this within, inside you home directory, called a development directory. Every change set gets its own development directory. You can enter this development directory and have a look around using the following command: 

user$ aecd 6
user$ ls -l
user$
That “6” is the change set number. It was specified explicitly on the aetar(1) command line, so that it matches the tarball. If you don't specify a number, the aetar(1) command will use the next available.

There are a number of other Aegis command which now have some content. Try 

user$ ael cd
user$
The “cd” is short for change-details and much faster to type than the long version, though that also works.

You will see that the change description isn't especially informative. You can use the following command to edit the change set's attributes: 

user$ tkaeca
user$
Just change the descriptions for now, and resist the urge to kick the tires. You can always create another change set later.

Note: if you aren't using X11, the aeca(1) command will does the same job, and it's what tkaeca(1) invokes, but you will need to read the aecattr(5) man page for the expected input format. For novices, the GUI interface is easier.

To finish this change set, it's much like the previous one. All of the usual Aegis process will be adhered to (if you consult the User Guide you will see what that means) but it will go by very quickly in this example. 

user$ aefinish
...lots of output...
user$ cd
user$ aeintegratq vgrabbj-0.9
user$
At this point, the most recent upstream version is in your Aegis repository. You can do what you like from now, but the next section gets it to build, so that you can start using some of Aegis more advanced software development process features.

Adding the Build to the Development Environment

The development process modeled by Aegis can be used to enforce policy such as “change sets must build successfully before they are committed”. In order to accomplish this policy, Aegis watches the exit status of the build command. You can use just about any build tool you like, but many OSS projects use GNU Make, and vgrabbj is no exception.

There is a second pre-packaged Aegis change set which you can use to have your project be built under Aegis, and enforce such a build policy.

This change set, which you will download very soon, does another thing, as well: it sets the development directory style. Many OSS developers are used to CVS or SVN which make a complete copy of the project when you check out your private work area. And their build systems are based on the assumption that this has happened. Aegis is able to provide this kind of development directory style, however the default is a “view path” style which only has source files in the private work area if they are actually being changed, which can get confusing for new users who are expecting a fully populated source tree.

user$ aedist -rec -f http://aegis.sourceforge.net/eg_oss_build.ae -p vgrabbj.0.9 -c 901 -v -trojan
...lots of output...
user$
This command downloads the change set, creates a private work area for it (called a development directory in Aegis speak) and unpacks all the files of the change set into it.

The -trojan option says to stop once the files are unpacked, and before any builds occur. You can do this for remote changes you are not sure about, but it also gives you a chance to poke about the development directory and see what Aegis has actually done. 

user$ aecd 901
user$ ls
user$
The first thing you will want to know is “where have all the source files gone?” Remember the view path thing? The development directory style just downloaded hasn't taken effect yet. The build will take care of that, and we will get to it shortly.

It is worth taking a look at the files about to be created by this change set. The aegis.conf.d/build file tells Aegis how the project is built. It invokes make(1) with a special makefile which includes the generated Makefile, if it exists, and builds it if it does not (in which case it builds it and starts again). In this way, the build is boot-strapped without altering any of the source files we got from the tarball.

To build, you just need this command:

user$ aeb
...lots of output...
user$
If you look at the output (scroll the terminal back) you will see that all of the usual and expected things are done to build an OSS project. You will also note that the development directory is now full of source files... this is because the aeb(1) command updated the development directory automatically before running the configured build command. After this change set is integrated, the next time you start a new change set, the development directory will be populated immediately.

If there are any problems with the build, it is going to be with how the project uses GNU Autoconf and GNU Automake to bootstrap itself. You may need to edit the aegis.supplementary/makefile file to fix the problem. Once the “real” Makefile has been produced, the supplementary file will do nothing.

We will finish this change set the same way as before, using the aefinish(1) command, and then integrate it: 

user$ aefinish
...lots of output...
user$ cd
user$ aeintegratq vgrabbj-0.9
user$
And now the project builds. This would be a good time to read through the worked example in the Aegis User Guide.

Template Contents for New Files

One of the useful features of Aegis is the ability to provide templated contents for new files. There is a pre-built change set you can download which will provide GPL headers for all of your new files.
user$ aedist -rec -f http://aegis.sourceforge.net/eg_oss_templ.ae -p vgrabbj.0.9 -c 902 -v
user$
This change set is finished in the usual way. 
user$ aefinish
user$ cd
user$ aeintegratq vgrabbj-0.9
user$
This change set also includes a new file template for new tests. You create a new test with the aent(1) command, from within a change set in the being developed state.

All Done

At this point your project is ready to go. You can create a new change set, begin development, write a test, and start bug fixing and/or adding new functionality. A couple of tips:
The beautiful graphics on this web site are by Grégory Delattre.

 Return to the Aegis home page.