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.
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.
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.
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
-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.
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;
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
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