Instructions for Getting Started with GAP

[In what follows, the links assume that the USA server (http://www.ccs.neu.edu/mirrors/GAP/NEU/) is being used. If this does not apply in your case, do not use the links here but find the equivalent on your server's page.]

The GAP page is fairly well laid out. If you need to become acquainted with GAP, I would recommend that you browse through the first section, About GAP. While you may also wish to visit the GAP Support and GAP Miscellanea sections, here we will focus on the Get GAP section.

If you feel very confident about navigating with computers and can "follow your nose", you may find it faster to use an FTP client and use the addresses found at the FTP Server. Otherwise, I suggest that you use the GAP 4 Distribution link.

Here are the steps that you want to take:

1. The first step is to make sure that you satisfy the System Requirements to run GAP.

2. From the GAP 4 Distribution link, download one of the following.
   • INSTALL (for Unix users)
   • INSTALL-MAC.TXT (for Macintosh users)
   • INSTALL.WIN (for Windows users)
   Print this out and read through it completely before beginning the next step.

3. Create or choose a directory (folder) into which you wish to download the GAP files.

4. Into the chosen directory (which will be assumed to be called "GAP"), download one of the following. This application is used to decompress/extract the other files that will be downloaded. For Macintosh users, this Stuffit file should automatically decompress; if this is not the case, you will need to use the free program Stuffit Expander on this file. (You may have this application already on your hard disk, but if not, you can find it on the web from http://www.aladdinsys.com/expander/index.html.)
   • unzoo.c (for Unix users)
   • unzoo-4.2-PPC.sit (for Power Macintosh or IMac users)
   • unzoo-4.2-68k.sit (for 68K Macintosh users)
   • unzoo.exe (for Windows users)

5. Into the GAP directory, download one of the following. This is the "All-in-one" archive of GAP materials.
   • gap4r2.zoo (for Unix users)
   • gapmac4r2.zoo (for Macintosh users)
     [For Netscape users downloading the Macintosh version: Netscape may not know what to do with a .zoo file, so it writes it to the screen as it downloads. Wait until this is done and then do a Save As... to the GAP directory.]
   • gappc4r2.zoo (for Windows users - NOTE: some have experienced this file, and other .zoo files, becoming filename.zoo.zoo; if you experience this, remove one of the .zoo extensions in each case.)

6. Now we wish to extract the GAP materials with the unzoo application. This will create the home (working) directory for GAP, called gap4r2; all GAP files should reside here.
   • Unix users -- follow your documentation guidelines in the INSTALL file.

   • Macintosh users -- with unzoo and gapmac4r2.zoo in the same folder, double-click on unzoo. When greeted with the "Enter a command line or an empty line to quit:", type in (without the quotes) "-x gapmac4r2.zoo" and then RETURN. Many lines will be returned as various files are extracted. Quit unzoo by typing the RETURN key when asked "Enter a command...".

   • Windows users -- with unzoo and gappc4r2.zoo in the same folder, go into this folder using Windows Explorer and double-click on unzoo. When greeted with the "Enter a command line or an empty line to quit:", type in (without the quotes) "-x gappc4r2.zoo" and then RETURN. Many lines will be returned as various files are extracted. Quit unzoo by typing the RETURN key when asked "Enter a command...".

7. For Macintosh users, there are pre-compiled binaries of the GAP application. Select one of the following and download it into the GAP directory. As above, this Stuffit file should automatically decompress. Place the GAP 4 application into the gap4r2 folder.
   • bin4r2n3-PPC.sit (for Power Macintosh or IMac users)
   • bin4r2n3-68k.sit (for 68K Macintosh users)

8. For Windows users, open up the gap4r2 directory and double-click on instwin.bat. Then close the MS-DOS window.

9. Do a quick test of GAP. For Macintosh users, double-click on the GAP 4 application. For Windows users, double-click on the file named "gap" inside GAP\gap4r2\bin. On any platform, the program will start, give a splash screen, and then try to load the library files. If you get a complaint about not finding some library file, be sure you have correctly done the previous steps. After a short period, you will be given the GAP prompt:
   

   gap>

   Type 2+2; (followed by Return). You should have 4 returned on the next line. Now type quit; and the Return key. (In both cases, the semicolon indicates the end of a GAP command; this is not optional.)

10. There are some bug fix files that you may wish to download. Go to the bugfix page. Read the instructions carefully, in particular about applying the bugfixes in the particular order. Download the bugfix files into the gap4r2 directory (at the top level, in the GAP folder). Note the names of the files that you have downloaded. Move the unzoo application into this directory also. Start up the unzoo application and as before type in (without quotes) "-x filename", where you give the appropriate filename. In some cases you may be asked if you wish to replace previous files. You will want to type "All". After extracting a file, you may wish to read the corresponding Description file. Here are some special instructions for the three platforms.
    • Unix users - nothing to add
    • Macintosh users - you only need to download the bug fixes; the GAP application is the same as was downloaded in a previous step
    • Windows users - download the bug fixes and the latest wbin4r2 file (which replaces the original binary application)

11. Optionally, you may wish to download files that have been shared by others that can be used to extend GAP. These can be found on the GAP 4 Share Packages page. In each case, if you find that you wish to download a package, proceed as follows: click to download on the package file(s) and READ ME file(s) (placing them into the gap4r2 directory), open up the unzoo application (which should also be in the gap4r2 directory) and type (without the quotes) "-x filename" where filename corresponds exactly to the name of the file that needs extracting. This will create a new directory with a similar name containing documentation and all the other necessary files.

12. After you are confident that GAP is working correctly, you can delete any of the *.zoo files from which you have extracted the necessary files.

13. Send a short e-mail message to gap@dcs.st-and.ac.uk containing your full name and address indicating that you have downloaded the package (per the request at the GAP site)

14. You may wish to read the INSTALL document again at this point.

15. You may wish to take a tour of the gap4r2 directory. The casual user will find the doc folder most useful (and perhaps the tst folder as well). Here you will find the files to construct the documentation for GAP. The GAP manual comes in four major "books": tut (a beginner's tutorial), ref (the reference manual), prg (programmer's tutorial), and ext (programmer's reference). These four subdirectories contain the TeX files used to build the manual. Inside each one is a dvi file that contains the TeX output.

16. Alternatively, the standard distribution also contains a directory called htm inside the doc directory. This contains all the documentation in files suitable for a browser. This may be a convenient method of browsing through the documentation.

17. Another alternative is to go to the ftp site (ftp://ftp.ccs.neu.edu/pub/mirrors/ftp-gap.dcs.st-and.ac.uk/pub/gap/gap4/) and download either docpdf4r2.zoo or docps4r2.zoo. The former provides the documentation in .pdf format suitable for Adobe Acrobat Reader (freely downloadable from http://www.adobe.com/products/acrobat/readstep.html) while the latter provides the documentation in PostScript form. For printing purposes, you may find either of these two to provide the best results. They will provide a set of files called manual.pdf or manual.ps. If you download either of these into the GAP directory (one level above gap4r2) and also place unzoo there, then upon extracting with unzoo in a fashion similar to above (-x filename), they will be properly placed within the doc directory. If you place these in any other place, the pdf docs are placed within a new gap4r2\doc\* directory.

18. Read and try out items in the Tutorial.

19. Windows users may wish to add GAP to Start menu. [Received from a friend; use as is.]