aegis a project change supervisor - sourceforge

.

AegisA Project Change Supervisor

HOWTO

Peter [email protected]

Howto Aegis

.

This document describes Aegis version 4.24and was prepared 14 March 2008.

This document describing the Aegis program, and the Aegis program itself, areCopyright © 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,2003, 2004, 2005, 2006, 2007, 2008 Peter Miller

This program is free software; you can redistribute it and/or modify it under the terms ofthe GNU General Public License as published by the Free Software Foundation; eitherversion 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 WAR-RANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FORA 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 pro-gram. If not, see <http://www.gnu.org/licenses/>.

(bl/lib/en/howto/introductio.so) Peter Miller

Aegis Howto

Table of Contents

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1. Assumed Knowledge . . . . . . . . . . . . . . . . . . . . . . 31.2. Howto Install Aegis . . . . . . . . . . . . . . . . . . . . . . . 31.3. Howto Contribute . . . . . . . . . . . . . . . . . . . . . . . 3

2. Cheat Sheet . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.1. Common Commands. . . . . . . . . . . . . . . . . . . . . . 42.2. Developer Commands. . . . . . . . . . . . . . . . . . . . . . 42.3. Reviewer Commands. . . . . . . . . . . . . . . . . . . . . . 52.4. Integrator Commands. . . . . . . . . . . . . . . . . . . . . . 52.5. Project Administrator Commands. . . . . . . . . . . . . . . . . . 5

3. How to Start Using Aegis . . . . . . . . . . . . . . . . . . . . . . . 63.1. First, Create The Project. . . . . . . . . . . . . . . . . . . . . 63.2. Second, Use a Template Project. . . . . . . . . . . . . . . . . . . 63.3. Second, Copy a Template Project . . . . . . . . . . . . . . . . . . 6

4. How to Recreate Old Versions . . . . . . . . . . . . . . . . . . . . . 74.1. aecp. . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.2. Finding Delta Numbers . . . . . . . . . . . . . . . . . . . . . 74.3. ${version} . . . . . . . . . . . . . . . . . . . . . . . . . . 74.4. Out Of Date . . . . . . . . . . . . . . . . . . . . . . . . . 7

5. How to Create a New Project . . . . . . . . . . . . . . . . . . . . . . 95.1. Single User Project. . . . . . . . . . . . . . . . . . . . . . . 95.2. Two User Project . . . . . . . . . . . . . . . . . . . . . . . 95.3. Multi User Project . . . . . . . . . . . . . . . . . . . . . . . 105.4. Warning . . . . . . . . . . . . . . . . . . . . . . . . . . 105.5. Changing The Project Owner. . . . . . . . . . . . . . . . . . . . 10

6. How to Move a Project . . . . . . . . . . . . . . . . . . . . . . . . 126.1. Relocating a Project. . . . . . . . . . . . . . . . . . . . . . . 126.2. Renaming a Project. . . . . . . . . . . . . . . . . . . . . . . 12

7. Working in Teams . . . . . . . . . . . . . . . . . . . . . . . . . 147.1. Local . . . . . . . . . . . . . . . . . . . . . . . . . . . 147.2. Distributed . . . . . . . . . . . . . . . . . . . . . . . . . 15

8. How to use Aegis with Python . . . . . . . . . . . . . . . . . . . . . 188.1. Handling Aegis search paths. . . . . . . . . . . . . . . . . . . . 188.2. The build step . . . . . . . . . . . . . . . . . . . . . . . . 198.3. Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . 198.4. Running your programs . . . . . . . . . . . . . . . . . . . . . 20

9. Howto End A Branch . . . . . . . . . . . . . . . . . . . . . . . . 2210. How to Become an Aegis Developer . . . . . . . . . . . . . . . . . . . 24

10.1. Required Software . . . . . . . . . . . . . . . . . . . . . . . 2410.2. Create The Aegis Project. . . . . . . . . . . . . . . . . . . . . 2510.3. The Download . . . . . . . . . . . . . . . . . . . . . . . . 2610.4. Supporting Several Architectures . . . . . . . . . . . . . . . . . . 2710.5. The Bleeding Edge . . . . . . . . . . . . . . . . . . . . . . 2810.6. Undiscovered Country . . . . . . . . . . . . . . . . . . . . . 2810.7. Sending Changes. . . . . . . . . . . . . . . . . . . . . . . 2810.8. Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . 2910.9. Coding Style . . . . . . . . . . . . . . . . . . . . . . . . 2910.10. Writing Tests . . . . . . . . . . . . . . . . . . . . . . . . 2910.11. Debugging . . . . . . . . . . . . . . . . . . . . . . . . . 3010.12. The To-Do List . . . . . . . . . . . . . . . . . . . . . . . 30

Peter Miller (bl/lib/en/howto/main.ms) Page 1001

Howto Aegis

Page 1002 () Peter Miller

Aegis Howto

1. Intr oduction

This manual contains a series of brief lessons or“How To” guides for using Aegis. Each isarranged to cover two pages, so that when themanual lies open on the desk, the whole subject iseasily visible in front of you.

When printing this manual, it is essential to printit double sided, or the “subject at once” effect willnot occur.

The table of contents will be printed last. Insert it(there should be two pages, on one sheet of paper)before this page.

1.1. AssumedKnowledge

Many of these sections are written for use bybeginners, so there is a fairly low lev el ofassumed knowledge. However, you may want tohave The Aegis User Guide, and The Aegis Refer-ence Manualvery close by, as all of the materialconveyed here is available in a more expended ordetailed form on those manuals.

1.2. Howto Install Aegis

The description of how to build, test and installAegis may be found in the Reference Manual,under the headingThe BUILDING File, whichreproduces theBUILDING file included in theAegis source distribution.

If you installed Aegis using a RedHat or Debianpackage, this will not be at all relevant to you,simply ignore it.

1.3. Howto Contribute

If you would like to see other “How To” subjects,please drop me an e-mail. Better yet, write oneand e-mail it to me.


Howto Aegis

2. CheatSheet

This page is a quick reference into the commonAegis commands.

• Usually, “mancommand_name” can be used toget more details on a particular command.

• See also the official Aegis quick reference inthe User Guide, page 88.

• The “-p name” option is used to specify theproject name.

• The “-c number” option is used to specify thechange number.

• The “-l ” (or “-List ”) option can often beused to list subjects for the given command (eg.change numbers or projects) or simply to listrather than edit (e.g.a file or change attributes).

2.1. CommonCommands

ae_p project-name.branch-numberSet current project number for all fol-lowing Aegis commands.The ae_pcommand with no arguments will‘unset’ this forced default.

ae_c numberSet current change number for all fol-lowing Aegis commands.The ae_ccommand with no arguments will‘unset’ this forced default.

aecd [ -bl ]Change directory [change to baseline].

aeb Aegis build - used by developers,reviewers and/ or integrators.

aet Run tests - used by developers.

aed Difference of change files with baseline.

aedlessView difference files generated withaed .

ael cdList change details.

aeca [ -l ]Edit [list] change attributes.

tkaencCreate a new change (seeaenc(1) fordetails), using a GUI interface. Thismakes it a damn sight easier to type inthe description field.

tkaecaEdit change attributes (seeaeca(1) fordetails), using a GUI interface. Thismakes it a damn sight easier to edit the

description field.

ael llList all of the lists (there are a lot).

ael c List all of the changes for a project(branch).

ael cfList all of the files in a change.

aeuconf(5)This is a man page documenting the˜/.aegisrc file format.

2.2. Developer Commands

Procedure:ael cd → aedb → do stuff → aeb→ aet → aed → aedless [ → aeclean ] →aede

aedb[u]Develop begin [undo].

aede[u]Develop end [undo].

aecleanThis will remove all files in the develop-ment directory which are not in the changeas new files or copied files. This maydelete files that you want, so be careful.

The aeclean(1) command uses Aegis’ knowledgeof what issupposedto be in the change.You aremeant to tell Aegis about all source files you cre-ate in a development directory. If you have for-gotten to do this, it is highly likely that the inte-gration would fail in any case.

If you are importing files from elsewhere, use“aenf .” and all of the files in the directory treebelow dot (the current directory) will be added tothe change (make sure there are no object fileswhen you do this).

aecpPrepares a file in the project for editingwithin the change;i.e. copy file into changefrom baseline. Remove symlink if neces-sary, etc.

aecpuReverse the effects of the above.

aecpu -unchWill check all files in your change to see ifany hav enot been modified, and perform anaecpuon them. This will stop an unneces-sary version number increment for files thathave not changed. (And also improves testcorrelations.)

Page 4 (bl/lib/en/howto/cheat.so) Peter Miller

Aegis Howto

aem Merge out-of-date files. See the-Only-mergeoption of theaed(1) command.

aenf[u]Create/ add a new file [undo].

aemvRename (move) files.

aerm[u]This tells Aegis the file is to be removedfrom the baseline when the change is inte-grated. Oraermu to undo thisbefore thechange is finished.

2.3. Reviewer Commands

Procedure:ael cd → aecd → aedless →view output, review source files-> aerpass

Remember: the point of reviews is to find prob-lems, not be a rubber stamp.You are expected tofail some reviews.

aerpassReview pass.

aerpuReview pass undo.

aerfailReview fail.

2.4. Integrator Commands

Procedure:aeib → aeb → aet → aed →aeipass

There is anaeintegratq(1) script distributed withAegis to do this procedure automatically.

aeib[u]Integrate begin [undo].

aeipassIntegrate pass.

aeifailIntegrate fail.

2.5. Project Administrator Commands

This includes all of the commands that don’t fitthe categories above.

aenc[u]Create a new change [undo].Seeaecattr(5)for description of file format, or usetkaenc(1) instead.

aend andaerdNew dev eloper; remove dev eloper.

aenrv andaerrvNew reviewer; remover reviewer.

aeni andaeriNew integrator; remove integrator.

aena andaeraNew (project) administrator; removeadministrator.

aepa [-l]Edit [list] project attributes (seeaepattr(5)for file format).

aeca [-l]Edit [list] change attributes (seeaecattr(5)for file format).

tkaecaEdit change attributes using a GUI.Thismakes it much easier to type in the descrip-tion field.


Howto Aegis

3. How to Start Using Aegis

For the first-time user, Aegis can appear to bevery daunting. It has a huge number of configura-tion alternatives for each project, and it is difficultto know where to begin.

It is assumed that you already have Aegisinstalled. Ifyou do not, see the section of theRef-erence ManualcalledThe BUILDING File. Thisreproduces theBUILDING file included in theAegis source distribution.

3.1. First,Create The Project

You need to create a new project. Follow theinstructions in theHow to Create a New Projectsection, and then return here.

3.2. Second,Use a Template Project

The very first time you use Aegis, it will be easi-est if you download one of the template projects.This gives you a project which (almost always)works correctly the first time “out of the box”.

• The template projects can be found on theAegis home page: http://-www.canb.auug.org.au/˜millerp/-aegis/

