3 Running GAP

Sections

1. Command Line Options
2. Advanced Features of GAP
3. Running GAP under MacOS
4. The .gaprc file
5. Completion Files
6. The Compiler
7. Suitability for Compilation
8. Compiling Library Code
9. CRC Numbers
10. Saving and Loading a Workspace

This chapter informs about command line options for GAP under UNIX (see Command Line Options, Advanced Features of GAP), options and features of GAP on the Macintosh (see Running GAP under MacOS), the .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).

3.1 Command Line Options

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 Installation of GAP for UNIX), 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.

-h

tells GAP to print a summary of all available options (-h is mnemonic for ``help''). GAP exits after printing the summary, all other options are ignored.

-b

tells GAP to suppress the banner. That means that GAP immediately prints the prompt. This is useful when, after a while, you get tired of the banner.

-q

tells GAP to be quiet. This means that GAP displays neither the banner nor the prompt 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.

-e

tells GAP not to quit when receiving a ctr-D on an empty input line (see quit). This option should not be used when the input is a file or pipe.

-f

tells GAP to enable the line editing and history (see Line Editing).

In general line editing will be enabled if the input is connected to a terminal. There are rare circumstances, for example when using a remote session with a corrupted telnet implementation, when this detection fails. Try using -f in this case to enable line editing.

-n

tells GAP 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 GAP. For example if GAP 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 GAP.

-x length

With this option you can tell GAP how long lines are. GAP uses this value to decide when to split long lines. After starting GAP you may use SizeScreen (see SizeScreen) to alter the line length.

The default value is 80, unless another value can be obtained from the Operating System, which is the right value if you have a standard ASCII terminal. 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 GAP how many lines your screen has. GAP uses this value to decide after how many lines of on-line help it should wait. After starting GAP you may use SizeScreen (see SizeScreen) to alter the number of lines.

The default value is 24, unless another value can be obtained from the Operating System, which is the right value if you have a standard ASCII terminal. 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.

-g

tells GAP to print a information message every time a full garbage collection is performed.

#G  FULL 44580/2479kb live   57304/4392kb dead   734/4096kb free

For example, this tells you that there are 44580 live objects that survived a full garbage collection, that 57304 unused objects were reclaimed by it, and that 734 KBytes from a total allocated memory of 4096 KBytes are available afterwards.

-g -g

If you give the option -g twice, 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

for example, tells you that 9405 objects survived the partial garbage collection and 7525 objects were reclaimed, and that 2541 KBytes from a total allocated memory of 4096 KBytes are available afterwards.

-m memory

tells GAP to allocate memory bytes at startup time. If the last character of memory is k or K it is taken as KBytes, if the last character is m or M memory is taken as MBytes and if it is 'g' or 'G' it is taken as Gigabytes.

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

-o memory

tells GAP to allocate at most memory bytes. If the last character of memory is k or K it is taken as KBytes, if the last character is m or M memory is taken as MBytes and if it is 'g' or 'G' it is taken as Gigabytes.

Under UNIX the default amount is 256 MBytes. If more than this amount is required during the GAP session, GAP prints an error messages and enters a break loop.

-K memory

is like -o above. But while the latter actually allocates more memory if the system allows it and then prints a warning inside a break loop the -K options 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.

-l path_list

can be used to modify GAP's list of root directories (see GAP Root Directory). Before the option -l is 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 -l option 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.

path_list should be a list of directories separated by semicolons. No whitespace is permitted before or after a semicolon. Each directory name should end with a pathname separator, i.e., /, 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 GAP_ROOT_PATHS.

GAP will attempt to read the file root_dir/lib/init.g during startup where root_dir is one of the directories in its list of root directories. If GAP cannot find init.g it will print the following warning

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

It is not possible to use GAP without the library files, so you must not ignore this warning. You should leave GAP and start it again, specifying the correct root path using the -l option.

-r

The option -r tells GAP not to read the user supplied  /.gaprc files.

-L filename

The option -L tells GAP to load a saved workspace. See section Saving and Loading a Workspace.

-R

The option -R tells GAP not to load a saved workspace previously specified via the -L option.

filename ...

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

3.2 Advanced Features of GAP

The following options are in general not needed for the normal operation of GAP. They are mostly used for debugging.

-a memory

GASMAN, the storage manager of GAP uses sbrk to get blocks of memory from (certain) operating systems and it is required that subsequent calls to sbrk produce adjacent blocks of memory in this case because GAP only wants to deal with one large block of memory. If the C function malloc is called for whatever reason, it is likely that sbrk will no longer produce adjacent blocks, therefore GAP does not use malloc itself.

However some operating systems insist on calling malloc to 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 malloc which is immediately freed. The amount preallocated can be controlled with the -a option. If the last character of memory is k or K it is taken as KBytes and if the last character is m or M memory is taken as MBytes.

