Google
 

Trailing-Edge - PDP-10 Archives - bb-bt99e-bb - soupr.doc
There are 11 other files named soupr.doc in the archive. Click here to see a list.


SOUPR Functional Description

     SOUPR (SOftware Update Package Revisited) is a  package
     which   was  written  to  ease  the  task  of  software
     maintenance.   The   design   of   SOUPR   allows   the
     distribution   of  small  correction  files  to  update
     field-image software  sources.   Also  present  is  the
     ability  to automatically merge user modifications with
     DEC-supplied updates/fixes.  SOUPR correction files may
     be edited directly and the output of SOUPR is ready for
     immediate assembly/compilation.

     SOUPR is  a  collection  of  three  programs:   COMPAR,
     UPDATE,   and   MERGE.    The   following  is  a  brief
     description of each program.

1.  COMPAR

     The input to COMPAR consists of two ASCII  files  known
     as  the  base  file  and  the  user  file.  COMPAR will
     compare the two files and  create  a  correction  file.
     The  correction  file details how the user file differs
     from the base file.  The command format is:

     *cor-file=base-file,user-file/switches

2.  UPDATE

     UPDATE will reconstruct the user file.   The  input  to
     UPDATE  consists  of a base file and a correction file.
     The command format is:

     *user-file=base-file,cor-file/switches

3.  MERGE

     MERGE will merge several correction files into a single
     correction  file  and  flag any conflicts.  The command
     format is:

     *cor-file=cor-file/switches,cor-file/switches...
                                                      Page 2


SOUPR Source File Format


     SOUPR may be used with any ASCII file.  The file is not
     parsed in any way.  Binary files (such as REL files and
     SAVE files) may not be used.  Any text  editor  may  be
     used to alter the input file for COMPAR.

     Each line in the source file is  identified  internally
     by the notation "n/m".  Where n is the line number, and
     m is the page number.

     A line is an arbitrary  sequence  of  ASCII  characters
     terminated  by  a break character.  The break character
     itself is considered to be part of the  line.   In  the
     case of consecutive break characters, each character is
     considered to be a separate line.   The  following  are
     defined to be break characters:

          12   LF   Line Feed
          13   VT   Vertical Tab
          14   FF   Form Feed
          32   ^Z   control Z
          33   ESC  ESCape


     A page is an arbitrary sequence of lines terminated  by
     a  form feed.  The form feed itself is considered to be
     the last character of the last  line  of  the  previous
     page.    Since  form  feeds  are  usually  preceded  by
     <CR><LF>, the form feed is usually the  only  character
     in its line.

     SOUPR will ignore the line sequence  numbers  generated
     by SOS.
                                                      Page 3


SOUPR Correction File Format

     Each line in the  correction  file  is  prefixed  by  a
     special  character.  This character determines which of
     three categories the line falls into:

1.   Commands  to  SOUPR  (see  below).   All  commands  are
     prefixed by a space (ASCII 40).

2.   Text to be acted upon by the commands.   Each  line  of
     text  is  prefixed by a tab (ASCII 11).  Except for its
     use as a delimiter, the tab is ignored.

3.   In the event that a line fails to be prefixed by either
     a  space  or  a tab, the line is regarded as text.  The
     first character, whatever it may be, is  considered  to
     be part of the text.
                                                      Page 4


SOUPR Commands

1.    DELETE n/m ;comment
             text

     Delete text starting at line n of page m.  The text  to
     be   deleted   follows  immediately  after  the  DELETE
     command, and continues until a space is encountered  in
     column  one  (i.e.   another  command).  If the text at
     line n of page m in the base file is different from the
     text  in  the  correction  file,  UPDATE  will flag the
     condition as an error.

2.    INSERT n/m ;comment
             text

     Insert text just before line n of page m.  The text  to
     be   inserted  follows  immediately  after  the  INSERT
     command, and continues until a space is encountered  in
     column one.

3.    REPLACE n/m ;comment
             text1
      WITH
             text2

     At line n of page m replace text1  with  text2.   Text1
     follows  immediately  after  the  REPLACE  command, and
     continues until a space is encountered in  column  one.
     This  line  will  be the WITH auxiliary command.  Text2
     follows  immediately  after  the  WITH   command,   and
     continues  until  a space is encountered in column one.
     If the text at line n of page m in  the  base  file  is
     different  from  text1  in  the correction file, UPDATE
     will flag the condition as an error.

4.    SUM n ;comment

     Where n is a rotate add one checksum of the base  file.
     While  processing  the base file, UPDATE will recompute
     this checksum.  If the value does not match that stored
     in  the correction file, UPDATE will flag the condition
     as  an  error.   Hence  a  user   is   prevented   from
     accidentally   using   the   correction  file  with  an
     incorrect version of the base file.  MERGE will type an
     error  message  if  a user attempts to merge correction
     files with different checksums.  The SUM command  marks
     end of file.

