path: root/web/funnelAC/userman/u_ch4.tex

%==============================================================================%
%                              Start of Ch4.tex                                %
%==============================================================================%
%
% Copyright
% ---------
% Copyright (C) 1992 Ross N. Williams.
% This file contains a chapter of the FunnelWeb User's Manual.
% See the main TeX file for this manual for further information.
%
%==============================================================================%

\chapter{FunnelWeb Installation}
\label{chapinstall}\xx{FunnelWeb}{installation}

This chapter describes how to obtain, compile, and install FunnelWeb.
You will need:

\begin{itemize}

\item FTP access to the internet \i{or} a FunnelWeb distribution kit on disk.

\item A Sun, VMS VAX, Macintosh, or PC \i{or} lots of extra time to port
FunnelWeb to a new platform.

\item About four megabytes of free disk space. You might be able to
install it with less, but four megabytes is safe. The distribution kit itself
is about two and a half megabytes.
If you are short on space, you can throw away everything after installation
except the binary executable which will consume about half a megabyte.

\item A C compiler.

\item An acquaintance with the C programming language and the ability to
compile and link C programs on your machine.

\item Elementary systems programming knowledege for your machine.

\item About an hour.

\end{itemize}

You will \i{not} need any sort of system privileges to install FunnelWeb,
unless you want the FunnelWeb command \p{fw} to be automatically available
to everyone on your machine as well as yourself.

\section{Obtaining a Copy of FunnelWeb}
\xx{FunnelWeb}{obtaining}\xx{ftp}{anonymous}

The simplest way to obtain a copy of FunnelWeb is by anonymous FTP from:

\begin{verbatim}
   Machine   : sirius.itd.adelaide.edu.au [IP=129.127.40.3].
   Directory : ~pub/funnelweb/   (or a directory of similar name).
\end{verbatim}

It is not clear at the time of writing whether FunnelWeb will be presented
as a \dqp{.tar} file, or as a directory tree,
or both. Just sniff around and use
your common sense. Two points deserve attention however:

\begin{enumerate}

\item Be sure to use the \i{text} transfer mode whenever you transfer
raw FunnelWeb files. However, you should use \i{binary} mode for TAR files
and other conglomerate representations.

\item If you have to transfer the files individually,
don't lump all the FunnelWeb files into a single directory. Refer to
the sections that follow for information on the directory tree you should
create to receive the FunnelWeb files.

\end{enumerate}

If anonymous FTP is not available to you, contact the author
for up-to-date information on other channels of distribution.

\begin{verbatim}
   Name:  Dr Ross N. Williams
   Email: ross@spam.adelaide.edu.au
   Snail: 16 Lerwick Avenue, Hazelwood Park 5066, Australia.
\end{verbatim}

\section{Establishing The Directory Tree}
\xx{directory}{tree}

At this stage,
we will assume that you have somehow obtained a set of files that
are supposed to be FunnelWeb, and that they are sitting on a disk
on the machine on which you wish to compile and install
FunnelWeb.

The first thing you have to do is to make sure that
the FunnelWeb directory tree has been correctly unpacked. The directory
tree should look like this.

\begin{verbatim}
   fwdir       - Root FunnelWeb directory.
      admin    - Administrative files.
      answers  - Answers to test suite.
      hackman  - FunnelWeb Hacker's Manual.
      results  - For test results.
      scripts  - Test scripts.
      sources  - Source code.
      tests    - Test suite.
      userman  - FunnelWeb User's Manual.
\end{verbatim}

The following sections describe the contents of each directory in
alphabetical order. Check the
contents to make sure that you have everything. Do not become fussed if
your configuration is not quite as specified as
it is very easy for
installation guides such as this one to go out
of date as minor last minute changes and updates
are made to the distribution kit. Check the source from which you obtained
the kit, and if it is different too, proceed.

\subsection{Admin Directory}
\xx{admin}{directory}

The \p{admin} directory contains administrative files to do with licensing
and such. It is also a catch-all directory for files that don't belong
anywhere else. At the time of writing, it is not clear
exactly what will be in the \p{admin} directory. Why not take a look?

