<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %W  run.xml                 GAP documentation                Frank Celler -->
<!-- %W                                                     & Martin Schönert -->
<!-- %W                                                     & Alexander Hulpke -->
<!-- %W                                                    & Burkhard Höfling -->
<!-- %% -->
<!-- %% -->
<!-- %Y  Copyright 1997,  Lehrstuhl D für Mathematik,  RWTH Aachen,   Germany -->
<!-- %% -->
<!-- %%  This file contains the  description of the installation procedure and -->
<!-- %%  command line options for various operating systems. -->
<!-- %% -->

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Chapter Label="Running GAP">
<Heading>Running GAP</Heading>

<Index>options</Index>
This chapter contains information about the command line options for &GAP;
(see&nbsp;<Ref Sect="Command Line Options"/>),
about some files in user specific &GAP; root  directory
(see&nbsp;<Ref Sect="sect:gap.ini"/>)
and about saving and loading a &GAP; workspace
(see&nbsp;<Ref Sect="Saving and Loading a Workspace"/>).


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Command Line Options">
<Heading>Command Line Options</Heading>

<Index Subkey="under UNIX">features</Index>
<Index Subkey="features">UNIX</Index>
<Index Subkey="under UNIX">options</Index>
<Index Subkey="options">UNIX</Index>
<Index Key="GAPInfo.CommandLineOptions">
<C>GAPInfo.CommandLineOptions</C></Index>

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 <C>-</C>, followed by a  single letter.
Options must not be grouped, e.g., <C>gap -gq</C> is invalid,
use <C>gap -g -q</C> instead.
Some options require an argument, this must follow the option
and  must be separated by whitespace, e.g.,  <C>gap -m 256m</C>,
it is not correct to say <C>gap -m256m</C> instead.
Certain boolean options (<C>-b</C>, <C>-q</C>, <C>-e</C>, <C>-r</C>,
<C>-A</C>, <C>-D</C>, <C>-M</C>, <C>-T</C>, <C>-X</C>, <C>-Y</C>)
toggle the current value so that <C>gap -b -b</C> is equivalent to <C>gap</C>
and to <C>gap -b -q -b -q</C> etc.
<P/>
&GAP; for UNIX will distinguish between upper and lower case options.
<P/>
As described in the &GAP; installation instructions (see the
<F>INSTALL.md</F> file in the &GAP; root directory),
usually you will not execute &GAP; directly. Instead  you  will
call a (shell) script, with the name <C>gap</C>, 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.
<P/>
During a &GAP; session, one can find the current values of command line options
in the record <C>GAPInfo.CommandLineOptions</C> (see <Ref Var="GAPInfo"/>),
whose component names are the command line options
(without the leading <C>-</C>).
<P/>
<List>

