





.













                           Aegis

                A Project Change Supervisor




                           HOWTO







                        Peter Miller

                  _m_i_l_l_e_r_p_@_c_a_n_b_._a_u_u_g_._o_r_g_._a_u































Howto                                                  Aegis


.






This document describes Aegis version 4.24.2
and was prepared 3 August 2025.






This  document  describing  the Aegis program, and the Aegis
program itself, are
Copyright (C) 1991, 1992,  1993,  1994,  1995,  1996,  1997,
1998,  1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
2008, 2009 Peter Miller

This program is  free  software;  you  can  redistribute  it
and/or  modify  it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 3 of the License, or (at your option) any later ver-
sion.

This program is distributed in the hope that it will be use-
ful, but WITHOUT ANY WARRANTY; without even the implied war-
ranty of MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR-
POSE.   See the GNU General Public License for more details.

You should have received a copy of the  GNU  General  Public
License    along    with   this   program.   If   not,   see
<http://www.gnu.org/licenses/>.






















Page 2          (lib/en/howto/introductio.so)   Peter Miller





Aegis                                                  Howto


11..  IInnttrroodduuccttiioonn

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

When  printing this manual, it is essential to print it dou-
ble sided, or the "subject at once" effect will not occur.

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

11..11..  AAssssuummeedd KKnnoowwlleeddggee

Many of these sections are written for use by beginners,  so
there  is a fairly low level of assumed knowledge.  However,
you may want to have _T_h_e _A_e_g_i_s _U_s_e_r  _G_u_i_d_e,  and  _T_h_e  _A_e_g_i_s
_R_e_f_e_r_e_n_c_e  _M_a_n_u_a_l very close by, as all of the material con-
veyed here is available in a more expended or detailed  form
on those manuals.

11..22..  HHoowwttoo IInnssttaallll AAeeggiiss

The  description of how to build, test and install Aegis may
be found in the Reference  Manual,  under  the  heading  _T_h_e
_B_U_I_L_D_I_N_G  _F_i_l_e,  which reproduces the BUILDING file included
in the Aegis source distribution.

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

11..33..  HHoowwttoo CCoonnttrriibbuuttee

If  you  would  like  to see other "How To" subjects, please
drop me an e-mail.  Better yet, write one and e-mail  it  to
me.



















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





Howto                                                  Aegis


22..  CChheeaatt SShheeeett

This  page  is  a quick reference into the common Aegis com-
mands.

+o Usually, "man  _c_o_m_m_a_n_d___n_a_m_e"  can  be  used  to  get  more
  details on a particular command.

+o See  also  the  official Aegis quick reference in the User
  Guide, page 88.

+o The "-p _n_a_m_e" option is used to specify the project  name.

+o The  "-c _n_u_m_b_e_r" option is used to specify the change num-
  ber.

+o The "-l" (or "-List") option can often  be  used  to  list
  subjects  for  the  given  command  (eg. change numbers or
  projects) or simply to list rather than edit (_e_._g_. a  file
  or change attributes).

22..11..  CCoommmmoonn CCoommmmaannddss