• If you are a long-time GNU Make user, youprobably want the Make-RCS template, at leastto start with.

• Follow the instructions found on the web pageand you will have a working Aegis project,complete with self tests.

• From this starting point, create changes (thetkaenccommand is good for this, as it givesyou a simple GUI) and try modifying the calcu-lator, or adding more programs to the project.

• The template projects is intended to be gener-ally useful. Many users have simply retainedthis format and inserted their own projects intoit. (Use a change to delete the calculator andits tests.)

3.3. Second,Copy a Template Project

If this isn’t the very first time, you may wish toget more adventurous, and try copying the rele-vant bits out of a working project.Usually, whensites first try this, the working project will be oneof the template projects from the previous section.

• Create a new project. For this exercise, youprobably want a single user project.

• Create a new change

• Copy the projectconfigfile, and and files refer-enced by it, such as the new file templates andthe build configuration file (Makefile orHowto.cook, depending).

• Copy the sources of the existing project into thedevelopment directory. If you have sev eral lev-els of directories, reproduce this, too.

• Remove files which are not primary sources(e.g. the generated C sources of you have yaccinput files).

• Using the “aenf .” command (yes, that’s a dot,meaning “the current directory”) you can tellAegis to add all of the source files in the devel-opment directory to the change set.

• You will probably need to modify your buildmethod to meet Aegis’ expectations. Ratherthan do this immediately, change thebuild_command in the projectconfig file toread “build_command = "exit 0"; ”and fix it in the next change set.

• Now, build, develop end, review and integrate,as found in theUser Guideworked example.(Except, of course, there is only one member ofstaff.)

• Create a second change, and copy the projectconfiguration file (calledaegis.confby default),and the build configuration file (probablyMakefileor Howto.cook) into the change.

• This would be a good time to read theDepen-dency Maintenance Tool chapter of the AegisUser Guide, and alsoRecursive Make Consid-ered Harmful(see the author’s web site) if youhaven’t already.

• Edit the build configuration, try theaeb com-mand; it will probably fail. Iterateuntil thingsbuild correctly.

• dev elop end, review and integrate as normal.Your project is now under Aegis.

Page 6 (bl/lib/en/howto/main.ms) Peter Miller

Aegis Howto

4. How to Recreate Old Versions

It is possible to recreate old versions of yourproject. This is done using the delta numberassigned to every completed change.

4.1. aecp

Recreating the sources is usually done to recreatea bug. To this end, it is also usually done fromwithin an existing change.Theaecp(1) commandis used to copy histprical file versions into achange.

The aecp(1) command has some options whichare used to perform the source recreation:

−DELta numberThis option tellsaecp(1) to extract an histori-cal version of the files, rather than the headrevision (the one visable in the baseline).You need to know the delta number of thechange, assigned at integration time, not thechange number.

−BRanchnumberIf the historical version is on a differentbranch than the one the current change is on,use this option. The branch number is to theleft of the "D" in version strings.

−DELta-From-Change numberThis option tellsaecp(1) to extract an histori-cal version of the files, rather than the headrevision (the one visable in the baseline).You only need the change number to use thisoption.

−DELta-Date " string"This option tells aecp(1) to extract an his-torical version of the files, rather than thehead revision (the one visable in the base-line). You only need the date the changewas integrated to use this option.It under-stands many forms of written (English)dates, but try to avoid ambiguous monthnumbering (it can be confused by someEuropean vs. American numeric formats,use month names instead).

4.2. FindingDelta Numbers

You can find delta numbers in a number of ways:

• The “ael change-details” command will listchange details. If changes are completed, theirdelta number will appear at the top of the listing.

• The “ael project-history” command lists all inte-gration for a project, including their change num-bers and delta numbers.

• The aeannotate(1) command lists the filesource, annotationg each line with the developer,the date and the version. To the right of the "D"in the version is the delta number.

• The #{version} substitution (seeaesub(5) formore information) is covered in the next section.

In addition, you may need to use the−BRanchoption, if the historical version is on a differentbranch than the one the current change is on.Thebranch number is to the left of the "D" in versionstrings.

4.3. ${version}

Thebuild_commandfield in the projectconfigfilemay be given the ${version} substitution, whichyou may use to embed the version string into yourexecutables. You could, for example, have thisstring printed when yoiur program is given the−versioncommand line option.For example:

% aegis --versionaegis version 4.15.D012%

Armed with this version string, you can recreatethe sources for the version being executed. Thecommand

% aecp --change=4.15.D012 .%

would be issued from inside a suitable change.This form of theaecp −changeoption combinesthe −BRanch and −DELta options into a singlecommand line option.

4.4. OutOf Date

Once you have recreated your sources and rebuiltyour project, and presumably fixed the bug youwere hunting, there are a couple more steps.

• The first is to remove unchanged sources.Dothis with the

% aecpu -unchanged%

command. Thisremoves from your change allfiles which were not changed by this change.This cuts down on the clutter and makes the nextstep much easier.

• The next step is to merge the files. Because youare working with historical versions of the files,Aegis will think they are out-of-date and wantyou to merge them.Do this is the usual way(using the aem(1) command). Remember thatAegis will stash a backup copy with a “,B” suffixbefore merging.

Peter Miller (bl/lib/en/howto/recreate.so) Page 7

Howto Aegis

You may find the following command

