56 Getting and Installing GAP

GAP3 runs on several different operating systems. It behaves slightly different on each of those. This chapter describes the behaviour of GAP3, the installation, and the options on some of those operating systems.

Currently it contains sections for UNIX (see GAP for UNIX), WINDOWS (see GAP for Windows), and Mac/OSX (see "GAP for Mac/OSX").

For other systems the section Porting GAP gives hints how to approach such a port.

Subsections

  1. Getting GAP
  2. GAP for UNIX
  3. Installation of GAP for UNIX
  4. Features of GAP for UNIX
  5. GAP for Windows
  6. Copyright of GAP for Windows
  7. Installation of GAP for Windows
  8. Features of GAP for Windows
  9. GAP for Mac/OSX
  10. Copyright of GAP for Mac/OSX
  11. Installation of GAP for Mac/OSX
  12. Features of GAP for Mac/OSX
  13. Porting GAP

56.1 Getting GAP

GAP3 is distributed free of charge. You can give it away to your colleagues. GAP3 is not in the public domain, however. In particular you are not allowed to incorporate GAP3 or parts thereof into a commercial product.

This distribution of GAP3 is maintained by Jean Michel, jean.michel@imj-prg.fr. I would appreciate if let me know, e.g., by sending a short e-mail message, if you are using it. I also take bug reports.

If you publish some result that was partly obtained using GAP3, we would appreciate it if you would cite GAP3, just as you would cite another paper that you used. Specifically, please refer to

[S+ 97] Martin Sch"onert et.al.  GAP -- Groups, Algorithms, and Programming.
        Lehrstuhl D f"ur Mathematik, Rheinisch Westf"alische Technische
        Hochschule, Aachen, Germany, sixth edition, 1997.
Again we would appreciate if you could inform us about such a paper.

This distribultion contains full source for everything, the C code for the kernel, the GAP3 code for the library, and the LaTeX code for the manual, which has at present about 1900 pages. So it should be no problem to get GAP3, even if you have a rather uncommon system. Of course, ports to non UNIX systems may require some work. We already have ports for MS-DOS/Windows, and Apple Mac. Note that about 50 MByte of main memory and about 100MB of disk space are required to run GAP3. A full GAP3 installation, including all share packages and data libraries uses up to 100MB of disk space.

The easiest way to get this GAP3 distribution is to download it from http://webusers.imj-prg.fr/~jmichel/gap3.

The original site for the distribution is http://www-gap.dcs.st-and.ac.uk/~gap, but it now distributes GAP34.

At http://webusers.imj-prg.fr/~jmichel/gap3 you can browse this manual and download the system.

56.2 GAP for UNIX

GAP3 runs best under UNIX. In fact it has being developed under UNIX. GAP3 running on any UNIX machine should behave exactly as described in the manual.

The section Installation of GAP for UNIX describes how you install GAP3 on a UNIX machine, and the section Features of GAP for UNIX describe the options that GAP3 accepts under UNIX.

56.3 Installation of GAP for UNIX

Installation of GAP3 for UNIX is fairly easy.

First go to the directory where you want to install GAP3. If you will be the only user using GAP3, you probably should install it in you homedirectory. If other users will be using GAP3 also, you should install it in a public place, such as /usr/local/lib/. GAP3 will be installed in a subdirectory gap3-jm of this directory. You can later move GAP3 to a different location. For example you can first install it in your homedirectory and when it works move it to /usr/local/lib/. In the following example we will assume that you want to install GAP3 for your own use in your homedirectory. Note that certain parts of the output in the examples should only be taken as rough outline, especially file sizes and file dates are not to be taken literally.

Get the distribution gap3-jmxxx.tar.gz where xxx is the date of the version you are downloading (like gap3-jm19feb18.tar.gz for the version released on 30 november 2016). Unpack this archive in the chosen directory with the command

tar -xvzf gap3-jm19feb18.tar.gz

This will create a gap3-jm directory containing the GAP3 distribution. Then edit the shell script gap.sh in the gap3-jm/bin directory according to the instructions in this file (the main thing to do is to set the variable GAP_DIR to the directory where you installed GAP3). Then copy this script to a directory in your search path, i.e., ~/bin/. This script will start GAP3.

