%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %A install.tex GAP documentation Martin Schoenert %% %H @(#)$Id: install.tex,v 3.19 1994/07/08 09:52:27 vfelsch Rel $ %% %Y Copyright (C) 1993, Lehrstuhl D fuer Mathematik, RWTH Aachen, Germany %% %% This file describes the installation and features of \GAP\ on various OS. %% %% Currently UNIX, IBM PC compatibles under MS-DOS, Windows, or OS/2, and %% the Atari ST under TOS on the Atari ST are available. We hope to provide %% ports to DEC VAX or AXP systems under VMS and the Apple Macintosh under %% MPW soon. %% %% To read about the system you are interested in, search for the string %% 'Section{GAP for }', e.g., 'Section{GAP for UNIX}'. %% %H $Log: install.tex,v $ %H Revision 3.19 1994/07/08 09:52:27 vfelsch %H updated release number %H %H Revision 3.18 1994/03/23 09:43:05 fceller %H changed internet address of pell %H %H Revision 3.17 1993/11/09 00:08:10 martin %H updated installation descriptions %H %H Revision 3.16 1993/05/06 11:35:47 fceller %H fixed a misspelling %H %H Revision 3.15 1993/04/15 18:03:42 fceller %H added 'dehn.mth.pdx.edu' %H %H Revision 3.14 1993/02/19 11:30:42 gap %H removed overfull hboxes %H %H Revision 3.13 1993/02/19 10:48:42 gap %H adjustments in line length and spelling %H %H Revision 3.12 1993/02/18 07:55:21 felsch %H some misprints removed %H %H Revision 3.11 1993/02/17 15:07:32 felsch %H example fixed %H %H Revision 3.10 1993/02/16 15:06:04 fceller %H fixed example, changed description of 'gapexe.next' %H %H Revision 3.9 1993/02/11 15:51:53 martin %H updated for 3.2 %H %H Revision 3.8 1992/05/25 18:09:39 martin %H added "Upgrading GAP" %H %H Revision 3.7 1992/05/22 08:58:45 martin %H added the sections for IBM PC compatibles %H %H Revision 3.6 1992/04/09 11:36:01 martin %H made a few changes so that two LaTeX passes suffice %H %H Revision 3.5 1992/04/07 22:48:42 martin %H fixed the examples %H %H Revision 3.4 1992/04/02 18:03:40 martin %H added the banner %H %H Revision 3.3 1992/03/25 15:49:27 martin %H changed the output of 'ls /doc' %H %H Revision 3.2 1992/03/23 12:37:54 martin %H added "Getting GAP" %H %H Revision 3.1 1992/03/23 11:58:51 martin %H improved the installation sections %H %H Revision 3.0 1991/12/27 16:10:27 martin %H initial revision under RCS %H %% \Chapter{Getting and Installing GAP}% \index{installation}\index{options} {\GAP} runs on a large number of different operating systems. It behaves slightly different on each of those. This chapter describes the behaviour of {\GAP}, the installation, and the options on some of those operating systems. Currently it contains sections for *UNIX* (see "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*. We hope to provide ports of {\GAP} to DEC VAX or AXP systems under VMS and the Apple Macintosh under MPW soon. For other systems the section "Porting GAP" gives hints how to approach such a port. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{Getting GAP}% \index{ftp} {\GAP} is distributed *free of charge*. You can obtain it via 'ftp' 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@samson.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. 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 900 pages. So it should be no problem to get {\GAP}, even if you have a rather uncommon system. Of course, ports to non UNIX systems may require some work. We already have ports for IBM PC compatibles with an Intel 80386 or 80486 under MS-DOS, Windows, or OS/2, and for the Atari ST under TOS. We hope to provide ports to DEC VAX or AXP systems under VMS and the Apple Macintosh under MPW soon. Note that about 4 MByte of main memory and a harddisk are required to run {\GAP}. {\GAP} 3.4 can be obtained by anonymous *ftp* from the following servers. 'samson.math.rwth-aachen.de':\\ Lehrstuhl D fur Mathematik, RWTH Aachen, Germany,\\ internet number 137.226.152.6,\\ directory '/pub/gap/'. 'dimacs.rutgers.edu':\\ DIMACS, Rutgers, New Brunswick, New Jersey,\\ internet number 128.6.75.16,\\ directory '/pub/gap/'. 'math.ucla.edu':\\ Math. Dept., Univ. of California at Los Angeles,\\ internet number 128.97.4.254,\\ directory '/pub/gap/'. 'wuarchive.wustl.edu':\\ Math. Archives, Washington Univ. at St. Louis,\\ internet number 128.252.135.4,\\ directory '/edu/math/source.code/group.theory/gap'. 'dehn.mth.pdx.edu':\\ PSU Mathematics Department, Portland State Univ.,\\ internet number 131.252.40.89,\\ directory '/mirror/gap/' 'pell.anu.edu.au':\\ School of Mathematical Sciences, Australian National Univ., Canberra,\\ internet number 150.203.33.4,\\ directory '/pub/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. For users in the United Kingdom with Janet access 'ftp' may not work. Please contact Derek Holt (e-mail address 'dfh@maths.warwick.ac.uk'). He has kindly offered us to distribute {\GAP} in the United Kingdom. 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. 'gap3r4p0.zoo':\\ This file contains the *complete* distribution of {\GAP} version 3 release 4 current patchlevel 0. It is a 'zoo' archive approximately 7 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} 3r4p0 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. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{Upgrading GAP} From time to time we will *upgrade* {\GAP}. There are generally two types of upgrades. The major upgrades create new *releases* and the minor are upgrades between releases. New releases usually introduce new features while upgrades between releases usually only fix bugs found in one release. Each version has a number. The number of a release consists of two parts. The first part is the *version number*, which is currently 3. The second part is the *release number*, which is 1 for the first release, 2 for the second, and so on. The current number is *version 3 release 4*, which we sometimes abbreviate to 'V3R4'. The number of a upgrade between releases consists of three parts. The first and second part are the version and release number of the current release. The third part is called the *patchlevel*. The first upgrade after a release has patchlevel 1, the second patchlevel 2, and so on. The current number is *version 3 release 4 patchlevel 0*, which we sometimes abbreviate to 'V3R4P0'. Because it might be too much work for you to obtain the complete distribution for every upgrade, we also make the differences between one upgrade and the next one available. They are stored in a single file, called an *upgrade file*. For example the differences between 'V3R4P0' and 'V3R4P1' will be stored in a file called 'upg3r4p1.dif'. Note that upgrade files always take you from one version to the next. So to upgrade to 'V3R4P2' you must first upgrade to 'V3R4P1'. To make it easier for you to apply an upgrade, the upgrade files are in a special format, called (unified) 'diff', which a special program, called 'patch', can understand. 'patch' reads the upgrade file and automatically makes all the necessary changes to the files. This program is available on most UNIX machines. However, we also make it available on the 'ftp' servers, so you can get it from there if your machine does not have one or if your machine has one that is too old to understand unified 'diff'-s. To apply an upgrade you need the sources for the parts of {\GAP} that you are interested in. This should at least be the sources, the library, and the documentation. You may also have the groups library, the primitive groups library, the 2-groups library, and the character table library. If an upgrade changes a file in one of the parts that you do not have, 'patch' will ask you about the file it cannot find. Then you can tell 'patch' to ignore this change, and it will continue to change those files it can find. In the following example, we assume that you (as user 'you') have all parts of {\GAP}, that {\GAP} is installed in the subdirectory 'gap/' of your homedirectory, and that you want to upgrade from 'V3R1' to 'V3R1P1'. The first thing of course is to get the upgrade file. The upgrade files are available at the same places as the rest of {\GAP} (see "Getting GAP"). If you are subscribed to the {\GAP}-forum, you will also get the upgrade files as e-mail messages. In this example we will assume that you have obtained the upgrade file 'upg3r1p1.dif' from one of the 'ftp' servers. | you@ernie:~/gap > ls -l drwxr-xr-x 2 you 1536 May 25 18:03 doc drwxr-xr-x 2 you 512 May 25 18:03 grp drwxr-xr-x 2 you 1536 May 25 18:02 lib drwxr-xr-x 2 you 1536 May 25 18:01 src drwxr-xr-x 2 you 1536 May 25 18:04 tbl drwxr-xr-x 2 you 1024 May 25 18:04 two -rw-r--r-- 1 you 123695 May 25 18:04 upg3r1p1.dif you@ernie:~/gap > | The first thing that you should do is always to read the beginning of the upgrade file. It contains instructions on how to apply the upgrade. You should always read this to see if there are special things that must be done before this upgrade can be applied. For example, before you can apply the upgrade from 'V3R1P1' to 'V3R1P2' you must first make a copy of the file 'src/system.st'. In our example, i.e., the upgrade from 'V3R1' to 'V3R1P1' no special tasks must be performed. Now you apply the upgrade with the following command. | you@ernie:~/gap > patch -p0 < upg3r1p1.dif Hmm... Looks like a unified diff to me... The text leading up to this was: -------------------------- !What is this file? !================== # 'patch' prints the introduction text, about 200 lines long !Now for the upgrade itself !========================== ! !diff -u doc/aboutgap.tex doc/aboutgap.tex !--- doc/aboutgap.tex Thu Apr 9 14:06:31 1992 !+++ doc/aboutgap.tex Thu Apr 30 14:38:06 1992 -------------------------- Patching file doc/aboutgap.tex using Plan A... Hunk |'\#'|1 succeeded at 6. Hunk |'\#'|2 succeeded at 13. Hunk |'\#'|3 succeeded at 493. Hunk |'\#'|4 succeeded at 529. Hunk |'\#'|5 succeeded at 1074. Hunk |'\#'|6 succeeded at 5168. Hmm... The next patch looks like a unified diff to me... The text leading up to this was: -------------------------- !diff -u doc/aggroup.tex doc/aggroup.tex !--- doc/aggroup.tex Thu Apr 9 14:06:33 1992 !+++ doc/aggroup.tex Thu Apr 30 14:20:05 1992 -------------------------- Patching file doc/aggroup.tex using Plan A... Hunk |'\#'|1 succeeded at 2. Hunk |'\#'|2 succeeded at 10. Hunk |'\#'|3 succeeded at 336. Hunk |'\#'|4 succeeded at 2708. # similar output for 70 more files, about 700 lines Hmm... The next patch looks like a unified diff to me... The text leading up to this was: -------------------------- !diff -u src/word.h src/word.h !--- src/word.h Fri Apr 3 20:56:34 1992 !+++ src/word.h Wed Apr 29 13:28:43 1992 -------------------------- Patching file src/word.h using Plan A... Hunk |'\#'|1 succeeded at 3. done you@ernie:~/gap > | See below about the things that could go wrong. For the moment we will assume that everything worked, i.e., that 'patch' did not complain. Next compile the source of the kernel again. How this is done is described in the installation sections (see "Installation of GAP for UNIX"). Note that it may not be necessary to do this if the source of the kernel did not change, or if the changes were only cosmetic. The introduction of the upgrade file will tell you if it is really necessary or not. Then {\LaTeX} the documentation again. How this is done is also described in the installation sections (see "Installation of GAP for UNIX", "Installation of GAP for MS-DOS", "Installation of GAP for TOS"). Again this may not be necessary, if the changes to the manual were only minor. Again the introduction of the upgrade file will tell you if it is really necessary or not. Now you may want to throw away the original files. 'patch' saves them by appending the suffix '.orig' to the original file name. So to remove all original files issue the following command. | you@ernie:~/gap > rm -f */*.orig you@ernie:~/gap > | There are several things that can go wrong. The first possibility is that you don\'t have 'patch'. In this case get 'patch', for example by anonymous 'ftp' from 'samson.math.rwth-aachen.de' (Internet number 137.226.152.6). Another possibility is that you have a version of 'patch' that is too old. Versions of 'patch' before 2.0.2.0 (patchlevel 12u4) don\'t understand the unified 'diff' format of this upgrade file. In this case you will see the following message. | you@ernie:~/gap > patch -p0 < upg3r1.dif Hmm... I can't seem to find a patch in there anywhere. you@ernie:~/gap > | To solve this problem, get a newer version of 'patch'. For example by anonymous 'ftp' from 'samson.math.rwth-aachen.de'. Another possibility is that you forgot the '-p0' option for 'patch'. In this case 'patch' assumes that the files to patch are all in the current directory (not in the subdirectories 'doc', 'grp', etc.). It can\'t find them there of course. Therefore it asks you for the names of the files to patch interactively. | you@ernie:~/gap > patch -p0 < upg3r1p1.dif Hmm... Looks like a unified diff to me... The text leading up to this was: -------------------------- !What is this file? !================== # 'patch' prints the introduction text, about 200 lines long !Now for the upgrade itself !========================== ! !diff -u doc/aboutgap.tex doc/aboutgap.tex !--- doc/aboutgap.tex Thu Apr 9 14:06:31 1992 !+++ doc/aboutgap.tex Thu Apr 30 14:38:06 1992 -------------------------- File to patch: | Stop 'patch' by hitting -'C', and start it anew, this time with the option '-p0'. Another possibility is that you already changed a file. For example if you already changed 'word.c', which could not be compiled with GNU cc on the NeXT, you will get the following message (note the message that hunk '\#3' failed). | you@ernie:~/gap > patch -p0 < upg3r1p1.dif # the usual output from 'patch' Hmm... The next patch looks like a unified diff to me... The text leading up to this was: -------------------------- !diff -u src/word.c src/word.c !--- src/word.c Sun Apr 5 23:29:44 1992 !+++ src/word.c Wed Apr 29 13:28:43 1992 -------------------------- Patching file src/word.c using Plan A... Hunk |'\#'|1 succeeded at 3. Hunk |'\#'|2 succeeded at 10. Hunk |'\#'|3 failed at 2094. Hunk |'\#'|4 succeeded at 2218. Hunk |'\#'|5 succeeded at 2469. 1 out of 5 hunks failed--saving rejects to src/word.c.rej # the rest of the output from 'patch' you@ernie:~/gap > | In this case examine the '\*.rej' files carefully after running 'patch'. They will tell you what 'patch' expected to find in the file, and what it really found. Then examine the source file itself to see if you can ignore the rejection, or if you should apply the patch manually. Another possibility is that 'patch' cannot find the files it should patch. For example, if you don\'t have the groups library installed 'patch' will give the following output. | you@ernie:~/gap > patch -p0 < upg3r1p1.dif # the usual output from 'patch' Hmm... The next patch looks like a unified diff to me... The text leading up to this was: -------------------------- !diff -u grp/permgrp.grp grp/permgrp.grp !--- grp/permgrp.grp Tue Apr 7 22:39:12 1992 !+++ grp/permgrp.grp Thu Apr 30 13:14:12 1992 -------------------------- File to patch: | Simply type to this question. 'patch' will ask you then. | No file found--skip this patch? [n] | Answer with 'y', i.e., tell 'patch' to ignore this file. 'patch' will then show the following output. | Skipping patch... Hunk |'\#'|1 ignored at 2. Hunk |'\#'|2 ignored at 9. Hunk |'\#'|3 ignored at 83. 3 out of 3 hunks ignored--saving rejects to grp/permgrp.grp.rej patch: can't create grp/permgrp.grp.rej, output is in /tmp/patchra22700. | Then it will continue to apply the other patches. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{GAP for UNIX}% \index{BSD}\index{4.2BSD}\index{4.3BSD}\index{ULTRIX}% \index{System V}\index{SysV}\index{HP-UX}\index{SunOS}% {\GAP} runs very well under UNIX. In fact it is being developed on UNIX workstations. {\GAP} running on any UNIX machine should behave exactly as described in the manual. {\GAP} has successfully been compiled and installed on the following UNIX machines. | Vendor, Model, Processor, System, Compiler DEC, DECstation 3100, MIPS R2000, Ultrix 4.0, cc and GNU gcc DEC, DECstation 5120, MIPS R3000, Ultrix 4.2, cc and GNU gcc HP, HP 9000/825, HP-PA 1.0, HP-UX 7.0, cc HP, HP 9000/720, HP-PA 1.1, HP-UX 8.0.5, cc IBM, POWERstation 530, RS/6000, AIX, cc IBM, PC, i386/i486, 386BSD, GNU gcc IBM, PC, i386/i486, Linux, GNU gcc MIPS, M120/5, MIPS R2000, RiscOS, cc NeXT, NeXTstation, MC68040, Mach, GNU gcc Sequent, Symmetry, ---, Dynix, cc, SGI, Iris, MIPS R3000, Irix, cc and GNU gcc Sun, Sun 3/60, MC68020, SunOS 4.0.1, cc and GNU gcc Sun, Sun 4/280, Sparc, SunOS 4.0.1, cc and GNU gcc| We hope that compiling and installing {\GAP} on another UNIX machine does not pose any problem. If it does, please inform us of your problems, and, if possible of your solution. The section "Installation 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 undex UNIX. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{Installation of GAP for UNIX}% \index{installation!under UNIX}\index{UNIX!installation} 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 'gap3r4p0' 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 'gap3r4p0.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 gap3r4p0.zoo gap3r4p0/bin/gap.sh -- extracted as text gap3r4p0/doc/aboutgap.tex -- extracted as text gap3r4p0/doc/aggroup.tex -- extracted as text # about 500 more lines gap3r4p0/two/twogpd8.grp -- extracted as text you@ernie:~ > | Change into the source directory 'gap3r4p0/src/' and execute 'make' to see which compilation targets are predefined. | you@ernie:~ > cd gap3r4p0/src you@ernie:~/gap3r4p0/src > make usage: 'make ' 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-msdos-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 NeXT under Mach with GNU cc 2 'next-m68k-mach-cc' for NeXT under Mach 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 COPTS= LOPTS=', i.e., 'make sun-sparc-sunos-gcc2 COPTS=-g LOPTS=-g.' you@ernie:~/gap3r4p0/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:~/gap3r4p0/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:~/gap3r4p0/src > ls -l gap -rwxr-xr-x you 711620 Nov 13 12:47 gap you@ernie:~/gap3r4p0/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 'gap3r4p0/bin/' directory. | you@ernie:~/gap3r4p0/src > mv gap ../bin you@ernie:~/gap3r4p0/src > cd ../.. you@ernie:~ > | Then edit the shell script 'gap.sh' in the 'gap3r4p0/bin/' directory according to the instructions in this file. This script will start {\GAP} and is the place for all neccessary 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 gap3r4p0/bin you@ernie:~/gap3r4p0/bin > cp gap.sh ~/bin/gap you@ernie:~/gap3r4p0/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 -'P' redisplays the last command, that -'E' moves the cursor to the end of the line, that -'B' moves the cursor back one character, and that -'D' deletes single characters. So, after entering the above commands, typing\\ -'P' -'P' -'E' -'B' -'B' -'B' -'B' -'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 -'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 'gap3r4p0/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 gap3r4p0/doc you@ernie:~/gap3r4p0/doc > latex manual # about 2400 messages about undefined references you@ernie:~/gap3r4p0/doc > latex manual # there should be no warnings this time you@ernie:~/gap3r4p0/doc > ls -l manual.dvi -rw-r--r-- you 2806136 Nov 3 23:28 manual.dvi you@ernie:~/gap3r4p0/doc > lp -dvi manual.dvi you@ernie:~/gap3r4p0/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 gap3r4p0/doc you@ernie:~/gap3r4p0/doc > latex manual # about 2000 messages about undefined references you@ernie:~/gap3r4p0/doc > bibtex manual # 'bibtex' prints the name of each file it is scanning you@ernie:~/gap3r4p0/doc > latex manual # still some messages about undefined citations you@ernie:~/gap3r4p0/doc > makeindex manual # 'makeindex' prints some diagnostic output you@ernie:~/gap3r4p0/doc > latex manual # there should be no warnings this time you@ernie:~/gap3r4p0/doc > lp -dvi manual.dvi you@ernie:~/gap3r4p0/doc > cd ../.. you@ernie:~ > | Thats all, finally you are done. We hope that you will enjoy using {\GAP}. If you have problems, do not hesitate to contact us. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{Features of GAP for UNIX}% \index{features!under UNIX}\index{UNIX!features}% \index{options!under UNIX}\index{UNIX!options}% \index{.gaprc} 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 , 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 neccessary to make {\GAP} work on your system. This means that the default settings mentioned below may not be what you experience when you execute {\GAP} on your system. '-g' The option '-g' tells {\GAP} to print a information message every time a garbage collection is performed. | #G collect garbage, 1931 used, 5012 dead, 912 KB free, 4096 KB total| For example, this tells you that there are 1931 live objects that surived a garbage collection, that 5012 unused objects were reclaimed by it, and that 912 KByte of totally allocated 4096 KBytes are available afterwards. '-l ' The option '-l' tells {\GAP} that the library of {\GAP} functions is in the directory . Per default 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. should end with a pathname separator, i.e., '/', but {\GAP} will silently add one if it is missing. {\GAP} will read the file '/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 '?| If you want a bare bones {\GAP}, i.e., if you do not need any library functions, you may ignore this warning, otherwise you should leave {\GAP} and start it again, specifying the correct library path using the '-l' option. It is also possible to specify several alternative library pathes by separating them with semicolons ';'. Note that in this case all path names must end with the pathname separator '/'. {\GAP} will then search for its library files in all those directories in turn, reading the first it finds. E.g., if you specify |-l "lib/;/usr/local/lib/gap3r4p0/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/gap3r4p0/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 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 '/init.g' that reads | GRPNAME := ReplacedString( LIBNAME, "lib", "grp" );| This path can also consist of several alternative pathes, just as the library path. If the library path consists of several alternative pathes the default value for this path will consist of the same pathes, where in each component the last occurrence of 'lib/' is replaced by 'grp/'. Similar considerations apply to the character table files. Those filenames end in '.tbl'. {\GAP} looks for those files in the directory given by 'TBLNAME'. The default value for 'TBLNAME' is obtained by replacing 'lib' in with 'tbl'. '-h ' The option '-h' tells {\GAP} that the on-line documenation for {\GAP} is in the directory . Per default is obtained by replacing 'lib' in with 'doc'. should end with a pathname separator, i.e., '/', but {\GAP} will silently add one if it is missing. {\GAP} will read the file '/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 '?| '-m ' The option '-m' tells {\GAP} to allocate bytes at startup time. If the last character of is 'k' or 'K' it is taken in KBytes and if the last character is 'm' or 'M' 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. 4 MByte is reasonable for single user workstations with 8 MByte or for multi user systems with more. '-n' The option '-n' tells {\GAP} to disable the line editing and history (see "Line Editing"). You may want to do this if the command line editing is incompatible with another program that is used to run {\GAP}. For example if {\GAP} is run from inside a GNU Emacs shell window, '-n' should be used since otherwise every input line will be echoed twice, once by Emacs and once by {\GAP}. '-b' The option '-b' tells {\GAP} to surpress the banner. That means that {\GAP} immediately prints the prompt. This is useful when you get tired of the banner after a while. '-q' The option '-q' tells {\GAP} to be quiet. This means that {\GAP} does not display the banner and the prompts 'gap>'. This is useful if you want to run {\GAP} as a filter with input and output redirection and want to avoid the the banner and the prompts clobber the output file. '-x ' 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 ' 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 |-- 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 '/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 '/init.g', but before any of the files mentioned on the command line are read. You can use this file for your private customizations. For example, if you have a file containing functions or data that you always need, you could read this from '.gaprc'. Or if you find some of the names in the library too long, you could define abbreviations for those names in '.gaprc'. The following sample '.gaprc' file does both. | Read("/usr/you/dat/mygroups.grp"); Op := Operation; OpHom := OperationHomomorphism; RepOp := RepresentativeOperation; RepsOp := RepresentativesOperation; | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{GAP for MS-DOS}% \index{GAP for MS-DOS}\index{MSDOS}\index{Windows} 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. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{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 (111 Ross St., Cambridge, CB1 3BS, UK, +44 223 411661, 'sl25@cus.cam.ac.uk'). He assignes 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.4. The compiler can be obtained by anonymous 'ftp' from 'grape.ecs.clarkson.edu' where it is in the directory 'pub/msdos/djgpp'. Many thanks to the Free Software Foundation and DJ Delorie for this amazing piece of work. The GNU C compiler is *Copyright (C) 1989, 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.* %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{Installation of GAP for MS-DOS}% \index{installation!under MS-DOS}\index{MS-DOS!installation} \index{installation!under Windows}\index{Windows!installation} Installation of {\GAP} on IBM PC compatibles is fairly easy. As already mentioned above, {\GAP} must be installed on a harddisk, because it is too large to be run from floppy disks. First go to a directory where you want to install {\GAP}, e.g., |c:\|. {\GAP} will be installed in a subdirectory |gap3r4p0\| 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 'gap3r4p0.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 'bin3r4p0-ibm-i386-msdos.zoo', which is in the subdirectory 'bin' and which you should rename to 'bin3r4p0.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 bin3r4p0.zoo gap3r4p0\bin\README.DOS -- extracted as text gap3r4p0\bin\gap.bat -- extracted as text gap3r4p0\bin\gapdjg.exe -- extracted as binary C: > unzoo -x gap3r4p0.zoo gap3r4p0\bin\gap.sh -- extracted as text gap3r4p0\doc\aboutgap.tex -- extracted as text gap3r4p0\doc\aggroup.tex -- extracted as text # about 500 more lines gap3r4p0\two\twogpd8.grp -- extracted as text C: > | If you got the executable and the distribution on disks, you must unpack them with the following comands (assuming that your disk drive is |A:|) | C: > rem Insert the 1. disk. C: > copy a:\unzoo.exe . C: > unzoo -x a:\bin3r4p0.zoo gap3r4p0\bin\README.DOS -- extracted as text gap3r4p0\bin\gap.bat -- extracted as text gap3r4p0\bin\gapdjg.exe -- extracted as binary C: > unzoo -x a:\etc3r4p0.zoo gap3r4p0\etc\README -- extracted as text # about 20 more messages C: > unzoo -x a:\grp3r4p0.zoo gap3r4p0\grp\basic.grp -- extracted as text # about 10 more messages C: > unzoo -x a:\lib3r4p0.zoo gap3r4p0\lib\abattoir.g -- extracted as text # about 77 more messages C: > rem Insert the 2. disk. C: > unzoo -x a:\doc3r4p0.zoo gap3r4p0\doc\about.tex -- extracted as text # about 65 more messages C: > unzoo -x a:\two3r4p0.zoo gap3r4p0\two\twogp.grp # about 25 more messages C: > unzoo -x a:\thr3r4p0.zoo gap3r4p0\thr\thrgp.grp # about 10 more messages C: > rem Insert the 3. disk. C: > unzoo -x a:\tbl3r4x1.zoo gap3r4p0\tbl\ctbalter.tbl # about 50 more messages C: > rem Insert the 4. disk. C: > unzoo -x a:\tbl3r4x2.zoo gap3r4p0\tbl\ctomonst.tbl # about 10 more messages C: > unzoo -x a:\tom3r4p0.zoo gap3r4p0\tom\tmaltern.tom # about 10 more messages C: > unzoo -x a:\src3r4p0.zoo gap3r4p0\src\Makefile -- extracted as text # about 60 more messages C: > rem Insert the 5. disk. C: > unzoo -x a:\pkg3r4p0.zoo gap3r4p0\pkg\anupq\MakeLibrary\MakeLibray -- extracted as text # about 150 more messages C: > | Instead of using the executable that we provide in 'bin3r4p0.zoo' you can compile {\GAP} yourself if you have the DJGPP compiler installed. To do this change into the source directory |gap3r4p0\src| and compile {\GAP} with the commands | C: > chdir gap3r4p0\src C:\GAP3R4P0\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:\GAP3R4P0\SRC > copy gapdjg.exe ..\bin C:\GAP3R4P0\SRC > chdir ..\.. C: > | Change into the directory |gap3r4p0\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 gap3r4p0\bin C:\GAP3R4P0\BIN > edit gap.bat # edit the script 'gap.bat' C:\GAP3R4P0\BIN > copy gap.bat c:\bin\gap.bat C:\GAP3R4P0\BIN > chdir ..\.. C: > | When you later move {\GAP} to another location you must only edit this script. {\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 -'P' redisplays the last command, that -'E' moves the cursor to the end of the line, that -'B' moves the cursor back one character, and that -'D' deletes single characters. So after entering the above three commands typing\\ -'P' -'P' -'E' -'B' -'B' -'B' -'B' -'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 |gap3r4p0\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 gap3r4p0\doc C:\GAP3R4P0\DOC > latex manual # about 2000 messages about undefined references C:\GAP3R4P0\DOC > latex manual # there should be no warnings this time C:\GAP3R4P0\DOC > dir manual.dvi -a--- 2591132 Nov 13 23:29 manual.dvi C:\GAP3R4P0\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 gap3r4p0\doc # about 2000 messages about undefined references C:\GAP3R4P0\DOC > bibtex manual # 'bibtex' prints the name of each file it is scanning C:\GAP3R4P0\DOC > latex manual # still some messages about undefined citations C:\GAP3R4P0\DOC > makeindex manual # 'makeindex' prints some diagnostic output C:\GAP3R4P0\DOC > latex manual # there should be no warnings this time C:\GAP3R4P0\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. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{Features of GAP for MS-DOS} \index{features!under MS-DOS}\index{MS-DOS!features}% \index{options!under MS-DOS}\index{MS-DOS!options}% \index{gap.rc}\index{.gaprc} 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 -'C' the DOS extender ('go32') catches it and aborts {\GAP} immediately. The keys -'Z' and -'C' can be used instead to interrupt {\GAP}. The arrow keys , , , , , , and 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 , 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 surived a garbage collection, that 5012 unused objects were reclaimed by it, and that 912 KByte of totally allocated 3072 KBytes are available afterwards. '-l ' The option '-l' tells {\GAP} that the library of {\GAP} functions is in the directory . Per default 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. should end with a pathname separator, i.e., |\|, but {\GAP} will silently add one if it is missing. {\GAP} will read the file |\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 '?| If you want a bare bones {\GAP}, i.e., if you do not need any library functions, you may ignore this warning, otherwise you should leave {\GAP} and start it again, specifying the correct library path using the '-l' option. It is also possible to specify several alternative library pathes by separating them with semicolons ';'. Note that in this case all path names must end with the pathname separator |\|. {\GAP} will then search for its library files in all those directories in turn, reading the first it finds. E.g., if you specify |-l "lib\;\usr\local\lib\gap3r4p0\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\gap3r4p0\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 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 |\init.g| that reads | GRPNAME := ReplacedString( LIBNAME, "lib", "grp" );| This path can also consist of several alternative pathes, just as the library path. If the library path consists of several alternative pathes the default value for this path will consist of the same pathes, where in each component the last occurrence of |lib\| is replaced by |grp\|. Similar considerations apply to the character table files. Those filenames end in '.tbl'. {\GAP} looks for those files in the directory given by 'TBLNAME'. The default value for 'TBLNAME' is obtained by replacing 'lib' in with 'tbl'. '-h ' The option '-h' tells {\GAP} that the on-line documenation for {\GAP} is in the directory . Per default is obtained by replacing 'lib' in with 'doc'. should end with a pathname separator, i.e., |\|, but {\GAP} will silently add one if it is missing. {\GAP} will read the file |\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 '?| '-m ' The option '-m' tells {\GAP} to allocate bytes at startup time. If the last character of is 'k' or 'K' it is taken in KBytes and if the last character is 'm' or 'M' is taken in MBytes. {\GAP} for MS-DOS will by default allocate 4 MBytes of memory. If you specify '-m ' {\GAP} will only allocate that much memory. The amount of memory should be large enough so that computations do not require too many garbage collections. On the other hand if {\GAP} allocates more virtual memory than is physically available it will spend most of the time paging. '-n' The options '-n' tells {\GAP} to disable the line editing and history (see "Line Editing"). There does not seem to be a good reason to do this on IBM PC compatibles. '-b' The option '-b' tells {\GAP} to surpress the banner. That means that {\GAP} immediately prints the prompt. This is useful when you get tired of the banner after a while. '-q' The option '-q' tells {\GAP} to be quiet. This means that {\GAP} does not display the banner and the prompts 'gap>'. This is useful if you want to run {\GAP} as a filter with input and output redirection and want to avoid the the banner and the prompts clobber the output file. '-x ' 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 ' 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 |-- 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 ' {\GAP} for MS-DOS checks in regular intervals whether the user has entered -'Z' or -'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 -'C'), which is rather expensive. Therefor {\GAP} only reads the keyboard status every -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 |\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 |\init.g|, but before any of the files mentioned on the command line are read. You can use this file for your private customizations. For example, if you have a file containing functions or data that you always need, you could read this from 'gap.rc'. Or if you find some of the names in the library too long, you could define abbreviations for those names in 'gap.rc'. The following sample 'gap.rc' file does both. | Read("c:\\gap\\dat\\mygroups.grp"); Op := Operation; OpHom := OperationHomomorphism; RepOp := RepresentativeOperation; RepsOp := RepresentativesOperation; | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{GAP for TOS}% \index{TOS}\index{Atari ST} 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). 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 monochrom 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. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{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. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{Installation of GAP for TOS}% \index{installation!under TOS}\index{TOS!installation} 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 |gap3r4p0\| 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 'gap3r4p0.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 'bin3r4p0-atari-m68k-tos.zoo', which is in the subdirectory 'bin' and which you should rename to 'bin3r4p0.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 bin3r4p0.zoo gap3r4p0\bin\README.TOS -- extracted as text gap3r4p0\bin\gap.ttp -- extracted as binary C: > unzoo -x gap3r4p0.zoo gap3r4p0\bin\gap.sh -- extracted as text gap3r4p0\doc\aboutgap.tex -- extracted as text gap3r4p0\doc\aggroup.tex -- extracted as text # about 500 more lines gap3r4p0\two\twogpd8.grp -- extracted as text C: > | If you got the executable and the distribution on disks, you must unpack them with the following comands (assuming that your disk drive is |A:|) | C: > rem Insert the 1. disk. C: > copy a:\unzoo.exe . C: > unzoo -x a:\bin3r4p0.zoo gap3r4p0\bin\README.TOS -- extracted as text gap3r4p0\bin\gap.ttp -- extracted as binary C: > unzoo -x a:\etc3r4p0.zoo gap3r4p0\etc\README -- extracted as text # about 20 more messages C: > unzoo -x a:\grp3r4p0.zoo gap3r4p0\grp\basic.grp -- extracted as text # about 10 more messages C: > unzoo -x a:\lic3r4p0.zoo gap3r4p0\lib\ctautoms.g -- extracted as text # about 10 more messages C: > rem Insert the 2. disk. C: > unzoo -x a:\lib3r4p0.zoo gap3r4p0\lib\abattoir.g -- extracted as text # about 70 more messages C: > rem Insert the 3. disk. C: > unzoo -x a:\doc3r4p0.zoo gap3r4p0\doc\about.tex -- extracted as text # about 65 more messages C: > rem Insert the 4. disk. C: > unzoo -x a:\two3r4p0.zoo gap3r4p0\two\twogp.grp # about 25 more messages C: > unzoo -x a:\thr3r4p0.zoo gap3r4p0\thr\thrgp.grp # about 10 more messages C: > rem Insert the 5. disk. C: > unzoo -x a:\tom3r4p0.zoo gap3r4p0\tom\tmaltern.tom # about 10 more messages C: > rem Insert the 6. disk. C: > unzoo -x a:\src3r4p0.zoo gap3r4p0\src\Makefile -- extracted as text # about 60 more messages C: > | Instead of using the executable that we provide in 'bin3r4p0.zoo' you can compile {\GAP} yourself if you have the GNU C compiler installed. To do this change into the source directory |gap3r4p0\src\| and compile {\GAP} with the commands | C: > chdir gap3r4p0\src C:\GAP3R4P0\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:\GAP3R4P0\SRC > copy gap.ttp ..\bin C:\GAP3R4P0\SRC > chdir ..\.. C: > | In either case now move the executable 'gap.ttp' from the |gap3r4p0\bin\| subdirectory to the |gap3r4p0\| 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 ||\gap3r4p0\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 -'P' redisplays the last command, that -'E' moves the cursor to the end of the line, that -'B' moves the cursor back one character, and that -'D' deletes single characters. So after entering the above three commands typing\\ -'P' -'P' -'E' -'B' -'B' -'B' -'B' -'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 |gap3r4p0\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 gap3r4p0\doc C:\GAP3R4P0\DOC > latex manual # about 2000 messages about undefined references C:\GAP3R4P0\DOC > latex manual # there should be no warnings this time C:\GAP3R4P0\DOC > dir manual.dvi -a--- 2591132 Nov 13 23:29 manual.dvi C:\GAP3R4P0\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 gap3r4p0\doc # about 2000 messages about undefined references C:\GAP3R4P0\DOC > bibtex manual # 'bibtex' prints the name of each file it is scanning C:\GAP3R4P0\DOC > latex manual # still some messages about undefined citations C:\GAP3R4P0\DOC > makeindex manual # 'makeindex' prints some diagnostic output C:\GAP3R4P0\DOC > latex manual # there should be no warnings this time C:\GAP3R4P0\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. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{Features of GAP for TOS}% \index{features!under TOS}\index{TOS!features}% \index{options!under TOS}\index{TOS!options}% \index{gap.rc}\index{.gaprc} {\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 ', {\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 , , , and 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 , 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 distuingish 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 surived a garbage collection, that 5012 unused objects were reclaimed by it, and that 912 KByte of totally allocated 3072 KBytes are available afterwards. '-l ' The option '-l' tells {\GAP} that the library of {\GAP} functions is in the directory . Per default 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. should end with a pathname separator, i.e., |\|, but {\GAP} will silently add one if it is missing. {\GAP} will read the file |\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 '?| If you want a bare bones {\GAP}, i.e., if you do not need any library functions, you may ignore this warning, otherwise you should leave {\GAP} and start it again, specifying the correct library path using the '-l' option. It is also possible to specify several alternative library pathes by separating them with semicolons ';'. Note that in this case all path names must end with the pathname separator |\|. {\GAP} will then search for its library files in all those directories in turn, reading the first it finds. E.g., if you specify |-l "lib\;\usr\local\lib\gap3r4p0\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\gap3r4p0\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 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 |\init.g| that reads | GRPNAME := ReplacedString( LIBNAME, "lib", "grp" );| This path can also consist of several alternative pathes, just as the library path. If the library path consists of several alternative pathes the default value for this path will consist of the same pathes, where in each component the last occurrence of |lib\| is replaced by |grp\|. Similar considerations apply to the character table files. Those filenames end in '.tbl'. {\GAP} looks for those files in the directory given by 'TBLNAME'. The default value for 'TBLNAME' is obtained by replacing 'lib' in with 'tbl'. '-h ' The option '-h' tells {\GAP} that the on-line documenation for {\GAP} is in the directory . Per default is obtained by replacing 'lib' in with 'doc'. should end with a pathname separator, i.e., |\|, but {\GAP} will silently add one if it is missing. {\GAP} will read the file |\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 '?| '-m ' The option '-m' tells {\GAP} to allocate bytes at startup time. If the last character of is 'k' or 'K' it is taken in KBytes and if the last character is 'm' or 'M' is taken in MBytes. {\GAP} for TOS will by default allocate all available memory. If you specify '-m ' {\GAP} will only allocate that much memory, unless is larger than the default, in that case {\GAP} will fail. If you speficy a negative amount {\GAP} leaves that much memory unallocated. You may want to do this so that it is possible to run other programs from inside {\GAP} with the 'Exec' command, for example 'gap -m -256k' will leave 256 KByte unallocated, enough to run MicroEMACS from inside {\GAP}. '-n' The options '-n' tells {\GAP} to disable the line editing and history (see "Line Editing"). There does not seem to be a good reason to do this on an Atari ST. '-b' The option '-b' tells {\GAP} to surpress the banner. That means that {\GAP} immediately prints the prompt. This is useful when you get tired of the banner after a while. '-q' The option '-q' tells {\GAP} to be quiet. This means that {\GAP} does not display the banner and the prompts 'gap>'. This is useful if you want to run {\GAP} as a filter with input and output redirection and want to avoid the the banner and the prompts clobber the output file. '-x ' 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 ' 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 |-- 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 ' {\GAP} for TOS checks in regular intervals whether the user has entered -'Z' or -'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 -'C'), which is rather expensive. Therefor {\GAP} only reads the keyboard status every -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 |\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 |\init.g|, but before any of the files mentioned on the command line are read. You can use this file for your private customizations. For example, if you have a file containing functions or data that you always need, you could read this from 'gap.rc'. Or if you find some of the names in the library too long, you could define abbreviations for those names in 'gap.rc'. The following sample 'gap.rc' file does both. | Read("c:\\gap\\dat\\mygroups.grp"); Op := Operation; OpHom := OperationHomomorphism; RepOp := RepresentativeOperation; RepsOp := RepresentativesOperation; | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \Section{Porting GAP} Porting {\GAP} to a new operating system should not be very difficult. However, {\GAP} expects some features from the operating system and the compiler and porting {\GAP} to a system or with a compiler that do not have those features may prove very difficult. The design of {\GAP} makes it quite portable. {\GAP} consists of a small kernel written in the programming language C and a large library written in the programming language provided by the {\GAP} kernel, which is also called {\GAP}. Once the kernel has been ported, the library poses no additional problem, because all those functions only need the kernel to work, they need no additional support from the environment. The kernel itself is separated into a large part that is largely operating system and compiler independent, and one file that contains all the operating system and compiler dependent functions. Usually only this file must be modified to port {\GAP} to a new operating system. Now lets take a look at the minimal support that {\GAP} needs from the operating system and the machine. First of all you need enough filespace. The kernel sources and the object files need between 3.5 MByte and 4 MByte, depending on the size of object files produced by your compiler. The library takes up an additional 3.5 MBytes, and the online documentation also needs 2.5 MByte. So you need about 10 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 or Intel 80486 processor under extended DOS in protected 32 bit mode. (This is also necessary, because, as mentioned below, {\GAP} wants to view its memory as a large flat address space.) Next lets turn to the requirements for the C compiler and its library. As was already mentioned, the {\GAP} kernel is written in the C language. We have tried to use as few features of the C language as possible. {\GAP} has been compiled without problems with compilers that adhere to the old definition from Kernighan and Ritchie, and with compilers that adhere to the new definition from the ANSI-C standard. However, it is probably necessary that the compiler has a default integer size of 32 bits, i.e., 'sizeof(int)' should be 4 not 2. It may be possible to fix all the places where 32 bit 'int's are assumed, but we assume that it will be easier to get a 32 bit compiler. The most critical aspect probably is that the {\GAP} kernel needs a flat address space. There are especially two systems where this is a problem. The first is MS-DOS with its segments. As was already mentioned above, we circumvent this by using an extended DOS in protected 32 bit mode on PC compatibles with an Intel 386 or Intel 486 processor. The other system is the Macintosh. On the Macintosh the operating system wants to deal out the memory only in small chunks, and also wants programs to allow it to move those chunks to the disk temporarily. This is because Apple wanted to support programs that used quite some memory on its initial Macs, which had only 512 KByte of memory, without true virtual memory support. Thus they forced the application programs to simulate virtual memory. {\GAP} does not do this. Probably the best way to deal with that is to allocate as much memory as one can get in one large chunk, while leaving enough memory free for the operating system, and to lock this chunk in memory. Such behaviour is considered uncooperative, but it is the best {\GAP} can do without a major rewrite. The two points mentioned above are necessary, because most parts of {\GAP} depend on those features. All other dependencies on the operating system or compiler should be separated in one special file which is called the 'system' file. When you port {\GAP} to a new operating system, you probably have to create a new 'system' file. You should however look through the 'system.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 -, used in some operating systems, with a single , used in C. However, since {\GAP} treats and 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 -'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 -'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 -'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 consequitive calls to 'SyGetmem' must be adjacent, because {\GAP} wants to manage a single large block of memory. Usually this can be done with the C library function 'sbrk'. If this does not work, you can define a large static array in the 'system' file and return this on the first call to 'SyGetmem' and return 0 on subsequent calls to indicate that this array cannot dynamically be expanded.