[MathJax off]

3 Running GAP

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

3.1 Command Line Options

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 https://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 GAPInfo (3.5-1)), whose component names are the command line options (without the leading -).

-A

By default, some needed and suggested GAP packages (see 76) 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 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 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

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

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

If your GAP installation uses the readline library for command line editing (see 6.9), 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

tells GAP not to quit when receiving a Ctrl-D on an empty input line (see 6.4-1). 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

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

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

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

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

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 filename

changes the name of the init file from the default init.g to filename. (Usually not needed.)

-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 filename

The option -L tells GAP to load a saved workspace. See section 3.3.

-l path_list

can be used to set or modify GAP's list of root directories (see 9.2). 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 GAPInfo (3.5-1).

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 9.2 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

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

tells GAP to disable the line editing and history (see 6.8).

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

disables loading obsolete variables (see Chapter 77). 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 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

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

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

-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 3.2. Multiple -r options toggle this behaviour.

-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

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

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 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 (6.12-1) 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 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 (6.12-1) 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.

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.

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

3.2 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 9.2), 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 LoadPackage (76.2-1)) and whether library files containing obsolete variables are read (see Chapter 77). 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 SetUserPreference (3.2-3). This file can be generated (or updated when new releases introduce further user preferences) with the command WriteGapIniFile (3.2-3). 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 3.1). 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 77.5 how to migrate your old setup.

3.2-1 The gap.ini file

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 SetUserPreference (3.2-3), see Section SetUserPreference (3.2-3).

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 Concatenation (21.20-1) and JoinStringsWithSeparator (27.7-17).

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

3.2-2 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.

3.2-3 Configuring User preferences

Some aspects of the behaviour of GAP can be customized by the user via user preferences. Examples include the way help sections are displayed or the use of colors in the terminal.

User preferences are specified via a pair of strings, the first is the (case insensitive) name of a package (or "GAP" for the core GAP library) and the second is some arbitrary case sensitive string.

User preferences can be set to some value with SetUserPreference. The current value of a user preference can be found with UserPreference. In both cases, if no package name is given the default "GAP" is used. If a user preference is not known or not set then UserPreference returns fail.

The function ShowUserPreferences with no argument shows in a pager an overview of all known user preferences together with some explanation and the current value. If one or more strings package1, ... are given then only the user preferences for these packages are shown.

The easiest way to make use of user preferences is probably to use the function WriteGapIniFile, usually without argument. This function creates a file gap.ini in your user specific GAP root directory (GAPInfo.UserGapRoot). If such a file already exists the function will make a backup of it first. This newly created file contains descriptions of all known user preferences and also calls of SetUserPreference for those user preferences which currently do not have their default value. You can then edit that file to customize (further) the user preferences for future GAP sessions.

Should a later version of GAP or some packages introduce new user preferences then you can call WriteGapIniFile again since it will set the previously known user preferences to their current values.

Optionally, a different directory for the resulting gap.ini file can be specified as argument dir to WriteGapIniFile. Another optional argument is the boolean value true, if this is given, the settings of all user preferences in the current session are ignored.

Note that your gap.ini file is read by GAP very early during its startup process. A consequence is that the value argument in a call of SetUserPreference must be some very basic GAP object, usually a boolean, a number, a string or a list of those. A few user preferences support more complicated settings. For example, the user preference "UseColorPrompt" admits a record as its value whose components are available only after the GAPDoc package has been loaded, see ColorPrompt (3.6-1). If you want to specify such a complicated value, then move the corresponding call of SetUserPreference from your gap.ini file into your gaprc file (also in the directory GAPInfo.UserGapRoot). This file is read much later.

gap> SetUserPreference( "Pager", "less" );
gap> SetUserPreference("PagerOptions",
>                      [ "-f", "-r", "-a", "-i", "-M", "-j2" ] );
gap> UserPreference("Pager");
"less"

The first two lines of this example will cause GAP to use the programm less as a pager. This is highly recommended if less is available on your system. The last line displays the current setting.

3.2-4 DeclareUserPreference

This function can be used (also in packages) to introduce new user preferences. It declares a user preference, determines a default value and contains documentation of the user preference. After declaration a user preference will be shown with ShowUserPreferences (3.2-3) and WriteGapIniFile (3.2-3).