If there is no executable in the bin directory matching your system, it means you are attempting a new port. Change into the source directory gap3-jm/src/ and execute make to see which compilation targets are predefined. Choose the best matching target. There is a good chance that linux or linux32 will do the job, otherwise create a new target.

Now start GAP3 and try a few things. The -b option suppresses the banner. Note that GAP3 has to read most of the library for the fourth statement below.

    you@ernie:~ > gap -b
    gap> 2 * 3 + 4;
    10
    gap> Factorial( 30 );
    265252859812191058636308480000000
    gap> Factors( 10^42 + 1 );
    [ 29, 101, 281, 9901, 226549, 121499449, 4458192223320340849 ]
    gap> m11 := Group((1,2,3,4,5,6,7,8,9,10,11),(3,7,11,8)(4,10,5,6));;
    gap> Size( m11 );
    7920
    gap> Factors( 7920 );
    [ 2, 2, 2, 2, 3, 3, 5, 11 ]
    gap> Number( ConjugacyClasses( m11 ) );
    10 

Especially try the command line editing and history facilities, because the are probably the most machine dependent feature of GAP3. 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
should give the following line.

    gap> Factors( 7921 );
    [ 89, 89 ] 

If command line editing does not work, remove the file system.o and try to compile with a different target, i.e., bsd instead of linux or vice versa. If neither works, we suggest that you disable command line editing by calling GAP3 always with the -n option. In any case we would like to hear about such problems.

If your operating system has job control, make sure that you can still stop GAP3, which is usually done by pressing ctr-Z.

If you want to redo the manual after some changes, you need to have LaTeX installed, and ruby to make the html version. Go to the doc subdirectory of gap3-jm and do make doc. This will make files gap3-jm/doc/manual.dvi, gap3-jm/manual.pdf and gap3-jm/htm/chap*.htm. To remove the unneeded .aux files, you can excute make clean in the doc directory. The full manual is, to put it mildly, now rather long (1900 pages).

Thats all, finally you are done. We hope that you will enjoy using GAP3. If you have problems, do not hesitate to contact us.

56.4 Features of GAP for UNIX

When you start GAP3 for UNIX, you may specify a number of options on the command-line to change the default behaviour of GAP3. All these options start with a hyphen -, followed by a single letter. Options must not be grouped, e.g., gap -gq is illegal, use gap -g -q instead. Some options require an argument, this must follow the option and must be separated by a space, e.g., gap -m 256k, it is not correct to say gap -m256k instead.

GAP3 for UNIX will only accept lower case options.

As is described in the previous section (see Installation of GAP for UNIX) usually you will not execute GAP3 directly. Instead you will call a shell script, with the name gap, which in turn executes GAP3. This shell script sets some options as necessary to make GAP3 work on your system. This means that the default settings mentioned below may not be what you experience when you execute GAP3 on your system.

-g

The option -g tells GAP3 to print an information message every time a garbage collection is performed.

#G collect garbage, 1567022 used, 412991 dead, 84.80MB free, 512MB total

For example, this tells you that there are 1567022 live objects that survived a garbage collection, that 412991 unused objects were reclaimed by it, and that 84 MBytes of totally allocated 512 MBytes are available afterwards.

-l libname The option -l tells GAP3 that the library of GAP3 functions is in the directory libname. Per default libname is lib/, i.e., the library is normally expected in the subdirectory lib/ of the current directory. GAP3 searches for the library files, whose filenames end in .g, and which contain the functions initially known to GAP3, in this directory. libname should end with a pathname separator, i.e., /, but GAP3 will silently add one if it is missing. GAP3 will read the file libname/init.g during startup. If GAP3 cannot find this file it will print the following warning

gap: hmm, I cannot find 'lib/init.g', maybe use option '-l <lib>'?

If you want a bare bones GAP3, i.e., if you do not need any library functions, you may ignore this warning, otherwise you should leave GAP3 and start it again, specifying the correct library path using the -l option.

It is also possible to specify several alternative library paths by separating them with semicolons ;. Note that in this case all path names must end with the pathname separator /. GAP3 will then search for its library files in all those directories in turn, reading the first it finds. E.g., if you specify -l "lib/;/usr/local/lib/gap3-jm/lib/" GAP3 will search for a library file first in the subdirectory lib/ of the current directory, and if it does not find it there in the directory /usr/local/lib/gap3-jm/lib/. This way you can built your own directory of GAP3 library files that override the standard ones.