% ael cf | grep ’(’%

useful for finding out-of-date files.

• Once Aegis thinks all the files are up-to-dateyou then need to rebuild and retest before com-pleting development.


Aegis Howto

5. How to Create a New Project

Before you can do anything else with Aegis, youneed a project to do it to.The advantage of this isthat each project is administered and configuredindependently.

If this is your first time using Aegis, you probablywant a single-user project.You can change thenumber of users later, if you ever want to addmore staff to the project.

You need to select the name with some care, aschanging the project name later is tedious.Adding aliases, however, is simple.

5.1. SingleUser Project

A single suer project is one where all of the dif-ferent staff roles are filled by the same person,and a number of interlocks are disabled, as youwill see in a moment.

Unfortunately, there is no Tcl/Tk GUI for this,yet, which makes this documentation bigger thenit needs to be.

Don’t do anything yet! Read through all of thesteps first.

• You may want to read theaenpr(1) man pagefor more information.

• The command “aenpr name -version -” willcreate the project with no branches. This willautomatically make you (that is, the executinguser) the project administrator and the projectowner. Theumaskis remembered, too.

• The root of the project directory will be in yourhome directory, named after the project name.If you want something else, use theaenpr--directoryoption.

• The default group at the time of executiondetermines the file group of the project.Makesure the account created for the project has thecorrect group. (Even if you don’t understandthis, your system administrator should.)

• The umaskat the time of execution determinesthe group access to the project.Even if youusually work with a restrictive umask, set it tothe right one for the project before running thisaenprcommand.

• For additional security, it is often veryuseful tocreate a UNIX user for each project.You mayneed to consult your system administrator forassistance with this. It is usual to name theuser and the project the same thing, to avoidconfusion. Login as this user to execute theinitial project creation commands; once

completed no one will ever login to thisaccount again.

• Add the staff to the project: the “aenayour-normal-login ” command adds your normalaccount as a project administrator. You needthis if you are using a special project account,so that your normal self can administer theproject.

• At this point, log out of the special projectaccount. Askthe system administrator to per-manently disable it.

• Add the rest of the staff: the “aend your-login ” command makes you a developer, the“aenrvyour-login ” command makes you areviewer and the “aeni your-login ” com-mand makes you an integrator.

• You need to edit the project attributes next.The “aepa -edit” command does this.You willbe placed into a text editor, and will see some-thing similar to this:

description = "The \" example\" project";developer_may_review = false;developer_may_integrate = false;reviewer_may_integrate = false;developers_may_create_changes = false;umask = 022;

Ignore any extra stuff, you should not change itat the moment.To get a single user project,edit the field to read

developer_may_review = true;developer_may_integrate = true;reviewer_may_integrate = true;developers_may_create_changes = true;

Be extra careful to preserve the semicolons!You may also want to change the description atthis time, too.Don’t forget the closing double-quoteandsemicolon.

• Create the first branch now. They inherit allstaff and attributes at creation time, which iswhy we worked on the trunk project first.Thecommand “aenbr name 1” f ollowed by fol-lowed by “aenbr name.1 0” will give you abranch calledname.1.0 for use wherever Aegiswants a project name.(See the branchingchapter of the User Guide for more informa-tion.)

5.2. Two User Project

Everything is done as above, except you want toproject attributes to look like this:

Peter Miller (bl/lib/en/howto/new_project.so) Page 9

Howto Aegis

developer_may_review = false;developer_may_integrate = true;reviewer_may_integrate = true;developers_may_create_changes = true;

This says that developers can’t review their ownwork.

You will need to add the other person to thedeveloper, reviewer and integrator roles, too.

Converting a single user project to a two personproject is simply editing the project attributes tolook like this later. Remember:each branchinherited its attributes when it was created − youneed to edit the ancestor branches’ projectattributes too.

5.3. Multi User Project

Everything is done as above, except you want toproject attributes to look like this:

developer_may_review = false;developer_may_integrate = false;reviewer_may_integrate = false;developers_may_create_changes = true;

This says that developers can’t review their ownwork, and reviewers can’t integrate their ownreviews. This ensures the maximum number ofeyes validate each change.

You will need to add the other staff to the appro-priate developer, reviewer and integrator roles.Staff need to always be permitted all roles: it iscommon for junior staff, for example,not to beauthorized as reviewers.

Converting a single user project to a multi-personproject is simply editing the project attributes tolook like this later. Remember:each branchinherited its attributes when it was created − youneed to edit the ancestor branches’ projectattributes too.

5.4. Warning

The /usr/local/com/aegis/statefile contains point-ers to "system" projects.Pointers. Users mayadd their own project pointers (to their ownprojects) by putting a search path into theAEGIS_PATH environment variable. Thesystempart is always automatically appended byAegis.The default, already set by the/usr/local/lib/-aegis/cshrcfile, is $HOME/lib/aegis. Do not cre-ate this directory, Aegisis finicky and wants to dothis itself.

Where projects reside is completely flexi-ble, be they system projects or user projects.They are not kept under the/usr/local/com/aegis

directory, this directory only contains pointers.

5.4.1. Creating Projects

When you create a new project, thefirst elementof the AEGIS_PATH is used as the place toremember the projectpointer. This means theproject will not show up in the global project listif you have set AEGIS_PATH to include privateprojects.

There are two ways to make sure that you are cre-ating a global project. Either “unsetAEGIS_PATH” i mmediately before using the“aenpr” command, or use the “--library/usr/local/com/aegis” option of the aenpr com-mand.

5.4.2. Web Visibility

If you have a Web server, you make like to installthe Aegis web interface. You do this by copyingthe aeget program from/usr/local/bin/aeget intoyour web server’s cgi-bin directory. There is aaeget.instalhelper script, if you don’t know whereyour web server’scgi-bindirectory is.

You may prefer to use a symbolic link, as this willbe more stable across Aegis upgrades.However,this requires a correspondingfollow-symlinksset-ting in your web server’s configuration file. (Usetheaeget.instal −soption.)

If you have a Web server, and aeget wasinstalled, you can use a wrapper script to set theAEGIS_PATH environment variable, if you wantit to be able to see more projects than just theglobal projects.

5.5. ChangingThe Project Owner

Typically, when folks try Aegis for the first time,they don’t worry about having a separate user fortheir projects. However, once things are tickingalong, it is less and less attractive to toss it all andstart again cleanly. So, now you need to changethe project owner from the user who started theAegis evaluation to the unique project useraccount.

1. You need to beroot to perform this procedure.

2. Createthe user account.It doesn’t need towork to login, so the password can be dis-abled. You probably want to arrange to havethis user’s email forwarded somewhere sensi-ble (maybe see the Distributed Developmentchapter of the User Guide).

3. The owner of the project is taken from theowner of the project directory tree, so this is

Page 10 (bl/lib/en/howto/new_project.so) Peter Miller

Aegis Howto

what needs to be changed.Go to the root ofthe project tree - the directory which appearsin the “ael projects” l isting. This isn’t thetrunk baseline, but the directory above it (youwill see info, historyandbaselinesub-directo-ries).

4. Usethe command

chown -R username.

to change the ownership of this directory, andall files and sub-directories below it. Insertthe username of the account you created instep 2. (You need thedot on the end of thecommand, its not mere punctuation.)

There is no need to change the owner ofany active changes, or any other change attributes.


Howto Aegis

6. How to Move a Project

By "move a project", you may wish to change theproject’s name but leave the project files in thesame location, or you may wish to change aprojects directory location and leave it with thesame name. This section covers both.

There are two ways to move a project. Oneisfrom within Aegis, and one is from outside Aegis.Each section below covers both methods.

6.1. Relocatinga Project

This section deals with moving a project’s filesfrom one file system location to another.

6.1.1. From within Aegis

This works best when you are moving a projectfrom one machine to another. It is a very goodidea if there are no active changes onanybranch.

Step 1: You need to know where in the file systemthe project currently resides.Take a look in theprojects list (ael p) and see the directory reportedfor the trunk of the project.Ignore any activebranches.

Step 2: Usually, when you remove a project,Aegis deleted all of the project files.However theaerm −keep option tells Aegis to remove theproject name, but keep all of the project files.

Step 3: Move the files to their new location, youneedall of the files below the directory tree youfound in step 1. This may be a simple file move,or may involve copying the files to tape, and thenunpacking on a new machine. Remembertomake sure the file ownerships are set the way youwant (usually, this means "preserved exactly").

Step 4: Tell Aegis where the project is.To dothis, use the −dir and −keep options of theaenpr(1) command.

6.1.2. From outside Aegis

This works best of the project is staying on thesame machine, or the same NFS network.


Step 2: Move the files to the new location.

Step 3: Edit the /usr/local/com/aegis/state file andedit the path appropriately to tell Aegis where youmoved the files to. You will need to be root forthis step.

6.2. Renaminga Project

This section deals with changing a project’s namewithout moving is files.

6.2.1. From within Aegis


Step 2: Usually, when you remove a project,Aegis deleted all of the project files.However theaerm −keep option tells Aegis to remove theproject name, but keep all of the project files.

Step 3: Tell Aegis where the project is, using thenew name. To do this, use the −dir and −keepoptions of theaenpr(1) command.

6.2.2. From outside Aegis

Step 1: Edit the /usr/local/com/aegis/state file andedit the name appropriately to tell Aegis the newname of the project.You will need to be root forthis step.

6.2.3. Project Aliases

You may need some transition time for yourdevelopers. Eitherbefore or after you rename theproject, you may want to consider adding aproject alias (seeaenpa(1) for more information)so that the project has "both" names for a while.


Aegis Howto

.


Howto Aegis

7. Working in Teams

Aegis supports teamwork in two basic ways: localdevelopment and distributed development. Localdevelopment breaks down into a single machine,and networked machines on a common LAN.Bybuilding the description a little at a time, this sec-tion will show how each of these modes of devel-opment are related in the model used by Aegis.

7.1. Local

7.1.1. SingleUser, Single Machine

The simplest case to understand is the single user.In such an environment, there is a project and theuser makes changes to this project in the usualway described in the User Guide and earlier sec-tions of this How-To.

Even in this environment, it is often the case thata single user will be working on more than onething at once.You could have a large new featurebeing added, and a series of bug fixes happeningin parallel during the course of this development.Or some-one may interrupt you with a moreimportant feature they need to be added.Aegisallows you to simply and rapidly create as manyor as few independent changes (and developmentdirectories) as required.

By using independent work areas, things whichare not yet completed cannot be confused withimmediate bug fixes. Thereis no risk of untestedcode "contaminating" a bug fix, as would be thecase in one large work area.

7.1.2. Multi User, Single Machine

Having multiple developers working on the sameproject is very little different than having onedeveloper. There are simple many changes allbeing worked on in parallel. Each has its ownindependent work area. Each is independentlyvalidated before it may be integrated.

One significant difference with multiple develop-ers is that you now hav eenough people to do realcode reviews. Thiscan make a huge difference tocode quality.

7.1.3. Multi User, Multi Machine

Aegis assumes that when working on a LAN, youwill use a networked file system, of some sort.NFS is adequate for this task, and commonlyavailable. Byusing NFS, there is very little dif-ference between the single-machine case and themulti-machine case.

There are some system administration constraintsimposed by this, however: it is assumed that eachmachine is apparently "the same", in terms ofenvironment.

7.1.3.1. GeneralRequirements

You need some sort of network file system (e.g.NFS, AFS, DFS), but it needs working locks (i.e.not CODA at present). I’ll assume the ubiquitousNFS for now.

• You need exactly the same/etc/passwdand/etc/groupfile on every machine. This gives auniform environment, with uniform security.(It also gets the UIDs right, which NFS needs.)Keeping /etc/passwdand /etc/group in syncacross more than about 3 machines can be timeconsuming and error prone if done manually -so don’t. Use NIS or similar - do sys adminonce, automatically takes effect everywhere.

• All of the machines see the same file systemswith the same path names as all the others.(Actually, you only need worry about the onesAegis is interested in.)Again, you can try tokeep all those/etc/fstabfiles in sync manually,but you are better off using NIS (or NIS+) andthe automounter or amd.

• All of the machines need their clocks synchro-nized. Otherwisetools which use time stamps(obviouslymake(1), but also a few others) willget confused. NTP or XNTP make this simpleand automatic.In a pinch, you can userdate(1)from cron every 15 minutes.

• Many sites are worried about the security ofNFS. Usually, you need to take the root pass-word away from workstation users; once theenvironment is uniform across all of them, theneed for it usually disappears.It also meansthey can’t abuse NFS, and they can’t run packetsniffers, either. By using netgroups (I’mnottalking about the/etc/groupsfile) you can fur-ther restrict who NFS will talk to. By usingNIS+ and NFSv3 you can quash the last coupleof security issues, but unless you have militarycontracts, it’s rarely worth it.

Fortunately, NFS and NIS readily available, bothfor proprietary systems and open source systems.Large sites use these techniques successfully andsecurely - and they don’t have O(nˆ2) or evenO(n) sys admin issues, they get most sys admintasks down toO(1).

But, but, but! Many sites arevery concernedabout being able to work when the server(s) are

Page 14 (bl/lib/en/howto/team_work.so) Peter Miller

Aegis Howto

down. I agree, however I suggest sweet talkingyour sys admin, not bashing NFS or NIS orAegis. It is possible to get very high availabilityfrom modern systems (and even ancient PCs,using Linux or BSD).

The fact is, working in a team requires interac-tion. Lotsof interaction. It is an illusion that youcan work independently indefinitely. In the ulti-mate siege mentality, you need a full and com-plete private copy of everything in order to pullthis off; but expect the other team member tocarefully inspect everything you produce this way.

7.1.3.2. Aegis-specificRequirements

There are a couple of things required, once youhave the above up and running.

• All of the Aegis distribution can be installedlocally for performance, if that’s what youneed. (Except,see the next item.) Or, you caninstall it all on an NFS mounted disk, whichguarantees everyone is always running exactlythe same software revision which can some-times be important (shortens upgrade times,too.)

• Except the${prefix}/com/aegisdirectory, whichmust be the one NFS disk mounted by everysingle machine identically, and must be readwrite. I.e. unique to the whole network (well,all machines using Aegis). This is where thepointer to the projects are kept, and this iswhere the database locks are kept. If this direc-tory isn’t common to every machine, the Aegisdatabase will quickly become corrupted.

• The project directory tree must be on an NFSdisk which all machines see, and must be thesame absolute path on all machines.This is sothat the absolute paths in ${pre-fix}/com/aegis/statemean something.

• The development directories need to be on NFSdisks every machine can see.Usually, thismeans a common home directory disk, or acommon development directory disk. This canstill be a disk local to the workstation, but theymust all be exported, and all must appear in theautomount maps. This is because Aegisassumes that every workstation has a uniformview of the entire system (so reviews canreview your development directory, and inte-grators can pick up the new files from yourdevelopment directory).

Large software shops have used these techniqueswithout difficulty.

7.1.4. Known Problems

There is a known problem with the HP/UX NFSclients. If you see persistent "no locks available"error messages when/usr/local/lib/aegisis NFSmounted, try making the/usr/local/lib/aegis/lock-file file world writable.

chmod 666 /usr/local/lib/aegis/lockfile

There is the possibility of a denial of serviceattack in this mode (which is why the default is0600) but since you are presently denied serviceanyway, it’s academic.

7.2. Distributed

The distributed functionality of Aegis is designedto be able to operate through corporate firewalls.Corporate firewall administrators, however, take avery dim view of adding holes to the for propri-etary protocols.Aegis, as a result, requires none.Instead it uses existing protocols such as e-mail,FTP and HTTP. It will even work with "sneakernet" (hand carried media).

The other aspect of Aegis, which you have proba-bly noticed already, is that it is very keen on secu-rity. Security of the "availability, integrity andconfidentiality" kind.

Incoming change sets are subject to the samescrutiny as achange set produced locally. It isdropped into a work area, built and tested, beforebeing presented for review. Just like any localchange set would be.

7.2.1. Multiple Single-User Sites

In the case of an Open Source project maintainer,this is essential, because incoming contributionsare of varying quality, or may interact in unfortu-nate ways with other received change sets.Thiscareful integration checking is essential.Imagingthe chaos which could ensure if change sets wereunconditionally dropped into the baseline.(Deliberate malice or sabotage, of course, alsobeing a grim possibility.)

The careful reader will by now be squirming."How", they wonder, "can the maintainer examineev ery change every developer makes. Surelyitdoesn’t scale?"

Indeed, it would not.Aegis provides a mecha-nism for aggregating changes into "superchanges". Theselarger changes can then beshipped around. (See the Branching chapter inthe User Guide for more information.)

Peter Miller (bl/lib/en/howto/team_work.so) Page 15

Howto Aegis

In the reverse direction, from the maintainer outto the developer, dev elopers in an Open Sourceproject probably aren’t going to want to see eachand every change set made to the project.Again,they can use an aggregation (e.g. grab the latestsnapshot when each release is announced) to re-sync in larger chunks, less often. The chances ofan intersection are fairly low (otherwise someoneis duplicating effort) so the merge is usually quitesimple.

7.2.2. Multiple Multi-User Sites

Most distributed large-scale corporate operationsare actually similar to Open Source projects,though they usually have more staff. There isusually a "senior" site, and the other sites maketheir contributions, which are scrutinized care-fully before being promoted to full acceptance.

Again, aggregations become essential to the sys-tem integration phase of a product.There mayev en be a hierarchy of concentrators along theway.

Junior corporate sites can sync periodically withthe senior site, too, rather than double handle (orworse) every change set.

7.2.3. Telecommuting

One of the most desired cases is that of telecom-muting. How do remote worker, who may nevermake it into the office, develop projects usingAegis?

There are many way to do this, but the simplest isto have a central cite ("the office") with satellitedevelopers.

7.2.3.1. Officeto Developer

The office makes available a web interface toAegis. Fromthis, it is possible to download indi-vidual changes, branch updates, or wholeprojects. All of this is already present in theAegis distribution.

However, many corporate sites are not going towant to make all of their intimate developmentdetails to comprehensively available on the web.For such sites, I would suggest either a direct"behind the firewall" dial-in, or some virtual pri-vate networking software (which means users canuse a local ISP, and still be treated "as if" theywere behind the firewall).

If a VPN won’t fly (due to company security poli-cies), then selected encrypted updates could beposted "outside", or perhaps an procmail "change

set service" could be arranged.

7.2.3.2. Developer to Office

It is unlikely (though possible) that you wouldhave a web server on the developer’s machine -usually you aren’t connected, to the office pullingchanges sets back is probably not viable.

The simplest mechanism is for the satellite devel-oper to configure their Aegis project so that thetrunk tracks the office version. Oncea week (ormore often if you get notified something signifi-cant has happened) pull down the latest version of"the office" as a change set and apply it.Thisway, the trunk tracks the official version.

The developer works in a sub-branch, withaeipass configured to e-mail branch integrations(but not individual change sets) back to the office.In this way, a work package can be encapsulatedin a branch, and sent when finished.You alsohave the ability to manually send the branch atany earlier state, and it still encapsulates the set ofchanges you have made to date.


Aegis Howto

.


Howto Aegis

8. How to use Aegis with Python

This section describes how to use Aegis to super-vise the development of Python programs.Someof the remarks in this section may also be helpfulto people who use Aegis to supervise develop-ment in other non-compiled languages.

This section is contributed courtesy of TangibleBusiness Software, www.tbs.co.za . Python-specific questions relating to this section may besent to Pieter Nagel at<[email protected]> .

8.1. HandlingAegis search paths

8.1.1. TheAegis model vs. the Python model

Aegis’ view of a project is that it consists of ahierarchy of project baselines. Each baseline con-sists of only those files that were modified as partof that (sub)project, plus all files that were builtby the DMT (see the section of theUser Guidecalled The Dependency Maintenance Tool).Aegis expects the DMT to be able to collect theentire project into one piece by searching up thisbaseline search path for all needed files.

This works fine when using statically compiledlanguages such as C.The build process "projects"source files from various Aegis baselines onto oneor more executables. Whenthese are run they donot need to search through the Aegis search pathfor parts of themselves; they are already com-plete.

Python programs, however, are never compiledand linked into a single executable. Onecouldsay that a Python program is re-linked each timeit is run. This means that the Python program willneed to be able to find its components at run-time.More importantly, it will need to avoid importingthe old versions of files from the baseline whennewer versions are present in the development orintegration directories.

8.1.2. Thesolution

The simplest (and only recommended) way tomarry Aegis and Python is to configure Aegis tokeep all of the project’s files visible in a the devel-opment and integration directories, at all times.That way Aegis’ search path becomes irrelevantto Python.

Use Aegis version 3.23 or later, and set the fol-lowing in the projectconfigfile:

create_symlinks_before_build= t rue;

remove_symlinks_after_integration_build= f alse;

The second directive is not available in earlierversions of Aegis.

If you keep your Python files in a subdirectory ofyour project, such assrc/python, you will needthat directory’s relative in your PYTHONPATHwhenever Aegis executes your code for testing,i.e. by setting

test_command="\PYTHONPATH=$$PYTHONPATH:src/python \python ...";

in your project configuration file (example splitacross multiple lines for formatting only).

It may seem strange to you that we are not substi-tuting the Aegis Search_Path variable intoPYTHONPATH at all − it does at first seem to bethe solution that is called for. The reason why wedon’t is very simple:it does not work. It is worthstressing the following rule:

Never i nject any absolute path of any Aegisbaseline into the Python search path.

8.1.3. Why setting PYTHONPATH to theAegis search path will not work

The reason why PYTHONPATH does not work asAegis expects is due to the way Python searchesfor packages. For a full explanation of whatpackages are, you can seeSection 6.4of thePython Tutorial, but the crucial point is that aPython package consists of a directory with an__init__.py file in which the other files in thatdirectory which should be treated as part of thatpackage are listed.

When Python imports anything from a package,Python first searches for the__init__.pyfile andremembers the absolute path of the directorywhere it found it. It will thereafter search for allother parts of the package within the same direc-tory. Without the create_symlinks_before_buildandremove_symlinks_after_integration_buildset-tings enabled, all the needed files are not guaran-teed tobe present in one directory at all times,however; they will most likely be spread out overthe entire Aegis search path.

The result is that if you were to try and use theapproach of setting thePYTHONPATH to theAegis search path, package import will mysteri-ously fail under (at least) two conditions:

Page 18 (bl/lib/en/howto/python.so) Peter Miller

Aegis Howto

• Whenever you modify a file in a package with-out modifying the accompanying __init__.py,Python will find the__init__.pyfile in the base-line and import theold files from there.

• Whenever you modify the __init__.py andleave some other file in the package unmodi-fied, Aegis will find the __init__.py in thedevelopment/integration directory but fail tofind the unmodified files there.

8.2. Thebuild step

Python programs do not need to be built, com-piled, or linked before they can be run, but Aegisrequires a build step as part of the developmentcycle.

One perfectly valid option is to explicitly declarethe build step to be a no-op, by setting

build_command = "true";

in the project configuration file.true(1) is a Unixcommand which is guaranteed to always succeed.

In practice, however, there often are housekeepingchores that can be done as part of the build pro-cess, so you can just as well go ahead and create aMakefile, Cook recipe, or script that performsthese tasks and make that your build step.

Here are some examples of tasks that can be per-formed during the build step:

• Setting the executable flag on your mainscripts. Aegis does not store file modes, but itis often convenient to have one or more of thePython source files in your project beexecutable, so that one does not need to invokePython explicitly to run them.

• Delete unwanted Python object files (.pyc and.pyo files). Thesecould arise when you aermand delete a Python script, but forget to deletethe accompanying Python object file(s).Otherfiles will then mysteriously succeed in import-ing the removed scripts, where you wouldexpect them to fail. Your build process coulduseael -cfandael -pf) to get a list of ’allowed’scripts, and remove all Python object fileswhich do not correspond to any of these.

