





.













                           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.16
and was prepared 9 September 2005.






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 Peter Miller; All
rights reserved.

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 2 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, write to the Free
Software Foundation,  Inc.,  59  Temple  Place,  Suite  330,
Boston, MA 02111, USA.





















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

+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
current  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 _c_o_n_f_i_g file,
  and  the  build  config   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 config, try the _a_e_b command; it will proba-
  bly 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).

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

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

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






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





Aegis                                                  Howto


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.

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





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





Howto                                                  Aegis


+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
  administrator.   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'' fol-
  lowed 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 make like to install the Aegis
web  interface.  You do this by copying the _a_e_g_i_s_._c_g_i script
from  _/_u_s_r_/_b_i_n_/_a_e_g_i_s_._c_g_i  into  your  web  server's  _c_g_i_-_b_i_n
directory.   There  is  a  _a_e_g_i_s_._c_g_i_._i 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_i_s_._c_g_i_._i _-_s option.)

If  you  have a Web server, and the aegis.cgi was installed,
you can set its _A_E_G_I_S___P_A_T_H environment variable, if you want
it  to  be  able  to  see more projects than just the global
projects.   You  do  this  by  creating  a  _/_u_s_r_/_l_i_b_/_a_e_g_i_s_/_-
_a_e_g_i_s_._c_g_i_._c_o_n_f  file  (there isn't one, by default) and set-
ting the _A_E_G_I_S___P_A_T_H environment variable in it.  This  is  a
fragment of Bourne shell script, not just the name.

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



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





Aegis                                                  Howto


3. The  owner  of the project is taken from the owner of the
   project directory tree, so  this  is  what  needs  to  be
   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 /var/lib/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 /var/lib/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_/_l_i_b_/_a_e_g_i_s    is    NFS    mounted,   try   making   the
_/_u_s_r_/_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/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 config 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 config 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.11 or later.

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

+o GNU Autoconf 2.53 or later.

+o GNU Automake.

+o You will need to install FHist, for the history tool.

+o You will need to install _t_a_r_d_y, for manipulating tarballs.

+o You will need to install _p_t_x(1), for the permuted indexes
  in the documentation.  This is now part of GNU coreutils.

+o You need psutils (e.g.
  http://www.dcs.ed.ac.uk/home/ajcd/psutils/) for the psse-
  lect utility, to manipulate the documentation files,
  mostly to put the tables of contents at the start, rather
  than at the end as GNU Groff generates them.

+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 probably don't.

+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 probably don't).

+o You need to install Bison, the GNU Yacc replacement.

+o You will need to install Flex, the GNU replacement for
  Lex.



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





Aegis                                                  Howto


+o You need to GNU Gettext (0.11.4 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... well... stuffed.)

+o You need GNU Ghostscript, for the ps2pdf utility, so that
  you can create PDF documents.

+o You need _u_u_d_e_c_o_d_e with a -o option (to redirect the out-
  put).  It is part of GNU Sharutils.

+o You need to install GNU awk.

+o You need a _c_t_a_g_s(1) command with a -L option (to read file
  names from standard input).

+o You need RCS installed for the automated tests.

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

+o You need netpbm installed, for turning _a_e_g_i_s_._p_n_g into
  _a_e_g_i_s_._x_p_m because _r_p_m(8) will only accept GIF or XPM
  icons.

+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.  You can get it from
  http://www.winterdrache.de/freeware/png2ico/

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

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.16 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..1166
     aegis: project "aegis": created
     aegis: project "aegis.4.16": created
     %

but experienced Aegis users will know that this means a
laborious setting of project attributes.  It is easier to



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





Howto                                                  Aegis


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
     % aaeennbbrr --pp aaeeggiiss 44
     aegis: project "aegis.4": created
     % aaeennbbrr --pp aaeeggiiss..44 1166
     aegis: project "aegis.4.16": 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.

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






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





Aegis                                                  Howto


     % 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..1166..aaee \\
         --pp aaeeggiiss..44..1166
     _._._._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 _c_o_n_f_i_g 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_.

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..1166
     % 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 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 ``config''
    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



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





Howto                                                  Aegis


  configure it differently).  You need to leave just about
  everything alone, except for the architecture specifica-
  tion.  Change it from

       architecture =
       [
           "unspecified",
       ];

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

       architecture =
       [
           "linux-i486",
       ];

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



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





Aegis                                                  Howto


  --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.16": 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.
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..1166 --cc 1100
     aegis: project "aegis.4.16": 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..1166 --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_._._.
     Integrator: please use the following command:
       su1 -c "chown root _a_r_c_h/bin/aegis &&
       chmod u+s _a_r_c_h/bin/aegis"
     %


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, that comes later.

If you don't have my _s_u_1(1) command, just use _s_u(1) instead,
or _s_u_d_o or something.




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





Howto                                                  Aegis


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

+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
directory so that they can be cleaned up (deleted) when the
change completes.

1100..44..  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.)