<Mark><Index Key="-A"><C>-A</C></Index>
<C>-A</C></Mark>
<Item>
By default, some needed and suggested &GAP; packages
(see <Ref Chap="Using and Developing GAP Packages"/>) 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.
</Item>
<Mark><Index Key="-b"><C>-b</C></Index>
<C>-b</C></Mark>
<Item>
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 <C>-b</C>
toggles the state of banner display.
</Item>
<Mark><Index Key="-c"><C>-c</C></Index>
<C>-c </C><A>gapcode</A></Mark>
<Item>
tells &GAP; to execute the given &GAP; code as if it was entered into
a temporary file which then is processed together with the other files
given to GAP (see the explanation at the end of this list for further
details on how filenames are processed).
</Item>
<Mark><Index Key="-D"><C>-D</C></Index>
<C>-D</C></Mark>
<Item>
The <C>-D</C> 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,
<P/>
<Log><![CDATA[
#I  READ_GAP_ROOT: loading 'lib/kernel.g' as GAP file
]]></Log>
<P/>
tells   you  that   &GAP;  has  started    to  read the   library   file
<F>lib/kernel.g</F>.
<P/>
<Log><![CDATA[
#I  READ_GAP_ROOT: loading 'lib/kernel.g' statically
]]></Log>
<P/>
tells you that &GAP; has used the compiled version of the  library  file
<F>lib/kernel.g</F>. This compiled module was statically linked to the  &GAP;
kernel at the time the kernel was created.
<P/>
<Log><![CDATA[
#I  READ_GAP_ROOT: loading 'lib/kernel.g' dynamically
]]></Log>
<P/>
tells you that &GAP; has loaded the compiled version of the library file
<F>lib/kernel.g</F>. This compiled module was dynamically loaded to the &GAP;
kernel at runtime from a corresponding <C>.so</C> file.
<P/>
Obviously, this is a debugging option and most users will not need it.
</Item>
<Mark><Index Key="-E"><C>-E</C></Index>
<C>-E</C></Mark>
<Item>
If your &GAP; installation uses the <C>readline</C> library for command line
editing (see <Ref Sect="sec:readline"/>), this may be disabled by using
<C>-E</C> option. This option may be repeated to toggle this behavior on and
off. If your &GAP; installation does not use the <C>readline</C> library
(you can check by <C>IsBound(GAPInfo.UseReadline);</C> if this is the case),
this option will have no effect at all.
</Item>
<Mark><Index Key="-e"><C>-e</C></Index>
<C>-e</C></Mark>
<Item>
tells &GAP; not to quit when receiving a <B>Ctrl-D</B>
on an empty input line (see&nbsp;<Ref Subsect="quit"/>).
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.
</Item>
<Mark><Index Key="-f"><C>-f</C></Index>
<C>-f</C></Mark>
<Item>
tells &GAP; to enable the line editing and history
(see <Ref Sect="Line Editing"/>).
<P/>
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 <C>-f</C> in this case to enable line editing. This option does not
toggle; you must use <C>-n</C> to disable line editing.
</Item>
<Mark><Index Key="-g"><C>-g</C></Index>
<C>-g</C></Mark>
<Item>
tells &GAP; to print a message every  time  a  full  garbage
collection is performed.
(This is available only if the <C>GASMAN</C> garbage collector is used,
see <Ref Subsect="Garbage Collection"/>.)
<P/>
<Log><![CDATA[
#G  FULL 44580/2479kb live   57304/4392kb dead   734/4096kb free
]]></Log>
<P/>
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.
</Item>
<Mark><Index Key="-g -g"><C>-g -g</C></Index>
<C>-g -g</C></Mark>
<Item>
If you give the option <C>-g</C> twice, &GAP; prints  a  information  message
every time a  partial  or  full  garbage  collection  is  performed.
(This is available only if the <C>GASMAN</C> garbage collector is used,
see <Ref Subsect="Garbage Collection"/>.)
The message,
<P/>
<Log><![CDATA[
#G  PART 9405/961kb+live   7525/1324kb+dead   2541/4096kb free
]]></Log>
<P/>
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.
</Item>
<Mark><Index Key="-h"><C>-h</C></Index>
<C>-h</C></Mark>
<Item></Item>
<Mark><Index Key="--help"><C>--help</C></Index>
<C>--help</C></Mark>
<Item>
tells &GAP; to print a summary of all available options.
&GAP; exits after printing the summary, all options coming
after are ignored.
</Item>
<Mark><Index Key="-K"><C>-K</C></Index>
<C>-K </C><A>memory</A></Mark>
<Item></Item>
<Mark><Index Key="--limitworkspace"><C>--limitworkspace</C></Index>
<C>--limitworkspace </C><A>memory</A></Mark>
<Item>
is like the <C>-o</C> option.
But while the latter actually allocates more memory if the system allows it
and then prints a warning inside a break loop the <C>-K</C>
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.
</Item>
<Mark><Index Key="-L"><C>-L</C></Index>
<C>-L </C><A>filename</A></Mark>
<Item>
The option <C>-L</C> tells &GAP; to load a saved workspace. See
section&nbsp;<Ref Sect="Saving and Loading a Workspace"/>.
(This is available only if the <C>GASMAN</C> garbage collector is used,
see <Ref Subsect="Garbage Collection"/>.)
</Item>
<Mark><Index Key="-l"><C>-l</C></Index>
<C>-l </C><A>path_list</A></Mark>
<Item></Item>
<Mark><Index Key="--roots"><C>--roots</C></Index>
<C>--roots </C><A>path_list</A></Mark>
<Item>
can be used to set or modify &GAP;'s list of root directories
(see <Ref Sect="GAP Root Directories"/>).
The default if no <C>-l </C> option is given is the current directory
<F>./</F>. This option can be used several times. Depending on the
<C>-r</C> option a further user specific path is prepended to the
list of root directories (the path in <C>GAPInfo.UserGapRoot</C>).
<P/>
<A>path_list</A> should be a list of directories separated by  semicolons.
No whitespace is permitted before or after a semicolon.
If <A>path_list</A> does not start  or  end  with  a semicolon,
then <A>path_list</A> replaces the existing list of root directories.
If <A>path_list</A> starts with a semicolon, then <A>path_list</A>  is
appended to the existing list of root directories.  If  <A>path_list</A>  ends
with a semicolon and does not start with one, then the new list of root
directories is the concatenation of <A>path_list</A> 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 <C>GAPInfo.RootPaths</C>,
see <Ref Var="GAPInfo"/>.
<P/>
Usually this option is used inside a startup script to specify
where &GAP; is installed on the system.
The <C>-l</C> 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 <Ref Sect="GAP Root Directories"/>  explains  how  several
root paths can be used to do this.
<P/>
&GAP; will attempt to read the file <A>root_dir</A><F>/lib/init.g</F> during
startup where <A>root_dir</A> is one of the directories in its  list  of  root
directories.
If &GAP; cannot find its <F>init.g</F> file it will print the following
warning.
<P/>
<Log><![CDATA[
gap: hmm, I cannot find 'lib/init.g' maybe use option '-l <gaproot>'?
]]></Log>
<P/>
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 <C>-l</C> option.
</Item>
<Mark><Index Key="--packagedirs"><C>--packagedirs</C></Index>
<C>--packagedirs </C><A>path_list</A></Mark>
<Item>
can be used to add paths to &GAP;'s list of package directories
(see <Ref Sect="GAP Package Directories"/>).
The list always contains all subdirectories <F>pkg</F> in a &GAP; root directory.
<P/>
<A>path_list</A> should be a list of directories separated by semicolons.
No whitespace is permitted before or after a semicolon, and the first and
last character of <A>path_list</A> may not be a semicolon.
After &GAP; has completed its startup procedure and
displays the prompt, the list of package directories can be seen in the
variable <C>GAPInfo.PackageDirectories</C>,
see <Ref Var="GAPInfo"/>.
<P/>
Usually this option is used inside a startup script to specify
where additional &GAP; packages are located on the system.
The <C>--packagedirs</C> option can also be used by individual users to tell &GAP;
about additional &GAP; packages, without the need to set up a complete root
directory structure.
</Item>
<Mark><Index Key="-M"><C>-M</C></Index>
<C>-M</C></Mark>
<Item>
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.
</Item>
<Mark><Index Key="-m"><C>-m</C></Index>
<C>-m </C><A>memory</A></Mark>
<Item></Item>
<Mark><Index Key="--minworkspace"><C>--minworkspace</C></Index>
<C>--minworkspace </C><A>memory</A></Mark>
<Item>
tells &GAP; to allocate <A>memory</A> bytes at startup time.
If the last character of <A>memory</A> is <C>k</C> or <C>K</C>
it is taken as kilobytes,
if the last character is <C>m</C> or <C>M</C> <A>memory</A>
is taken as megabytes
and if it is <C>g</C> or <C>G</C> it is taken as gigabytes.
<P/>
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.
</Item>
<Mark><Index Key="-n"><C>-n</C></Index>
<C>-n</C></Mark>
<Item>
tells &GAP; to disable the line editing and history
(see <Ref Sect="Line Editing"/>).
<P/>
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, <C>-n</C> 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 <C>-f</C> to enable line editing.
</Item>
<Mark><Index Key="-O"><C>-O</C></Index>
<C>-O</C></Mark>
<Item>
disables loading obsolete variables (see
Chapter <Ref Label="Replaced and Removed Command Names"/>). 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.
</Item>
<Mark><Index Key="-o"><C>-o</C></Index>
<C>-o </C><A>memory</A></Mark>
<Item></Item>
<Mark><Index Key="--maxworkspace"><C>--maxworkspace</C></Index>
<C>--maxworkspace </C><A>memory</A></Mark>
<Item>
tells &GAP; to allocate at most <A>memory</A> bytes without asking.
The option argument <A>memory</A> is specified as with the <C>-m</C>
option.
<P/>
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 <C>return;</C> which implicitly doubles the amount given with this
option.
</Item>
<Mark><Index Key="-q"><C>-q</C></Index>
<C>-q</C></Mark>
<Item>
tells &GAP; to be quiet. This means that  &GAP;  displays  neither  the
banner nor the prompt <C>gap></C>. 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 <C>-q</C> toggles quiet mode.
</Item>
<Mark><Index Key="-R"><C>-R</C></Index>
<C>-R</C></Mark>
<Item>
The option <C>-R</C> tells &GAP; not to load a saved workspace previously
specified via the <C>-L</C> option. This option does not toggle.
</Item>
<Mark><Index Key="-r"><C>-r</C></Index>
<C>-r</C></Mark>
<Item>
The option <C>-r</C> tells &GAP; to ignore any user specific configuration
files. In particular, the user specific root directory
<C>GAPInfo.UserGapRoot</C> is not added to the &GAP; root directories and
so <F>gap.ini</F> and <F>gaprc</F> files  that may be contained in that
directory are not read, see <Ref Sect="sect:gap.ini"/>.
Multiple <C>-r</C> options toggle this behaviour.
</Item>
<Mark><Index Key="-s"><C>-s</C></Index>
<C>-s </C><A>memory</A></Mark>
<Item>
With this option &GAP; does not use <C>sbrk</C> to get memory from the
operating system. Instead it uses <C>mmap</C>, <C>malloc</C> or some other
command for the amount given
with this option to allocate
space for the <C>GASMAN</C> memory manager.
Usually &GAP; does not really use all of this memory, the options
<C>-m</C>, <C>-o</C>, <C>-K</C> 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 <C>-s</C> 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 <C>malloc</C>.
<P/>
The option argument <A>memory</A> is specified as with the <C>-m</C>
option.
</Item>
<Mark><Index Key="-T"><C>-T</C></Index>
<C>-T</C></Mark>
<Item>
suppresses the usual break loop behaviour of  &GAP;.  With  this  option
&GAP; behaves as if the user <K>quit</K> immediately from every  break  loop,
and also suppresses displaying any error backtrace.
This is intended for automated testing of &GAP;. This option may be
repeated to toggle this behavior on and off.
</Item>
<Mark><Index Key="--version"><C>--version</C></Index>
<C>--version</C></Mark>
<Item>
tells &GAP; to print its version and then exit immediately,
all options coming after are ignored.
</Item>
<Mark><Index Key="-x"><C>-x</C></Index>
<C>-x </C><A>length</A></Mark>
<Item></Item>
<Mark><Index Key="--width"><C>--width</C></Index>
<C>--width </C><A>length</A></Mark>
<Item>
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 <Ref Func="SizeScreen"/> to alter the line length.
<P/>
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.
</Item>
<Mark><Index Key="-y"><C>-y</C></Index>
<C>-y </C><A>length</A></Mark>
<Item></Item>
<Mark><Index Key="--line"><C>--line</C></Index>
<C>--line </C><A>length</A></Mark>
<Item>
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
<Ref Func="SizeScreen"/> to alter the number of lines.
<P/>
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.
</Item>
<Mark><Index Subkey="command line, filenames">options</Index>
<A>filename</A> ...</Mark>
<Item>
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. Filenames ending with <C>.tst</C>
are processed by <Ref Func="Test" />, all other files by <Ref Oper="Read" />.
These files and also commands specified via the <C>-c</C> option are processed
in the order in which they appear on the command line.
If a file cannot be opened or if executing the code in it raises an error,
then the usual error handling for <Ref Oper="Read" /> respectively
<Ref Func="Test" /> kicks in. If this enters a break loop, then exiting that
break loop also exits &GAP;.
</Item>
</List>
<P/>
<Index Subkey="command line, internal">options</Index>
<Index Key="-C"><C>-C</C></Index>
<Index Key="-P"><C>-P</C></Index><Index Key="-p"><C>-p</C></Index>
Additional options, such as <C>-C</C>, <C>-P</C> and<C>-p</C> are used
internally by the <Package>gac</Package> script (see <Ref Label="Kernel modules"/>)
and/or on specific operating systems.


