% This file was created automatically from install.msk.
% DO NOT EDIT!
% DO NOT CHANGE THE ARRANGEMENT OF SECTIONS, SECTION TITLES OR ADD/REMOVE
% SECTIONS WITHOUT CHANGING THE `texdoc' and `instfiles.awk' scripts in
% `mkdistrib' !

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  install.msk               GAP documentation              Frank Celler
%W                                                     & Martin Schoenert
%W                                                     & Alexander Hulpke
%W                                                    & Burkhard Hoefling
%%
%H  @(#)$Id: install.msk,v 1.102 2002/05/05 05:21:36 gap Exp $
%%
%Y  Copyright 1997,  Lehrstuhl D fuer Mathematik,  RWTH Aachen,   Germany
%Y  (C) 1998 School Math and Comp. Sci., University of St  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
%%  This file contains the  description of the installation procedure 
%%  for various operating systems.
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Installing GAP}

\index{installation}\index{options}

{\GAP} runs on a large number of different operating systems. It behaves
slightly different on each of those. This chapter describes the
behaviour of {\GAP}, the installation, and the options on some of those
operating systems.

Currently it contains sections for *UNIX* (see "GAP for UNIX"), which
runs on an ever increasing number of machines, for *Windows* (see "GAP for
Windows"), which is one operating system for *IBM PC compatibles*
and *MacOS* (see "GAP for MacOS"), which is the operating system on
Apple Macintosh computers. 

For other systems the section "Porting GAP" gives hints how to
approach such a port.

Section~"The Documentation" contains information about the manual, where to
find and how to print it.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installation for the Impatient}

\indextt{unzoo}
Because {\GAP} supports three different platforms, Windows, Macintosh and
UNIX, the installation process might differ a bit from what you are used to.
This document explains in detail which files to get and how to install the
system and if you are inexperienced we strongly recommend you follow these
instructions.

If you already have experience in installing {\GAP} or would not read the
installation instructions anyhow this section provides a quick run through
of the installation on a UNIX system.
(If it is incomprehensible or causes problems, *please follow the explicit
installation instructions given below!*)

Get and `unzoo' binary and installation archive(s) and the most recent bugfix 
file (including the most recent binary if you use Windows or Mac).
The following instructions assume you have `unzoo' and it is in your path.
Call
\begintt
unzoo -x gap4r3.zoo
cd gap4r3
\endtt
If there is a bugfix (starting with release 4.3, bugfixes for a release
will be comprehensive), extract it:
\begintt
unzoo -x ../fix4r3nX.zoo
\endtt
Then, to compile the {\GAP} binary call
\begintt
./configure
make
\endtt
and you will get a shell script `bin/gap.sh' to start {\GAP} which you can
copy in a standard path, e.g. copy the script to say `/usr/local/bin' and
rename it to how you expect users to call {\GAP} (either `gap' or `gap4'
is usual).

Send an email to \Mailto{gap@dcs.st-and.ac.uk}, telling us about the 
installation. (This is just a courtesy; we like to know how many people
are using {\GAP} and get feedback regarding difficulties (hopefully none)
that users may have had with installation.)

You might also want to unpack and install {\GAP} packages.
Generally, this involves first getting `accpkg4r3.zoo' and
`deppkg4r3.zoo' (these have all the accepted/refereed and
all the deposited but not yet refereed {\GAP} packages, respectively) or 
visiting the {\GAP} website again and first looking for the `GAP Packages'
link and following through to the individual {\GAP} package `.zoo' files you
want. The package `.zoo' files should all be `unzoo'-ed in the `pkg'
directory, i.e. do: `cd pkg' first. Some of the {\GAP} packages are written
entirely in {\GAP}; these are essentially ``ready-to-go'' after unpacking,
except they should be listed in the `ALLPKG' file (see~"Loading a GAP
Package"). Other {\GAP} packages have a C code component; these generally
require one to do: `./configure; make' in their respective directories.

Each {\GAP} package has a `README'; it's recommended that despite your
impatience that you at least give these a quick glance; for one thing
they will tell you whether the `./configure; make' steps are needed.

Also note that a few details might have changed since the last release.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Getting GAP}

\indextt{ftp}\indextt{www}
{\GAP} is distributed *free of charge*. You can obtain it via `ftp' and
give it away to your colleagues. {\GAP} is *not* in the public domain,
however. In particular you are not allowed to incorporate {\GAP} or
parts thereof into a commercial product.

If you get {\GAP}, we would appreciate it if you could notify us, e.g.,
by sending a short e-mail message to \Mailto{gap@dcs.st-and.ac.uk},
containing your full name and address, so that we have a rough idea of
the number of users. We also hope that this number will be large enough
to convince various agencies that {\GAP} is a project worthy of
(financial) support. If you publish some result that was partly obtained
using {\GAP}, we would appreciate it if you would cite {\GAP}, just as
you would cite another paper that you used. (The copyright page of the
manual gives a sample citation.)
Again we would appreciate if you could inform us about such a paper.

The current release of {\GAP} is version 4.3.

We distribute the *full source* for everything, the C code for the kernel,
the {\GAP} code for the library, and the {\TeX} code for the manual. So it
should be no problem to get {\GAP}, even if you have a rather uncommon
system. Of course, ports to non UNIX systems may require some work. Note
that about 16 MByte of main memory (though at least 32 MByte is desirable)
and about 30MB of disk space are required to run {\GAP}. A full {\GAP}
installation, including all {\GAP} packages and data libraries can use 200MB
and more of disk space. {\GAP} will compile on pentium (586) processors, 
though a faster machine is recommended.

We list and describe the extraction from `.zoo' archives below. As of 
{\GAP}~4.3, however, we also supply the equivalent `.zip' and `.tar.gz' 
archives (simply download the archive type you prefer and use the
corresponding extraction command).

(If you already downloaded an installation archive, you may ignore the rest of
this section.)

