





.













                           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 23 November 2024.






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


11..  IInnttrroodduuccttiioonn

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.

11..11..  AAssssuummeedd KKnnoowwlleeddggee

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.

11..22..  HHoowwttoo IInnssttaallll AAeeggiiss

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.

11..33..  HHoowwttoo CCoonnttrriibbuuttee

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


22..  CChheeaatt SShheeeett

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

22..11..  CCoommmmoonn CCoommmmaannddss

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.

22..22..  DDeevveellooppeerr CCoommmmaannddss

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.

22..33..  RReevviieewweerr CCoommmmaannddss

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.

22..44..  IInntteeggrraattoorr CCoommmmaannddss

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.

22..55..  PPrroojjeecctt AAddmmiinniissttrraattoorr CCoommmmaannddss

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


33..  HHooww ttoo SSttaarrtt UUssiinngg AAeeggiiss

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.

33..11..  FFiirrsstt,, CCrreeaattee TThhee PPrroojjeecctt

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.

33..22..  SSeeccoonndd,, UUssee aa TTeemmppllaattee PPrroojjeecctt

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

33..33..  SSeeccoonndd,, CCooppyy aa TTeemmppllaattee PPrroojjeecctt

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


44..  HHooww ttoo RReeccrreeaattee OOlldd VVeerrssiioonnss

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

44..11..  aaeeccpp

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:

--DDEELLttaa _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.

--BBRRaanncchh _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.

--DDEELLttaa--FFrroomm--CChhaannggee _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.

--DDEELLttaa--DDaattee ""_s_t_r_i_n_g""
  TThhiiss ooppttiioonn tteellllss _a_e_c_p((11)) ttoo eexxttrraacctt aann hhiissttoorriiccaall vveerrssiioonn
  ooff tthhee ffiilleess,, rraatthheerr tthhaann tthhee hheeaadd rreevviissiioonn ((tthhee oonnee  vviiss--
  aabbllee  iinn tthhee bbaasseelliinnee))..  YYoouu oonnllyy nneeeedd tthhee ddaattee tthhee cchhaannggee
  wwaass iinntteeggrraatteedd ttoo uussee tthhiiss ooppttiioonn..   IItt  uunnddeerrssttaannddss  mmaannyy
  ffoorrmmss ooff wwrriitttteenn ((EEnngglliisshh)) ddaatteess,, bbuutt ttrryy ttoo aavvooiidd aammbbiigguu--
  oouuss mmoonntthh nnuummbbeerriinngg ((iitt ccaann bbee ccoonnffuusseedd bbyy  ssoommee  EEuurrooppeeaann
  vvss.. AAmmeerriiccaann nnuummeerriicc ffoorrmmaattss,, uussee mmoonntthh nnaammeess iinnsstteeaadd))..

44..22..  FFiinnddiinngg DDeellttaa NNuummbbeerrss

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 --BBRRaanncchh 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.

44..33..  $${{vveerrssiioonn}}

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 --vveerrssiioonn command line option.  For example:

     % aaeeggiiss ----vveerrssiioonn
     aegis version 4.15.D012
     %


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

     % aaeeccpp ----cchhaannggee==44..1155..DD001122 ..
     %

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  --BBRRaanncchh  and  --DDEELLttaa
options into a single command line option.