</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:gap.ini">
<Heading>The gap.ini and gaprc files</Heading>

When you start &GAP;,
it looks for files with the names <F>gap.ini</F> and <F>gaprc</F>
in its root directories (see <Ref Sect="GAP Root Directories"/>),
and reads the first <F>gap.ini</F> and the first <F>gaprc</F> file it finds.
These files are used for certain initializations, as follows.
<P/>
The file <F>gap.ini</F> 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 <Ref Func="LoadPackage"/>)
and whether library files containing obsolete variables are read
(see Chapter <Ref Chap="Replaced and Removed Command Names"/>).
On the other hand, only calls to a restricted set of &GAP; functions are
allowed in a <F>gap.ini</F> file. Usually, it should only contain calls
of <Ref Func="SetUserPreference"/>. This file can be generated (or updated
when new releases introduce further user preferences) with the command
<Ref Func="WriteGapIniFile"/>.
This file is read whenever &GAP; is started, with or without a workspace.
<P/>
The file <F>gaprc</F> is read after the startup process,
before the first input file given on the command line
(see <Ref Sect="Command Line Options"/>).
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
<F>gaprc</F> 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 <F>gaprc</F> file
is read when &GAP; is started with the workspace,
and on the other hand one can start &GAP;, read one's <F>gaprc</F> file,
save a workspace, and then start from this workspace <E>without</E>
reading one's <F>gaprc</F> file again.)
<P/>
Note that by default, the user specific &GAP; root directory
<C>GAPInfo.UserGapRoot</C>
is the first &GAP; root directory.
So you can put your <F>gap.ini</F> and <F>gaprc</F> files into this directory.
<P/>
This mechanism substitutes the much less flexible reading of a users
<F>.gaprc</F> file in versions of &GAP; up to 4.4.
For compatibility this <F>.gaprc</F> file is still read if the directory
<C>GAPInfo.UserGapRoot</C> does not exist, see <Ref Sect="obsolete-gaprc"/>
how to migrate your old setup.

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="subsect:gap.ini file">
<Heading>The gap.ini file</Heading>