ae_p _p_r_o_j_e_c_t_-_n_a_m_e_._b_r_a_n_c_h_-_n_u_m_b_e_r
        Set  current  project number for all following Aegis
        commands.  The ae_p command with no  arguments  will
        `unset' this forced default.

ae_c _n_u_m_b_e_r
        Set  current  change  number for all following Aegis
        commands.  The ae_c command 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.

aedless View difference files generated with aed.

ael cd  List change details.

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

tkaenc  Create a new change (see _a_e_n_c(1) for details), using
        a  GUI interface.  This makes it a damn sight easier
        to type in the description field.




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





Aegis                                                  Howto


tkaeca  Edit change attributes (see  _a_e_c_a(1)  for  details),
        using  a  GUI interface.  This makes it a damn sight
        easier to edit the description field.

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

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

ael cf  List all of the files in a change.

_a_e_u_c_o_n_f(5)
        This is a man page documenting the  ~/.aegisrc  file
        format.

22..22..  DDeevveellooppeerr CCoommmmaannddss

Procedure:  ael  cd -> aedb -> _d_o _s_t_u_f_f -> aeb -> aet -> aed
-> aedless [ -> aeclean ] -> aede

aedb[u]
     Develop begin [undo].

aede[u]
     Develop end [undo].

aeclean
     This will remove all files in the development directory
     which  are  not  in  the  change as new files or copied
     files.  This may delete files  that  you  want,  so  be
     careful.

The _a_e_c_l_e_a_n(1) command uses Aegis' knowledge of what is _s_u_p_-
_p_o_s_e_d to be in the change.  You  are  meant  to  tell  Aegis
about  all  source  files you create in a development direc-
tory.  If you have forgotten to do this, it is highly likely
that the integration would fail in any case.

If  you are importing files from elsewhere, use "_a_e_n_f _." and
all of the files in the directory tree below dot  (the  cur-
rent directory) will be added to the change (make sure there
are no object files when you do this).

aecp Prepares a file in the project for editing  within  the
     change;  _i_._e_.  copy  file  into  change  from baseline.
     Remove symlink if necessary, etc.

aecpu
     Reverse the effects of the above.

aecpu -unch
     Will check all files in your change to see if any  have
     not  been modified, and perform an _a_e_c_p_u on them.  This
     will stop an unnecessary version number  increment  for
     files  that  have not changed.  (And also improves test



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





Howto                                                  Aegis


     correlations.)

aem  Merge out-of-date files.  See the _-_O_n_l_y_-_m_e_r_g_e option of
     the _a_e_d(1) command.

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

aemv Rename (move) files.

aerm[u]
     This  tells  Aegis  the  file is to be removed from the
     baseline when the change is integrated.   Or  _a_e_r_m_u  to
     undo this _b_e_f_o_r_e the change is finished.

22..33..  RReevviieewweerr CCoommmmaannddss

Procedure:  ael cd -> aecd -> aedless -> _v_i_e_w _o_u_t_p_u_t_, _r_e_v_i_e_w
_s_o_u_r_c_e _f_i_l_e_s -> aerpass

Remember: the point of reviews is to find problems, not be a
rubber stamp.  You are expected to fail some reviews.

aerpass
     Review pass.

aerpu
     Review pass undo.

aerfail
     Review fail.

22..44..  IInntteeggrraattoorr CCoommmmaannddss

Procedure: aeib -> aeb -> aet -> aed -> aeipass

There  is an _a_e_i_n_t_e_g_r_a_t_q(1) script distributed with Aegis to
do this procedure automatically.

aeib[u]
     Integrate begin [undo].

aeipass
     Integrate pass.

aeifail
     Integrate fail.

22..55..  PPrroojjeecctt AAddmmiinniissttrraattoorr CCoommmmaannddss

This includes all of the commands that don't fit  the  cate-
gories above.





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





Aegis                                                  Howto


aenc[u]
     Create   a  new  change  [undo].   See  _a_e_c_a_t_t_r(5)  for
     description of file format, or use _t_k_a_e_n_c(1) instead.

aend and aerd
     New developer; remove developer.

aenrv and aerrv
     New reviewer; remover reviewer.

aeni and aeri
     New integrator; remove integrator.

aena and aera
     New (project) administrator; remove administrator.

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

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

tkaeca
     Edit change attributes using a GUI.  This makes it much
     easier to type in the description field.






























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





Howto                                                  Aegis


33..  HHooww ttoo SSttaarrtt UUssiinngg AAeeggiiss

For  the first-time user, Aegis can appear to be very daunt-
ing.  It has a huge number of configuration alternatives for
each project, and it is difficult to know where to begin.

It is assumed that you already have Aegis installed.  If you
do not, see the section of the _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l  called  _T_h_e
_B_U_I_L_D_I_N_G  _F_i_l_e.   This reproduces the BUILDING file included
in the Aegis source distribution.

33..11..  FFiirrsstt,, CCrreeaattee TThhee PPrroojjeecctt

You need to create a new project.  Follow  the  instructions
in  the _H_o_w _t_o _C_r_e_a_t_e _a _N_e_w _P_r_o_j_e_c_t section, and then return
here.

33..22..  SSeeccoonndd,, UUssee aa TTeemmppllaattee PPrroojjeecctt

The very first time you use Aegis, it will be easiest 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".

+o The template projects can be found on the Aegis home page:
  http://www.canb.auug.org.au/~millerp/aegis/

+o If you are a long-time GNU Make user,  you  probably  want
  the Make-RCS template, at least to start with.

+o Follow the instructions found on the web page and you will
  have a working Aegis project, complete with self tests.

+o From this starting point, create changes (the _t_k_a_e_n_c  com-
  mand  is  good for this, as it gives you a simple GUI) and
  try modifying the calculator, or adding more  programs  to
  the project.

+o The  template projects is intended to be generally useful.
  Many users have simply retained this format  and  inserted
  their  own  projects into it.  (Use a change to delete the
  calculator and its tests.)

33..33..  SSeeccoonndd,, CCooppyy aa TTeemmppllaattee PPrroojjeecctt

If this isn't the very first time, you may wish to get  more
adventurous,  and  try  copying  the  relevant bits out of a
working project.  Usually, when sites first  try  this,  the
working  project  will  be one of the template projects from
the previous section.

+o Create a new project.  For  this  exercise,  you  probably
  want a single user project.




Page 8          (lib/en/howto/first_time.so)    Peter Miller





Aegis                                                  Howto


+o Create a new change

+o Copy  the project _c_o_n_f_i_g file, and and files referenced by
  it, such as the new file templates and the build  configu-
  ration file (_M_a_k_e_f_i_l_e or _H_o_w_t_o_._c_o_o_k, depending).

+o Copy the sources of the existing project into the develop-
  ment directory.  If you have several  levels  of  directo-
  ries, reproduce this, too.

+o Remove  files which are not primary sources (_e_._g_. the gen-
  erated C sources of you have yacc input files).

+o Using the "_a_e_n_f _." command (yes,  that's  a  dot,  meaning
  "the  current directory") you can tell Aegis to add all of
  the source files  in  the  development  directory  to  the
  change set.

+o You will probably need to modify your build method to meet
  Aegis' expectations.  Rather  than  do  this  immediately,
  change  the  _b_u_i_l_d___c_o_m_m_a_n_d  in  the project _c_o_n_f_i_g file to
  read "build_command = "exit 0";" and fix it  in  the  next
  change set.

+o Now, build, develop end, review and integrate, as found in
  the _U_s_e_r _G_u_i_d_e worked example.  (Except, of course,  there
  is only one member of staff.)

+o Create a second change, and copy the project configuration
  file (called _a_e_g_i_s_._c_o_n_f by default), and the build config-
  uration  file  (probably  _M_a_k_e_f_i_l_e or _H_o_w_t_o_._c_o_o_k) into the
  change.

+o This would be a good time to read the  _D_e_p_e_n_d_e_n_c_y  _M_a_i_n_t_e_-
  _n_a_n_c_e  _T_o_o_l  chapter  of  the  Aegis  User Guide, and also
  _R_e_c_u_r_s_i_v_e _M_a_k_e _C_o_n_s_i_d_e_r_e_d _H_a_r_m_f_u_l (see  the  author's  web
  site) if you haven't already.

+o Edit the build configuration, try the _a_e_b command; it will
  probably fail.  Iterate until things build correctly.

+o develop end, review and integrate as normal.  Your project
  is now under Aegis.














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





Howto                                                  Aegis


44..  HHooww ttoo RReeccrreeaattee OOlldd VVeerrssiioonnss

It  is  possible  to  recreate old versions of your project.
This is done using the delta number assigned to  every  com-
pleted change.

44..11..  aaeeccpp

Recreating  the  sources  is usually done to recreate a bug.
To this end, it is also usually done from within an existing
change.  The _a_e_c_p(1) command is used to copy histprical file
versions into a change.

The _a_e_c_p(1) command has some options which are used to  per-
form the source recreation:

--DDEELLttaa _n_u_m_b_e_r
  This option tells _a_e_c_p(1) to extract an historical version
  of the files, rather than the head revision (the one  vis-
  able  in the baseline).  You need to know the _d_e_l_t_a number
  of the change,  assigned  at  integration  time,  not  the
  change number.

--BBRRaanncchh _n_u_m_b_e_r
  If  the  historical  version is on a different branch than
  the one the current change is on, use  this  option.   The
  branch  number  is  to  the  left  of  the  "D" in version
  strings.

--DDEELLttaa--FFrroomm--CChhaannggee _n_u_m_b_e_r
  This option tells _a_e_c_p(1) to extract an historical version
  of  the files, rather than the head revision (the one vis-
  able in the baseline).  You only need the change number to
  use this option.

--DDEELLttaa--DDaattee ""_s_t_r_i_n_g""
  TThhiiss ooppttiioonn tteellllss _a_e_c_p((11)) ttoo eexxttrraacctt aann hhiissttoorriiccaall vveerrssiioonn
  ooff tthhee ffiilleess,, rraatthheerr tthhaann tthhee hheeaadd rreevviissiioonn ((tthhee oonnee  vviiss--
  aabbllee  iinn tthhee bbaasseelliinnee))..  YYoouu oonnllyy nneeeedd tthhee ddaattee tthhee cchhaannggee
  wwaass iinntteeggrraatteedd ttoo uussee tthhiiss ooppttiioonn..   IItt  uunnddeerrssttaannddss  mmaannyy
  ffoorrmmss ooff wwrriitttteenn ((EEnngglliisshh)) ddaatteess,, bbuutt ttrryy ttoo aavvooiidd aammbbiigguu--
  oouuss mmoonntthh nnuummbbeerriinngg ((iitt ccaann bbee ccoonnffuusseedd bbyy  ssoommee  EEuurrooppeeaann
  vvss.. AAmmeerriiccaann nnuummeerriicc ffoorrmmaattss,, uussee mmoonntthh nnaammeess iinnsstteeaadd))..

44..22..  FFiinnddiinngg DDeellttaa NNuummbbeerrss

You can find delta numbers in a number of ways:

+o The "_a_e_l _c_h_a_n_g_e_-_d_e_t_a_i_l_s" command will list change details.
If changes are completed, their delta number will appear  at
the top of the listing.

+o  The  "_a_e_l  _p_r_o_j_e_c_t_-_h_i_s_t_o_r_y" command lists all integration
for a project, including  their  change  numbers  and  delta



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





Aegis                                                  Howto


numbers.

+o  The  _a_e_a_n_n_o_t_a_t_e(1) command lists the file source, annota-
tiong each line with the developer, the date  and  the  ver-
sion.   To  the right of the "D" in the version is the delta
number.

+o The _#_{_v_e_r_s_i_o_n_} substitution (see _a_e_s_u_b(5) for more  infor-
mation) is covered in the next section.

In  addition, you may need to use the --BBRRaanncchh option, if the
historical version is on a different branch than the one the
current  change  is on.  The branch number is to the left of
the "D" in version strings.

44..33..  $${{vveerrssiioonn}}

The _b_u_i_l_d___c_o_m_m_a_n_d field in the project _c_o_n_f_i_g  file  may  be
given  the  _$_{_v_e_r_s_i_o_n_}  substitution,  which  you may use to
embed the version string into your executables.  You  could,
for  example, have this string printed when yoiur program is
given the --vveerrssiioonn command line option.  For example:

     % aaeeggiiss ----vveerrssiioonn
     aegis version 4.15.D012
     %


Armed with this version string, you can recreate the sources
for the version being executed.  The command

     % aaeeccpp ----cchhaannggee==44..1155..DD001122 ..
     %

would be issued from inside a suitable change.  This form of
the _a_e_c_p _-_c_h_a_n_g_e option  combines  the  --BBRRaanncchh  and  --DDEELLttaa
options into a single command line option.

44..44..  OOuutt OOff DDaattee

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

+o  The  first  is to remove unchanged sources.  Do this with
the

     % aaeeccppuu --uunncchhaannggeedd
     %

command.  This removes from your change all files which were
not  changed  by this change.  This cuts down on the clutter
and makes the next step much easier.




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





Howto                                                  Aegis


+o The next step is to merge  the  files.   Because  you  are
working  with  historical  versions of the files, Aegis will
think they are out-of-date and want you to merge  them.   Do
this  is the usual way (using the _a_e_m(1) command).  Remember
that Aegis will stash a  backup  copy  with  a  ",B"  suffix
before merging.

You may find the following command

     % aaeell ccff || ggrreepp ''((''
     %

useful for finding out-of-date files.

+o  Once  Aegis  thinks all the files are up-to-date you then
need to rebuild and retest before completing development.









































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





Aegis                                                  Howto


55..  HHooww ttoo CCrreeaattee aa NNeeww PPrroojjeecctt

Before you can do anything  else  with  Aegis,  you  need  a
project  to  do  it  to.  The advantage of this is that each
project is administered and configured independently.

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

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

55..11..  SSiinnggllee UUsseerr PPrroojjeecctt

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

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

_D_o_n_'_t _d_o _a_n_y_t_h_i_n_g _y_e_t_!  Read through all of the steps first.

+o You may want to read the _a_e_n_p_r(1) man page for more infor-
  mation.

+o The  command  "_a_e_n_p_r  name  _-_v_e_r_s_i_o_n  _-"  will  create the
  project with no branches.  This  will  automatically  make
  you  (that is, the executing user) the project administra-
  tor and the project owner.  The _u_m_a_s_k is remembered,  too.

+o The  root  of  the  project directory will be in your home
  directory, named after the  project  name.   If  you  want
  something else, use the _a_e_n_p_r _-_-_d_i_r_e_c_t_o_r_y option.

+o The  default group at the time of execution determines the
  file group of the project.  Make sure the account  created
  for the project has the correct group.  (Even if you don't
  understand this, your system administrator should.)

+o The _u_m_a_s_k at the time of execution  determines  the  group
  access  to  the  project.  Even if you usually work with a
  restrictive _u_m_a_s_k, set it to the right one for the project
  before running this _a_e_n_p_r command.

+o For additional security, it is often _v_e_r_y useful to create
  a UNIX user for each project.  You  may  need  to  consult
  your system administrator for assistance with this.  It is
  usual to name the user and the project the same thing,  to
  avoid  confusion.  Log in as this user to execute the ini-
  tial project creation commands; once completed nnoo oonnee will
  ever login to this account again.



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





Howto                                                  Aegis


+o Add the staff to the project: the "_a_e_n_a your-normal-login"
  command adds your normal account as a project  administra-
  tor.   You  need  this  if you are using a special project
  account, so that  your  normal  self  can  administer  the
  project.

+o At  this  point,  log  out of the special project account.
  Ask the system administrator to permanently disable it.

+o Add the rest of the staff: the "_a_e_n_d  your-login"  command
  makes  you  a  developer,  the  "_a_e_n_r_v your-login" command
  makes you a reviewer and  the  "_a_e_n_i  your-login"  command
  makes you an integrator.

+o You  need  to edit the project attributes next.  The "_a_e_p_a
  _-_e_d_i_t" command does this.  You will be placed into a  text
  editor, and will see something similar to this:

       description = "The \"_e_x_a_m_p_l_e\" 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 it at 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 at this time,  too.   Don't
  forget the closing double-quote _a_n_d semicolon.

+o Create  the  first branch now.  They inherit all staff and
  attributes at creation time, which is why we worked on the
  trunk  project first.  The command "_a_e_n_b_r name _1" followed
  by followed by "_a_e_n_b_r name_._1 _0" will  give  you  a  branch
  called  _n_a_m_e.1.0  for  use  wherever Aegis wants a project
  name.  (See the branching chapter of the  User  Guide  for
  more information.)

55..22..  TTwwoo UUsseerr PPrroojjeecctt

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







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





Aegis                                                  Howto


     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 own work.

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

Converting  a single user project to a two person project is
simply editing the project  attributes  to  look  like  this
later.   _R_e_m_e_m_b_e_r_: each branch inherited its attributes when
it was created - you need to  edit  the  ancestor  branches'
project attributes too.

55..33..  MMuullttii UUsseerr PPrroojjeecctt

Everything  is  done  as  above,  except you want to project
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 own  work,  and
reviewers  can't  integrate their own reviews.  This ensures
the maximum number of eyes validate each change.

You will need to add the  other  staff  to  the  appropriate
developer,  reviewer  and  integrator  roles.  Staff need to
always be permitted all  roles:  it  is  common  for  junior
staff, for example, _n_o_t to be authorized as reviewers.

Converting  a  single user project to a multi-person project
is simply editing the project attributes to look  like  this
later.   _R_e_m_e_m_b_e_r_: each branch inherited its attributes when
it was created - you need to  edit  the  ancestor  branches'
project attributes too.

55..44..  WWaarrnniinngg

The  _/_u_s_r_/_l_o_c_a_l_/_c_o_m_/_a_e_g_i_s_/_s_t_a_t_e  file  contains  pointers to
"system" projects.   _P_o_i_n_t_e_r_s_.   Users  may  add  their  own
project pointers (to their own projects) by putting a search
path into the _A_E_G_I_S___P_A_T_H environment variable.   The  system
part   is  always  automatically  appended  by  _A_e_g_i_s.   The
default, already set by the _/_u_s_r_/_l_o_c_a_l_/_l_i_b_/_a_e_g_i_s_/_c_s_h_r_c file,
is  _$_H_O_M_E_/_l_i_b_/_a_e_g_i_s.  Do not create this directory, _A_e_g_i_s is
finicky and wants to do this itself.

     Where projects reside is completely flexible,  be  they
system  projects  or user projects.  They are not kept under



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





Howto                                                  Aegis


the _/_u_s_r_/_l_o_c_a_l_/_c_o_m_/_a_e_g_i_s directory, this directory only con-
tains pointers.

55..44..11..  CCrreeaattiinngg PPrroojjeeccttss

When  you  create  a  new  project, the _f_i_r_s_t element of the
AEGIS_PATH is used as the  place  to  remember  the  project
_p_o_i_n_t_e_r.   This  means  the  project will not show up in the
global project list if you have set  AEGIS_PATH  to  include
private projects.

There  are  two  ways  to  make sure that you are creating a
global  project.   Either  "_u_n_s_e_t  _A_E_G_I_S___P_A_T_H"   immediately
before  using  the  "_a_e_n_p_r"  command,  or use the "--library
_/_u_s_r_/_l_o_c_a_l_/_c_o_m_/_a_e_g_i_s" option of the _a_e_n_p_r command.

55..44..22..  WWeebb VViissiibbiilliittyy

If you have a Web server, you may like to install the  Aegis
web  interface.   You  do  this by copying the _a_e_g_e_t program
from  _/_u_s_r_/_p_k_g_/_b_i_n_/_a_e_g_e_t  into  your  web  server's  _c_g_i_-_b_i_n
directory.   There  is  a _a_e_g_e_t_._i_n_s_t_a_l helper script, if you
don't know where your web server's _c_g_i_-_b_i_n directory is.

You may prefer to use a symbolic link, as this will be  more
stable across Aegis upgrades.  However, this requires a cor-
responding _f_o_l_l_o_w_-_s_y_m_l_i_n_k_s setting in your web server's con-
figuration file.  (Use the _a_e_g_e_t_._i_n_s_t_a_l _-_s option.)

If  you  have a Web server, and aeget was installed, you can
use a wrapper script to set the _A_E_G_I_S___P_A_T_H environment vari-
able,  if  you  want it to be able to see more projects than
just the global projects.

55..55..  CChhaannggiinngg TThhee PPrroojjeecctt OOwwnneerr

Typically, when folks try Aegis for  the  first  time,  they
don't worry about having a separate user for their projects.
However, once things are ticking along, it is less and  less
attractive  to toss it all and start again cleanly.  So, now
you need to change the  project  owner  from  the  user  who
started  the  Aegis  evaluation  to  the unique project user
account.

1. You need to be _r_o_o_t to perform this procedure.

2. Create the user account.  It  doesn't  need  to  work  to
   login,  so  the  password  can be disabled.  You probably
   want to arrange to have this user's email forwarded some-
   where  sensible  (maybe  see  the Distributed Development
   chapter of the User Guide).

3. The owner of the project is taken from the owner  of  the
   project  directory  tree,  so  this  is  what needs to be



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





Aegis                                                  Howto


   changed.  Go to the root of the project tree - the direc-
   tory  which  appears in the "_a_e_l _p_r_o_j_e_c_t_s" listing.  This
   isn't the trunk baseline, but the directory above it (you
   will see _i_n_f_o, _h_i_s_t_o_r_y and _b_a_s_e_l_i_n_e sub-directories).

4. Use the command

        chown -R _u_s_e_r_n_a_m_e .

   to  change the ownership of this directory, and all files
   and sub-directories below it.  Insert the username of the
   account  you created in step 2.  (You need the ddoott on the
   end of the command, its not mere punctuation.)

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









































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





Howto                                                  Aegis


66..  HHooww ttoo MMoovvee aa PPrroojjeecctt

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

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

66..11..  RReellooccaattiinngg aa PPrroojjeecctt

This section deals with moving a project's  files  from  one
file system location to another.

66..11..11..  FFrroomm wwiitthhiinn AAeeggiiss

This  works  best  when  you  are  moving a project from one
machine to another.  It is a _v_e_r_y good idea if there are  no
active changes on _a_n_y branch.

Step  1:  You  need  to  know  where  in the file system the
project currently resides.  Take a look in the projects list
(_a_e_l  _p) and see the directory reported for the trunk of the
project.  Ignore any active branches.

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

Step  3:  Move the files to their new location, you need _a_l_l
of the files below the directory tree you found in  step  1.
This  may  be a simple file move, or may involve copying the
files to tape, and then unpacking on a new machine.   Remem-
ber  to  make  sure  the file ownerships are set the way you
want (usually, this means "preserved exactly").

Step 4: Tell Aegis where the project is.  To  do  this,  use
the -dir and -keep options of the _a_e_n_p_r(1) command.

66..11..22..  FFrroomm oouuttssiiddee AAeeggiiss

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

Step 1: You need to  know  where  in  the  file  system  the
project currently resides.  Take a look in the projects list
(ael p) and see the directory reported for the trunk of  the
project.  Ignore any active branches.

Step 2: Move the files to the new location.




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





Aegis                                                  Howto


Step  3: Edit the /usr/pkg/com/aegis/state file and edit the
path appropriately to tell Aegis where you moved  the  files
to.  You will need to be root for this step.

66..22..  RReennaammiinngg aa PPrroojjeecctt

This  section  deals  with changing a project's name without
moving is files.

66..22..11..  FFrroomm wwiitthhiinn AAeeggiiss

Step 1: You need to  know  where  in  the  file  system  the
project currently resides.  Take a look in the projects list
(_a_e_l _p) and see the directory reported for the trunk of  the
project.  Ignore any active branches.

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

Step 3: Tell Aegis where the project is, using the new name.
To  do  this, use the -dir and -keep options of the _a_e_n_p_r(1)
command.

66..22..22..  FFrroomm oouuttssiiddee AAeeggiiss

Step 1: Edit the /usr/pkg/com/aegis/state file and edit  the
name  appropriately  to  tell  Aegis  the  new  name  of the
project.  You will need to be root for this step.

66..22..33..  PPrroojjeecctt AAlliiaasseess

You may need  some  transition  time  for  your  developers.
Either  before or after you rename the project, you may want
to consider adding a project alias (see  _a_e_n_p_a(1)  for  more
information)  so  that  the  project  has "both" names for a
while.



















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





Howto                                                  Aegis


77..  WWoorrkkiinngg iinn TTeeaammss

Aegis supports teamwork in two basic ways: local development
and  distributed development.  Local development breaks down
into a single machine, and networked machines  on  a  common
LAN.   By  building the description a little at a time, this
section will show how each of these modes of development are
related in the model used by Aegis.

77..11..  LLooccaall


77..11..11..  SSiinnggllee UUsseerr,, SSiinnggllee MMaacchhiinnee

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

Even in this environment, it is often the case that a single
user  will  be  working on more than one thing at once.  You
could have a large new feature being added, and a series  of
bug  fixes  happening  in parallel during the course of this
development.  Or some-one may  interrupt  you  with  a  more
important  feature  they need to be added.  Aegis allows you
to simply and rapidly create as many or as  few  independent
changes (and development directories) as required.

By  using  independent  work areas, things which are not yet
completed cannot  be  confused  with  immediate  bug  fixes.
There is no risk of untested code "contaminating" a bug fix,
as would be the case in one large work area.

77..11..22..  MMuullttii UUsseerr,, SSiinnggllee MMaacchhiinnee

Having multiple developers working on the  same  project  is
very  little different than having one developer.  There are
simple many changes all being worked on in  parallel.   Each
has  its  own  independent work area.  Each is independently
validated before it may be integrated.

One significant difference with multiple developers is  that
you  now  have  enough people to do real code reviews.  This
can make a huge difference to code quality.

77..11..33..  MMuullttii UUsseerr,, MMuullttii MMaacchhiinnee

Aegis assumes that when working on a LAN,  you  will  use  a
networked  file  system,  of some sort.  NFS is adequate for
this task, and commonly available.  By using NFS,  there  is
very  little  difference between the single-machine case and
the multi-machine case.





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





Aegis                                                  Howto


There are some system administration constraints imposed  by
this, however: it is assumed that each machine is apparently
"the same", in terms of environment.

77..11..33..11..  GGeenneerraall RReeqquuiirreemmeennttss

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 ubiquitous NFS for now.

+o You need exactly the same _/_e_t_c_/_p_a_s_s_w_d and _/_e_t_c_/_g_r_o_u_p  file
  on  every machine.  This gives a uniform environment, with
  uniform security.  (It also gets the UIDs right, which NFS
  needs.)  Keeping _/_e_t_c_/_p_a_s_s_w_d and _/_e_t_c_/_g_r_o_u_p in sync across
  more than about 3 machines can be time consuming and error
  prone  if  done manually - so don't.  Use NIS or similar -
  do sys admin once, automatically takes effect  everywhere.

+o All  of  the  machines  see the same file systems with the
  same path names as all the others.   (Actually,  you  only
  need worry about the ones Aegis is interested in.)  Again,
  you can try to keep all those  _/_e_t_c_/_f_s_t_a_b  files  in  sync
  manually,  but  you are better off using NIS (or NIS+) and
  the automounter or amd.

+o All of the machines need their clocks synchronized.   Oth-
  erwise tools which use time stamps (obviously _m_a_k_e(1), but
  also a few others) will get confused.  NTP  or  XNTP  make
  this  simple  and  automatic.   In  a  pinch,  you can use
  _r_d_a_t_e(1) from cron every 15 minutes.

+o Many sites are worried about the security  of  NFS.   Usu-
  ally,  you  need to take the root password away from work-
  station users; once the environment is uniform across  all
  of  them,  the  need  for  it usually disappears.  It also
  means they can't abuse NFS,  and  they  can't  run  packet
  sniffers,  either.   By  using  netgroups (I'm _n_o_t talking
  about the _/_e_t_c_/_g_r_o_u_p_s file) you can further  restrict  who
  NFS  will  talk to.  By using NIS+ and NFSv3 you can quash
  the last couple of security issues, but  unless  you  have
  military contracts, it's rarely worth it.

Fortunately, NFS and NIS readily available, both for propri-
etary systems and open  source  systems.   Large  sites  use
these  techniques successfully and securely - and they ddoonn''tt
have _O_(_n_^_2_) or even _O_(_n_) sys admin issues, they get most sys
admin tasks down to _O_(_1_).

But,  _b_u_t,  bbuutt!!   Many sites are _v_e_r_y concerned about being
able to work when the server(s) are down.  I agree,  however
I  suggest  sweet talking your sys admin, not bashing NFS or
NIS or Aegis.  It is possible to get very high  availability
from  modern  systems  (and even ancient PCs, using Linux or
BSD).



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





Howto                                                  Aegis


The fact is, working in a team requires  interaction.   Lots
of  interaction.   It is an illusion that you can work inde-
pendently indefinitely.  In the  ultimate  siege  mentality,
you  need  a full and complete private copy of everything in
order to pull this off; but expect the other team member  to
carefully inspect everything you produce this way.

77..11..33..22..  AAeeggiiss--ssppeecciiffiicc RReeqquuiirreemmeennttss

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

+o All of the Aegis distribution can be installed locally for
  performance,  if  that's  what you need.  (Except, see the
  next item.)  Or, you can install it all on an NFS  mounted
  disk,  which guarantees everyone is always running exactly
  the same software revision which can sometimes  be  impor-
  tant (shortens upgrade times, too.)

+o Except  the  _$_{_p_r_e_f_i_x_}_/_c_o_m_/_a_e_g_i_s  directory, which must be
  the one NFS disk mounted by every single  machine  identi-
  cally,  and  must be read write.  _I_._e_. unique to the whole
  network (well, all machines using Aegis).  This  is  where
  the  pointer  to  the projects are kept, and this is where
  the database locks are kept.  If this directory isn't com-
  mon  to  every  machine,  the  Aegis database will quickly
  become corrupted.

+o The project directory tree must be on an  NFS  disk  which
  all  machines  see,  and must be the same absolute path on
  all machines.  This is  so  that  the  absolute  paths  in
  _$_{_p_r_e_f_i_x_}_/_c_o_m_/_a_e_g_i_s_/_s_t_a_t_e mean something.

+o The  development directories need to be on NFS disks every
  machine can see.  Usually, this means a common home direc-
  tory  disk,  or a common development directory disk.  This
  can still be a disk local to  the  workstation,  but  they
  must all be exported, and all must appear in the automount
  maps.  This is because Aegis assumes that  every  worksta-
  tion  has  a uniform view of the entire system (so reviews
  can review your development directory, and integrators can
  pick up the new files from your development directory).

Large software shops have used these techniques without dif-
ficulty.

77..11..44..  KKnnoowwnn PPrroobblleemmss

There is a known problem with the HP/UX NFS clients.  If you
see  persistent  "no  locks  available"  error messages when
_/_u_s_r_/_p_k_g_/_l_i_b_/_a_e_g_i_s  is   NFS   mounted,   try   making   the
_/_u_s_r_/_p_k_g_/_l_i_b_/_a_e_g_i_s_/_l_o_c_k_f_i_l_e file world writable.





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





Aegis                                                  Howto


     chmod 666 /usr/pkg/lib/aegis/lockfile

There  is  the  possibility of a denial of service attack in
this mode (which is why the default is 0600) but  since  you
are presently denied service anyway, it's academic.

77..22..  DDiissttrriibbuutteedd

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

The  other  aspect of Aegis, which you have probably noticed
already, is that it is very keen on security.   Security  of
the "availability, integrity and confidentiality" kind.

Incoming  change  sets are subject to the same scrutiny as a
change set produced locally.  It  is  dropped  into  a  work
area,  built  and tested, before being presented for review.
Just like any local change set would be.

77..22..11..  MMuullttiippllee SSiinnggllee--UUsseerr SSiitteess

In the case of an Open Source project  maintainer,  this  is
essential,  because  incoming  contributions  are of varying
quality, or may interact  in  unfortunate  ways  with  other
received  change sets.  This careful integration checking is
essential.  Imaging the chaos which could ensure  if  change
sets   were   unconditionally  dropped  into  the  baseline.
(Deliberate malice or sabotage, of course, also being a grim
possibility.)

The  careful  reader  will by now be squirming.  "How", they
wonder, "can  the  maintainer  examine  every  change  every
developer makes.  Surely it doesn't scale?"

Indeed, it would not.  Aegis provides a mechanism for aggre-
gating changes into "super changes".  These  larger  changes
can  then  be shipped around.  (See the Branching chapter in
the User Guide for more information.)

In the reverse direction, from the  maintainer  out  to  the
developer,  developers  in  an  Open Source project probably
aren't going to want to see each and every change  set  made
to  the  project.   Again, they can use an aggregation (_e_._g_.
grab the latest snapshot when each release is announced)  to
re-sync  in  larger  chunks,  less often.  The chances of an
intersection are fairly low (otherwise someone is  duplicat-
ing effort) so the merge is usually quite simple.




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





Howto                                                  Aegis


77..22..22..  MMuullttiippllee MMuullttii--UUsseerr SSiitteess

Most  distributed large-scale corporate operations are actu-
ally similar to Open Source projects,  though  they  usually
have  more staff.  There is usually a "senior" site, and the
other sites make their contributions, which are  scrutinized
carefully before being promoted to full acceptance.

Again,  aggregations become essential to the system integra-
tion phase of a product.  There may even be a  hierarchy  of
concentrators along the way.

Junior corporate sites can sync periodically with the senior
site, too, rather than double handle (or worse) every change
set.

77..22..33..  TTeelleeccoommmmuuttiinngg

One of the most desired cases is that of telecommuting.  How
do remote worker, who may never make  it  into  the  office,
develop projects using Aegis?

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

77..22..33..11..  OOffffiiccee ttoo DDeevveellooppeerr

The office makes available a web interface to  Aegis.   From
this,  it is possible to download individual changes, branch
updates, or whole projects.  All of this is already  present
in the Aegis distribution.

However,  many corporate sites are not going to want to make
all of their intimate development details to comprehensively
available  on  the  web.   For  such  sites, I would suggest
either a direct "behind the firewall" dial-in, or some  vir-
tual  private networking software (which means users can use
a local ISP, and still be treated "as if" they  were  behind
the firewall).

If  a VPN won't fly (due to company security policies), then
selected encrypted updates could  be  posted  "outside",  or
perhaps  an procmail "change set service" could be arranged.

77..22..33..22..  DDeevveellooppeerr ttoo OOffffiiccee

It is unlikely (though possible) that you would have  a  web
server  on the developer's machine - usually you aren't con-
nected, to the office pulling changes sets back is  probably
not viable.

The  simplest  mechanism  is  for the satellite developer to
configure their Aegis project so that the trunk  tracks  the
office  version.   Once  a  week  (or  more often if you get



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





Aegis                                                  Howto


notified something significant has happened) pull  down  the
latest version of "the office" as a change set and apply it.
This way, the trunk tracks the official version.

The developer works in a sub-branch, with aeipass configured
to  e-mail  branch  integrations  (but not individual change
sets) back to the office.  In this way, a work  package  can
be  encapsulated  in  a branch, and sent when finished.  You
also have the ability to manually send  the  branch  at  any
earlier  state, and it still encapsulates the set of changes
you have made to date.














































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





Howto                                                  Aegis


88..  HHooww ttoo uussee AAeeggiiss wwiitthh PPyytthhoonn

This section describes how to use  Aegis  to  supervise  the
development of Python programs.  Some of the remarks in this
section may also be helpful  to  people  who  use  Aegis  to
supervise development in other non-compiled languages.

This  section  is  contributed courtesy of Tangible Business
Software, www.tbs.co.za.  Python-specific questions relating
to   this   section   may   be   sent  to  Pieter  Nagel  at
<pnagel@tbs.co.za>.

88..11..  HHaannddlliinngg AAeeggiiss sseeaarrcchh ppaatthhss

88..11..11..  TThhee AAeeggiiss mmooddeell vvss.. tthhee PPyytthhoonn mmooddeell

Aegis' view of a project is that it consists of a  hierarchy
of  project baselines.  Each baseline consists of only those
files that were modified as part of that (sub)project,  plus
all files that were built by the DMT (see the section of the
_U_s_e_r _G_u_i_d_e called _T_h_e _D_e_p_e_n_d_e_n_c_y _M_a_i_n_t_e_n_a_n_c_e  _T_o_o_l).   Aegis
expects  the  DMT  to  be able to collect the entire project
into one piece by searching up this baseline search path for
all needed files.

This  works  fine  when  using statically compiled languages
such as C.  The build process "projects" source  files  from
various  Aegis baselines onto one or more executables.  When
these are run they do not need to search through  the  Aegis
search  path  for parts of themselves; they are already com-
plete.

Python programs, however, are never compiled and linked into
a single executable.  One could say that a Python program is
re-linked each time it is run.  This means that  the  Python
program  will need to be able to find its components at run-
time.  More importantly, it will need to avoid importing the
old  versions of files from the baseline when newer versions
are present in the development or integration directories.

88..11..22..  TThhee ssoolluuttiioonn

The simplest (and only recommended) way to marry  Aegis  and
Python  is  to  configure Aegis to keep all of the project's
files visible in a the development and integration  directo-
ries,  at  all  times.   That way Aegis' search path becomes
irrelevant to Python.

Use Aegis version 3.23 or later, and set  the  following  in
the project _c_o_n_f_i_g file:







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





Aegis                                                  Howto


     create_symlinks_before_build
         = true;
     remove_symlinks_after_integration_build
         = false;

The second directive is not available in earlier versions of
Aegis.

If you keep your Python files  in  a  subdirectory  of  your
project,  such as _s_r_c_/_p_y_t_h_o_n, you will need that directory's
relative in your _P_Y_T_H_O_N_P_A_T_H  whenever  Aegis  executes  your
code for testing, i.e. by setting

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

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

It may seem strange to you that we are not substituting  the
Aegis  _S_e_a_r_c_h___P_a_t_h variable into _P_Y_T_H_O_N_P_A_T_H at all - it does
at first seem to be the solution that is  called  for.   The
reason why we don't is very simple: _i_t _d_o_e_s _n_o_t _w_o_r_k.  It is
worth stressing the following rule:

NNeevveerr iinnjjeecctt aannyy aabbssoolluuttee ppaatthh ooff aannyy  AAeeggiiss  bbaasseelliinnee  iinnttoo
tthhee PPyytthhoonn sseeaarrcchh ppaatthh..

88..11..33..  WWhhyy sseettttiinngg PPYYTTHHOONNPPAATTHH ttoo tthhee AAeeggiiss sseeaarrcchh ppaatthh wwiillll
nnoott wwoorrkk

The reason why _P_Y_T_H_O_N_P_A_T_H does not work as Aegis expects  is
due  to  the  way  Python searches for packages.  For a full
explanation of what packages are, you can see _S_e_c_t_i_o_n _6_._4 of
the  _P_y_t_h_o_n _T_u_t_o_r_i_a_l, but the crucial point is that a Python
package consists of a directory with an _____i_n_i_t_____._p_y file  in
which  the  other  files  in  that directory which should be
treated as part of that package are listed.

When Python imports anything from a  package,  Python  first
searches for the _____i_n_i_t_____._p_y file and remembers the absolute
path of the directory where it found it.  It will thereafter
search  for  all  other parts of the package within the same
directory.   Without  the  _c_r_e_a_t_e___s_y_m_l_i_n_k_s___b_e_f_o_r_e___b_u_i_l_d  and
_r_e_m_o_v_e___s_y_m_l_i_n_k_s___a_f_t_e_r___i_n_t_e_g_r_a_t_i_o_n___b_u_i_l_d   settings  enabled,
all the needed files are not guaranteed to _b_e present in one
directory  at  all  times, however; they will most likely be
spread out over the entire Aegis search path.

The result is that if you were to try and use  the  approach
of  setting the _P_Y_T_H_O_N_P_A_T_H to the Aegis search path, package
import will mysteriously fail under (at  least)  two  condi-
tions:



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





Howto                                                  Aegis


+o Whenever  you modify a file in a package without modifying
  the  accompanying  _____i_n_i_t_____._p_y,  Python  will   find   the
  _____i_n_i_t_____._p_y  file in the baseline and import the _o_l_d files
  from there.

+o Whenever you modify the _____i_n_i_t_____._p_y and leave  some  other
  file  in  the  package  unmodified,  Aegis  will  find the
  _____i_n_i_t_____._p_y in the development/integration  directory  but
  fail to find the unmodified files there.

88..22..  TThhee bbuuiilldd sstteepp

Python programs do not need to be built, compiled, or linked
before they can be run, but Aegis requires a build  step  as
part of the development cycle.

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

     build_command = "true";

in the project configuration file. _t_r_u_e(1) is a Unix command
which is guaranteed to always succeed.

In  practice,  however,  there often are housekeeping chores
that can be done as part of the build process,  so  you  can
just as well go ahead and create a Makefile, Cook recipe, or
script that performs these tasks and make  that  your  build
step.

Here are some examples of tasks that can be performed during
the build step:

+o Setting the executable flag on your main  scripts.   Aegis
  does  not  store file modes, but it is often convenient to
  have one or more  of  the  Python  source  files  in  your
  project be executable, so that one does not need to invoke
  Python explicitly to run them.

+o Delete unwanted Python object files (_._p_y_c and _._p_y_o files).
  These  could  arise  when  you  aerm  and  delete a Python
  script, but  forget  to  delete  the  accompanying  Python
  object  file(s).   Other files will then mysteriously suc-
  ceed in importing the removed  scripts,  where  you  would
  expect them to fail.  Your build process could use _a_e_l _-_c_f
  and _a_e_l _-_p_f) to get  a  list  of  'allowed'  scripts,  and
  remove  all Python object files which do not correspond to
  any of these.

+o Auto generate your  packages  _____i_n_i_t_____._p_y  files.   Python
  wants  you  to  declare  your  intent  to have a directory
  treated as a package  by  creating  the  _____i_n_i_t_____._p_y  file
  (otherwise  a  stray  directory  with  a  common name like
  'string', 'test', 'common' or  'foo'  could  shadow  like-



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





Aegis                                                  Howto


  named  packages  later  on in the search path).  But since
  Aegis is, by definition, an authoritative source  on  what
  is  and  what  is  not part of your program it can just as
  well declare your intent for you.

88..33..  TTeessttiinngg

Testing under Aegis using Python is no  different  from  any
other  language, only much more fun.  Python's run-time type
checking makes it  much  easier  to  develop  software  from
loosely-coupled  components.   Such components are much more
suited to unit testing than strongly-coupled components are.

If  the  testing  script which Aegis invokes is part of your
project, there is one important  _P_Y_T_H_O_N_P_A_T_H-related  caveat:
when  Aegis  runs the tests, it specifies them with an abso-
lute path.  When Python runs any scripts  with  an  absolute
path, it prepends 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 the search path when
doing regression testing.

The solution is to use code like this to remove  the  test'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 test file, you
may want to centralize that code in  a  test  harness  which
imports  and  runs the tests on Aegis' behalf.  This harness
can also serve as a central place where  you  can  translate
test  success  or  failure  into  the  exit  statuses  Aegis
expects.

The test harness must take care to import  the  file  to  be
tested  without needing to add the absolute path of the file
to _s_y_s_._p_a_t_h.  Use _i_m_p_._f_i_n_d___m_o_d_u_l_e and _i_m_p_._f_i_n_d___m_o_d_u_l_e.

I can strongly recommend _P_y_U_n_i_t,  the  _P_y_t_h_o_n  _U_n_i_t  _T_e_s_t_i_n_g
_F_r_a_m_e_w_o_r_k  by  Steve  Purcell,  available  from  http://pyu-
nit.sourceforge.net.  It is based on  Kent  Beck  and  Erich
Gamma's  _J_U_n_i_t  framework  for Java, and is becoming the _d_e_-
_f_a_c_t_o standard testing framework for Python.

One bit of advice when using _P_y_U_n_i_t: like Aegis, _P_y_U_n_i_t also
distinguishes  between  test  failures  as  opposed  to test
errors, but I find it best to report _P_y_U_n_i_t test  errors  as
Aegis  test failures.  This is to ensure that baseline tests
fail as Aegis expects them to.  _P_y_U_n_i_t will consider a  test
which  raises  anything other than a _A_s_s_e_r_t_i_o_n_E_r_r_o_r to be an
'error', but in practice baseline test  failures  are  often



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





Howto                                                  Aegis


_A_t_t_r_i_b_u_t_e_E_r_r_o_r  exceptions which arise when the test invokes
methods not present in the old code.  This is  a  legitimate
way  to  verify,  as  Aegis  wants us to, that the test does
indeed invoke and test functionality which  is  not  present
the old code.

88..44..  RRuunnnniinngg yyoouurr pprrooggrraammss

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

The simplest approach is to have your program's main  script
be   located   at   the  top  of  your  Python  source  tree
(_s_r_c_/_p_y_t_h_o_n) in our example.  Whenever you run that  script,
Python  will automatically add the directory it was found in
to the Python path, and will find all your other files  from
there.

You  can  safely  let your shell's _P_A_T_H environment variable
point to that script's location, since the  shell  _P_A_T_H  and
the _P_Y_T_H_O_N_P_A_T_H do not mutually interfere.

Just  avoid  the temptation to set the absolute path of that
script into your _P_Y_T_H_O_N_P_A_T_H, or otherwise  your  development
code and baseline code will interfere with each other.  This
is not an Aegis-specific problem, though, since there  would
be potential confusion on any system, in any language, where
two versions of one program are simultaneously visible  from
the same search path.




























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





Aegis                                                  Howto


.
























































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





Howto                                                  Aegis


99..  HHoowwttoo EEnndd AA BBrraanncchh

"OK,  I  give  up.   I  do  not  understand  the  ending  of
branches."

Usually, you end development of a branch the  same  way  you
end development of a simple change.  In this example, branch
_e_x_a_m_p_l_e_._1_._4_2 will be ended:

     % aaeeddee --pp eexxaammppllee 11 --cc 4422
     aegis: project "example.1": change 42: file "_f_u_b_a_r" in
     the baseline has changed since the last 'aegis -DIFFer-
     ence' command, you need to do a merge
     %

Oops.  Something went wrong.  Don't panic!

I'm going to assume, for the purposes of explanation, that
there have been changes in one of the  ancestor branches,
and thus require a merge, just like file _f_u_b_a_r, above.

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

At his point you need to do 5 things: (1) create a new
change on example.1.42, (2) copy _f_u_b_a_r into it, (3) merge
_f_u_b_a_r with branch "example.1" (4) end development of the
change and integrate it, and (5) now you can end exam-
ple.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 sideways.

     % aaeemm --ggpp _f_u_b_a_r
     %

And manually fix any conflicts... naturally.

At this point, have a look at the file listing, it will show
you something you have never seen before - it will show you
what it is _g_o_i_n_g _t_o set the branch's edit_number_origin to
for each file, at _a_e_i_p_a_s_s.

     % aaeell ccff
     Type   Action Edit        File Name
     ------ ------ -------     -----------
     source modify 1.3         aerect/rect.c
                   {cross 1.2}

Now finish the change as usual...  _a_e_b_, _a_e_d_, _a_e_d_e_, _a_e_r_p_a_s_s_,
_a_e_i_b_, _._._._, _a_e_i_p_a_s_s nothing special here.





Page 32           (lib/en/howto/branch.so)      Peter Miller





Aegis                                                  Howto


One small tip: merge file files one at a time.  It makes
keeping track of where you are up to much easier.

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 conflict where
you, the human, know there is none.  Remember that the _a_e_m
command saves the old version of the file with a ,B suffix
(`B' for backup).  If you have a file like this, just use

     % mmvv _f_u_b_a_r,,BB _f_u_b_a_r
     %

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









































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