GAP3 searches for the group files, whose filenames end in .grp, and which contain the groups initially known to GAP3, in the directory one gets by replacing the string lib in libname with the string grp. If you do not want to put the group directory grp/ in the same directory as the lib/ directory, for example if you want to put the groups onto another hard disk partition, you have to edit the assignment in libname/init.g that reads

GRPNAME := ReplacedLib( "grp" );

This path can also consist of several alternative paths, just as the library path. If the library path consists of several alternative paths the default value for this path will consist of the same paths, where in each component the last occurrence of lib/ is replaced by grp/.

Similar considerations apply to the character table files. Those filenames end in .tbl. GAP3 looks for those files in the directory given by TBLNAME. The default value for TBLNAME is obtained by replacing lib in libname with tbl.

-h docname

The option -h tells GAP3 that the on-line documentation for GAP3 is in the directory docname. Per default docname is obtained by replacing lib in libname with doc. docname should end with a pathname separator, i.e., /, but GAP3 will silently add one if it is missing. GAP3 will read the file docname/manual.toc when you first use the help system. If GAP3 cannot find this file it will print the following warning

    help: hmm, I cannot open the table of contents file 'doc/manual.toc'
    maybe you should use the option '-h <docname>'?

-m memory

The option -m tells GAP3 to allocate memory bytes at startup time. If the last character of memory is k or K it is taken in KBytes and if the last character is m or M memory is taken in MBytes.

Under UNIX the default amount of memory allocated by GAP3 is 4 MByte. The amount of memory should be large enough so that computations do not require too many garbage collections. On the other hand if GAP3 allocates more virtual memory than is physically available it will spend most of the time paging.

-n

The option -n tells GAP3 to disable the line editing and history (see Line Editing).

You may want to do this if the command line editing is incompatible with another program that is used to run GAP3. For example if GAP3 is run from inside a GNU Emacs shell window, -n should be used since otherwise every input line will be echoed twice, once by Emacs and once by GAP3.

-b

The option -b tells GAP3 to suppress the banner. That means that GAP3 immediately prints the prompt. This is useful when you get tired of the banner after a while.

-q

The option -q tells GAP3 to be quiet. This means that GAP3 does not display the banner and the prompts gap>. This is useful if you want to run GAP3 as a filter with input and output redirection and want to avoid the the banner and the prompts clobbering the output file.

-e

The option -e tells GAP3 not to act on ctrl-D. This means that you have to type explicitely quit; to exit error loops or GAP3 at the prompt. This may be useful if you find ctrl-D too easy to type by accident.

-x length

With this option you can tell GAP3 how long lines are. GAP3 uses this value to decide when to split long lines. The default value is 80.

-y length

With this option you can tell GAP3 how many lines your screen has. GAP3 uses this value to decide after how many lines of on-line help it should display -- <space> for more --. The default value is 24.

GAP3 does not read the variables specifying the screen size

automatically. On most shells you can tell GAP3 by giving the options:

-x $COLUMNS -y $LINES

Further arguments are taken as filenames of files that are read by GAP3 during startup, after libname/init.g is read, but before the first prompt is printed. The files are read in the order in that they appear on the command line. GAP3 only accepts 14 filenames on the command line. If a file cannot be opened GAP3 will print an error message and will abort.

When you start GAP3, it looks for the file with the name .gaprc in your homedirectory. If such a file is found it is read after libname/init.g, but before any of the files mentioned on the command line are read. You can use this file for your private customizations. For example, if you have a file containing functions or data that you always need, you could read this from .gaprc. Or if you find some of the names in the library too long, you could define abbreviations for those names in .gaprc. The following sample .gaprc file does both.

    Read("/usr/you/dat/mygroups.grp");
    Op := Operation;
    OpHom := OperationHomomorphism;
    RepOp := RepresentativeOperation;
    RepsOp := RepresentativesOperation; 

-r

The option -r tells GAP3 to ignore a .gaprc file. This may be useful to see if a problem may be caused by the contents of your .gaprc file.

56.5 GAP for Windows

