.\"
.\" aegis - project change supervisor
.\" Copyright (C) 1999-2008 Peter Miller
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.\"
.nh 1 "How to Become an Aegis Developer"
.LP
This section describes how to become an Aegis developer,
and gives some procedures, some ideas of areas which need work,
and some general guidelines.
.LP
Please note: if these instructions have a problem, let someone know!
If you are having a problem, so is the next guy.
\fIPlease\fP send all problem reports to
Peter Miller <millerp@canb.auug.org.au>
.nh 2 "Required Software"
.LP
There are a number of pieces of software you will need to work on Aegis.
.IP \(bu 2n
It will probably come as no surprise that Aegis is developed using Aegis
(never trust a skinny chef) so the first thing you need is to install
Aegis and become familiar with using it.  You will need Aegis \*(v) or later.
.IP \(bu 2n
You will need a C++ compiler.
If your compiler is installed in an uncommon directory or has an
uncommon name, you can set the appropriate attribute by editing the
\fIaegis.conf.d/site.conf\fP file.
.IP \(bu 2n
You will need to install Cook,
in order to build things.
Version 2.8 or later, preferably you should track the latest release.
.br
http://www.canb.auug.org.au/~millerp/cook/
.IP \(bu 2n
GNU Autoconf 2.53 or later.
.br
http://ftp.gnu.org/pub/gnu/autoconf/
.br
If your tools are installed in an uncommon directory or have an
uncommon name, you can set the appropriate attribute by editing the
\fIaegis.conf.d/site.conf\fP file.
.IP \(bu 2n
GNU Automake.
.br
http://ftp.gnu.org/\%pub/\%gnu/\%automake/
.IP \(bu 2n
You will need to install FHist, for the history tool.
.br
http://fhist.sourceforge.net/
.IP \(bu 2n
You will need to install \fItardy\fP, for manipulating tarballs.
.br
http://miller.emu.id.au/\%pmiller/\%software/\%tardy/
.IP \(bu 2n
You will need to install \fIptx\fP(1), for the permuted indexes in the
documentation.
This is now part of GNU coreutils.
.br
http://ftp.gnu.org/\%pub/\%gnu/\%coreutils/
.IP \(bu 2n
You need psutils for the \fIpsselect\fP utility, to manipulate the
documentation files, mostly to put the tables of contents at the start,
rather than at the end as GNU Groff generates them.
.br
http://www.dcs.ed.ac.uk/home/ajcd/psutils/
.IP \(bu 2n
You will need the developer libraries for the \fIrx\fP library (if you
installed from the tarball, you have these, but if you installed from RPM,
you need the \-devel package as well).
.br
http://ftp.gnu.org/pub/gnu/rx/
.IP \(bu 2n
You will need the developer libraries for the \fIzlib\fP library (if you
installed from the tarball, you have these, but if you installed from RPM,
you need the \-devel package as well).
.br
http://www.gzip.org/zlib/
.IP \(bu 2n
You will need the developer libraries for the \fIlibcurl\fP library (if you
installed from the tarball, you have these, but if you installed from RPM,
you need the \-devel package as well).
.br
http://curl.haxx.se/
.IP \(bu 2n
You need UUID generation capability.
This requirement may be
satisfied in several different ways depending of your development platform.
.br
First, on GNU/Linux you could skip this requirement provided that your
kernel has support for \fI/proc\fP filesystem.  Please note: in order to
work \fI/proc\fP must be mounted and \fI/proc/sys/kernel/random/uuid\fP
must be present.
.br
Second, you could install the developer libraries for the
\fIe2fsprogs\fP package (if you installed from the tarball, you have
these, but if you installed from RPM you need the \-devel package as
well).
.br
http://e2fsprogs.sourceforge.net/
.br
Third, you could install the UUID library from OSSP:
.br
http://www.ossp.org/pkg/lib/uuid/
.br
Fourth, if your platform has support for an API compliant with DCE 1.1,
Aegis also supports the DCE API.
.IP \(bu 2n
The GNOME libxml2 library (\f[CW]http://xmlsoft.org/\fP) is used to
parse XML, you will need version 1.8.17 or later.  You do not have to
install the rest of GNOME as this library is able to be used by itself.
This package is \fBnot\fP optional, you need it to successfully build
Aegis.
.IP \(bu 2n
You need to install Bison, the GNU replacement for Yacc.
.br
http://ftp.gnu.org/pub/gnu/bison/
.IP \(bu 2n
You will need to install Flex, the GNU replacement for Lex.
.br
http://ftp.gnu.org/pub/gnu/non-gnu/flex/
.IP \(bu 2n
You need to GNU Gettext (0.16.1 or later) tools installed.
Even though Glibc 2.0 and
later include Gettext, you need the developer tools as well.  (You need
GNU Gettext even on Solaris, because the Solaris Gettext implementation
is less than adequate.)
.br
http://ftp.gnu.org/pub/gnu/gettext/
.IP \(bu 2n
You need GNU Ghostscript, for the ps2pdf utility, so that you can create
PDF documents.
.br
http://ftp.gnu.org/pub/gnu/ghostscript/
.IP \(bu 2n
You need a \fIuudecode\fP with a \f[CW]-o\fP option (to redirect the output).
It is part of GNU Sharutils.
.br
http://ftp.gnu.org/pub/gnu/sharutils/
.IP \(bu 2n
You need to install GNU awk.
.br
http://ftp.gnu.org/pub/gnu/gawk/
.IP \(bu 2n
You need a \fIctags\fP(1) command with a \f[CW]-L\fP option
(to read file names from standard input).
.br
http://ctags.sourceforge.net/
.IP \(bu 2n
You need RCS installed for the automated tests.
.br
http://ftp.gnu.org/pub/gnu/rcs/
.IP \(bu 2n
You need to install \fIsudo\fP(8).
See \f[CW]etc/set-uid-root\fP in the distribution for how to configure
the \fI/etc/sudoers\fP file.
.br
ftp://ftp.sudo.ws/pub/sudo/
.\" .IP \(bu 2n
.\" You need ImageMagic installed, for turning \fIaegis.png\fP into
.\" \fIaegis.xpm\fP because \fIrpm\fP(8) will only accept GIF or XPM icons.
.\" .br
.\" http://netpbm.sourceforge.net/
.IP \(bu 2n
The location box icon is generated using \fIconvert\fP from ImageMagick,
but the build can cope if you don't have it.
.br
http://www.imagemagick.org/
.IP \(bu 2n
The PNG images are optimized by the \f[I]pngcrush\fP command.
.br
http://pmt.sourceforge.net/pngcrush/
.IP \(bu 2n
The location box icon is generated using \fIpng2ico\fP but the build
can cope if you don't have it.
.br
http://www.winterdrache.de/freeware/png2ico/
.IP \(bu 2n
It is possible to use the dmalloc library
for
debugging memory abuses.  Be warned: the dmalloc library can be
instructed to log to a file, circumventing the Aegis I/O layer, thus
it's possible to create file owned by root.  The dmalloc library should
only ever be used as a debugging tool, and \f[I]never\fP be used in a
production build of Aegis.
.br
http://dmalloc.com/
.br
On a Debian system, use the \f[CW]apt-get install libdmalloc-dev\fP command.
.br
You will need to aecp the \f[CW]etc/Howto.cook\fP file to alter the build
to use the dmalloc library.
.IP \(bu 2n
\fIProbably more things I've forgotten.\fP
.IP \(bu 2n
Some parts of the build need Perl
.nh 2 "Create The Aegis Project"
.LP
The next thing to do is create an Aegis project to hold the Aegis source.
This is done in the usual way.  I suggest you create branches which
match the current public release, \fIe.g.\fP it is \*(v) at present.
.LP
The best-practice technique of having a separate user account to mind
the sources is recommended.  The following commands should be run as
that user, not your usual login.  This prevents a variety of accidents
which can happen when you are browsing the baseline (master source).
.LP
You could use the following command:
.E(
% \f(CBaenpr aegis.\*(v)\fP
aegis: project "aegis": created
aegis: project "aegis.\*(v)": created
%
.E)
but experienced Aegis users will know that this means a laborious setting
of project attributes.  It is easier to create the top-level project,
set the attributes, and the create the branches, so that they inherit
the attributes on creation.
.E(
% \f(CBaenpr aegis -version -\fP
aegis: project "aegis": created
% \f(CBaepa -e -p aegis\fP
\fIedits the project attributes for single user,
or you may find\fP tkaepa \fPeasier\fP
% \f(CBaena -p aegis\fP \f(CIyou\fP
aegis: user "\f(CIyou\fP" is now a administrator
% \f(CBaend -p aegis\fP \f(CIyou\fP
aegis: user "\f(CIyou\fP" is now a developer
% \f(CBaenrv -p aegis\fP \f(CIyou\fP
aegis: user "\f(CIyou\fP" is now a reviewer
% \f(CBaeni -p aegis\fP \f(CIyou\fP
aegis: user "\f(CIyou\fP" is now an integrator
.so developer_nbr.so
%
.E)
.LP
At this point, the rest of the commands in this chapter may (should!) be
executed as \[lq]\fIyou\fP,\[rq] your usual login account.  When you added your
normal account as an administrator just now, you authorized yourself to
perform the necessary actions.
.LP
You will need about 120MB of free space to build and integrate Aegis
changes, or more, depending on the changes you make and the size of your
development directories.
.LP
The \fI\&.forward\fP file of the \[lq]aegis\[rq] user needs to be set to
someone appropriate to read mail directed at the project.
.LP
You can now set the \[lq]aegis\[rq] user's password field to \[lq]*\[rq].  This
effectively prevents the \[lq]aegis\[rq] user from logging in.  Aegis is
designed to make this unnecessary from now on.
.nh 2 "The Download"
.LP
The Aegis project is distributed in the form of an
\fIaedist\fP(1) change set.  The file to download is called
\f[CW]http://aegis.sourceforge.net\%/aegis-\*(v).ae\fP
and can be grabbed using your favorite web browser, or \fIwget\fP(1).
.LP
The downloaded change set is applied using the following command
.E(
% \f[CB]aedist --receive \e
	-f aegis-\*(v).ae \e
	-p aegis.\*(v)\fP
\fI\&...lots of output...\fP
%
.E)
.LP
It is a good idea to give the project name on the command line, or
\fIaedist\fP will try to use the project name it finds in the change set,
and it probably wont find it if you are using different numbering to
the chief maintainer's copy.
.LP
The \fIaedist\fP 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:
.LP
.in +0.25i
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 \fIbeing developed\fP state.
.in -0.25i
.LP
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 \fIaegis.conf\fP file, and in the \fIetc/Howto.cook\fP file.
For your own protection, \fIaedist\fP stops at this point.  You may
want to inspect these two files before continuing.
.LP
\fII really must get around to signing it with PGP.  This would make
the \fI\-notrojan\fP option safe, because you could tell the file is direct
from the chief maintainer, and thus as trustable as you think the chief
maintainer happens to be.\fP
.LP
In order to complete development of the change set, you must first
build it...
.E(
% \f[CB]ae_p aegis.\*(v)\fP
% \f[CB]aecd\fP
% \f[CB]aeb\fP
\fI\&...you will see commands which build the project...\fP
%
.E)
.LP
Things that can go wrong...
.IP \(bu 2n
There are checks to make sure that there is no white space on the ends
of lines.  If you use Emacs, you can add
.E(
(add-hook 'write-file-hooks
    'delete-trailing-whitespace)
.E)
to have this done automagically.  The same checks also verify that the
text files are all printable, and that line lengths are 80 characters or
less.  Please don't disable the checks, it makes accepting your patches
more time consuming.
.IP \(bu 2n
Each change set has an architecture list associated with it.  Initially
you won't care, but Aegis does if you see the following error message:
.in +0.25i
found 1 unlisted architecture, edit the change attributes to remove it
or edit the project configuration file to add it
.in -0.25i
You need to use the \fIaeca -e\fP command (\fInot\fP the tkaeca command).
You will be placed into an editor (usually \fIvi\fP unless you have used
Aegis before, and know how to configure it differently).  You need
to leave just about everything alone, except for the architecture
specification.  Change it from
.E(
architecture =
[
	"unspecified",
];
.E)
to something more meaningful on your machine.
For PC users, this is almost always
.E(
architecture =
[
	"linux-i386",
];
.E)
The alternatives may be found in the \fIconfig\fP in the current directory
(search for \f[CW]architecture =\fP).
If you can't see a suitable choice,
you may need to add one;
the \fIaepconf\fP(5) man page has more information.
Edit the \fIconfig\fP file to contain a suitable entry,
and then use the \fIaeca -e\fP command to have the change agree with it.
.IP \(bu 2n
If you don't have Cook installed, the build command (aeb) will fail.
.IP \(bu 2n
If you don't have GNU Bison installed, the build will fail.
.IP \(bu 2n
If you don't have GNU Gettext installed, the error message run-time
binaries will not be built.  This isn't an error, so you can keep going,
but you'll get the shorter, cryptic form of the error messages.
.IP \(bu 2n
Please note: if these instructions have a problem, let someone know!
If you are having a problem, so is the next guy.
\fIPlease\fP send all problem reports to
Peter Miller <millerp@canb.auug.org.au>
.LP
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).
.E(
% \f[CB]aed\fP
\fI\&...you will see commands which "diff" the project...\fP
%
.E)
.LP
Things that can go wrong...
.IP \(bu 2n
If you don't have the FHist package installed, the difference (aed)
will fail.  The \fIfcomp\fP command it is looking for is a whole-file
context difference command (the GNU \f[CB]diff -c\fP is a bit too terse
for humans).
.LP
Now you will need to test the change.
This is the basic test suite for Aegis, it ensures nothing is broken.
It takes a while, go grab a cup of coffee.
.E(
% \f[CB]aet\fP
\fI\&...lots of output...\fP
%
.E)
.LP
The change is now ready to end development.
.E(
% \f[CB]aede\fP
aegis: project "aegis.\*(v)": change 10:
	development complete
%
.E)
.LP
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.
.E(
% \f[CB]aerpass -p aegis.\*(v) -c 10\fP
aegis: project "aegis.\*(v)": change 10:
	review pass
%
.E)
.LP
The change is now ready to be integrated.  Only when integration
is complete are the files actually committed to the repository.
.E(
% \f[CB]aeib -p aegis.\*(v) -c 10\fP
% \f[CB]aeb\fP
\fI\&...you will see commands which build the project...\fP
-rwsr-xr-x 1 root ... \fIarch\fP/bin/aegis
-rwsr-xr-x 1 root ... \fIarch\fP/bin/aeimport
-rwsr-xr-x 1 root ... \fIarch\fP/bin/aelock
Integrator: please do the following:
  sudo .../baseline/etc/set-uid-root \fIarch\fP aegis aeimport aelock
  if they aren't root already.  See etc/set-uid-root for
  instructions for how to set-up your /etc/sudoers file.
%
.E)
.LP
This message at the end of the build is where Aegis is made set-uid-root
in the repository.  You want to do this, because you are going to symlink
out of \fI/usr/local/bin\fP (or wherever you installed Aegis) right into
the baseline.  In this way, you will be executing your bleeding-edge
version of Aegis, exercising it before you send it to anyone else.
Hang on a bit, the sending part comes later.
.LP
Don't know how to set these files set-uid-root?  The above message
includes the command to do it:
.E(
$ \f[CB]cd\fP \f[I]blahblah\fP\f[CB]/delta*
$ \f[CB]sudo etc/set-uid-root\fP \f[I]arch\fP \f[CB]aegis aeimport aelock\fP
$
.E)
You will need to substitute the appropriate architecture name,
although it is likely to be \[lq]unspicified\fP on a fresh project.
.LP
Things that can go wrong...
.IP \(bu 2n
If you don't have \fIps2pdf\fP or \fIpsselect\fP or \fIptx\fP installed,
it won't build the documentation (this isn't an error, just keep going).
.IP \(bu 2n
If you don't have \fItardy\fP(1) install, it won't build the tarball
(this isn't an error, just keep going).
.IP \(bu 2n
Please note: if these instructions have a problem, let someone know!
If you are having a problem, so is the next guy.
\fIPlease\fP send all problem reports to
Peter Miller <millerp@canb.auug.org.au>
.LP
If all is OK,
continue with the integration...
.E(
% \f[CB]aed\fP
\fI\&...you will see commands which "diff" the project...\fP
% \f[CB]aet && aet -bl\fP
\fI\&...lots of output...\fP
% \f[CB]cd\fP
% \f[CB]aeipass\fP
\fI\&...you will see commands committing the files to fhist...\fP
aegis: project "aegis.1.0": change 10:
	integrate pass
%
.E)
.LP
The \[lq]\fIcd\fP\[rq] 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.
.nh 2 "Supporting Several Architectures"
.LP
Aegis is able to track architectures to make sure that change sets have
been built and tested on all necessary architectures.  You may hav
notices that Aegis is calling your architecture \[lq]unspecified\[rq],
you can give it a more descriptive name, too.
.LP
The architecture configuration data is described in the
\f[I]architecture\fP field of the \f[I]aepconf\fP(1) man page.
It is based on the \f[I]uname\fP(2) data, see the man page for how.
You will, of course, need a change set to change it.
.LP
Once you have a change set, you need to create the
\f[I]aegis.conf.d/architecture\fP file.
.E(
% \f[CB]aenf aegis.conf.d/architecture\fP
% \f[CB]aefa aegis.conf.d/architecture entire-source-hide\fP
% \f[CB]aefa aegis.conf.d/architecture local-source-hide\fP
%
.E)
.LP
Here are some suggestions for what you may like to set for your
architecture or architectures.
.E(
architecture =
[
  {
    name = "linux-i386";
    pattern = "Linux-*-*-i?86";
  },
  {
    name = "linux-x86_64";
    pattern = "Linux-*-*-x86_64";
  },
  {
    name = "freebsd-i386";
    pattern = "FreeBSD-*-*-i?86";
  },
  {
    name = "sunos-4.1-sparc";
    pattern = "SunOS-4.1*-*-sun4*";
  },
  {
    name = "solaris-2.6-sparc";
    pattern = "SunOS-5.6*-*-sun4*";
  },
  {
    name = "solaris-2.6-i386";
    pattern = "SunOS-5.6*-*-i86pc";
  },
  {
    name = "solaris-7-sparc";
    pattern = "SunOS-5.7*-*-sun4*";
  },
  {
    name = "solaris-7-i386";
    pattern = "SunOS-5.7*-*-i86pc";
  },
  {
    name = "ppc-Darwin-7.x";
    pattern = "Darwin-7.*-Darwin*";
  },
];
.E)
Remember to only include the architectures from the above list that
you actually have.  Having architectures in this list that you
don't routinely have access to means that you will not be able to
\f[I]aede\fP(1) any change sets.
.LP
Occasional architectures can be handled, too:
.E(
architecture =
[
  {
    name = "ppc-Darwin-7.x";
    pattern = "Darwin-7.*-Darwin*";
    mode = optional;
  },
];
.E)
Again, only do this with architectures you actually have access to.
.PP
If you need to have architecture specific options to some commands,
you can also have \f[I]project_specific\fP attributes, too.
\f[B]Note\fP that you should \f[I]first\fP look into having a
\f[CW]$prefix/share/config.site\fP or \f[CW]$prefix/etc/config.site\fP
file for \f[I]./configure\fP to read.  This is particularly important if
you want to include \f[I]/usr/local/include\fP, \f[I]/usr/local/lib\fP,
\f[I]etc\fP, in the various compiler flags.
.nh 2 "The Bleeding Edge"
.LP
As I mentioned above, the next thing to do is create symbolic links out
of \fI/usr/local/bin\fP into your Aegis baseline.  The reason for doing
this is so that you exercise your Aegis changes by using Aegis before
you send them to anyone else.  (Never trust a skinny chef.)
.LP
There is a shell script called \fIae-symlinks\fP
in the baseline \fI$arch/bin\fP direcdtory.
Use it like this:
.E(
$ \f[CB]aecd -bl\fP
# \f[CB]su\fP
Password:
# \f[CB]linux-i486/bin/ae-symlinks aegis.\*(v)\fP
# \f[CB]exit\fP
$
.E)
The \fIlinux-i486\fP may need to be replaced with the output of the
\fIaesub -bl '$arch'\fP command if you are using something more
interesting than a PC.
.nh 2 "Undiscovered Country"
.LP
If you got this far, your local Aegis project is ready for use.
.LP
It is strongly suggested that you complete the first change
\[lq]as is\[rq] and perform your own customizations in later changes,
rather than trying to get the project started and customize it
at the same time.
.LP
The rest of this file describes how to perform various common
changes to the example project.
.nh 2 "Sending Changes"
.LP
First, read the Distributed Development chapter of the User Guide.
.LP
When you have a change set you wish to have the other Aegis deveopers try,
use a simple command such as:
.E(
aedist --send -p aegis.\*(v) -c \fInumber\fP | \e
gpg --clearsign | \e
mail aegis-developers@lists.sourceforge.net
.E)
or similar.  (Or maybe \fIaepatch\fP(1) instead.)
A suitable subject line would be very helpful.
.nh 2 "Guidelines"
.LP
.nh 3 "What You Can Do"
.LP
Write more documentation.  There is a crying need for documentation of
all sorts: better manual pages, more and better information in the User
Guide, more and better HOWTOs.  If you work out how to do something,
and it isn't in the documentation, write some documentation and put it
in a change set because other folks have probably missed it too.
.LP
Add more ease-of-use functionality.  Stuff which makes the development
process more efficient, or makes the information in the repository
more accessible.
.LP
Extend the GUI.  All of the commands which manipulate the change while
in the \fIbeing developed\fP state are candidates.  Some kind of wrapper
that ties it all together would be good, too.  User preferences, project
attributes and creating projects are candidates, too.
.LP
Most new project configuration things belong in the project \fIconfig\fP file.
Only add new project attributes (aepa -e) for things which
(a) are catch 22 to change in a change set, or
(b) allow a security abuse if in a change set
(e.g. the notify commands, particularly aede), or
(c) allow the repository to be damaged.
(My thanks to Ralf Fassel <ralf@akutech.de> 2 Feb 1999 for pointing this out.)
.nh 3 "What You Can't Do"
.LP
You can't change Aegis' semantics.  Developers around the world, and
their managers, rely on Aegis working just the way it does right now.
You can't change things that will compromise their ability to get
things done.
.LP
Particularly, Aegis has a strong security story.  Availability, integrity
and confidentiality, and all that.  If you want it more flexible,
that's good, but you can't change the defaults and you can't make it
irretrievably weaker.
(You can, as a \fInon\fP-default make it weaker, within limits.)
.LP
Aegis (the executable, not the whole package) is quite big enough.
Don't add code to \fIarch\fP\f[CW]/bin/aegis\fP than can be done with
the report generator, or as a separate program like \f[CW]aesub\fP or
\f[CW]aefind\fP.  More GUI can be added using Tk/Tcl - unless you have
grander plans and even then it \fIstill\fP shouldn't be added to the
set-uid-root executable.
.nh 2 "Coding Style"
.LP
Please try to emulate the existing coding style.
(Indents recently changed from 8 to 4, not all of the code has caugh-up yet.)
Lines are to be 80 charcters or less wide,
limited to the 95 printable ASCII characters,
with no trailing white space.
.LP
Probably need a GNU Indent profile for code formatting, too.
.nh 2 "Writing Tests"
.LP
If you have fixed a bug you should write a test to verify the correct
behaviour of Aegis.
Because test file names are generated automatically starting from your
repository state, it's possible that \fIaet\fP will create a test with the
same name as one in the P.Miller repository.  Because Aegis is not yet
able to detect such situation, if you plan to send back
your work to P.Miller you may want to modify your \f[CW]aegis.conf\fP
adding the following lines:
.E(
new_test_filename =
  "test/${zpad $hundred 2}/"
  "t${zpad $number 4}${left $type 1}-${left ${user login} 4}.sh";
.E)
In this way the possibility of a name collision should be reduced.
Invoke \fIaent\fP:
.E(
% \f(CBaent\fP
aegis: appending log to "aegis.log"
aegis: user "walter", group "projadm"
aegis: rm -f etc/cook/change_filesf etc/cook/project_files
aegis: project "aegis.4.16.2": change 11: file "test/01/t0157a-walt.sh" new test
%
.E)
Now you can start to implement the test.  Remember to invoke the
programs under test as \f[CW]$bin/program\fP.
.IP \(bu 2n
In order to improve error messages you should organize your script as
a sequence of activity and use the \fIactivity\fP variable as sketched
below:
.E(
#
# create a new change
#
activity="new change 163"
cat > tmp << 'end'
brief_description = "The first change";
cause = internal_bug;
end
if test $? -ne 0 ; then no_result; fi
$bin/aegis -nc 1 -f tmp -p foo > log 2>&1
if test $? -ne 0 ; then cat log; no_result; fi
.E)
If you are reading this document, you probably don't need help to
understand this code fragment, the only thing to note is that the
number in the string (163) refer to the current line number and is
used when printing a failure message.  You don't need to maintain it
by hand as explained in the following step.
.IP \(bu 2n
You can use \f[CW]test/activity.sh\fP to automatically renumber the
activity variables of your tests:
.E(
$ \f(CBsh test/activity.sh\fP
test/01/t0159a-walt.sh...
test/01/t0160a-walt.sh...
$
.E)
If you have not modified \f[CW]test/activity.sh\fP you should find it
as \f[CW]bl/test/activity.sh\fP or \f[CW]blbl/test/activity.sh\fP.
.nh 2 "Debugging"
.LP
Aegis, as any other software, may contain undiscovered bugs.  If you are
interested in helping to fix these bugs, and as a developer you should
be interested, the first thing to do is compiling Aegis in DEBUG mode.
In order to do so you must modify \f[CW]common/main.h\fP and uncomment
the DEBUG define.  (If you use the \fIaecp \-read-only\fP option, Aegis
will remind you to uncopy the file again before develop end, ensuring
that you don't accidentally integrate this.)
.LP
In DEBUG mode the \-Trace command line option is available for most
Aegis commands.  This option is followed by the names of the source
files you want to trace, and may be used more than once.
.LP
If you need to add tracing capability to a file, you must first
include \f[CW]trace.h\fP, modify the code in order to use the trace
facility (look at \f[CW]common/trace.h\fP) then build the change with
\fIaeb\fP and run the buggy command with the proper \-Trace option.
.LP
On Linux >= 2.4 the \fIaegis\fP command, wich is set-uid-root, is enabled
to dump core when needed.  If this does not happen, remember to verify
the \fIulimit\fP(1) settings; you may need to execute the \fIulimit \-c
unlimited\fP command.
.so devel_to_do.so