Howto                                                  Aegis


1100..  HHooww ttoo BBeeccoommee aann AAeeggiiss DDeevveellooppeerr

This section describes how to become an Aegis developer, and
gives some procedures, some ideas of areas which need work,
and some general guidelines.

Please note: if these instructions have a problem, let some-
one know!  If you are having a problem, so is the next guy.
_P_l_e_a_s_e send all problem reports to Peter Miller
<millerp@canb.auug.org.au>

1100..11..  RReeqquuiirreedd SSooffttwwaarree

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

+o It will probably come as no surprise that Aegis is devel-
  oped using Aegis (never trust a skinny chef) so the first
  thing you need is to install Aegis and become familiar
  with using it.  You will need Aegis 4.24.2 or later.

+o You will need a C++ compiler.  If your compiler is
  installed in an uncommon directory or has an uncommon
  name, you can set the appropriate attribute by editing the
  _a_e_g_i_s_._c_o_n_f_._d_/_s_i_t_e_._c_o_n_f file.

+o You will need to install Cook, in order to build things.
  Version 2.8 or later, preferably you should track the lat-
  est release.
  http://www.canb.auug.org.au/~millerp/cook/

+o GNU Autoconf 2.53 or later.
  http://ftp.gnu.org/pub/gnu/autoconf/
  If your tools are installed in an uncommon directory or
  have an uncommon name, you can set the appropriate
  attribute by editing the _a_e_g_i_s_._c_o_n_f_._d_/_s_i_t_e_._c_o_n_f file.