5.    ;comment

     Ignored.
                                                      Page 5


                              NOTE

         All keywords (e.g.   DELETE,  INSERT,  REPLACE,
         WITH,  and  SUM)  may  be  abbreviated  to  the
         smallest  unambiguous   form   (currently   one
         letter).



     MERGE goes to a great deal of trouble to make conflicts
     easy  to  resolve.   The  begining  and  ending of each
     conflict is clearly labeled and numbered.  For example,
     a section of the correction file might appear as:

      ;***BEGINING OF CONFLICT 3***
      DEL 66/5
                 JRST    FOO
      REP 66/5
                 JRST    FOO
      WIT
         ;FALL TO ROUTINE FOO
      ;***END OF CONFLICT 3***


     The  programmer  can  quickly  see  that  both  patches
     attempted.  to do the same thing, they merely did it in
     different ways.  The object was to remove the  JRST  at
     line   66  of  page  5.   The  first  patch  tried  the
     straightforward approach, it merely deleted  the  line.
     The  second  patch attempted to replace the line with a
     comment.  But MERGE doesn't realize  that  the  patches
     are equivalent.  MERGE will type a warning message that
     conflicts exist.  The  programmer  must  type  out  the
     correction file and study the conflicts.  In this case,
     he merely decides which patch  he  wishes  to  use  and
     removes  the  other.   This  sort of "conflict", by the
     way, is quite common.  It's nice to know that even when
     conflicts do occur, they are usually easy to resolve.
                                                      Page 6


SOUPR Switches


     One of the most  powerful  features  of  SOUPR  is  the
     conditionals  facility.   To  use  this  facility  each
     command in the correction file is labeled with a sixbit
     name.   The  correction  file  is  then  regarded  as a
     library of patches.  Each patch is refered to by  name.
     The user may specify which patches from the library are
     to be used.

     Labels are placed at the end of a  statement,  and  are
     preceded by a semicolon.  E.G.:

      INS 3/4 ;XYZBUG SPR#3141

     Those of you who are familiar with MACRO will recognize
     the  label  as  a  cross between a comment and a TITLE.
     The label resembles a comment in that  it  may  contain
     any  information  that the user feels would be helpful.
     The label resembles a TITLE in that the first  word  is
     taken  as  the name of the module.  Thus in the example
     above,  the  name  of  the  patch  is  "XYZBUG".    The
     following  is  a  list  of  data that one might wish to
     include in a comment:

     1.  Patch name
     2.  SPR number
     3.  MCO/PCO number
     4.  Edit number
     5.  Brief description

     Labels are added to patches by using the  /NAME  switch
     in COMPAR.  The switch has two forms:

     /NAME:"string"
     /NAME:foo

     The former is used to specify an  entire  string.   The
     later is used to specify just a sixbit name.

     The following is a list  of  switches  used  to  select
     which  patches  from  the library are to be used.  Both
     UPDATE and MERGE have each of the switches:

     /NCLUDE:x           Processing  includes   only   those
                         patches  labeled with x.  Wildcards
                         are legal.  The default is *  (i.e.
                         include all patches).

     /NCLUDE:(x,y,...)   Specifies a list of patches  to  be
                         included

     /UNCLUD             Unlabeled   patches   are    always
                         included (default)
                                                      Page 7


     /UXCLUD             Unlabeled   patches   are    always
                         excluded

     /XCLUDE:x           Processing excludes  those  patches
                         labeled with x

     /XCLUDE:(x,y,...)   Specifies a list of patches  to  be
                         excluded


     Another feature allows the COMPAR program to  associate
     an   internally   created   label   with  every  change
     encountered during a single compare function.  This  is
     not  the  same  as  each  patch  being identifiable.  A
     single patch  may  create  multiple  code  changes  and
     multiple  concurrent  patches would result in logically
     one code change.

     This feature is called by adding a /NUM or /LET  switch
     to a COMPAR command which has a /NAME:  switch.
                                                      Page 8


SOUPR Examples

1.   To create a labeled patch:

     .R COMPAR
     *cor-file=base-file,user-file/NAME:foo

2.   To apply a single patch:

     .R UPDATE
     *user-file=base-file,cor-file/NCLUDE:foo

3.   To apply all but a single patch:

     .R UPDATE
     *user-file=base-file,cor-file/XCLUDE:foo

4.   To add a new patch to the library:

     .R MERGE
     *new-library=old-library,new-patch

5.   To remove a patch from the library:

     .R MERGE
     *new-library=old-library/XCLUDE:foo

6.   To extract a patch from the library:

     .R MERGE
     *cor-file=library/NCLUDE:foo
                                                      Page 9


SOUPR - Applying Local Source Edits


     SOUPR, as described above, has  the  ability  to  merge
     edits.   The  UPDATE module requires a known base file.
     DEC  provides  updates  which  can  be  used  by  SOUPR
     directly only on the last DEC release.  The SOUPR tool,
     however, can be used to  merge  local  edits  prior  to
     using UPDATE.

     The process of  applying  local  edits  calls  for  the
     availability of the completely updated source module as
     last released and updated by DEC.   When  an  Autopatch
     tape  is  received  and  you want to apply the supplied
     corrections to your locally edited source file you  can
     use the following procedure:

     1.   Obtain the last DEC release of the source module.

     2.   Create a correction file  by  using  COMPAR.   The
          above  module is the base-file and the module with
          local edits is the user-file.

     3.   Use MERGE to combine this correction file with the
          one  supplied by DEC.  The MERGE program will flag
          any conflicts.  These must be resolved by  editing
          the  correction  file  before going on to the next
          step.

     4.   Use UPDATE to apply this combined correction  file
          to the base-file.