• Auto generate your packages__init__.pyfiles.Python wants you to declare your intent to havea directory treated as a package by creating the__init__.py file (otherwise a stray directorywith a common name like ’string’, ’test’, ’com-mon’ or ’foo’ could shadow like-named pack-ages later on in the search path). But sinceAegis is, by definition, an authoritative source

on what is and what is not part of your programit can just as well declare your intent for you.

8.3. Testing

Testing under Aegis using Python is no differentfrom any other language, only much more fun.Python’s run-time type checking makes it mucheasier to develop software from loosely-coupledcomponents. Suchcomponents are much moresuited to unit testing than strongly-coupled com-ponents are.

If the testing script which Aegis invokes is part ofyour project, there is one importantPYTHON-PA TH-related caveat: when Aegis runs the tests, itspecifies them with an absolute path.WhenPython runs any scripts with an absolute path, itprepends that path to its search path, and the dan-ger is that the baseline directory (with the old,unchanged versions of files) is prepended to thesearch path when doing regression testing.

The solution is to use code like this to remove thetest’s absolute path from the Python path:

selfdir = os.path.abspath(sys.argv[0])if selfdir in sys.path:

sys.path.remove(selfdir)

Instead of copying these lines into each new testfile, you may want to centralize that code in a testharness which imports and runs the tests onAegis’ behalf. This harness can also serve as acentral place where you can translate test successor failure into the exit statuses Aegis expects.

The test harness must take care to import the fileto be tested without needing to add the absolutepath of the file tosys.path. Use imp.find_moduleandimp.find_module.

I can strongly recommendPyUnit, the PythonUnit Testing Frameworkby Steve Purcell, avail-able from http://pyunit.source-forge.net . It is based on Kent Beck and ErichGamma’s JUnit framework for Java, and isbecoming thede-factostandard testing frameworkfor Python.

One bit of advice when usingPyUnit: like Aegis,PyUnit also distinguishes between test failures asopposed to test errors, but I find it best to reportPyUnit test errors as Aegis test failures. Thisis toensure that baseline tests fail as Aegis expectsthem to. PyUnit will consider a test which raisesanything other than aAssertionError to be an’error’, but in practice baseline test failures areoften AttributeError exceptions which arise whenthe test invokes methods not present in the old

Peter Miller (bl/lib/en/howto/python.so) Page 19

Howto Aegis

code. Thisis a legitimate way to verify, as Aegiswants us to, that the test does indeed invoke andtest functionality which is not present the oldcode.

8.4. Runningyour programs

Of course you will at some stage want to run theprogram(s) you are developing.

The simplest approach is to have your program’smain script be located at the top of your Pythonsource tree (src/python) in our example. When-ev er you run that script, Python will automaticallyadd the directory it was found in to the Pythonpath, and will find all your other files from there.

You can safely let your shell’s PA TH environmentvariable point to that script’s location, since theshell PA TH and thePYTHONPATH do not mutu-ally interfere.

Just avoid the temptation to set the absolute pathof that script into yourPYTHONPATH, or other-wise your development code and baseline codewill interfere with each other. This is not anAegis-specific problem, though, since there wouldbe potential confusion on any system, in any lan-guage, where two versions of one program aresimultaneously visible from the same search path.


Aegis Howto

.


Howto Aegis

9. Howto End A Branch

“OK, I give up. I do not understand the ending ofbranches.”

