INSTALLATION


This document explains how to compile and install the zoo archiver.

Generally, you will not build zoo by directly invoking the supplied
makefile.  Instead, you will execute one of the supplied scripts, or
create a suitable script.  Each supplied script has a name beginning
with the characters "mk" and is executed with the command
"sh scriptname" or "csh scriptname".  All the scripts listed below
worked correctly with version 1.50 of zoo.  All of them except mkx68 and
mkx86 are also known to work correctly for versions 1.71, 2.00, and
2.01.

mksysv    This is for any system running System V Release 2 or something
          reasonably compatible.  It is known to work on the *T&T **IX
          PC (also known as the 3B1 or the *T&T 7300) running software
          revision 3.0.  It should also work on more recent versions of
          Xenix.  On older machine architectures this script may need to
          be revised to add a `-Ml' switch or equivalent to cause the
          large memory model to be used.  For Microport System V/AT and
          Xenix see also descriptions for mkuport, mkx86, and mkx68.

mkbsd     This is for 4.3BSD.  It is known to work on a VAX-11/785 run-
          ning 4.3BSD straight from Berkeley.

mkuport   For Microport System V/AT.  This script includes the -Ml
          switch so that the large memory model is used.

mkx68     This script is for Xenix/68000.  It is known to work with zoo
          version 1.50 on a Radio Shack Model 16 running Xenix version
          3.01.01.  It takes care of problems in the C compiler and in
          the include files related to incorrect handling of the `void'
          data type.  However, since this version of Xenix does not have
          the memset() library function, the line "#define MEMSET" may
          first need to be commented out from the group of symbol defin-
          itions for SYS_V in the file ``options.h''.  You may also need
          to add the switch "-F 6000" (or some other reasonable value
          instead of 6000) to the loader to make it allocate a bigger
          stack.

mkx86     This script is for Xenix for 80286 systems.  It is known to
          work (for zoo version 1.50) on an Intel 310/286 running Xenix
          3.4 and an AT running SCO Xenix 2.2.  It causes the large
          memory model to be used and sufficient stack space to be allo-
          cated at load time.

descrip.mms This is a makefile suitable for use on VAX/VMS systems with
          DEC's version of make, called MMS.  It is believed to work on
          versions 4.5 through 4.7 of VAX/VMS.  The target zoo.exe
          directs the linker to use the file options.opt so that the
          shareable library is used.  The target zoobig.exe is identical
          except that the shareable library is not used, making the exe-
          cutable program about twice as big.

          Special techniques are needed to work around numerous pecu-
          liarities in VAX/VMS.  These are described separately in the
          file ``vmsbugs.doc''.  In particular, the VAX/VMS version of
          zoo must be used in conjunction with the "bilf.exe" utility,
          which performs needed file conversions.  The source program
          bilf.c is included in the current source distribution for zoo.

The file ``options.h'' defines preprocessor symbols for the various sys-
tems.  In most cases, given a reasonably powerful C compiler and
library, you will be able to find a combination of options that will
work.  Documentation for these options is in the file ``options.doc''.

Other machine-dependent code and definitions are in machine.h,
machine.c, and portable.h.  Also, the amount of memory used for various
arrays can be customized by defining symbols that are described and used
in zoomem.h.

The low-level input/output routines are in portable.c.  In most cases
these will not need to be modified.

The zoo source code largely conforms to the requirements of Kernighan
and Ritchie's book.  Some exceptions are as follows.

   - Variables are believed to be unique in their initial 8 characters.
     Systems that distinguish fewer than 8 initial characters are
     currently not supported.

   - Zoo code assumes that members of structures do not have global
     scope.

   - Long preprocessor symbols are occasionally used.

   - The special value -1 is cast to a pointer of type (FILE *) to pro-
     vide a distinguished file pointer that is used to signify output to
     a null file.  This should work on most systems that support the
     system call sbrk.  Any suitable value may be supplied in place of
     -1 in zooio.h.

TROUBLESHOOTING.

As currently configured for **IX variants, zoo uses the access() system
call to check for file existence (see the definition for the symbol
EXISTS in options.h).  There is some question about the appropriatenes
of this, because access() can give the wrong answer when used from a
set-user-id program.  If EXISTS is left undefined, zoo uses its own
function to test for file existence by trying to open the file for read
and also for write.

Two common reasons for crashes when zoo is executed are the following.

   - On machines with older (Intel-style) architectures zoo requires the
     large memory model.  Compiling with the small memory model will
     cause problems.  Also, systems that are limited to 64 kilobytes of
     data and 64 kilobytes of code are not currently supported (but they
     will be in the future).

   - A generous amount of stack space is needed.  Depending on the sys-
     tem, this will vary from about 15 kilobytes to about 33 kilobytes.
     On systems that cannot expand the stack dynamically you will need
     to specify the size of the stack area at load time.

SPECIAL VERSIONS.  A version (currently 2.01) is available for MS-DOS
that provides better performance due to assembly language routines and
also includes some system-dependent features.  Another version
(currently 2.00) has been ported by J. Brian Waters for the Amiga.  It
includes several AmigaDOS-dependent features such as preservation of
file times and wildcard expansion.

EXTRACT-ONLY VERSIONS.  For a new system, your first concern should be
the ability to extract and list zoo archives.  For this purpose try com-
piling booz (which stands for Barebones Ooz) (currently version 1.01),
which can be compiled with three different options requiring different
degrees of compiler sophistication and offering different levels of
features.  Unlike zoo, booz will work on systems with less than 64 kilo-
bytes of total available memory.  However, unlike zoo, booz uses low-
level unbuffered file descriptors in **IX style.  This program is not a
part of the standard zoo distribution, because nobody has ever shown any
interest in it.

Machine-dependencies.

   - Currently the only systems supported are those that can read and
     write in 8-bit units.  The file ``machine.h'' contains a typedef of
     BYTE, and it must be defined to be an 8-bit quantity.

   - It is not known whether zoo code as it stands will work on a 1's-
     complement machine.

   - The code assumes that type `int' is at least 16 bits long and type
     `long' is at least 32 bits long.  There may be some implicit
     assumptions that type `char' is exactly 8 bits;  I am not sure if
     this is so.  However, type `BYTE' must be exactly 8 bits long.

   - In accordance with K&R (p 126), zoo code assumes that sizeof(char)
     equals exactly 1.

                                     -- Rahul Dhesi 1988/08/25