cde/programs/dtksh/ksh93/ship/README

   1 /* $XConsortium: README /main/2 1996/07/15 14:13:29 drk $ */
   2 Software shipment information.  [better documentation forthcoming ...]
   3
   4 All files and directories, except for those in /usr/spool/uucppublic,
   5 are rooted at the shipment/installation directory named by
   6 $INSTALLROOT.  The $INSTALLROOT hierarchy is similar to the System V
   7 /usr hierarchy.
   8
   9 The $INSTALLROOT/ship subdirectory is automatically maintained by
  10 shipin and shipout.  If you expect to receive future shipments then
  11 do not change files in this directory.
  12
  13 pax is the Bell Labs implementation of the proposed POSIX (01/90)
  14 portable archive interchange command.  The default output format is
  15 `cpio -c'.  The pax delta format is a Bell Labs extension.
  16
  17 The following assumes:
  18
  19         INSTALLROOT=<path name of software installation root directory>
  20
  21 After each shipment:
  22
  23         <follow specific shipment instructions>
  24         cd $INSTALLROOT
  25         ship/shipin
  26
  27 `ship/shipin -n' shows actions but does not unbundle or build.
  28 `ship/shipin -s <dir>' unbundles from <dir> rather than /usr/spool/uucppublic.
  29 `ship/shipin -u' unbundles the shipment but does not build.
  30 `ship/shipin -i' copies from spool area but does not unbundle or build.
  31 `ship/shipin -E' rebuild components that failed last time (use after fixes).
  32
  33 Any non-option arguments to shipin are passed as arguments to the
  34 generating make or shell script for each component.
  35
  36 To pass the shipment to another machine (requires ksh):
  37
  38         # rcp                   # TO=host:ship
  39         # uucp                  # TO=machine!user
  40         # list of files         # TO=%list
  41         # remote dk pull script # TO=%pull
  42         cd $INSTALLROOT
  43         ship/shipin -i  # if not installed on this machine
  44         cd ship
  45         shipout $TO
  46
  47 {rcp,uucp} initiate copies whereas {list,pull} generate information on
  48 stdout.  {uucp} copies to an intermediate spool area on the other machine
  49 whereas {rcp,list,pull} are relative to $INSTALLROOT on the other machine.
  50
  51 To copy a command <cmd> from $INSTALLROOT to a new root you must copy:
  52
  53         $INSTALLROOT/bin/<cmd>
  54         $INSTALLROOT/lib/<cmd>
  55
  56 to the new root directory for all interdependent <cmd>'s.  Depending on
  57 <cmd>, only one of the above files/directories may exist.
  58
  59 Be sure to maintain a different $INSTALLROOT for each machine architecture.
  60 If the same $INSTALLROOT/ship must be reused for a different architecture
  61 then delete everything except ship from $INSTALLROOT and run ship/shipin -F.
  62 An alternative would be to use nmake and optionally 3d to viewpath a new
  63 architecture hierarchy on top of $INSTALLROOT.  In this case nmake would
  64 be run from within the $INSTALLROOT/src/(cmd|lib) hierarchy.
  65
  66 The files below may appear on the shipment side, the installation side,
  67 or both.  <installer-login> and <shipper-system> are defined in the
  68 shipment mail announcement.
  69
  70 Each shipment is identified by a two part version number [R]YYMMDD
  71
  72         R       release -- if specified then it must match for compatibility
  73         YYMMDD  shipment year, month and day number
  74
  75 /usr/spool/uucppublic/<installer-login>/<shipper-system> directory hierarchy:
  76
  77         <shipper-login>.<YYMMDD>        shipment control directory
  78         <shipper-login>.<YYMMDD>/manifest list of all files in shipment
  79
  80 $INSTALLROOT directory hierarchy:
  81
  82         bin/            executable binaries and scripts
  83         include/        common header files
  84         lib/            object archives a common data
  85         man/            man page subtree
  86             man1/       command man pages
  87             man3/       library man pages
  88             man8/       adminstration and maintenance man pages
  89         src/            source subtree
  90             cmd/        command source
  91             lib/        library source
  92         ship/           shipment and installation info
  93
  94 $INSTALLROOT/ship contents:
  95
  96         README          installation info
  97         !<mach_user>    shipment installation message for machine!user
  98         ship.body       optional shipment announcement main body
  99         ship.head       optional shipment announcement header
 100         ship.tail       optional shipment announcement trailer
 101         shipcost        show relative cost of delta/update shipment
 102         shipcrate       crate all components for shipout
 103         shipin          unbundle, build and install shipment
 104         shiplist        shipout using name-tool list
 105         shipop          shipin/shipout support executable
 106         shipout         split and send shipment
 107         shipslog        shipment log and recipient address info
 108         shipswab        clean old stuff from the ship area
 109         shipyard        shipment support tools component name
 110         lib*            library components
 111         *               command components
 112
 113 $INSTALLROOT/ship/<component> contents:
 114
 115         <[R]YYMMDD>     information for the <[R]YYMMDD> shipment
 116         base            link to the newest pax base archive
 117         delta           link to the newest pax delta archive
 118         in.log          shipin log
 119         items           required components (excluding this one)
 120         list            optional list of persons to send to
 121         message         optional message to include in shipment announcement
 122         owner           mail address for installation report
 123         release         the the current shipment release number
 124         report          optional list of $INSTALLROOT relative files to report
 125
 126 $INSTALLROOT/ship/<component>/<[R]YYMMDD> contents:
 127
 128         <[R]YYMMDD>     pax delta archive for ../[R]YYMMDD/base
 129         <[R]YYMMDD>.<NNN> delta archive split for uucp
 130         BUILT           present if release build succeeded
 131         ERROR           present if release build failed
 132         GENERATED       present if base archive was generated from a delta
 133         UNCRATED        present if release uncrate succeeded
 134         base            pax base archive
 135         base.<NNN>      base archive split for uucp
 136         items           items for this release
 137         message         message for this release
 138         owner           owner for this release
 139         report          report for this release
 140
 141 Each component $NAME is extracted into either $INSTALLROOT/src/lib/$NAME
 142 or $INSTALLROOT/src/cmd/$NAME.  The following are attempted, in order,
 143 to build and install $NAME under $INSTALLROOT:
 144
 145         $INSTALLROOT/bin/nmake -f Makefile install
 146         mamexec install < Mamfile # mamexec is built into ship/shipin
 147         make -f makefile install
 148         sh Makescript
 149
 150 where Mamfile, Makescript and makefile are usually generated from the
 151 corresponding nmake Makefile.
 152
 153         Glenn Fowler    ulysses!gsf
 154         David Korn      ulysses!dgk