Usually, you end development of a branch thesame way you end development of a simplechange. Inthis example, branchexample.1.42will be ended:

% aede -p example 1 -c 42aegis: project "example.1": change42: file " fubar" in t he baselinehas changed since the last ’aegis-DIFFerence’ command, you need todo a merge%

Oops. Somethingwent wrong. Don’t panic!

I’m going to assume, for the purposes of explana-tion, that there have been changes in one of theancestor branches, and thus require a merge, justlike file fubar, above.

You need to bring filefubarup-to-date. How?You do it in a change set, like everything else.

At his point you need to do 5 things: (1) create anew change on example.1.42, (2) copyfubar intoit, (3) mergefubarwith branch "example.1" (4)end development of the change and integrate it,and (5) now you can end example.1.42

The -GrandParent option is a special case of the-BRanch option.You are actually doing a cross-branch merge, just up-and-down rather than side-ways.

% aem -gp fubar%

And manually fix any conflicts... naturally.

At this point, have a look at the file listing, it willshow you something you have nev er seen before -it will show you what it isgoing toset thebranch’s edit_number_origin to for each file, ataeipass.

% ael cfType Action Edit File Name------ ------ ------- -----------source modify 1.3 aerect/rect.c

{cross 1.2}

Now finish the change as usual...aeb, aed, aede,aerpass, aeib, ..., aeipassnothing special here.

One small tip: merge file files one at a time. Itmakes keeping track of where you are up to mucheasier.

Now you can end development of the branch,because all of the files are up-to-date.

In some cases, Aegis has detected a logical con-flict where you, the human, know there is none.Remember that theaemcommand saves the oldversion of the file with a,B suffix (‘B’ forbackup). Ifyou have a file like this, just use

% mv fubar,B fubar%

to discard everything from the ancestor branch,and use the current branch.


Aegis Howto

.


Howto Aegis

10. How to Become an Aegis Developer

This section describes how to become an Aegisdeveloper, and gives some procedures, some ideasof areas which need work, and some generalguidelines.

Please note: if these instructions have a problem,let someone know! If you are having a problem,so is the next guy.Pleasesend all problemreports to Peter Miller<[email protected]>

10.1. Required Software

There are a number of pieces of software you willneed to work on Aegis.

• It will probably come as no surprise that Aegisis developed using Aegis (never trust a skinnychef) so the first thing you need is to installAegis and become familiar with using it.Youwill need Aegis 4.24 or later.

• You will need a C++ compiler. If your com-piler is installed in an uncommon directory orhas an uncommon name, you can set the appro-priate attribute by editing theaegis.conf.d/site.conffile.

• You will need to install Cook, in order to buildthings. Version 2.8 or later, preferably youshould track the latest release.http://www.canb.auug.org.au/˜millerp/cook/

• GNU Autoconf 2.53 or later.http://ftp.gnu.org/pub/gnu/autoconf/If your tools are installed in an uncommondirectory or have an uncommon name, you canset the appropriate attribute by editing theaegis.conf.d/site.conffile.

• GNU Automake.http://ftp.gnu.org/pub/gnu/automake/

• You will need to install FHist, for the historytool.http://fhist.sourceforge.net/

• You will need to installtardy, for manipulatingtarballs.http://miller.emu.id.au/pmiller/software/tardy/

• You will need to installptx(1), for the permutedindexes in the documentation. This is now partof GNU coreutils.http://ftp.gnu.org/pub/gnu/coreutils/

• You need psutils for thepsselectutility, tomanipulate the documentation files, mostly toput the tables of contents at the start, ratherthan at the end as GNU Groff generates them.http://www.dcs.ed.ac.uk/home/ajcd/psutils/

• You will need the developer libraries for therxlibrary (if you installed from the tarball, youhave these, but if you installed from RPM, youneed the −devel package as well).http://ftp.gnu.org/pub/gnu/rx/

• You will need the developer libraries for thezlib library (if you installed from the tarball,you have these, but if you installed from RPM,you need the −devel package as well).http://www.gzip.org/zlib/

• You will need the developer libraries for thelibcurl library (if you installed from the tarball,you have these, but if you installed from RPM,you need the −devel package as well).http://curl.haxx.se/

• You need UUID generation capability. Thisrequirement may be satisfied in several differ-ent ways depending of your development plat-form.First, on GNU/Linux you could skip thisrequirement provided that your kernel has sup-port for /procfilesystem. Pleasenote: in orderto work /procmust be mounted and/proc/sys/kernel/random/uuidmust be present.Second, you could install the developerlibraries for thee2fsprogs package (if youinstalled from the tarball, you have these, but ifyou installed from RPM you need the −develpackage as well).http://e2fsprogs.sourceforge.net/Third, you could install the UUID library fromOSSP:http://www.ossp.org/pkg/lib/uuid/Fourth, if your platform has support for an APIcompliant with DCE 1.1, Aegis also supportsthe DCE API.

• The GNOME libxml2 library (http://xml-soft.org/ ) is used to parse XML, you willneed version 1.8.17 or later. You do not have toinstall the rest of GNOME as this library is ableto be used by itself. This package isnotoptional, you need it to successfully buildAegis.

• You need to install Bison, the GNU replace-ment for Yacc.http://ftp.gnu.org/pub/gnu/bison/

• You will need to install Flex, the GNU replace-ment for Lex.http://ftp.gnu.org/pub/gnu/non-gnu/flex/

• You need to GNU Gettext (0.16.1 or later) toolsinstalled. Even though Glibc 2.0 and laterinclude Gettext, you need the developer tools

Page 24 (bl/lib/en/howto/developer.so) Peter Miller

Aegis Howto

as well. (You need GNU Gettext even onSolaris, because the Solaris Gettext implemen-tation is less than adequate.)http://ftp.gnu.org/pub/gnu/gettext/

• You need GNU Ghostscript, for the ps2pdf util-ity, so that you can create PDF documents.http://ftp.gnu.org/pub/gnu/ghostscript/

• You need auudecodewith a -o option (to redi-rect the output). It is part of GNU Sharutils.http://ftp.gnu.org/pub/gnu/sharutils/

• You need to install GNU awk.http://ftp.gnu.org/pub/gnu/gawk/

• You need actags(1) command with a-L option(to read file names from standard input).http://ctags.sourceforge.net/

• You need RCS installed for the automated tests.http://ftp.gnu.org/pub/gnu/rcs/

• You need to installsudo(8). Seeetc/set-uid-root in the distribution for how to con-figure the/etc/sudoersfile.ftp://ftp.sudo.ws/pub/sudo/

• The location box icon is generated usingcon-vert from ImageMagick, but the build can copeif you don’t hav eit.http://www.imagemagick.org/

• The PNG images are optimized by thepngcrushcommand.http://pmt.sourceforge.net/pngcrush/

• The location box icon is generated usingpng2icobut the build can cope if you don’thave it.http://www.winterdrache.de/freeware/png2ico/

• It is possible to use the dmalloc library fordebugging memory abuses. Bewarned: thedmalloc library can be instructed to log to afile, circumventing the Aegis I/O layer, thus it’spossible to create file owned by root. Thedmalloc library should only ever be used as adebugging tool, andneverbe used in a produc-tion build of Aegis.http://dmalloc.com/On a Debian system, use theapt-getinstall libdmalloc-dev command.You will need to aecp theetc/Howto.cookfile to alter the build to use the dmalloc library.

• Probably more things I’ve forgotten.

• Some parts of the build need Perl

10.2. Create The Aegis Project

The next thing to do is create an Aegis project tohold the Aegis source. This is done in the usual

way. I suggest you create branches which matchthe current public release,e.g.it is 4.24 at present.

The best-practice technique of having a separateuser account to mind the sources is recom-mended. Thefollowing commands should be runas that user, not your usual login. This prevents avariety of accidents which can happen when youare browsing the baseline (master source).

You could use the following command:

% aenpr aegis.4.24aegis: project "aegis": createdaegis: project "aegis.4.24": created%

but experienced Aegis users will know that thismeans a laborious setting of project attributes. Itis easier to create the top-level project, set theattributes, and the create the branches, so that theyinherit the attributes on creation.

% aenpr aegis -version -aegis: project "aegis": created% aepa -e -p aegisedits the project attributes for single user,or you may findtkaepa easier% aena -p aegis youaegis: user " you" is n ow a administrator% aend -p aegis youaegis: user " you" is n ow a developer% aenrv -p aegis youaegis: user " you" is n ow a reviewer% aeni -p aegis youaegis: user " you" is n ow an integrator% \f[CB]aenbr -p aegis 4\fPaegis: project "aegis.4": created% \f[CB]aenbr -p aegis.4 24\fPaegis: project "aegis.4.24": created%

At this point, the rest of the commands in thischapter may (should!) be executed as “you,” yourusual login account. When you added your nor-mal account as an administrator just now, youauthorized yourself to perform the necessaryactions.

You will need about 120MB of free space to buildand integrate Aegis changes, or more, dependingon the changes you make and the size of yourdevelopment directories.

The.forwardfile of the “aegis” user needs to beset to someone appropriate to read mail directedat the project.

You can now set the “aegis” user’s password fieldto “*”. This effectively prevents the “aegis” userfrom logging in. Aegis is designed to make thisunnecessary from now on.

Peter Miller (bl/lib/en/howto/developer.so) Page 25

Howto Aegis

10.3. TheDownload

The Aegis project is distributed in the form of anaedist(1) change set. The file to download iscalledhttp://aegis.sourceforge.net-/aegis-4.24.ae and can be grabbed usingyour favorite web browser, or wget(1).

The downloaded change set is applied using thefollowing command

% aedist --receive \-f aegis-4.24.ae \-p aegis.4.24

...lots of output...%

It is a good idea to give the project name on thecommand line, oraedistwill try to use the projectname it finds in the change set, and it probablywont find it if you are using different numberingto the chief maintainer’s copy.

Theaedistcommand will, in turn, issue a numberof other commands. These are all normal Aegiscommands you could issue yourself, if you werefamiliar with Aegis. Itwill, however, stop with amoderately alarming message:

Warning: This change contains files whichcould host a Trojan horse attack.Youshould review it before building it or testingit or completing development. Thischangeremains in thebeing developedstate.

This message comes because in order to build theproject, you are going to have to execute a num-ber of commands contained in the projectaegis.conffile, and in theetc/Howto.cookfile.For your own protection,aediststops at this point.You may want to inspect these two files beforecontinuing.

I really must get around to signing it with PGP.This would make the −notrojan option safe,because you could tell the file is direct from thechief maintainer, and thus as trustable as youthink the chief maintainer happens to be.

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

% ae_p aegis.4.24% aecd% aeb...you will see commands which build the project...%

Things that can go wrong...

• There are checks to make sure that there is nowhite space on the ends of lines. If you useEmacs, you can add

(add-hook ’write-file-hooks’delete-trailing-whitespace)

to have this done automagically. The samechecks also verify that the text files are allprintable, and that line lengths are 80 charac-ters or less. Please don’t disable the checks, itmakes accepting your patches more time con-suming.

• Each change set has an architecture list associ-ated with it. Initially you won’t care, but Aegisdoes if you see the following error message:

found 1 unlisted architecture, edit thechange attributes to remove it or edit theproject configuration file to add it

You need to use theaeca -ecommand (not thetkaeca command).You will be placed into aneditor (usuallyvi unless you have used Aegisbefore, and know how to configure it differ-ently). You need to leave just about everythingalone, except for the architecture specification.Change it from

architecture =[

"unspecified",];

to something more meaningful on yourmachine. For PC users, this is almost always

architecture =[

"linux-i386",];

The alternatives may be found in theconfiginthe current directory (search forarchitec-ture = ). If you can’t see a suitable choice,you may need to add one; theaepconf(5) manpage has more information. Edit theconfigfileto contain a suitable entry, and then use theaeca -ecommand to have the change agreewith it.

• If you don’t hav eCook installed, the buildcommand (aeb) will fail.

• If you don’t hav eGNU Bison installed, thebuild will fail.

• If you don’t hav eGNU Gettext installed, theerror message run-time binaries will not bebuilt. This isn’t an error, so you can keepgoing, but you’ll get the shorter, cryptic form ofthe error messages.

• Please note: if these instructions have a prob-lem, let someone know! If you are having aproblem, so is the next guy.Pleasesend allproblem reports to Peter Miller


Aegis Howto

<[email protected]>

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


• If you don’t hav ethe FHist package installed,the difference (aed) will fail. Thefcompcom-mand it is looking for is a whole-file contextdifference command (the GNUdiff -c is abit too terse for humans).

Now you will need to test the change. This is thebasic test suite for Aegis, it ensures nothing isbroken. Ittakes a while, go grab a cup of coffee.

% aet...lots of output...%

The change is now ready to end development.

% aedeaegis: project "aegis.4.24": change 10:

development complete%

The change set is now ready to be reviewed. Inasingle-person project like this one, you can reviewyour own work. Obviously this is a conflict ofinterest, and larger projects are usually configuredto have Aegis prevent this.

% aerpass -p aegis.4.24 -c 10aegis: project "aegis.4.24": change 10:

review pass%

The change is now ready to be integrated. Onlywhen integration is complete are the files actuallycommitted to the repository.

% aeib -p aegis.4.24 -c 10% aeb...you will see commands which build the project...-rwsr-xr-x 1 root ... arch/bin/aegis-rwsr-xr-x 1 root ... arch/bin/aeimport-rwsr-xr-x 1 root ... arch/bin/aelockIntegrator: please do the following:

sudo .../baseline/etc/set-uid-root arch aegis aeimport aelockif they aren’t root already. See etc/set-uid-root forinstructions for how to set-up your /etc/sudoers file.

%

This message at the end of the build is whereAegis is made set-uid-root in the repository. Youwant to do this, because you are going to symlinkout of /usr/local/bin(or wherever you installed

Aegis) right into the baseline. In this way, youwill be executing your bleeding-edge version ofAegis, exercising it before you send it to anyoneelse. Hangon a bit, the sending part comes later.

Don’t know how to set these files set-uid-root?The above message includes the command to doit:

$ cd blahblah/delta*$ sudo etc/set-uid-root arch aegis aeimport aelock$

You will need to substitute the appropriate archi-tecture name, although it is likely to be “unspici-fied on a fresh project.


• If you don’t hav eps2pdfor psselector ptxinstalled, it won’t build the documentation (thisisn’t an error, just keep going).

• If you don’t hav etardy(1) install, it won’t buildthe tarball (this isn’t an error, just keep going).

• Please note: if these instructions have a prob-lem, let someone know! If you are having aproblem, so is the next guy.Pleasesend allproblem reports to Peter Miller<[email protected]>

If all is OK, continue with the integration...

% aed...you will see commands which "diff" the project...% aet && aet -bl...lots of output...% cd% aeipass...you will see commands committing the files to fhist...aegis: project "aegis.1.0": change 10:

integrate pass%

The “cd” command you see is actually important:you need to be out of the development directoryand integration directory so that they can becleaned up (deleted) when the change completes.

10.4. SupportingSeveral Architectures

Aegis is able to track architectures to make surethat change sets have been built and tested on allnecessary architectures.You may hav notices thatAegis is calling your architecture “unspecified”,you can give it a more descriptive name, too.

The architecture configuration data is described inthearchitecturefield of theaepconf(1) man page.It is based on theuname(2) data, see the man pagefor how. You will, of course, need a change set tochange it.


Howto Aegis

Once you have a change set, you need to createtheaegis.conf.d/architecturefile.

% aenf aegis.conf.d/architecture% aefa aegis.conf.d/architecture entire-source-hide% aefa aegis.conf.d/architecture local-source-hide%

Here are some suggestions for what you may liketo set for your architecture or architectures.

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*";

},];