\subsection{Answers Directory}
\xx{answers}{directory}

The \p{answers} directory contains the
\dq{correct answers}\xx{correct}{answers}
to all the regression testing input files. The regression test scripts
compare these files to the files generated in the \p{results} directory.

\begin{verbatim}
an01.lis ... an04.lis
ex01.lis ... ex16.lis
ex01.out ... ex10.out
ex11.tex ... ex16.tex
generate.lis
hi01.lis ... hi10.lis
hi01.out ... hi05.out
hi06a.out
hi06b.out
hi07a.out
hi07b.out
hi08.out ... hi10.out
pr01.lis ... pr10.lis
sc01.lis ... sc29.lis
tg01.lis ... tg09.lis
tg01.out ... tg09.out
wv01.lis ... wv06.lis
wv01.tex ... wv06.tex
\end{verbatim}

\subsection{Hackman Directory}
\xx{hackman}{directory}

The \p{hackman} directory contains the \p{.tex} files that make up the
\i{FunnelWeb Hacker's Manual}.

\begin{verbatim}
h_ch0.tex     - Preface, etc.
h_ch1.tex     - Design.
h_ch2.tex     - Implementation.
h_ch3.tex     - Modification.
h_ch4.tex     - Future.
h_cha.tex     - Appendices.
h_manual.tex  - Main TeX file.
\end{verbatim}

See the comment at the top of \p{h\_manual.tex} file for
instructions on how to typeset and print the \i{FunnelWeb Hacker's Manual}.

There is no need to read or print the \i{FunnelWeb Hacker's Manual} unless you
intend to modify FunnelWeb.

\subsection{Results Directory}
\xx{results}{directory}

The \p{results} directory exists as a target directory for
the output files generated by FunnelWeb during regression testing.
This directory is distributed empty and
should be empty at the start of regression testing.
However, it is permissible for the \p{results} directory to
contain files generated
during a previous test run, as the regression testing scripts
delete specific unwanted files before each test anyway.

\subsection{Scripts Directory}
\xx{scripts}{directory}

The \p{scripts} directory stores the FunnelWeb command shell scripts that
are used to perform regression testing.\xx{regression}{testing}

\begin{verbatim}
master.fws    - The master test script. This is the one you run.
test_gen.fws  - Script to generate certain tricky input files.
test_l.fws    - Test FunnelWeb with +L.
test_ld.fws   - Test FunnelWeb with +L +B...
test_lo.fws   - Test FunnelWeb with +L +O.
test_lo2.fws  - Test FunnelWeb with +L +O (two output files).
test_lot.fws  - Test FunnelWeb with +L +O +T.
test_lt.fws   - Test FunnelWeb with +L +T.
\end{verbatim}

\subsection{Sources Directory}
\xx{sources}{directory}

The \p{sources} directory contains \i{all} of the C source files
required to build a FunnelWeb binary executable. In the following list,
files given without an extension represent both \p{.c} and \p{.h} files.

\begin{verbatim}
analyse       - The analyser.
as            - Assertions.
clock         - A clock abstraction.
command       - The shell command interpreter.
data          - Shared data structures and global variables.
dump          - Functions to dump internal data structures.
environ.h     - Lightweight machine-dependent, program-independent header.
help          - Module to write out help messages.
help_gnu      - Function to write out the GNU license.
help_gnu.txt  - The GNU license in text form.
help_gnu.ctx  - The GNU license in C code form.
list          - A list abstraction.
lister        - Module to manage the listing file.
machin        - Module to hold machine-dependent, program-dependent stuff.
main.c        - The main() program.
mapper        - Module to read files into memory.
memory        - Memory management.
misc          - Miscellaneous functions.
option        - Command line option processing.
parser        - The parser.
scanner       - The scanner.
section       - A section number abstraction.
style.h       - A machine-independent, program-independent header file.
table         - A table abstraction.
tangle        - The tangler.
texhead       - Module to write out TeX header in documentation files.
texhead.ctx   - The TeX header in C code form.
texhead.tex   - The TeX header in TeX form.
weave         - The weaver.
writfile      - Output abstraction.
\end{verbatim}

The \dqp{.txt}, and \dqp{.tex} files do not participate in the compilation,
but are considered part of the source code as they
were used to generate the \dqp{.ctx} files. The \dqp{.ctx} files
are included by \p{.c} files of the same name. They do not need to be
compiled themselves.

\subsection{Tests Directory}
\xx{tests}{directory}

The \p{tests} directory stores all the input files of the
regression test suite. These come in two kinds: FunnelWeb input
files with extensions of \dqp{.fw}, and FunnelWeb include files with
extensions of \dqp{.fwi}.

\begin{verbatim}
FunnelWeb Input Files:
   an01.fw ... an04.fw    - Analyser tests.
   ex01.fw ... ex16.fw    - Examples from the tutorial in user manual.
   generate.fw            - Generates a few other tricky input files.
   hi01.fw ... hi10.fw    - Examples from the hints chapter in user manual.
   pr01.fw ... pr10.fw    - Parser tests.
   sc01_note.fw           - A note explaining absence of sc01.fw
   sc02.fw ... sc29.fw    - Scanner tests.
   tg01.fw ... tg09.fw    - Tangler tests.
   wv01.fw ... wv06.fw    - Weaver tests.

FunnelWeb Include Files:
   ex09a.fwi
   sc13a.fwi ... sc13f.fwi
   sc15a.fwi
   tg08a.fwi
\end{verbatim}

\subsection{Userman Directory}
\xx{userman}{directory}

The \p{userman} directory contains the \p{.tex} files that make up the
\i{FunnelWeb User's Manual}.

\begin{verbatim}
u_ch0.tex     - Preface, etc.
u_ch1.tex     - Tutorial.
u_ch2.tex     - Hints.
u_ch3.tex     - Definition.
u_ch4.tex     - Installation.
u_ch5.tex     - Administration.
u_cha.tex     - Appendices.
u_manual.tex  - Main TeX file.
\end{verbatim}

See the comment at the top of \p{u\_manual.tex} file for
instructions on how to typeset and print the \i{FunnelWeb User's Manual}.

\section{Compiling FunnelWeb}
\xx{compiling}{FunnelWeb}

The FunnelWeb source code is entirely contained within the \p{sources}
directory. However, some simple
script files and makefiles can be found in the \p{admin} directory.

FunnelWeb contains some machine-dependent components, so before compiling
FunnelWeb, you need to specify your machine in the source file \p{environ.h}.
To do this,
edit the \p{environ.h} file and set exactly one of the machine name
\p{\#define}s to \p{1}. For example, on the Sun you should set:

\begin{verbatim}
#define MAC 0
#define SUN 1
#define VMS 0
#define PC  0
\end{verbatim}

There should be little difficulty compiling FunnelWeb for any of these
platforms.
If the machine on which you are compiling FunnelWeb is not one of the ones
listed in the \p{environ.h} file, then choose the closest one you can.
Try the \p{SUN} if you are running a non-Sun Unix.
If you run into serious difficulties, you will have to
customize \p{machin.h} and \p{machin.c} for your machine.
See the comments in these files
for instructions on how to do this.

Once you have specified a target machine, compile FunnelWeb by pointing
your C compiler at all the
\dqp{.c} files in the \p{sources} directory.
The \dqp{.txt}, and \dqp{.tex} files do not participate in the compilation,
but appear in the \p{sources} directory because they
were used to generate the \dqp{.ctx} files. The \dqp{.ctx} files
are included by \p{.c} files of the same name and do not need to be
compiled separately.
Link the results.

The result of all this should be a binary executable called
\p{fw}, or \p{fw.exe},
or \p{fw.xxx} where \p{.xxx} is whatever file extension is
appropriate on the target machine. Clean up the
\p{sources} directory by deleting all the listing and object files.

\section{Testing FunnelWeb}
\label{testingfunnelweb}\xx{testing}{FunnelWeb}

Once you have obtained a binary executable, you should test FunnelWeb
before making it available to users. To do this:

\begin{enumerate}

\item Set the default directory to be the \p{scripts} directory.

\item Copy the FunnelWeb executable into the scripts directory (or
be able to invoke it from the scripts directory).

\item Edit the script \p{master.fws}. Locate the section called
\dq{Define Symbol For the Root Test Directory} and define the \p{R}
symbol to point to the FunnelWeb root directory \p{fwdir}. The examples
in the comments in the script should make it clear what is required.

\item Invoke FunnelWeb to execute the master test script
with the command line \p{fw +xmaster}

\end{enumerate}

The \p{master.fws} script should run for a few minutes. If all goes
well, you will find a differences report on your screen reporting
zero differences. If this happens, then FunnelWeb has been
fully tested and is ready to be made available to users. You should
delete all the files in the \p{results} directory and proceed to the next
section on installing FunnelWeb for users.

If there were
one or more differences, you can either give up and contact the author,
or attempt to fix the code yourself. If you decide to fix the code
yourself, start
with the differences log file and follow your nose. Good luck!

\section{Installing FunnelWeb}
\xx{installing}{FunnelWeb}

At this stage you should have a \p{fwdir} directory tree somewhere in your
file system. Its contents should be almost identical to the directory
contents specified earlier in this chapter except there should now be
an additional binary executable file sitting in the \p{scripts}
directory.

To make FunnelWeb available to users, you should:

\begin{enumerate}

\item Make the entire directory tree readable to all users.

\item Move the binary executable from the scripts directory to the
\p{admin} directory \i{or} copy it to somewhere convenient such as
a \p{/bin} directory.

\item Set up a symbol, path, or command of some kind by the name of \p{fw}
that \dq{points} to the binary executable. If possible, set this up so
that the \p{fw} symbol is available to all users. Alternatively,
you can inform interested users of how they can add a command to their
\p{login} command file to make the command available to them.

\end{enumerate}

If you are short of disk space or have a system that is stressed in some other
way, it may be of assistance to you to know that
FunnelWeb has been constructed so that its
binary executable\xx{FunnelWeb}{executable} is
\i{totally self contained}. The binary executable does not rely on any
other files to operate. Nor does it care about its position in the file system.
In fact, all that is really required to use FunnelWeb is the binary
executable and the \i{FunnelWeb User's Manual}. Thus, if you are short
of disk space, you can move the binary executable to your \dqp{/bin}
directory and delete the entire FunnelWeb tree.  However, making the
tree available to users is encouraged because:

\begin{itemize}

\item It allows users to copy the tree and install it on another machine
without bothering you.

\item It allows users access to the \TeX{} code for the \i{FunnelWeb
User's Manual} and the \i{FunnelWeb Hacker's Manual}.

\item It allows users access to the regression test suite. This may not
seem important, but it could be very convenient for the user as the
\p{ex*} and \p{hi*} files of the regression test suite contain most
of the examples from the \i{FunnelWeb User's Manual}. By making them available
you will save users the trouble of typing them in.

\end{itemize}

Finally, you should fill in and send off a FunnelWeb registration form.
This allows me to get a handle on the size and needs of the user base, and you
to be kept informed of new FunnelWeb releases (optional).
See Section~\ref{registration} for more information.

\section{Printing Manuals}
\xx{printing}{manuals}

FunnelWeb comes with two manuals, a \i{FunnelWeb User's Manual} and a
\i{FunnelWeb Hacker's Manual}. Instructions for how to
typeset and print these manuals appear at the top of
the main \TeX{} files for these manuals
\p{u\_manual.tex} and \p{h\_manual.tex}.

There is no need to print the \i{FunnelWeb Hacker's Manual} unless you
intend to modify FunnelWeb. However, you should make a few copies of the
\i{FunnelWeb User's Manual} available for users, or at least
let them know where the \TeX{} source for the \i{FunnelWeb User's Manual}
is kept so that they can typeset and print it themselves.

\section{Installation Problems?}
\xx{problems}{installation}

If you run into any problems installing FunnelWeb, please write a short
report describing the problem and mail it to the author Ross Williams
(\p{ross@spam.adelaide.edu.au}). I may not be able to help you with it
immediately, but I certainly want to know that a problem exists so that
it can be corrected in future releases of FunnelWeb.

%==============================================================================%
%                               End of Ch4.tex                                 %
%==============================================================================%