+o GNU Automake.
  http://ftp.gnu.org/pub/gnu/automake/

+o You will need to install FHist, for the history tool.
  http://fhist.sourceforge.net/

+o You will need to install _t_a_r_d_y, for manipulating tarballs.
  http://miller.emu.id.au/pmiller/software/tardy/

+o You will need to install _p_t_x(1), for the permuted indexes
  in the documentation.  This is now part of GNU coreutils.
  http://ftp.gnu.org/pub/gnu/coreutils/

+o You need psutils for the _p_s_s_e_l_e_c_t utility, to manipulate
  the documentation files, mostly to put the tables of con-
  tents at the start, rather than at the end as GNU Groff
  generates them.



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





Aegis                                                  Howto


  http://www.dcs.ed.ac.uk/home/ajcd/psutils/

+o You will need the developer libraries for the _r_x library
  (if you installed from the tarball, you have these, but if
  you installed from RPM, you need the -devel package as
  well).
  http://ftp.gnu.org/pub/gnu/rx/

+o You will need the developer libraries for the _z_l_i_b 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/

+o You will need the developer libraries for the _l_i_b_c_u_r_l
  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/

+o You need UUID generation capability.  This requirement may
  be satisfied in several different ways depending of your
  development platform.
  First, on GNU/Linux you could skip this requirement pro-
  vided that your kernel has support for _/_p_r_o_c filesystem.
  Please note: in order to work _/_p_r_o_c must be mounted and
  _/_p_r_o_c_/_s_y_s_/_k_e_r_n_e_l_/_r_a_n_d_o_m_/_u_u_i_d must be present.
  Second, you could install the developer libraries for the
  _e_2_f_s_p_r_o_g_s package (if you installed from the tarball, you
  have these, but if you installed from RPM you need the
  -devel package as well).
  http://e2fsprogs.sourceforge.net/
  Third, you could install the UUID library from OSSP:
  http://www.ossp.org/pkg/lib/uuid/
  Fourth, if your platform has support for an API compliant
  with DCE 1.1, Aegis also supports the DCE API.