Remember to only include the architectures fromthe above list that you actually have. Havingarchitectures in this list that you don’t routinelyhave access to means that you will not be able toaede(1) any change sets.

Occasional architectures can be handled, too:

architecture =[

{name = "ppc-Darwin-7.x";pattern = "Darwin-7.*-Darwin*";mode = optional;

},];

Again, only do this with architectures you actu-ally have access to.

If you need to have architecture specificoptions to some commands, you can also haveproject_specificattributes, too.Note that youshouldfirst look into having a$pre-fix/share/config.site or $pre-fix/etc/config.site file for ./configuretoread. Thisis particularly important if you want toinclude/usr/local/include, /usr/local/lib, etc, inthe various compiler flags.

10.5. TheBleeding Edge

As I mentioned above, the next thing to do is cre-ate symbolic links out of/usr/local/bininto yourAegis baseline. The reason for doing this is sothat you exercise your Aegis changes by usingAegis before you send them to anyone else.(Never trust a skinny chef.)

There is a shell script calledae-symlinksin thebaseline$arch/bin direcdtory. Use it like this:

$ aecd -bl# suPassword:# linux-i486/bin/ae-symlinks aegis.4.24# exit$

The linux-i486may need to be replaced with theoutput of theaesub -bl ’$arch’ command if youare using something more interesting than a PC.

10.6. Undiscovered Country

If you got this far, your local Aegis project isready for use.

It is strongly suggested that you complete the firstchange “as is” and perform your own customiza-tions in later changes, rather than trying to get theproject started and customize it at the same time.

The rest of this file describes how to perform vari-ous common changes to the example project.

10.7. SendingChanges

First, read the Distributed Development chapter ofthe User Guide.


Aegis Howto

When you have a change set you wish to have theother Aegis deveopers try, use a simple commandsuch as:

aedist --send -p aegis.4.24 -c number | \gpg --clearsign | \mail [email protected]

or similar. (Or maybeaepatch(1) instead.) Asuitable subject line would be very helpful.

10.8. Guidelines

10.8.1. WhatYou Can Do

Write more documentation. There is a cryingneed for documentation of all sorts: better manualpages, more and better information in the UserGuide, more and better HOWTOs. If you workout how to do something, and it isn’t in the docu-mentation, write some documentation and put itin a change set because other folks have probablymissed it too.

Add more ease-of-use functionality. Stuff whichmakes the development process more efficient, ormakes the information in the repository moreaccessible.

Extend the GUI. All of the commands whichmanipulate the change while in thebeing devel-opedstate are candidates. Some kind of wrapperthat ties it all together would be good, too. Userpreferences, project attributes and creatingprojects are candidates, too.

Most new project configuration things belong inthe projectconfigfile. Onlyadd new projectattributes (aepa -e) for things which (a) are catch22 to change in a change set, or (b) allow a secu-rity abuse if in a change set (e.g. the notify com-mands, particularly aede), or (c) allow the reposi-tory to be damaged. (My thanks to Ralf Fassel<[email protected]> 2 Feb 1999 for pointing thisout.)

10.8.2. WhatYou Can’t Do

You can’t change Aegis’ semantics. Developersaround the world, and their managers, rely onAegis working just the way it does right now.You can’t change things that will compromisetheir ability to get things done.

Particularly, Aegis has a strong security story.Av ailability, integrity and confidentiality, and allthat. If you want it more flexible, that’s good, butyou can’t change the defaults and you can’t makeit irretrievably weaker. (You can, as anon-defaultmake it weaker, within limits.)

Aegis (the executable, not the whole package) isquite big enough. Don’t add code toarch/bin/aegis than can be done with thereport generator, or as a separate program likeaesub or aefind . More GUI can be addedusing Tk/Tcl - unless you have grander plans andev en then itstill shouldn’t be added to the set-uid-root executable.

10.9. CodingStyle

Please try to emulate the existing coding style.(Indents recently changed from 8 to 4, not all ofthe code has caugh-up yet.) Lines are to be 80charcters or less wide, limited to the 95 printableASCII characters, with no trailing white space.

Probably need a GNU Indent profile for code for-matting, too.

10.10. Writing Tests

If you have fixed a bug you should write a test toverify the correct behaviour of Aegis. Becausetest file names are generated automatically start-ing from your repository state, it’s possible thataetwill create a test with the same name as one inthe P.Miller repository. Because Aegis is not yetable to detect such situation, if you plan to sendback your work to P.Miller you may want to mod-ify your aegis.conf adding the followinglines:

new_test_filename ="test/${zpad $hundred 2}/""t${zpad $number 4}${left $type 1}-${left ${user login} 4}.sh";

In this way the possibility of a name collisionshould be reduced. Invokeaent:

% aentaegis: appending log to "aegis.log"aegis: user "walter", group "projadm"aegis: rm -f etc/cook/change_filesf etc/cook/project_filesaegis: project "aegis.4.16.2": change 11: file "test/01/t0157a-walt.sh" new test%

Now you can start to implement the test. Remem-ber to invoke the programs under test as$bin/program .

• In order to improve error messages you shouldorganize your script as a sequence of activityand use theactivityvariable as sketched below:


Howto Aegis

## c reate a new change#activity="new change 163"cat > tmp << ’end’brief_description = "The first change";cause = internal_bug;endif test $? -ne 0 ; then no_result; fi$bin/aegis -nc 1 -f tmp -p foo > log 2>&1if test $? -ne 0 ; then cat log; no_result; fi

If you are reading this document, you probablydon’t need help to understand this code frag-ment, the only thing to note is that the numberin the string (163) refer to the current line num-ber and is used when printing a failure mes-sage. You don’t need to maintain it by hand asexplained in the following step.

• You can usetest/activity.sh to auto-matically renumber the activity variables ofyour tests:

$ sh test/activity.shtest/01/t0159a-walt.sh...test/01/t0160a-walt.sh...$

If you have not modifiedtest/activ-ity.sh you should find it asbl/test/activity.sh orblbl/test/activity.sh .

10.11. Debugging

