This document describes how to install GAP 4 on a Unix system. Section "Getting GAP" describes where to get GAP 4 and which files to get. Section "Installation of GAP for UNIX" describes the installation process. Section "Porting GAP" describes what to do to port GAP 4 to other systems. Installation for the Impatient Because GAP supports three different platforms, Windows, Macintosh and UNIX, the installation process might differ a bit from what you are used to. This document explains in detail which files to get and how to install the system and if you are inexperienced we strongly recommend you follow these instructions. If you already have experience in installing GAP or would not read the installation instructions anyhow this section provides a quick run through of the installation on a UNIX system. (If it is incomprehensible or causes problems, please follow the explicit installation instructions given below!) Get and unzoo binary and installation archive(s) and the most recent bugfix file (including the most recent binary if you use Windows or Mac). The following instructions assume you have unzoo and it is in your path. Call unzoo -x gap4r3.zoo cd gap4r3 If there is a bugfix (starting with release 4.3, bugfixes for a release will be comprehensive), extract it: unzoo -x ../fix4r3nX.zoo Then, to compile the GAP binary call ./configure make and you will get a shell script bin/gap.sh to start GAP which you can copy in a standard path, e.g. copy the script to say /usr/local/bin and rename it to how you expect users to call GAP (either gap or gap4 is usual). Send an email to gap@dcs.st-and.ac.uk, telling us about the installation. (This is just a courtesy; we like to know how many people are using GAP and get feedback regarding difficulties (hopefully none) that users may have had with installation.) You might also want to unpack and install GAP packages. Generally, this involves first getting accpkg4r3.zoo and deppkg4r3.zoo (these have all the accepted/refereed and all the deposited but not yet refereed GAP packages, respectively) or visiting the GAP website again and first looking for the GAP Packages link and following through to the individual GAP package .zoo files you want. The package .zoo files should all be unzoo-ed in the pkg directory, i.e. do: cd pkg first. Some of the GAP packages are written entirely in GAP; these are essentially ``ready-to-go'' after unpacking, except they should be listed in the ALLPKG file (see Loading a GAP Package). Other GAP packages have a C code component; these generally require one to do: ./configure; make in their respective directories. Each GAP package has a README; it's recommended that despite your impatience that you at least give these a quick glance; for one thing they will tell you whether the ./configure; make steps are needed. Also note that a few details might have changed since the last release. 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@dcs.st-and.ac.uk, containing your full name and address, so that we have a rough idea of the number of users. We also hope that this number will be large enough to convince various agencies that GAP is a project worthy of (financial) support. If you publish some result that was partly obtained using GAP, we would appreciate it if you would cite GAP, just as you would cite another paper that you used. (The copyright page of the manual gives a sample citation.) Again we would appreciate if you could inform us about such a paper. The current release of GAP is version 4.3. We distribute the full source for everything, the C code for the kernel, the GAP code for the library, and the TeX code for the manual. So it should be no problem to get GAP, even if you have a rather uncommon system. Of course, ports to non UNIX systems may require some work. Note that about 16 MByte of main memory (though at least 32 MByte is desirable) and about 30MB of disk space are required to run GAP. A full GAP installation, including all GAP packages and data libraries can use 200MB and more of disk space. GAP will compile on pentium (586) processors, though a faster machine is recommended. We list and describe the extraction from .zoo archives below. As of GAP 4.3, however, we also supply the equivalent .zip and .tar.gz archives (simply download the archive type you prefer and use the corresponding extraction command). (If you already downloaded an installation archive, you may ignore the rest of this section.) The easiest way to get GAP for most users is probably via the World Wide Web. The main GAP Web site is found at http://www.gap-system.org There are two mirror sites updated automatically each night, at: http://www.math.rwth-aachen.de/~GAP http://www.ccs.neu.edu/mirrors/GAP and At these sites you can browse this manual, download the system and contributed extensions, read past postings to the GAP forum, and find out about authors of and contributors to GAP, publications that cited GAP and GAP related events. GAP can also be obtained by anonymous ftp from (at least) the following servers. ftp-gap.dcs.st-and.ac.uk: School of Mathematical and Computational Sciences, University of St Andrews, Scotland, UK. Directory /pub/gap/gap4/. ftp.math.rwth-aachen.de: Lehrstuhl D für Mathematik, RWTH Aachen, Germany. Directory /pub/gap4/. ftp.ccs.neu.edu: College of Computer Science, Northeastern University, Boston, USA. Directory /pub/mirrors/ftp-gap.dcs.st-and.ac.uk/pub/gap/gap4. ftp to the server closest to you, login as user ftp and give your full e-mail address as password. Remember when you transmit the files to set the file transfer type to binary image, otherwise you will only receive unusable garbage. Those servers will always have the latest version of GAP available. The WWW page for the GAP distribution and the ftp directory contain the following files. Please check first which files you need, to avoid transferring those that you do not need. Except for the package archives all archives should be extracted at the ``top'' level level (i.e. they contain a gap4r3 directory). INSTALL, INSTALL.WIN, INSTALL-MAC.TXT: Installation files, one of which you are currently reading. FILES: More detailed description of the available files. gap4r3.zoo: This file contains the complete standard distribution of GAP version 4.3 (it does not include the packages contained in accpkg4r3.zoo and deppkg4r3.zoo). basic4r3.zoo: This file contains a minimal distribution of GAP version 4.3. (There are further archives with which you can ``upgrade'' it to the full version.) gappc4r3.zoo: This file contains a complete distribution for 32-bit Windows. It includes a precompiled binary. gapmac4r3.zoo: This file contains a complete distribution for Macintosh under MacOS. You will also need to obtain the binaries separately from the bin subdirectory via ftp or from the links on the Distribution web page. accpkg4r3.zoo: This file contains all accepted GAP packages as of the release date. It should be extracted in the pkg directory of a previously extracted GAP distribution or a user's private pkg directory. deppkg4r3.zoo: This file contains all deposited, but not accepted, GAP packages whose authors wish to make them available, as of the release date. They should be viewed as analogous to preprints. It should be extracted in the pkg directory of a previously extracted GAP distribution or a user's private pkg directory. tools4r3.zoo: This file contains additional files not provided in the standard distribution, mainly needed by package developers for the purpose of generating documentation. util/unzoo.c: A simple zoo archive extractor, which should be used to unpack the distribution. The bin subdirectory contains precompiled executables for common systems. More files are available from the Distribution web page links or the following ftp subdirectories: bin: This directory contains executables for systems that do not come with a C compiler or where another C compiler produces a faster executable. split: This directory contains the complete distribution of GAP 4.3 in several smaller archives. accpkg: This directory contains all accepted GAP packages in case you don't want to load the comprehensive accpkg archive. deposit/pkg: This directory contains all deposited but not yet accepted GAP packages whose authors wish to make them available, in case you don't want to load the comprehensive deppkg archive. GAP for UNIX GAP runs very well under UNIX. In fact it is being developed on UNIX workstations (and PCs under Linux). GAP running on any UNIX machine should behave exactly as described in the manual. GAP has successfully been compiled and installed on the following UNIX machines: DECalpha under OSF 3.2 with GNU cc 2 or cc, HP9000 under HP-UX with GNU cc 2, IBM PC under Linux with GNU cc 2, IBM RS/6000 & AIX with GNU cc 2, SGI Mips under IRIX 5/6 with gcc2 or cc, Sun Sparc under Solaris with GCC 2 or cc. We hope that compiling and installing GAP on another UNIX machine does not pose any problem. If it does, please inform us of your problems (and, if possible, of your solution). The section Installation of GAP for UNIX describes how you install GAP on a UNIX machine. See Chapter Running GAP for information about command line options that GAP accepts under UNIX. Installation of GAP for UNIX Installing GAP on a UNIX machine is fairly easy. Get the files described in Getting GAP and decide into which directory you want to install GAP 4.3. If you will be the only user using GAP, you probably should install it in your home directory. If other users will be also using GAP, you should install it in a public place, such as /usr/local/lib/. GAP will be installed in a subdirectory gap4r3 of this directory. You can later move GAP to a different location. For example you can first install it in your home directory and when it works move it to /usr/local/lib/. The following installation example assumes that you (as user you on the machine unix) are installing GAP into the directory /usr/local/lib on a Pentium Pro running Linux. Note that certain parts of the output in the examples should only be taken as rough outline, especially file sizes and file dates are not to be taken literally. If you encounter problems please also see section If Things Go Wrong of this document. Get the distribution gap4r3.zoo and the source for the zoo archive extractor unzoo.c. How you can get those files is described in the section Getting GAP. Remember that the distribution consists of binary files and that you must transmit them in binary mode. Compile the zoo archive extractor unzoo with the command you@unix> cc -o unzoo -DSYS_IS_UNIX -O unzoo.c you@unix> ls -l unzoo -rwxr-xr-x you 45056 Nov 3 10:11 unzoo you@unix> Now unpack the distribution with the command you@unix> ./unzoo -x gap4r3.zoo gap4r3/doc/aboutgap.tex -- extracted as text gap4r3/doc/aggroup.tex -- extracted as text [many more lines] you@unix> (Messages of the form: /bin/mkdir: cannot create directory are harmless and can be ignored. They stem from issuing mkdir calls for top level directories every time a new subdirectory is created.) If you got not the full distribution file but several small files, extract all of them (except the bug fixes and GAP packages!) in this way. (Afterwards you will not need the file gap4r3.zoo any longer. If you are short of disk space you can remove it now.) you@unix> rm gap4r3.zoo Now go into the directory gap4r3. If there is a bug fix (there are none in the initial release but invariably some follow later and are deposited in the bugfixes directory on our ftp server(s). Starting with release 4.3, bugfixes will be comprehensive and you need only the most recent bugfix), extract it while in the gap4r3 directory. (The bug fixes extract only on this level of the directory hierarchy to make them applicable even if you chose later to rename the root directory of your GAP distribution.) The program may ask you for confirmation to overwrite files, you should give this permission. you@unix> cd gap4r3 you@unix> ../unzoo -x ../fix4r3n3.zoo [extraction information] If you got any GAP packages, extract them in the pkg subdirectory in the same way. For example if you got the accpkg4r3.zoo and deppkg4r3.zoo archives, you would issue: you@unix> cd pkg you@unix> ../../unzoo -x ../../accpkg4r3.zoo you@unix> ../../unzoo -x ../../deppkg4r3.zoo you@unix> cd .. There is a little more to do to install the GAP packages but (particularly for those packages with a C code component) it's only appropriate to complete each GAP package's installation after GAP has been compiled. The directories trans, small and prim contain data libraries. If you are short of disk space you can erase some of them, and any of the GAP package directories in pkg that you have decided you don't need, but then of course you will not be able to access these data or packages. Under UNIX, we now use the ``autoconfig'' method to take care of system dependencies. (See Porting GAP if this is not working on your machine.) If you are installing GAP on various systems that share a file system then all the above steps have essentially been done for all but the first system and on succeeding systems these steps are replaced by (fairly obviously) changing to the gap4r3 directory. However, before proceeding with the following steps, on each other machine you must first remove the files config.cache and config.status created on the previous machine! Now run the shell script configure: you@unix> ./configure checking host system type... i686-unknown-linux2.0.27 [many more lines] This will automatically detect the machine and compiler target. The process will automatically create an appropriate binary subdirectory. It also creates a Makefile that will be used to compile GAP on this machine. Simply call make: you@unix> make [many lines of further configuration and compilation] The compilation process creates the object files and the executable in the directory /usr/local/lib/gap4r3/bin/target/ where target is the name printed by the first configure (and /usr/local/lib the directory in which you installed GAP). In our example the executable will be created as /usr/local/lib/gap4r3/bin/i686-unknown-linux2.0.27/gap If configure or make fails, see section Known Problems of the Configure Process for a description of some remedies. If all of these fail, please inform us at gap-trouble@dcs.st-and.ac.uk. If you have UNIX experience you might want to change the compilation options to obtain a better performance. Section Optimization and Compiler Options explains how to do this. In particular, if you have little system memory, you might want to remove debugging information from the binary to create a smaller file. This is done by the UNIX strip command which gets invoked by: you@unix> make strip In order to test your compilation now run the newly created executable. You should get the GAP banner and then the GAP prompt. (The process of starting GAP may take a little while.) you@unix> cd .. you@unix> bin/i686-unknown-linux2.0.27/gap -l /usr/local/lib/gap4r3 [... lines deleted] gap> (Having to give the library path with the -l option each time would be a bit tedious. Below we will therefore install a shell script to start GAP.) Try a few things to see if the compilation succeeded. gap> 2 * 3 + 4; 10 gap> Factorial( 30 ); 265252859812191058636308480000000 gap> Size( SymmetricGroup( 10 ) ); 3628800 gap> Factors( 10^42 + 1 ); [ 29, 101, 281, 9901, 226549, 121499449, 4458192223320340849 ] gap> m11 := Group((1,2,3,4,5,6,7,8,9,10,11),(3,7,11,8)(4,10,5,6));; gap> Size( m11 ); 7920 gap> Factors( 7920 ); [ 2, 2, 2, 2, 3, 3, 5, 11 ] gap> Length( ConjugacyClasses( m11 ) ); 10 Especially try the command line editing and history facilities, because they are probably the most machine dependent feature of GAP. Enter a few commands and then make sure that ctr-P redisplays the last command, that ctr-E moves the cursor to the end of the line, that ctr-B moves the cursor back one character, and that ctr-D deletes single characters. So, after entering the above commands, typing ctr-P ctr-P ctr-E ctr-B ctr-B ctr-B ctr-B ctr-D 1 return should give the following lines: gap> Factors( 7921 ); [ 89, 89 ] If you can compile but command line editing does not work you can always start GAP with option -n to disable command line editing. In such a case however we would like to hear about such problems. If your operating system has job control, make sure that you can still stop GAP, which is usually done by pressing ctr-Z. The make process should also have created a shell script gap.sh in the bin subdirectory. This file already contains proper directory paths and it should be possible to start GAP by simply calling this script. Still, you might want to edit it to give further default command line options or modify the default memory. Execute the script to start GAP again you@unix> bin/gap.sh If the shell complains that it cannot execute or find gap.sh check the permissions of the file by doing a ls -l bin/gap.sh. The permissions should include execute permissions, if they don't you can set them by you@unix> chmod +x bin/gap.sh Then copy this script into a directory in your search path, for example /usr/local/bin/ as gap (or gap4 if you also have GAP 3 running on the same machine). (If you are using the C-shell, you will also have to rehash, so that the C-shell adds gap to its internal tables). When you later move GAP to another location you only need to edit this script. There also is a shell script gac in the same place that can be used to invoke the compiler. Depending on your installation you also might want to copy it in a directory in your search path. Now you should be able to start GAP by its name: you@unix> cd ~ you@unix> gap (If you get an error message ``hmm, I cannot find lib/init.g'' you are starting the pure binary. It needs to find the library which is given via the command line parameter -l.) A set of test files is provided, running them all takes some 40 minutes on a Pentium Pro 200 MHz. As a quick test we start combinat.tst first. gap> Filename( DirectoriesLibrary("tst"), "combinat.tst" ); "/usr/local/lib/gap4r3/tst/combinat.tst" gap> ReadTest(last); + $ld: combinat.tst,v 4.7 1997/11/21 10:19:47 ahulpke Exp $ + GAP4stones: 27801 true The number given as GAP4stones will vary, depending on the speed of your machine. Now use Read (not ReadTest) to read the file testall.g to run all available test files. This is not a necessary part of the installation, it only serves as a confirmation that everything went OK. The full test suite takes some time (almost 2 hours on a Pentium III/500) and uses quite a bit of memory (around 100MB), so you may wish to skip this step or run only part of the tests. This does no harm. gap> Filename( DirectoriesLibrary("tst"), "testall.g" ); "/usr/local/lib/gap4r3/tst/testall.g" gap> Read(last); [lines omitted] test file GAP4stones time(msec) ------------------------------------------- testing: ./tst/boolean.tst boolean.tst 0 0 testing: ./tst/unknown.tst unknown.tst 0 10 testing: ./tst/gaussian.tst gaussian.tst 0 250 [further lines omitted] You can ignore warnings from weakptr.tst, which stem from garbage collections occurring at different times, and those from grpconst.tst which stem from differences in available GAP packages. The information about the manual is system independent, you can find it in section The Documentation. Now you should finish the installation for the GAP packages you intend to install. First do: you@unix> cd pkg Each GAP package has a README, which details the additional steps necessary for installation of the package. Some of the GAP packages are written entirely in GAP; for these once you have installed them on one system there is no further work required on other systems sharing the same file system. For the packages with a C code component, generally one must do ./configure and make after changing to the package's directory, e.g. for the ACE package you usually only need to do: you@unix> cd ace you@unix> ./configure you@unix> make you@unix> cd .. For other systems sharing the same file system you need to repeat these steps for each system; the appropriate time is immediately after compiling GAP on each system. Some GAP packages are set up to load (or provide the documentation) automatically. To enable this, after installing all the packages you think you will need, you should list all the GAP packages you have installed in a file ALLPKG in the pkg directory (see Section Loading a GAP Package in the Reference Manual for details); an easy way to do this under UNIX is by issuing the command find * -type d -maxdepth 0 -print > ALLPKG while still in the pkg directory. Please see Chapter GAP Packages for more details on the installation of GAP packages. If you want to install GAP also on different architectures, which share the same file system with the machine on which you just installed GAP log into these machines and go to the GAP home directory. You do not need to extract any new files, simply execute the same ``configure/make'' process which has been described above again (but remember to remove the files config.cache and config.status, each time). Make sure also, however, that you copy the bin/gap.sh and bin/gac shell scripts created by the make process, each time, because they are system dependent and will be overwritten when compiling on each new system. A few final reminders: * Make sure that you got and installed the most recent bugfix. * We would appreciate after installation your sending us a short note at gap@dcs.st-and.ac.uk (even if you have installed GAP 3 before). Generally, we do not reply to such emails; we only use them to gain some idea of how many people use GAP and of the machines/operating systems on which GAP has been successfully installed. * We also suggest that you subscribe to our gap-forum mailing list; see the GAP web pages for details. Whenever there is a bug fix or new release of GAP this is where it is announced. The gap-forum also deals with user questions of a general nature; bug reports and other problems you have while installing and/or using GAP should be sent to gap-trouble@dcs.st-and.ac.uk. That's all, your installation should be complete. We hope that you will enjoy using GAP. Remember, if you have problems, do not hesitate to contact us at gap-trouble@dcs.st-and.ac.uk. See Section If Things Go Wrong for what to include in a bug report. Known Problems of the Configure Process If make complains ``Do not know how to make xyz'' but xyz is an existing file, it is likely that the dates of the files were not extracted properly (Alpha-OSF machines are prone to this). Call touch * cnf/* src/* from the main GAP directory (this ought to reset the date of all relevant files to ``now'') and try again. Sometimes the configure process does not properly figure out the ``inline'' compiler command. If you get error messages that complain that ``inline'' is unknown, edit the file config.h in the bin/target subdirectory and replace the line /* #undef inline */ by #define inline and then try to compile again. The configure script respects compiler settings given in environment variables. However such settings may conflict with the automatic configuration process. If configure produces strange error messages about not being able to run the compiler, check whether environment variables that might affect the compilation (in particular CC, LD, CFLAGS, LDFLAGS and C_INCLUDE_PATH) are set and reset them using unsetenv. Some users reported problems with make, while the GNU version gmake worked. Thus if problems occur you should try gmake instead if it is installed on your machine. Problems on Particular Systems The highest levels of optimization of the OSF/4 C compiler cc on the Compaq alpha chip make assumptions about the use of pointers which are not valid for GAP, and produce executables that can crash; -O3 seems to be safe, but -O4 and -fast are not. On Sun and IRIX systems which are capable of running in 32 or 64 bit modes, it is possible to build a 64 bit version of GAP, but special procedures are needed (and, on Suns, a compiler bug must be circumvented). If you wish to compile on such a system, please send an email to gap-trouble@dcs.st-and.ac.uk. Optimization and Compiler Options Because of the large variety of different versions of UNIX and different compilers it is possible that the configure process will not chose best possible optimization level, but you might need to tell make about it. If you want to compile GAP with further compiler options (for example specific processor optimizations) you will have to assign them to the variable COPTS as in the following example when calling make: make COPTS=-option If there are several compiler options or if they contain spaces you might have to enclose them by quotes to avoid depending on the shell you are using. The configure process also introduces some default compiler options. (See the Makefile in the bin directory for details.) You can eliminate these by assigning the variable CFLAGS (which contains the default options and COPTS) to the desired list of compiler options in the same way as you would assign COPTS. The recommended C compiler for GAP is the GNU C compiler gcc, or a related compiler such as egcs. There are two reasons for this recommendation: firstly we use gcc in GAP development and so this combination has been far more heavily tested than any other and secondly, we have found that it generally produces code which is faster than that produced by other compilers. If you do wish to use another compiler, you should remove config.cache and config.status in the GAP root directory, set the environment variable CC to the name of your preferred compiler and then rerun configure and make. You may have to experiment to determine the best values for CFLAGS and/or COPTS as described above. Please let us (gap-trouble@dcs.st-and.ac.uk) know the results of your experiments. Porting GAP Porting GAP to a new operating system should not be very difficult. However, GAP expects some features from the operating system and the compiler and porting GAP to a system or with a compiler that do not have those features may prove very difficult. The design of GAP makes it quite portable. GAP consists of a small kernel written in the programming language C and a large library written in the programming language provided by the GAP kernel, which is also called GAP. Once the kernel has been ported, the library poses no additional problem, because all those functions only need the kernel to work, they need no additional support from the environment. The kernel itself is separated into a large part that is largely operating system and compiler independent, and one file that contains all the operating system and compiler dependent functions. Usually only this file must be modified to port GAP to a new operating system. Now let us take a look at the minimal support that GAP needs from the operating system and the machine: You need enough main memory in your computer. The size of the GAP kernel varies between 1.5 and 2.5 MByte (depending on the machine). The GAP library additionally takes a minimum of 10MByte and the library of functions that GAP loads takes up another 1.5 MByte. So it is clear that at least 16 MByte of main memory are required to do any serious work with GAP. Additionally, the GAP kernel needs a flat address space, that is all the memory is available in one contiguous chunk. Note that this implies that there is no point in trying to port GAP to plain MS-DOS running on IBM PCs and compatibles. The version of GAP for IBM PC compatibles that we provide runs on machines with the Intel 80486, Pentium or beyond processor under 32-bit Windows. (This is also necessary, because, as just mentioned, GAP wants to view its memory as a large flat address space.) Next let us turn to the requirements for the C compiler and its library. As was already mentioned, the GAP kernel is written in the C language. We have tried to use as few features of the C language as possible. GAP has been compiled without problems with compilers that adhere to the old definition from Kernighan and Ritchie, and with compilers that adhere to the new definition from the ANSI-C standard. Porting GAP to another UNIX should not be hard. You need some very basic understanding of C and UNIX. If you plan to port GAP to a non-UNIX system please contact gap-trouble@dcs.st-and.ac.uk. The configuration script runs various tests to determine the configuration of your system. It produces a file bin/architecture/config.h which contains definitions according to the test results. It might be, however, that the tests used don't produce on your machine the results they are expected to or that further tests are necessary. If this is the case the easiest way is to edit the config.h script, remove all object files and call make in the bin/architecture subdirectory. If you have to resort to changing or amending this file, please tell us what had to be changed (mail to gap-trouble@dcs.st-and.ac.uk). If you had to add further definitions please also tell what properties of your system these defines represent. If GAP compiles but crashes while reading the library or during a garbage collection with a bus error it is possible that the configuration script did not guess the permitted pointer alignment correctly. This value is stored in the line #define C_STACK_ALIGN 2 of config.h. Increase the value to the next power of 2 ( £ 8) and compile GAP anew. There is still a Makefile in the src directory, but it is not used by the configuration process any longer. As a last resort you might want to try this file, but please still report your problems to gap-trouble. The Documentation The GAP manual is distributed in various ``books''. The standard distribution contains four of them (as well as a comprehensive index). GAP packages (see Chapter GAP Packages and, in particular, Section Loading a GAP Package) provide their own documentation in their own doc directories. All documentation will be available automatically for the online help (see Section Tut:Help in the Tutorial and Chapter The Help System in this manual for more details). There also is (if installed) an HTML version of some books that can be viewed with an HTML browser, see Changing the Help Viewer. Some of these use symbol fonts for mathematical formulae. To get them correctly displayed (only in a browser which uses a graphical display), you may want to adjust the font setup for your browser. See HTML Font Setup below for a hint. The manual is also available in dvi and pdf format. In the full UNIX distribution (gap4r3.zoo) these files are included in the directory gap4r3/doc in the subdirectories tut (a beginner's tutorial), ref (the reference manual), prg (programmer's tutorial), ext (programmer's reference) and new (new material that might still change in future versions). If you downloaded another distribution file, you can get the missing dvi (resp. pdf) files by downloading the archive docdvi4r3.zoo (resp. docpdf4r3.zoo) from the same place you got GAP. If you want to use these manual files with the online help you may check (or make sure) that your system provides some additional software like xpdf see http://www.foolabs.com/xpdf/ xdvi see any of the CTAN sites/mirrors; the main site is: http://www.ctan.org/ and the mirrors are listed at: http://www.ctan.org/tex-archive/CTAN.sites At any of the mirrors the path of the file containing the xdvi archive (after the main site name) is tex-archive/dviware/xdvi/xdvi.tar.gz. acroread see http://www.adobe.com/products/acrobat/readstep.html As a complete beginner, we suggest you read the tutorial first for an introduction to GAP 4. Then start to use the system with extensive use of the online help system (see Section Tut:Help in the Tutorial and Chapter The Help System in this manual). If you have experience with GAP 3, it might be still worthwhile to at least glance over the first chapters of the tutorial. You however should read the last chapter of the tutorial, ``Migrating to GAP4''. This chapter gives a summary of changes between GAP 3 and GAP 4 that will affect the user. It also explains a ``compatibility mode'' you may turn on to make GAP 4 behave a bit more like GAP 3. As some of the manuals are quite large, you should not immediately print them. If you start using GAP it will be helpful to print the tutorial (and probably the first chapters of the reference manual). There is no compelling reason to print the whole of the reference manual, better use the online help which provides useful search features. HTML Font Setup The HTML pages of the manual use the symbol font to display non-latin symbols in mathematical formulae. This font might not be enabled by default on your browser. The documentation of the tth converter we use http://hutchinson.belmont.ma.us/tth/Xfonts.html describes how to set up this font for use in Netscape or Konqueror. For Netscape on UNIX, essentially you want: Netscape*documentFonts.charset*adobe-fontspecific: iso-8859-1 in your .Xresources or .Xdefaults file. A good test to see if you need this remedy is to check the display of: {1,...,n}; if you see an ellipsis (three dots) between the commas, you are ok, and if you see 1/4 you need the remedy! If you have problems viewing symbol fonts on the Mac, you may have to choose Mac font encoding, sometimes called MacRoman, or Western (Mac). More information about the font setup on Macintoshes can be found http://hutchinson.belmont.ma.us/tth/manual/sec12.html, Section 12.3. If Things Go Wrong This section lists a few common problems when installing or running GAP and their remedies. Also see the FAQ list on the GAP web pages at http://www.gap-system.org/Info/faq.html GAP starts with a warning ``hmm, I cannot find 'lib/init.g'''. You either started only the binary or did not edit the shell script/batch file to give the correct library path. You must start the binary with the command line option -l path where path is the path to the GAP home directory. See section Command Line Options in the reference manual. When starting, GAP produces error messages about undefined variables. You might have a .gaprc file that was intended for GAP 3 but is not compatible with GAP 4. See section The .gaprc file in chapter Running GAP of the reference manual. GAP stops with an error message: ``cannot extend the workspace any more''. Your calculation exceeded the available memory. Most likely you asked GAP to do something which required more memory than you have (as listing all elements of S[15] for example). You can use the command line option -g (see section Command Line Options in the reference manual) to display how much memory GAP uses. If this is below what your machine has available (this happens for example under Windows) extending the workspace is impossible. Start GAP with more memory or use the -a option to pre-allocate initially a large piece of workspace. GAP complains: ``corrupted completion file''. Some library files got changed without rebuilding the completion files. This is often a sign that earlier a bugfix was not installed properly or that you changed the library yourself. In the latter case, start GAP with command line option -N and see section Completion Files. GAP stops with an error message ``exceeded the permitted memory''. Your job got bigger than what is permitted by default (128MB). (This is a safety feature to avoid single jobs wrecking a multi-user system.) You can type return; to continue, if the error message happens repeatedly you better start the job anew and use the command line option -o to set a higher memory limit. make complains about not being able to find files in cnf or src which exist. The dates of the new files were not extracted properly (Alpha-OSF machines are prone to this). Call touch * cnf/* src/* from the main GAP directory (this ought to reset the date of all relevant files to ``now'') and try again. Recompilation does not actually compile changed files. The dates of the new files were not extracted properly. Go in the source directory and touch (UNIX command to change date) the new files. Recompilation fails or the new binary crashes. Call make clean and restart the configure / make process completely from scratch. (It is possible that the operating system and/or compiler got upgraded in the meantime and so the existing .o files cannot be used any longer. A calculation runs into an error ``no method found''. GAP is not able to execute a certain operation with the given arguments. Besides the possibility of bugs in the library this means two things: Either GAP truly is incapable of coping with this task (the objects might be too complicated for the existing algorithms or there might be no algorithm that can cope with the input). Another possibility is that GAP does not know that the objects have certain nice properties (like being finite) which are required for the available algorithms. See sections ApplicableMethod and KnownPropertiesOfObject. Problems specific to Windows The gap.bat file does not start GAP. Make sure you ran instwin.bat. If your version of Windows uses a language other than English you must still edit the resulting file gap.bat in the bin subdirectory, due to a misdesign of Windows. If the path name contains long file names or blanks, you might have to edit the file to rectify the -l argument or to enclose it by apostrophes. Windows complains Out of environment space. Click the batch file instwin.bat or gap.bat which caused the problem with the right mouse button and select Properties,Memory and increase the initial environment space to at least 1024. This will create a pif shortcut which should be used to start GAP. Command line editing does not work under Windows. The default key commands are UNIX-like. GAP also tries to emulate some of the special keys under Windows, however if the key repeat is set too high, Windows loses parts of the codes for these keys and thus GAP cannot recognize them. Windows98 produces the same scan code for all cursor keys. As GAP does not interface directly with the Windows machinery, there is no way around this problem so far. The ^-key cannot be entered. This is a problem if you are running a keyboard driver for some non-english languages. These drivers catch the ^ character to produce the French circumflex accent and do not pass it properly to GAP. No fix is known. Cut and Paste does not work See http://www.gap-system.org/Info4/windows.html for a remedy. If all these remedies fail or you encountered a bug please send a mail to gap-trouble@dcs.st-and.ac.uk. Please give: * a (short, if possible) self-contained excerpt of a GAP session containing both input and output that illustrates your problem (including comments of why you think it is a bug); and * state the type of machine, operating system, (compiler used, if UNIX/Linux) and version of GAP (for example ``gap4r3, fix1'') you are using (the line after the GAP 4 banner starting: GAP4, Version: 4... when your GAP 4 starts up, supplies the information required).