+o The GNOME libxml2 library (http://xmlsoft.org/) is used to
  parse XML, you will need version 1.8.17 or later.  You do
  not have to install the rest of GNOME as this library is
  able to be used by itself.  This package is nnoott optional,
  you need it to successfully build Aegis.

+o You need to install Bison, the GNU replacement for Yacc.
  http://ftp.gnu.org/pub/gnu/bison/

+o You will need to install Flex, the GNU replacement for
  Lex.
  http://ftp.gnu.org/pub/gnu/non-gnu/flex/

+o You need to GNU Gettext (0.16.1 or later) tools installed.
  Even though Glibc 2.0 and later include Gettext, you need
  the developer tools as well.  (You need GNU Gettext even
  on Solaris, because the Solaris Gettext implementation is



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





Howto                                                  Aegis


  less than adequate.)
  http://ftp.gnu.org/pub/gnu/gettext/

+o You need GNU Ghostscript, for the ps2pdf utility, so that
  you can create PDF documents.
  http://ftp.gnu.org/pub/gnu/ghostscript/

+o You need a _u_u_d_e_c_o_d_e with a -o option (to redirect the out-
  put).  It is part of GNU Sharutils.
  http://ftp.gnu.org/pub/gnu/sharutils/

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

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

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

+o You need to install _s_u_d_o(8).  See etc/set-uid-root in the
  distribution for how to configure the _/_e_t_c_/_s_u_d_o_e_r_s file.
  ftp://ftp.sudo.ws/pub/sudo/

+o The location box icon is generated using _c_o_n_v_e_r_t from
  ImageMagick, but the build can cope if you don't have it.
  http://www.imagemagick.org/

+o The PNG images are optimized by the _p_n_g_c_r_u_s_h command.
  http://pmt.sourceforge.net/pngcrush/

+o The location box icon is generated using _p_n_g_2_i_c_o but the
  build can cope if you don't have it.
  http://www.winterdrache.de/freeware/png2ico/

+o It is possible to use the dmalloc library for debugging
  memory abuses.  Be warned: the dmalloc library can be
  instructed to log to a file, circumventing the Aegis I/O
  layer, thus it's possible to create file owned by root.
  The dmalloc library should only ever be used as a debug-
  ging tool, and _n_e_v_e_r be used in a production build of
  Aegis.
  http://dmalloc.com/
  On a Debian system, use the apt-get install libdmalloc-dev
  command.
  You will need to aecp the etc/Howto.cook file to alter the
  build to use the dmalloc library.

+o _P_r_o_b_a_b_l_y _m_o_r_e _t_h_i_n_g_s _I_'_v_e _f_o_r_g_o_t_t_e_n_.

+o Some parts of the build need Perl





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





Aegis                                                  Howto


1100..22..  CCrreeaattee TThhee AAeeggiiss PPrroojjeecctt

The next thing to do is create an Aegis project to hold the
Aegis source.  This is done in the usual way.  I suggest you
create branches which match the current public release, _e_._g_.
it is 4.24.2 at present.

The best-practice technique of having a separate user
account to mind the sources is recommended.  The following
commands should be run as that user, not your usual login.
This prevents a variety of accidents which can happen when
you are browsing the baseline (master source).

You could use the following command:

     % aaeennpprr aaeeggiiss..44..2244..22
     aegis: project "aegis": created
     aegis: project "aegis.4.24.2": created
     %

but experienced Aegis users will know that this means a
laborious setting of project attributes.  It is easier to
create the top-level project, set the attributes, and the
create the branches, so that they inherit the attributes on
creation.

     % aaeennpprr aaeeggiiss --vveerrssiioonn --
     aegis: project "aegis": created
     % aaeeppaa --ee --pp aaeeggiiss
     _e_d_i_t_s _t_h_e _p_r_o_j_e_c_t _a_t_t_r_i_b_u_t_e_s _f_o_r _s_i_n_g_l_e _u_s_e_r_,
     _o_r _y_o_u _m_a_y _f_i_n_d tkaepa _e_a_s_i_e_r
     % aaeennaa --pp aaeeggiiss _y_o_u
     aegis: user "_y_o_u" is now a administrator
     % aaeenndd --pp aaeeggiiss _y_o_u
     aegis: user "_y_o_u" is now a developer
     % aaeennrrvv --pp aaeeggiiss _y_o_u
     aegis: user "_y_o_u" is now a reviewer
     % aaeennii --pp aaeeggiiss _y_o_u
     aegis: user "_y_o_u" is now an integrator
     % \f[CB]aenbr -p aegis 4\fP
     aegis: project "aegis.4": created
     % \f[CB]aenbr -p aegis.4 24\fP
     aegis: project "aegis.4.24": created
     % \f[CB]aenbr -p aegis.4.24 2\fP
     aegis: project "aegis.4.24.2": created
     %


At this point, the rest of the commands in this chapter may
(should!) be executed as "_y_o_u," your usual login account.
When you added your normal account as an administrator just
now, you authorized yourself to perform the necessary
actions.




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





Howto                                                  Aegis


You will need about 120MB of free space to build and inte-
grate Aegis changes, or more, depending on the changes you
make and the size of your development directories.

The _._f_o_r_w_a_r_d file of the "aegis" user needs to be set to
someone appropriate to read mail directed at the project.

You can now set the "aegis" user's password field to "*".
This effectively prevents the "aegis" user from logging in.
Aegis is designed to make this unnecessary from now on.

1100..33..  TThhee DDoowwnnllooaadd

The Aegis project is distributed in the form of an _a_e_d_i_s_t(1)
change set.  The file to download is called
http://aegis.sourceforge.net/aegis-4.24.2.ae and can be
grabbed using your favorite web browser, or _w_g_e_t(1).

The downloaded change set is applied using the following
command

     % aaeeddiisstt ----rreecceeiivvee \\
         --ff aaeeggiiss--44..2244..22..aaee \\
         --pp aaeeggiiss..44..2244..22
     _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
     %


It is a good idea to give the project name on the command
line, or _a_e_d_i_s_t will try to use the project name it finds in
the change set, and it probably wont find it if you are
using different numbering to the chief maintainer's copy.

The _a_e_d_i_s_t command will, in turn, issue a number of other
commands.  These are all normal Aegis commands you could
issue yourself, if you were familiar with Aegis.  It will,
however, stop with a moderately alarming message:

  Warning: This change contains files which could host a
  Trojan horse attack.    You should review it before build-
  ing it or testing it or completing development.  This
  change remains in the _b_e_i_n_g _d_e_v_e_l_o_p_e_d state.

This message comes because in order to build the project,
you are going to have to execute a number of commands con-
tained in the project _a_e_g_i_s_._c_o_n_f file, and in the
_e_t_c_/_H_o_w_t_o_._c_o_o_k file.  For your own protection, _a_e_d_i_s_t stops
at this point.  You may want to inspect these two files
before continuing.

_I _r_e_a_l_l_y _m_u_s_t _g_e_t _a_r_o_u_n_d _t_o _s_i_g_n_i_n_g _i_t _w_i_t_h _P_G_P_.  _T_h_i_s _w_o_u_l_d
_m_a_k_e _t_h_e _-_n_o_t_r_o_j_a_n _o_p_t_i_o_n _s_a_f_e_, _b_e_c_a_u_s_e _y_o_u _c_o_u_l_d _t_e_l_l _t_h_e
_f_i_l_e _i_s _d_i_r_e_c_t _f_r_o_m _t_h_e _c_h_i_e_f _m_a_i_n_t_a_i_n_e_r_, _a_n_d _t_h_u_s _a_s
_t_r_u_s_t_a_b_l_e _a_s _y_o_u _t_h_i_n_k _t_h_e _c_h_i_e_f _m_a_i_n_t_a_i_n_e_r _h_a_p_p_e_n_s _t_o _b_e_.



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





Aegis                                                  Howto


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

     % aaee__pp aaeeggiiss..44..2244..22
     % aaeeccdd
     % aaeebb
     _._._._y_o_u _w_i_l_l _s_e_e _c_o_m_m_a_n_d_s _w_h_i_c_h _b_u_i_l_d _t_h_e _p_r_o_j_e_c_t_._._.
     %


Things that can go wrong...

+o There are checks to make sure that there is no white space
  on the ends of lines.  If you use Emacs, you can add

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

  to have this done automagically.  The same checks also
  verify that the text files are all printable, and that
  line lengths are 80 characters or less.  Please don't dis-
  able the checks, it makes accepting your patches more time
  consuming.

+o Each change set has an architecture list associated with
  it.  Initially you won't care, but Aegis does if you see
  the following error message:
    found 1 unlisted architecture, edit the change
    attributes to remove it or edit the project configura-
    tion file to add it
  You need to use the _a_e_c_a _-_e command (_n_o_t the tkaeca com-
  mand).  You will be placed into an editor (usually _v_i
  unless you have used Aegis before, and know how to config-
  ure it differently).  You need to leave just about every-
  thing alone, except for the architecture specification.
  Change it from

       architecture =
       [
           "unspecified",
       ];

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

       architecture =
       [
           "linux-i386",
       ];

  The alternatives may be found in the _c_o_n_f_i_g in the current
  directory (search for architecture =).  If you can't see a
  suitable choice, you may need to add one; the _a_e_p_c_o_n_f(5)
  man page has more information.  Edit the _c_o_n_f_i_g file to



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





Howto                                                  Aegis


  contain a suitable entry, and then use the _a_e_c_a _-_e command
  to have the change agree with it.

+o If you don't have Cook installed, the build command (aeb)
  will fail.

+o If you don't have GNU Bison installed, the build will
  fail.

+o If you don't have GNU Gettext installed, the error message
  run-time binaries will not be built.  This isn't an error,
  so you can keep going, but you'll get the shorter, cryptic
  form of the error messages.

+o Please note: if these instructions have a problem, let
  someone know!  If you are having a problem, so is the next
  guy.  _P_l_e_a_s_e send all problem reports to Peter Miller
  <millerp@canb.auug.org.au>

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

     % aaeedd
     _._._._y_o_u _w_i_l_l _s_e_e _c_o_m_m_a_n_d_s _w_h_i_c_h _"_d_i_f_f_" _t_h_e _p_r_o_j_e_c_t_._._.
     %


Things that can go wrong...

+o If you don't have the FHist package installed, the differ-
  ence (aed) will fail.  The _f_c_o_m_p command it is looking for
  is a whole-file context difference command (the GNU ddiiffff
  --cc is a bit too terse for humans).

Now you will need to test the change.  This is the basic
test suite for Aegis, it ensures nothing is broken.  It
takes a while, go grab a cup of coffee.

     % aaeett
     _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
     %


The change is now ready to end development.

     % aaeeddee
     aegis: project "aegis.4.24.2": change 10:
         development complete
     %


The change set is now ready to be reviewed.  In a single-
person project like this one, you can review your own work.



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





Aegis                                                  Howto


Obviously this is a conflict of interest, and larger
projects are usually configured to have Aegis prevent this.

     % aaeerrppaassss --pp aaeeggiiss..44..2244..22 --cc 1100
     aegis: project "aegis.4.24.2": change 10:
         review pass
     %


The change is now ready to be integrated.  Only when inte-
gration is complete are the files actually committed to the
repository.

     % aaeeiibb --pp aaeeggiiss..44..2244..22 --cc 1100
     % aaeebb
     _._._._y_o_u _w_i_l_l _s_e_e _c_o_m_m_a_n_d_s _w_h_i_c_h _b_u_i_l_d _t_h_e _p_r_o_j_e_c_t_._._.
     -rwsr-xr-x 1 root ... _a_r_c_h/bin/aegis
     -rwsr-xr-x 1 root ... _a_r_c_h/bin/aeimport
     -rwsr-xr-x 1 root ... _a_r_c_h/bin/aelock
     Integrator: please do the following:
       sudo .../baseline/etc/set-uid-root _a_r_c_h aegis aeimport aelock
       if they aren't root already.  See etc/set-uid-root for
       instructions for how to set-up your /etc/sudoers file.
     %


This message at the end of the build is where Aegis is made
set-uid-root in the repository.  You want to do this,
because you are going to symlink out of _/_u_s_r_/_l_o_c_a_l_/_b_i_n (or
wherever you installed Aegis) right into the baseline.  In
this way, you will be executing your bleeding-edge version
of Aegis, exercising it before you send it to anyone else.
Hang on a bit, the sending part comes later.

Don't know how to set these files set-uid-root?  The above
message includes the command to do it:

     $ ccdd _b_l_a_h_b_l_a_h//ddeellttaa**
     $$ ssuuddoo eettcc//sseett--uuiidd--rroooott _a_r_c_h aaeeggiiss aaeeiimmppoorrtt aaeelloocckk
     $$

You will need to substitute the appropriate architecture
name, although it is likely to be "unspicified on a fresh
project.

Things that can go wrong...

+o If you don't have _p_s_2_p_d_f or _p_s_s_e_l_e_c_t or _p_t_x installed, it
  won't build the documentation (this isn't an error, just
  keep going).