-A

By default, some GAP packages (see GAP Packages) are loaded, if present, into the GAP session when it starts. This option disables (actually toggles) this behaviour, which can be useful for debugging or testing.

-B architecture

Executable binary files that form part of GAP or of a GAP package are kept in a subdirectory of the bin directory 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 -B option.

-D

The -D option 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

tells you that GAP has started to read the library file lib/kernel.g.

#I  READ_GAP_ROOT: loading 'lib/kernel.g' statically

tells you that GAP has used the compiled version of the library file 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

tells you that GAP has loaded the compiled version of the library file lib/kernel.g. This compiled module was dynamically loaded to the GAP kernel at runtime from a corresponding .so file.

#I  completing 'lib/domain.gd'

tells you that GAP has completed the file lib/domain.gd. See Completion Files for more information about completion of files.

-M

tells GAP not to check for, nor to use, compiled versions of library files.

-N

tells GAP not to check for, nor to use, completion files, see Completion Files.

-O

enables a GAP 3 compatibility mode, in which (for instance) the values false and fail are 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.

-T

suppresses the usual break loop behaviour of GAP. With this option GAP behaves as if the user quit immediately from every break loop. This is intended for automated testing of GAP.

-X

tells GAP to do a consistency check of the library file and the corresponding completion file when reading the completion file.

-Y

tells GAP to do a consistency check of the library file and the corresponding completion file when completing the library file.

-i filename

changes the name of the init file from the default init.g to filename.

Additional options, -C, -U, -P, -W and -z are used internally in the GAP compiler and/or on specific operating systems.

3.3 Running GAP under MacOS

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:

-m 32m

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 GAP options directly; note that changes only take effect the next time you launch GAP.

There are three additional command line option on the Mac.

-z n

sets the time between checks for events (keystrokes, mouse clicks etc.) to n/60 second. Lower values make GAP more responsive but computations are somewhat slower. A value greater than 60 is not recommended, the default value for n is 6.

-P m

sets the amount of memory required for printing. The reason is that printer drivers may require quite a bit of memory, and may even crash if not enough is found. To prevent this, GAP will not print unless at least the specified amount of memory is available. The default value is 64 Kilobytes, which is enough for the Apple LaserWriter printer driver. Setting the printing memory to 0 disables printing altogether.

-W m

sets the size of the log window to m bytes. This means that if the text in the log window exceeds this amount, then lines at the beginning of the log are deleted. The default value is 32 Kilobytes.

The following command line options work differently on the Mac.

-a

On the Mac, the -a option 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).

-f, -n

The -f and -n command line options do not have any effect on the Mac.

-e

The -e command line option enables ctr-D.

-o

The -o command line option should not normally be used on the Mac. The value set by the -o option 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 GAP log 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 Edit menu) 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 with shift, option and command. Note that you can also move forward and backward in the command line history by pressing ctrl-arrow down and ctrl-arrow up.

Note that Quit in GAP's file menu works differently from the quit 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. New, Open..., Save and Close from the File menu work in the usual way.

The Read... and 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 to 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 Reread (see Reread) to read the chosen file.

The 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 File menu item changes to 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 -g 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 Window menu.

If 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 even if 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 window, 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 the 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 Read, PrintTo, AppendTo, 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 documents on My HD, the absolute path name to that file is

/My HD/documents/programs/program.g

Relative path names work similarly, except that the starting point is not a disk but the folder in which the GAP application program resides. Relative path names are formed like absolute ones, except that they do not start with a /. Thus, if you want to access the file temp.g in the folder tmp in the GAP folder, you may use the following path name: tmp/temp.g. It is also possible to move upward to a parent folder: suppose that the folder containing GAP is called applications, which contains a folder editor which in turn contains the file 'program.g', then you could access this file by the path ../editor/program.g. The path ./ refers 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.

3.4 The .gaprc file

When you start GAP, it looks for the file with the name .gaprc in your home directory (on UNIX systems). On a Macintosh 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. 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");
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 the following .gaprc file can be used to load alternatively a .gap3rc or 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");

3.5 Completion Files

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 use the -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:

$ 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"
...

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

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

bin/gac -d lib/combinat.gi

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

gap> Print(Binomial);
function ( <<arg-1>>, <<arg-2>> )
    <<compiled code>>
end

gap> CrcFile("lib/morpheus.gi");
2705743645

gap> a:=1;
gap> SaveWorkspace("savefile");
true
gap> quit;

you@unix> gap -L savefile
gap> a;
1

you@unix> gzip -9 savefile
you@unix> gap -L savefile
gap> a;
1

gap> SaveWorkspace("b5");
#W bad bag id 4 found, 0 saved
#W bad bag id 20 found, 0 saved
true