This chapter informs about command line options for GAP under UNIX
and OS X
(see Command Line Options, Advanced Features of GAP),
and features of GAP on the Macintosh (see
Running GAP under MacOS),
.gaprc file (see The .gaprc file),
completion files (see Completion Files),
the GAP compiler (see The Compiler, Suitability for Compilation,
Compiling Library Code),
and how to save and load a GAP workspace
(see Saving and Loading a Workspace).
When you start GAP under UNIX, you may specify a number of options on
the command-line to change the default behaviour of GAP. 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.
GAP for UNIX will distinguish between upper and lower case options.
As is described in Chapter Installing GAP (see Installing GAP),
usually you will not execute GAP directly. Instead you will
call a shell script, with the name
gap, which in turn executes GAP.
This shell script sets some options which are necessary to make GAP
work on your system. This means that the default settings mentioned below
may not be what you experience when you execute GAP on your system.
-his mnemonic for ``help''). GAP exits after printing the summary, all other options are ignored.
gap>. This is useful if you want to run GAP as a filter with input and output redirection and want to avoid the banner and the prompts appearing in the output file.
-Don an empty input line (see quit). This option should not be used when the input is a file or pipe.
-fin this case to enable line editing.
-nshould be used since otherwise every input line will be echoed twice, once by Emacs and once by GAP.
SizeScreen(see SizeScreen) to alter the line length.
SizeScreen(see SizeScreen) to alter the number of lines.
#G FULL 44580/2479kb live 57304/4392kb dead 734/4096kb free
-gtwice, GAP prints a information message every time a partial or full garbage collection is performed. The message,
#G PART 9405/961kb+live 7525/1324kb+dead 2541/4096kb free
Kit is taken as KBytes, if the last character is
Mmemory is taken as MBytes and if it is 'g' or 'G' it is taken as Gigabytes.
Kit is taken as KBytes, if the last character is
Mmemory is taken as MBytes and if it is 'g' or 'G' it is taken as Gigabytes.
-oabove. But while the latter actually allocates more memory if the system allows it and then prints a warning inside a break loop the
-Koptions tells GAP not even to try to allocate more memory. Instead GAP just exits with an appropriate message. The default is that this feature is switched off. You have to set it explicitly when you want to enable it.
-lis used for the first time, the only root directory is
./, i.e., GAP has only one root directory which is the current directory. Usually this option is used inside a startup script to specify where GAP is installed on the system. The
-loption can also be used by individual users to tell GAP about privately installed modifications of the library, additional GAP packages and so on. Section GAP Root Directory explains how several root paths can be used to do this.
/, but GAP will silently add one if it is missing. If path_list does not start or end with a semicolon, then path_list replaces the existing list of root directories. If path_list starts with a semicolon, then path_list is appended to the existing list of root directories. If path_list ends with a semicolon (and does not start with one), then the new list of root directories is the concatenation of path_list and the existing list of root directories. After GAP has completed its startup procedure and displays the prompt, the list of root directories can be viewed in the variable
/lib/init.gduring startup where root_dir is one of the directories in its list of root directories. If GAP cannot find
init.git will print the following warning
gap: hmm, I cannot find 'lib/init.g' maybe use option '-l <gaproot>'?
-rtells GAP not to read the user supplied
-Ltells GAP to load a saved workspace. See section Saving and Loading a Workspace.
-Rtells GAP not to load a saved workspace previously specified via the
The following options are in general not needed for the normal operation of GAP. They are mostly used for debugging.
sbrkto get blocks of memory from (certain) operating systems and it is required that subsequent calls to
sbrkproduce adjacent blocks of memory in this case because GAP only wants to deal with one large block of memory. If the C function
mallocis called for whatever reason, it is likely that
sbrkwill no longer produce adjacent blocks, therefore GAP does not use
mallocto create a buffer when a file is opened, or for some other reason. In order to catch these cases GAP preallocates a block of memory with
mallocwhich is immediately freed. The amount preallocated can be controlled with the
-aoption. If the last character of memory is
Kit is taken as KBytes and if the last character is
Mmemory is taken as MBytes.
bindirectory with in the GAP or package root directory. The subdirectory name is determined from the operating system, processor and compiler details when GAP (resp. the package) is installed. Under rare circumstances, it may be necessary to override this name, and this can be done using the
-Doption tells GAP to print short messages when it is reading or completing files or loading modules. The message,
#I READ_GAP_ROOT: loading 'lib/kernel.g' as GAP file
#I READ_GAP_ROOT: loading 'lib/kernel.g' statically
lib/kernel.g. This compiled module was statically linked to the GAP kernel at the time the kernel was created.
#I READ_GAP_ROOT: loading 'lib/kernel.g' dynamically
lib/kernel.g. This compiled module was dynamically loaded to the GAP kernel at runtime from a corresponding
#I completing 'lib/domain.gd'
lib/domain.gd. See Completion Files for more information about completion of files.
failare identified. Use of this mode is not recommended other than as a transitional step in porting GAP 3 code to GAP 4, because the GAP 4 library may not work reliably in this mode.
quitimmediately from every break loop. This is intended for automated testing of GAP.
-z are used internally
in the GAP compiler and/or on specific operating systems.
This sections describes the features of GAP for MacOS that differ from those described earlier in this chapter.
Since you cannot enter command line options directly when you launch the GAP application on a Macintosh, another mechanism is being used: Hold down any of the command (apple), option, control or shift keys or space bar when launching the GAP application, e.g., by double-clicking on its icon. Please note that some keys have side effects (e.g., pressing the option key usually closes Findeer windows), and that System X behaves slightly differently from other systems.
A dialog box will open, into which you can enter the desired GAP command line options. as described in Command Line Options. For example, if you want GAP to start with a workspace of 32 megabytes, the dialog box should contain the following text:
Note that the dialog box may already contain settings which you have
previously saved. The
OK button accepts the command line for
the current GAP session, and the
Save button can be used to save these options
for subsequent GAP sessions. The
command line options will be saved in a text file called
GAP options in the
Preferences folder in the system folder. You may also modify the file
options directly; note that changes only take effect the next time you launch
There are three additional command line option on the Mac.
The following command line options work differently on the Mac.
-aoption has a different meaning from the one described in Advanced Features of GAP. On the Mac, it must be used to reserve memory for loading dynamic libraries into GAP. See The Compiler for details about dynamic libraries (and note that the PPC version of GAP for MacOS can use dynamic libraries).
-ncommand line options do not have any effect on the Mac.
-ecommand line option enables
-ocommand line option should not normally be used on the Mac. The value set by the
-ooption is only used if it is lower than the size of the workspace that would normally be available for GAP.
The file called
.gaprc on UNIX systems (see The .gaprc file) is called
gap.rc on the Mac; it must be in the same folder as the GAP application.
All interaction between GAP and you takes place via the
window: this is where GAP prints its messages and waits for your input.
The amount of text in this window is limited (see the
-W command line option
above), so don't be surprised if old GAP messages are deleted from the
beginning of the text when this limit is reached. The reason for deleting
old lines is that otherwise GAP may run out of memory just because of
the messages it has printed.
GAP for the Mac now remembers the font and
text size (which can be set choosing
Format... in the
as well as the window position of the GAP log window from one
session to the next.
Almost all of the GAP editing keys described in Section Line Editing work
on the Mac. In addition, GAP for MacOS also supports the usual
editing keys on the Mac, such as Copy and Paste, Undo, arrow keys (also
. Note that you can also move
forward and backward in the command line history by pressing
Quit in GAP's file menu works differently from the
GAP command (see quit):
Quit in the file menu always quits the GAP application, it
cannot be used to quit from a break loop.
GAP for MacOS also contains a simple built-in text editor, which is mainly
intended to create GAP files.
Close from the
File menu work in the usual way.
LogTo commands in the
File menu work basically like the
corresponding GAP commands (see File Operations). The only difference
is that GAP will prompt you for the file with a standard Mac file opening
dialog, so you do not have to enter the path name yourself. (You will see the
file's path name in the log window afterwards). Note that if a file you want
read is open in GAP's built-in editor, then GAP will read the file from
the edit window, not from the disk.
If you press the shift key while choosing
Read... from the
File menu, the
menu item will change to
Reread... which will then use the GAP command
(see Reread) to read the chosen file.
Read... command in the
File menu changes to
Read if the front window
belongs to a file in GAP's built-in editor -- choosing
Read then makes
GAP read that file -- and while the file is being read, the
Abort Read. You cannot close the file's window while it is being
read by GAP -- choose
Abort Read first.
Garbage collection messages, which are switched on and off by the
command line option (see Command Line Options) can also be switched
on and off by choosing
Show garbage collections and
Show partial collections from the
Always scroll to printout is selected in the
Window menu, GAP will
always scroll the
GAP log window so that you can see what GAP is
currently printing. Otherwise, the GAP log window is only scrolled to
the current print position when GAP prints its prompt and
waits for you to enter a command. Note that you may see text lines disappear
Always scroll to printout is off -- this happens if you are
viewing the text at the beginning of the log window and some lines are just
being deleted from the log because it has exceeded its 32000 character limit.
The contents of the
Help menu should be quite self-explanatory. Note that,
unlike in GAP 3 for the Mac, the online help is not displayed in a separate
nor is the online help available while GAP is computing.
Holding down the Command (Apple) key while selecting text does the same as
selecting the text and choosing
Find selection in table of contents from
Help menu, holding down both Command and Option keys while selecting
tries to find the selection in the index.
When you want to refer to files or folders in GAP (for example in the
LogTo commands), or have to specify files
or folders for a command line option, these files must be identified by UNIX
style path names. (Presently, GAP for MacOS also supports Mac path
names, but this may change in the future.)
Users who are familiar with UNIX path names may skip the rest of this section, noting that the working directory (i.e., folder) 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 UNIX 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
My HD, the absolute path name to that file is
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
tmp in the GAP folder, you may use the following path name:
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. The path
to the GAP folder itself, and
../ refers to ``the folder above''.
Note also that GAP for the Mac follows (resolves) aliases to folders and files.
When you start GAP, it looks for the file with the name
.gaprc in your
home directory (on UNIX systems). On a Macintosh or a Windows system the
equivalent to the
.gaprc file is
gap.rc, and for it to be read it must
be in the same folder as the GAP application.
(Note that the file must be called
gap.rc. If you use a Windows text
editor, in particular if your default is not to show file suffixes, you
might accidentaly create a file
gap.rc.doc which GAP will
If such a file is found it is read after
/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"); Ac := Action; AcHom := ActionHomomorphism; RepAc := RepresentativeAction;
If you have already a
.gaprc file for GAP 3, its settings might not be
compatible with GAP 4. In this case it has to be removed. On UNIX Systems
.gaprc file can be used to load alternatively a
.gap4rc file from your home directory.
if IsBound(Permutations) then # GAP 3 Exec("echo \"READ(\\\"`pwd ~`/.gap3rc\\\");\" > /tmp/jJj"); else # GAP 4 Exec("echo \"READ(\\\"`pwd ~`/.gap4rc\\\");\" > /tmp/jJj"); fi; Read("/tmp/jJj");
The standard distribution of GAP already contains completion files so in general you do not need to create these files by yourself.
When starting, GAP reads in the whole library. As this takes some time, library files are normally condensed into completion files. These completion files contain the basic skeleton of the library but not the function bodies. When a function body is required, for example because you want to execute the corresponding function, the library file containing the function body is completed.
Completion files reduce the startup time of GAP drastically. However, this technique also means that the information stored in the completion files and the library must be consistent. If you change a library file without recreating the completion files disaster is bound to happen.
Bugfixes distributed for GAP will also update the completion files. Therefore you only need to update them if you have changed the library by yourself.
However, if you are modifying a library file a more convenient way is to
-X option (see Command Line Options) that allows you (in most
cases) to use the completion files for the unchanged parts of library
files and avoids using the completion files for the changed parts. After
you have finished modifying the library files you can recreate the
completion files using:
CreateCompletionFiles( ) F
To create completion files you must have write permissions to
which defaults to the first root directory. Start GAP with the
option (to suppress the reading of any existing completion files), then
execute the command
);, where path is a
string giving a path to the home directory of GAP (the directory
This produces, in addition to lots of informational output, the completion files.
$ gap4 -N gap> CreateCompletionFiles(); #I converting "gap4/lib/read2.g" to "gap4/lib/read2.co" #I parsing "gap4/lib/process.gd" #I parsing "gap4/lib/listcoef.gi" ...
ARCH_IS_UNIX( ) F
tests whether GAP is running on a UNIX system.
ARCH_IS_MAC( ) F
tests whether GAP is running on a Macintosh under MacOS
ARCH_IS_WINDOWS( ) F
tests whether GAP is running on a Windows system.
The GAP compiler GAC creates C code from GAP code and then calls the system's C compiler to produce machine code from it. This can result in a speedup (see section Suitability for Compilation for more details).
To use the compiler to produce dynamically loadable modules,
call it with the
M193 /home/ahulpke > gap4/bin/i386-ibm-linux-gcc2/gac -d test.g gap4/bin/i386-ibm-linux-gcc2/gap -C /tmp/5827_test.c test.g Init_Dynamic gcc -fpic -ansi -Wall -O2 -o /tmp/5827_test.o -I gap4/bin/i386-ibm-linux-gcc2/../../src -c /tmp/5827_test.c ld -Bshareable -x -o test.so /tmp/5827_test.o rm -f /tmp/5827_test.o rm -f /tmp/5827_test.cThis produces a file
To load a compiled file, the command
LoadDynamicModule is used. This
command loads filename as module. If given, the CRC checksum crc must
match the value of the module (see CRC Numbers).
gap> LoadDynamicModule("./test.so"); gap> CrcFile("test.g"); 2906458206 gap> LoadDynamicModule("./test.so",1); Error, <crc> mismatch (or no support for dynamic loading) called from <function>( <arguments> ) called from read-eval-loop Entering break read-eval-print loop ... you can 'quit;' to quit to outer loop, or you can 'return;' to continue brk> quit; gap> LoadDynamicModule("./test.so",2906458206);
If you want to see or modify the intermediate C code, you can also instruct
the compiler to produce only the C files by using the option
-C instead of
There are some known problems with C code produced with the GAP compiler on 32 bit architectures and used on 64 bit architectures (and vice versa).
On some operating systems, once you have loaded a dynamic module with a certain filename, loading another with the same filename will have no effect, even if the file on disk has changed.
Typically algorithms spend large parts of their runtime only in small parts of the code. The design of GAP reflects this situation with kernel methods for many time critical calculations such as matrix or permutation arithmetic.
Compiling an algorithm whose time critical parts are already in the kernel of course will give disappointing results: Compilation will only speed up the parts that are not already in the kernel and if they make us a small part of the runtime, the overall gain is small.
Routines that benefit from compilation are those which do extensive operations with basic data types, such as lists or small integers.
The most tempting code to compile is probably the library. This section describes the mechanism used to make GAP recognize compiled versions of library files. Note however that there is no point in compiling the whole library as typically only few functions benefit from compilation as described in Section Suitability for Compilation.
All files that come with GAP are read using the internal function
READ_GAP_ROOT. This function then checks whether a compiled version of the
file exists and if its CRC number (see CRC Numbers) matches the file.
If it does, the compiled version is loaded. Otherwise the file is read.
You can start GAP with the
-D -N option to see information printed
about this process.
To make GAP find the compiled versions, they must be
put in the
/compiled directory (systemname is the name
you gave for compilation, for example
i386-ibm-linux-gcc2). They have
to be called according to the following scheme:
Suppose the file is
humpty/dumpty.gi in the GAP home
directory. Then the compiled version will be
/compiled/humpty/gi/dumpty.so. That is, the directory
hierarchy is mirrored under the
compiled directory. A further directory
level is added for the suffix of the file,
and the suffix of the compiled version of the file is set to
(as produced by the compiler).
For example we show how
to compile the
combinat.gi file on a Linux machine. Suppose we are in
the home directory of the gap distribution.
bin/gac -d lib/combinat.gi
creates a file
combinat.so. We now put it in the right place, creating
also the necessary directories:
mkdir bin/i386-ibm-linux-gcc2/compiled mkdir bin/i386-ibm-linux-gcc2/compiled/lib mkdir bin/i386-ibm-linux-gcc2/compiled/lib/gi mv combinat.so bin/i386-ibm-linux-gcc2/compiled/lib/gi
If you now start GAP and look, for example, at the function
combinat.gi, you see it is indeed compiled:
gap> Print(Binomial); function ( <<arg-1>>, <<arg-2>> ) <<compiled code>> end
The command line option
-M disables the loading of compiled modules and
always reads code from the library.
CRC (cyclic redundancy check) numbers provide a certain method of doing checksums. They are used by GAP to check whether files have changed. Whenever files are ``condensed'' -- for example for completion files (see Section Completion Files) or when compiling files (see Section The compiler) -- such a checksum is computed implicitly and stored within the condensed file.
When reading a condensed version of the file instead of the original one,
the CRC checksum, which is computed via
CrcFile (see CrcFile), can be
used to check whether the original has been changed in the meantime, e.g.
gap> CrcFile("lib/morpheus.gi"); 2705743645
will save a ``snapshot'' image of the current GAP workspace in the file
filename. This image then can be loaded by another copy of GAP which
then will behave as at the point when
SaveWorkspace was called.
gap> a:=1; gap> SaveWorkspace("savefile"); true gap> quit;
SaveWorkspace can only be used at the main
gap> prompt. It cannot
be included in the body of a loop or function, or called from a break loop.
A saved workspace can be loaded by starting GAP with the option
(see Command Line Options).
This will start GAP and load the workspace.
you@unix> gap -L savefile gap> a; 1
Please note that paths to workspaces have to be given in full, expansion of the tilde to denote a home directory will not work.
Under UNIX, it is possible to compress savefiles using
typically reduces the size of a workspace by a factor 3 or 4.
If GAP is started with a compressed savefile (omit the
it will try to locate
gzip on the system and uncompress the file
automatically while reading it.
you@unix> gzip -9 savefile you@unix> gap -L savefile gap> a; 1
We cannot guarantee that saved workspaces are portable between different system architectures or over different versions of GAP or its library.
If compiled modules had been loaded into GAP before the workspace
was saved, they will be loaded into the new GAP session during the
workspace loading process. If they are not available then the load
will fail. Additional compiled modules will not be used, even if
they are available, although they may be loaded later using
SaveWorkspace may sometimes produce warning messages, as in
gap> SaveWorkspace("b5"); #W bad bag id 4 found, 0 saved #W bad bag id 20 found, 0 saved true
A small number of such messages can probably be ignored (they arise
because the garbage collector may not always collect all dead objects,
and dead objects may contain data that
SaveWorkspace does not know how
GAP packages which had been loaded before the workspace was saved are loaded also when the workspace is loaded. Packages which had been available but not loaded before the workspace was saved are available also when the workspace is loaded, provided these packages have not been upgraded. Packages which have been newly installed after the workspace was saved are not available when the workspace is loaded.
GAP provides hooks for functions which are called when the prompt is to be printed and when an input line is finished.
An example of using this feature is the following function.
ColorPrompt(true); GAP changes its user interface: The
prompts and the user input are displayed in different colors. It
also sets the variable
true (which has the side
effect that some help pages are also displayed with color markup.
Switch the colored prompts off with
Note that this will only work if your terminal emulation in which
you run GAP understands the so called ANSI color escape sequences
- almost all terminal emulations on current UNIX/Linux (
konsole, ...) systems do so.
The colors shown depend on the terminal configuration and cannot be forced from an application. If your terminal follows the ANSI conventions you see the standard prompt in bold blue and the break loop prompt in bold red, as well as your input in red.
If it works for you and you like it, put the line
ColorPrompt(true); in your
.gaprc file (see The .gaprc file).
[Top] [Up] [Previous] [Next] [Index]
GAP 4 manual