GAP for the Mac (Version 3r4p4 fix 12) This document contains information about GAP that is specific to the port of GAP for the Apple Macintosh (simply called GAP for the Mac below). To run GAP for the Mac you need an Apple Macintosh with a Motorola M68020, M68030, or M68040 processor, or a Power Macintosh. The computer must have at least 6 MByte (PowerMac 8 MB) of (physical) memory and a harddisk. For serious calculations, much more may be needed. The operating system must be System 7.0 or higher, maybe even System 7.5 (freely available from Apple). The section 'Copyright of GAP for the Mac' describes the copyright as it applies to the executable version that we distribute. The section 'Installation of GAP for the Mac' how to install GAP for the Mac, and the section 'Features of GAP for the Mac' describes the special features of GAP for the Mac. A quick overview of the changes in GAP for the Mac can be found in the section 'Version history'. Finally, this introduction contains information about using an external editor and share packages with GAP for the Macintosh. Please report any bugs and/or suggestions concerning the Mac port to the author of GAP for the Macintosh. What's new in version 3r4p4 fix 12 of GAP for the Mac? Apart from the kernel bugfix in GAP itself, the following has changed. * the GAP help menu has been merged with the Mac standard help menu (which is beside the menu bar clock in System 7 and appears as the rightmost GAP menu under System 8.) * there are several new shortcut keys in the GAP menus. * there are numerous bug fixes and improvements in the editor. * 'Runtime()' now measures true microseconds (previously only 60ths of a second). This should give more precise information when using the 'Profile()' function. Please be sure to report any bugs or problems with GAP for the Mac to 'gap-trouble@dcs.st-andrews.ac.uk' (see section 'Known bugs' at the end of this file). Copyright of GAP for the Mac In addition to the general copyright for GAP set forth in the GAP copyleft conditions, the following terms apply to GAP for the Mac. The system dependent part of GAP for the Mac was written by Burkhard Hoefling. He assigns the copyright to Lehrstuhl D fuer Mathematik. Burkhard Hoefling's port was partly based on an earlier port of GAP for the Mac, which was done by Dave Bayer (dab@math.columbia.edu) and used the Mac Programmers Workshop (MPW) compiler. Many thanks to Dave for his work. Moreover, the built-in editor is based upon the freeware text editor PlainText by Mel Park which, in turn, uses TE32K, a TextEdit replacement by Roy Wood. Installation of GAP for the Mac This section describes a new installation of GAP for the Mac. If you only wish to install a bugfix, you may skip the first steps. Installation of GAP for the Mac is fairly easy. As already mentioned above, GAP must be installed on a hard disk, because it is too large to be run from floppy disks. First create a folder where you want to install GAP, e.g., 'temp' on your hard disk. GAP will be installed in a folder 'gap3r4p4' of this folder. You can later move GAP to another location, for example you can first install it in a folder called 'temp' and once it works move it to another place. You first have to get the ordinary GAP distribution, if possible from the servers closest to you, e.g. 'gap3r4p4'. Make sure to also download all bugfixes in the 'bugfixes' directory. Further, you need the Mac-specific GAP application program and the Mac version of the archive extractor 'unzoo'. You may get one of the application archives 'bin3r4p4-68k.sit' (for 68k Macs), or 'bin3r4p4-PPC.sit' (for Power Macs). A recent version of the archive extractor 'unzoo' is available from the GAP 4 distribution. You may have to get the application archives from the ftp server in St. Andrews (ftp-gap.dcs.st-and.ac.uk). Unpack the 'unzoo' archive, which comes in *MacBinaryII* format, for example using Stuffit Expander. Sometimes, your ftp application may have done this (or part of this) automatically for you. Move the 'unzoo' application and the ordinary GAP distribution into the folder 'temp' and decompress the GAP distribution by launching 'unzoo' and then typing, e.g., '-x -o gap3r4p4' in the 'unzoo' window. Now quit the 'unzoo' application and move it and the files containing the bugfixes (fix1.zoo, ...) into the folder 'gap3r4p4'. Then decompress the bugfixes by re-launching 'unzoo' and typing '-x -o fix??' (where ?? is the bugfix number) for all bugfix files. Make sure you decompress the bugfix files *in the right order*. Unpack the application archive, 'bin3r4p4-68k.sit' or 'bin3r4p4-PPC.sit', as described for the 'unzoo' application. Replace any previous GAP application from 'gap3r4p4' by the new GAP application (GAP 3.4.4 68K or GAP 3.4.4 PPC). Alternatively, you can compile GAP for the Mac yourself. Please contact the author (burkhard.hoefling@minet.uni-jena.de); note that you will need a C compiler to build the Mac-specific applicatons. Set the amount of memory that the GAP applications is given with the 'Info' command in the 'File' menu of the Finder. The preferred amount should never be larger than the amount of physical memory in your machine minus at least 1024 KByte for the system (MacOS 8 and MacOS 9 will definitely require more). The Finder will allocate the preferred amount, or less if less free memory is available. The maximum size of GAP's workspace is the allocated amount minus around another 1260 KByte (PPC: 64 (!) KByte). You should also turn virtual memory on in the Memory control panel. See the section 'Setting up GAP's memory' below for further details. Start GAP and try something in GAP, e.g., the following exercises GAP quite a bit gap> m11 := Group((1,2,3,4,5,6,7,8,9,10,11),(3,7,11,8)(4,10,5,6));; gap> Number( ConjugacyClasses( m11 ) ); The result should be 10. If you have a big version of LaTeX available, you may now want to make a printed copy of the manual. The LaTeX source is in the ':doc:' subdirectory. You must run LaTeX twice to resolve all references. Then print the dvi file. If you are sure that everything is working properly, you can delete the archives 'gap3r4p4.zoo', 'bin3r4p4-68k.sit' and 'bin3r4p4-PPC.sit'. Note that, if you had an old version (before PT 2.0) of GAP installed, you may not be able to see the new GAP icon. (the letters 'G','A' and 'P' in the icon are now sans serif characters, instead of script, and also the icons for GAP documents have changed). The easiest way to solve this and similar problems is to drag the GAP application on the (free) application 'Save a BNDL' by Mike Engber (hopefully still available via the InfoMac archives). Alternatively, you can rebuild your Macintosh's desktop data base by holding down the option and command keys while (re)starting your Mac. That's all, finally you are done. We hope that you will enjoy using GAP. If you have problems installing GAP, do not hesitate to contact 'gap-trouble@dcs.st-andrews.ac.uk'. Features of GAP for the Mac GAP for the Macintosh's online help The GAP manual is available online; it can be accessed most easily via the 'Help' menu. The manual is divided into chapters and sections. The first page is available by selecting 'About GAP' from the 'Help' menu. You can then browse through the sections of the GAP manual by choosing 'preceding/next section/chapter' from the Help menu. In the help window, the arrow keys can be used to move in the manual. Left and right arrow move one section back and forward, respectively; down and up arrow move to the start of the chapter/previous chapter and next chapter, respectively (just as ?<, ?>, ?<< and ?>>. The '-' and '+' keys move you back and forth in the help history, just as ?- and ?+. You may also look up a keyword in GAP's table of contents or index. To do this, select the relevant keyword or keywords, and choose 'Find selection in table of contents'/'Find selection in index' from the 'Help' menu. Alternatively, you can press the command key and double-click on keyword to find it in the table of contents. If you double-click on a keyword while pressing both the option key and the command key, the word will be looked up in the index. Note that the latter method expands a selection to a whole phrase if the selection starts or ends with quotes or parentheses. Thus if you read this document with the built-in GAP editor and click on the first or last word of 'Welcome to GAP' while holding down the command key, the help window 'Welcome to GAP' is displayed. . The above possibilities for getting help are functionally equivalent to the help functions described in the GAP manual (which can be read online by choosing 'Help on help' in the 'Help' menu.) The GAP log window The GAP log window is the window in which GAP displays its results, and from which it reads its input data. GAP is ready to process text when it displays its prompt ('gap>' or 'brk>'). Your input (i.e. the text after the prompt) is read as you type ' The whole input line is read, even if the cursor is not at the end of the input line (- can be used to pass only the text before the cursor to GAP, the rest of the line will appear after the new GAP prompt). The GAP log window cannot be closed, but its close button can be used to clear the contents, except for any lines not yet read by GAP. The length of the text contained in the log window is limited to about 32000 characters. If the log window is full, the first (i.e. oldest) lines will be deleted. Use the 'LogTo()' GAP command (or the corresponding meun command) if you need to record the whole GAP log in a file. The text in the log window before the prompt cannot be edited, but you can copy it and paste it into another window/application. Messages about GAP's garbage collections can be displayed in the GAP log windows; select 'Show garbage collection' in the Windows menu or check the appropriate box in the 'Preferences...' dialog. If 'Always scroll to printout' is checked in the 'Windows' menu and GAP prints something to the GAP log window, it will scroll automatically to the text being printed. This is the default behaviour. If this option is not checked, the portion of the GAP log visible in the window will not change. This is useful for printing large amounts of data, because scrolling slows down the printing process considerably. In any case, GAP will scroll the visible part of the GAP log to the GAP prompt if it waits for or reads user input. Note also that, even if the 'Always scroll to printout' option is unchecked, the GAP log window will still scroll if part of the visible text is being deleted from the log becuase it has exceeded its maximum length (see above). In this case, you may wish to clear the entire log manually by clicking into its close box (upper left corner), or to scroll to the end of the log window. Setting up GAP's workspace Before an application is launched on the Mac, the system needs to know the maximum amount of memory that application will require. This amount can be set by selecting the application in the Finder, and then choosing "Get Info" from the file menu. You can set two values, the minimum size and the preferred size. As mentioned above, the maximum size of GAP's workspace has to be set by changing the preferred amount of memory allocated for the GAP application with the 'Info...' command in the 'File' menu of the Finder. This has to be done before you run GAP. The maximum size of GAP's workspace is the allocated amount minus about 1280 KByte for a 68K Mac (these 1280 KBytes are used for the application code, the stack, data and the GAP log), and only around 64 KBytes In the PPC version (for the GAP log and some data). The best setting depends on whether you use virtual memory or not. The use of virtual memory is strongly recommended. If you are using virtual memory (check the Memory control panel), the amount of memory allocated to GAP should be set to the size of physical RAM on your machine, minus 2048 KBytes for the system; the amount of workspace for GAP is this value minus around 1280K. If you are sure that you don't need so much workspace, set the amount of memory to the required workspace plus 1280K. If you are using a 68K Mac and the Modern Memory Manager (see the Memory control panel), then you may increase this value by around 500 KByte. The 1280K of memory mentioned above are an experimental value; it depends on the system you are using and should be increased by the size of the disk cache, ...; If you notice that GAP uses your hard disk heavily whenever it is performing a garbage collection (Select 'Show garbage collection' in the Windows menu), you should decrease the amount of memory allocated to GAP. If GAP runs out of workspace before this happens, you may try to increas ethe amount of memory allocated to GAP a little. If you don't use virtual memory, the maximum amount of memory you can allocate to GAP is the RAM size minus the memory used by the system minus the sizes of all the files you wish to edit simultaneously with GAP's built-in editor. If you wish to use other applications at the same time as well, you also have to subtract the memory required by them. Setting other GAP options and customising GAP You may wish to change the standard settings of GAP, either permanently or just for the current GAP session. To do this, hold down the command (Apple) key while starting GAP. GAP for the Mac's preferences dialog will pop up, and you can make the desired changes, either for the current GAP session (press the OK button) or save them as the default (save button) in the GAP.options file. Some preferences can also be set while GAP is running; choose "Preferences..." from the Edit menu. You may set the paths for GAP's lib and doc folders (using Unix style path names) if the lib and/or doc folders are not in the folder which contains the GAP application. This can only be changed while GAP starts up. You may also set how many times per second GAP checks for an user interrupt (or any other event, such as a key pressed, or a mouse click) while it is doing calculations. This also determines how long GAP is permitted to calculate at a time when running in the background. Thus a value of 2 makes GAP gain control for 1/2 second at a time (so the front application doesn't react to your input for that time). The same applies to GAP's built-in editor as well. The following table gives you an idea how this value affects GAP's speed. ===================================== | interrupts per second | GAP speed | |=======================|===========| | 1 | 100 % | | 2 | 98 % | | 5 | 95 % | | 10 | 90 % | | 20 | 85 % | | 60 | 80 % | ===================================== You can switch garbage collection messages on and off with the 'Show garbage collection' check box. Note that this is now also possible via the Windows menu without going through the Preferences... box. If you tick 'don't display help warnings', GAP will merely beep if help is not available for the chosen topic, instead of displaying an error message in the Help window. During startup, GAP for the Mac reads a file 'gap.rc' if there is such a file in the folder containing the GAP application. More precisely, this file is read after 'init.g' in the 'lib' folder. To suppress reading this file, tick 'don't read gap.rc'. In order to have the original GAP banner displayed in the log window, you should tick 'show old GAP banner'. File and path (folder) names on the MacIf you want to use files in GAP (for example in the 'Read', 'PrintTo', 'AppendTo', 'LogTo' commands), these files must be identified by UNIX style path names. Those users who are familiar with Unix may skip the rest of this section, noting that the working directory is the one in which the GAP application resides, and that file names on the Mac are not case sensitive. Paths are strings used to describe where a file is stored on a hard disk. There are two ways for specifying GAP path names: absolute and relative paths. An absolute path starts with a '/', then the name of the disk where the file is located, another '/', then a list of folders, each containing the next one, separated by '/', and finally the name of the file, which resides in the last folder in the list. For instance, if your hard disk is called 'My HD', and your file 'program.g' resides (or should be created) in the folder 'programs' in the folder 'documents' on 'My HD', the absolute path name to that file is '/My HD/documents/programs/program.g' Relative path names work similarly, except that the starting point is not a disk but the folder in which the GAP application program resides. Relative path names are formed like absolute ones, except that they do not start with a '/'. Thus, if you want to access the file 'temp.g' in the folder 'tmp' in the GAP folder, you may use the following path name: 'tmp/temp.g' It is also possible to move upward to a parent folder: suppose that the folder containing GAP is called 'applications', which contains a folder 'editor' which in turn contains the file 'program.g', then you could access this file by the path '../editor/program.g'. Note also that GAP for the Mac follows aliases to folders and files. The built-in editor GAP for the Macintosh has a simple built-in editor, which should be straightforward to use. Note that if GAP for the Macintosh reads a file via the "Read()" command or the corresponding command in the 'File' menu (see the GAP manual), and that file is open in the editor, then the contents of the file are read from the editor window, rather than from the (last saved) version of the file on your hard disk. The table below shows the available editing keys. Both Mac keys and GAP (for UNIX) keys are supported; the rule of thumb is that the UNIX style editing keys are accessed via the control key. Note that you can always quit GAP by choosing 'Quit' from the file menu or by pressing -Q, even if GAP is still doing calculations. Note that 'Quit' from the file menu is not the same as the GAP command 'quit', e.g. 'Quit' from the file menu must not be used to leave break loops. ============================================================================= | | function | Mac keys | GAP keys | |=======|==========================|=========================|==============| | Cur- | forward one character | arrow right | -F | | sor | backward one character | arrow left | -B | | move- | to the beginning of the |