Running GAP
options
This chapter informs about command line options for &GAP; (see ), some files in user specific &GAP; root directory (see ) and saving and loading a &GAP; workspace (see ).

Command Line Options
features
UNIX
options
UNIX
GAPInfo.CommandLineOptions

When you start &GAP; from a command line or from a script 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 invalid, use gap -g -q instead. Some options require an argument, this must follow the option and must be separated by whitespace, e.g., gap -m 256m, it is not correct to say gap -m256m instead. Certain Boolean options (-b, -q, -e, -r, -A, -D, -M, -T, -X, -Y) toggle the current value so that gap -b -b is equivalent to gap and to gap -b -q -b -q etc.

&GAP; for UNIX will distinguish between upper and lower case options.

As described in the &GAP; installation instructions (see the INSTALL file in the &GAP; root directory, or at http://www.gap-system.org/Download/INSTALL), usually you will not execute &GAP; directly. Instead you will call a (shell) script, with the name gap, which in turn executes &GAP;. This 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.

During a &GAP; session, one can find the current values of command line options in the record GAPInfo.CommandLineOptions (see ), whose component names are the command line options (without the leading -).

-A
-A
By default, some needed and suggested &GAP; packages (see ) are loaded, if present, into the &GAP; session when it starts. This option disables (actually toggles) the loading of suggested packages, which can be useful for debugging or testing. The needed packages (and their needed packages, and so on) are loaded in any case.
-a
-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. (Most users do not need this option.)

The option argument memory is specified as with the -m option.
-B
-B
architecture
Executable binary files that form part of &GAP; or of a &GAP; package are kept in a subdirectory of the bin directory within 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.
-b
-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. This option can be repeated to enable the banner; each -b toggles the state of banner display.
-D
-D
The -D option tells &GAP; to print short messages when it is reading files or loading modules. This option may be repeated to toggle this behavior on and off. 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.

Obviously, this is a debugging option and most users will not need it.
-E
-E
If your &GAP; installation uses the readline library for command line editing (see ), this may be disabled by using -E option. This option may be repeated to toggle this behavior on and off. If your &GAP; installation does not use the readline library (you can check by IsBound(GAPInfo.UseReadline); if this is the case), this option will have no effect at all.
-e
-e
tells &GAP; not to quit when receiving a Ctrl-D on an empty input line (see ). This option should not be used when the input is a file or pipe. This option may be repeated to toggle this behavior on and off.
-f
-f
tells &GAP; to enable the line editing and history (see ).

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. This option does not toggle; you must use -n to disable line editing.
-g
-g
tells &GAP; to print a 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 kilobytes from a total allocated memory of 4096 kilobytes are available afterwards.
-g -g
-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 kilobytes from a total allocated memory of 4096 kilobytes are available afterwards.
-h
-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.
-i
-i
filename
changes the name of the init file from the default init.g to filename. (Usually not needed.)
-K
-K
memory
is like the -o option. 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
-L
filename
The option -L tells &GAP; to load a saved workspace. See section .
-l
-l
path_list
can be used to set or modify &GAP;'s list of root directories (see ). The default if no -l option is given is the current directory ./. This option can be used several times. Depending on the -r option a further user specific path is prepended to the list of root directories (the path in GAPInfo.UserGapRoot).

path_list should be a list of directories separated by semicolons. No whitespace is permitted before or after a semicolon. 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 seen in the variable GAPInfo.RootPaths, see .

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 explains how several root paths can be used to do this.

&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 its init.g file 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.
-M
-M
tells &GAP; not to check for, nor to use, compiled versions of library files. This option may be repeated to toggle this behavior on and off.
-m
-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 kilobytes, if the last character is m or M memory is taken as megabytes and if it is g or G it is taken as gigabytes.

This 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 memory than is physically available, it will spend most of the time paging.
-n
-n
tells &GAP; to disable the line editing and history (see ).

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;. This option does not toggle; you must use -f to enable line editing.
-O
-O
disables loading obsolete variables (see Chapter ). This option is used mainly for testing purposes, for example in order to make sure that a &GAP; package or one's own &GAP; code does not rely on the obsolete variables.
-o
-o
memory
tells &GAP; to allocate at most memory bytes without asking. The option argument memory is specified as with the -m option.

If more than this amount is required during the &GAP; session, &GAP; prints an error message and enters a break loop. In that case you can enter return; which implicitly doubles the amount given with this option.
-q
-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. This option may be repeated to disable quiet mode; each -q toggles quiet mode.
-R
-R
The option -R tells &GAP; not to load a saved workspace previously specified via the -L option. This option does not toggle.
-r
-r
The option -r tells &GAP; to ignore any user specific configuration files. In particular, the user specific root directory GAPInfo.UserGapRoot is not added to the &GAP; root directories and so gap.ini and gaprc files that may be contained in that directory are not read, see . Multiple -r options toggle this behaviour.
-s
-s
memory
With this option &GAP; does not use sbrk to get memory from the operating system. Instead it uses mmap, malloc or some other command for the amount given with this option to allocate space for the GASMAN memory manager. Usually &GAP; does not really use all of this memory, the options -m, -o, -K still work as documented. This feature assumes that the operating system only assigns physical memory to the &GAP; process when it is accessed, so that specifying a large amount of memory with -s should not cause any performance problem. The advantage of using this option is that &GAP; can work together with kernel modules which allocate a lot of memory with malloc.

The option argument memory is specified as with the -m option.
-T
-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;. This option may be repeated to toggle this behavior on and off.
-X
-X
tells &GAP; to do a consistency check of the library file and the corresponding compiled module when loading the compiled module. This option may be repeated to toggle this behavior on and off.
-x
-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 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 terminal application. 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
-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 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 terminal application. 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.
options
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 up to 14 filenames on the command line. If a file cannot be opened &GAP; will print an error message and will abort.

options
-C
-U
-P
-W
-z
-p
Additional options, -C, -U, -P, -W, -p and -z are used internally by the `gac` script (see ) and/or on specific operating systems.

The gap.ini and gaprc files

When you start &GAP;, it looks for files with the names gap.ini and gaprc in its root directories (see ), and reads the first gap.ini and the first gaprc file it finds. These files are used for certain initializations, as follows.

The file gap.ini is read early in the startup process. Therefore, the parameters set in this file can influence the startup process, such as which packages are automatically loaded (see ) and whether library files containing obsolete variables are read (see Chapter ). On the other hand, only calls to a restricted set of &GAP; functions are allowed in a gap.ini file. Usually, it should only contain calls of . This file can be generated (or updated when new releases introduce further user preferences) with the command . This file is read whenever &GAP; is started, with or without a workspace.

The file gaprc is read after the startup process, before the first input file given on the command line (see ). So the contents of this file cannot influence the startup process, but all &GAP; library functions can be called in this file. When &GAP; is started with a workspace then the file is read only if no gaprc file had been read before the workspace was created. (With this setup, it is on the one hand possible that administrators provide a &GAP; workspace for several users such that the user's gaprc file is read when &GAP; is started with the workspace, and on the other hand one can start &GAP;, read one's gaprc file, save a workspace, and then start from this workspace without reading one's gaprc file again.)

Note that by default, the user specific &GAP; root directory GAPInfo.UserGapRoot is the first &GAP; root directory. So you can put your gap.ini and gaprc files into this directory.

This mechanism substitutes the much less flexible reading of a users .gaprc file in versions of &GAP; up to 4.4. For compatibility this .gaprc file is still read if the directory GAPInfo.UserGapRoot does not exist, see how to migrate your old setup.

The gap.ini file
gap.ini

The file gap.ini is read after the declaration part of the &GAP; library is read, before the declaration parts of the packages needed and suggested by &GAP; are read, and before the implementation parts of &GAP; and of the packages are read.

The file gap.ini is expected to consist of calls to the function , see Section .

Since the file gap.ini is read before the implementation part of &GAP; is read, not all &GAP; functions may be called in the file. Assignments of numbers, lists, and records are admissible as well as calls to basic functions such as and .

Note that the file gap.ini is read also when &GAP; is started with a workspace.

The gaprc file

If a file gaprc is found it is read after &GAP;'s init.g, but before any of the files mentioned on the command line are read. You can use this file for your private customizations. (Many users may be happy with using just user preferences in the gap.ini file (see above) for private customization.) 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;

Note that only one gaprc file is read when &GAP; is started. When a workspace is created in a &GAP; session after a gaprc file has been read then no more gaprc file will be read when &GAP; is started with this workspace.

Also note that the file must be called gaprc. If you use a Windows text editor, in particular if your default is not to show file suffixes, you might accidentally create a file gaprc.txt or gaprc.doc which GAP will not recognize.

<#Include Label="UserPreferences">

Saving and Loading a Workspace

&GAP; workspace files are binary files that contain the data of a &GAP; session. One can produce a workspace file with , and load it into a new &GAP; session using the -L command line option, see Section .

One purpose of workspace files is of course the possibility to save a snapshot image of the current &GAP; workspace in a file.

The recommended way to start &GAP; is to load an existing workspace file, because this reduces the startup time of &GAP; drastically. So if you have installed &GAP; yourself then you should think about creating a workspace file immediately after you have started &GAP;, and then using this workspace file later on, whenever you start &GAP;. If your &GAP; installation is shared between several users, the system administrator should think about providing such a workspace file.

save
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 was called.

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

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.
Testing for the System Architecture
<#Include Label="ARCH_IS_UNIX"> <#Include Label="ARCH_IS_MAC_OS_X"> <#Include Label="ARCH_IS_WINDOWS">

Global Values that Control the &GAP; Session
Several global values control the &GAP; session, such as the command line, the architecture, or the information about available and loaded packages. Many of these values are accessible as components of the global record . Typically, these components are set and read in low level &GAP; functions, so changing the values of existing components of by hand is not recommended.

Important components are documented via index entries, try the input ??GAPInfo for getting an overview of these components.
Coloring the Prompt and Input

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

<#Include Label="ColorPrompt">