The easiest way to get {\GAP} for most users is probably via the
World Wide Web. The main {\GAP} Web site is found at
\URL{http://www.gap-system.org}

There are two *mirror sites* updated automatically each night, at:

\URL{http://www.math.rwth-aachen.de/~GAP}

\URL{http://www.ccs.neu.edu/mirrors/GAP} and

%\URL{http://wwwmaths.anu.edu.au/research.groups/algebra/GAP/www/}
%
At these sites you can browse this manual, download the system and
contributed extensions, read past postings to the {\GAP} forum, and
find out about authors of and contributors to {\GAP}, publications
that cited {\GAP} and {\GAP} related events.

{\GAP} can also be obtained by anonymous *ftp* from (at least) the following
servers.

\beginitems
`ftp-gap.dcs.st-and.ac.uk':&
  School of Mathematical and Computational Sciences,
  University of St Andrews, Scotland, UK.
  Directory `/pub/gap/gap4/'.

`ftp.math.rwth-aachen.de':&
  Lehrstuhl D f{\accent127 u}r Mathematik, RWTH Aachen, Germany.
  Directory `/pub/gap4/'.

`ftp.ccs.neu.edu':&
  College of Computer Science,
  Northeastern University, Boston, USA.
  Directory `/pub/mirrors/ftp-gap.dcs.st-and.ac.uk/pub/gap/gap4'.
\enditems

%`pell.anu.edu.au':&
%  School of Mathematical Sciences, Australian National University,
%  Canberra, Australia.
%  Directory `/pub/algebra/gap4/'.
%
%`math.ucla.edu':
%
% Math. Dept., Univ. of California at Los Angeles,
%
% directory `/pub/gap/'.
%
%`wuarchive.wustl.edu':
%
% Math. Archives, Washington Univ. at St. Louis,
%
% directory `/edu/math/source.code/group.theory/gap'.
%
%`dehn.mth.pdx.edu':
%
% PSU Mathematics Department, Portland State Univ.,
%
% directory `/mirror/gap/'

`ftp' to the server *closest* to you, login as user `ftp' and give your
full e-mail address as password. Remember when you transmit the files to
set the file transfer type to *binary image*, otherwise you will only
receive unusable garbage. Those servers will always have the latest
version of {\GAP} available.

The WWW page for the {\GAP} distribution and the `ftp' directory
contain the following files. Please check first
which files you need, to avoid transferring those that you do not need.
Except for the package archives all archives should be extracted at the
``top'' level level (i.e.~they contain a `gap4r3' directory).

\beginitems
`INSTALL', `INSTALL.WIN', `INSTALL-MAC.TXT':&
 Installation files, one of which you are currently reading.

`FILES':&
 More detailed description of the available files.

`gap4r3.zoo':&
 This file contains the *complete* standard distribution
 of {\GAP} version 4.3 (it does not include the packages
 contained in `accpkg4r3.zoo' and
 `deppkg4r3.zoo').

`basic4r3.zoo':&
 This file contains a *minimal* distribution
 of {\GAP} version 4.3. (There are further archives with which
 you can ``upgrade'' it to the full version.)

`gappc4r3.zoo':&
 This file contains a complete distribution for 32-bit Windows. It includes
 a precompiled binary.

`gapmac4r3.zoo':&
 This file contains a complete distribution for Macintosh under MacOS. You
 will also need to obtain the binaries separately from the `bin'
 subdirectory via ftp or from the links on the Distribution web page.

`accpkg4r3.zoo':&
 This file contains all accepted {\GAP} packages as of the release date.
 It should be extracted in the `pkg' directory of a previously extracted
 {\GAP} distribution or a user's private `pkg' directory.

`deppkg4r3.zoo':&
 This file contains all deposited, but not accepted, {\GAP} packages
 whose authors wish to make them available, as of the release date. They
 should be viewed as analogous to preprints.
 It should be extracted in the `pkg' directory of a previously extracted
 {\GAP} distribution or a user's private `pkg' directory.

`tools4r3.zoo':&
 This file contains additional files not provided in the standard 
 distribution, mainly needed by package developers for the purpose of
 generating documentation.

`util/unzoo.c':&
 A simple `zoo' archive extractor, which should be
 used to unpack the distribution. The `bin'
 subdirectory contains precompiled executables
 for common systems.

 More files are available from the Distribution web page links or
 the following ftp *subdirectories*:

`bin':&
 This directory contains *executables* for systems
 that do not come with a C compiler or where another
 C compiler produces a faster executable.

`split':&
 This directory contains the complete distribution
 of {\GAP} 4.3 in several smaller archives.

`accpkg':&
 This directory contains all accepted {\GAP} packages in case you don't want
 to load the comprehensive `accpkg' archive.

`deposit/pkg':&
 This directory contains all deposited but not yet accepted {\GAP} packages 
 whose authors wish to make them available, in
 case you don't want to load the comprehensive `deppkg' archive.
\enditems


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{GAP for UNIX}

\atindex{BSD}{@BSD}\atindex{4.2BSD}{@4.2BSD}\atindex{4.3BSD}{@4.3BSD}
\atindex{ULTRIX}{@ULTRIX}
\atindex{Linux}{@Linux}\atindex{OSF}{@OSF}\atindex{RS/6000}{@RS/6000}
\atindex{System V}{@System V}\atindex{SysV}{@SysV}\atindex{HP-UX}{@HP-UX}
\atindex{Solaris}{@Solaris}\atindex{IRIX}{@IRIX}
{\GAP} runs very well under UNIX. In fact it is being developed on UNIX
workstations (and PCs under Linux). {\GAP} running on any UNIX machine
should behave exactly as described in the manual.

{\GAP} has successfully been compiled and installed on the following UNIX
machines:
\begintt
DECalpha under OSF 3.2 with GNU cc 2 or cc,
HP9000 under HP-UX with GNU cc 2, 
IBM PC under Linux with GNU cc 2, 
IBM RS/6000 & AIX with GNU cc 2, SGI Mips under IRIX 5/6 with gcc2 or
cc, Sun Sparc under Solaris with GCC 2 or cc. 
\endtt

We hope that compiling and installing {\GAP} on another UNIX machine does
not pose any problem. If it does, please inform us of your problems 
(and, if possible, of your solution).

The section "Installation of GAP for UNIX" describes how you install
{\GAP} on a UNIX machine. See Chapter~"Running GAP" for information about
command line options that {\GAP} accepts under UNIX.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installation of GAP for UNIX}

\atindex{installation!under UNIX}{@installation!under UNIX}
\atindex{UNIX!installation}{@UNIX!installation}
Installing {\GAP} on a UNIX machine
is fairly easy. Get the files described in "Getting GAP"
and decide into which directory you want to install {\GAP} 4.3. 
If
you will be the only user using {\GAP}, you probably should install it
in your home directory. If other users will be also using {\GAP}, you
should install it in a public place, such as `/usr/local/lib/'. {\GAP}
will be installed in a subdirectory `gap4r3' of this directory.
You can later move {\GAP} to a different location. For example you
can first install it in your home directory and when it works move it to
`/usr/local/lib/'.

The following installation example assumes that you (as user `you' on the
machine `unix') are installing {\GAP}
into the  directory `/usr/local/lib' on a Pentium Pro running Linux.

Note that certain parts of the output in the examples
should only be taken as rough outline, especially file sizes and file
dates are *not* to be taken literally.

If you encounter problems please also see section~"If Things Go Wrong" of
this document.

Get the distribution `gap4r3.zoo' and the source for the zoo
archive extractor `unzoo.c'. How you can get those files is described in the
section "Getting GAP". Remember that the distribution consists of binary files
and that you must transmit them in binary mode.

Compile the zoo archive extractor `unzoo' with the command

\begintt
you@unix> cc -o unzoo -DSYS_IS_UNIX -O unzoo.c
you@unix> ls -l unzoo
-rwxr-xr-x you 45056 Nov 3 10:11 unzoo
you@unix> 
\endtt

Now unpack the distribution with the command

\begintt
you@unix> ./unzoo -x gap4r3.zoo
gap4r3/doc/aboutgap.tex -- extracted as text
gap4r3/doc/aggroup.tex  -- extracted as text
[many more lines]
you@unix> 
\endtt

(Messages of the form: `/bin/mkdir: cannot create directory' are harmless
and can be ignored. They stem from issuing `mkdir' calls for top level
directories every time a new subdirectory is created.)

If you got not the full distribution file but several small files, extract
all of them (*except the bug fixes and {\GAP} packages!*) in this way.

(Afterwards you will not need the file `gap4r3.zoo' any
longer. If you are short of disk space you can remove it now.)
\begintt
you@unix> rm gap4r3.zoo
\endtt

Now go into the directory `gap4r3'. If there is a bug fix (there are
none in the initial release but invariably some follow later and are
deposited in the `bugfixes' directory on our ftp server(s). Starting with
release 4.3, bugfixes will be comprehensive and you need only the most
recent bugfix), extract it while in the `gap4r3' directory. (The bug
fixes extract only on this level of the directory hierarchy to make them
applicable even if you chose later to rename the root directory of your
{\GAP} distribution.)

The program may ask you for confirmation to overwrite files, you should give
this permission.

\begintt
you@unix> cd gap4r3
you@unix> ../unzoo -x ../fix4r3n3.zoo
[extraction information]
\endtt

If you got any {\GAP} packages, extract them in the `pkg' subdirectory in the
same way. For example if you got the `accpkg4r3.zoo' and
`deppkg4r3.zoo' archives, you would issue:

\begintt
you@unix> cd pkg
you@unix> ../../unzoo -x ../../accpkg4r3.zoo
you@unix> ../../unzoo -x ../../deppkg4r3.zoo
you@unix> cd ..
\endtt

There is a little more to do to install the {\GAP} packages but (particularly
for those packages with a C code component) it's only appropriate to 
complete each {\GAP} package's installation after {\GAP} has been compiled.

The directories `trans', `small' and `prim' contain data
libraries. If you are short of disk space you can erase some of them,
and any of the {\GAP} package directories in `pkg' that you have decided
you don't need, but then of course you will not be able to access these
data or packages.

Under UNIX, we now use the ``autoconfig'' method to take care of system
dependencies. (See~"Porting GAP" if this is not working on your machine.)

If you are installing {\GAP} on various systems that share a file system 
then all the above steps have essentially been done for all but the first
system and on succeeding systems these steps are replaced by (fairly
obviously) changing to the `gap4r3' directory. However, before 
proceeding with the following steps, on each other machine you *must* 
first remove the files `config.cache' and `config.status' created on
the previous machine!

Now run the shell script `configure':

\begintt
you@unix> ./configure
checking host system type... i686-unknown-linux2.0.27
[many more lines]
\endtt

This will automatically detect the machine and compiler target. The 
process will automatically create an appropriate binary subdirectory.
It also creates a `Makefile' that will be used to compile {\GAP} on this
machine. Simply call `make':

\begintt
you@unix> make
[many lines of further configuration and compilation]
\endtt

The compilation process creates the object files and the executable in
the directory 

\)\kernttindent/usr/local/lib/gap4r3/bin/<target>/

where <target> is the name printed by the first `configure' (and
`/usr/local/lib' the directory in which you installed {\GAP}). In our
example the executable will be created as

\)\kernttindent/usr/local/lib/gap4r3/bin/i686-unknown-linux2.0.27/gap

If `configure' or `make' fails, see section~"Known Problems of the Configure
Process" for a description of some remedies. If all of these fail,
please inform us at \Mailto{gap-trouble@dcs.st-and.ac.uk}.

If you have UNIX experience you might want to change the compilation options
to obtain a better performance. Section~"Optimization and Compiler Options"
explains how to do this. In particular, if you have little system memory,
you might want to remove debugging information from the binary to create a
smaller file. This is done by the UNIX `strip' command which gets invoked by:
\begintt
you@unix> make strip
\endtt

In order to test your compilation now run the newly created executable.
You should get the {\GAP} banner and then the {\GAP} prompt. (The process of
starting {\GAP} may take a little while.)

\begintt
you@unix> cd ..
you@unix> bin/i686-unknown-linux2.0.27/gap -l /usr/local/lib/gap4r3
[... lines deleted]
gap> 
\endtt

(Having to give the library path with the `-l' option each time would be a
bit tedious. Below we will therefore install a shell script to start
{\GAP}.)

Try a few things to see if the compilation succeeded.

\begintt
gap> 2 * 3 + 4;
10
gap> Factorial( 30 );
265252859812191058636308480000000
gap> Size( SymmetricGroup( 10 ) );
3628800
gap> Factors( 10^42 + 1 );
[ 29, 101, 281, 9901, 226549, 121499449, 4458192223320340849 ]
gap> m11 := Group((1,2,3,4,5,6,7,8,9,10,11),(3,7,11,8)(4,10,5,6));;
gap> Size( m11 );
7920
gap> Factors( 7920 );
[ 2, 2, 2, 2, 3, 3, 5, 11 ]
gap> Length( ConjugacyClasses( m11 ) );
10 
\endtt

Especially try the command line editing and history facilities, because
they are probably the most machine dependent feature of {\GAP}. Enter a
few commands and then make sure that <ctr>-`P' redisplays the last
command, that <ctr>-`E' moves the cursor to the end of the line, that
<ctr>-`B' moves the cursor back one character, and that <ctr>-`D' deletes
single characters. So, after entering the above commands, typing

<ctr>-`P' <ctr>-`P' <ctr>-`E' <ctr>-`B'
<ctr>-`B' <ctr>-`B' <ctr>-`B' <ctr>-`D' `1' <return>

should give the following lines:

\beginexample 
gap> Factors( 7921 );
[ 89, 89 ]
\endexample

If you can compile but command line editing does not work
you can always start {\GAP} with option `-n' to
disable command line editing. In such a case however we would like to hear
about such problems.

If your operating system has job control, make sure that you can still
stop {\GAP}, which is usually done by pressing <ctr>-`Z'.

The `make' process should also have created a shell script `gap.sh' in the
`bin' subdirectory. This file already contains proper directory paths and it
should be possible to start {\GAP} by simply calling this script. Still, you
might want to edit it to give further default command line options or modify
the default memory.

Execute the script to start {\GAP} again
\begintt
you@unix> bin/gap.sh
\endtt
If the shell complains that it cannot execute or find `gap.sh' check
the permissions of the file by doing a `ls  -l bin/gap.sh'. The
permissions should include execute permissions, if they don't you can set
them by
\begintt
you@unix> chmod +x bin/gap.sh
\endtt

Then copy this script into a directory in your search path, for example
`/usr/local/bin/' as `gap' (or `gap4' if you also have {\GAP} 3 running on
the same machine). (If you are using the C-shell, you will also
have to `rehash', so that the C-shell adds `gap' to its internal
tables). When you later move {\GAP} to another location you only need
to edit this script.

There also is a shell script `gac' in the same place that can be used to
invoke the compiler. Depending on your installation you also might want to
copy it in a directory in your search path.

Now you should be able to start {\GAP} by its name:

\begintt
you@unix> cd ~
you@unix> gap
\endtt

(If you get an error message ```hmm, I cannot find lib/init.g''' you are
starting the pure binary. It needs to find the library which is given via
the command line parameter `-l'.)

A set of test files is provided, running them all takes some 40 minutes on
a Pentium Pro 200 MHz. As a quick test we start `combinat.tst' first.

\begintt
gap> Filename( DirectoriesLibrary("tst"), "combinat.tst" );
"/usr/local/lib/gap4r3/tst/combinat.tst"
gap> ReadTest(last);
+ $ld: combinat.tst,v 4.7 1997/11/21 10:19:47 ahulpke Exp $
+ GAP4stones: 27801
true
\endtt

The number given as `GAP4stones' will vary, depending on the speed of your
machine.

Now use `Read' (*not* `ReadTest') to read the file `testall.g' to run
*all* available test files. This is not a necessary part of the
installation, it only serves as a confirmation that everything went
OK. The full test suite takes some time (almost 2 hours on a Pentium
III/500) and uses quite a bit of memory (around 100MB), so you may
wish to skip this step or run only part of the tests. This does no
harm.

\begintt
gap> Filename( DirectoriesLibrary("tst"), "testall.g" );
"/usr/local/lib/gap4r3/tst/testall.g"
gap> Read(last);
[lines omitted]
test file         GAP4stones     time(msec)
-------------------------------------------
testing: ./tst/boolean.tst
boolean.tst                0              0
testing: ./tst/unknown.tst
unknown.tst                0             10
testing: ./tst/gaussian.tst
gaussian.tst               0            250
[further lines omitted]
\endtt

You can ignore warnings from `weakptr.tst', which stem from garbage
collections occurring at different times, and those from `grpconst.tst'
which stem from differences in available {\GAP} packages.

The information about the manual is system independent, you can find it in
section~"The Documentation".

Now you should finish the installation for the {\GAP} packages you intend to
install. First do:

\begintt
you@unix> cd pkg
\endtt

Each {\GAP} package has a `README', which details the additional steps
necessary for installation of the package.
Some of the {\GAP} packages are written entirely in {\GAP}; for these once
you have installed them on one system there is no further work required
on other systems sharing the same file system. For the packages with a C
code component, generally one must do `./configure' and `make' after changing
to the package's directory, e.g. for the \package{ACE} package you 
usually only need to do:

\begintt
you@unix> cd ace
you@unix> ./configure
you@unix> make
you@unix> cd ..
\endtt

For other systems sharing the same file system you need to repeat these
steps for each system; the appropriate time is immediately after compiling
{\GAP} on each system.

Some {\GAP} packages are set up to load  (or  provide  the  documentation)
automatically. To enable this, after  installing  all  the  packages  you
think you will need, you should list all  the {\GAP}  packages  you  have
installed in a file `ALLPKG' in the `pkg' directory (see Section~"Loading
a GAP Package" in the Reference Manual for details); an easy way to  do
this under UNIX is by issuing the command

\begintt
find * -type d -maxdepth 0 -print > ALLPKG
\endtt
while still in the `pkg' directory.

Please see
Chapter~"GAP Packages" for more details on the installation of {\GAP}
packages.

If you want to install {\GAP}  also  on  different  architectures,  which
share the same file system with the machine on which you  just  installed
{\GAP} log into these machines and go to the {\GAP} home  directory.  You
do  not  need  to  extract  any  new  files,  simply  execute  the   same
``configure/make'' process which has  been  described  above  again  (but
remember to remove the files  `config.cache'  and  `config.status',  each
time). Make sure also,  however,  that  you  copy  the  `bin/gap.sh'  and
`bin/gac' shell scripts created by the `make' process, each time, because
they are system dependent and will be overwritten when compiling on  each
new system.

*A few final reminders:*

\beginlist%unordered

\item{$\bullet$}
Make sure that you got and installed *the most recent* bugfix. 

\item{$\bullet$}
We would appreciate after installation your sending us a short note at
\Mailto{gap@dcs.st-and.ac.uk} 
(even if you have installed {\GAP} 3 before).
Generally, we do not reply to such emails; we only use them to gain  some
idea of how many people use {\GAP} and of the machines/operating  systems
on which {\GAP} has been successfully installed.

\item{$\bullet$}
We also suggest that you subscribe to our `gap-forum' mailing  list;  see
the {\GAP} web pages for details. Whenever there is  a  bug  fix  or  new
release of {\GAP} this is where it is  announced.  The  `gap-forum'  also
deals with user questions of a general  nature;  bug  reports  and  other
problems you have while installing and/or using {\GAP} should be sent  to
\Mailto{gap-trouble@dcs.st-and.ac.uk}.

\endlist

That's all, your installation should be complete. We hope that you will 
enjoy using {\GAP}. Remember, if you have problems, do not hesitate to
contact us at
\Mailto{gap-trouble@dcs.st-and.ac.uk}.
See Section~"If Things Go Wrong" for what to include in a bug report.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Known Problems of the Configure Process}

If `make' complains ``Do not know how to make <xyz>'' but <xyz> is an
existing file, it is likely that the dates of the files were not
extracted properly (Alpha-OSF machines are prone to this). Call
\begintt
touch * cnf/* src/*
\endtt
from the main {\GAP} directory (this ought to reset the date of all relevant
files to ``now'') and try again.

Sometimes the `configure' process does not properly figure out the 
``inline'' compiler command. If you get error messages
that complain that ``inline'' is unknown, edit the file `config.h' in the
`bin/<target>' subdirectory and replace the line
\begintt
/* #undef inline */
\endtt
by
\begintt
#define inline
\endtt
and then try to compile again.

The `configure' script respects compiler settings given in environment
variables. However such settings may conflict with the automatic
configuration process. If `configure' produces strange error messages about
not being able to run the compiler, check whether environment variables that
might affect the compilation (in particular `CC', `LD', `CFLAGS', `LDFLAGS'
and `C_INCLUDE_PATH') are set and reset them using `unsetenv'.

Some users reported problems with `make', while the GNU version `gmake'
worked. Thus if problems occur you should try `gmake' instead
if it is installed on your machine.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Problems on Particular Systems}

The highest levels of optimization of the OSF/4 C compiler `cc' on the
Compaq alpha chip make assumptions about the use of pointers which are
not valid for {\GAP}, and produce executables that can crash; `-O3'
seems to be safe, but `-O4' and `-fast' are not.

On Sun and IRIX systems which are capable of running in 32 or 64 bit
modes, it is possible to build a 64 bit version of {\GAP}, but special 
procedures are needed (and, on Suns, a compiler bug must be
circumvented). If you wish to compile on such a system, please send an
email to 
\Mailto{gap-trouble@dcs.st-and.ac.uk}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Optimization and Compiler Options}

Because of the large variety of different versions of UNIX and different
compilers it is possible that the `configure' process will not chose
best possible optimization level, but you might need to tell `make' about
it.

If you want to compile {\GAP} with further compiler options (for example
specific processor optimizations) you will have to assign them to the variable
`COPTS' as in the following example when calling `make':
\begintt
make COPTS=-option
\endtt
If there are several compiler options or if they contain spaces you might
have to enclose them by quotes to avoid depending on the shell you are
using.

The `configure' process also introduces some default compiler
options. (See the `Makefile' in the `bin' directory for details.)
You can eliminate these by assigning the variable `CFLAGS' (which contains
the default options and `COPTS') to the desired list of compiler options in
the same way as you would assign `COPTS'.

The *recommended* C compiler for {\GAP} is the GNU C compiler `gcc',
or a related compiler such as `egcs'. There are two reasons for this
recommendation: firstly we use `gcc' in {\GAP} development and so this
combination has been far more heavily tested than any other and
secondly, we have found that it generally produces code which is
faster than that produced by other compilers. 

If you do wish to use another compiler, you should remove
`config.cache' and `config.status' in the {\GAP} root directory, set
the environment variable `CC' to the name of your preferred compiler
and then rerun `configure' and `make'. You may have to experiment to
determine the best values for `CFLAGS' and/or `COPTS' as described
above. Please let us (\Mailto{gap-trouble@dcs.st-and.ac.uk}) know 
the results of your experiments.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{GAP for Windows}

\atindex{Windows}{@Windows}
It is possible to compile {\GAP} for 32-bit Windows using the Cygnus
`cygwin32' implementation of GCC. We provide such a binary, and have tested
that runs under the English version of Windows 98. It is likely that it will
also work under later versions such as WindowsNT and Windows XP.

It is likely that features of {\GAP} like `Process', `Exec' or the compiler,
that rely on a UNIX environment will not work under Windows.

The following sections contain information about {\GAP} that is specific
to this port of {\GAP} (simply called {\GAP} for Windows below).

To run {\GAP} under Windows you need an IBM PC compatible with an Intel
Intel 80486, or Intel Pentium processor or better.
The system must have at least 16 MByte of main memory and a harddisk.
The operating system must be Windows 95 or better.

The section "Copyright of GAP for Windows" describes the copyright as it
applies to the executable version that we distribute. The section
"Installation of GAP for Windows" describes how you install {\GAP} for
Windows.

The compiler we are using to create the Windows binary (Cygnus GNUWin32)
provides a C-library that emulates all standard UNIX commands. There
are however a few low-level routines that have to be called system-specific
and for which we have not yet found out how to do it under Windows.
We will try to fix
these in a future version. If you have experience in Windows programming and
know how to do such things we would very much welcome help.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Copyright of GAP for Windows}

In addition to the general copyright for {\GAP} set forth in the
Copyright the following terms apply to {\GAP} for Windows.

The executable of {\GAP} for Windows that we distribute was compiled with
The `gnuwin32' compiler of the `cygwin' package. 
This compiler can be obtained by anonymous `ftp' from a
variety of general public FTP archives. Many thanks to the Free Software
Foundation and Cygnus Support for this amazing piece of work.

The GNU C compiler is

*Copyright (C) 1989, 1991 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA*

under the terms of the GNU General Public License (GPL). Note that the
GNU GPL states that the mere act of compiling does not affect the
copyright status of {\GAP}.

The compiler is copyright under the terms of the GNU General Public
License (GPL). You can find details under
\URL{http://www.cygnus.com/misc/gnu-win32/faq.html}

The Cygwin32 API library is also covered by the GNU GPL. The executable we
provide is linked against this library (and in the process includes
GPL'd Cygwin32 glue code). This means that the executable falls under
the GPL too, i.e., is distributed freely, which it basically does anyhow.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installation of GAP for Windows}

\atindex{installation!under Windows}{@installation!under Windows}
\atindex{Windows!installation}{@Windows!installation}
Installing {\GAP} under 32-bit Windows should be fairly easy.

In the following, we assume that you install {\GAP} in the directory 
\begintt
C:\GAP4R3
\endtt
on a Windows98 machine.
(For experts (or users without write permission in the `C:' directory) it is
possible to install GAP in another directory, but this will require
specialist knowledge (editing a batch file) which many Windows users do not
possess. See section~"Expert Windows installation" for details on how to do
this.)

Note that certain parts of the output in the examples
should only be taken as rough outline, especially file sizes and file
dates are *not* to be taken literally.

If you encounter problems please also see section~"If Things Go Wrong" of
this document.

Get the Windows-specific files `gappc4r3.zoo' and the Windows
version of the zoo archive extractor `unzoo.exe', and copy them in the `C:'
directory.

How you can get those files is described in the section "Getting GAP". 
Remember that the distribution consists of binary files
and that you must transmit them in binary mode. See 
\URL{http://www.gap-system.org/Info/mime.html}
if you have problems with loading the files.

(The `zoo' archives we provide for {\GAP} contain comments which indicate
whether files are text or binary files. The `unzoo' we provide uses these
comments to translate the ``LF'' line endings we use to the Windows style
``CRLF''. If you use another zoo extractor you might lose this information
and end up with files that might not conform to your operation system
standards.)

Open a window with the `MS-DOS Command Prompt' and go to the `C:' directory.
\begintt
C:\WINDOWS> cd c:\
\endtt

Now unpack the distribution with the command

\begintt
C:\> unzoo -x gappc4r3.zoo
gap4r3\bin\gap.bat -- extracted
gap4r3\doc\aboutgap.tex -- extracted
gap4r3\doc\aggroup.tex -- extracted
[many more lines]
\endtt

(Afterwards you will not need the file `gappc4r3.zoo' any
longer. If you are short of disk space you can remove it now.)
\begintt
C:\> del gappc4r3.zoo
\endtt

Now go into the directory `GAP4R3'. If there is a bug fixes (there
are none in the initial release but invariably some follow later and are
deposited in the `bugfixes' directory on our ftp server(s). Starting with
release 4.3, bugfixes will be comprehensive and you need only the most
recent bugfix), extract it while in the `gap4r3' directory. (The bug
fixes extract only on this level of the directory hierarchy to make them
applicable even if you chose later to rename the root directory of your
{\GAP} distribution.)

The program may ask you for confirmation to overwrite files, you should give
this permission.

\begintt
C:\> cd GAP4R3
C:\GAP4R3> ../unzoo -x ../fix4r3n3.zoo
[extraction information]
\endtt

If the bugfixes provide a new binary, unpack the corresponding file
`wbinXXX.zoo' in the same way. It overwrites the old binary.

If you got any {\GAP} packages, extract them in the `pkg' subdirectory in
the same way.  Some {\GAP} packages are set up to load (or provide the
documentation) automatically. To enable this, after installing all the
packages you think you will need, you should list all the {\GAP} packages
you have installed in a file `ALLPKG' in the `pkg' directory (see
Section~"Loading a GAP Package" in the Reference Manual for details).
(Any {\GAP} package that has a C code component is essentially UNIX-dependent
and you may as well delete those; such packages typically describe in their
`README' files that they require `configure' and `make' to complete their
installation or have a `src' directory.)

The directories `trans', `small' and `prim' contain data
libraries. If you are short of disk space you can erase some of them and
any {\GAP} package directories in the `pkg' directory that you don't need,
but then of course you will not be able to access these data and packages.

We provide a precompiled binary in the `bin' subdirectory, so there is no
need to compile {\GAP} yourself.
The provided binary should work under Windows9x and Windows NT.

Now start {\GAP} either by calling
\begintt
C:\GAP4R3> bin\gapw95.exe
\endtt
or by starting the program `gapw95.exe' in the directory
\begintt
C:\GAP4R3\BIN
\endtt

You should get the {\GAP} banner and then the {\GAP} prompt. (The process of
starting {\GAP} may take a little while.)

Try a few things to see if the binary works.

\begintt
gap> 2 * 3 + 4;
10
gap> Factorial( 30 );
265252859812191058636308480000000
gap> Size( SymmetricGroup( 10 ) );
3628800
gap> Factors( 10^42 + 1 );
[ 29, 101, 281, 9901, 226549, 121499449, 4458192223320340849 ]
gap> m11 := Group((1,2,3,4,5,6,7,8,9,10,11),(3,7,11,8)(4,10,5,6));;
gap> Size( m11 );
7920
gap> Factors( 7920 );
[ 2, 2, 2, 2, 3, 3, 5, 11 ]
gap> Length( ConjugacyClasses( m11 ) );
10 
\endtt

Especially try the command line editing and history facilities, because
they are probably the most machine dependent feature of {\GAP}.

Note that {\GAP} is developed under UNIX and therefore the key commands are
rather UNIX-type then Windows type. We try also to recognize some common
Windows key commands such as the arrow keys, but it is likely that not all
Windows-special key commands will be recognized: in general {\GAP} will not
conform to standard Windows ``look-and feel''. (See below on how to enable
cut-and-paste.)

Enter a few commands and then make sure that <ctr>-`P' redisplays the last
command, that <ctr>-`E' moves the cursor to the end of the line, that
<ctr>-`B' moves the cursor back one character, and that <ctr>-`D' deletes
single characters. So, after entering the above commands, typing

<ctr>-`P' <ctr>-`P' <ctr>-`E' <ctr>-`B'
<ctr>-`B' <ctr>-`B' <ctr>-`B' <ctr>-`D' `1' <return>

should give the following lines:

\begintt
gap> Factors( 7921 );
[ 89, 89 ] 
\endtt

You also might want to enable cut-and-paste in the {\GAP} window and select
a more pleasant icon. You should be able to do this with the `PIF' file
`gap.pif' in the `bin' directory (it might show up only as `GAP' with an
`MSDOS' icon), if
necessary following the instructions on the web page
\URL{http://www.gap-system.org/Info4/windows.html}.  (If this `PIF' file
does not work, you will have to create a new PIF file. For details on how to
do this, see the Documentation provided by Microsoft.)

The information about the manual is system independent, you can find it in
section~"The Documentation".

*A few final reminders:*

\beginlist%unordered

\item{$\bullet$}
Make sure that you got and installed *the most recent* (and probably the
corresponding binary).

\item{$\bullet$}
We would appreciate after installation your sending us a short note at
\Mailto{gap@dcs.st-and.ac.uk} 
(even if you have installed {\GAP} 3 before).
Generally, we do not reply to such emails; we only use them to gain some idea
of how many people use {\GAP} and of the machines/operating systems on which
{\GAP} has been successfully installed.

\item{$\bullet$}
We also suggest that you subscribe to our `gap-forum' mailing list; 
see the {\GAP} web pages for details. Whenever there is a bug fix or new
release of {\GAP} this is where it is announced. The `gap-forum' also
deals with user questions of a general nature; bug reports and other
problems you have while installing and/or using {\GAP} should be sent to
\Mailto{gap-trouble@dcs.st-and.ac.uk}.

\endlist

That's all, your installation should be complete. We hope that you will 
enjoy using {\GAP}. Remember, if you have problems, do not hesitate to
contact us at
\Mailto{gap-trouble@dcs.st-and.ac.uk}.
See Section~"If Things Go Wrong" for what to include in a bug report.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Expert Windows installation}

This section decribes how to get a better shell for GAP, how to install {\GAP}
in another directory and how to test the installation. 

Some users report that the `rxvt' shell gives a btter windows environment
for cut/paste etc. You can find information on this at
\URL{http://www.gap-system.org/Forum/Pasechni.1/Dima.1/Re__Wind.1/1.html}

If you decide to install {\GAP} in another directory you can do so, but you
will have to edit a batch file and use this file to start {\GAP}.

First unpack the {\GAP} distribution in the directory you want. 

Lets suppose you want {\GAP} to reside in the directory
\begintt
C:\SOFTWARE\GAP
\endtt
Extract {\GAP} (as described in the previous section for `C:') in this
directory. (alternatively, you can also first unpack it in 
\begintt
C:\GAP4R3
\endtt
test it there first, and afterwards move it in the desired location.)

You now will have to edit a batch file, that will be used to start {\GAP}.
This batch file is needed, since {\GAP} otherwise will not find its library
directories. The most natural name for this file would be
\begintt
C:\SOFTWARE\GAP\GAPGAP4R3\BIN\GAP.BAT
\endtt
This file should contain the following *single* line (which might be broken
over in several lines in this instructions since the page width is limited):
\begintt
C:\SOFTWARE\GAP\GAPGAP4R3\bin\gapw95.exe -m 14m 
  -l C:\SOFTWARE\GAP\GAPGAP4R3 %1 %2 %3 %4 %5 %6 %7 %8
\endtt
If the path includes blanks (such as `Program Files'), you will have to
enclose the `-l' argument in apostrophes:
\begintt
C:\Program Files\GAP\GAPGAP4R3\bin\gapw95.exe -m 14m 
  -l 'C:\Program Files\GAP\GAPGAP4R3' %1 %2 %3 %4 %5 %6 %7 %8
\endtt

You now should be able to start {\GAP} by clicking this `gap.bat' file.
You might want to copy this file `gap.bat' into a directory in your
search path (for example the `DOS' directory)
as `gap.bat' to be able to start {\GAP} by its name from any location:
\begintt
C:\WINDOWS> gap
\endtt

If you want to check your installation, a set of test files is provided,
This test is not a necessary part of the installation, it only serves as a
confirmation that everything went OK.  (Since running these tests might take
several hours and requires quite a bit of free memory, you may wish to skip
this step or run only part of the tests. This does no harm.)

As a quick test we start `combinat.tst' first.

\begintt
gap> Filename( DirectoriesLibrary("tst"), "combinat.tst" );
"./tst/combinat.tst"
gap> ReadTest(last);
+ $ld: combinat.tst,v 4.7 1997/11/21 10:19:47 ahulpke Exp $
+ GAP4stones: 26801
true
\endtt

Note that {\GAP} internally uses `/' to separate directory names. This will
be translated to backslashes for the operating system.

Now you can use `Read' (*not* `ReadTest') to read the file `testall.g' to
run *all* available test files.  (You should not pay too much attention to
the {\GAP}stone ratings of the different files. The time measurements are
not calibrated and sometimes vary substantially because further tests have
been added to a file.)

\begintt
gap> Filename( DirectoriesLibrary("tst"), "testall.g" );
"./tst/testall.g"
gap> Read(last);
[lines omitted]
test file     GAP4stones   time(msec)
-------------------------------------------
[further lines omitted]
\endtt

You can ignore warnings from `weakptr.tst', which stem from garbage
collections occurring at different times, and those from `grpconst.tst'
which stem from differences in available {\GAP} packages.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{GAP for MacOS}

\atindex{MacOS}{@MacOS}\atindex{Apple}{@Apple}\atindex{Macintosh}{@Macintosh}
This section contains information about {\GAP} that is specific to the
port of {\GAP} for Apple Macintosh systems under MacOS (simply called
{\GAP} for MacOS below).

To run {\GAP} for MacOS you need an Apple Macintosh with a Motorola M68020, 
M68030, or M68040 processor, or a Power Macintosh. The computer must have 
at least 16MByte of (physical) memory and a harddisk. For 
serious calculations, much more may be needed. The operating system must 
be System 7 or higher. {\GAP} for MacOS runs under System X, however only
in Classic Mode. 

Note that, alternatively, you can run {\GAP} for UNIX version of
GAP in the Terminal window. However, you may need additional development 
software, available from Apple, to compile GAP yourself.
See "GAP for UNIX" for installation instructions.

The section "Copyright of GAP for MacOS" describes the copyright as it
applies to the executable version that we distribute. The section
"Installation of GAP for MacOS" describes how you install {\GAP} for
MacOS. 

Please refer to the relevant sections of Chapter "Running GAP" in the 
GAP reference manual (included with the {\GAP} distribution
for an overview over the features of {\GAP} for MacOS.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Copyright of GAP for MacOS}

In addition to the general copyright for {\GAP} set forth in the Copyright the 
following terms apply to {\GAP} for the Mac.

The system dependent part of {\GAP} for the Mac was written by Burkhard 
H{\accent127 o}fling (his email address is
\Mailto{b.hoefling@tu-bs.de}). He assigns
the copyright to the {\GAP} group. Many thanks to Burkhard for his help!
Burkhard H{\accent127 o}fling{\pif}s port was partly based on an earlier
port of {\GAP} for the Mac, 
which was done by Dave Bayer (\Mailto{dab@math.columbia.edu})
and used the 
Mac Programmers Workshop (MPW) compiler. Many thanks to Dave for his work. 
Moreover, the built-in editor is based upon the freeware text editor 
`PlainText' by Mel Park which, in turn, uses `TE32K', a `TextEdit' 
replacement by Roy Wood. It also uses `Internet Config'.

For technical reasons we do not distribute the Macintosh specific source and
project files as part of the standard archives. If you are interested in
compiling {\GAP} yourself, we are happy to provide you with the appropriate
files (contact us at \Mailto{gap-trouble@dcs.st-and.ac.uk}). The source can
be compiled with CodeWarrior Pro 5 with Apple's Universal Headers 3.3
installed.

Please contact the author
\Mailto{b.hoefling@tu-bs.de}
or \Mailto{gap-trouble@dcs.st-and.ac.uk} if you need further information.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installation of GAP for MacOS}

Installing {\GAP} under MacOS is fairly easy. First, decide into which 
folder you want to install {\GAP} 4.3.
{\GAP} will be installed in a subfolder `gap4r3' of this folder.
You can later move {\GAP} to a different location.

Note that certain parts of the output in the examples
should only be taken as rough outline, especially file sizes and file
dates are *not* to be taken literally.

If you encounter problems please also see section~"If Things Go Wrong" of
this document.

Get the Mac-specific files described  in  "Getting  GAP",  that  is,  the
distribution   `gapmac4r3.zoo',    the    binary    archive
`unzoo4r3-PPC.sit', the most recent bugfix, and the {\GAP} application  
program  (also
called *binary* or  *executable*).  The  {\GAP}  application  program  is
distributed     as     a     binary     archive.     It     is     called
`bin4r3-PPC.sit' if no  bugfixes  requiring  a  new  {\GAP}
application  have  been  issued  so  far.   Otherwise,   it   is   called
`bin4r3nX-PPC.sit', where `X' is the  number  of  the  last
bugfix. The latest {\GAP}  application  archive  is  available  from  the
{\GAP} distribution web page, or from the `mac' subdirectory of the `bin'
subdirectory on the ftp servers.

How you can get those
files is described in the section "Getting GAP". Remember that the
distribution consists of binary files and that you must transmit them in
binary mode. 

If the `sit' files did not extract automatically click on them to extract
them. If even this fails use one of the standard 
decompression utilities, such as `Stuffit Expander'.

After this process you should end up with two applications,
`GAP 4 PPC' and `unzoo 4.3 PPC'. 

The latter is used to uncompress the `.zoo' archives which contain most of 
{\GAP}. The `zoo' archives we provide for {\GAP} contain comments which indicate
whether files are text or binary files. The `unzoo' we provide uses these
comments. If you use another zoo extractor you might lose this information
and end up with files that contain text but cannot be opened as text files.

The following installation example assumes that you are installing {\GAP}
in the folder `Applications' on a PowerPC Macintosh. (For a 68k Macintosh 
you should replace all references to `PPC' to ones referring to `68K'

Move the file `gapmac4r3.zoo' into the folder `Applications'
and drag it onto the icon of `unzoo 4.3 PPC'. You will get many lines of 
output in this window. 

This should have created a folder `gap4r3' in the current folder.

(You will not need the file `gapmac4r3.zoo' any
longer. If you are short of disk space you can remove it now.)

If you got not the full distribution file but several small files, extract
all of them (*except the bug fixes and {\GAP} packages!*) in this way.

Move  `GAP 4 PPC' and the bugfix file (if there is one) in the folder 
`gap4r3'. Drag the bugfix file onto the icon of `unzoo 4.3 PPC'
to decompress it. 

If you got any {\GAP} packages, move them into the `pkg' folder in the folder 
folder `gap4r3' extract them there, in the same way as the bugfix.

Some {\GAP} packages are set up to load (or provide the documentation)
automatically. To enable this, after installing all the packages you think
you will need, you should list all the {\GAP} packages you have installed
in a file `ALLPKG' in the `pkg' directory (see Section~"Loading a GAP
Package" in the Reference Manual for details).

After extraction you may discard all `.zoo' files if you are short of disk 
space.

The folders `trans', `small' and `prim' contain data
libraries. If you are short of disk space you can erase some of them and
any {\GAP} package directories in the `pkg' directory that you don't need,
but then of course you will not be able to access these data and packages.
(Any {\GAP} package that has a C code component is essentially UNIX-dependent
and you may as well delete those; such packages typically describe in their
`README' files that they require `configure' and `make' to complete their
installation or have a `src' directory.)

Before you use {\GAP}, you should set up {\GAP}'s memory allocation, by 
setting appropriate values by selecting the {\GAP} application and 
`Get Info...' in the Finder's `File' menu (in order to be able to 
modify the values there, you have to do this *before* you launch {\GAP}). 

The maximum amount of workspace {\GAP} can use depends on the amount of 
memory the Finder allocates to {\GAP} when it is launched. The maximum 
amount of {\GAP} workspace is this value, minus a certain amount used 
internally by the {\GAP} application (for the PPC 
version, currently around 1.7 Megabytes, plus the size of the {\GAP} 
application if you do not use virtual memory, and 2.9 Megabytes for the 
68K version), minus any additional amount set with the `-a', `-P' or `-W'
command line options (see below).

You can find information about the amount of free {\GAP} workspace, the total
amount of available workspace, and the remaining free memory, 
by choosing `About GAP' in the `Apple' menu.

To ensure efficient operation, you should not allocate more memory to {\GAP}
than the amount of physical memory in your computer. 
If you are not using virtual memory, 
the amount may have to be considerably less (depending on your system and
the number of other applications which you may want to run at the same time).

If you notice heavy disk use during garbage collections, this is a clear 
indication that you have allocated too much memory to {\GAP}.

In order to test your installation now run the `GAP' application
by clicking on `GAP 4 PPC'.
You should get the {\GAP} banner and then the {\GAP} prompt in a window
titled `GAP log'. (The process of starting {\GAP} may take a while.)

Try a few things to see if the installation succeeded.

\begintt
gap> 2 * 3 + 4;
10
gap> Factorial( 30 );
265252859812191058636308480000000
gap> Size( SymmetricGroup( 10 ) );
3628800
gap> Factors( 10^42 + 1 );
[ 29, 101, 281, 9901, 226549, 121499449, 4458192223320340849 ]
gap> m11 := Group((1,2,3,4,5,6,7,8,9,10,11),(3,7,11,8)(4,10,5,6));;
gap> Size( m11 );
7920
gap> Factors( 7920 );
[ 2, 2, 2, 2, 3, 3, 5, 11 ]
gap> Length( ConjugacyClasses( m11 ) );
10 
\endtt

A set of test files is provided, running them all probably takes some 40
minutes on a 200 MHz PPC machine. As a quick test we start `combinat.tst' 
first.
Initially we must ensure that the print width of {\GAP} is 80 characters per
line which we achieve with the `SizeScreen' command (otherwise we will be
swamped with error messages).

\begintt
gap> SizeScreen([80,]);;
gap> Filename( DirectoriesLibrary("tst"), "combinat.tst" );
"./tst/combinat.tst"
gap> ReadTest(last);
+ $ld: combinat.tst,v 4.7 1997/11/21 10:19:47 ahulpke Exp $
+ GAP4stones: 27801
true
\endtt

Now use `Read' (*not* `ReadTest') to read the file `testall.g' to run
*all* available test files. This is not a necessary part of the
installation; it only serves as a confirmation that everything went
OK. The full test suite takes some time (almost 2 hours on a Pentium
III/500) and uses quite a bit of memory (around 100MB), so you may
wish to skip this step or run only part of the tests. This does no
harm.

You should not pay too much attention to the {\GAP}stone ratings of the
different files. The time measurements are not calibrated and sometimes vary
substantially because further tests have been added to a file.

\begintt
gap> Filename( DirectoriesLibrary("tst"), "testall.g" );
"./tst/testall.g"
gap> Read(last);
[lines omitted]
test file     GAP4stones   time(msec)
-------------------------------------------
unknown.tst      15238       21  (next ~ 0 sec)
listgen.tst      118000       5  (next ~ 0 sec)
gaussian.tst      2738      325  (next ~ 0 sec)
[further lines omitted]
\endtt

You can ignore warnings from `weakptr.tst', which stem from garbage
collections occurring at different times, and those from `grpconst.tst'
which stem from differences in available {\GAP} packages.

The information about the manual is system independent; you can find it in
section~"The Documentation".

*A few final reminders:*

\beginlist%unordered

\item{$\bullet$}
Make sure that you got and installed *the most recent* bugfix. 

\item{$\bullet$}
We would appreciate after installation your sending us a short note at
\Mailto{gap@dcs.st-and.ac.uk} 
(even if you have installed {\GAP} 3 before).
Generally, we do not reply to such emails; we only use them to gain some idea
of how many people use {\GAP} and of the machines/operating systems on which
{\GAP} has been successfully installed.

\item{$\bullet$}
We also suggest that you subscribe to our `gap-forum' mailing list; 
see the {\GAP} web pages for details. Whenever there is a bug fix or new
release of {\GAP} this is where it is announced. The `gap-forum' also
deals with user questions of a general nature; bug reports and other
problems you have while installing and/or using {\GAP} should be sent to
\Mailto{gap-trouble@dcs.st-and.ac.uk}.

\endlist

That's all, your installation should be complete. Please refer to
Chapter "Running GAP" in the GAP reference manual for a description
of some special features and options of {\GAP} for MacOS.

We hope that you will 
enjoy using {\GAP}. Remember, if you have problems, do not hesitate to
contact us at
\Mailto{gap-trouble@dcs.st-and.ac.uk}.
See Section~"If Things Go Wrong" for what to include in a bug report.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Testing for the System Architecture}

\>ARCH_IS_UNIX( ) F

tests whether {\GAP} is running on a UNIX system.

\>ARCH_IS_MAC( ) F

tests whether {\GAP} is running on a Macintosh under MacOS

\>ARCH_IS_WINDOWS( ) F

tests whether {\GAP} is running on a Windows system.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Porting GAP}

Porting {\GAP} to a new operating system should not be very difficult.
However, {\GAP} expects some features from the operating system and the
compiler and porting {\GAP} to a system or with a compiler that do not
have those features may prove very difficult.

The design of {\GAP} makes it quite portable. {\GAP} consists of a small
kernel written in the programming language C and a large library written
in the programming language provided by the {\GAP} kernel, which is also
called {\GAP}.

Once the kernel has been ported, the library poses no additional problem,
because all those functions only need the kernel to work, they need no
additional support from the environment.

The kernel itself is separated into a large part that is largely
operating system and compiler independent, and one file that contains all
the operating system and compiler dependent functions. Usually only this
file must be modified to port {\GAP} to a new operating system.

Now let us take a look at the minimal support that {\GAP} needs from the
operating system and the machine:

You need enough main memory in your computer. The size of the
{\GAP} kernel varies between 1.5 and 2.5 MByte (depending on the machine).
The {\GAP} library additionally takes a minimum of 10MByte and the
library of functions that {\GAP} loads takes up another 1.5 MByte. So it
is clear that at least 16 MByte of main memory are required to do any
serious work with {\GAP}.

Additionally, the {\GAP} kernel needs a flat address space, that is all the
memory is available in one contiguous chunk.

Note that this implies that there is no point in trying to port {\GAP} to
plain MS-DOS running on IBM PCs and compatibles. The version of {\GAP}
for IBM PC compatibles that we provide runs on machines with the
Intel 80486, Pentium or beyond processor under 32-bit Windows.
(This is also necessary, because, as just mentioned, {\GAP} wants to view its 
memory as a large flat address space.)

Next let us turn to the requirements for the C compiler and its library.

As was already mentioned, the {\GAP} kernel is written in the C language.
We have tried to use as few features of the C language as possible.
{\GAP} has been compiled without problems with compilers that adhere to
the old definition from Kernighan and Ritchie, and with compilers that
adhere to the new definition from the ANSI-C standard.

Porting {\GAP} to another UNIX should not be hard. You need some
very basic understanding of C and UNIX.
If you plan to port {\GAP} to a non-UNIX system please contact
\Mailto{gap-trouble@dcs.st-and.ac.uk}.

The configuration script runs various tests to determine the configuration
of your system. It produces a file `bin/<architecture>/config.h' which
contains definitions according to the test results.
It might be, however, that the tests used don't produce on
your machine the results they are expected to or that further tests are
necessary. If this is the case the easiest way is to edit the `config.h'
script, remove all object files and call `make' in the `bin/<architecture>'
subdirectory. If you have to resort to changing or amending this file,
please tell us what had to be changed (mail to
\Mailto{gap-trouble@dcs.st-and.ac.uk}). If you had to add further definitions
please also tell what properties of your system these `define's represent.

If {\GAP} compiles but crashes while reading the library or during a garbage
collection with a bus error it is possible that the configuration script did
not guess the permitted pointer alignment correctly. This value is stored
in the line
\begintt
#define C_STACK_ALIGN      2
\endtt
of `config.h'. Increase the value to the next power of 2  ($\le  8$)  and
compile {\GAP} anew.

There is still a `Makefile' in the `src' directory, but it is not used by
the configuration process any longer. As a last resort you might want  to
try this file, but please still report your problems to `gap-trouble'.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The Documentation}

The {\GAP} manual is  distributed  in  various  ``books''.  The  standard
distribution contains four of them (as well as  a  comprehensive  index).
{\GAP}  packages  (see  Chapter~"GAP  Packages"  and,   in   particular,
Section~"Loading a GAP Package") provide  their  own  documentation  in
their own `doc' directories.

All documentation will be available automatically  for  the  online  help
(see Section~"Tut:Help" in the Tutorial and Chapter~"The Help System"  in
this manual for more details).

There also  is (if  installed) an  HTML version  of some  books that  can be
viewed with an  HTML browser, see~"Changing the Help Viewer".  Some of these
use  *symbol  fonts*  for  mathematical  formulae.  To  get  them  correctly
displayed (only in  a browser which uses a graphical  display), you may want
to adjust the font setup for your browser. See~"HTML Font Setup" below for a
hint.

The manual is also available in `dvi' and `pdf' format.
In the full UNIX
distribution (`gap4r3.zoo') these files are included in the
directory
`gap4r3/doc'  in the
subdirectories  `tut' (a  beginner{\pif}s  tutorial),  `ref' (the  reference
manual),  `prg' (programmer{\pif}s  tutorial), `ext'  (programmer{\pif}s
reference) and `new' (new material that might still change in future versions).

If you downloaded another distribution file, you can get the missing `dvi' 
(resp.~`pdf') files by downloading the archive `docdvi4r3.zoo'
(resp.~`docpdf4r3.zoo') from the same place you got {\GAP}.

If  you want  to  use these manual files  with  the online  help you  may
check (or  make sure)  that  your  system  provides some  additional
software  like

\beginitems

`xpdf'&
see  \URL{http://www.foolabs.com/xpdf/}

`xdvi'&
see any of the CTAN  sites/mirrors; the main site is:
\URL{http://www.ctan.org/}

&
and the mirrors are listed at:
\URL{http://www.ctan.org/tex-archive/CTAN.sites}

&
At any of the mirrors the path of the file containing the `xdvi' archive
(after the main site name) is
`tex-archive/dviware/xdvi/xdvi.tar.gz'.

`acroread'&
see \URL{http://www.adobe.com/products/acrobat/readstep.html}

\enditems

As  a complete  beginner, we  suggest  you read  the tutorial  first for  an
introduction to {\GAP} 4. Then start to use the system with extensive use of
the  online  help  system  (see  Section~"Tut:Help"  in  the  Tutorial   and
Chapter~"The Help System" in this manual).

If you  have experience with  {\GAP} 3, it might  be still worthwhile  to at
least glance  over the first  chapters of  the tutorial. You  however should
read the last  chapter of the tutorial, ``Migrating to  GAP4''. This chapter
gives a summary  of changes between {\GAP}  3 and {\GAP} 4  that will affect
the user. It also explains a ``compatibility  mode'' you may turn on to make
{\GAP} 4 behave a bit more like {\GAP} 3.

As some  of the manuals  are quite large,  you should not  immediately print
them. If  you start using  {\GAP} it will be  helpful to print  the tutorial
(and  probably the  first chapters  of the  reference manual).  There is  no
compelling reason to print the whole of the reference manual, better use the
online help which provides useful search features.
%%     I don't agree, it is much better to learn to use the online help! (FL)
%%  
%%  We also recommend to print the full index to the manuals to be found in
%%  `gap4r3/doc/fullindex.dvi'.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{HTML Font Setup}

The HTML pages of the manual use the `symbol' font to display non-latin
symbols in mathematical formulae. This font might not be enabled by default
on your browser. The documentation of the `tth' converter we use 
\URL{http://hutchinson.belmont.ma.us/tth/Xfonts.html}

describes how to set up this font for use in Netscape or Konqueror. For
Netscape on UNIX, essentially you want:

\begintt
Netscape*documentFonts.charset*adobe-fontspecific:   iso-8859-1
\endtt

in your `.Xresources' or `.Xdefaults' file. 

A good test to see if you need this remedy is to check the display of:
$\{1,\dots,n\}$; if you see an ellipsis (three dots) between the commas,
you are ok, and if you see `1/4' you need the remedy!

If you have problems viewing symbol fonts on the Mac, you may have 
to choose Mac font encoding, sometimes called MacRoman, or Western (Mac).
More information about the font setup on Macintoshes can be found 
\URL{http://hutchinson.belmont.ma.us/tth/manual/sec12.html},
Section 12.3.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{If Things Go Wrong}

\index{problems}
\atindex{FAQ}{@FAQ}

This section lists a few common problems when installing or running {\GAP}
and their remedies. Also see the FAQ list on the {\GAP} web pages at
\URL{http://www.gap-system.org/Info/faq.html}

\beginitems
{\GAP} starts with a warning ``{`hmm, I cannot find {'}lib/init.g{'}'}''.&
You either started only the binary or did not edit the shell script/batch
file to give the correct library path. 
You must start the binary with the command line option
`-l '<path> where <path> is the path to the {\GAP} home directory. See
section~"Command Line Options" in the reference manual.

When starting, {\GAP} produces error messages about undefined variables.&
You might have a `.gaprc' file that was intended for \GAP~3 but is not
compatible with \GAP~4. See section~"The .gaprc file" in chapter~"Running
GAP" of the reference manual.

{\GAP} stops with an error message: ``{`cannot extend the workspace any more'}''.&
Your calculation exceeded the available memory. Most likely you asked {\GAP}
to do something which required more memory than you have (as listing all
elements of $S_{15}$ for example). You can use the command line option `-g'
(see section~"Command Line Options" in the reference manual) to display how
much memory {\GAP} uses. If this is below what your machine has available
(this happens for example under Windows) extending the workspace is
impossible. Start {\GAP} with more memory or use the `-a' option to 
pre-allocate initially a large piece of workspace.

{\GAP} complains: ``{`corrupted completion file'}''.&
Some library files got changed without rebuilding the completion files.
This is often a sign that earlier a bugfix was not installed properly or
that you changed the library yourself. In the latter case,
start {\GAP} with command line option `-N' and see section~"Completion Files".

{\GAP} stops with an error message ``{`exceeded the permitted memory'}''.&
Your job got bigger than what is permitted by default (128MB). (This is a
safety feature to avoid single jobs wrecking a multi-user system.) You can
type `return;' to continue, if the error message happens repeatedly you
better start the job anew and use the command line option `-o' to set a
higher memory limit.

`make' complains about not being able to find files in `cnf' or `src' which exist.&
The dates of the new files were not extracted properly (Alpha-OSF machines
are prone to this). Call
\begintt
touch * cnf/* src/*
\endtt
from the main {\GAP} directory (this ought to reset the date of all relevant
files to ``now'') and try again.

Recompilation does not actually compile changed files.&
The dates of the new files were not extracted properly. Go in the source
directory and `touch' (UNIX command to change date) the new files.

Recompilation fails or the new binary crashes.&
Call `make clean' and restart the `configure' / `make' process completely
from scratch. (It is possible that the operating system and/or compiler got
upgraded in the meantime and so the existing `.o' files cannot be used any
longer.

A calculation runs into an error ``no method found''.&
{\GAP} is not able to execute a certain operation with the given arguments.
Besides the possibility of bugs in the library this means two things: Either
{\GAP} truly is incapable of coping with this task (the objects might be
too complicated for the existing algorithms or there might be no algorithm
that can cope with the input). Another possibility is that {\GAP} does not
*know* that the objects have certain nice properties (like being finite)
which are required for the available algorithms. See
sections~"ApplicableMethod" and "KnownPropertiesOfObject".
\enditems

*Problems specific to Windows*
\beginitems
The `gap.bat' file does not start GAP.&
Make sure you ran `instwin.bat'. If your version
of Windows uses a language other than English you must still edit the
resulting file `gap.bat' in the `bin' subdirectory, due to a misdesign of
Windows. If the path name contains long file names or blanks, you might have
to edit the file to rectify the `-l' argument or to enclose it by
apostrophes.

Windows complains `Out of environment space'.&
Click the batch file `instwin.bat' or `gap.bat' which caused the problem
with the right mouse button and select `Properties',`Memory' and increase
the initial environment space to at least 1024. This will create a `pif'
shortcut which should be used to start {\GAP}.

Command line editing does not work under Windows.&
The default key commands are UNIX-like. {\GAP} also tries to emulate some of
the special keys under Windows, however if the key repeat is set too high,
Windows loses parts of the codes for these keys and thus {\GAP} cannot
recognize them.
Windows98 produces the same scan code for all cursor keys. As {\GAP} does
not interface directly with the Windows machinery, there is no way around
this problem so far.

The `^'-key cannot be entered.&
This is a problem if you are running a keyboard driver for some non-english
languages. These drivers catch the `^' character to produce the French
circumflex accent and do not pass it properly to {\GAP}.
No fix is known.

Cut and Paste does not work&
See \URL{http://www.gap-system.org/Info4/windows.html}
for a remedy.
\enditems

\indextt{gap-trouble!email address}
\atindex{bug reports!see If Things Go Wrong}%
{@bug reports!see If Things Go Wrong}
*If all these remedies fail* or you encountered a bug please send a mail to
\Mailto{gap-trouble@dcs.st-and.ac.uk}. Please give:

\beginlist%unordered
\item{$\bullet$} a (short, if possible) self-contained excerpt of a {\GAP}
session containing both input and output that illustrates your problem 
(including comments of why you think it is a bug); and

\item{$\bullet$} state the type of machine, operating system,
(compiler used, if UNIX/Linux) and version of {\GAP} (for example
``gap4r3, fix1'') you are using
(the line after the {\GAP}~4 banner starting:
\begintt
GAP4, Version: 4...
\endtt
when your {\GAP}~4 starts up, supplies the information required).
\endlist