This sections contain information about GAP3 that is specific to the port of GAP3 for IBM PC compatibles under Windows (simply called GAP3 for Windows below).

To run GAP3 for Windows you need an IBM PC compatible with an Intel 80386, Intel 80486, or Intel Pentium processor, it will not run on IBM PC compatibles with an Intel 80186 or Intel 80286 processor. The system must have at least 4 MByte of main memory and a harddisk. The operating system must be Windows version 5.0 or later or Windows 3.1 or later (earlier versions may work, but this has not been tested).

The section Copyright of GAP for 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 GAP3 for Windows, and the section Features of GAP for Windows describes the special features of GAP3 for Windows.

56.6 Copyright of GAP for Windows

In addition to the general copyright for GAP3 set forth in the Copyright the following terms apply to GAP3 for Windows.

The system dependent part for GAP3 for Windows was written by Steve Linton. He assigns the copyright to the Lehrstuhl D fuer Mathematik. Many thanks to Steve Linton for his work.

The executable of GAP3 for Windows that we distribute was compiled with DJ Delorie's port of the Free Software Foundation's GNU C compiler version 2.7.2. The compiler can be obtained by anonymous ftp from a variety of general public FTP archives. Many thanks to the Free Software Foundation and DJ Delorie for this amazing piece of work.

The GNU C compiler is

Copyright (C) 1989, 1991 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA

under the terms of the GNU General Public License (GPL). Note that the GNU GPL states that the mere act of compiling does not affect the copyright status of GAP3.

The modifications to the compiler to make it operating under Windows, the functions from the standard library libpc.a, the modifications of the functions from the standard library libc.a to make them operate under Windows, and the DOS extender go32 (which is prepended to gapexe.386) are

Copyright (C) 1991 DJ Delorie, 24 Kirsten Ave, Rochester NH 03867-2954, USA

also under the terms of the GNU GPL. The terms of the GPL require that we make the source code for libpc.a available. They can be obtained by writing to Steve Linton (however, it may be easier for you to ftp them from grape.ecs.clarkson.edu yourself). They also require that GAP3 falls under the GPL too, i.e., is distributed freely, which it basically does anyhow.

The functions in libc.a that GAP3 for the 386 uses are

Copyright (c) 1988 Regents of the University of California

under the following terms

All rights reserved.

Redistribution and use in source and binary forms are permitted provided that the above copyright notice and this paragraph are duplicated in all such forms and that any documentation, advertising materials, and other materials related to such distribution and use acknowledge that the software was developed by the University of California, Berkeley. The name of the University may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED AS IS AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

56.7 Installation of GAP for Windows

Installation of GAP3 on WIndows is similar to Unix.

First go to a directory where you want to install GAP3, e.g., c:\. GAP3 will be installed in a subdirectory gap3-jm\ of this directory. You can later move GAP3 to another location, for example you can first install it in d:\tmp\ and once it works move it to c:\. In the following example we assume that you want to install GAP3 in c:\. Note that certain parts of the output in the examples should only be taken as rough outline, especially file sizes and file dates are not to be taken literally.

Get the GAP3 distribution onto your IBM PC compatible --- see the Unix instructions how to get it from the web.

Change into the directory gap-jm\bin\ and edit the script gap.cmd, which starts GAP3, according to the instructions in this file. Then copy this script to a directory in your search path, e.g., c:\bin\, with the commands

    C: > chdir gap-jm\bin
    C:\GAPR4P4\BIN > edit gap.cmd
    # edit the script gap.cmd
    C:\GAPR4P4\BIN > copy gap.cmd c:\bin\gap.cmd
    C:\GAPR4P4\BIN > chdir ..\..
    C: > 

When you later move GAP3 to another location you must only edit this script.

An alternative possibility is to compile a version of GAP3 for use under Windows, on a UNIX system, using a cross-compiler. Cross-compiling versions of gcc can be found on some FTP archives, or compiled according to the instructions supplied with the gcc source distribution.