When this declaration is evaluated it is checked, if this user preference is already set in the current session. If not the value of the user preference is set to its default. (Do not use fail as default value since this indicated that a user preference is not set.)

The argument record of DeclareUserPreference must be a record with the following components.

name

a string or a list of strings, the latter meaning several preferences which belong together,

description

a list of strings describing the preference(s), one string for each paragraph; if several preferences are declared together then the description refers to all of them,

default

the default value that is used, or a function without arguments that computes this default value; if several preferences are declared together then the value of this component must be the list of default values for the individual preferences.

The following components of record are optional.

check

a function that takes a value as its argument and returns either true or false, depending on whether the given value is admissible for this preference; if several preferences are declared together then the number of arguments of the function must equal the length of the name list,

values

the list of admissible values, or a function without arguments that returns this list,

multi

true or false, depending on whether one may choose several values from the given list or just one; needed (and useful only) if the values component is present,

package

the name of the GAP package to which the preference is assigned; if the declaration happens inside a file that belongs to this package then the value of this component is computed, using GAPInfo.PackageCurrent; otherwise, the default value for package is "GAP",

omitFromGapIniFile

if the value is true then this user preference is ignored by WriteGapIniFile (3.2-3).

gap> UserPreference( "MyFavouritePrime" );
fail
gap> DeclareUserPreference( rec(
>        name:= "MyFavouritePrime",
>        description:= [ "is not used, serves as an example" ],
>        default:= 2,
>        omitFromGapIniFile:= true ) );
gap> UserPreference( "MyFavouritePrime" );
2
gap> SetUserPreference( "MyFavouritePrime", 17 );
gap> UserPreference( "MyFavouritePrime" );
17

3.3 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 SaveWorkspace (3.3-1), and load it into a new GAP session using the -L command line option, see Section 3.1.

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.

3.3-1 SaveWorkspace

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.

3.4 Testing for the System Architecture

3.4-1 ARCH_IS_UNIX

tests whether GAP is running on a UNIX system (including Mac OS X).

3.4-2 ARCH_IS_MAC_OS_X

tests whether GAP is running on Mac OS X. Note that on Mac OS X, also ARCH_IS_UNIX (3.4-1) will be true.

3.4-3 ARCH_IS_WINDOWS

tests whether GAP is running on a Windows system.

3.5 Global Values that Control the GAP Session

3.5-1 GAPInfo

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 GAPInfo. Typically, these components are set and read in low level GAP functions, so changing the values of existing components of GAPInfo "by hand" is not recommended.

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

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

3.6-1 ColorPrompt

With ColorPrompt(true); GAP changes its user interface: The prompts and the user input are displayed in different colors. Switch off the colored prompts with ColorPrompt(false);.

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 (xterm, rxvt, 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 a call of SetUserPreference("UseColorPrompt", true); in your gap.ini file. If you want a more complicated setting as explained below then put your SetUserPreference("UseColorPrompt", rec( ... ) ); call into your gaprc file.

The optional second argument optrec allows one to further customize the behaviour. It must be a record from which the following components are recognized:

MarkupStdPrompt

a string or no argument function returning a string containing the escape sequence used for the main prompt gap> .

MarkupContPrompt

a string or no argument function returning a string containing the escape sequence used for the continuation prompt > .

MarkupBrkPrompt

a string or no argument function returning a string containing the escape sequence used for the break prompt brk...> .

MarkupInput

a string or no argument function returning a string containing the escape sequence used for user input.

TextPrompt

a no argument function returning the string with the text of the prompt, but without any escape sequences. The current standard prompt is returned by CPROMPT(). But note that changing the standard prompts makes the automatic removal of prompts from input lines impossible (see 6.2).

PrePrompt

a function called before printing a prompt.

Here is an example.

LoadPackage("GAPDoc");
timeSHOWMIN := 100;
ColorPrompt(true, rec(
   # usually cyan bold, see ?TextAttr
   MarkupStdPrompt := Concatenation(TextAttr.bold, TextAttr.6),
   MarkupContPrompt := Concatenation(TextAttr.bold, TextAttr.6),
   PrePrompt := function()
     # show the 'time' automatically if at least timeSHOWMIN
     if CPROMPT() = "gap> " and time >= timeSHOWMIN then
       Print("Time of last command: ", time, " ms\n");
     fi;
   end)    );

generated by GAPDoc2HTML