44..44..  OOuutt OOff DDaattee

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

     % aaeeccppuu --uunncchhaannggeedd
     %

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

     % aaeell ccff || ggrreepp ''((''
     %

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


55..  HHooww ttoo CCrreeaattee aa NNeeww PPrroojjeecctt

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.

55..11..  SSiinnggllee UUsseerr PPrroojjeecctt

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 nnoo oonnee 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.)

55..22..  TTwwoo UUsseerr PPrroojjeecctt

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.

55..33..  MMuullttii UUsseerr PPrroojjeecctt

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.

55..44..  WWaarrnniinngg

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.

55..44..11..  CCrreeaattiinngg PPrroojjeeccttss

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.

55..44..22..  WWeebb VViissiibbiilliittyy

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.

55..55..  CChhaannggiinngg TThhee PPrroojjeecctt OOwwnneerr

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 ddoott 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


66..  HHooww ttoo MMoovvee aa PPrroojjeecctt

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.

66..11..  RReellooccaattiinngg aa PPrroojjeecctt

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

66..11..11..  FFrroomm wwiitthhiinn AAeeggiiss

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.

66..11..22..  FFrroomm oouuttssiiddee AAeeggiiss

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.

66..22..  RReennaammiinngg aa PPrroojjeecctt

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

66..22..11..  FFrroomm wwiitthhiinn AAeeggiiss

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.

66..22..22..  FFrroomm oouuttssiiddee AAeeggiiss

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.

66..22..33..  PPrroojjeecctt AAlliiaasseess

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


77..  WWoorrkkiinngg iinn TTeeaammss

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.

77..11..  LLooccaall


77..11..11..  SSiinnggllee UUsseerr,, SSiinnggllee MMaacchhiinnee

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.

77..11..22..  MMuullttii UUsseerr,, SSiinnggllee MMaacchhiinnee

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.

77..11..33..  MMuullttii UUsseerr,, MMuullttii MMaacchhiinnee

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.

77..11..33..11..  GGeenneerraall RReeqquuiirreemmeennttss

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 ddoonn''tt
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,  bbuutt!!   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.

77..11..33..22..  AAeeggiiss--ssppeecciiffiicc RReeqquuiirreemmeennttss

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.

77..11..44..  KKnnoowwnn PPrroobblleemmss

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.

77..22..  DDiissttrriibbuutteedd

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.

77..22..11..  MMuullttiippllee SSiinnggllee--UUsseerr SSiitteess

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


77..22..22..  MMuullttiippllee MMuullttii--UUsseerr SSiitteess

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.

77..22..33..  TTeelleeccoommmmuuttiinngg

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.

77..22..33..11..  OOffffiiccee ttoo DDeevveellooppeerr

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.

77..22..33..22..  DDeevveellooppeerr ttoo OOffffiiccee

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


88..  HHooww ttoo uussee AAeeggiiss wwiitthh PPyytthhoonn

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

88..11..  HHaannddlliinngg AAeeggiiss sseeaarrcchh ppaatthhss

88..11..11..  TThhee AAeeggiiss mmooddeell vvss.. tthhee PPyytthhoonn mmooddeell

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.

88..11..22..  TThhee ssoolluuttiioonn

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:

NNeevveerr iinnjjeecctt aannyy aabbssoolluuttee ppaatthh ooff aannyy  AAeeggiiss  bbaasseelliinnee  iinnttoo
tthhee PPyytthhoonn sseeaarrcchh ppaatthh..

88..11..33..  WWhhyy sseettttiinngg PPYYTTHHOONNPPAATTHH ttoo tthhee AAeeggiiss sseeaarrcchh ppaatthh wwiillll
nnoott wwoorrkk

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.

88..22..  TThhee bbuuiilldd sstteepp

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.

88..33..  TTeessttiinngg

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.

88..44..  RRuunnnniinngg yyoouurr pprrooggrraammss

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


99..  HHoowwttoo EEnndd AA BBrraanncchh

"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:

     % aaeeddee --pp eexxaammppllee 11 --cc 4422
     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.

     % aaeemm --ggpp _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.

     % aaeell ccff
     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

     % mmvv _f_u_b_a_r,,BB _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


1100..  HHooww ttoo BBeeccoommee aann AAeeggiiss DDeevveellooppeerr

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>

1100..11..  RReeqquuiirreedd SSooffttwwaarree

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 nnoott 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


1100..22..  CCrreeaattee TThhee AAeeggiiss PPrroojjeecctt

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:

     % aaeennpprr aaeeggiiss..44..2244..22
     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.

     % aaeennpprr aaeeggiiss --vveerrssiioonn --
     aegis: project "aegis": created
     % aaeeppaa --ee --pp aaeeggiiss
     _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
     % aaeennaa --pp aaeeggiiss _y_o_u
     aegis: user "_y_o_u" is now a administrator
     % aaeenndd --pp aaeeggiiss _y_o_u
     aegis: user "_y_o_u" is now a developer
     % aaeennrrvv --pp aaeeggiiss _y_o_u
     aegis: user "_y_o_u" is now a reviewer
     % aaeennii --pp aaeeggiiss _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.

1100..33..  TThhee DDoowwnnllooaadd

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

     % aaeeddiisstt ----rreecceeiivvee \\
         --ff aaeeggiiss--44..2244..22..aaee \\
         --pp aaeeggiiss..44..2244..22
     _._._._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...

     % aaee__pp aaeeggiiss..44..2244..22
     % aaeeccdd
     % aaeebb
     _._._._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).

     % aaeedd
     _._._._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 ddiiffff
  --cc 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.

     % aaeett
     _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
     %