<Index Key="gap.ini"><F>gap.ini</F></Index>

The file <F>gap.ini</F> 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.
<P/>
The file <F>gap.ini</F> is expected to consist of calls to the function
<Ref Func="SetUserPreference"/>,
see Section&nbsp;<Ref Func="SetUserPreference"/>.
<P/>

Since the file <F>gap.ini</F> 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
<Ref Func="Concatenation" Label="for several lists"/> and
<Ref Func="JoinStringsWithSeparator"/>.
<P/>
Note that the file <F>gap.ini</F> is read also when &GAP; is started
with a workspace.

</Subsection>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="subsect:gaprc file">
<Heading>The gaprc file</Heading>

If a file <F>gaprc</F> is found it is read after &GAP;'s <F>init.g</F>,
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
<F>gap.ini</F> 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 <F>gaprc</F>.
Or if you find some of the names in the library too long,
you could define abbreviations for those names in <F>gaprc</F>.
The following sample <F>gaprc</F> file does both.
<P/>
<Log><![CDATA[
Read( "/usr/you/dat/mygroups.grp" );
Ac := Action;
AcHom := ActionHomomorphism;
RepAc := RepresentativeAction;
]]></Log>
<P/>
Note that only one <F>gaprc</F> file is read when &GAP; is started.
When a workspace is created in a &GAP; session after a <F>gaprc</F> file
has been read then no more <F>gaprc</F> file will be read when &GAP;
is started with this workspace.
<P/>
Also note that the file must be called <F>gaprc</F>.
If you use a Windows text editor,
in particular if your default is not to show file suffixes,
you might accidentally create a file <F>gaprc.txt</F> or <F>gaprc.doc</F>
which GAP will not recognize.

