GAP runs on a large number of different operating systems. It behaves slightly different on each of those. This chapter describes the behaviour of GAP, the installation, and the options on some of those operating systems.
Currently it contains sections for UNIX (see GAP for UNIX), which runs on an ever increasing number of machines, for MS-DOS (see GAP for MS-DOS), which is one operating system on IBM PC compatibles, and TOS (see GAP for TOS), which is the operating system on Atari ST and MacOS (see GAP for MacOS), which is the operating system on Apple Macintosh computers.
For other systems the section Porting GAP gives hints how to approach such a port.
GAP is distributed free of charge. You can obtain it via ftp
and
give it away to your colleagues. GAP is not in the public domain,
however. In particular you are not allowed to incorporate GAP or
parts thereof into a commercial product.
If you get GAP, we would appreciate it if you could notify us, e.g.,
by sending a short e-mail message to gap@math.rwth-aachen.de
,
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. Specifically, please
refer to
[S+ 97] Martin Sch"onert et.al. GAP -- Groups, Algorithms, and Programming. Lehrstuhl D f"ur Mathematik, Rheinisch Westf"alische Technische Hochschule, Aachen, Germany, sixth edition, 1997.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 1600 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 processor under MS-DOS, Windows, or OS/2, for the Atari ST under TOS and Apple Macintosh using the CodeWarrior compiler. Note that about 8 MByte of main memory and about 20MB of disk space are required to run GAP. A full GAP installation, including all share packages and data libraries can use up to 100MB of disk space.
The easiest way to get GAP 3.4 for most users is probably via the
World Wide Web. The main GAP Web site is found at
http://www-gap.dcs.st-and.ac.uk/~gap
.
There are three mirror sites updated automatically each night, at:
http://www.math.rwth-aachen.de/LDFM/GAP http://www.ccs.neu.edu/Cobwebs/GAP and http://wwwmaths.anu.edu.au/algebra/GAP/WWW.
At these sites you can browse this manual, download the system and contributed extensions, read past postings to the GAP forum, and find out about authors of and contributors to GAP, publications that cited GAP andGAP related events.
GAP 3.4 can also be obtained by anonymous ftp from the following servers.
ftp-gap.dcs.st-and.ac.uk
:/pub/gap/gap/
.
ftp.math.rwth-aachen.de
:/pub/gap/
.
math.ucla.edu
:/pub/gap/
.
wuarchive.wustl.edu
:/edu/math/source.code/group.theory/gap
.
dehn.mth.pdx.edu
:/mirror/gap/
pell.anu.edu.au
:/pub/algebra/gap/
.
ftp
to the server closest to you, login as user ftp
and give your
full e-mail address as password. Remember when you transmit the files to
set the file transfer type to binary image, otherwise you will only
receive unusable garbage. Those servers will always have the latest
version of GAP available.
The ftp
directory contains the following files. Please check first
which files you need, to avoid transferring those that you don't need.
README
:
gap3r4p4.zoo
:zoo
archive approximately 18 MByte large.
unzoo.c
:zoo
archive extractor, which should be
used to unpack the distribution. The utils
subdirectory contains ready compiled executables
for common systems.
bin
:KERNELS
file tells you which executables are
here.
split
:SPLIT
file tells you which
archive contains what.
utils
:unzoo
and patch
. The UTILS
file tells you which
files are here.
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 Sun Sparcstations Sparc, Solaris 2.5 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 of GAP for UNIX describes how you install GAP on a UNIX machine, and the section Features of GAP for UNIX describe the options that GAP accepts under UNIX.
55.3 Installation of GAP for UNIX
Installation of GAP for UNIX is fairly easy.
First go to the directory where you want to install GAP. If you will
be the only user using GAP, you probably should install it in you
homedirectory. If other users will be using GAP also, you should
install it in a public place, such as /usr/local/lib/
. GAP will be
installed in a subdirectory gap3r4p4
of this directory. You can later
move GAP to a different location. For example you can first install
it in your homedirectory and when it works move it to /usr/local/lib/
.
In the following example we will assume that you, as user you
, want to
install GAP for your own use in your homedirectory on a DECstation
called ernie
. 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.
Get the distribution gap3r4p4.zoo
and the source for the zoo archive
extractor unzoo.c
. How you can get those files is described in the
section Getting GAP. The usual way would be to get it with ftp
onto
your machine. Remember that the distribution consists of binary files
and that you must transmit them in binary mode.
Compile the zoo archive extractor unzoo
with the command
you@ernie:~ > cc -o unzoo -DSYS_IS_UNIX -O unzoo.c you@ernie:~ > ls -l unzoo -rwxr-xr-x you 45056 Nov 3 10:11 unzoo you@ernie:~ >
Unpack the distribution with the command
you@ernie:~ > unzoo -x gap3r4p4.zoo gap3r4p4/bin/gap.sh -- extracted as text gap3r4p4/doc/aboutgap.tex -- extracted as text gap3r4p4/doc/aggroup.tex -- extracted as text # about 500 more lines gap3r4p4/two/twogpd8.grp -- extracted as text you@ernie:~ >
Change into the source directory gap3r4p4/src/
and execute make
to
see which compilation targets are predefined.
you@ernie:~ > cd gap3r4p4/src you@ernie:~/gap3r4p4/src > make usage: 'make <target>' where target is one of 'atari-m68k-tos-gcc2' for Atari ST under TOS with GNU cc 2 'dec-mips-ultrix-gcc2' for DECstation under Ultrix with GNU cc 2 'dec-mips-ultrix-cc' for DECstation under Ultrix with cc 'hp-hppa1.0-hpux-cc' for HP 9000/800 under HP-UX with cc 'hp-hppa1.1-hpux-cc' for HP 9000/700 under HP-UX with cc 'ibm-power-aix-cc' for IBM RS/6000 under AIX with cc 'ibm-i386-386bsd-gcc2' for IBM PC under 386BSD with GNU cc 2 'ibm-i386-386bsd-cc' for IBM PC under 386BSD with cc (GNU) 'ibm-i386-linux-gcc2' for IBM PC under Linux with GNU cc 2 'ibm-i386-dos-djgpp' for IBM PC under MSDOS with DJ GNU cc 'ibm-i386-os2-emx' for IBM PC under OS/2 with EMX GNU cc 'mips-mips-bsd-cc' for MIPS under RISC/os Berkeley with cc 'mips-mips-sysv-cc' for MIPS under RISC/os System V with cc 'next-m68k-mach-gcc2' for NEXTSTEP 3 on NeXT with GNU cc 2 'next-m68k-mach-cc' for NEXTSTEP 3 on NeXT with cc (GNU) 'next-i386-mach-gcc2' for NEXTSTEP 3 on IBM PC with GNU cc 2 'next-i386-mach-cc' for NEXTSTEP 3 on IBM PC with cc (GNU) 'sequent-i386-dynix-cc' for Sequent Symmetry under Dynix with cc 'sgi-mips-irix-gcc2' for SGI under Irix with GNU cc 2 'sgi-mips-irix-cc' for SGI under Irix with cc 'sun-m68k-sunos-gcc2' for SUN 3 under SunOS with GNU cc 2 'sun-m68k-sunos-cc' for SUN 3 under SunOS with cc 'sun-sparc-sunos-gcc2' for SUN 4 under SunOS with GNU cc 2 'sun-sparc-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., 'sun-sparc-sunos-gcc2' is better than 'sun-sparc-sunos-cc'. additional C compiler and linker flags can be passed with 'make <target> COPTS=<compiler-opts> LOPTS=<linker-opts>', i.e., 'make sun-sparc-sunos-gcc2 COPTS=-g LOPTS=-g.' you@ernie:~/gap3r4p4/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 system.c
fails or the command line editing
does not work, remove the file system.o
and try the other target. If
system.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 example the right target is obviously dec-mips-ultrix-cc
(remember ernie
was assumed to be a DECstation). Compile GAP.
you@ernie:~/gap3r4p4/src > make dec-mips-ultrix-cc cc -DSYS_IS_BSD -DSYS_HAS_ANSI=1 -c system.c cc -O2 -c gap.c # about 30 more lines you@ernie:~/gap3r4p4/src > ls -l gap -rwxr-xr-x you 711620 Nov 13 12:47 gap you@ernie:~/gap3r4p4/src >
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).
Copy or move the executable to the gap3r4p4/bin/
directory.
you@ernie:~/gap3r4p4/src > mv gap ../bin you@ernie:~/gap3r4p4/src > cd ../.. you@ernie:~ >
Then edit the shell script gap.sh
in the gap3r4p4/bin/
directory
according to the instructions in this file. This script will start
GAP and is the place for all necessary configurations. Then copy
this script to a directory in your search path, i.e., ~/bin/
. (If you
are using the C-shell, you will also have to rehash
, so that the
C-shell adds gap
to its internal tables).
you@ernie:~ > cd gap3r4p4/bin you@ernie:~/gap3r4p4/bin > cp gap.sh ~/bin/gap you@ernie:~/gap3r4p4/bin > cd ../.. you@ernie:~ >
When you later move GAP to another location you must only edit this script.
Now start GAP and try a few things. The -b
option suppresses the
banner. 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 -b 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> Number( ConjugacyClasses( m11 ) ); 10
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
.
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 gap3r4p4/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:~ > cd gap3r4p4/doc you@ernie:~/gap3r4p4/doc > latex manual # about 2400 messages about undefined references you@ernie:~/gap3r4p4/doc > latex manual # there should be no warnings this time you@ernie:~/gap3r4p4/doc > ls -l manual.dvi -rw-r--r-- you 4806136 Nov 3 23:28 manual.dvi you@ernie:~/gap3r4p4/doc > lp -dvi manual.dvi you@ernie:~/gap3r4p4/doc > cd ../.. you@ernie:~ >
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:~ > cd gap3r4p4/doc you@ernie:~/gap3r4p4/doc > latex manual # about 2000 messages about undefined references you@ernie:~/gap3r4p4/doc > bibtex manual #bibtex
prints the name of each file it is scanning you@ernie:~/gap3r4p4/doc > latex manual # still some messages about undefined citations you@ernie:~/gap3r4p4/doc > makeindex manual #makeindex
prints some diagnostic output you@ernie:~/gap3r4p4/doc > latex manual # there should be no warnings this time you@ernie:~/gap3r4p4/doc > lp -dvi manual.dvi you@ernie:~/gap3r4p4/doc > cd ../.. you@ernie:~ >
The full manual is, to put it mildly, now rather long (almost 1600
pages). For this reason, it may be more convenient just to print
selected chapters. This can be done using the \includeonly
LaTeX
command, which is present in manual.tex
(around line 240), but
commented out. To use this, you must first LaTeX the whole manual as
normal, to obtain the complete set of .aux
files and determine the
pages and numbers of all the chapters and sections. After that, you can
edit manual.tex
to uncomment the \includeonly
command and select the
chapters you want. A good start can be to include only the first chapter,
from the file aboutgap.tex
, by editing the line to read
\includeonly{aboutgap}
. The next step is to LaTeX the manual again.
This time only the selected chapter(s) and the table of contents and
indices will be processed, producing a shorter dvi
file that you can
print by whatever means applies locally.
you@ernie:~/gap3r4p4/doc > latex manual
# many messages about undefined references, 1600 pages output
you@ernie:~/gap3r4p4/doc > vi manual.tex
# edit line 241 to include only aboutgap
you@ernie:~/gap3r4p4/doc > latex manual
# pages 0-196 and 1503-1553 only output no warnings
you@ernie:~/gap3r4p4/doc > ls -l manual.dvi
-rw-rw-r-- 1 you 1277496 Apr 3 14:48 manual.dvi
# the full manual is nearly 5MB
you@ernie:~/gap3r4p4/doc > lp -d manual.dvi
Thats all, finally you are done. We hope that you will enjoy using GAP. If you have problems, do not hesitate to contact us.
When you start GAP for 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 for UNIX will only accept lower case options.
As is described in the previous section (see Installation of GAP for
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 necessary 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 survived 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 paths 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/gap3r4p4/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/gap3r4p4/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 paths, just as the
library path. If the library path consists of several alternative paths
the default value for this path will consist of the same paths, 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 documentation 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 4 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.
-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 suppress 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 clobbering 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;
This sections contain information about GAP that is specific to the port of GAP for IBM PC compatibles under MS-DOS or Windows (simply called GAP for MS-DOS below).
To run GAP for MS-DOS you need an IBM PC compatible with an Intel 80386, Intel 80486, or Intel Pentium processor, it will not run on IBM PC compatibles with an Intel 80186 or Intel 80286 processor. The system must have at least 4 MByte of main memory and a harddisk. The operating system must be MS-DOS version 5.0 or later or Windows 3.1 or later (earlier versions may work, but this has not been tested).
The section Copyright of GAP for MS-DOS describes the copyright as it applies to the executable version that we distribute. The section Installation of GAP for MS-DOS describes how you install GAP for MS-DOS, and the section Features of GAP for MS-DOS describes the special features of GAP for MS-DOS.
55.6 Copyright of GAP for MS-DOS
In addition to the general copyright for GAP set forth in the Copyright the following terms apply to GAP for MS-DOS.
The system dependent part for GAP for MS-DOS was written by Steve Linton. He assigns the copyright to the Lehrstuhl D fuer Mathematik. Many thanks to Steve Linton for his work.
The executable of GAP for MS-DOS that we distribute was compiled with
DJ Delorie's port of the Free Software Foundation's GNU C compiler
version 2.7.2. The compiler can be obtained by anonymous ftp
from a
variety of general public FTP archives. Many thanks to the Free Software
Foundation and DJ Delorie for this amazing piece of work.
The GNU C compiler is
Copyright (C) 1989, 1991 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA
under the terms of the GNU General Public License (GPL). Note that the GNU GPL states that the mere act of compiling does not affect the copyright status of GAP.
The 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.
55.7 Installation of GAP for MS-DOS
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 floppy disks.
First go to a directory where you want to install GAP, e.g., c:\
.
GAP will be installed in a subdirectory gap3r4p4\
of this directory.
You can later move GAP to another location, for example you can first
install it in d:\tmp\
and once it works move it to c:\
. In the
following example we assume that you want to install GAP in c:\
.
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.
Get the GAP distribution onto your IBM PC compatible. One usual way
would be to get the distribution with ftp
onto some UNIX workstation
and to download it from there onto your IBM PC compatible, for example
with kermit
. Remember that the distribution consists of binary files
and that you must transmit them in binary mode. Another possibility is
that you got a set of floppy disks.
If you get the distribution via ftp
, you must get the distribution
gap3r4p4.zoo
, the zoo archive extractor unzoo-ibm-i386-msdos.exe
,
which is in the subdirectory util
and which you should rename to
unzoo.exe
, and the executable bin3r4p4-ibm-i386-msdos.zoo
, which is
in the subdirectory bin
and which you should rename to bin3r4p4.zoo
.
You may have to get the latter 2 files from ftp.math.rwth-aachen.de
,
because some ftp
servers may not keep it. We recommend that you use
unzoo
even if you already have zoo
on your system, because unzoo
automatically translates text files to the appropriate local format.
If you got the distribution via ftp
unpack the executable and the
distribution with the following commands
C: > unzoo -x bin3r4p4.zoo gap3r4p4\bin\README.DOS -- extracted as text gap3r4p4\bin\gap.bat -- extracted as text gap3r4p4\bin\gapdjg.exe -- extracted as binary C: > unzoo -x gap3r4p4.zoo gap3r4p4\bin\gap.sh -- extracted as text gap3r4p4\doc\aboutgap.tex -- extracted as text gap3r4p4\doc\aggroup.tex -- extracted as text # about 500 more lines gap3r4p4\two\twogpd8.grp -- extracted as text C: >
If you got the executable and the distribution on disks, you must unpack
each of the zoo files separately with commands such as the following
(assuming that your disk drive is A:
)
C: > rem Insert the 1. disk. C: > copy a:\unzoo.exe . C: > unzoo -x a:\bin3r4p4.zoo gap3r4p4\bin\README.DOS -- extracted as text gap3r4p4\bin\gap.bat -- extracted as text gap3r4p4\bin\gapdjg.exe -- extracted as binary C: > unzoo -x a:\etc3r4p4.zoo gap3r4p4\etc\README -- extracted as text # about 20 more messages C: > unzoo -x a:\grp3r4p4.zoo gap3r4p4\grp\basic.grp -- extracted as text # about 10 more messages C: > unzoo -x a:\lib3r4p4.zoo gap3r4p4\lib\abattoir.g -- extracted as text # about 77 more messages C: > rem Insert the 2. disk. C: > unzoo -x a:\doc3r4p4.zoo gap3r4p4\doc\about.tex -- extracted as text # about 65 more messages C: > unzoo -x a:\two3r4p4.zoo gap3r4p4\two\twogp.grp # about 25 more messages C: > unzoo -x a:\thr3r4p4.zoo gap3r4p4\thr\thrgp.grp # about 10 more messages C: > rem Insert the 3. disk. C: > unzoo -x a:\tbl3r4x1.zoo gap3r4p4\tbl\ctbalter.tbl # about 50 more messages C: > rem Insert the 4. disk. C: > unzoo -x a:\tbl3r4x2.zoo gap3r4p4\tbl\ctomonst.tbl # about 10 more messages C: > unzoo -x a:\tom3r4p4.zoo gap3r4p4\tom\tmaltern.tom # about 10 more messages C: > unzoo -x a:\src3r4p4.zoo gap3r4p4\src\Makefile -- extracted as text # about 60 more messages C: > rem Insert the 5. disk. C: > unzoo -x a:\pkg3r4p4.zoo gap3r4p4\pkg\anupq\MakeLibrary\MakeLibray -- extracted as text # about 150 more messages C: >
Instead of using the executable that we provide in bin3r4p4.zoo
you can
compile GAP yourself if you have the DJGPP compiler installed. To do
this change into the source directory gap3r4p4\src
and compile GAP
with the commands
C: > chdir gap3r4p4\src C:\GAP3R4P4\SRC > make ibm-i386-msdos-djgpp gcc -DSYS_IS_MSDOS_DJGPP -DSYS_HAS_STRING_PROTO -DSYS_HAS_STDIO_PROTO\ -DSYS_HAS_MISC_PROTO -c system.c gcc -O2 -c gap.c # about 30 more messages C:\GAP3R4P4\SRC > copy gapdjg.exe ..\bin C:\GAP3R4P4\SRC > chdir ..\.. C: >
Change into the directory gap3r4p4\bin\
and edit the script gap.bat
,
which starts GAP, according to the instructions in this file. Then
copy this script to a directory in your search path, e.g., c:\bin\
,
with the commands
C: > chdir gap3r4p4\bin
C:\GAP3R4P4\BIN > edit gap.bat
# edit the script gap.bat
C:\GAP3R4P4\BIN > copy gap.bat c:\bin\gap.bat
C:\GAP3R4P4\BIN > chdir ..\..
C: >
When you later move GAP to another location you must only edit this script.
An alternative possibility is to compile a version of GAP for use
under MS-DOS, on a UNIX system, using a cross-compiler. Cross-compiling
versions of gcc
can be found on some FTP archives, or compiled
according to the instructions supplied with the gcc
source
distribution.
GAP must sometimes open more than 8 files at once. MS-DOS disallows
this, unless you add the following line to the file config.sys
on your
boot drive. You must then reboot for this change to take effect.
files=32
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 -b 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> Number( ConjugacyClasses( m11 ) ); 10
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 have a big version of LaTeX available you may now want to make
a printed copy of the manual. Change into the directory gap3r4p4\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: > chdir gap3r4p4\doc C:\GAP3R4P4\DOC > latex manual # about 2000 messages about undefined references C:\GAP3R4P4\DOC > latex manual # there should be no warnings this time C:\GAP3R4P4\DOC > dir manual.dvi -a--- 4591132 Nov 13 23:29 manual.dvi C:\GAP3R4P4\DOC > chdir ..\.. C: >
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: > chdir gap3r4p4\doc # about 2000 messages about undefined references C:\GAP3R4P4\DOC > bibtex manual #bibtex
prints the name of each file it is scanning C:\GAP3R4P4\DOC > latex manual # still some messages about undefined citations C:\GAP3R4P4\DOC > makeindex manual #makeindex
prints some diagnostic output C:\GAP3R4P4\DOC > latex manual # there should be no warnings this time C:\GAP3R4P4\DOC > chdir ..\.. C: >
The full manual is, to put it mildly, now rather long (almost 1600
pages). For this reason, it may be more convenient just to print
selected chapters. This can be done using the \includeonly
LaTeX
command, which is present in manual.tex
(around line 240), but
commented out. To use this, you must first LaTeX the whole manual as
normal, to obtain the complete set of .aux
files and determine the
pages and numbers of all the chapters and sections. After that, you can
edit manual.tex
to uncomment the \includeonly
command and select the
chapters you want. A good start can be to include only the first chapter,
from the file aboutgap.tex
, by editing the line to read
\includeonly{aboutgap}
. The next step is to LaTeX the manual again.
This time only the selected chapter(s) and the table of contents and
indices will be processed, producing a shorter dvi
file that you can
print by whatever means applies locally.
C:\GAP3R4P4\DOC > latex manual
# many messages about undefined references, 1600 pages output
C:\GAP3R4P4\DOC > edit manual.tex
# edit line 241 to include only aboutgap
C:\GAP3R4P4\DOC > latex manual
# pages 0-196 and 1503-1553 only output no warnings
C:\GAP3R4P4\DOC > dir manual.dvi
-a--- 1291132 Nov 13 23:29 manual.dvi
C:\GAP3R4P4\DOC >
# now print the DVI file in whatever way is appropriate
Thats all, finally you are done. We hope that you will enjoy using GAP. If you have problems, do not hesitate to contact us.
55.8 Features of GAP for MS-DOS
Note that GAP for MS-DOS 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 interrupt GAP.
The arrow keys left, right, up, down, home, end, and delete can be used for command line editing with their intuitive meaning.
Pathnames may be given inside GAP using either slash (/
) or
backslash (\
) as a separator (though \
must be escaped in strings of
course).
When you start GAP 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 for MS-DOS accepts the following (lowercase) 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 survived 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 paths 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\gap3r4p4\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\gap3r4p4\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 paths, just as the
library path. If the library path consists of several alternative paths
the default value for this path will consist of the same paths, 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 documentation 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.
GAP for MS-DOS will by default allocate 4 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 suppress 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 for MS-DOS 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;
This sections contain information about GAP that is specific to the port of GAP for Apple Macintosh systems under MacOS (simply called GAP for MacOS below).
To run GAP for MacOS you need to be written
The section Copyright of GAP for MacOS describes the copyright as it applies to the executable version that we distribute. The section Installation of GAP for MacOS describes how you install GAP for MacOS, and the section Features of GAP for MacOS describes the special features of GAP for MacOS.
55.10 Copyright of GAP for MacOS
to be written
55.11 Installation of GAP for MacOS
to be written
55.12 Features of GAP for MacOS
to be written
This sections contain information about GAP that is specific to the port of GAP for Atari ST systems under TOS (simply called GAP for TOS below). We no longer have access to any TOS systems, and so we have not tested GAP 3 release 4 patchlevel 4 on such a system, and cannot, at present supply a TOS binary. To the best of our knowledge, however, the system should work as described in this section.
To run GAP for TOS you need an Atari ST or Atari TT. The system must have at least 4 MByte of main memory and a harddisk. The operation system must be TOS 1.4 or later. Since GAP is a plain text application a monochrome monitor is probably best, but you may also use a color monitor.
The section Copyright of GAP for TOS describes the copyright as it applies to the executable version that we distribute. The section Installation of GAP for TOS describes how you install GAP for TOS, and the section Features of GAP for TOS describes the special features of GAP for TOS.
55.14 Copyright of GAP for TOS
In addition to the general copyright for GAP set forth in the copyright the following terms apply to the executable of GAP for TOS.
GAP for TOS was compiled with J. Bammi's port of the Free Software
Foundation's GNU C compiler version 2.5. The compiler is available by
anonymous ftp
from the ftp
server atari.archive.umich.edu
where it
is found in the directory atari/Gnustuff/Tos
. Many thanks to the Free
Software Foundation and J. Bammi for this amazing piece of work.
The GNU C compiler is
Copyright (C) 1989, 1991 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA
under the terms of the GNU General Public License (GPL). Note that the GNU GPL states that the mere act of compiling does not affect the copyright status of GAP.
The executable is linked with the GNU library gnu.obl
, which is
Copyright (C) 1991 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA
under the terms of the GNU Library General Public License (LGPL). The
terms of the LGPL require that we make the source code for the gnu.olb
available. They can be obtained by writing to Martin Schoenert (however,
it may be easier for you to ftp
them from atari.archive.umich.edu
yourself). They also require that we make GAP available in a form
that allows you to modify it, which we basically to anyhow.
55.15 Installation of GAP for TOS
Installation of GAP on an 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 floppy disks.
First go to a directory where you want to install GAP, e.g., c:\
.
GAP will be installed in a subdirectory gap3r4p4\
of this directory.
You can later move GAP to another location, for example you can first
install it in d:\tmp\
and once it works move it to c:\
. In the
following example we assume that you want to install GAP in c:\
.
We will also 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.
Get the GAP distribution onto your Atari ST. One usual way would be
to get the distribution with ftp
onto some UNIX workstation and to
download it from there onto your Atari ST, for example with kermit
.
Remember that the distribution consists of binary files and that you must
transmit them in binary mode. Another possibility is that you got a set
of floppy disks.
If you get the distribution via ftp
, you must get the distribution
gap3r4p4.zoo
, the zoo archive extractor unzoo-atari-m68k-tos.ttp
,
which is in the subdirectory util
and which you should rename to
unzoo.ttp
, and the executable bin3r4p4-atari-m68k-tos.zoo
, which is
in the subdirectory bin
and which you should rename to bin3r4p4.zoo
.
You may have to get the latter 2 files from samson.math.rwth-aachen.de
,
because some ftp
servers may not keep it. We recommend that you use
unzoo
even if you already have zoo
on your system, because unzoo
automatically translates text files to the appropriate local format.
If you got the distribution via ftp
unpack the executable and the
distribution with the following commands
C: > unzoo -x bin3r4p4.zoo gap3r4p4\bin\README.TOS -- extracted as text gap3r4p4\bin\gap.ttp -- extracted as binary C: > unzoo -x gap3r4p4.zoo gap3r4p4\bin\gap.sh -- extracted as text gap3r4p4\doc\aboutgap.tex -- extracted as text gap3r4p4\doc\aggroup.tex -- extracted as text # about 500 more lines gap3r4p4\two\twogpd8.grp -- extracted as text C: >
If you got the executable and the distribution on disks, you must unpack
them with the following commands (assuming that your disk drive is A:
)
C: > rem Insert the 1. disk. C: > copy a:\unzoo.exe . C: > unzoo -x a:\bin3r4p4.zoo gap3r4p4\bin\README.TOS -- extracted as text gap3r4p4\bin\gap.ttp -- extracted as binary C: > unzoo -x a:\etc3r4p4.zoo gap3r4p4\etc\README -- extracted as text # about 20 more messages C: > unzoo -x a:\grp3r4p4.zoo gap3r4p4\grp\basic.grp -- extracted as text # about 10 more messages C: > unzoo -x a:\lic3r4p4.zoo gap3r4p4\lib\ctautoms.g -- extracted as text # about 10 more messages C: > rem Insert the 2. disk. C: > unzoo -x a:\lib3r4p4.zoo gap3r4p4\lib\abattoir.g -- extracted as text # about 70 more messages C: > rem Insert the 3. disk. C: > unzoo -x a:\doc3r4p4.zoo gap3r4p4\doc\about.tex -- extracted as text # about 65 more messages C: > rem Insert the 4. disk. C: > unzoo -x a:\two3r4p4.zoo gap3r4p4\two\twogp.grp # about 25 more messages C: > unzoo -x a:\thr3r4p4.zoo gap3r4p4\thr\thrgp.grp # about 10 more messages C: > rem Insert the 5. disk. C: > unzoo -x a:\tom3r4p4.zoo gap3r4p4\tom\tmaltern.tom # about 10 more messages C: > rem Insert the 6. disk. C: > unzoo -x a:\src3r4p4.zoo gap3r4p4\src\Makefile -- extracted as text # about 60 more messages C: >
Instead of using the executable that we provide in bin3r4p4.zoo
you can
compile GAP yourself if you have the GNU C compiler installed. To do
this change into the source directory gap3r4p4\src\
and compile GAP
with the commands
C: > chdir gap3r4p4\src C:\GAP3R4P4\SRC > make atari-m68k-tos-gcc2 gcc -DSYS_IS_TOS_GCC2 -DSYS_HAS_MISC_PROTO -c system.c gcc -O2 -c gap.c # about 30 more messages C:\GAP3R4P4\SRC > copy gap.ttp ..\bin C:\GAP3R4P4\SRC > chdir ..\.. C: >
In either case now move the executable gap.ttp
from the gap3r4p4\bin\
subdirectory to the gap3r4p4\
directory. Then you can either start
GAP from the desktop by double clicking or from a shell such as Gulam
or bash
(in which case you must use -b
install-dir\gap3r4p4\lib\
option to tell GAP where to find the library).
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 -b 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> Number( ConjugacyClasses( m11 ) ); 10
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 have a big version of LaTeX available you may now want to make
a printed copy of the manual. Change into the directory gap3r4p4\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: > chdir gap3r4p4\doc C:\GAP3R4P4\DOC > latex manual # about 2000 messages about undefined references C:\GAP3R4P4\DOC > latex manual # there should be no warnings this time C:\GAP3R4P4\DOC > dir manual.dvi -a--- 2591132 Nov 13 23:29 manual.dvi C:\GAP3R4P4\DOC > chdir ..\.. C: >
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: > chdir gap3r4p4\doc # about 2000 messages about undefined references C:\GAP3R4P4\DOC > bibtex manual #bibtex
prints the name of each file it is scanning C:\GAP3R4P4\DOC > latex manual # still some messages about undefined citations C:\GAP3R4P4\DOC > makeindex manual #makeindex
prints some diagnostic output C:\GAP3R4P4\DOC > latex manual # there should be no warnings this time C:\GAP3R4P4\DOC > chdir ..\.. C: >
Thats all, finally you are done. We hope that you will enjoy using GAP. If you have problems, do not hesitate to contact us.
GAP for TOS will usually allocate all available memory. Note that
GAP for TOS does not support virtual memory, i.e., you can never use
more memory than this default gives you. If you specify -m memory
,
GAP will only allocate that much memory. If you specify a negative
amount, GAP leaves this much memory unallocated. You may want to do
this, so that that it is possible to run other programs from inside
GAP with the Exec
command.
The arrow keys left, right, up, and down can be used for command line editing with their intuitive meaning.
GAP for TOS supports UNIXMODE
, i.e., if the environment variable
UNIXMODE
is set to an appropriate value such as /.,rCLAHbd
, GAP
will emulate a UNIX style file system on top of the TOS filesystem. That
is GAP will accept pathnames with the /
as separator, which it will
automatically map to the TOS separator \
. It will also allow long
filenames (with more than 8+3 characters), which it will automatically
map to TOS filenames and remember the true filenames in a special file
.dir
. .dir
is used to symbolic links, which can be resolved by
GAP (to create then you need the GNU ln
program).
GAP for TOS runs as an ordinary TOS program. 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.
Apart from this everything works as described in this manual and you should not have any problems using GAP.
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. GAP for TOS, unlike the UNIX versions,
does not distinguish upper and lower case for options.
GAP for TOS accepts the following (lowercase) 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 survived 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 paths 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\gap3r4p4\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\gap3r4p4\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 paths, just as the
library path. If the library path consists of several alternative paths
the default value for this path will consist of the same paths, 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 documentation 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.
GAP for TOS 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 specify 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 an Atari ST.
-b
The option -b
tells GAP to suppress 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 for TOS checks in regular intervals whether the user has entered
ctr-Z
or alt-C
to interrupt an ongoing computation. Under TOS
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;
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.5 MByte and 4 MByte, depending on the size of object files produced by your compiler. The library takes up an additional 4.8 MBytes, and the online documentation also needs 4 MByte. So you need about 13 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 1.5 MByte. So it is clear that at least 4 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, Intel 80486, Pentium or Pentium Pro 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. In particular, it
is not possible to run GAP version 3 on machines with 64 bit integers
or 64 bit pointers. This will be corrected in version 4.
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.c
file that we supply and take as much
code from them as possible. Currently system.c
supports Berkeley UNIX,
System V UNIX, IBM PC compatibles under MS-DOS with the DJGPP compiler,
and the Atari ST under TOS with the GNU C compiler.
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.
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 extremely 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 consecutive 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.
Previous Up Next
Index
GAP 3.4.4