55 Getting and Installing GAP

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

Subsections

  1. Getting GAP
  2. GAP for UNIX
  3. Installation of GAP for UNIX
  4. Features of GAP for UNIX
  5. GAP for MS-DOS
  6. Copyright of GAP for MS-DOS
  7. Installation of GAP for MS-DOS
  8. Features of GAP for MS-DOS
  9. GAP for MacOS
  10. Copyright of GAP for MacOS
  11. Installation of GAP for MacOS
  12. Features of GAP for MacOS
  13. GAP for TOS
  14. Copyright of GAP for TOS
  15. Installation of GAP for TOS
  16. Features of GAP for TOS
  17. Porting GAP

55.1 Getting GAP

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:

School of Mathematical and Computational Sciences,
University of St Andrews, Scotland
directory /pub/gap/gap/.

ftp.math.rwth-aachen.de:

Lehrstuhl D fur Mathematik, RWTH Aachen, Germany,
directory /pub/gap/.

math.ucla.edu:

Math. Dept., Univ. of California at Los Angeles,
directory /pub/gap/.

wuarchive.wustl.edu:

Math. Archives, Washington Univ. at St. Louis,
directory /edu/math/source.code/group.theory/gap.

dehn.mth.pdx.edu:

PSU Mathematics Department, Portland State Univ.,
directory /mirror/gap/

pell.anu.edu.au:

School of Mathematical Sciences, Australian National Univ., Canberra,
directory /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:

the file you are currently reading.

gap3r4p4.zoo:

This file contains the complete distribution of GAP version 3 release 4 current patchlevel 4. It is a zoo archive approximately 18 MByte large.

unzoo.c:

A simple zoo archive extractor, which should be used to unpack the distribution. The utils subdirectory contains ready compiled executables for common systems.

More files are in the following subdirectories:

bin:

This directory contains executables for systems that dont come with a C compiler or where another C compiler produces a faster executable. The KERNELS file tells you which executables are here.

split:

This directory contains the complete distribution of GAP 3r4p4 in several archives. This allows you to get only the parts that you are really interested in. The SPLIT file tells you which archive contains what.

utils:

This directory contains several utilities that you may need to get or upgrade GAP, e.g., unzoo and patch. The UTILS file tells you which files are here.

55.2 GAP for UNIX

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.

55.4 Features of GAP for UNIX

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.

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; 

55.5 GAP for MS-DOS

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; 

55.9 GAP for MacOS

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

55.13 GAP for TOS

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.

55.16 Features of GAP for TOS

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; 

55.17 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.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 ints 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
April 1997