Start GAP3 and try a few things. Note that GAP3 has to read most of the library for the fourth statement below, so this takes quite a while. Subsequent definitions of groups will be much faster.

    C: > gap -b
    gap> 2 * 3 + 4;
    10
    gap> Factorial( 30 );
    265252859812191058636308480000000
    gap> Factors( 10^42 + 1 );
    [ 29, 101, 281, 9901, 226549, 121499449, 4458192223320340849 ]
    gap> m11 := Group((1,2,3,4,5,6,7,8,9,10,11),(3,7,11,8)(4,10,5,6));;
    gap> Size( m11 );
    7920
    gap> Factors( 7920 );
    [ 2, 2, 2, 2, 3, 3, 5, 11 ]
    gap> Number( ConjugacyClasses( m11 ) );
    10 

Especially try the command line editing and history facilities, because the are probably the most machine dependent feature of GAP3. 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 three commands typing
ctr-P ctr-P ctr-E ctr-B ctr-B ctr-B ctr-B ctr-D 1
should give the following line.

    gap> Factors( 7921 );
    [ 89, 89 ] 

If you have a big version of LaTeX available you may now want to make a printed copy of the manual. Change into the directory gap3-jm\doc\ and run LaTeX twice on the source. The first pass with LaTeX produces the .aux files, which resolve all the cross references. The second pass produces the final formatted dvi file manual.dvi. This will take quite a while, since the manual is large. Then print the dvi file. How you actually print the dvi file produced by LaTeX depends on the printer you have, the version of LaTeX you have, and whether you use a \TeX-shell or not, so we will not attempt to describe it here.

    C: > chdir gap3-jm\doc
    C:\GAPR4P4\DOC > latex manual
    # about 2000 messages about undefined references
    C:\GAPR4P4\DOC > latex manual
    # there should be no warnings this time
    C:\GAPR4P4\DOC > dir manual.dvi
    -a---   4591132 Nov 13 23:29 manual.dvi
    C:\GAPR4P4\DOC > chdir ..\..
    C: > 

Note that because of the large number of cross references in the manual you need a big LaTeX to format the GAP3 manual. If you see the error message TeX capacity exceeded, you do not have a big LaTeX. In this case you may also obtain the already formatted dvi file manual.dvi from the same place where you obtained the rest of the GAP3 distribution.

Note that, apart from the *.tex files and the file manual.bib (bibliography database), which you absolutely need, we supply also the files manual.toc (table of contents), manual.ind (unsorted index), manual.idx (sorted index), and manual.bbl (bibliography). If those files are missing, or if you prefer to do everything yourself, here is what you will have to do. After the first pass with LaTeX, you will have preliminary manual.toc and manual.ind files. All the page numbers are still incorrect, because the do not account for the pages used by the table of contents itself. Now bibtex manual will create manual.bbl from manual.bib. After the second pass with LaTeX you will have a correct manual.toc and manual.ind. makeindex now produces the sorted index manual.idx from manual.ind. The third pass with LaTeX incorporates this index into the manual.

    C: > chdir gap3-jm\doc
    # about 2000 messages about undefined references
    C:\GAPR4P4\DOC > bibtex manual
    # bibtex prints the name of each file it is scanning
    C:\GAPR4P4\DOC > latex manual
    # still some messages about undefined citations
    C:\GAPR4P4\DOC > makeindex manual
    # makeindex prints some diagnostic output
    C:\GAPR4P4\DOC > latex manual
    # there should be no warnings this time
    C:\GAPR4P4\DOC > chdir ..\..
    C: > 

The full manual is, to put it mildly, now rather long (almost 1600 pages). For this reason, it may be more convenient just to print selected chapters. This can be done using the \includeonly LaTeX command, which is present in manual.tex (around line 240), but commented out. To use this, you must first LaTeX the whole manual as normal, to obtain the complete set of .aux files and determine the pages and numbers of all the chapters and sections. After that, you can edit manual.tex to uncomment the \includeonly command and select the chapters you want. A good start can be to include only the first chapter, from the file aboutgap.tex, by editing the line to read \includeonly{aboutgap}. The next step is to LaTeX the manual again. This time only the selected chapter(s) and the table of contents and indices will be processed, producing a shorter dvi file that you can print by whatever means applies locally.

    C:\GAPR4P4\DOC > latex manual
    # many messages about undefined references, 1600 pages output	
    C:\GAPR4P4\DOC > edit manual.tex
    # edit line 241 to include only aboutgap
    C:\GAPR4P4\DOC > latex manual
    # pages 0-196 and 1503-1553 only output no warnings
    C:\GAPR4P4\DOC > dir manual.dvi
    -a---   1291132 Nov 13 23:29 manual.dvi
    C:\GAPR4P4\DOC > 
    # now print the DVI file in whatever way is appropriate

