Math Solutions 1995 October/Math_Solutions_CD-ROM_Walnut_Creek_October_1995.iso/pc/mac/discrete/doc/install.tex

Text File | 1993-05-05 | 109.4 KB | 2,365 lines

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  install.tex                 GAP documentation            Martin Schoenert
%%
%A  @(#)$Id: install.tex,v 3.14 1993/02/19 11:30:42 gap Exp $
%%
%Y  Copyright 1990-1992,  Lehrstuhl D fuer Mathematik,  RWTH Aachen,  Germany
%%
%%  This file describes the installation and features of \GAP\ on various OS.
%%
%%  Currently only UNIX  and TOS on the   Atari ST are supported.   Hopefully
%%  more systems will follow soon, especially DOS on 386PC and the Macintosh.
%%
%%  To read about the  system you are   interested in, search for  the string
%%  'Section{<system>}', e.g., 'Section{UNIX}' or 'Section{Atari ST}'.
%%
%H  $Log: install.tex,v $
%H  Revision 3.14  1993/02/19  11:30:42  gap
%H  removed overfull hboxes
%H
%H  Revision 3.13  1993/02/19  10:48:42  gap
%H  adjustments in line length and spelling
%H
%H  Revision 3.12  1993/02/18  07:55:21  felsch
%H  some misprints removed
%H
%H  Revision 3.11  1993/02/17  15:07:32  felsch
%H  example fixed
%H
%H  Revision 3.10  1993/02/16  15:06:04  fceller
%H  fixed example, changed description of 'gapexe.next'
%H
%H  Revision 3.9  1993/02/11  15:51:53  martin
%H  updated for 3.2
%H
%H  Revision 3.8  1992/05/25  18:09:39  martin
%H  added "Upgrading GAP"
%H
%H  Revision 3.7  1992/05/22  08:58:45  martin
%H  added the sections for IBM PC compatibles
%H
%H  Revision 3.6  1992/04/09  11:36:01  martin
%H  made a few changes so that two LaTeX passes suffice
%H
%H  Revision 3.5  1992/04/07  22:48:42  martin
%H  fixed the examples
%H
%H  Revision 3.4  1992/04/02  18:03:40  martin
%H  added the banner
%H
%H  Revision 3.3  1992/03/25  15:49:27  martin
%H  changed the output of 'ls <gap-dir>/doc'
%H
%H  Revision 3.2  1992/03/23  12:37:54  martin
%H  added "Getting GAP"
%H
%H  Revision 3.1  1992/03/23  11:58:51  martin
%H  improved the installation sections
%H
%H  Revision 3.0  1991/12/27  16:10:27  martin
%H  initial revision under RCS
%H
%%
\Chapter{Getting and 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 "UNIX", "Installation
under  UNIX", "Features under UNIX"), which  runs on  an ever  increasing
number  of machines, for  *MS-DOS*, which is the operating system on *IBM
PC compatibles* (see "IBM PC Compatibles", "Copyright  of GAP  for IBM PC
Compatibles", "Installation on  IBM PC Compatibles", "Features on  IBM PC
Compatibles"), and *TOS*, which is the operating system of the *Atari ST*
(see "Atari  ST", "Installation on the Atari ST", "Features  on the Atari
ST").

When you port {\GAP} to a new machine we would like to hear  about it, so
that we can make this new port  available  to others.  We are  especially
interested in ports to the Macintosh, and to VMS on DEC VAX systems.  The
section "Porting GAP" gives hints how to approach such a port.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Getting GAP}%
\index{ftp}

{\GAP}  is distributed *free of charge*.  You can obtain it via 'ftp'  or
electronic mail  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 '[e-mail]',
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.  Again we would appreciate if
you could inform us about such a paper.

We  distribute  the *full source*  for everything, the  C  code  for  the
kernel, the {\GAP}  code for the library, and  the {\LaTeX}  code for the
manual, which has at present about 800 pages.  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.  We already have ports
for IBM PC compatibles with an Intel 80386 or 80486 and for the Atari ST.
We also hope to provide a port  of {\GAP} 3.2  to  the Apple Macintosh in
the near future (there is already a port of {\GAP} 3.1).  Note that about
4 MByte of main memory and a harddisk are required to run {\GAP}.

{\GAP} 3.2 can be obtained by anonymous *ftp* from the following servers.

'samson.math.rwth-aachen.de':\\
        Lehrstuhl D fur Mathematik, RWTH Aachen, Germany.\\
        (Internet number 137.226.152.6)

'dimacs.rutgers.edu':\\
        DIMACS, Rutgers, New Brunswick, New Jersey.\\
        (Internet number 128.6.75.16)

'math.ucla.edu':\\
        Math. Dept., Univ. of California at Los Angeles.\\
        (Internet number 128.97.4.254)

'wuarchive.wustl.edu':\\
        Mathematics Archives, Univ. of Tennessee.\\
        (Internet number 128.252.135.4) \\
        (directory '/edu/math/source.code/group.theory/gap')

'pell.anu.edu.au':\\
        Math. Dept., Australian National Univ., Canberra.\\
        (Internet number 150.203.15.5)

'ftp' to the server *closest* to  you, login  as user 'ftp' and give your
full e-mail address as password.  {\GAP} is  in the directory  'pub/gap'.
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.

{\GAP}  can also be obtained via  *electronic mail*.   To get one of  the
files  below, send  a  message  to  '[e-mail]'
containing  a line 'get  GAP <file-name>', e.g., 'get GAP  src3r2.tar.Z'.
'listserv' will reply by sending you the file as e-mail message.

Because most files are  large  binary files they will  be  uuencoded  and
split into  several parts,  each   at  most 64  kBytes  large.   You  can
concatenate  the parts  by hand,  removing the mail  header, and then use
'uudecode' to decode them.  We suggest however that you also get 'uud.c',
which skips  the  mail headers automatically  and  is also able to fix up
transmission errors caused by 'EBCDIC' machines.  You can also get single
parts of a file by sending 'get GAP <file-name> <part-nr>'.

For users in the United Kingdom with only Janet access, neither 'ftp' nor
the mail server will work (please do *not*  try to  use the mail server).
Please contact Derek Holt (e-mail address '[e-mail]').  He
has kindly offered us to distribute GAP in the United Kingdom.

The 'ftp'  directory and  the 'listserv' archive   contain  the following
files.  Please check first  which files you  need, to  avoid transferring
those that you don\'t need.

'README':\\
        the announcement for {\GAP}.

{\GAP} version 3  release 2 itself comes in  several  files.  You  do not
need all of those files.  All files are 'compress'-ed 'tar' archives.

'src3r2.tar.Z':\\
        the *source code* for the {\GAP} kernel.  You need it  unless you
        get one of the executables below.  This  file is about 750 KBytes
        long.

'lib3r2.tar.Z':\\
        the  *library of functions*.  You need this.   This file is about
        1000 KBytes long.

'doc3r2.tar.Z':\\
        the *documentation*.   Serves  as  LaTeX  source for  the printed
        manual and  online documentations.  This file is about 850 KBytes
        long.

'doc3r2.dvi.Z':\\
        the preformatted documentation.  You need this if you do not have
        a *big* TeX.  This file is about 1100 KByte long.

'grp3r2.tar.Z':\\
        various  *group  libraries*.  Contains for example all  primitive
        permutation groups of  degree at most 50.  This file is about  50
        KByte long.

'two3r2.tar.Z':\\
        the library of *2-groups* of size  at  most  256.  This  file  is
        about 650 KByte long.

'thr3r2.tar.Z':\\
        the library of *3-groups* of size  at  most  729.  This  file  is
        about 20 KByte long.

'tbl3r2.tar.Z':\\
        a library of *character tables* including all of the ATLAS.  This
        file is about 2050 KByte long.

'tom3r2.tar.Z':\\
        a library of *table of marks* of  various groups.  This  file  is
        about 450 KByte long.

'anupq.tar.Z':\\
        the *ANU PQ* share library package.  This file is about 350 KByte
        long.

'nq.tar.Z':\\
        the *NQ*  share  library  package.  This  file is about 100 KByte
        long.

'weyl.tar.Z':\\
        the *Weyl* share library package.  This  file  is about  50 KByte
        long.

'src3r2.zoo', 'lib3r2.zoo', 'doc3r2.zoo', 'grp3r2.zoo', \\
'two3r2.zoo', 'thr3r2.zoo', 'tbl3r2.zoo', 'tom3r2.zoo', \\
'anupq.zoo',  'nq.zoo',     'weyl.zoo':\\
        'zoo'  archives  containing  *exactly*  the  same  files  as  the
        'compress'-ed   'tar'   archives   above.    The   advantage   of
        'compress'-ed  'tar' archives is that 'uncompress' and 'tar'  are
        widely  available  on  UNIX  systems.   The  advantage  of  'zoo'
        archives  is that  they are smaller (about  30 percent)  and that
        'zoo' is more common on PC-s and  Atari ST-s.  (These  files  may
        not be available on all servers.)

We supply executables for machines  that  don\'t usually come  with  a  C
compiler  or  machines  where  the  standard C compiler does  not produce
optimal results.  If you have one of those machines it will be easier for
you  to get this executable  instead of compiling  {\GAP}  yourself.  The
following  executables  are  available  (again these  files  may  not  be
available on all servers)

'gapexe.386':\\
        executable for IBM  PC  compatibles with  an Intel 80386 or 80486
        running  MS-DOS 5.0 compiled with the GNU C  2.2.2 compiler.  See
        below for the copyright.  This file is about 500 KByte long.

'gapexe.next':\\
        executable for  the  NeXT (680?0)  running  NeXTstep 3.0 compiled
        with GNU C compiler 2.3.3.  This file is about 400 KByte long.

'gapexe.st':\\
        executable for Atari ST (680?0) running TOS compiled with the GNU
        C compiler.  This file is about 450 KByte long.

'gapexe.su3':\\
        executable for SUN 3 (680?0) running SunOS 4.0 or higher compiled
        with SunOS C.  This file is about 500 KByte long.

'gapexe.su4':\\
        executable for SUN 4 (Sparc) running SunOS 4.1 or higher compiled
        with GNU C 2.3.2 compiler.  This file is about 600 KByte long.

The following support files are also available (and again these files may
not be available on all servers)

'compress.tar':\\
        'compress' version 4.1.  You need  this program to uncompress the
        compressed tar files.  Note however, that almost all UNIX systems
        these days already come with an executable 'compress'.  This file
        is about 40 KByte long.

'patch.tar.Z':\\
        Larry Wall\'s 'patch' program version 2.0.2.0 (patchlevel  12u4).
        This program can be used  to automatically apply  upgrades.  Note
        that older versions  of 'patch' are *not* able to understand  the
        unified 'diff'  format  used in the  upgrade files.  This file is
        about 70 KByte long.

'uud.c':\\
        'uud' version 3.4.  'uud' is much better than the 'uudecode' that
        comes with most UNIX systems.  This file is about 12 KByte long.

'zoo21.tar.Z':\\
        Rahul Dhesi\'s 'zoo' archiver  version  2.1.   You  need  this to
        unpack the *zoo-archives*.  Note that the widespread version 2.01
        will *not* work.  This file is about 240 KByte long.

'zooexe.386':\\
        Executable of 'zoo' for  IBM PC  compatibles.  This file is about
        55 KByte long.

'zooexe.st':\\
        Executable of  'zoo' for the  Atari  ST.  This  file is  about 80
        KByte long.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Upgrading GAP}

From time  to  time we  will  *upgrade* {\GAP}.  There  are generally two
types of  upgrades.  The  major  upgrades create  new  *releases* and the
minor  are upgrades between releases.  New releases usually introduce new
features while upgrades  between releases  usually only fix bugs found in
one release.

Each version  has  a  number.  The number of  a  release consists of  two
parts.  The first  part is  the  *version number*,  which is currently 3.
The  second part  is  the *release  number*,  which  is  1 for  the first
release, 2 for  the second, and so on.  The current number is  *version 3
release  1*, which we  sometimes abbreviate  to  'V3R1'.  The number of a
upgrade between releases consists of three  parts.  The first and  second
part are the  version and release  number  of  the  current release.  The
third part is called the *patchlevel*.  The first upgrade after a release
has patchlevel 1, the second patchlevel 2, and so on.  The current number
is *version 3 release  2 patchlevel 0*, which we sometimes abbreviate  to
'V3R2P0'.

Because it would be too much work for us to put the complete distribution
(which currently is about 6  MByte  for the  'compress'-ed 'tar' archives
alone)  on the 'ftp' servers for every upgrade, and also because it would
be  a lot of  work  for you to obtain the complete distribution for every
upgrade, we  only make  the differences between  one upgrade and the next
one available.  They  are  stored in  a  single  file, called an *upgrade
file*.  For example the  differences  between  'V3R1P1' and  'V3R1P2' are
stored  in a file called 'upg3r1p2.dif'  (actually this  file  is  stored
'compress'-ed   on   the   'ftp'   servers,   so   its   true   name   is
'upg3r1p2.dif.Z').

Note that upgrade files always take you from one version to the next.  So
to upgrade to  'V3R1P2'  you  must first  upgrade  to 'V3R1P1'.  Also the
upgrade to a new release will be relative to the latest patchlevel of the
previous release.   So to  upgrade to 'V3R2' you must  first  upgrade  to
'V3R1P2', or whatever will be the latest patchlevel of the first release.

Note also  that we will provide new executables  only  for  new releases.
That  means that  currently the  executables  we  provide  are those  for
'V3R1', not those for 'V3R1P2'.  So  for  example, to get  the executable
for  'V3R1P2'  for the Atari ST, you must get the sources for the kernel,
upgrade  them, and compile  them yourself.  Note  however, that  upgrades
between releases will only fix bugs, of which we  hope there will  not be
too many in the kernel.  That means that it should be possible to use the
executables  even  with the  upgraded library.  The  same holds  for  the
preformatted documentation ('doc3r1.dvi.Z').

To make it easier for you to apply an upgrade, the upgrade files are in a
special format, called (unified) 'diff', which a  special program, called
'patch',  can   understand.    'patch'   reads   the   upgrade  file  and
automatically makes all the necessary changes to the files.  This program
is  available on  most UNIX machines.  However, we also make it available
on the 'ftp' servers, so  you can get it from there  if your machine does
not have one or if your machine  has one  that is  too  old to understand
unified 'diff'-s.

To apply an upgrade you need the sources for the parts of {\GAP} that you
are interested in.  This should at least be the sources, the library, and
the documentation.  You may also have  the groups  library, the primitive
groups library,  the 2-groups library, and  the character table  library.
If  an upgrade changes  a file in one of the  parts that you do not have,
'patch'  will ask you about the file it  cannot find.  Then  you can tell
'patch' to ignore this change, and it will continue to change those files
it can find.

In  the following example,  we assume that  you (as user 'you') have  all
parts of {\GAP}, that {\GAP}  is installed in  the subdirectory 'gap/' of
your homedirectory, and that you want to upgrade from 'V3R1' to 'V3R1P1'.

The first thing  of course is to get the upgrade file.  The upgrade files
are available at  the  same  places as the rest  of {\GAP} (see  "Getting
GAP").  If you are subscribed to the  {\GAP}-forum, you will also get the
upgrade  files as  e-mail messages.   In this example we will assume that
you have obtained the upgrade file 'upg3r1p1.dif.Z' from one of the 'ftp'
servers.

|    you@ernie:~/gap > ls -l
    drwxr-xr-x  2 you          1536 May 25 18:03 doc
    drwxr-xr-x  2 you           512 May 25 18:03 grp
    drwxr-xr-x  2 you          1536 May 25 18:02 lib
    drwxr-xr-x  2 you          1536 May 25 18:01 src
    drwxr-xr-x  2 you          1536 May 25 18:04 tbl
    drwxr-xr-x  2 you          1024 May 25 18:04 two
    -rw-r--r--  1 you         45866 May 25 18:04 upg3r1p1.dif.Z
    you@ernie:~/gap > |

Next 'uncompress' the upgrade file with the following command.

|    you@ernie:~/gap > uncompress upg3r1p1.dif
    you@ernie:~/gap > ls -l upg3r1p1.dif
    -rw-r--r--  1 you        123695 May 25 18:04 upg3r1p1.dif
    you@ernie:~/gap > |

The first thing that you should do is always to read the beginning of the
upgrade file.  It contains instructions on how to apply the upgrade.  You
should always read this  to see if there are special  things that must be
done before  this  upgrade can be applied.  For  example, before  you can
apply the upgrade from 'V3R1P1' to 'V3R1P2' you must first make a copy of
the file  'src/system.st'.  In our example, i.e., the upgrade from 'V3R1'
to 'V3R1P1' no special tasks must be performed.

Now you apply the upgrade with the following command.

|    you@ernie:~/gap > patch -p0 < upg3r1p1.dif
    Hmm...  Looks like a unified diff to me...
    The text leading up to this was:
    --------------------------
    !What is this file?
    !==================

    # 'patch' prints the introduction text, about 200 lines long

    !Now for the upgrade itself
    !==========================
    !
    !diff -u doc/aboutgap.tex doc/aboutgap.tex
    !--- doc/aboutgap.tex   Thu Apr  9 14:06:31 1992
    !+++ doc/aboutgap.tex   Thu Apr 30 14:38:06 1992
    --------------------------
    Patching file doc/aboutgap.tex using Plan A...
    Hunk |'\#'|1 succeeded at 6.
    Hunk |'\#'|2 succeeded at 13.
    Hunk |'\#'|3 succeeded at 493.
    Hunk |'\#'|4 succeeded at 529.
    Hunk |'\#'|5 succeeded at 1074.
    Hunk |'\#'|6 succeeded at 5168.
    Hmm...  The next patch looks like a unified diff to me...
    The text leading up to this was:
    --------------------------
    !diff -u doc/aggroup.tex doc/aggroup.tex
    !--- doc/aggroup.tex    Thu Apr  9 14:06:33 1992
    !+++ doc/aggroup.tex    Thu Apr 30 14:20:05 1992
    --------------------------
    Patching file doc/aggroup.tex using Plan A...
    Hunk |'\#'|1 succeeded at 2.
    Hunk |'\#'|2 succeeded at 10.
    Hunk |'\#'|3 succeeded at 336.
    Hunk |'\#'|4 succeeded at 2708.

    # similar output for 70 more files, about 700 lines

    Hmm...  The next patch looks like a unified diff to me...
    The text leading up to this was:
    --------------------------
    !diff -u src/word.h src/word.h
    !--- src/word.h Fri Apr  3 20:56:34 1992
    !+++ src/word.h Wed Apr 29 13:28:43 1992
    --------------------------
    Patching file src/word.h using Plan A...
    Hunk |'\#'|1 succeeded at 3.
    done
    you@ernie:~/gap > |

See below about the  things that  could go wrong.  For the moment we will
assume that everything worked, i.e., that 'patch' did not complain.

Next compile the  source  of  the  kernel again.   How  this  is  done is
described in  the installation sections (see "Installation under  UNIX").
Note that it may not be necessary to do this if the source of  the kernel
did not  change, or if the changes were only  cosmetic.  The introduction
of the upgrade file will tell you if it is really necessary or not.

Then  {\LaTeX}  the  documentation  again.   How this  is  done  is  also
described in  the  installation  sections (see "Installation under UNIX",
"Installation on IBM PC Compatibles",  "Installation  on  the Atari ST").
Again this may not be necessary,  if the changes to the manual were  only
minor.  Again the introduction of the upgrade file will tell you if it is
really necessary or not.

Now you may want to throw away the original files.  'patch' saves them by
appending the suffix '.orig' to the original file name.  So to remove all
original files issue the following command.

|    you@ernie:~/gap > rm -f */*.orig
    you@ernie:~/gap > |

There are several things that can go wrong.

The first possibility is that you don\'t  have 'patch'.  In this case get
'patch', for example by anonymous 'ftp' from 'samson.math.rwth-aachen.de'
(Internet number 137.226.152.6).

Another possibility is that  you  have a version  of 'patch' that  is too
old.   Versions  of  'patch'  before  2.0.2.0  (patchlevel  12u4)  don\'t
understand the unified 'diff' format of this upgrade file.  In this  case
you will see the following message.

|    you@ernie:~/gap > patch -p0 < upg3r1.dif
    Hmm...  I can't seem to find a patch in there anywhere.
    you@ernie:~/gap > |

To solve this problem, get a newer version of 'patch'.   For  example  by
anonymous 'ftp' from 'samson.math.rwth-aachen.de'.

Another possibility is that you forgot the '-p0' option for 'patch'.   In
this case 'patch' assumes  that the files to patch are all in the current
directory (not in the subdirectories 'doc', 'grp', etc.).  It can\'t find
them there of course.  Therefore it asks you for the names  of  the files
to patch interactively.

|    you@ernie:~/gap > patch -p0 < upg3r1p1.dif
    Hmm...  Looks like a unified diff to me...
    The text leading up to this was:
    --------------------------
    !What is this file?
    !==================

    # 'patch' prints the introduction text, about 200 lines long

    !Now for the upgrade itself
    !==========================
    !
    !diff -u doc/aboutgap.tex doc/aboutgap.tex
    !--- doc/aboutgap.tex   Thu Apr  9 14:06:31 1992
    !+++ doc/aboutgap.tex   Thu Apr 30 14:38:06 1992
    --------------------------
    File to patch: |

Stop 'patch' by hitting <ctr>-'C', and  start it anew, this time with the
option '-p0'.

Another possibility is that you already  changed a file.  For  example if
you already changed 'word.c', which could not be  compiled with GNU cc on
the NeXT, you will get  the  following  message (note  the  message  that
hunk '\#3' failed).

|    you@ernie:~/gap > patch -p0 < upg3r1p1.dif

    # the usual output from 'patch'

    Hmm...  The next patch looks like a unified diff to me...
    The text leading up to this was:
    --------------------------
    !diff -u src/word.c src/word.c
    !--- src/word.c Sun Apr  5 23:29:44 1992
    !+++ src/word.c Wed Apr 29 13:28:43 1992
    --------------------------
    Patching file src/word.c using Plan A...
    Hunk |'\#'|1 succeeded at 3.
    Hunk |'\#'|2 succeeded at 10.
    Hunk |'\#'|3 failed at 2094.
    Hunk |'\#'|4 succeeded at 2218.
    Hunk |'\#'|5 succeeded at 2469.
    1 out of 5 hunks failed--saving rejects to src/word.c.rej

    # the rest of the output from 'patch'

    you@ernie:~/gap > |

In this case examine the '\*.rej' files  carefully after running 'patch'.
They will tell you what 'patch' expected to find in the file, and what it
really  found.   Then  examine the  source file itself to see if  you can
ignore the rejection, or if you should apply the patch manually.

Another  possibility is that 'patch'  cannot  find the  files  it  should
patch.   For example,  if you  don\'t have  the  groups library installed
'patch' will give the following output.

|    you@ernie:~/gap > patch -p0 < upg3r1p1.dif

    # the usual output from 'patch'

    Hmm...  The next patch looks like a unified diff to me...
    The text leading up to this was:
    --------------------------
    !diff -u grp/permgrp.grp grp/permgrp.grp
    !--- grp/permgrp.grp  Tue Apr  7 22:39:12 1992
    !+++ grp/permgrp.grp  Thu Apr 30 13:14:12 1992
    --------------------------
    File to patch: |

Simply type <return> to this question.  'patch' will ask you then.

|    No file found--skip this patch? [n] |

Answer with 'y<return>', i.e., tell 'patch' to ignore this file.  'patch'
will then show the following output.

|    Skipping patch...
    Hunk |'\#'|1 ignored at 2.
    Hunk |'\#'|2 ignored at 9.
    Hunk |'\#'|3 ignored at 83.
    3 out of 3 hunks ignored--saving rejects to grp/permgrp.grp.rej
    patch: can't create grp/permgrp.grp.rej,
           output is in /tmp/patchra22700. |

Then it will continue to apply the other patches.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{UNIX}%
\index{BSD}\index{4.2BSD}\index{4.3BSD}\index{ULTRIX}%
\index{System V}\index{SysV}\index{HP-UX}\index{SunOS}%

{\GAP} runs very well under UNIX.  In fact  it is being developed on UNIX
workstations.   {\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.

|    Vendor,  Model,            Processor,  System,      Compiler
    DEC,     DECstation 3100,  MIPS R2000, Ultrix 4.0,  cc and GNU gcc
    DEC,     DECstation 5120,  MIPS R3000, Ultrix 4.2,  cc and GNU gcc
    HP,      HP 9000/825,      HP-PA 1.0,  HP-UX 7.0,   cc
    HP,      HP 9000/720,      HP-PA 1.1,  HP-UX 8.0.5, cc
    IBM,     POWERstation 530, RS/6000,    AIX,         cc
    IBM,     PC,               i386/i486,  386BSD,      GNU gcc
    IBM,     PC,               i386/i486,  Linux,       GNU gcc
    MIPS,    M120/5,           MIPS R2000, RiscOS,      cc
    NeXT,    NeXTstation,      MC68040,    Mach,        GNU gcc
    Sequent, Symmetry,         ---,        Dynix,       cc,
    SGI,     Iris,             MIPS R3000, Irix,        cc and GNU gcc
    Sun,     Sun 3/60,         MC68020,    SunOS 4.0.1, cc and GNU gcc
    Sun,     Sun 4/280,        Sparc,      SunOS 4.0.1, cc and GNU gcc|

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 under UNIX" describes how you install {\GAP} on
a  UNIX  machine, and  the section  "Features  under  UNIX" describe  the
options that {\GAP} accepts undex UNIX.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installation under UNIX}%
\index{installation!under UNIX}\index{UNIX!installation}

Installation of {\GAP}  under UNIX is  fairly easy.  There are however  a
couple of choices to make.

The first choice is to decide who should  be able to  use {\GAP}.  It may
be that you are the only user  that will use {\GAP},  or it may be that a
couple of users will be using {\GAP}.  So first decide about this.

Next you have to decide on which machines you want to use {\GAP}.  It may
be that  you (and the  other users as well)  will be using {\GAP} only on
one machine, or it may be that  you will be using  {\GAP} on a number of,
possibly different, machines on a network.  So next decide about this.

In  the following we  will give two examples.  In  the first  one we will
assume that you, as user 'you', want  to install {\GAP}  for your own use
on one  DECstation, called 'ernie', only.  In  the other example  we will
assume that you,   as user 'local',  are installing   {\GAP}  for use  by
several users on a network of two DECstations, called 'bert' and 'tiffy',
and a   HP 9000/825, called  'goliath'.   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.

In the  next step you  have to decide where to  install {\GAP}.  The best
place depends on the decisions  you have made.  If you  are the only  one
who will be using {\GAP} and you will be using it only on one machine, it
is probably  best to install {\GAP}  beneath you homedirectory.  If other
users will also be  using {\GAP}, you  should install {\GAP} in  a public
place accessible to all users.  If you want to use  {\GAP} on a number of
machines on a network, you should install {\GAP} on  a filesystem that is
shared via *NFS* (*N*etwork *F*ile *S*ystem) between those machines.

For our first example you have to create  the subdirectory 'gap/' beneath
you homedirectory, assuming that no such directory already exists.

|    you@ernie:~ > mkdir gap
    you@ernie:~ > cd gap
    you@ernie:~/gap > |

For our  second example you will  have to create the  subdirectory 'gap/'
beneath the directory  '/usr/local/lib/',  which  is a  common place  for
software package of general interest, and which, we assume, is shared via
NFS between 'bert', 'tiffy' and 'goliath'.

|    local@goliath:~ > cd lib
    local@goliath:~/lib > mkdir gap
    local@goliath:~/lib > cd gap
    local@goliath:~/lib/gap > |

Now you have to get the {\GAP} distribution on your machine.  How you can
obtain {\GAP} is  described in the section  "Getting GAP".  The usual way
would be to get them with 'ftp' onto  you machine.  Remember that all the
files are binary files and that you must transmit them in binary mode.

So lets assume that  you have the  files  'src3r2.tar.Z', 'lib3r2.tar.Z',
'doc3r2.tar.Z',  and maybe  also  the  optional  files 'grp3r2.tar.Z' and
'tbl3r2.tar.Z'

|    you@ernie:~/gap > ls -l
    -rw-r--r--     you      835097 Apr  7 22:13 doc3r2.tar.Z
    -rw-r--r--     you     1062916 Apr  7 22:21 lib3r2.tar.Z
    -rw-r--r--     you      741217 Apr  7 22:27 src3r2.tar.Z
    you@ernie:~/gap > |

Now make a  subdirectory for the source  called 'src/'.  Change into this
subdirectory and unpack the source.  Note that you must  be in the source
subdirectory to unpack  the source.  After you  have  unpacked the source
you may  remove the *archive-file*.  The unpacking  of the source happens
correspondingly in the second example, so we do not show it here.

|    you@ernie:~/gap > mkdir src
    you@ernie:~/gap > cd src
    you@ernie:~/gap/src > uncompress ../src3r2.tar.Z
    you@ernie:~/gap/src > tar xf ../src3r2.tar
    you@erine:~/gap/src > ls
    Makefile      finfield.c    pcpresen.c    read.h        sysunix.c
    agcollec.c    finfield.h    pcpresen.h    record.c      tietze.c
    agcollec.h    function.c    permutat.c    record.h      tietze.h
    aggroup.c     function.h    permutat.h    scanner.c     unknown.c
    aggroup.h     gap.c         plist.c       scanner.h     unknown.h
    blister.c     gasman.c      plist.h       set.c         vecffe.c
    blister.h     gasman.h      polynom.c     set.h         vecffe.h
    costab.c      idents.c      polynom.h     statemen.c    vector.c
    costab.h      idents.h      range.c       statemen.h    vector.h
    cyclotom.c    integer.c     range.h       string.c      word.c
    cyclotom.h    integer.h     rational.c    string.h      word.h
    eval.c        list.c        rational.h    sysdos.c
    eval.h        list.h        read.c        system.h
    you@ernie:~/gap/src > |

Execute 'make' to see which compilation targets are predefined.

|    you@ernie:~/gap/src > make
    usage: 'make <target>'  where target is one of
    'decs-ultrix-gcc2'  for DECstations under Ultrix with GNU cc 2
    'decs-ultrix-cc'    for DECstations under Ultrix with cc
    'hp700-hpux-cc'     for HP 9000/700 under HP-UX with cc
    'hp800-hpux-cc'     for HP 9000/800 under HP-UX with cc
    'ibm6000-aix-cc'    for IBM RS/6000 under AIX with cc
    'ibmpc-386bsd-gcc2' for IBM PCs under 386BSD with GNU cc 2
    'ibmpc-386bsd-cc'   for IBM PCs under 386BSD with cc (GNU)
    'ibmpc-linux-gcc2'  for IBM PCs under Linux with GNU cc 2
    'ibmpc-msdos-djgpp' for IBM PCs under MSDOS with DJ GNU cc
    'mips-bsd-cc'       for MIPS under RISC/os Berkeley with cc
    'mips-sysv-cc'      for MIPS under RISC/os System V with cc
    'next-mach-gcc2'    for NeXT under Mach with GNU cc 2
    'next-mach-cc'      for NeXT under Mach with cc (GNU)
    'sequent-dynix-cc'  for Sequent Symmetry under Dynix with cc
    'sgi-irix-gcc2'     for SGI under Irix with GNU cc 2
    'sgi-irix-cc'       for SGI under Irix with cc
    'st-tos-gcc2'       for Atari ST under TOS with GNU cc 2
    'sun3-sunos-gcc2'   for SUN 3 under SunOs with GNU cc 2
    'sun3-sunos-cc'     for SUN 3 under SunOS with cc
    'sun4-sunos-gcc2'   for SUN 4 under SunOs with GNU cc 2
    'sun4-sunos-cc'     for SUN 4 under SunOS with cc
    'bsd'               for others under Berkeley UNIX with cc
    'usg'               for others under System V UNIX with cc
       targets are listed according to preference,
       i.e., 'sun4-sunos-gcc2' is better than 'sun4-sunos-cc'.
       additional C compiler and linker flags can be passed with
       'make <target> COPTS=<compiler-opts> LOPTS=<linker-opts>',
       i.e., 'make sun4-sunos-gcc2 COPTS=-g LOPTS=-g.'
    you@ernie:~/gap/src > |

Choose the best matching target.  If nothing matches precisely, use 'bsd'
(if your UNIX is more Berkeley) or 'usg' (if your UNIX is more System V).
If compilation of  the file 'sysunix.c' fails or the command line editing
does not work, remove the  file 'sysunix.o' and try the other target.  If
'sysunix.c' cannot be compiled neither with target  'bsd' nor with target
'usg', look  at this file and try to modify it so that compilation works.
If you can  compile but command  line editing does not  work  with either
target,  we  suggest  that you always start  {\GAP}  with option '-n'  to
disable command  line editing.   In any case we would like to  hear about
such problems.

In our  first example   the  right target is  obviously  'decs-ultrix-cc'
(remember 'ernie' was assumed to be a DECstation).  Compile {\GAP}.

|    you@ernie:~/gap/src > make decs-ultrix-cc
    # 'make' prints the name of each file as it is compiled
    # ignore the warnings that two functions in 'system.c' are too large
    # for optimization, they are not critical for the performance
    you@ernie:~/gap/src > ls -l gap
    -rwxr-xr-x     you      520192 Apr  7 22:47 gap
    you@ernie:~/gap/src > cd ..
    you@ernie:~/gap > |

In our second example things are a little bit more difficult, because you
have to   compile  {\GAP} for  two different   types of machines.   First
compile it for 'goliath', the HP 9000/800. To avoid name conflicts rename
the executable to 'gap.hp8'.

|    local@goliath:~/lib/gap/src > make hp800-hpux-cc
    # 'make' prints the name of each file as it is compiled
    # ignore the warnings that two functions in 'system.c' are too large
    # for optimization, they are not critical for the performance
    local@goliath:~/lib/gap/src > mv gap gap.hp8
    local@goliath:~/lib/gap/src > |

and   then compile it  on 'bert',  one   of the DECstations.  Rename this
executable  to 'gap.ds'.  Note that you  first have to  remove the object
files.  Otherwise 'make' will only try to link the object files, and fail
because those object files were made for a different processor.

|    local@goliath:~/lib/gap/src > rlogin bert
    local@bert:~ > cd lib/gap/src
    local@bert:~/lib/gap/src > rm *.o
    local@bert:~/lib/gap/src > make decs-ultrix-cc
    # 'make' prints the name of each file as it is compiled
    # ignore the warnings that two functions in 'system.c' are too large
    # for optimization, they are not critical for the performance
    local@bert:~/lib/gap/src > mv gap gap.ds
    local@bert:~/lib/gap/src > exit
    local@goliath:~/lib/gap/src > cd ..
    local@goliath:~/lib/gap > |

You may  want to keep  the source and  object files around until  you are
certain that  everything works.  However if space  is a tight resource on
your system you may remove the source and object files now.  All you need
in the 'src/' subdirectory from now on is (are) the executable(s).

Now you have to make a small  shell script whose job  is to start {\GAP}.
This  shell script  is  a convenient  place to put   various defaults and
configuration parameters.  In our first example enter

|    you@ernie:~/gap > cat > gap
    exec /usr/you/gap/src/gap -l /usr/you/gap/lib/ -m 4m $*
    |<ctr>-'D'
|    you@ernie:~/gap > |

The '-l' option tells {\GAP} where  to find the  library, in this case it
is in '/usr/you/gap/lib'.   If you give a wrong path {\GAP} will complain

|    gap: hmm, I cannot find 'lib/init.g', maybe use option '-l <libname>'?|

and very little will work.

The  '-m' option   tells {\GAP} the  default  amount  of  initial working
memory, in this case  it is 4 MByte.   Note that  {\GAP} will expand  its
working memory as need arises.  However, before doing so it will try very
hard to succeed  with the  current amount of memory.  Since  this is very
time consuming you may  not want to  make  this value  to small.  On  the
other hand you should  not make it  too large, because  otherwise  {\GAP}
will not fit in main  memory, and will spend most  of  its  time  paging,
instead of doing useful work.

The |$*| makes the script pass all its arguments to {\GAP}, so that users
can override   the default values of   '-l' and '-m'  and  also set other
options (see "Features under UNIX").

In the second example the  shell script is more complex  to allow for the
various machines.    Also  put it  into the   '/usr/local/bin' directory,
assuming  that this is the  directory that users have  in their path.  If
the  '/usr/local/bin' directory is  not shared between 'goliath', 'bert',
and 'tiffy' you have to put this script into each of those directories.

|    local@goliath:~/gap > cd ../bin
    local@goliath:~/bin > cat > gap
    case `hostname` in
    'goliath' )
        exec /usr/local/lib/gap/src/gap.hp8 -l /usr/local/lib/gap/lib $*
        ;;
    'bert' )
        exec /usr/local/lib/gap/src/gap.ds -l /usr/local/lib/gap/lib $*
        ;;
    'tiffy' )
        exec /usr/local/lib/gap/src/gap.ds -l /usr/local/lib/gap/lib $*
        ;;
    * )
        echo "gap: sorry, no executable exists for this machine"
    esac
    |<ctr>-'D'
|    local@goliath:~/bin > |

Now make a subdirectory for the library  called 'lib/'.  Change into this
subdirectory and unpack  the  library.   Note that  you  must  be in  the
library directory  to unpack  the  library.  After you  have unpacked the
library you may remove the  *archive-file*.  The unpacking of the library
happens correspondingly in the second example, so we do not show it here.

|    you@ernie:~/gap > mkdir lib
    you@ernie:~/gap > cd lib
    you@ernie:~/gap/lib > uncompress ../lib3r2.tar.Z
    you@ernie:~/gap/lib > tar xf ../lib3r2.tar
    you@ernie:~/gap/lib > ls
    abattoir.g    ctautoms.g    fpsgpres.g    matgrp.g      permprod.g
    agcent.g      ctbasic.g     fptietze.g    matring.g     permutat.g
    agclass.g     ctcharac.g    gaussian.g    matrix.g      polyfin.g
    agcomple.g    ctfilter.g    group.g       module.g      polyfld.g
    agcoset.g     ctgapmoc.g    grpcoset.g    numfield.g    polynom.g
    agctbl.g      ctgeneri.g    grpctbl.g     numtheor.g    polyrat.g
    aggroup.g     ctlattic.g    grpelms.g     onecohom.g    pq.g
    aghall.g      ctmapcon.g    grphomom.g    operatio.g    rational.g
    aghomomo.g    ctmapusi.g    grpprods.g    permag.g      recsl.g
    aginters.g    ctpermch.g    init.g        permbckt.g    ring.g
    agnorm.g      ctpgrp.g      integer.g     permcose.g    rowmodul.g
    agprops.g     ctsymmet.g    lattag.g      permcser.g    rowspace.g
    agsubgrp.g    cyclotom.g    lattgrp.g     permctbl.g    string.g
    agwords.g     domain.g      lattperf.g    permgrp.g     tom.g
    cdaggrp.g     field.g       lattperm.g    permhomo.g    vecspace.g
    chevgrp.g     finfield.g    list.g        permnorm.g
    combinat.g    fpgrp.g       mapping.g     permoper.g
    you@ernie:~/gap/lib > cd ..
    you@ernie:~/gap > |

Now start {\GAP} and try a few things.  Note that {\GAP} has to read most
of the library for   the fourth statement   below, so this takes  quite a
while.  Subsequent definitions of groups will be much faster.

|    you@ernie:~/gap > src/gap
    gap> 2 * 3 + 4;
    10
    gap> Factorial( 30 );
    265252859812191058636308480000000
    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> IsSimple( M11 );
    true |

Especially try the  command line  editing and history facilities, because
the 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'\\
should give the following line.

|    gap> Factors( 7921 );
    [ 89, 89 ] |

If command line editing does not work, remove the file 'system.o' and try
to compile with a different target, i.e., 'bsd' instead of  'usg' or vice
versa.  If  neither works,  we   suggest that  you  disable command  line
editing  by calling {\GAP}  always with the '-n' option.   In any case 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'.

Unpack the documentation  into a subdirectory 'doc/'.   The documentation
serves both as {\LaTeX} source for the printed manual and as online help.
Because the documentation  files also serve as   online help, you  do not
want to remove them, unless space is very tight, and you are content with
the printed manual.

|    you@ernie:~/gap > mkdir doc
    you@ernie:~/gap > cd doc
    you@ernie:~/gap/doc > uncompress ../doc3r2.tar.Z
    you@ernie:~/gap/doc > tar xf ../doc3r2.tar
    you@ernie:~/gap/doc > ls
    aboutgap.tex  environm.tex  language.tex  numfield.tex  rowspace.tex
    aggroup.tex   field.tex     list.tex      numtheor.tex  set.tex
    agwords.tex   finfield.tex  manual.bbl    operatio.tex  share.tex
    anupq.tex     fpgrp.tex     manual.bib    paramaps.tex  string.tex
    blister.tex   gaussian.tex  manual.idx    permgrp.tex   tom.tex
    boolean.tex   gentable.tex  manual.ind    permutat.tex  unknown.tex
    characte.tex  gettable.tex  manual.tex    polynom.tex   vecspace.tex
    chartabl.tex  group.tex     manual.toc    preface.tex   vector.tex
    combinat.tex  grplib.tex    mapping.tex   range.tex     weyl.tex
    copyrigh.tex  homomorp.tex  matgrp.tex    rational.tex  word.tex
    cyclotom.tex  install.tex   matring.tex   record.tex
    domain.tex    integer.tex   matrix.tex    ring.tex
    you@ernie:~/gap/doc > |

If you have a big version of {\LaTeX} available, you may now want to make
a printed copy  of the manual.  Change  into the directory 'doc/' and run
{\LaTeX} *twice* on  the source.  The first  pass  with {\LaTeX} produces
the  '.aux'  files, which resolve  all  the cross references.  The second
pass produces  the final formatted *dvi*   file 'manual.dvi'.  Then print
the  *dvi*  file.  How   this is  done    depends on your   local  {\TeX}
installation, if in doubt ask your local computer guru.

|    you@ernie:~/gap/doc > latex manual
    # about 2000 messages about undefined references
    you@ernie:~/gap/doc > latex manual
    # there should be no warnings this time
    you@ernie:~/gap/doc > ls -l manual.dvi
    -rw-r--r--     you    2591132 Apr  7 23:28 manual.dvi
    you@ernie:~/gap/doc > lp -dvi manual.dvi
    you@ernie:~/gap/doc > cd ..
    you@ernie:~/gap > |

Note that because  of the large number  of cross references in the manual
you need a *big*  {\LaTeX} to format  the {\GAP} manual.   If you see the
error message 'TeX capacity exceeded',  you do not  have a big  {\LaTeX};
again ask your local computer guru to  provide a big version of {\LaTeX}.
If this is not possible, you may  also obtain the already formatted *dvi*
file 'manual.dvi' from the same place where  you obtained the rest of the
{\GAP} distribution.

Note that, apart   from   the  '\*.tex' files  and the file  'manual.bib'
(bibliography database),  which you absolutely need, we  supply  also the
files 'manual.toc' (table of   contents), 'manual.ind' (unsorted  index),
'manual.idx' (sorted  index), and  'manual.bbl' (bibliography).  If those
files are missing, or  if you prefer  to do everything  yourself, here is
what you will have to do.  After  the first  pass with {\LaTeX}, you will
have  preliminary 'manual.toc' and  'manual.ind'  files.   All  the  page
numbers are  still incorrect, because the  do not account  for  the pages
used by  the table of contents itself.   Now 'bibtex  manual' will create
'manual.bbl' from 'manual.bib'.  After  the second pass with {\LaTeX} you
will  have a  correct   'manual.toc'  and 'manual.ind'.  'makeindex'  now
produces the sorted index 'manual.idx' from 'manual.ind'.  The third pass
with {\LaTeX} incorporates this index into the manual.

|    you@ernie:~/gap/doc > latex manual
    # about 2000 messages about undefined references
    you@ernie:~/gap/doc > bibtex manual
    # 'bibtex' prints the name of each file it is scanning
    you@ernie:~/gap/doc > latex manual
    # still some messages about undefined citations
    you@ernie:~/gap/doc > makeindex manual
    # 'makeindex' prints some diagnostic output
    you@ernie:~/gap/doc > latex manual
    # there should be no warnings this time
    you@ernie:~/gap/doc > lp -dvi manual.dvi
    you@ernie:~/gap/doc > cd ..
    you@ernie:~/gap > |

If you obtained the groups and character tables libraries unpack them now
into the subdirectories 'grp/', 'two/', and  'tbl/'.  Note that the group
and the character table libraries  are not essential to work with {\GAP},
you only need them when you want to access the data in those libraries.

Thats  all, finally you  are  done.  We  hope  that you  will enjoy using
{\GAP}.  If you have problems, do not hesitate to contact us.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Features under UNIX}%
\index{features!under UNIX}\index{UNIX!features}%
\index{options!under UNIX}\index{UNIX!options}%
\index{.gaprc}

When you start {\GAP} under UNIX, you may  specify a number of options on
the  command-line to change the  default behaviour  of {\GAP}.  All these
options start with a  hyphen '-', followed by  a single  letter.  Options
must not be grouped, e.g., 'gap -gq' is illegal, use 'gap -g -q' instead.
Some options require an argument, this must follow the option and must be
separated  by a <space>, e.g., 'gap  -m 256k', it is  not  correct to say
'gap -m256k' instead.

{\GAP} under UNIX will only accept lower case options.

As is described  in the previous section  (see "Installation under UNIX")
usually you will  not execute {\GAP} directly.   Instead you will  call a
shell script,  with the name 'gap', which in  turn executes {\GAP}.  This
shell script sets some options as neccessary to make  {\GAP} work on your
system.  This means that the default settings mentioned  below may not be
what you experience when you execute {\GAP} on your system.

'-g'

The option  '-g' tells {\GAP} to print a information message every time a
garbage collection is performed.

|    #G collect garbage, 1931 used, 5012 dead, 912 KB free, 4096 KB total|

For example, this tells you that there are 1931 live objects that surived
a garbage collection, that 5012 unused objects  were reclaimed by it, and
that 912 KByte of totally allocated 4096 KBytes are available afterwards.

'-l <libname>'

The option '-l' tells {\GAP} that  the  library of {\GAP} functions is in
the directory  <libname>.  Per  default <libname>  is 'lib/',  i.e.,  the
library is normally  expected in the  subdirectory  'lib/' of the current
directory.  {\GAP} searches for the library files, whose filenames end in
'.g', and which contain the functions initially known to  {\GAP}, in this
directory.   <libname> should end with  a  pathname separator, i.e., '/',
but {\GAP} will silently add one  if it is missing.  {\GAP} will read the
file '<libname>/init.g' during startup.  If {\GAP} cannot find this  file
it will print the following warning

|    gap: hmm, I cannot find 'lib/init.g', maybe use option '-l <lib>'?|

If you want  a bare bones {\GAP},  i.e., if you do  not need  any library
functions, you may ignore this warning, otherwise you should leave {\GAP}
and start it  again, specifying the  correct library path using the  '-l'
option.

It is  also possible  to  specify several  alternative library  pathes by
separating them  with semicolons ';'.   Note  that in this case  all path
names must end with the pathname separator '/'.   {\GAP} will then search
for its library files in all those directories in turn, reading the first
it finds.  E.g., if you specify '-l \"lib/;/usr/local/lib/gap/3.2/lib/\"'
{\GAP} will search for a library file first in the subdirectory 'lib/' of
the current directory, and if it does not find it there in the  directory
'/usr/local/lib/gap/3.2/lib/'.  This way you can built your own directory
of {\GAP} library files that override the standard ones.

{\GAP} searches  for the group files,  whose filenames end in '.grp', and
which contain the groups initially known  to {\GAP}, in the directory one
gets  by replacing the  string 'lib' in  <libname> with the string 'grp'.
If you  do not  want  to  put  the group   directory  'grp/' in  the same
directory as the  'lib/' directory, for  example if you want  to  put the
groups onto another hard disk partition,  you have to edit the assignment
in '<libname>/init.g' that reads

|    GRPNAME := ReplacedString( LIBNAME, "lib/;", "grp/;" );|

This path  can also consist of  several  alternative  pathes, just as the
library path.  If the library path consists of several alternative pathes
the default value for this path will consist of the same pathes, where in
each component the last occurrence of 'lib/' is replaced by 'grp/'.

Similar considerations    apply to   the  character  table  files.  Those
filenames end in '.tbl'.   {\GAP} looks for  those files in the directory
given  by 'TBLNAME'.  The default  value   for 'TBLNAME'  is  obtained by
replacing 'lib' in <libname> with 'tbl'.

'-h <docname>'

The option '-h'  tells {\GAP} that the on-line documenation for {\GAP} is
in  the  directory  <docname>.  Per  default  <docname>  is  obtained  by
replacing 'lib'  in  <libname> with  'doc'.   <docname> should end with a
pathname  separator, i.e., '/', but {\GAP} will silently add one if it is
missing.  {\GAP} will read the file '<docname>/manual.toc' when you first
use the help system.  If  {\GAP} cannot find this file it will print  the
following warning

|    help: hmm, I cannot open the table of contents file 'doc/manual.toc'
    maybe you should use the option '-h <docname>'?|

'-m <memory>'

The option '-m' tells {\GAP} to allocate <memory>  bytes at startup time.
If the last character of <memory> is 'k' or 'K' it is taken in KBytes and
if the last character is 'm' or 'M' <memory> is taken in MBytes.

Under UNIX the default amount  of memory allocated  by {\GAP} is 2 MByte.
The amount of memory  should be large  enough so that computations do not
require  too  many  garbage  collections.  On the   other hand  if {\GAP}
allocates more virtual memory than  is physically available it will spend
most of  the  time  paging.   2 MByte    is  reasonable for  single  user
workstations with 4 MByte or for multi user systems with 8 MByte or more.

'-n'

The option  '-n'  tells {\GAP}  to disable  the line editing  and history
(see "Line Editing").

You may want to do this if the command line  editing is incompatible with
another program that is used to run {\GAP}.  For example if {\GAP} is run
from inside a GNU Emacs shell window, '-n' should be used since otherwise
every input line will be echoed twice, once by Emacs and once by {\GAP}.

'-b'

The option '-b'  tells {\GAP} to  surpress the banner.  That  means  that
{\GAP} immediately prints the prompt.  This is useful  when you get tired
of the banner after a while.

'-q'

The option  '-q' tells {\GAP} to  be quiet.  This  means that {\GAP} does
not display the  banner and the prompts  'gap>'.  This is  useful  if you
want to run {\GAP} as a filter with input and output redirection and want
to avoid the the banner and the prompts clobber the output file.

'-x <length>'

With this option  you can tell  {\GAP}  how long lines  are.  {\GAP} uses
this value to decide when to split long lines.

The default value is 80, which is the right value if you have  a standard
ASCII terminal.  If you have a larger monitor, or use a  smaller font, or
redirect the output to a printer, you may want to increase this value.

'-y <length>'

With this  option you can  tell {\GAP} how  many lines  your  screen has.
{\GAP} uses this value to decide after how  many lines of on-line help it
should display |-- <space> for more --|.

The default value is 24, which is the right  value if you have a standard
ASCII terminal.  If you have a larger monitor, or use  a smaller font, or
redirect the output to a printer, you may want to increase this value.

Further arguments are taken as filenames of files that are read by {\GAP}
during  startup, after '<libname>/init.g' is read, but  before the  first
prompt is printed.  The files are read  in the order  in that they appear
on  the command line.  {\GAP} only accepts  14  filenames  on the command
line.  If a file cannot be opened {\GAP} will print  an error message and
will abort.

When you  start {\GAP}, it looks  for the file  with the name '.gaprc' in
your  homedirectory.  If   such  a file   is    found it  is  read  after
'<libname>/init.g', but before any of the files  mentioned on the command
line are read.  You  can use this  file  for your private customizations.
For example,  if you have a  file containing functions  or  data that you
always need, you could read this from '.gaprc'.  Or if  you  find some of
the names  in the library too  long, you could  define  abbreviations for
those names in '.gaprc'.  The following sample '.gaprc' file does both.

|    Read("/usr/you/dat/mygroups.grp");
    Op := Operation;
    OpHom := OperationHomomorphism;
    RepOp := RepresentativeOperation;
    RepsOp := RepresentativesOperation; |

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{IBM PC Compatibles}%
\index{MSDOS}

{\GAP} runs on IBM PC compatibles with an Intel 80386 or 80486 processor,
running MS-DOS 5.0.   {\GAP} does *not* run on IBM PC compatibles with an
Intel  80186  or  80286  processor.   {\GAP} does  also *not*  run  under
Windows.

To  use {\GAP} you  need at  least 2  MByte  of  main memory (less may be
possible,  but this would make {\GAP} so slow that no serious work can be
done).   More is  preferred for serious computations.   You  also need  a
harddisk with at least 3 MByte of free space.   If you also want to  keep
the manual  online  you need an additional 2 MByte of space for that.  If
you also want to keep the source and object modules for the {\GAP} kernel
you need an  additional 3  MByte  of space for that.   Since  {\GAP} is a
plain text application either a monochrom or color monitor may be used.

{\GAP} will use  up to 128 MByte of extended memory (using *XMS*, *VDISK*
memory  allocation strategies) or  up  to  128 MByte  of  expanded memory
(using *VCPI* programs, such  as 'QEMM' and '386MAX') and up to 128 MByte
of disk  space for swapping.

If you hit <ctr>-'C' the  DOS  extender ('go32')  catches  it and  aborts
{\GAP} immediately.  The keys <ctr>-'Z' and <alt>-'C' can be used instead
to interupt {\GAP}.

The arrow keys <left>, <right>, <up>, <down>, <home>, <end>, and <delete>
can be used for command line editing with their intuitive meaning.

One of the more annyoing *features* of MS-DOS is the use of the backslash
|\| as a directory separator in  filenames  instead of the slash '/' used
in  UNIX.  To ease  this {\GAP}  allows slashes  in  filenames  and  will
silently replace them with backslashes.  Throughout this sections we will
use the slash as separator.

Apart  from this everything  works as  described  in this manual  and you
should not have any problems using {\GAP}.

The section  "Copyright of  GAP  for IBM  PC  Compatibles"  describes the
copyright as it applies to  the executable  version  that we  distribute.
The  section  "Installation on  IBM  PC  Compatibles" describes  how  you
install  {\GAP} on  the IBM PC Compatibles, and the section "Features  on
IBM PC Compatibles" describes the options that {\GAP}  accepts on the IBM
PC Compatibles.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Copyright of GAP for IBM PC Compatibles}

The  system  dependent part of  {\GAP}  for  the  386  ('system.dos') was
written by Steve  Linton (111  Ross St., Cambridge,  CB1 3BS, UK, +44 223
411661,   '[e-mail]').   He  assignes   the  copyright  to  the
Lehrstuhl D fuer Mathematik.  Many thanks to Steve Linton for his work.

The executable of {\GAP}  for the  386 that we distribute  ('gapexe.386')
was compiled with  DJ Delorie\'s port of the Free Software  Foundation\'s
GNU C  compiler version 2.1.  The compiler can be  obtained  by anonymous
'ftp'  from  'grape.ecs.clarkson.edu'   where  it  is  in  the  directory
'pub/msdos/djgpp'.  Many  thanks to  the Free Software  Foundation and DJ
Delorie for this amazing piece of work.

The GNU C compiler is

*Copyright (C) 1989 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 modifications to the compiler to make it operating under  MS-DOS, the
functions from  the standard library 'libpc.a', the  modifications of the
functions from the standard library  'libc.a' to make  them operate under
MS-DOS, and the DOS extender  'go32' (which is prepended to 'gapexe.386')
are

*Copyright (C) 1991 DJ Delorie,
24 Kirsten Ave, Rochester NH 03867-2954, USA*

also under  the terms of the GNU GPL.  The terms of  the GPL require that
we make the source code for 'libpc.a' available.  They can be obtained by
writing to Steve Linton (however, it may be  easier for you to 'ftp' them
from  'grape.ecs.clarkson.edu'  yourself).   They  also require that  GAP
falls under the GPL too, i.e., is distributed freely,  which it basically
does anyhow.

The functions in 'libc.a' that GAP for the 386 uses are

*Copyright (c) 1988 Regents of the University of California*

under the following terms

*All rights reserved.*

*Redistribution and use in source and binary forms are permitted provided
that the above copyright notice and this paragraph are  duplicated in all
such forms and that  any documentation, advertising  materials, and other
materials  related to  such  distribution and  use acknowledge  that  the
software  was developed by  the University of California, Berkeley.   The
name  of the University  may not be  used to endorse or promote  products
derived from this software without specific prior written permission.*

*THIS  SOFTWARE  IS  PROVIDED AS IS  AND WITHOUT  ANY EXPRESS OR  IMPLIED
WARRANTIES,  INCLUDING,  WITHOUT  LIMITATION, THE  IMPLIED WARRANTIES  OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.*

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installation on IBM PC Compatibles}%
\index{installation!under MS-DOS}\index{MS-DOS!installation}

Installation of {\GAP} on IBM PC compatibles is fairly  easy.  As already
mentioned above,  {\GAP} must  be installed on a harddisk,  because it is
too large to be run from diskettes.

In  this section we will assume  in the examples that you  install {\GAP}
from 'command.com'.   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.  We also assume a program
'ls' that is used to list the files in a directory,  the output  of 'dir'
is too verbose.

First choose  a place where  you want   to install  {\GAP}.  You can  put
{\GAP} anywhere, however, for sake of an example we will assume here that
you have choosen |C:\GAP|, i.e., top level directory 'GAP' on drive  'C'.
Now make this directory.

|     C: > mkdir gap
     C: > chdir gap
     C:\GAP > |

The  next  step  is  to  get the  {\GAP}  distribution  on  your  IBM  PC
compatible.  How  you  can obtain  {\GAP}  is described  in  the  section
"Getting GAP".  The usual way would  be to get  the files with 'ftp' onto
some UNIX machine and then to download them, for example with 'kermit' or
a terminal  emulation program that supports downloading  of  files,  onto
your IBM PC compatible.  Remember that all the files are binary files and
that you must  transmit them in binary mode.  We are sorry, but we cannot
send out disks.

For  IBM PC compatibles  it is better  to  get  the  *zoo-archive*  files
instead of the *compressed-tar*  files, because 'zoo' is much more common
on  IBM  PC compatible  machines than  'compress'  and 'tar'.   Also  the
*zoo-archive*s  are  smaller.   You  need 'zoo' version  2.1 or later.  A
version  of  'zoo'  for IBM  PC  compatibles is  available  together with
{\GAP}.  Also for IBM PC compatibles you should get the executable kernel
'gapexe.386'.  You may also get the source for the kernel to read it, but
there  is  very  little  point  in compiling  {\GAP}  again  on your  own
computer.

So  lets  assume  that  you have  the  files  'gapexe.386', 'lib3r2.zoo',
'doc3r2.zoo',  and maybe also the files  'grp3r2.zoo', 'tbl3r2.zoo'  (the
sizes reported below in the example are only approximate).

|    C:\GAP > dir
    -a---     649958 May 13 22:45 doc3r2.zoo
    -a---     481851 May 13 22:51 gapexe.386
    -a---     725911 May 13 22:57 lib3r2.zoo
    C:\GAP > |

Rename the executable to 'gap.exe'.

|    C:\GAP > ren gapexe.386 gap.exe
    C:\GAP > |

Make a subdirectory  for the library.  Usually  this is  the subdirectory
'lib'.  Other names  are possible, but then you  need to pass the name of
the library subdirectory as an option whenever you start {\GAP}.  Using a
nonstandard name only  makes sense when you  want to work  with different
libraries (as do the developers of {\GAP}), but this is very unlikely.

|    C:\GAP > mkdir lib
    C:\GAP > |

Now change  into this subdirectory  and  unpack the library from the  zoo
archive.  Note that you must be in the library subdirectory to unpack the
library.   After you have unpacked  the library remove the *archive-file*
and change back into the parent directory.

|    C:\GAP > chdir lib
    C:\GAP\LIB > zoo x ..\lib3r2.zoo
    # 'zoo' prints the name of each file as it is extracted
    C:\GAP\LIB > ls
    abattoir.g    ctautoms.g    fpsgpres.g    matgrp.g      permprod.g
    agcent.g      ctbasic.g     fptietze.g    matring.g     permutat.g
    agclass.g     ctcharac.g    gaussian.g    matrix.g      polyfin.g
    agcomple.g    ctfilter.g    group.g       module.g      polyfld.g
    agcoset.g     ctgapmoc.g    grpcoset.g    numfield.g    polynom.g
    agctbl.g      ctgeneri.g    grpctbl.g     numtheor.g    polyrat.g
    aggroup.g     ctlattic.g    grpelms.g     onecohom.g    pq.g
    aghall.g      ctmapcon.g    grphomom.g    operatio.g    rational.g
    aghomomo.g    ctmapusi.g    grpprods.g    permag.g      recsl.g
    aginters.g    ctpermch.g    init.g        permbckt.g    ring.g
    agnorm.g      ctpgrp.g      integer.g     permcose.g    rowmodul.g
    agprops.g     ctsymmet.g    lattag.g      permcser.g    rowspace.g
    agsubgrp.g    cyclotom.g    lattgrp.g     permctbl.g    string.g
    agwords.g     domain.g      lattperf.g    permgrp.g     tom.g
    cdaggrp.g     field.g       lattperm.g    permhomo.g    vecspace.g
    chevgrp.g     finfield.g    list.g        permnorm.g
    combinat.g    fpgrp.g       mapping.g     permoper.g
    C:\GAP\LIB > del ..\lib3r2.zoo
    C:\GAP\LIB > chdir ..
    C:\GAP > |

Add the following line to your 'autoexec.bat' file

|    SET GO32TMP=|<swap-file-directory>||

where <swap-file-directory> should be the directory where you want GAP to
put  the  swap  file,  e.g.,  |C:\TMP|.   The swap  file will  be  called
'page????.386' and is normally  removed when GAP exits.  If  'GO32TMP' is
not set, 'GCCTMP', 'TMP', 'TEMP' are checked (in this order).  If neither
is set, GAP  will  not swap to disk.  Note that you must *reboot*  before
this change in 'autoexec.bat' takes effect.

Start {\GAP} and try a few things.  Note that {\GAP} has  to read most of
the library for the fourth statement below,  so this takes quite a while.
Subsequent definitions of groups will be much faster.

|    C:\GAP > gap
    gap> 2 * 3 + 4;
    10
    gap> Factorial( 30 );
    265252859812191058636308480000000
    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> IsSimple( M11 );
    true |

Especially try the command  line editing  and history facilities, because
the 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 three commands typing\\
<ctr>-'P' <ctr>-'P' <ctr>-'E' <ctr>-'B'
<ctr>-'B' <ctr>-'B' <ctr>-'B' <ctr>-'D' '1'\\
should give the following line.

|    gap> Factors( 7921 );
    [ 89, 89 ] |

If you start {\GAP}  from another place, i.e.,  not from within the 'gap'
directory,  you  will  have to   specify  the full  path   to the library
subdirectory.

|    C:\GAP > chdir ..
    C: > gap\gap
    gap: hmm, I cannot find 'lib\init.g', maybe use option '-l <libname>'?
    gap> quit;
    C: > gap\gap -l c:\gap\lib\
    gap> Gcd( 123, 66 );
    3
    gap> quit;
    C: > chdir gap
    C:\GAP > |

You may  want to  create  a  batch  file  that  calls the  executable and
automatically  passes  the correct library path.   It  is probably a good
idea to put this file into a directory in your default search path, e.g.,
|C:\BIN|. In the following example we use 'copy' to create this file, you
may prefer to use your favorite editor.

|    C:\GAP > chdir ..\bin
    C:\BIN > copy con gap.bat
    c:\gap\gap  -m 2m  -l c:\gap\lib  %1 %2 %3 %4 %5 %6 %7 %8 %9
    |<ctr>-'Z'
|    1 File(s) copied
    C:\BIN > chdir ..
    C: > gap
    gap> 2 * 3 + 4;
    10
    gap> quit;
    C: > chdir gap
    C:\GAP > |

The '-l' option tells {\GAP} where  to find the  library, in this case it
is in |C:\GAP\LIB|.   If you  give  a  wrong  path {\GAP}  will  complain

|    gap: hmm, I cannot find 'lib/init.g', maybe use option '-l <libname>'?|

and very little will work.

The  '-m' option   tells {\GAP} the  default  amount  of  initial working
memory, in this case  it is 2 MByte.   Note that  {\GAP} will expand  its
working memory as need arises.  However, before doing so it will try very
hard to succeed  with the  current amount of memory.  Since  this is very
time consuming you may  not want to  make  this value  to small.  On  the
other hand you should  not make it  too large, because  otherwise  {\GAP}
will not fit in main  memory, and will spend most  of  its  time  paging,
instead of doing useful work.

The |%1  %2  ...| makes the script pass all its  arguments to  {\GAP}, so
that  you can override the default  values of '-l' and  '-m' and also set
other options (see "Features on IBM PC Compatibles").

Unpack the documentation  into a subdirectory 'doc'.   The documentation
serves both as {\LaTeX} source for the printed manual and as online help.
Because the documentation  files also serves as  online help, you  do not
want to remove them, unless space is very tight, and you are content with
the printed manual.

|    C:\GAP > mkdir doc
    C:\GAP > chdir doc
    C:\GAP\DOC > zoo x ..\doc3r2.zoo
    # 'zoo' prints the name of each file as it is extracted
    C:\GAP\DOC > ls
    aboutgap.tex  environm.tex  language.tex  numfield.tex  rowspace.tex
    aggroup.tex   field.tex     list.tex      numtheor.tex  set.tex
    agwords.tex   finfield.tex  manual.bbl    operatio.tex  share.tex
    anupq.tex     fpgrp.tex     manual.bib    paramaps.tex  string.tex
    blister.tex   gaussian.tex  manual.idx    permgrp.tex   tom.tex
    boolean.tex   gentable.tex  manual.ind    permutat.tex  unknown.tex
    characte.tex  gettable.tex  manual.tex    polynom.tex   vecspace.tex
    chartabl.tex  group.tex     manual.toc    preface.tex   vector.tex
    combinat.tex  grplib.tex    mapping.tex   range.tex     weyl.tex
    copyrigh.tex  homomorp.tex  matgrp.tex    rational.tex  word.tex
    cyclotom.tex  install.tex   matring.tex   record.tex
    domain.tex    integer.tex   matrix.tex    ring.tex
    C:\GAP\DOC > del ..\doc3r2.zoo
    C:\GAP\DOC > |

If you have a big version of {\LaTeX} available you  may now want to make
a printed copy  of the manual.  Change into  the directory 'doc'  and run
{\LaTeX} *twice* on the source.   The  first pass with {\LaTeX}  produces
the '.aux'  files,  which resolve all the  cross  references.  The second
pass produces  the final  formatted  *dvi* file 'manual.dvi'.  This  will
take quite  a while, since  the  manual is  large.  Then print  the *dvi*
file.  How you actually print the 'dvi' file produced by {\LaTeX} depends
on the  printer you have, the version  of {\LaTeX}  you have, and whether
you use a {\TeX}-shell   or not, so  we will  not attempt to  describe it
here.

|    C:\GAP\DOC > latex manual
    # about 2000 messages about undefined references
    C:\GAP\DOC > latex manual
    # there should be no warnings this time
    C:\GAP\DOC > dir manual.dvi
    -a---   2591132 May 13 23:29 manual.dvi
    C:\GAP\DOC > chdir ..
    C:\GAP > |

Note that because of the large  number of  cross references in the manual
you need a *big*  {\LaTeX} to format the {\GAP}  manual.  If you  see the
error message  'TeX capacity  exceeded', you do  not have a big {\LaTeX}.
In this case  you  may also  obtain the  already    formatted *dvi*  file
'manual.dvi' from  the  same place where   you obtained the   rest of the
{\GAP} distribution.

Note that, apart   from   the  '\*.tex' files  and the file  'manual.bib'
(bibliography database),  which you absolutely need, we  supply  also the
files 'manual.toc' (table of   contents), 'manual.ind' (unsorted  index),
'manual.idx' (sorted  index), and  'manual.bbl' (bibliography).  If those
files are missing, or  if you prefer  to do everything  yourself, here is
what you will have to do.  After  the first  pass with {\LaTeX}, you will
have  preliminary 'manual.toc' and  'manual.ind'  files.   All  the  page
numbers are  still incorrect, because the  do not account  for  the pages
used by  the table of contents itself.   Now 'bibtex  manual' will create
'manual.bbl' from 'manual.bib'.  After  the second pass with {\LaTeX} you
will  have a  correct   'manual.toc'  and 'manual.ind'.  'makeindex'  now
produces the sorted index 'manual.idx' from 'manual.ind'.  The third pass
with {\LaTeX} incorporates this index into the manual.

|    C:\GAP\DOC > latex manual
    # about 2000 messages about undefined references
    C:\GAP\DOC > bibtex manual
    # 'bibtex' prints the name of each file it is scanning
    C:\GAP\DOC > latex manual
    # still some messages about undefined citations
    C:\GAP\DOC > makeindex manual
    # 'makeindex' prints some diagnostic output
    C:\GAP\DOC > latex manual
    # there should be no warnings this time
    C:\GAP\DOC > chdir ..
    C:\GAP > |

If you have also fetched 'grp3r2.zoo', 'two3r2.zoo', and/or 'tbl3r2.zoo',
you may now want to unpack those into subdirectories 'grp', 'two', and/or
'tbl' in  a corresponding  way.  Alternatively  you can  do this  anytime
later.

Thats  all, finally you  are  done.  We  hope  that you  will enjoy using
{\GAP}.  If you have problems, do not hesitate to contact us.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Features on IBM PC Compatibles}
\index{features!under MS-DOS}\index{MS-DOS!features}%
\index{options!under MS-DOS}\index{MS-DOS!options}%
\index{.gaprc}

When you start {\GAP} on IBM PC compatibles,  you may specify a number of
options  on the command-line to change the  default  behaviour of {\GAP}.
All these options  start with a  hyphen '-', followed by a single letter.
Options must not be grouped,  e.g., 'gap -gq' is illegal, use 'gap -g -q'
instead.  Some options require an argument,  this must  follow the option
and must be separated by  a  <space>,  e.g.,  'gap  -m 256k',  it is  not
correct to say 'gap -m256k' instead.

{\GAP} on IBM PC compatibles will only accept lower case options.

'-g'

The options '-g' tells {\GAP} to print a information message every time a
garbage collection is performed.

|    #G collect garbage, 1931 used, 5012 dead, 912 KB free, 3072 KB total|

For example, this tells you that there are 1931 live objects that surived
a garbage collection, that 5012 unused objects  were reclaimed by it, and
that 912 KByte of totally allocated 3072 KBytes are available afterwards.

'-l <libname>'

The option '-l' tells {\GAP}  that the library  of {\GAP} functions is in
the  directory <libname>.  Per  default  <libname> is  'lib/', i.e.,  the
library  is normally expected in the subdirectory  'lib/'  of the current
directory.  {\GAP} searches for the library files, whose filenames end in
'.g', and which contain the functions initially known to  {\GAP}, in this
directory.   <libname> should end  with a  pathname separator, i.e., '/',
but {\GAP} will silently add one  if it is missing.  {\GAP} will read the
file '<libname>/init.g' during startup.  If {\GAP} cannot find this  file
it will print the following warning

|    gap: hmm, I cannot find 'lib/init.g', maybe use option '-l <lib>'?|

If you  want a bare bones {\GAP},  i.e., if you do  not  need any library
functions, you may ignore this warning, otherwise you should leave {\GAP}
and start  it again, specifying the correct  library path  using the '-l'
option.

It is  also possible  to  specify several  alternative library  pathes by
separating them  with semicolons ';'.   Note  that in this case  all path
names must end with the pathname separator '/'.   {\GAP} will then search
for its library files in all those directories in turn, reading the first
it finds.  E.g., if you specify '-l \"lib/;/usr/local/lib/gap/3.2/lib/\"'
{\GAP} will search for a library file first in the subdirectory 'lib/' of
the current directory, and if it does not find it there in the  directory
'/usr/local/lib/gap/3.2/lib/'.  This way you can built your own directory
of {\GAP} library files that override the standard ones.

{\GAP}  searches for the group files,  whose filenames end in '.grp', and
which contain the groups initially known to  {\GAP}, in the directory one
gets by replacing the string 'lib' in <libname> by the  string 'grp'.  If
you do not want  to put the group  directory 'grp/' in the same directory
as the 'lib/' directory,  for example if you want  to put the groups onto
another   hard  disk  partition,  you have  to   edit the   assignment in
'<libname>/init.g' that reads

|    GRPNAME := ReplacedString( LIBNAME, "lib/;", "grp/;" );|

This path  can also consist of  several  alternative  pathes, just as the
library path.  If the library path consists of several alternative pathes
the default value for this path will consist of the same pathes, where in
each component the last occurrence of 'lib/' is replaced by 'grp/'.

Similar considerations    apply to   the  character  table  files.  Those
filenames end in '.tbl'.   {\GAP} looks for  those files in the directory
given  by 'TBLNAME'.  The default  value   for 'TBLNAME'  is  obtained by
replacing 'lib' in <libname> with 'tbl'.

'-h <docname>'

The  option '-h' tells {\GAP} that the on-line documenation for {\GAP} is
in  the directory  <docname>.   Per  default  <docname>  is  obtained  by
replacing 'lib' in <libname>  with 'doc'.   <docname> should  end  with a
pathname separator, i.e., '/', but {\GAP} will silently  add one if it is
missing.  {\GAP} will read the file '<docname>/manual.toc' when you first
use the help system.  If {\GAP} cannot find this file  it will print  the
following warning

|    help: hmm, I cannot open the table of contents file 'doc/manual.toc'
    maybe you should use the option '-h <docname>'?|

'-m <memory>'

The option '-m' tells {\GAP} to  allocate <memory> bytes at startup time.
If the last character of <memory> is 'k' or 'K' it is taken in KBytes and
if the last character is 'm' or 'M' <memory> is taken in MBytes.

On IBM PC compatibles {\GAP} will by default allocate 2 MBytes of memory.
If you specify '-m <memory>' {\GAP} will only allocate that  much memory.
The amount of memory  should be large  enough so that computations do not
require  too  many  garbage  collections.  On the   other hand  if {\GAP}
allocates more virtual memory than  is physically available it will spend
most of  the  time  paging.

'-n'

The  options  '-n' tells {\GAP} to  disable  the line editing and history
(see "Line Editing").

There does not seem to be a good reason to do this on IBM PC compatibles.

'-b'

The option '-b'  tells {\GAP} to  surpress the banner.  That  means  that
{\GAP} immediately prints the prompt.  This is useful  when you get tired
of the banner after a while.

'-q'

The  option '-q' tells  {\GAP} to be quiet.  This  means that {\GAP} does
not  display the banner and the  prompts 'gap>'.  This  is useful  if you
want to run {\GAP} as a filter with input and output redirection and want
to avoid the the banner and the prompts clobber the output file.

'-x <length>'

With this  option you can tell  {\GAP} how long   lines are.  {\GAP} uses
this value to decide when to split long lines.

The default value is 80,  which  is correct if  you start {\GAP} from the
desktop or one of the usual shells.  However, if you  start {\GAP} from a
window shell such as 'gemini', you may want to decrease  this  value.  If
you have a larger monitor, or use a smaller font, or  redirect the output
to a printer, you may want to increase this value.

'-y <length>'

With this  option you can  tell {\GAP} how  many lines  your  screen has.
{\GAP} uses this value to decide after how  many lines of on-line help it
should display |-- <space> for more --|.

The default value is  24, which is  the right value  if  you start {\GAP}
from the desktop or one  of  the  usual shells.   However, if  you  start
{\GAP} from a window  shell such as 'gemini',   you may want  to decrease
this value.  If  you  have a larger monitor,  or use  a smaller  font, or
redirect the output to a printer, you may want to increase this value.

'-z <freq>'

{\GAP} checks in regular intervals whether the user has entered <ctr>-'Z'
or <alt>-'C'  to interrupt an  ongoing computation.   Under  MS-DOS  this
requires reading the keyboard status (UNIX on the other hand will deliver
a  signal  to {\GAP} when the user  entered <ctr>-'C'),  which is  rather
expensive.   Therefor  {\GAP}  only  reads   the  keyboard  status  every
<freq>-th time.   The default is 20.  With the option '-z' this value can
be  changed.   Lower values  make  {\GAP} more responsive  to interrupts,
higher values make {\GAP} a little bit faster.

Further arguments are taken as filenames of files that are read by {\GAP}
during startup, after '<libname>/init.g' is read,  but  before  the first
prompt is  printed.  The files are read in the order in  that they appear
on  the command line.  {\GAP}  only  accepts 14 filenames on the  command
line.  If a file  cannot be opened {\GAP} will print an error message and
will abort.

When you start {\GAP}, it looks  for  the file  with the name 'gap.rc' in
your  homedirectory (i.e., the   directory   defined by  the  environment
variable     'HOME').  If  such   a file  is    found it   is read  after
'<libname>/init.g', but before any of the  files mentioned on the command
line are read.   You can use  this file for your private  customizations.
For example, if you  have a file  containing  functions  or data that you
always need, you could read this from 'gap.rc'.   Or if you find  some of
the names in  the  library too long,  you could define abbreviations  for
those names in 'gap.rc'.  The following sample 'gap.rc' file does both.

|    Read("c:\\gap\\dat\\mygroups.grp");
    Op := Operation;
    OpHom := OperationHomomorphism;
    RepOp := RepresentativeOperation;
    RepsOp := RepresentativesOperation; |

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Atari ST}%
\index{TOS}

{\GAP} runs really  nice on the Atari ST  computers.   Those machines are
cheap yet reasonably powerful  and can be extended with  up to 4 MByte of
memory.  Several of the developers of {\GAP} have an Atari ST computer at
home, which probably is the main reason for the support of this machine.

To use {\GAP} on an Atari ST you need a machine with  at least 2 MByte of
main memory, more is preferred for serious computations.  You also need a
harddisk with at least 3  MByte of free space.  If  you also want to keep
the manual online you need an  additional 2 MByte of space  for that.  If
you also want to keep the source and object modules for the {\GAP} kernel
you need an  additional 3 MBytes  of space for  that.  Since {\GAP} is  a
plain text application a monochrom monitor is probably  best, but you may
also use a color monitor.

{\GAP} runs as an ordinary TOS program on  the Atari ST.  That means that
it does not open windows  or display a  menu  bar etc.  The advantage  of
this  is that no  valuable memory space is   wasted for the windows.  The
disadvantage  is that GEM programs with  windows are certainly more sexy.
A GEM version is being developed, but don\'t hold your breath.

{\GAP} usually grabs all  available memory when  it is started.  This  is
sensible when you want to solve some  medium to big problems with {\GAP}.
However, if you want to call other programms, for example an editor, from
inside {\GAP} or run under an multitasking system,  for example MiNT, you
may want to reduce this using the '-m' option described below.

One of the more  annyoing *features* of TOS  is  the use of the backslash
|\| as  a directory separator in filenames instead of the slash  '/' used
in UNIX.   To ease  this  {\GAP}  allows  slashes in  filenames and  will
silently replace them with backslashes.  Throughout this sections we will
use the slash as separator.

Apart  from this everything  works as  described  in this manual  and you
should not have any problems using {\GAP}.

The  section   "Installation on the Atari  ST"  describes how you install
{\GAP} on   the  Atari  ST, and  the section  "Features  on the Atari ST"
describes the options that {\GAP} accepts on the Atari ST.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installation on the Atari ST}%
\index{installation!under TOS}\index{TOS!installation}

Installation  of  {\GAP} on  the Atari   ST is  fairly easy.   As already
mentioned above,  {\GAP} must be  installed on a  harddisk, because it is
too large to be run from diskettes.

In this section  we will assume in  the examples that you install  {\GAP}
using some shell, e.g.  'tcsh', 'ksh',  'bash', or 'gulam'.  Installation
from the desktop is also possible, but it would be much more difficult to
give examples, because you have to use the mouse in this case.  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.

First choose  a place where  you want   to install  {\GAP}.  You can  put
{\GAP} anywhere, however, for sake of an example we will assume here that
you have choosen |c:\gap|, i.e., top level directory 'gap' on drive  'C'.
Now make this directory.

|     c:\ > pwd
     c:\
     c:\ > mkdir gap
     c:\ > cd gap
     c:\gap\ > |

The next step is to  get the {\GAP} distribution on  your Atari ST.   How
you can  obtain {\GAP} is described  in  the section "Getting  GAP".  The
usual way would be to get the files with 'ftp' onto some UNIX machine and
then to download them, for example with  'kermit' or a terminal emulation
program  that supports downloading of files,  onto  your Atari.  Remember
that all  the files are  binary files and that you  must transmit them in
binary mode.  We are sorry, but we cannot send out disks.

For the Atari ST it  is better to get the  *zoo-archive* files instead of
the *compressed-tar* files, because 'zoo' is much more common on Atari ST
machines than 'compress' and 'tar'.  Also the *zoo-archive*s are smaller.
You need 'zoo' version 2.1 or later.  A version of 'zoo' for the Atari ST
is available together with {\GAP}.  Also for the Atari  ST you should get
the executable kernel  'gapexe.st'.  You may also get  the source for the
kernel to  read it,  but there is  very little  point in compiling {\GAP}
again on your own computer.

So  lets  assume  that  you  have  the files  'gapexe.st',  'lib3r2.zoo',
'doc3r2.zoo', and maybe also  the  files 'grp3r2.zoo', 'tbl3r2.zoo'  (the
sizes reported below in the example are only approximate).

|    c:\gap\ > ls -l
    -rw     649958 Apr  7 22:45 doc3r2.zoo
    -rw     431851 Apr  7 22:51 gapexe.st
    -rw     725911 Apr  7 22:57 lib3r2.zoo
    c:\gap\ > |

Rename the executable  to something more  sensible.  If you want to start
{\GAP} from the desktop you should use the name 'gap.ttp' so that you can
pass options (see "Features on the Atari ST").  If  you only start {\GAP}
from within a shell the name probably does not matter.

|    c:\gap\ > mv gapexe.st gap.ttp
    c:\gap\ > |

Make a subdirectory  for the library.  Usually  this is  the subdirectory
'lib'.  Other names  are possible, but then you  need to pass the name of
the library subdirectory as an option whenever you start {\GAP}.  Using a
nonstandard name only  makes sense when you  want to work  with different
libraries (as do the developers of {\GAP}), but this is very unlikely.

|    c:\gap\ > mkdir lib
    c:\gap\ > |

Now  change  into  this subdirectory and unpack the library from the  zoo
archive.  Note that you must be in the library subdirectory to unpack the
library.  After you have unpacked the library  remove  the *archive-file*
and change back into the parent directory.

|    c:\gap\ > cd lib
    c:\gap\lib\ > zoo x ..\lib3r2.zoo
    # 'zoo' prints the name of each file as it is extracted
    c:\gap\lib\ > ls
    abattoir.g    ctautoms.g    fpsgpres.g    matgrp.g      permprod.g
    agcent.g      ctbasic.g     fptietze.g    matring.g     permutat.g
    agclass.g     ctcharac.g    gaussian.g    matrix.g      polyfin.g
    agcomple.g    ctfilter.g    group.g       module.g      polyfld.g
    agcoset.g     ctgapmoc.g    grpcoset.g    numfield.g    polynom.g
    agctbl.g      ctgeneri.g    grpctbl.g     numtheor.g    polyrat.g
    aggroup.g     ctlattic.g    grpelms.g     onecohom.g    pq.g
    aghall.g      ctmapcon.g    grphomom.g    operatio.g    rational.g
    aghomomo.g    ctmapusi.g    grpprods.g    permag.g      recsl.g
    aginters.g    ctpermch.g    init.g        permbckt.g    ring.g
    agnorm.g      ctpgrp.g      integer.g     permcose.g    rowmodul.g
    agprops.g     ctsymmet.g    lattag.g      permcser.g    rowspace.g
    agsubgrp.g    cyclotom.g    lattgrp.g     permctbl.g    string.g
    agwords.g     domain.g      lattperf.g    permgrp.g     tom.g
    cdaggrp.g     field.g       lattperm.g    permhomo.g    vecspace.g
    chevgrp.g     finfield.g    list.g        permnorm.g
    combinat.g    fpgrp.g       mapping.g     permoper.g
    c:\gap\lib\ > rm ..\lib3r2.zoo
    c:\gap\lib\ > cd ..
    c:\gap\ > |

Start {\GAP} and try a few things.  Note that {\GAP} has  to read most of
the library for the fourth statement below,  so this takes quite a while.
Subsequent definitions of groups will be much faster.

|    c:\gap\ > gap
    gap> 2 * 3 + 4;
    10
    gap> Factorial( 30 );
    265252859812191058636308480000000
    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> IsSimple( M11 );
    true |

Especially try the command  line editing  and history facilities, because
the 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 three commands typing\\
<ctr>-'P' <ctr>-'P' <ctr>-'E' <ctr>-'B'
<ctr>-'B' <ctr>-'B' <ctr>-'B' <ctr>-'D' '1'\\
should give the following line.

|    gap> Factors( 7921 );
    [ 89, 89 ] |

If you start {\GAP}  from another place, i.e.,  not from within the 'gap'
directory,  you  will  have to   specify  the full  path   to the library
subdirectory.

|    c:\gap\ > cd ..
    c:\ > gap\gap
    gap: hmm, I cannot find 'lib\init.g', maybe use option '-l <libname>'?
    gap> quit;
    c:\ > gap\gap -l c:\gap\lib\
    gap> Gcd( 123, 66 );
    3
    gap> quit;
    c:\ > cd gap
    c:\gap\ > |

Unpack the documentation into  a  subdirectory 'doc'.  The  documentation
serves both as {\LaTeX} source for the printed manual and as online help.
Because the documentation files also  serves  as online  help, you do not
want to remove them, unless space is very tight, and you are content with
the printed manual.

|    c:\gap\ > mkdir doc
    c:\gap\ > cd doc
    c:\gap\doc\ > zoo x ..\doc3r2.zoo
    # 'zoo' prints the name of each file as it is extracted
    c:\gap\doc\ > ls
    aboutgap.tex  environm.tex  language.tex  numfield.tex  rowspace.tex
    aggroup.tex   field.tex     list.tex      numtheor.tex  set.tex
    agwords.tex   finfield.tex  manual.bbl    operatio.tex  share.tex
    anupq.tex     fpgrp.tex     manual.bib    paramaps.tex  string.tex
    blister.tex   gaussian.tex  manual.idx    permgrp.tex   tom.tex
    boolean.tex   gentable.tex  manual.ind    permutat.tex  unknown.tex
    characte.tex  gettable.tex  manual.tex    polynom.tex   vecspace.tex
    chartabl.tex  group.tex     manual.toc    preface.tex   vector.tex
    combinat.tex  grplib.tex    mapping.tex   range.tex     weyl.tex
    copyrigh.tex  homomorp.tex  matgrp.tex    rational.tex  word.tex
    cyclotom.tex  install.tex   matring.tex   record.tex
    domain.tex    integer.tex   matrix.tex    ring.tex
    c:\gap\doc\ > rm ..\doc3r2.zoo
    c:\gap\doc\ > |

If you have a big version of {\LaTeX} available you  may now want to make
a printed copy  of the manual.  Change into  the directory 'doc/' and run
{\LaTeX} *twice* on the source.   The  first pass with {\LaTeX}  produces
the '.aux'  files,  which resolve all the  cross  references.  The second
pass produces  the final  formatted  *dvi* file 'manual.dvi'.  This  will
take quite  a while, since  the  manual is  large.  Then print  the *dvi*
file.  How you actually print the 'dvi' file produced by {\LaTeX} depends
on the  printer you have, the version  of {\LaTeX}  you have, and whether
you use a {\TeX}-shell   or not, so  we will  not attempt to  describe it
here.

|    c:\gap\doc\ > latex manual
    # about 2000 messages about undefined references
    c:\gap\doc\ > latex manual
    # there should be no warnings this time
    c:\gap\doc\ > ls -l manual.dvi
    -rw   2591132 Apr  7 23:29 manual.dvi
    c:\gap\doc\ > cd ..
    c:\gap\ > |

Note that because of the large  number of  cross references in the manual
you need a *big*  {\LaTeX} to format the {\GAP}  manual.  If you  see the
error message  'TeX capacity  exceeded', you do  not have a big {\LaTeX}.
In this case  you  may also  obtain the  already    formatted *dvi*  file
'manual.dvi' from  the  same place where   you obtained the   rest of the
{\GAP} distribution.

Note that, apart   from   the  '\*.tex' files  and the file  'manual.bib'
(bibliography database),  which you absolutely need, we  supply  also the
files 'manual.toc' (table of   contents), 'manual.ind' (unsorted  index),
'manual.idx' (sorted  index), and  'manual.bbl' (bibliography).  If those
files are missing, or  if you prefer  to do everything  yourself, here is
what you will have to do.  After  the first  pass with {\LaTeX}, you will
have  preliminary 'manual.toc' and  'manual.ind'  files.   All  the  page
numbers are  still incorrect, because the  do not account  for  the pages
used by  the table of contents itself.   Now 'bibtex  manual' will create
'manual.bbl' from 'manual.bib'.  After  the second pass with {\LaTeX} you
will  have a  correct   'manual.toc'  and 'manual.ind'.  'makeindex'  now
produces the sorted index 'manual.idx' from 'manual.ind'.  The third pass
with {\LaTeX} incorporates this index into the manual.

|    c:\gap\doc\ > latex manual
    # about 2000 messages about undefined references
    c:\gap\doc\ > bibtex manual
    # 'bibtex' prints the name of each file it is scanning
    c:\gap\doc\ > latex manual
    # still some messages about undefined citations
    c:\gap\doc\ > makeindex manual
    # 'makeindex' prints some diagnostic output
    c:\gap\doc\ > latex manual
    # there should be no warnings this time
    c:\gap\doc\ > lp -dvi manual.dvi
    c:\gap\doc\ > cd ..
    c:\gap\ > |

If you have also fetched 'grp3r2.zoo', 'two3r2.zoo', and/or 'tbl3r2.zoo',
you may now want to unpack those into subdirectories 'grp', 'two', and/or
'tbl' in  a corresponding  way.  Alternatively  you can  do this  anytime
later.

Thats  all, finally you  are  done.  We  hope  that you  will enjoy using
{\GAP}.  If you have problems, do not hesitate to contact us.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Features on the Atari ST}%
\index{features!under TOS}\index{TOS!features}%
\index{options!under TOS}\index{TOS!options}%
\index{.gaprc}

When you  start  {\GAP} on  the Atari  ST, you may   specify a  number of
options  on the command-line to  change the default  behaviour of {\GAP}.
All these  options start with a hyphen  '-', followed by a single letter.
Options must not be grouped, e.g., 'gap -gq' is  illegal, use 'gap -g -q'
instead.   Some options require an argument,  this must follow the option
and  must  be separated by a   <space>, e.g., 'gap  -m  256k',  it is not
correct to say 'gap -m256k' instead.

You must declare {\GAP}  as TOS-takes-parameter program   if you want  to
specify command-line options  when you start  {\GAP}  by double clicking.
This means that the  name of the {\GAP} program  file must be  'gap.ttp'.
When you start {\GAP} from a shell, such  as 'gulam.tos', the name of the
program file  does  not matter.  The   Atari ST version, unlike  the UNIX
versions, does not distuingish upper and lower case for options.

'-g'

The options '-g' tells {\GAP} to print a information message every time a
garbage collection is performed.

|    #G collect garbage, 1931 used, 5012 dead, 912 KB free, 3072 KB total|

For example, this tells you that there are 1931 live objects that surived
a garbage collection, that 5012 unused objects  were reclaimed by it, and
that 912 KByte of totally allocated 3072 KBytes are available afterwards.

'-l <libname>'

The option '-l'  tells {\GAP} that the library of {\GAP} functions  is in
the  directory <libname>.  Per  default  <libname> is 'lib/',  i.e.,  the
library is normally  expected  in the  subdirectory 'lib/' of the current
directory.  {\GAP} searches for the library files, whose filenames end in
'.g', and which contain the functions initially known to {\GAP},  in this
directory.  <libname> should  end with a  pathname separator,  i.e., '/',
but {\GAP} will silently add one if it is missing.   {\GAP} will read the
file '<libname>/init.g' during  startup.  If {\GAP} cannot find this file
it will print the following warning

|    gap: hmm, I cannot find 'lib/init.g', maybe use option '-l <lib>'?|

If you  want a bare bones {\GAP},  i.e., if you do  not  need any library
functions, you may ignore this warning, otherwise you should leave {\GAP}
and start  it again, specifying the correct  library path  using the '-l'
option.

It is  also possible  to  specify several  alternative library  pathes by
separating them  with semicolons ';'.   Note  that in this case  all path
names must end with the pathname separator '/'.   {\GAP} will then search
for its library files in all those directories in turn, reading the first
it finds.  E.g., if you specify '-l \"lib/;/usr/local/lib/gap/3.2/lib/\"'
{\GAP} will search for a library file first in the subdirectory 'lib/' of
the current directory, and if it does not find it there in the  directory
'/usr/local/lib/gap/3.2/lib/'.  This way you can built your own directory
of {\GAP} library files that override the standard ones.

{\GAP}  searches for the group files,  whose filenames end in '.grp', and
which contain the groups initially known to  {\GAP}, in the directory one
gets by replacing the string 'lib' in <libname> by the  string 'grp'.  If
you do not want  to put the group  directory 'grp/' in the same directory
as the 'lib/' directory,  for example if you want  to put the groups onto
another   hard  disk  partition,  you have  to   edit the   assignment in
'<libname>/init.g' that reads

|    GRPNAME := ReplacedString( LIBNAME, "lib/;", "grp/;" );|

This path  can also consist of  several  alternative  pathes, just as the
library path.  If the library path consists of several alternative pathes
the default value for this path will consist of the same pathes, where in
each component the last occurrence of 'lib/' is replaced by 'grp/'.

Similar considerations    apply to   the  character  table  files.  Those
filenames end in '.tbl'.   {\GAP} looks for  those files in the directory
given  by 'TBLNAME'.  The default  value   for 'TBLNAME'  is  obtained by
replacing 'lib' in <libname> with 'tbl'.

'-h <docname>'

The option '-h' tells {\GAP} that the on-line  documenation for {\GAP} is
in  the  directory <docname>.   Per  default  <docname>  is  obtained  by
replacing 'lib' in  <libname> with 'doc'.  <docname>  should  end with  a
pathname  separator, i.e., '/', but {\GAP} will silently add one if it is
missing.  {\GAP} will read the file '<docname>/manual.toc' when you first
use the help system.  If {\GAP}  cannot find this file it  will print the
following warning

|    help: hmm, I cannot open the table of contents file 'doc/manual.toc'
    maybe you should use the option '-h <docname>'?|

'-m <memory>'

The option '-m' tells {\GAP} to  allocate <memory> bytes at startup time.
If the last character of <memory> is 'k' or 'K' it is taken in KBytes and
if the last character is 'm' or 'M' <memory> is taken in MBytes.

On the Atari ST {\GAP} will by default allocate all available memory.  If
you specify  '-m <memory>'  {\GAP} will only  allocate  that much memory,
unless <memory> is  larger  than the  default,  in that case  {\GAP} will
fail.   If you speficy a negative  amount  {\GAP} leaves that much memory
unallocated.  You may want to do this so that it is possible to run other
programs from inside {\GAP} with the  'Exec' command, for example 'gap -m
-256k'  will leave 256 KByte unallocated,  enough to  run MicroEMACS from
inside {\GAP}.

'-n'

The  options  '-n' tells {\GAP} to  disable  the line editing and history
(see "Line Editing").

There does not seem to be a good reason to do this on the Atari ST.

'-b'

The option '-b'  tells {\GAP} to  surpress the banner.  That  means  that
{\GAP} immediately prints the prompt.  This is useful  when you get tired
of the banner after a while.

'-q'

The  option '-q' tells  {\GAP} to be quiet.  This  means that {\GAP} does
not  display the banner and the  prompts 'gap>'.  This  is useful  if you
want to run {\GAP} as a filter with input and output redirection and want
to avoid the the banner and the prompts clobber the output file.

'-x <length>'

With this  option you can tell  {\GAP} how long   lines are.  {\GAP} uses
this value to decide when to split long lines.

The default value is 80,  which  is correct if  you start {\GAP} from the
desktop or one of the usual shells.  However, if you  start {\GAP} from a
window shell such as 'gemini', you may want to decrease  this  value.  If
you have a larger monitor, or use a smaller font, or  redirect the output
to a printer, you may want to increase this value.

'-y <length>'

With this  option you can  tell {\GAP} how  many lines  your  screen has.
{\GAP} uses this value to decide after how  many lines of on-line help it
should display |-- <space> for more --|.

The default value is  24, which is  the right value  if  you start {\GAP}
from the desktop or one  of  the  usual shells.   However, if  you  start
{\GAP} from a window  shell such as 'gemini',   you may want  to decrease
this value.  If  you  have a larger monitor,  or use  a smaller  font, or
redirect the output to a printer, you may want to increase this value.

Further arguments are taken as filenames of files that are read by {\GAP}
during startup, after '<libname>/init.g'  is  read, but before the  first
prompt is printed.  The files are read in the order  in  that they appear
on the  command  line.   {\GAP} only accepts 14  filenames on the command
line.  If a file cannot be opened {\GAP} will print an error  message and
will abort.

When you start {\GAP}, it looks  for  the file  with the name 'gap.rc' in
your  homedirectory (i.e., the   directory   defined by  the  environment
variable     'HOME').  If  such   a file  is    found it   is read  after
'<libname>/init.g', but before any of the  files mentioned on the command
line are read.   You can use  this file for your private  customizations.
For example, if you  have a file  containing  functions  or data that you
always need, you could read this from 'gap.rc'.   Or if you find  some of
the names in  the  library too long,  you could define abbreviations  for
those names in 'gap.rc'.  The following sample 'gap.rc' file does both.

|    Read("c:\\gap\\dat\\mygroups.grp");
    Op := Operation;
    OpHom := OperationHomomorphism;
    RepOp := RepresentativeOperation;
    RepsOp := RepresentativesOperation; |

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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 lets take  a look at the minimal  support that {\GAP} needs from  the
operating system and the machine.

First  of all  you need enough   filespace.  The  kernel sources  and the
object files need between 3 MByte and 3.5 MByte, depending on the size of
object  files produced  by  your compiler.    The   library takes up   an
additional 2 MBytes, and the online documentation also needs 2 MByte.  So
you need about 8 MByte of available filespace, for example on a harddisk.

Next  you need  enough main memory  in  your computer.   The  size of the
{\GAP} kernel  varies between different  machine,  with as little as  300
KByte  (compiled with GNU C  on  an Atari ST)   and as much  as 600 KByte
(compiled with UNIX  cc  on a  HP 9000/800).   Add  to that the fact  the
library of functions that {\GAP} loads takes up another 400 KByte.  So it
is  clear that at least 2   MByte of main memory   are required to do any
serious work with {\GAP}.

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
80386  or Intel  80486  processor under  extended DOS in protected 32 bit
mode.  (This is also necessary, because, as mentioned below, {\GAP} wants
to view its memory as a large flat address space.)

Next lets 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.

However, it is probably necessary that the compiler has a default integer
size of 32   bits, i.e., 'sizeof(int)'  should be  4  not 2.  It  may  be
possible  to fix all the  places where 32 bit  'int's are assumed, but we
assume that it will be easier to get a 32 bit compiler.

The most critical aspect probably is that  the {\GAP} kernel needs a flat
address space.  There are especially two systems where this is a problem.

The first is MS-DOS with its segments.  As  was already  mentioned above,
we circumvent this by using an extended DOS in protected  32 bit  mode on
PC compatibles with an Intel 386 or Intel 486 processor.

The other system is the Macintosh.  On the Macintosh the operating system
wants   to deal out   the  memory only in  small  chunks,  and also wants
programs to allow it to move those chunks to the  disk temporarily.  This
is because Apple  wanted to support programs  that used quite some memory
on its  initial Macs, which had  only 512 KByte   of memory, without true
virtual memory  support.  Thus  they forced  the application programs  to
simulate virtual memory.  {\GAP} does not do this.  Probably the best way
to  deal with that  is to allocate  as much memory  as one can get in one
large chunk,  while leaving enough memory  free for the operating system,
and to    lock  this chunk  in   memory.  Such  behaviour   is considered
uncooperative, but it is the best {\GAP} can do without a major rewrite.

The  two points  mentioned above  are necessary,   because  most parts of
{\GAP} depend on those features.  All other dependencies on the operating
system or  compiler should be  separated   in one  special file which  is
called the  'system' file.   When  you  port  {\GAP}  to a  new operating
system, you  probably  have to create  a  new 'system' file.  You  should
however look through the  'system' files that  we supply and take as much
code   from  them  as  possible.  Currently   we supply  'system.bsd' for
Berkeley  UNIX, 'system.usg' for System V  UNIX, and  'system.st' for the
Atari ST running TOS with the  GNU C compiler.  As  you will notice, when
you do this, most of  the code in those  three files is again  identical.
This is not surprising.  Most C compilers today  come with a library that
more or less resembles the standard library available under UNIX.

The 'system' file contains the following functions.

First  file  input and output.  The   functions used by  the three system
files mentioned above are 'fopen', 'fclose',  'fgets', and 'fputs'.  They
are pretty standard, and in fact are in the ANSI C standard library.  The
only thing that may be necessary is to make sure that files are opened in
text  mode.  However, the most  important transformation  applied in text
mode seems to be to replace  the end of line sequence <newline>-<return>,
used in some  operating  systems, with a  single  <newline>, used  in  C.
However, since  {\GAP} treats <newline> and  <return> both as whitespaces
even this is not absolutely necessary.

Second you need  character oriented input  from the keyboard   and to the
screen.  This is not absolutely necessary, you can  use the line oriented
input and output described above.  However, if  you want the  history and
the command  line editing, {\GAP}  must  be  able   to read every  single
character as the user types it without echo, and also must be able to put
single characters  to  the screen.    Reading  characters  unblocked  and
without echo is very  system dependent  (and  is  in fact the reason  why
there are   two 'system' files for  UNIX,  one for  Berkeley  and one for
System V).

Third you need a  way to detect if the  user typed <ctr>-'C' to interrupt
an   ongoing  computation   in  {\GAP}.  Again    this is not  absolutely
necessary,  you can   do without.   However  if you want  to   be able to
interrupt computations,  {\GAP} must be able to  receive  the  interrupt.
This can be done in two ways.  Under  UNIX you can  catch the signal that
is   generated  if   the  user types <ctr>-'C'  ('SIGINT').   Under other
operating systems that do not support such signals you can poll the input
stream at regular intervals and simply look for <ctr>-'C'.

Fourth you need a  way  to find out  how  long  {\GAP} has been  running.
Again this is not absolutely necessary.  You can  simply always return 0,
fooling  {\GAP} into  thinking that it  is extremly fast.  However if you
want timing statistics, {\GAP} must be able to find out how much CPU time
it has spent.

The  last and most important function  is the function to allocate memory
for {\GAP}.  {\GAP}  assumes that  it can allocate the initial  workspace
with the function  'SyGetmem' and expand this workspace  on  demand  with
further calls to 'SyGetmem'.  The  memory allocated by consequitive calls
to 'SyGetmem' must be  adjacent, because {\GAP}  wants to manage a single
large  block  of memory.  Usually this   can be done  with  the C library
function 'sbrk'.  If this does  not work, you  can define a  large static
array in  the  'system'  file and return  this  on    the  first call  to
'SyGetmem' and return 0  on subsequent calls  to indicate that this array
cannot dynamically be expanded.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E  Emacs . . . . . . . . . . . . . . . . . . . . . local Emacs variables
%%
%%  Local Variables:
%%  mode:               outline
%%  outline-regexp:     "\\\\Chapter\\|\\\\Section"
%%  fill-column:        73
%%  eval:               (hide-body)
%%  End:
%%