    INSTALLING THE SOFTWARE

    This section describes how to unpack and compile the software for a
    Unix machine.  Note that getting the software to work in a non-Unix
    environment may be difficult or impossible.

    Unpacking the files.

    The software is distributed as a Unix tar archive.  To obtain the
    files, download the tar archive for the desired version by anonymous
    ftp or via your Web browser to a file of the form 'fbm.YYYY-MM-DD.tar',
    and then issue the Unix command

        tar xf fbm.YYYY-MM-DD.tar

    If you got the archive in compressed form, as 'fbm.YYYY-MM-DD.tar.Z',
    you must use the command "uncompress fbm.YYYY-MM-DD.tar.Z" before
    doing the above.  The following instructions cover what to do next for
    the current version; you should read the old documentation if for some
    reason you are installing an older version.

    The tar command should create a directory called 'fbm.YYYY-MM-DD',
    where YYYY-MM-DD is the release data.  It should place numerous files
    and sub-directories in this directory.  If this seems to have worked,
    you can remove the file 'fbm.YYYY-MM-DD.tar'.  You should now change
    into the 'fbm.YYYY-MM-DD' directory, as the following instructions
    assumed that you are there.

    If you prefer that this directory be called something other than
    'fbm.YYYY-MM-DD', change the name now, BEFORE compiling the programs,
    since the programs look for a file of random numbers in the directory
    under the name it had when they were compiled.

    Looking at the documentation.

    The directory 'doc' contains links to all the documentation files.
    The file 'manual' contains all the introductory documentation
    (including this) as a simple text file; the same information is also
    contained in several .doc files.  Other .doc files contain more
    detailed information.  Files of the form 'Release.YYYY-MM-DD.doc'
    contain information on current and past releases.  These may be of
    interest if you are upgrading from an older version of the software.

    If you have a Web browser, you can access all these documentation
    files via 'index.html' in the 'doc' directory, as described in
    Guide.doc.

    Compiling the programs.

    You will probably be able to compile the programs as described below
    without making having to change anything.  However, it is possible
    that you will want to use a different C compiler, or set certain
    compilation options.  You can probably set the required options by
    modifying the 'make.include' file in the main directory, which is
    included at the beginning of all Makefiles, though for some problems
    you might have to modify the 'Makefile' and 'xxx.make' files in the
    various sub-directories, or modify the source files.

    Here are some reasons that you might need to customize things:

      1) The programs are written in ANSI standard C.  If you compiler
         defaults to some other idea of what C is, you should try to
         persuade it otherwise.  On DEC Alpha machines, the "-std" flag
         does this.  It can be put in CFLAGS in 'make.include'.

      2) The programs were written with IEEE floating-point in mind, and
         therefore may occasionally perform operations that result in
         overflow or underflow.  If this causes program termination on
         your machine (eg, with a "floating point exception"), you will
         need to figure out how to disable these errors.  On DEC Alpha
         machines, for example, the problem can be fixed using a "-ieee"
         compiler option, which can be put in CFLAGS in 'make.include'.

      3) The 'util' directory contains a file of 100,000 natural random
         bytes, which are used in combination with pseudo-random numbers
         This file is accessed by many of the programs, using a path
         name that by default points into this 'util' directory.  If you
         plan on moving this file elsewhere, you will need to change the
         compilation command for rand.c at the end of 'util/util.make'.

      4) If you are rather short of memory, you might want to reduce the
         size of the Max_optional_memory constant defined in gp/gp-mc.c.
         This will save memory at the cost of some time.

    Once you have made any required changes, you can compile the programs
    by going to the main directory where you installed the software and
    issuing the command

        make-all

    This will compile programs in the various sub-directories.  Note that
    some modules will be compiled over again in each directory where they
    are used; this is intentional.

    It is possible that these compilation commands will fail for some
    reason, in which case you'll have to figure out what's wrong and fix
    it.  Note that the 'make-all' command just moves into each of the
    directories and does a 'make' there.  You can do this manually for
    each directory to see where the problem is.  For these makes to work
    correctly, the programs MUST be kept in separate 'util', 'mc', 'dist',
    'bvg', 'net', 'gp', and 'mix' sub-directories, with these names.

    Using the programs.

    Once you have successfully compiled the programs, you should put the
    'bin' directory (within the main directory for this software) in your
    search path.  How this is done depends on the shell program you are
    using; consult a local expert if you don't know how.  This directory
    contains symbolic links to all the programs making up this software.
    Subsequent instructions assume that you have this 'bin' directory in
    your search path.

    The above is the simple version of how to use the programs.  However,
    if you want to use the programs on more than one type of machine, you
    will need to compile them several times, once for each machine
    architecture, and you will need to set your search path to a directory
    that contains the versions of the programs compiled for the machine
    you are currently using.  By convention, these directories should be
    called "bin.ARCH", where ARCH is the name of the machine architecture.
    The shell file install-arch creates such a directory (if necessary)
    and copies the programs from the "bin" directory to the "bin.ARCH"
    directory for the current architecture.  It is assumed that a program
    called 'arch' exists that returns the name of the architecture.

    Cleaning things up.

    Once the compilations have finished, you can save some disk space by
    issuing the command

        rm */*.o

    when you are in the main directory.  You can get rid of the compiled
    programs by using the command

        make-clean

    when in the main directory.  Of course, you then won't be able to use
    the programs until you do another make-all to recompile them, unless
    you had copied them to a "bin.ARCH" directory.