Thats all, finally you are done. We hope that you will enjoy using GAP3. If you have problems, do not hesitate to contact us.

56.8 Features of GAP for Windows

Note that GAP3 for Windows will use up to 128 MByte of extended memory (using XMS, VDISK memory allocation strategies) or up to 128 MByte of expanded memory (using VCPI programs, such as QEMM and 386MAX) and up to 128 MByte of disk space for swapping.

If you hit ctr-C the DOS extender (go32) catches it and aborts GAP3 immediately. The keys ctr-Z and alt-C can be used instead to interrupt GAP3.

The arrow keys left, right, up, down, home, end, and delete can be used for command line editing with their intuitive meaning.

Pathnames may be given inside GAP3 using either slash (/) or backslash (\) as a separator (though \ must be escaped in strings of course).

When you start GAP3 you may specify a number of options on the command-line to change the default behaviour of GAP3. All these options start with a hyphen -, followed by a single letter. Options must not be grouped, e.g., gap -gq is illegal, use gap -g -q instead. Some options require an argument, this must follow the option and must be separated by a space, e.g., gap -m 256k, it is not correct to say gap -m256k instead.

GAP3 for Windows accepts the following (lowercase) options.

-g

The options -g tells GAP3 to print a information message every time a garbage collection is performed.

#G collect garbage, 1931 used, 5012 dead, 912 KB free, 3072 KB total

For example, this tells you that there are 1931 live objects that survived a garbage collection, that 5012 unused objects were reclaimed by it, and that 912 KByte of totally allocated 3072 KBytes are available afterwards.

-l libname

The option -l tells GAP3 that the library of GAP3 functions is in the directory libname. Per default libname is lib/, i.e., the library is normally expected in the subdirectory lib/ of the current directory. GAP3 searches for the library files, whose filenames end in .g, and which contain the functions initially known to GAP3, in this directory. libname should end with a pathname separator, i.e., \, but GAP3 will silently add one if it is missing. GAP3 will read the file libname\init.g during startup. If GAP3 cannot find this file it will print the following warning

gap: hmm, I cannot find 'lib\init.g', maybe use option '-l <lib>'?

If you want a bare bones GAP3, i.e., if you do not need any library functions, you may ignore this warning, otherwise you should leave GAP3 and start it again, specifying the correct library path using the -l option.

It is also possible to specify several alternative library paths by separating them with semicolons ;. Note that in this case all path names must end with the pathname separator \. GAP3 will then search for its library files in all those directories in turn, reading the first it finds. E.g., if you specify -l "lib\;\usr\local\lib\gap3-jm\lib" GAP3 will search for a library file first in the subdirectory lib\ of the current directory, and if it does not find it there in the directory \usr\local\lib\gap3-jm\lib\. This way you can built your own directory of GAP3 library files that override the standard ones.

GAP3 searches for the group files, whose filenames end in .grp, and which contain the groups initially known to GAP3, in the directory one gets by replacing the string lib in libname by the string grp. If you do not want to put the group directory grp\ in the same directory as the lib\ directory, for example if you want to put the groups onto another hard disk partition, you have to edit the assignment in libname\init.g that reads

GRPNAME := ReplacedString( LIBNAME, "lib", "grp" );

This path can also consist of several alternative paths, just as the library path. If the library path consists of several alternative paths the default value for this path will consist of the same paths, where in each component the last occurrence of lib\ is replaced by grp\.

Similar considerations apply to the character table files. Those filenames end in .tbl. GAP3 looks for those files in the directory given by TBLNAME. The default value for TBLNAME is obtained by replacing lib in libname with tbl.

-h docname

The option -h tells GAP3 that the on-line documentation for GAP3 is in the directory docname. Per default docname is obtained by replacing lib in libname with doc. docname should end with a pathname separator, i.e., \, but GAP3 will silently add one if it is missing. GAP3 will read the file docname\manual.toc when you first use the help system. If GAP3 cannot find this file it will print the following warning

    help: hmm, I cannot open the table of contents file 'doc\manual.toc'
    maybe you should use the option '-h <docname>'?