Aegis, as any other software, may contain undis-covered bugs. Ifyou are interested in helping tofix these bugs, and as a developer you should beinterested, the first thing to do is compiling Aegisin DEBUG mode. In order to do so you mustmodify common/main.h and uncomment theDEBUG define. (If you use theaecp −read-onlyoption, Aegis will remind you to uncopy the fileagain before develop end, ensuring that you don’taccidentally integrate this.)

In DEBUG mode the −Trace command lineoption is available for most Aegis commands.This option is followed by the names of thesource files you want to trace, and may be usedmore than once.

If you need to add tracing capability to a file, youmust first includetrace.h , modify the code inorder to use the trace facility (look atcom-mon/trace.h ) then build the change withaeband run the buggy command with the proper−Trace option.

On Linux >= 2.4 theaegiscommand, wich is set-uid-root, is enabled to dump core when needed.

If this does not happen, remember to verify theulimit(1) settings; you may need to execute theulimit −c unlimitedcommand.

10.12. TheTo-Do List

• Add an additonal mode toaedistto query anaeget server for change set UUIDs and down-load and apply missing change sets. It needs tobe able to be run bycron(8). Submitted:PMiller, 1-Jun-2004

10.12.1. aecvsserver

• The aecvsserver needs to be extensively testedby users. Submitted: PMiller, 1-Jun-2004

• Implement more of the CVS client commandswhich can be sent to the server, usually by say-ing "yes, bwana" and doing nothing. Submit-ted: PMiller, 1-Jun-2004

• Implement a cvs commit against a project (atthe moment this is not allowed because youhave to use a "module" named after a changeset) which will create a change set apply thechanges and do everything to get to aede. Sub-mitted: PMiller, 1-Jun-2004

• Is it possible to use the same techinique towrite an SVN server? Submitted:PMiller,1-Jun-2004

• Is it possible to use the same techinique towrite an arch server? Submitted:PMiller,1-Jun-2004

• Arch has the concept (if not the implementa-tion) of an SCM-neutral interchange format.Implement it. Submitted: PMiller, 23-Jan-2004

10.12.2. GeographicallyDistributed Develop-ment

• Theaedist −receivecommand needs to beenhanced to understand file attributes. Submit-ted: PMiller, 2-Jun-2004

• Theaepatch −receivecommand needs to beenhanced to understand file attributes. Submit-ted: PMiller, 2-Jun-2004

• Enhance theaedist -receivecommand to under-stand incoming files with UUIDs. Submitted:PMiller, 1-Jun-2004

• Enhance theaepatch -receivecommand tounderstand incoming files with UUIDs. Sub-mitted: PMiller, 1-Jun-2004

• Add an additonal mode toaedistto query anaeget server for change set UUIDs and down-load and apply missing change sets. It needs to

Page 30 (bl/lib/en/howto/devel_to_do.so) Peter Miller

Aegis Howto

be able to be run bycron(8). Submitted:PMiller, 1-Jun-2004

• Enhanceaedistto preserve change history(both send and receive will need work). Don’tforget backwards compatibility. Submitted:Jerry Pendergraft, 2003

• Enhanceaedist -receiveto leave changes inawaiting developmentor being developedifthat’s the state they were in at the origin. Sub-mitted: Jerry Pendergraft, May-2004

• Enhanceaepatch -receiveto run tests onchanges which require it. Submitted: PMiller,1-Jun-2004

• Enhanceaepatchto preserve change history(both send and receive will need work).Incoming patches with no meta-data obviouslycan’t do this. Don’t forget meta-data back-wards compatibility. Submitted: PMiller,1-Jun-2004

• Enhanceaepatch -receiveto leave changes inbeing developedif that’s the state they were inat the origin.Patches with no meta-data stay inbeing developed. Submitted: PMiller,1-Jun-2004

• Enhanceaepatchandaedistto automagicallysign (send) and verify (receive) the contents,using the (revolting) library from thegpgmeproject. Thisstupid library spawns angpg(1)instance and talks to it; unlike a sensible librarye.g.thezlib project; why on earth couldn’t theytake the common code from gpg and make alibrary of that? Submitted: PMiller,1-Jun-2004

10.12.3. Documentation

• Add a section to the branching chapter of theUser Guide, describing how a dev eloper mayuse a branch to temporarily waive the buildcommand. Aftera series of changes on thisbranch, the build command is restored, and thebranch development ended. This allows regu-lar "non working" commits, without losing anyof the strengths of the Aegis process. Submit-ted: 7-Mar-2000

• The manual pages need to have an example(s)section added to make them clearer. This isn’tjust for beginners, infrequently used commandsneed examples even for sophisticated Aegisusers.. Submitted:Geoff Soutter<[email protected]>, 3 Mar 2000

• Get tkdiff 3-way merge working with Aegis(seehttp://www.ede.com/free/-

tkdiff/ for code). Submitted: 24-jan-2000

• Add information to the History Tool chapter,describing how to use CVSup to access theRCS history tree. Submitted: 28-jan-2000

• the RCS history commands in the aegis userguide all use the ‘-u’ option for ‘ci’ to checkout a copy after registering/updating a file.However ‘ci -u’ always does keyword expan-sion. To avoid this, we have omitted the -u, sothe working file is gone after the ‘ci’.Wecheck it out again using ‘co’, this time with the‘-ko’ option to avoid keyword expansion. Notethat the -ko option is always given to the ‘co’command, never to ‘ci’ or ‘rcs’. Submitted:Ralf Fassel <[email protected]>, 18 Jan 2000

• * diff ; test $? -le 1 -> diff ; test $? -ne 1 meansthat unchanged files prevent aede!! (Only fly inthe ointment is moving files - need to cope withthis.) Submitted:Gus <[email protected]>28 Jul 1999

• mention in the diff tool part of the User Guide,that you can mess with diff_command toexclude with binary files, or file with CR inthem, or lines too long,etc. Submitted:PMiller, 28-jun-99

• in the branching chapter, hav ea section aboutusing sub-branches to turn build_command off(or to ignore exit status), and integrate lots ofteensy tiny bug fixes, and then turn it on again.In the front, reference the branching chapter in“how to extend the Aegis process” Can men-tion extra review steps there, too. Submitted:[email protected], 22 Jun 1999

• Document the build_time_adjust_notify_com-mand in the DMT chapter of the User Guide.Update the example projects to use it. Updatethe config example to use it. Submitted:PMiller, 4-Apr-99

• Mention binary files in the diff and merge sec-tion (may provide aebinfil command to helpchoose which behavior?) Submitted:PMiller,31-mar-99

• mention “rcs -ko” in the User Guide and put itinto the examples AND also fhist keywords inthe User Guide and put it into the examples.and make sure the examples all havehist_{put,create} the same. Subject: Ralf Fas-sel <[email protected]>, 9 Mar 1999

• worked example, “5.2.7 says that the cook filecontains all of the above commands but mycopy doesn’t hav ethem ...” [ for config file andhowto.cook file] BUT integration diffs not in

Peter Miller (bl/lib/en/howto/devel_to_do.so) Page 31

Howto Aegis

the worked example. Submitted:MichaelMcCarty <[email protected]>,26-Feb-99

• need discussion (Howto, or maybe the UserGuide) of how to use Aegis when you site has amix of Unix and Wintel. Submitted:PaoloSupino <[email protected]>, 4 Feb 1999

• add chapter to User Guide, saying how to con-fig web interface and how to use it. Submitted:Graham Wheeler <[email protected]>, 27 Jan1999

• User Guide: big changes bouncing: how to usea branch to get smaller reviews and smallerdiffs. Submitted:Ralf Fassel<[email protected]>, 27 Jan 1999

• note for User Guide: metrics software formftp://ftp.qucis.queensu.ca/pub/software-eng/-software/Cmetrics/

• correct documentation of file locking in UG:correct the example around the file locking - itgives the wrong text of the aede error - andprobably other stuff. also,the wrong personcomes back from aerobics

10.12.4. More Reports

• Add a -REVerse option, so that all of the list-ings (ael) come out in the reverse order to thatused at present. Submitted: John Darrington<[email protected]>, 20-Jul-2001

• Write anaereportfile to produce MS-Projectviews of a project, making sure that the statesof each change are linked, use averages to pre-dict any incomplete states. And maybe anotherto produce HTML pages of the same thing.Submitted: 15-Jan-2000

• On theaeget(1) web pages, link the file editnumbers to pages which will retrieve the histor-ical version. Submitted:Anoop Kulkarni<[email protected]>, 22 Dec 1999

• Add a user_change report (just like “aeluser_changes”) which takes a user name, soyou can get a list of changes by user. Makeaeget(1) do this, too. Submitted: Ralf Fassel<[email protected]>, 9 Dec 1999

• Add a outstanding_changes report (just like“ael outstanding_changes”) which takes a username, so you can get a list of outstandingchanges by user. Makeaeget(1) do this, too.Submitted: Ralf Fassel <[email protected]>, 9Dec 1999

• Write a report which says when you have to doto get a change completed Jerry says he haswritten most of this. Submitted: [email protected] 3-Nov-99

• ael change_history - write as a report and theninclude project history for sub branches. Don’tforget the web reports, too. Submitted:JerryPendergraft <[email protected]>, 30 Aug1999

• ael outstanding_changes - rewrite as a reportand then include sub branches. Don’t forgetthe web reports, too. Submitted: Jerry Pender-graft <[email protected]>, 30 Aug 1999

• ael project_history - rewrite as a report andthen include parents and sub branches. Don’tforget the web reports, too. Submitted: JerryPendergraft <[email protected]>, 30 Aug1999

• aer file_history - include parents and subbranches. Don’t forget the web reports, too.Submitted: Jerry Pendergraft <[email protected]> 30 Aug 1999

• Some kind of web report which makes “traintrack” diagrams of file branching.

• Some kind of web report which makes “traintrack” diagrams of project branching.

• multivariate linear regression: needed as areport generator function: needed for metricsanalysis

• more blurb in the statistics web pages, so theyare more self-explaining Submitted: Ralf Fassel<[email protected]>, 13-Oct-98

• Add anew report like “ael uc” except that it(optionally) takes a user name as well, to list aparticular user’s changes.

• File Activity Report (web) does not translateuser name and give email link. Should also putuser name under change state, as in changelists.

10.12.5. Core Enhancements

• Use the per-file attributes to record the encod-ing of the text (e.g. UTF-8) and the line termi-nation. Provide a way (via the iconv(3) func-tion? via recode(1) command?) to change theencoding. Submitted:PMiller, 23-Jun-2004

• "I hav edetermined that one reason [that aedeuis used in preference to aerfail] is the revieweris afraid they don’t understand the change andonce explained they would not fail it. Now thefact that the description, comments etc did not


Aegis Howto

do the job to explain the change is reasonenough to fail it notwithstanding... They aresaying if they had an aerfu command theywould be willing to aerf changes. How difficultwould that be?" Not very difficult at all. Pro-vided, of course, that nothing has been changedin the mean time (and Aegis has everything itneeds to check that). Submitted: Jerry Pender-graft, 23-Jun-2004