</Subsection>

<#Include Label="UserPreferences">

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="subsect:User Preferences Defined by GAP">
<Heading>User Preferences Defined by &GAP;</Heading>

Here is the list of those user preferences that are currently declared
via <Ref Func="DeclareUserPreference"/> for &GAP; itself.
The preferences that are declared for &GAP; packages belong to the
documentation of these packages.

<#Include SYSTEM "user_pref_list.xml">

</Subsection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Saving and Loading a Workspace">
<Heading>Saving and Loading a Workspace</Heading>

&GAP; workspace files are binary files that contain the data of a &GAP;
session.
Currently saving and loading workspace files are supported only when the
<C>GASMAN</C> garbage collector is used,
see Section <Ref Subsect="Garbage Collection"/>.
<P/>
One can produce a workspace file with <Ref Func="SaveWorkspace"/>,
and load it into a new &GAP; session using the <C>-L</C> command line option,
see Section <Ref Sect="Command Line Options"/>.
<P/>
One purpose of workspace files is of course the possibility
to save a <Q>snapshot</Q> image of the current &GAP; workspace in a file.
<P/>
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.

<ManSection>
<Func Name="SaveWorkspace" Arg='filename'/>

<Description>
<Index>save</Index>
will save a <Q>snapshot</Q> image of the current &GAP; workspace in the file
<A>filename</A>. This image then can be loaded by another copy of &GAP; which
then will behave as at the point when <Ref Func="SaveWorkspace"/> was called.
<P/>
<Log><![CDATA[
gap> a:=1;
gap> SaveWorkspace("savefile");
true
gap> quit;
]]></Log>
<P/>
<Ref Func="SaveWorkspace"/> can only be used at the main <C>gap></C> prompt.
It cannot be included in the body of a loop or function,
or called from a break loop.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Testing for the System Architecture">
<Heading>Testing for the System Architecture</Heading>