-m memory

The option -m tells GAP3 to allocate memory bytes at startup time. If the last character of memory is k or K it is taken in KBytes and if the last character is m or M memory is taken in MBytes.

GAP3 for Windows will by default allocate 4 MBytes of memory. If you specify -m memory GAP3 will only allocate that much memory. The amount of memory should be large enough so that computations do not require too many garbage collections. On the other hand if GAP3 allocates more virtual memory than is physically available it will spend most of the time paging.

-n

The options -n tells GAP3 to disable the line editing and history (see Line Editing).

There does not seem to be a good reason to do this on IBM PC compatibles.

-b

The option -b tells GAP3 to suppress the banner. That means that GAP3 immediately prints the prompt. This is useful when you get tired of the banner after a while.

-q

The option -q tells GAP3 to be quiet. This means that GAP3 does not display the banner and the prompts gap>. This is useful if you want to run GAP3 as a filter with input and output redirection and want to avoid the the banner and the prompts clobber the output file.

-x length

With this option you can tell GAP3 how long lines are. GAP3 uses this value to decide when to split long lines.

The default value is 80, which is correct if you start GAP3 from the desktop or one of the usual shells. However, if you start GAP3 from a window shell such as gemini, you may want to decrease this value. If you have a larger monitor, or use a smaller font, or redirect the output to a printer, you may want to increase this value.

-y length

With this option you can tell GAP3 how many lines your screen has. GAP3 uses this value to decide after how many lines of on-line help it should display -- <space> for more --.

The default value is 24, which is the right value if you start GAP3 from the desktop or one of the usual shells. However, if you start GAP3 from a window shell such as gemini, you may want to decrease this value. If you have a larger monitor, or use a smaller font, or redirect the output to a printer, you may want to increase this value.

-z freq

GAP3 for Windows checks in regular intervals whether the user has entered ctr-Z or alt-C to interrupt an ongoing computation. Under Windows this requires reading the keyboard status (UNIX on the other hand will deliver a signal to GAP3 when the user entered ctr-C), which is rather expensive. Therefor GAP3 only reads the keyboard status every freq-th time. The default is 20. With the option -z this value can be changed. Lower values make GAP3 more responsive to interrupts, higher values make GAP3 a little bit faster.

Further arguments are taken as filenames of files that are read by GAP3 during startup, after libname\init.g is read, but before the first prompt is printed. The files are read in the order in that they appear on the command line. GAP3 only accepts 14 filenames on the command line. If a file cannot be opened GAP3 will print an error message and will abort.

When you start GAP3, it looks for the file with the name gap.rc in your homedirectory (i.e., the directory defined by the environment variable HOME). If such a file is found it is read after libname\init.g, but before any of the files mentioned on the command line are read. You can use this file for your private customizations. For example, if you have a file containing functions or data that you always need, you could read this from gap.rc. Or if you find some of the names in the library too long, you could define abbreviations for those names in gap.rc. The following sample gap.rc file does both.

    Read("c:\\gap\\dat\\mygroups.grp");
    Op := Operation;
    OpHom := OperationHomomorphism;
    RepOp := RepresentativeOperation;
    RepsOp := RepresentativesOperation; 

56.9 GAP for Mac/OSX

This sections contain information about GAP3 that is specific to the port of GAP3 for Apple Macintosh systems under Mac/OSX (simply called GAP3 for Mac/OSX below).

To run GAP3 for Mac/OSX you need to be written

The section "Copyright of GAP for Mac/OSX describes the copyright as it applies to the executable version that we distribute. The section Installation of GAP for Mac/OSX" describes how you install GAP3 for Mac/OSX, and the section "Features of GAP for Mac/OSX" describes the special features of GAP3 for Mac/OSX.

56.10 Copyright of GAP for Mac/OSX

to be written

56.11 Installation of GAP for Mac/OSX

to be written

56.12 Features of GAP for Mac/OSX

to be written

56.13 Porting GAP

Porting GAP3 to a new operating system should not be very difficult. However, GAP3 expects some features from the operating system and the compiler and porting GAP3 to a system or with a compiler that do not have those features may prove very difficult.