I use the following shell script...

     #!/bin/sh
     project=aegis.4.16
     arch=linux-i486 # _s_e_t _t_o _m_a_t_c_h _y_o_u_r _s_y_s_t_e_m
     prefix=/usr/local # _s_e_t _t_o _m_a_t_c_h _y_o_u_r _s_y_s_t_e_m
     bin=$prefix/bin
     dir=`$bin/aegis -cd -bl -p $project`
     test $? -eq 0 || exit 1
     bin=$dir/$arch/bin






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





Aegis                                                  Howto


     echo bin...
     cd $prefix/bin
     for f in aeannotate aecomplete aedist \
         aefind aegis aeimport aels \
         aepatch aerect aereport aesub \
         aetar tkaegis tkaeca tkaenc \
         tkaepa aegis.cgi aegis.cgi.i
     do
         rm $f
         ln -s $dir/$arch/bin/$f $f
     done


     echo lib...
     cd $prefix/lib/aegis
     for f in en
     do
         rm -rf $f
         ln -s $dir/$arch/lib/$f $f
     done
     for f in profile cshrc
     do
         rm $f
         ln -s $dir/$arch/lib/$f $f
     done


     echo share...
     cd $prefix/share/aegis
     for f in en/html report \
         config.example wish
     do
         rm -rf $f
         mkdir $f
         ln -s `$bin/aefind -p $project -bl -baserel lib/$f
         -type f ! -name "*,*" ! -name "*.d" -print
         -resolve` $f/.
     done
     for f in report.index aegis.icon \
         aegis.mask
     do
         rm $f
         ln -s `$bin/aefind -p $project -bl -baserel lib/$f
         -type f ! -name "*,*" ! -name "*.d" -print
         -resolve` $f
     done


1100..55..  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.





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





Howto                                                  Aegis


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.

1100..66..  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.

Use a simple command such as

     aedist --send -p aegis.4.16 -bl | \
     pgp | \
     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..77..  GGuuiiddeelliinneess


1100..77..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.)






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





Aegis                                                  Howto


1100..77..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
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..88..  CCooddiinngg SSttyyllee

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

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

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