<#Include Label="ARCH_IS_UNIX">
<#Include Label="ARCH_IS_MAC_OS_X">
<#Include Label="ARCH_IS_WINDOWS">
<#Include Label="ARCH_IS_WSL">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="GAPInfo_sect">
<Heading>Global Values that Control the &GAP; Session</Heading>

<ManSection>
<Var Name="GAPInfo"/>

<Description>
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
<Ref Var="GAPInfo"/>.
Typically, these components are set and read in low level &GAP; functions,
so changing the values of existing components of <Ref Var="GAPInfo"/>
<Q>by hand</Q> is not recommended.
<P/>
Important components are documented via index entries,
try the input <C>??GAPInfo</C> for getting an overview of these components.
</Description>
</ManSection>

<!-- further components:
GAPInfo.Architecture (has an index entry)
GAPInfo.AtExitFuncs
GAPInfo.BytesPerVariable
GAPInfo.CommandLineEditFunctions
GAPInfo.CommandLineOptions (has an index entry)
GAPInfo.CommandLineOptionData
GAPInfo.Date
GAPInfo.DeletePrompts
GAPInfo.DirectoriesLibrary
GAPInfo.DirectoriesPrograms
GAPInfo.DirectoriesSystemPrograms
GAPInfo.DirectoriesTemporary
GAPInfo.DirectoryCurrent
GAPInfo.HasReadGAPRC
GAPInfo.History
GAPInfo.InitFiles
GAPInfo.KernelVersion
GAPInfo.MaxNrArgsMethod
GAPInfo.PackageInfoCurrent
GAPInfo.PackageLoadingMessages
GAPInfo.PackagesInfo
GAPInfo.PackagesLoaded
GAPInfo.RootPaths (has an index entry)
GAPInfo.SystemCommandLine
GAPInfo.TestData
GAPInfo.UseReadline
GAPInfo.UserHome
GAPInfo.UserPreferences
GAPInfo.Version (has an index entry)
GAPInfo.gaprc
-->

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Coloring the Prompt and Input">
<Heading>Coloring the Prompt and Input</Heading>

&GAP; provides hooks for functions which are called when the prompt is
to be printed and when an input line is finished.
<P/>
An example of using this feature is the following function.

<#Include Label="ColorPrompt">

</Section>


</Chapter>