+o If you don't have _t_a_r_d_y(1) install, it won't build the
  tarball (this isn't an error, just keep going).




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





Howto                                                  Aegis


+o Please note: if these instructions have a problem, let
  someone know!  If you are having a problem, so is the next
  guy.  _P_l_e_a_s_e send all problem reports to Peter Miller
  <millerp@canb.auug.org.au>

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

     % aaeedd
     _._._._y_o_u _w_i_l_l _s_e_e _c_o_m_m_a_n_d_s _w_h_i_c_h _"_d_i_f_f_" _t_h_e _p_r_o_j_e_c_t_._._.
     % aaeett &&&& aaeett --bbll
     _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
     % ccdd
     % aaeeiippaassss
     _._._._y_o_u _w_i_l_l _s_e_e _c_o_m_m_a_n_d_s _c_o_m_m_i_t_t_i_n_g _t_h_e _f_i_l_e_s _t_o _f_h_i_s_t_._._.
     aegis: project "aegis.1.0": change 10:
         integrate pass
     %


The "_c_d" command you see is actually important: you need to
be out of the development directory and integration direc-
tory so that they can be cleaned up (deleted) when the
change completes.

1100..44..  SSuuppppoorrttiinngg SSeevveerraall AArrcchhiitteeccttuurreess

Aegis is able to track architectures to make sure that
change sets have been built and tested on all necessary
architectures.  You may hav notices that Aegis is calling
your architecture "unspecified", you can give it a more
descriptive name, too.

The architecture configuration data is described in the
_a_r_c_h_i_t_e_c_t_u_r_e field of the _a_e_p_c_o_n_f(1) man page.  It is based
on the _u_n_a_m_e(2) data, see the man page for how.  You will,
of course, need a change set to change it.

Once you have a change set, you need to create the
_a_e_g_i_s_._c_o_n_f_._d_/_a_r_c_h_i_t_e_c_t_u_r_e file.

     % aaeennff aaeeggiiss..ccoonnff..dd//aarrcchhiitteeccttuurree
     % aaeeffaa aaeeggiiss..ccoonnff..dd//aarrcchhiitteeccttuurree eennttiirree--ssoouurrccee--hhiiddee
     % aaeeffaa aaeeggiiss..ccoonnff..dd//aarrcchhiitteeccttuurree llooccaall--ssoouurrccee--hhiiddee
     %


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









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





Aegis                                                  Howto


     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 from the above
list that you actually have.  Having architectures in this
list that you don't routinely have access to means that you
will not be able to _a_e_d_e(1) any change sets.

Occasional architectures can be handled, too:











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





Howto                                                  Aegis


     architecture =
     [
       {
         name = "ppc-Darwin-7.x";
         pattern = "Darwin-7.*-Darwin*";
         mode = optional;
       },
     ];

Again, only do this with architectures you actually have
access to.

     If you need to have architecture specific options to
some commands, you can also have _p_r_o_j_e_c_t___s_p_e_c_i_f_i_c
attributes, too.  NNoottee that you should _f_i_r_s_t look into hav-
ing a $prefix/share/config.site or $prefix/etc/config.site
file for _._/_c_o_n_f_i_g_u_r_e to read.  This is particularly impor-
tant if you want to include _/_u_s_r_/_l_o_c_a_l_/_i_n_c_l_u_d_e,
_/_u_s_r_/_l_o_c_a_l_/_l_i_b, _e_t_c, in the various compiler flags.

1100..55..  TThhee BBlleeeeddiinngg EEddggee

As I mentioned above, the next thing to do is create sym-
bolic links out of _/_u_s_r_/_l_o_c_a_l_/_b_i_n into your Aegis baseline.
The reason for doing this is so that you exercise your Aegis
changes by using Aegis before you send them to anyone else.
(Never trust a skinny chef.)

There is a shell script called _a_e_-_s_y_m_l_i_n_k_s in the baseline
_$_a_r_c_h_/_b_i_n direcdtory.  Use it like this:

     $ aaeeccdd --bbll
     # ssuu
     Password:
     # lliinnuuxx--ii448866//bbiinn//aaee--ssyymmlliinnkkss aaeeggiiss..44..2244..22
     # eexxiitt
     $

The _l_i_n_u_x_-_i_4_8_6 may need to be replaced with the output of
the _a_e_s_u_b _-_b_l _'_$_a_r_c_h_' command if you are using something
more interesting than a PC.

1100..66..  UUnnddiissccoovveerreedd CCoouunnttrryy

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

It is strongly suggested that you complete the first change
"as is" and perform your own customizations in later
changes, rather than trying to get the project started and
customize it at the same time.

The rest of this file describes how to perform various com-
mon changes to the example project.



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





Aegis                                                  Howto


1100..77..  SSeennddiinngg CChhaannggeess

First, read the Distributed Development chapter of the User
Guide.

When you have a change set you wish to have the other Aegis
deveopers try, use a simple command such as:

     aedist --send -p aegis.4.24.2 -c _n_u_m_b_e_r | \
     gpg --clearsign | \
     mail aegis-developers@lists.sourceforge.net

or similar.  (Or maybe _a_e_p_a_t_c_h(1) instead.)  A suitable sub-
ject line would be very helpful.

1100..88..  GGuuiiddeelliinneess


1100..88..11..  WWhhaatt YYoouu CCaann DDoo

Write more documentation.  There is a crying need for docu-
mentation of all sorts: better manual pages, more and better
information in the User Guide, more and better HOWTOs.  If
you work out how to do something, and it isn't in the docu-
mentation, write some documentation and put it in a change
set because other folks have probably missed it too.

Add more ease-of-use functionality.  Stuff which makes the
development process more efficient, or makes the information
in the repository more accessible.

Extend the GUI.  All of the commands which manipulate the
change while in the _b_e_i_n_g _d_e_v_e_l_o_p_e_d state are candidates.
Some kind of wrapper that ties it all together would be
good, too.  User preferences, project attributes and creat-
ing projects are candidates, too.

Most new project configuration things belong in the project
_c_o_n_f_i_g file.  Only add new project attributes (aepa -e) for
things which (a) are catch 22 to change in a change set, or
(b) allow a security abuse if in a change set (e.g. the
notify commands, particularly aede), or (c) allow the repos-
itory to be damaged.  (My thanks to Ralf Fassel
<ralf@akutech.de> 2 Feb 1999 for pointing this out.)

1100..88..22..  WWhhaatt YYoouu CCaann''tt DDoo

You can't change Aegis' semantics.  Developers around the
world, and their managers, rely on Aegis working just the
way it does right now.  You can't change things that will
compromise their ability to get things done.

Particularly, Aegis has a strong security story.  Availabil-
ity, integrity and confidentiality, and all that.  If you



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





Howto                                                  Aegis


want it more flexible, that's good, but you can't change the
defaults and you can't make it irretrievably weaker.  (You
can, as a _n_o_n-default make it weaker, within limits.)

Aegis (the executable, not the whole package) is quite big
enough.  Don't add code to _a_r_c_h/bin/aegis than can be done
with the report generator, or as a separate program like
aesub or aefind.  More GUI can be added using Tk/Tcl -
unless you have grander plans and even then it _s_t_i_l_l
shouldn't be added to the set-uid-root executable.

1100..99..  CCooddiinngg SSttyyllee

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

Probably need a GNU Indent profile for code formatting, too.

1100..1100..  WWrriittiinngg TTeessttss

If you have fixed a bug you should write a test to verify
the correct behaviour of Aegis.  Because test file names are
generated automatically starting from your repository state,
it's possible that _a_e_t will create a test with the same name
as one in the P.Miller repository.  Because Aegis is not yet
able to detect such situation, if you plan to send back your
work to P.Miller you may want to modify your aegis.conf
adding the following lines:

     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 collision should be
reduced.  Invoke _a_e_n_t:

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

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

+o In order to improve error messages you should organize
  your script as a sequence of activity and use the _a_c_t_i_v_i_t_y
  variable as sketched below:





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





Aegis                                                  Howto


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

  If you are reading this document, you probably don't need
  help to understand this code fragment, the only thing to
  note is that the number in the string (163) refer to the
  current line number and is used when printing a failure
  message.  You don't need to maintain it by hand as
  explained in the following step.

+o You can use test/activity.sh to automatically renumber the
  activity variables of your tests:

       $ sshh tteesstt//aaccttiivviittyy..sshh
       test/01/t0159a-walt.sh...
       test/01/t0160a-walt.sh...
       $

  If you have not modified test/activity.sh you should find
  it as bl/test/activity.sh or blbl/test/activity.sh.

1100..1111..  DDeebbuuggggiinngg