1100..99..11..  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 43





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 44         (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..99..22..  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 aegis.cgi 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 aegis.cgi do this, too.  Submitted: Ralf
  Fassel <ralf@akutech.de>, 9 Dec 1999

+o Add a outstanding_changes report (just like ``ael out-
  standing_changes'') which takes a user name, so you can
  get a list of outstanding changes by user.  Make aegis.cgi
  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 45





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'' dia-
  grams of file branching.

+o Some kind of web report which makes ``train track'' dia-
  grams 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 (option-
  ally) 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..99..33..  CCoorree EEnnhhaanncceemmeennttss

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





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





Aegis                                                  Howto


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

+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 [IF there were editable file attributes] add coupling
  between files (as file attribute) this means when you
  aecp, you get a set of files (see a command to set it,
  need to carry it thru integration, etc.)  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



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





Howto                                                  Aegis


  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

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




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





Aegis                                                  Howto


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

+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 cre-
  ated. 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: Chris-
  tian F. Goetze <c-goetze@u-aizu.ac.jp>




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





Howto                                                  Aegis


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

+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..99..33..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..99..44..  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:



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





Aegis                                                  Howto


  jerry.pendergraft@endocardial.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..99..55..  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

+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..99..66..  DDaattaabbaassee

+o Should the Aegis database be replaced by XML?  (This would
  have _h_u_g_e backwards compatibility issues.)  Maybe we need
  a way to project the Aegis database into XML?  Submitted:
  Mark Veltzer <mark2776@yahoo.com>, 16 Aug 2001

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

+o Write an interface so that Aegis looks just like a remote
  CVS server, accessed using the normal CVS clients.  Of



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





Howto                                                  Aegis


  course, you would have to do the aede on the Unix server.
  Submitted: P. Miller, 16 Aug 2001























































Page 52            (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.4.1. Creating Projects  . . . . . . . . . . . . . . . . .  16
5.4.2. Web Visibility . . . . . . . . . . . . . . . . . . .  16
5.5. Changing The Project Owner . . . . . . . . . . . . . .  16
6. How to Move a Project  . . . . . . . . . . . . . . . . .  18
6.1. Relocating a Project . . . . . . . . . . . . . . . . .  18
6.1.1. From within Aegis  . . . . . . . . . . . . . . . . .  18
6.1.2. From outside Aegis . . . . . . . . . . . . . . . . .  18
6.2. Renaming a Project . . . . . . . . . . . . . . . . . .  19
6.2.1. From within Aegis  . . . . . . . . . . . . . . . . .  19
6.2.2. From outside Aegis . . . . . . . . . . . . . . . . .  19
6.2.3. Project Aliases  . . . . . . . . . . . . . . . . . .  19
7. Working in Teams . . . . . . . . . . . . . . . . . . . .  20
7.1. Local  . . . . . . . . . . . . . . . . . . . . . . . .  20
7.1.1. Single User, Single Machine  . . . . . . . . . . . .  20
7.1.2. Multi User, Single Machine . . . . . . . . . . . . .  20
7.1.3. Multi User, Multi Machine  . . . . . . . . . . . . .  20
7.1.3.1. General Requirements . . . . . . . . . . . . . . .  21
7.1.3.2. Aegis-specific Requirements  . . . . . . . . . . .  22
7.1.4. Known Problems . . . . . . . . . . . . . . . . . . .  22
7.2. Distributed  . . . . . . . . . . . . . . . . . . . . .  23
7.2.1. Multiple Single-User Sites . . . . . . . . . . . . .  23
7.2.2. Multiple Multi-User Sites  . . . . . . . . . . . . .  24
7.2.3. Telecommuting  . . . . . . . . . . . . . . . . . . .  24
7.2.3.1. Office to Developer  . . . . . . . . . . . . . . .  24
7.2.3.2. Developer to Office  . . . . . . . . . . . . . . .  24
8. How to use Aegis with Python . . . . . . . . . . . . . .  26
8.1. Handling Aegis search paths  . . . . . . . . . . . . .  26



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





Howto                                                  Aegis


8.1.1. The Aegis model vs. the Python model . . . . . . . .  26
8.1.2. The solution . . . . . . . . . . . . . . . . . . . .  26
8.1.3. Why setting PYTHONPATH to the Aegis search path
  will not work  . . . . . . . . . . . . . . . . . . . .  27
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  . . . . . . . . . . . . . .  35
10.3. The Download  . . . . . . . . . . . . . . . . . . . .  36
10.4. The Bleeding Edge . . . . . . . . . . . . . . . . . .  40
10.5. Undiscovered Country  . . . . . . . . . . . . . . . .  41
10.6. Sending Changes . . . . . . . . . . . . . . . . . . .  42
10.7. Guidelines  . . . . . . . . . . . . . . . . . . . . .  42
10.7.1. What You Can Do . . . . . . . . . . . . . . . . . .  42
10.7.2. What You Can't Do . . . . . . . . . . . . . . . . .  43
10.8. Coding Style  . . . . . . . . . . . . . . . . . . . .  43
10.9. The To-Do List  . . . . . . . . . . . . . . . . . . .  43
10.9.1. Documentation . . . . . . . . . . . . . . . . . . .  43
10.9.2. More Reports  . . . . . . . . . . . . . . . . . . .  45
10.9.3. Core Enhancements . . . . . . . . . . . . . . . . .  46
10.9.3.1. More O(1) Scalability . . . . . . . . . . . . . .  50
10.9.4. GUI . . . . . . . . . . . . . . . . . . . . . . . .  50
10.9.5. Release and Build and Install . . . . . . . . . . .  51
10.9.6. Database  . . . . . . . . . . . . . . . . . . . . .  51






























Page 1002                    ()                 Peter Miller