• The project_file_roll_forward function needs tobe enhanced to understand file UUIDs. Sub-mitted: PMiller, 1-Jun-2004

• Now the sources are all being compiled by aC++ cimpiler, convert the various OO portionsof the code (inout_ty and its derived classes,output_ty, etc) to true C++. Need a style guidefirst, so other developers know how I want itdone. SeeSRecord for examples until this isdone. Submitted:PMiller, 1-Jun-2004

• More doxygen comments in the header files.Submitted: PMiller, 23-Jan-2004

• Add a "development directory style" configura-tion option. The current styles are "view path"and two types of "symlink farm", although thisis well concealed by the code. Need to add ahard link (arch-ish) / copyfile (cvs-ish) style aswell, but only for source files. The code whichcurrently maintains the symlinks can bepressed into doing the extra work fairly easily.Submitted: PMiller, 1-Jun-2004

• It would be nice to have a way to specify atimeout for aegis tests. If a single test does notfinish within this time, it should be aborted andconsidered ‘No Result’. Then aet should con-tinue with the next test (as appropriate if --per-severe was given). A ‘--timeout’ argument to‘aet’ would do the trick, and also a project con-fig field. The implementation could be interest-ing, since signaling the forked aegis child pro-cess might not be enough to stop all processes(process groups?). Submitted: Ralf Fassel<[email protected]>, 24-Jan-2001

• Problem with aepa that doesn’t specify thedefault values for all the test features in aeca(there are three types in aeca and only one inaepa). Submitted:Mark Veltzer<[email protected]>, 16 Aug 2001

• Theaedist(1) program should send changeswith no files, or changes in "being developed".Submitted: Mark Veltzer<[email protected]>, 16 Aug 2001

• Hav eaemmerge changes properly if anotherchanged moved the file in the baseline.Youneed to do this across the board, not just inaegis/aed.c Submitted: Ralf Fassel<[email protected]>, 25 Feb 2000

• Add progress (%) indicators (aeib was specificexample, but there may be otherse.g.symlinkfarms and aecp, even aede for big changes) foruse by the GUI interfaces - and maybe the textinterface too. Submitted: Ralf Fassel<[email protected]> 10 Dec 1999

• Extend the create_symlinks_before_build func-tionality to copy, not just symlink. Becausethey would edit the files direct, we then need animplicit aecpcorne detector. You need to lookfor other boundary conditions this is also goingto affect. You need a remove_sym-links_after_build analogue, too. Submitted:Darrin Thompson <[email protected]>, 15 Nov 1999

• os.h is a system header on some systems, soos.h has to move Sumbitted: Christophe Broult<[email protected]> 30 Sep 1999

• aedist -rec needs to preserve (a) copyrightyears, (b) test exemptions (subject to permis-sions), and (c) architecture (if possible). ANDCHANGE NUMBER? Submitted: EwoltWolters <[email protected]>, 27 Jul1999

• Aedist to add project history to end of descrip-tion when sending change set. Submitted:Jerry Pendergraft <[email protected]>,Dec-2000

• can we separate change creation from otheradministrator permissions? can we make"everyone" able to create changes? Submitted:Ewolt Wolters <[email protected]>, 28Jun 1999

• should explicitly mentionCPPFLAGS=-I/usr/local/include; exportCPPFLAGS LDFLAGS=-L/usr/local/lib;export LDFLAGS in the configuring section.Submitted: John Huddleston<[email protected]>, 19 Mar 1999

• Using file attributes, add coupling between filesto form file groups; this means when you aecp,you get the whole set of related files. Submit-ted: PMiller, 18-Feb-99

• The aed command does not promoteaenf->aecp unless the ,D file does not exist.This is annoying, should always do it. (Soshould some other commands.) Subject: Ralf

Peter Miller (bl/lib/en/howto/devel_to_do.so) Page 33

Howto Aegis

Fassel <[email protected]>, 1 Feb 1999

• Add a default_regression_test_exemptionproject attribute. Submitted:Ralf Fassel<[email protected]>, 31 Jan 1999, JerryPendergraft <[email protected]>, 2 Feb2001.

• Need a clean_exceptions file in the project con-fig file (list of strings) so can have local RCSdirs, and do "ci ‘aegis -l cf -ter‘" in thedevelop_end_command Submitted: 1-Feb-99

• aenpr -dir -keep: allow directory to alreadyexist if has right owner and is empty? Submit-ted: Jerry Pendergraft <[email protected]>, 22 Jan 1999

• Add a new post_merge_command so can gen-erate summary of files needing editing. Sub-ject: Ralf Fassel <[email protected]>, 21 Dec1998

• Create a new aepatch command: “aepatch-send” to create "ordinary" OpenSource sourcepatches, and “aepatch -receive” to turn patchesinto an Aegis change - and not necessarily onlypatches generated with aepatch.Yes, intention-ally similar to aedist.

• integrate difference should look for missing ,Dfiles (usually impossible) and re-instate them.Submitted: PMiller, 22-Sep-98

• tests 7, 20, 70 warn symlink.c: In function‘main’: symlink.c:5: warning: return type of‘main’ is not ‘int’ Submitted: Bruce StephenAdams <[email protected]>,10 Sep 1998

• change_set_env needs to set LINES and COLS

• commands which accept -branch and/or -trunkshould also accept -grandparent but not all do.check.

• Add a --no-baseline-lock option to the aeb andaecp commands.Warn them not to in the man-ual pages.

• list locks - need to spot the case where *all* ofa set are taken (all 64k) and report sensibly (not64K lines)

• aemv does not correctly check the -to- file-name. (specificexample = file name length)

• aefind needs a sort option

• aefind needs the rest of the find functionalityadded

• * Add a -output option to the aent command(others?) for scripting support.

• aed - when auto upgrade create to modify, clearmove if set.

• aede needs to make sure that the files (anddirectories) are readable (and searchable) byreviewers.

• make aemv rename files within a change

• aecp -anticipate

• Make the listing more specific for aecp aecpuaenfu aentu aerm aermu, etc

• add a file copy notification command to theproject config file

• Add pseudo change do can do many integra-tions at once (this pseudo change would be cre-ated by aeib and destroyed by aeipass, aeifail oraeibu).

• Version punctuation: at the moment you getsdots between the branch numbers. Need moreflexible punctuation: especially, want a hyphenfirst, then dots (sometimes).

• * aecp -delta bug “I’ve been makinggood use of the "-delta" option of aecp lately.

But there has been a complication in itsuse. Let’s say a file was aerm’ed in delta100. Let’s further say that we are at delta

175 and are trying to restore the sourcecode as of delta 75. If I do a "aecp -delta 75 file.c" I’m told that file.c is no

longer part of the project.” Should aecp-del fake aenf for deleted files in earlier deltas?Submitted: [email protected]

• internationalize -interactive

• Enhance aet to allow reviewers to run tests.

• check library state files on project creation“I was creating a new release from a

large project. After copying thebaseline and creating hundreds of history

files the aenrls failed becausethe librarydir I specified wasn’t writable by aegis and no

state file was created. Couldn’t this bechecked first?” Submitted: Lloyd Fischer<[email protected]>

• Add precedence constraints: a list of prerequi-site changes, which must all be in the “com-pleted” state before the change may end devel-opment. Submitted:Christian F. Goetze <[email protected]>

• If there is a read error when reading the tem-plate source file during aent, get a stupid errorwithin error message, and never tells you aboutthe file


Aegis Howto

• How about "include" support for the configfile? Thatway one could also cover architec-ture specific things by “include ${lib-dir}/${project}.defs” in the config file. Sub-mitted: Jerry Pendergraft <[email protected]>, 7 Sep 2001

• Add anaetouchcommand, to touch all of the(non-build) source files in the change. Submit-ted: 2001

• Hav ethe “aeclean -list” option say whataeclean would do, rather than list the changesource files. Submitted: 2001

• Hav eaed (aem) *remember* the previous statewhen it finds a problem (much like aet does,now). Submitted:Ralf Fassel<[email protected]> 3-Mar-2002

10.12.5.1. More O(1) Scalability

• Need to supplement the{project,change}_file_find and{project,change}_file_nth interfaces with{project,change}_file_name_nth interfaces.Then, use them as often as possible.

• Need the fstate file to have a manifest field;access this for file names. Then, store each fileinto in a separate file; only access this file is filestate is required.

• The presence or absence of the manifest field inthe top-level fstate file tells you if the old ornew file state usage is present.

10.12.6. GUI

• tkaeca barfs when there are no changes on thebranch. shouldbe more graceful. Submitted:Ewolt Wolters <[email protected]>, 11Aug 1999

• using tkaegis: project > branch > role > inte-grate, a window pops up "Error in tcl script,Error: invalid command name".mbar.review.menu"". Submitted:EwoltWolters <[email protected]> 9 Aug1999

• user pasted in text (including back slash) intoaeifail edit window. which was accepted, butbroke change state (illegal escape sequence).Submitted: Michael McCarty <[email protected]>, 10 May 1999

• A new ${architecture_list} substitution to giveall architectures in a command. Submitted:[email protected], 31 Mar1999

• hav eaedist -rec accept a -delta option, so youcan tell it where to apply from. Anticipated useis “-delta 0” meaning start of branch. (also a-reg option). Submitted:PMiller, 22-mar-99

10.12.7. Releaseand Build and Install

• add debian.deb file, add notification to<[email protected]> for new releases. Submitted:PMiller, 22-Jun-99

• building documentation needs to talk about libzsome more. particularly, you either need it onROOT’s LD_LIBRARY_PATH or you need tostatic link it. Submitted: Ralf Fassel<[email protected]> 5-Apr-99

• hav econfigure script whine about missing libzSubmitted: PMiller, 7 Apr 99

• hav econfigure script whine about missing reg-comp Submitted: PMiller, 7 Apr 99

• Sample documentation needs to make thegroupthing obvious. Andalso the umask ataenpr time! Submitted: Alan Zimmerman<[email protected]>, 5 Apr 1999

• generated makefile CC=cc needs to quote cc incase has spaces Submitted: Aaron Johnson<[email protected]>, 31 Mar 1999

• The BUILDING file needs to mention that youshould install zlib with --prefix=/usr becausemany systems think /usr/local/lib "insecuredirectory". Submitted:Fabien Campagne<[email protected]>, 26 Mar 1999

• add piece to BUILDING file saying to getApache first. Submitted: Graham Wheeler<[email protected]> 27 Jan 1999

10.12.8. Database

• Write an ODBC interface to the database?Submitted: P. Miller, 16 Aug 2001

• Does it make sense to have an NNTP interface?Would it be any use? Submitted:P. Miller, 16Aug 2001


Howto Aegis

.


Aegis Howto

.


aegis a project change supervisor - sourceforge

Documents