This document describes how to install GAP 4 on a 32-bit Windows (Windows 95 or Windows NT) system. Section "Getting GAP" describes where to get GAP 4 and which files to get. Section "Installation of GAP for Windows" describes the installation process. 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 Windows It is possible to compile GAP for 32-bit Windows using the Cygnus cygwin32 implementation of GCC. We provide such a binary, and have tested that runs under the English version of Windows 98. It is likely that it will also work under later versions such as WindowsNT and Windows XP. It is likely that features of GAP like Process, Exec or the compiler, that rely on a UNIX environment will not work under Windows. The following sections contain information about GAP that is specific to this port of GAP (simply called GAP for Windows below). To run GAP under Windows you need an IBM PC compatible with an Intel Intel 80486, or Intel Pentium processor or better. The system must have at least 16 MByte of main memory and a harddisk. The operating system must be Windows 95 or better. The section Copyright of GAP for Windows describes the copyright as it applies to the executable version that we distribute. The section Installation of GAP for Windows describes how you install GAP for Windows. The compiler we are using to create the Windows binary (Cygnus GNUWin32) provides a C-library that emulates all standard UNIX commands. There are however a few low-level routines that have to be called system-specific and for which we have not yet found out how to do it under Windows. We will try to fix these in a future version. If you have experience in Windows programming and know how to do such things we would very much welcome help. Copyright of GAP for Windows In addition to the general copyright for GAP set forth in the Copyright the following terms apply to GAP for Windows. The executable of GAP for Windows that we distribute was compiled with The gnuwin32 compiler of the cygwin package. This compiler can be obtained by anonymous ftp from a variety of general public FTP archives. Many thanks to the Free Software Foundation and Cygnus Support 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 compiler is copyright under the terms of the GNU General Public License (GPL). You can find details under http://www.cygnus.com/misc/gnu-win32/faq.html The Cygwin32 API library is also covered by the GNU GPL. The executable we provide is linked against this library (and in the process includes GPL'd Cygwin32 glue code). This means that the executable falls under the GPL too, i.e., is distributed freely, which it basically does anyhow. Installation of GAP for Windows Installing GAP under 32-bit Windows should be fairly easy. In the following, we assume that you install GAP in the directory C:\GAP4R3 on a Windows98 machine. (For experts (or users without write permission in the C: directory) it is possible to install GAP in another directory, but this will require specialist knowledge (editing a batch file) which many Windows users do not possess. See section Expert Windows installation for details on how to do this.) 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 Windows-specific files gappc4r3.zoo and the Windows version of the zoo archive extractor unzoo.exe, and copy them in the C: directory. 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. See http://www.gap-system.org/Info/mime.html if you have problems with loading the files. (The zoo archives we provide for GAP contain comments which indicate whether files are text or binary files. The unzoo we provide uses these comments to translate the ``LF'' line endings we use to the Windows style ``CRLF''. If you use another zoo extractor you might lose this information and end up with files that might not conform to your operation system standards.) Open a window with the MS-DOS Command Prompt and go to the C: directory. C:\WINDOWS> cd c:\ Now unpack the distribution with the command C:\> unzoo -x gappc4r3.zoo gap4r3\bin\gap.bat -- extracted gap4r3\doc\aboutgap.tex -- extracted gap4r3\doc\aggroup.tex -- extracted [many more lines] (Afterwards you will not need the file gappc4r3.zoo any longer. If you are short of disk space you can remove it now.) C:\> del gappc4r3.zoo Now go into the directory GAP4R3. If there is a bug fixes (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. C:\> cd GAP4R3 C:\GAP4R3> ../unzoo -x ../fix4r3n3.zoo [extraction information] If the bugfixes provide a new binary, unpack the corresponding file wbinXXX.zoo in the same way. It overwrites the old binary. If you got any GAP packages, extract them in the pkg subdirectory in the same way. 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). (Any GAP package that has a C code component is essentially UNIX-dependent and you may as well delete those; such packages typically describe in their README files that they require configure and make to complete their installation or have a src directory.) The directories trans, small and prim contain data libraries. If you are short of disk space you can erase some of them and any GAP package directories in the pkg directory that you don't need, but then of course you will not be able to access these data and packages. We provide a precompiled binary in the bin subdirectory, so there is no need to compile GAP yourself. The provided binary should work under Windows9x and Windows NT. Now start GAP either by calling C:\GAP4R3> bin\gapw95.exe or by starting the program gapw95.exe in the directory C:\GAP4R3\BIN You should get the GAP banner and then the GAP prompt. (The process of starting GAP may take a little while.) Try a few things to see if the binary works. 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. Note that GAP is developed under UNIX and therefore the key commands are rather UNIX-type then Windows type. We try also to recognize some common Windows key commands such as the arrow keys, but it is likely that not all Windows-special key commands will be recognized: in general GAP will not conform to standard Windows ``look-and feel''. (See below on how to enable cut-and-paste.) 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 ] You also might want to enable cut-and-paste in the GAP window and select a more pleasant icon. You should be able to do this with the PIF file gap.pif in the bin directory (it might show up only as GAP with an MSDOS icon), if necessary following the instructions on the web page http://www.gap-system.org/Info4/windows.html. (If this PIF file does not work, you will have to create a new PIF file. For details on how to do this, see the Documentation provided by Microsoft.) The information about the manual is system independent, you can find it in section The Documentation. A few final reminders: * Make sure that you got and installed the most recent (and probably the corresponding binary). * 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. Expert Windows installation This section decribes how to get a better shell for GAP, how to install GAP in another directory and how to test the installation. Some users report that the rxvt shell gives a btter windows environment for cut/paste etc. You can find information on this at http://www.gap-system.org/Forum/Pasechni.1/Dima.1/Re__Wind.1/1.html If you decide to install GAP in another directory you can do so, but you will have to edit a batch file and use this file to start GAP. First unpack the GAP distribution in the directory you want. Lets suppose you want GAP to reside in the directory C:\SOFTWARE\GAP Extract GAP (as described in the previous section for C:) in this directory. (alternatively, you can also first unpack it in C:\GAP4R3 test it there first, and afterwards move it in the desired location.) You now will have to edit a batch file, that will be used to start GAP. This batch file is needed, since GAP otherwise will not find its library directories. The most natural name for this file would be C:\SOFTWARE\GAP\GAPGAP4R3\BIN\GAP.BAT This file should contain the following single line (which might be broken over in several lines in this instructions since the page width is limited): C:\SOFTWARE\GAP\GAPGAP4R3\bin\gapw95.exe -m 14m -l C:\SOFTWARE\GAP\GAPGAP4R3 %1 %2 %3 %4 %5 %6 %7 %8 If the path includes blanks (such as Program Files), you will have to enclose the -l argument in apostrophes: C:\Program Files\GAP\GAPGAP4R3\bin\gapw95.exe -m 14m -l 'C:\Program Files\GAP\GAPGAP4R3' %1 %2 %3 %4 %5 %6 %7 %8 You now should be able to start GAP by clicking this gap.bat file. You might want to copy this file gap.bat into a directory in your search path (for example the DOS directory) as gap.bat to be able to start GAP by its name from any location: C:\WINDOWS> gap If you want to check your installation, a set of test files is provided, This test is not a necessary part of the installation, it only serves as a confirmation that everything went OK. (Since running these tests might take several hours and requires quite a bit of free memory, you may wish to skip this step or run only part of the tests. This does no harm.) As a quick test we start combinat.tst first. gap> Filename( DirectoriesLibrary("tst"), "combinat.tst" ); "./tst/combinat.tst" gap> ReadTest(last); + $ld: combinat.tst,v 4.7 1997/11/21 10:19:47 ahulpke Exp $ + GAP4stones: 26801 true Note that GAP internally uses / to separate directory names. This will be translated to backslashes for the operating system. Now you can use Read (not ReadTest) to read the file testall.g to run all available test files. (You should not pay too much attention to the GAPstone ratings of the different files. The time measurements are not calibrated and sometimes vary substantially because further tests have been added to a file.) gap> Filename( DirectoriesLibrary("tst"), "testall.g" ); "./tst/testall.g" gap> Read(last); [lines omitted] test file GAP4stones time(msec) ------------------------------------------- [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 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).