Aegis, as any other software, may contain undiscovered bugs.
If you are interested in helping to fix these bugs, and as a
developer you should be interested, the first thing to do is
compiling Aegis in DEBUG mode.  In order to do so you must
modify common/main.h and uncomment the DEBUG define.  (If
you use the _a_e_c_p _-_r_e_a_d_-_o_n_l_y option, Aegis will remind you to
uncopy the file again before develop end, ensuring that you
don't accidentally integrate this.)

In DEBUG mode the -Trace command line option is available
for most Aegis commands.  This option is followed by the
names of the source files you want to trace, and may be used
more than once.

If you need to add tracing capability to a file, you must
first include trace.h, modify the code in order to use the
trace facility (look at common/trace.h) then build the
change with _a_e_b and run the buggy command with the proper
-Trace option.

On Linux >= 2.4 the _a_e_g_i_s command, wich is set-uid-root, is
enabled to dump core when needed.  If this does not happen,



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





Howto                                                  Aegis


remember to verify the _u_l_i_m_i_t(1) settings; you may need to
execute the _u_l_i_m_i_t _-_c _u_n_l_i_m_i_t_e_d command.

1100..1122..  TThhee TToo--DDoo LLiisstt

+o Add an additonal mode to _a_e_d_i_s_t to query an _a_e_g_e_t server
  for change set UUIDs and download and apply missing change
  sets.  It needs to be able to be run by _c_r_o_n(8).  Submit-
  ted: PMiller, 1-Jun-2004

1100..1122..11..  aaeeccvvsssseerrvveerr

+o The aecvsserver needs to be extensively tested by users.
  Submitted: PMiller, 1-Jun-2004

+o Implement more of the CVS client commands which can be
  sent to the server, usually by saying "yes, bwana" and
  doing nothing.  Submitted: PMiller, 1-Jun-2004

+o Implement a cvs commit against a project (at the moment
  this is not allowed because you have to use a "module"
  named after a change set) which will create a change set
  apply the changes and do everything to get to aede.  Sub-
  mitted: PMiller, 1-Jun-2004

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

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

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

1100..1122..22..  GGeeooggrraapphhiiccaallllyy DDiissttrriibbuutteedd DDeevveellooppmmeenntt

+o The _a_e_d_i_s_t _-_r_e_c_e_i_v_e command needs to be enhanced to under-
  stand file attributes.  Submitted: PMiller, 2-Jun-2004

+o The _a_e_p_a_t_c_h _-_r_e_c_e_i_v_e command needs to be enhanced to
  understand file attributes.  Submitted: PMiller,
  2-Jun-2004

+o Enhance the _a_e_d_i_s_t _-_r_e_c_e_i_v_e command to understand incoming
  files with UUIDs.  Submitted: PMiller, 1-Jun-2004

+o Enhance the _a_e_p_a_t_c_h _-_r_e_c_e_i_v_e command to understand incom-
  ing files with UUIDs.  Submitted: PMiller, 1-Jun-2004

+o Add an additonal mode to _a_e_d_i_s_t to query an _a_e_g_e_t server
  for change set UUIDs and download and apply missing change
  sets.  It needs to be able to be run by _c_r_o_n(8).  Submit-
  ted: PMiller, 1-Jun-2004



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





Aegis                                                  Howto


+o Enhance _a_e_d_i_s_t to preserve change history (both send and
  receive will need work).  Don't forget backwards compati-
  bility.  Submitted: Jerry Pendergraft, 2003

+o Enhance _a_e_d_i_s_t _-_r_e_c_e_i_v_e to leave changes in _a_w_a_i_t_i_n_g
  _d_e_v_e_l_o_p_m_e_n_t or _b_e_i_n_g _d_e_v_e_l_o_p_e_d if that's the state they
  were in at the origin.  Submitted: Jerry Pendergraft,
  May-2004

+o Enhance _a_e_p_a_t_c_h _-_r_e_c_e_i_v_e to run tests on changes which
  require it.  Submitted: PMiller, 1-Jun-2004

+o Enhance _a_e_p_a_t_c_h to preserve change history (both send and
  receive will need work).  Incoming patches with no meta-
  data obviously can't do this.  Don't forget meta-data
  backwards compatibility.  Submitted: PMiller, 1-Jun-2004

+o Enhance _a_e_p_a_t_c_h _-_r_e_c_e_i_v_e to leave changes in _b_e_i_n_g _d_e_v_e_l_-
  _o_p_e_d if that's the state they were in at the origin.
  Patches with no meta-data stay in _b_e_i_n_g _d_e_v_e_l_o_p_e_d.  Sub-
  mitted: PMiller, 1-Jun-2004

+o Enhance _a_e_p_a_t_c_h and _a_e_d_i_s_t to automagically sign (send)
  and verify (receive) the contents, using the (revolting)
  library from the _g_p_g_m_e project.  This stupid library
  spawns an _g_p_g(1) instance and talks to it; unlike a sensi-
  ble library _e_._g_. the _z_l_i_b project; why on earth couldn't
  they take the common code from gpg and make a library of
  _t_h_a_t_?  Submitted: PMiller, 1-Jun-2004

1100..1122..33..  DDooccuummeennttaattiioonn

+o Add a section to the branching chapter of the User Guide,
  describing how a developer may use a branch to temporarily
  waive the build command.  After a series of changes on
  this branch, the build command is restored, and the branch
  development ended.  This allows regular "non working" com-
  mits, without losing any of the strengths of the Aegis
  process.  Submitted: 7-Mar-2000

+o The manual pages need to have an example(s) section added
  to make them clearer.  This isn't just for beginners,
  infrequently used commands need examples even for sophis-
  ticated Aegis users..  Submitted: Geoff Soutter
  <geoff@whitewolf.com.au>, 3 Mar 2000

+o Get tkdiff 3-way merge working with Aegis (see
  http://www.ede.com/free/tkdiff/ for code).  Submitted:
  24-jan-2000

+o Add information to the History Tool chapter, describing
  how to use CVSup to access the RCS history tree.  Submit-
  ted: 28-jan-2000




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





Howto                                                  Aegis


+o the RCS history commands in the aegis user guide all use
  the `-u' option for `ci' to check out a copy after regis-
  tering/updating a file.  However `ci -u' always does key-
  word expansion.  To avoid this, we have omitted the -u, so
  the working file is gone after the `ci'.  We check it out
  again using `co', this time with the `-ko' option to avoid
  keyword expansion.  Note that the -ko option is always
  given to the `co' command, never to `ci' or `rcs'.  Sub-
  mitted: Ralf Fassel <ralf@akutech.de>, 18 Jan 2000

+o * diff ; test $? -le 1 -> diff ; test $? -ne 1 means that
  unchanged files prevent aede!!  (Only fly in the ointment
  is moving files - need to cope with this.)  Submitted: Gus
  <gus@getsystems.com> 28 Jul 1999

+o mention in the diff tool part of the User Guide, that you
  can mess with diff_command to exclude with binary files,
  or file with CR in them, or lines too long, _e_t_c.  Submit-
  ted: PMiller, 28-jun-99

+o in the branching chapter, have a section about using sub-
  branches to turn build_command off (or to ignore exit sta-
  tus), and integrate lots of teensy tiny bug fixes, and
  then turn it on again.  In the front, reference the
  branching chapter in "how to extend the Aegis process"
  Can mention extra review steps there, too.  Submitted:
  choffman@dvcorp.com, 22 Jun 1999

+o Document the build_time_adjust_notify_command in the DMT
  chapter of the User Guide.  Update the example projects to
  use it.  Update the config example to use it.  Submitted:
  PMiller, 4-Apr-99

+o Mention binary files in the diff and merge section (may
  provide aebinfil command to help choose which behavior?)
  Submitted: PMiller, 31-mar-99

+o mention "rcs -ko" in the User Guide and put it into the
  examples AND also fhist keywords in the User Guide and put
  it into the examples.  and make sure the examples all have
  hist_{put,create} the same.  Subject: Ralf Fassel
  <ralf@akutech.de>, 9 Mar 1999

+o worked example, "5.2.7 says that the cook file contains
  all of the above commands but my copy doesn't have them
  ..."  [for config file and howto.cook file] BUT integra-
  tion diffs not in the worked example.  Submitted: Michael
  McCarty <mmccarty@xinetix.com>, 26-Feb-99

+o need discussion (Howto, or maybe the User Guide) of how to
  use Aegis when you site has a mix of Unix and Wintel.
  Submitted: Paolo Supino <paolo@schema.co.il>, 4 Feb 1999





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





Aegis                                                  Howto


+o add chapter to User Guide, saying how to config web inter-
  face and how to use it.  Submitted: Graham Wheeler
  <gram@cdsec.com>, 27 Jan 1999

+o User Guide: big changes bouncing: how to use a branch to
  get smaller reviews and smaller diffs.  Submitted: Ralf
  Fassel <ralf@akutech.de>, 27 Jan 1999

+o note for User Guide: metrics software form
  ftp://ftp.qucis.queensu.ca/pub/software-eng/software/-
  Cmetrics/

+o correct documentation of file locking in UG: correct the
  example around the file locking - it gives the wrong text
  of the aede error - and probably other stuff.  also, the
  wrong person comes back from aerobics

1100..1122..44..  MMoorree RReeppoorrttss

+o Add a -REVerse option, so that all of the listings (ael)
  come out in the reverse order to that used at present.
  Submitted: John Darrington <johnd@ot.com.au>, 20-Jul-2001

+o Write an _a_e_r_e_p_o_r_t file to produce MS-Project views of a
  project, making sure that the states of each change are
  linked, use averages to predict any incomplete states.
  And maybe another to produce HTML pages of the same thing.
  Submitted: 15-Jan-2000

+o On the _a_e_g_e_t(1) web pages, link the file edit numbers to
  pages which will retrieve the historical version.  Submit-
  ted: Anoop Kulkarni <anoop@sasi.com>, 22 Dec 1999

+o Add a user_change report (just like "ael user_changes")
  which takes a user name, so you can get a list of changes
  by user.  Make _a_e_g_e_t(1) do this, too.  Submitted: Ralf
  Fassel <ralf@akutech.de>, 9 Dec 1999

+o Add a outstanding_changes report (just like "ael outstand-
  ing_changes") which takes a user name, so you can get a
  list of outstanding changes by user.  Make _a_e_g_e_t(1) do
  this, too.  Submitted: Ralf Fassel <ralf@akutech.de>, 9
  Dec 1999

+o Write a report which says when you have to do to get a
  change completed Jerry says he has written most of this.
  Submitted: jerry.pendergraft@endocardial.com 3-Nov-99

+o ael change_history - write as a report and then include
  project history for sub branches.  Don't forget the web
  reports, too.  Submitted:Jerry Pendergraft <jerry@endocar-
  dial.com>, 30 Aug 1999





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





Howto                                                  Aegis


+o ael outstanding_changes - rewrite as a report and then
  include sub branches.  Don't forget the web reports, too.
  Submitted: Jerry Pendergraft <jerry@endocardial.com>, 30
  Aug 1999

+o ael project_history - rewrite as a report and then include
  parents and sub branches.  Don't forget the web reports,
  too.  Submitted: Jerry Pendergraft <jerry@endocar-
  dial.com>, 30 Aug 1999

+o aer file_history - include parents and sub branches.
  Don't forget the web reports, too.  Submitted: Jerry Pen-
  dergraft <jerry@endocardial.com> 30 Aug 1999

+o Some kind of web report which makes "train track" diagrams
  of file branching.

+o Some kind of web report which makes "train track" diagrams
  of project branching.

+o multivariate linear regression: needed as a report genera-
  tor function: needed for metrics analysis

+o more blurb in the statistics web pages, so they are more
  self-explaining Submitted: Ralf Fassel <ralf@akutech.de>,
  13-Oct-98

+o Add anew report like "ael uc" except that it (optionally)
  takes a user name as well, to list a particular user's
  changes.

+o File Activity Report (web) does not translate user name
  and give email link.  Should also put user name under
  change state, as in change lists.

1100..1122..55..  CCoorree EEnnhhaanncceemmeennttss

+o Use the per-file attributes to record the encoding of the
  text (e.g. UTF-8) and the line termination.  Provide a way
  (via the iconv(3) function? via recode(1) command?) to
  change the encoding.  Submitted: PMiller, 23-Jun-2004

+o "I have determined that one reason [that aedeu is used in
  preference to aerfail] is the reviewer is afraid they
  don't understand the change and once explained they would
  not fail it.  Now the fact that the description, comments
  etc did not do the job to explain the change is reason
  enough to fail it notwithstanding...  They are saying if
  they had an aerfu command they would be willing to aerf
  changes. How difficult would that be?"  Not very difficult
  at all.  Provided, of course, that nothing has been
  changed in the mean time (and Aegis has everything it
  needs to check that).  Submitted: Jerry Pendergraft,
  23-Jun-2004



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





Aegis                                                  Howto


+o The project_file_roll_forward function needs to be
  enhanced to understand file UUIDs.  Submitted: PMiller,
  1-Jun-2004

+o Now the sources are all being compiled by a C++ cimpiler,
  convert the various OO portions of the code (inout_ty and
  its derived classes, output_ty, etc) to true C++.  Need a
  style guide first, so other developers know how I want it
  done.  See SRecord for examples until this is done.  Sub-
  mitted: PMiller, 1-Jun-2004

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

+o Add a "development directory style" configuration option.
  The current styles are "view path" and two types of "sym-
  link farm", although this is well concealed by the code.
  Need to add a hard link (arch-ish) / copyfile (cvs-ish)
  style as well, but only for source files.  The code which
  currently maintains the symlinks can be pressed into doing
  the extra work fairly easily.  Submitted: PMiller,
  1-Jun-2004

+o It would be nice to have a way to specify a timeout for
  aegis tests.  If a single test does not finish within this
  time, it should be aborted and considered `No Result'.
  Then aet should continue with the next test (as appropri-
  ate if --persevere was given).  A `--timeout' argument to
  `aet' would do the trick, and also a project config field.
  The implementation could be interesting, since signaling
  the forked aegis child process might not be enough to stop
  all processes (process groups?).  Submitted: Ralf Fassel
  <ralf@akutech.de>, 24-Jan-2001

+o Problem with aepa that doesn't specify the default values
  for all the test features in aeca (there are three types
  in aeca and only one in aepa).  Submitted: Mark Veltzer
  <mark2776@yahoo.com>, 16 Aug 2001

+o The _a_e_d_i_s_t(1) program should send changes with no files,
  or changes in "being developed".  Submitted: Mark Veltzer
  <mark2776@yahoo.com>, 16 Aug 2001

+o Have _a_e_m merge changes properly if another changed moved
  the file in the baseline.  You need to do this across the
  board, not just in aegis/aed.c Submitted: Ralf Fassel
  <ralf@akutech.de>, 25 Feb 2000

+o Add progress (%) indicators (aeib was specific example,
  but there may be others _e_._g_. symlink farms and aecp, even
  aede for big changes) for use by the GUI interfaces - and
  maybe the text interface too.  Submitted: Ralf Fassel
  <ralf@akutech.de> 10 Dec 1999




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





Howto                                                  Aegis


+o Extend the create_symlinks_before_build functionality to
  copy, not just symlink.  Because they would edit the files
  direct, we then need an implicit aecpcorne detector.  You
  need to look for other boundary conditions this is also
  going to affect.  You need a remove_symlinks_after_build
  analogue, too.  Submitted: Darrin Thompson <dthomp-
  son@characterlink.net>, 15 Nov 1999

+o os.h is a system header on some systems, so os.h has to
  move Sumbitted: Christophe Broult <broult@info.unicaen.fr>
  30 Sep 1999

+o aedist -rec needs to preserve (a) copyright years, (b)
  test exemptions (subject to permissions), and (c) archi-
  tecture (if possible).  AND CHANGE NUMBER?  Submitted:
  Ewolt Wolters <ewolt@pallas-athena.com>, 27 Jul 1999

+o Aedist to add project history to end of description when
  sending change set.  Submitted: Jerry Pendergraft
  <jerry@endocardial.com>, Dec-2000

+o can we separate change creation from other administrator
  permissions?  can we make "everyone" able to create
  changes?  Submitted: Ewolt Wolters <ewolt@pallas-
  athena.com>, 28 Jun 1999

+o should explicitly mention CPPFLAGS=-I/usr/local/include;
  export CPPFLAGS LDFLAGS=-L/usr/local/lib; export LDFLAGS
  in the configuring section.  Submitted: John Huddleston
  <jhudd@cody.itc.nrcs.usda.gov>, 19 Mar 1999

+o Using file attributes, add coupling between files to form
  file groups; this means when you aecp, you get the whole
  set of related files.  Submitted: PMiller, 18-Feb-99

+o The aed command does not promote aenf->aecp unless the ,D
  file does not exist.  This is annoying, should always do
  it.  (So should some other commands.)  Subject: Ralf Fas-
  sel <ralf@akutech.de>, 1 Feb 1999

+o Add a default_regression_test_exemption project attribute.
  Submitted: Ralf Fassel <ralf@akutech.de>, 31 Jan 1999,
       Jerry Pendergraft <jerry@endocardial.com>, 2 Feb
  2001.

+o Need a clean_exceptions file in the project config file
  (list of strings) so can have local RCS dirs, and do "ci
  `aegis -l cf -ter`" in the develop_end_command Submitted:
  1-Feb-99

+o aenpr -dir -keep: allow directory to already exist if has
  right owner and is empty?  Submitted: Jerry Pendergraft
  <jerry@endocardial.com>, 22 Jan 1999




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





Aegis                                                  Howto


+o Add a new post_merge_command so can generate summary of
  files needing editing.  Subject: Ralf Fassel
  <ralf@akutech.de>, 21 Dec 1998

+o Create a new aepatch command: "aepatch -send" to create
  "ordinary" OpenSource source patches, and "aepatch
  -receive" to turn patches into an Aegis change - and not
  necessarily only patches generated with aepatch.  Yes,
  intentionally similar to aedist.

+o integrate difference should look for missing ,D files
  (usually impossible) and re-instate them.  Submitted:
  PMiller, 22-Sep-98

+o tests 7, 20, 70 warn symlink.c: In function `main': sym-
  link.c:5: warning: return type of `main' is not `int' Sub-
  mitted: Bruce Stephen Adams <brucea@cybernet-
  ics.demon.co.uk>, 10 Sep 1998

+o change_set_env needs to set LINES and COLS

+o commands which accept -branch and/or -trunk should also
  accept -grandparent but not all do.  check.

+o Add a --no-baseline-lock option to the aeb and aecp com-
  mands.  Warn them not to in the manual pages.

+o list locks - need to spot the case where *all* of a set
  are taken (all 64k) and report sensibly (not 64K lines)

+o aemv does not correctly check the -to- filename.  (spe-
  cific example = file name length)

+o aefind needs a sort option

+o aefind needs the rest of the find functionality added

+o * Add a -output option to the aent command (_o_t_h_e_r_s_?)  for
  scripting support.

+o aed - when auto upgrade create to modify, clear move if
  set.

+o aede needs to make sure that the files (and directories)
  are readable (and searchable) by reviewers.

+o make aemv rename files within a change

+o aecp -anticipate

+o Make the listing more specific for aecp aecpu aenfu aentu
  aerm aermu, etc





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





Howto                                                  Aegis


+o add a file copy notification command to the project config
  file

+o Add pseudo change do can do many integrations at once
  (this pseudo change would be created by aeib and destroyed
  by aeipass, aeifail or aeibu).

+o Version punctuation: at the moment you gets dots between
  the branch numbers.  Need more flexible punctuation: espe-
  cially, want a hyphen first, then dots (sometimes).

+o * aecp -delta bug      "I've been making good use of the
  "-delta" option of aecp lately.       But there has been a
  complication in its use.  Let's say a file      was
  aerm'ed in delta 100.  Let's further say that we are at
  delta      175 and are trying to restore the source code
  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: markm@endo.com

+o internationalize -interactive

+o Enhance aet to allow reviewers to run tests.

+o check library state files on project creation      "I was
  creating a new release from a large project.       After
  copying the      baseline and creating hundreds of history
  files the aenrls failed      because the library dir I
  specified wasn't writable by aegis and no      state file
  was created. Couldn't this be checked first?"  Submitted:
  Lloyd Fischer <lloyd@dvcorp.com>

+o Add precedence constraints: a list of prerequisite
  changes, which must all be in the "completed" state before
  the change may end development.  Submitted: Christian F.
  Goetze <c-goetze@u-aizu.ac.jp>

+o If there is a read error when reading the template source
  file during aent, get a stupid error within error message,
  and never tells you about the file

+o How about "include" support for the config file?  That way
  one could also cover architecture specific things by
  "include ${libdir}/${project}.defs" in the config file.
  Submitted: Jerry Pendergraft <jerry.pendergraft@endocar-
  dial.com>, 7 Sep 2001

+o Add an _a_e_t_o_u_c_h command, to touch all of the (non-build)
  source files in the change.  Submitted: 2001

+o Have the "aeclean -list" option say what aeclean would do,
  rather than list the change source files.  Submitted: 2001




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





Aegis                                                  Howto


+o Have aed (aem) *remember* the previous state when it finds
  a problem (much like aet does, now).  Submitted: Ralf Fas-
  sel <ralf@akutech.de> 3-Mar-2002

1100..1122..55..11..  MMoorree OO((11)) SSccaallaabbiilliittyy

+o 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.

+o Need the fstate file to have a manifest field; access this
  for file names.  Then, store each file into in a separate
  file; only access this file is file state is required.

+o The presence or absence of the manifest field in the top-
  level fstate file tells you if the old or new file state
  usage is present.

1100..1122..66..  GGUUII

+o tkaeca barfs when there are no changes on the branch.
  should be more graceful.  Submitted: Ewolt Wolters
  <ewolt@pallas-athena.com>, 11 Aug 1999

+o using tkaegis: project > branch > role > integrate, a win-
  dow pops up "Error in tcl script, Error: invalid command
  name ".mbar.review.menu"".  Submitted: Ewolt Wolters
  <ewolt@pallas-athena.com> 9 Aug 1999

+o user pasted in text (including back slash) into aeifail
  edit window.  which was accepted, but broke change state
  (illegal escape sequence).  Submitted: Michael McCarty
  <mmccarty@xinetix.com>, 10 May 1999

+o A new ${architecture_list} substitution to give all archi-
  tectures in a command.  Submitted: jerry.pendergraft@endo-
  cardial.com, 31 Mar 1999

+o have aedist -rec accept a -delta option, so you can tell
  it where to apply from.  Anticipated use is "-delta 0"
  meaning start of branch.  (also a -reg option).  Submit-
  ted: PMiller, 22-mar-99

1100..1122..77..  RReelleeaassee aanndd BBuuiilldd aanndd IInnssttaallll

+o add debian .deb file, add notification to <cd@debian.org>
  for new releases.  Submitted: PMiller, 22-Jun-99

+o building documentation needs to talk about libz some more.
  particularly, you either need it on ROOT's LD_LIBRARY_PATH
  or you need to static link it.  Submitted: Ralf Fassel
  <ralf@akutech.de> 5-Apr-99




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





Howto                                                  Aegis


+o have configure script whine about missing libz Submitted:
  PMiller, 7 Apr 99

+o have configure script whine about missing regcomp Submit-
  ted: PMiller, 7 Apr 99

+o Sample documentation needs to make the _g_r_o_u_p thing obvi-
  ous.  And also the umask at aenpr time!  Submitted: Alan
  Zimmerman <alanz@electrosolv.co.za>, 5 Apr 1999

+o generated makefile CC=cc needs to quote cc in case has
  spaces Submitted: Aaron Johnson <adj@ccltd.com>, 31 Mar
  1999

+o The BUILDING file needs to mention that you should install
  zlib with --prefix=/usr because many systems think
  /usr/local/lib "insecure directory".  Submitted: Fabien
  Campagne <campagne@Inka.MSSM.EDU>, 26 Mar 1999

+o add piece to BUILDING file saying to get Apache first.
  Submitted: Graham Wheeler <gram@cdsec.com> 27 Jan 1999

1100..1122..88..  DDaattaabbaassee

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

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




























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





Aegis                                                  Howto


  .
























































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





Aegis                                                  Howto



                      TTaabbllee ooff CCoonntteennttss


  1. Introduction  . . . . . . . . . . . . . . . . . . .   3
    1.1. Assumed Knowledge . . . . . . . . . . . . . . .   3
    1.2. Howto Install Aegis . . . . . . . . . . . . . .   3
    1.3. Howto Contribute  . . . . . . . . . . . . . . .   3
  2. Cheat Sheet . . . . . . . . . . . . . . . . . . . .   4
    2.1. Common Commands . . . . . . . . . . . . . . . .   4
    2.2. Developer Commands  . . . . . . . . . . . . . .   5
    2.3. Reviewer Commands . . . . . . . . . . . . . . .   6
    2.4. Integrator Commands . . . . . . . . . . . . . .   6
    2.5. Project Administrator Commands  . . . . . . . .   6
  3. How to Start Using Aegis  . . . . . . . . . . . . .   8
    3.1. First, Create The Project . . . . . . . . . . .   8
    3.2. Second, Use a Template Project  . . . . . . . .   8
    3.3. Second, Copy a Template Project . . . . . . . .   8
  4. How to Recreate Old Versions  . . . . . . . . . . .  10
    4.1. aecp  . . . . . . . . . . . . . . . . . . . . .  10
    4.2. Finding Delta Numbers . . . . . . . . . . . . .  10
    4.3. ${version}  . . . . . . . . . . . . . . . . . .  11
    4.4. Out Of Date . . . . . . . . . . . . . . . . . .  11
  5. How to Create a New Project . . . . . . . . . . . .  13
    5.1. Single User Project . . . . . . . . . . . . . .  13
    5.2. Two User Project  . . . . . . . . . . . . . . .  14
    5.3. Multi User Project  . . . . . . . . . . . . . .  15
    5.4. Warning . . . . . . . . . . . . . . . . . . . .  15
    5.5. Changing The Project Owner  . . . . . . . . . .  16
  6. How to Move a Project . . . . . . . . . . . . . . .  18
    6.1. Relocating a Project  . . . . . . . . . . . . .  18
    6.2. Renaming a Project  . . . . . . . . . . . . . .  19
  7. Working in Teams  . . . . . . . . . . . . . . . . .  20
    7.1. Local . . . . . . . . . . . . . . . . . . . . .  20
    7.2. Distributed . . . . . . . . . . . . . . . . . .  23
  8. How to use Aegis with Python  . . . . . . . . . . .  26
    8.1. Handling Aegis search paths . . . . . . . . . .  26
    8.2. The build step  . . . . . . . . . . . . . . . .  28
    8.3. Testing . . . . . . . . . . . . . . . . . . . .  29
    8.4. Running your programs . . . . . . . . . . . . .  30
  9. Howto End A Branch  . . . . . . . . . . . . . . . .  32
  10. How to Become an Aegis Developer . . . . . . . . .  34
    10.1. Required Software  . . . . . . . . . . . . . .  34
    10.2. Create The Aegis Project . . . . . . . . . . .  37
    10.3. The Download . . . . . . . . . . . . . . . . .  38
    10.4. Supporting Several Architectures . . . . . . .  42
    10.5. The Bleeding Edge  . . . . . . . . . . . . . .  44
    10.6. Undiscovered Country . . . . . . . . . . . . .  44
    10.7. Sending Changes  . . . . . . . . . . . . . . .  45
    10.8. Guidelines . . . . . . . . . . . . . . . . . .  45
    10.9. Coding Style . . . . . . . . . . . . . . . . .  46
    10.10. Writing Tests . . . . . . . . . . . . . . . .  46
    10.11. Debugging . . . . . . . . . . . . . . . . . .  47
    10.12. The To-Do List  . . . . . . . . . . . . . . .  48



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





Howto                                                  Aegis



























































Page 1002                    ()                 Peter Miller