The design of GAP3 makes it quite portable. GAP3 consists of a small kernel written in the programming language C and a large library written in the programming language provided by the GAP3 kernel, which is also called GAP3.

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 GAP3 to a new operating system.

Now lets take a look at the minimal support that GAP3 needs from the operating system and the machine.

First of all you need enough filespace. The kernel sources and the object files need between 3.5 MByte and 4 MByte, depending on the size of object files produced by your compiler. The library takes up an additional 4.8 MBytes, and the online documentation also needs 4 MByte. So you need about 13 MByte of available filespace, for example on a harddisk.

Next you need enough main memory in your computer. The size of the GAP3 kernel varies between different machine, with as little as 300 KByte (compiled with GNU C on an Atari ST) and as much as 600 KByte (compiled with UNIX cc on a HP 9000/800). Add to that the fact the library of functions that GAP3 loads takes up another 1.5 MByte. So it is clear that at least 4 MByte of main memory are required to do any serious work with GAP3.

Note that this implies that there is no point in trying to port GAP3 to plain Windows running on IBM PCs and compatibles. The version of GAP3 for IBM PC compatibles that we provide runs on machines with the Intel 80386, Intel 80486, Pentium or Pentium Pro processor under extended DOS in protected 32 bit mode. (This is also necessary, because, as mentioned below, GAP3 wants to view its memory as a large flat address space.)

Next lets turn to the requirements for the C compiler and its library.

As was already mentioned, the GAP3 kernel is written in the C language. We have tried to use as few features of the C language as possible. GAP3 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.

GAP3 was wriiten for 32-bit compilers (sizeof(int)==4), but it has been ported by Jean Michel to 64 bits, allowing use of terabytes of memory. Since Jean Michel works on Linux machines, this 64-bit version works for now only on such machines. The versions distributed for MAC/OSX and Windows are still 32-bit.

Dependencies on the operating system or compiler are separated in one special file which is called the system file. When you port GAP3 to a new operating system, you probably have to create a new system file. You should however look through the system.c file that we supply and take as much code from them as possible. Currently system.c supports Linux with gcc, Windows with the DJGPP compiler, and OS/X with gcc.

The system file contains the following functions.

First file input and output. The functions used by the three system files mentioned above are fopen, fclose, fgets, and fputs. They are pretty standard, and in fact are in the ANSI C standard library. The only thing that may be necessary is to make sure that files are opened in text mode. However, the most important transformation applied in text mode seems to be to replace the end of line sequence newline-return, used in some operating systems, with a single newline, used in C. However, since GAP3 treats newline and return both as whitespaces even this is not absolutely necessary.

Second you need character oriented input from the keyboard and to the screen. This is not absolutely necessary, you can use the line oriented input and output described above. However, if you want the history and the command line editing, GAP3 must be able to read every single character as the user types it without echo, and also must be able to put single characters to the screen. Reading characters unblocked and without echo is very system dependent.

Third you need a way to detect if the user typed ctr-C to interrupt an ongoing computation in GAP3. Again this is not absolutely necessary, you can do without. However if you want to be able to interrupt computations, GAP3 must be able to receive the interrupt. This can be done in two ways. Under UNIX you can catch the signal that is generated if the user types ctr-C (SIGINT). Under other operating systems that do not support such signals you can poll the input stream at regular intervals and simply look for ctr-C.

Fourth you need a way to find out how long GAP3 has been running. Again this is not absolutely necessary. You can simply always return 0, fooling GAP3 into thinking that it is extremely fast. However if you want timing statistics, GAP3 must be able to find out how much CPU time it has spent.

The last and most important function is the function to allocate memory for GAP3. GAP3 assumes that it can allocate the initial workspace with the function SyGetmem and expand this workspace on demand with further calls to SyGetmem. The memory allocated by consecutive calls to SyGetmem must be adjacent, because GAP3 wants to manage a single large block of memory. Usually this can be done with the C library function sbrk. If this does not work, you can define a large static array in the system file and return this on the first call to SyGetmem and return 0 on subsequent calls to indicate that this array cannot dynamically be expanded. Previous Up Next
Index

gap3-jm
19 Feb 2018