The change is now ready to end development.

     % aaeeddee
     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.

     % aaeerrppaassss --pp aaeeggiiss..44..2244..22 --cc 1100
     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.

     % aaeeiibb --pp aaeeggiiss..44..2244..22 --cc 1100
     % aaeebb
     _._._._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:

     $ ccdd _b_l_a_h_b_l_a_h//ddeellttaa**
     $$ ssuuddoo eettcc//sseett--uuiidd--rroooott _a_r_c_h aaeeggiiss aaeeiimmppoorrtt aaeelloocckk
     $$

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

     % aaeedd
     _._._._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_._._.
     % aaeett &&&& aaeett --bbll
     _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
     % ccdd
     % aaeeiippaassss
     _._._._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.

1100..44..  SSuuppppoorrttiinngg SSeevveerraall AArrcchhiitteeccttuurreess

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.

     % aaeennff aaeeggiiss..ccoonnff..dd//aarrcchhiitteeccttuurree
     % aaeeffaa aaeeggiiss..ccoonnff..dd//aarrcchhiitteeccttuurree eennttiirree--ssoouurrccee--hhiiddee
     % aaeeffaa aaeeggiiss..ccoonnff..dd//aarrcchhiitteeccttuurree llooccaall--ssoouurrccee--hhiiddee
     %


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.  NNoottee 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.

1100..55..  TThhee BBlleeeeddiinngg EEddggee

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:

     $ aaeeccdd --bbll
     # ssuu
     Password:
     # lliinnuuxx--ii448866//bbiinn//aaee--ssyymmlliinnkkss aaeeggiiss..44..2244..22
     # eexxiitt
     $

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.

1100..66..  UUnnddiissccoovveerreedd CCoouunnttrryy

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


1100..77..  SSeennddiinngg CChhaannggeess

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.

1100..88..  GGuuiiddeelliinneess


1100..88..11..  WWhhaatt YYoouu CCaann DDoo

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

1100..88..22..  WWhhaatt YYoouu CCaann''tt DDoo

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.

1100..99..  CCooddiinngg SSttyyllee

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.

1100..1100..  WWrriittiinngg TTeessttss

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:

     % aaeenntt
     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:

       $ sshh tteesstt//aaccttiivviittyy..sshh
       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.

1100..1111..  DDeebbuuggggiinngg

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.

1100..1122..  TThhee TToo--DDoo LLiisstt

+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

1100..1122..11..  aaeeccvvsssseerrvveerr

+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

1100..1122..22..  GGeeooggrraapphhiiccaallllyy DDiissttrriibbuutteedd DDeevveellooppmmeenntt

+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

1100..1122..33..  DDooccuummeennttaattiioonn

+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

1100..1122..44..  MMoorree RReeppoorrttss

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

1100..1122..55..  CCoorree EEnnhhaanncceemmeennttss

+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

1100..1122..55..11..  MMoorree OO((11)) SSccaallaabbiilliittyy

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

1100..1122..66..  GGUUII

+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

1100..1122..77..  RReelleeaassee aanndd BBuuiilldd aanndd IInnssttaallll

+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

1100..1122..88..  DDaattaabbaassee

+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



                      TTaabbllee ooff CCoonntteennttss


  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


