README.UNIX
         ( some additional tips and tricks by
           Frank Lübeck,  Frank.Luebeck@Math.RWTH-Aachen.De )

These remarks  are mainly  intended for UNIX  installations. Some  tips like
"Using a Saved  Workspace" or "Using Coloring of Prompts  and GAP Input" may
also work in a similar way on other systems.


===================================================
Almost automatic installation on Linux/UNIX systems
===================================================

On my system the script "inst_all.unix", appended at the bottom of this file
(and  contained  as separate  file  in  the ftp-distribution)  installs  GAP
completely including the packages which need compilation. Even if it doesn't
just run  through on your system,  you will at  least get an idea.  The most
critical part is usually the compilation of 'xgap' in the end, since on some
systems there are missing header or library files for the X11 environment.

Note that the installation of the CARAT  package can produce up to 180 MB of
data files (may vary between systems).

To use the script, copy gap4r3.tar.gz, accpkg4r3.tar.gz and deppkg4r3.tar.gz
to a  directory under which you  want to install GAP  (e.g., /usr/local/lib,
such that GAP's root directory becomes /usr/local/lib/gap4r3). Also copy the
script  to  that  directory,  give  it  executable  permission  ('chmod  755
inst_all.unix') and start it.  Alternatively try the separate lines with cut
and paste.

Note that  in the  'AtlasRep' package  'gap4r3/pkg/atlasrep', there  are two
directories 'datagens'  and 'dataword' which get  world writable permissions
(1777). These directories can grow a lot when the package is used much.

There are additional tables of marks available in archive xtom4r3.tar.gz, if
you want to install them, just  unpack above GAP's root directory, they need
additional 80 MB of disk space.

=======================
Using a Saved Workspace
=======================

GAP starts up much faster, when you use  a saved workspace. Here is how I do
this:

After installation start GAP as follows inside GAP's root directory:

mymachine> gap -r -N           # 'gap -h' explains the options

Then load  all packages you  are interested in,  enter a few  commands which
cause the loading of certain files and save the workspace, for example enter
the following commands:


######################################################
RequirePackage("EDIM");
RequirePackage("ace");
RequirePackage("anupq");
RequirePackage("aclib");
RequirePackage("atlasrep");
RequirePackage("cohomolo");
RequirePackage("format");
RequirePackage("fplsa");
RequirePackage("grape");
RequirePackage("grpconst");
RequirePackage("guava");
RequirePackage("kbmag");
RequirePackage("unipot");

# load help book infos
??blablfdfhskhks

# for nicer TAB completion
function() local a; for a in NamesGVars() do if ISB_GVAR(a) then
VAL_GVAR(a); fi;od;end;
last();

# save the workspace
SaveWorkspace("bin/wsgap4");
quit;
######################################################

Now generate a start script for GAP  which uses this workspace. Under UNIX a
command similar to the following will  do this (provided your standard start
script for GAP is called 'gap'):

/bin/echo -e '#\041/bin/sh\nif test -e $HOME/.gaprc; then G="$HOME/.gaprc"; else G=""; fi\ngap -L '`pwd`'/bin/wsgap4  $* $G '  > bin/gapL

chmod 755 bin/gapL

(Then copy this script to the same  directory as your 'gap'.) Note that with
-L ... the personal .gaprc file is no longer read, so we include its reading
in the command line above.

==============
Static Linking 
==============

On typical  Linux systems  the maximal  memory which  can be  used by  a GAP
process is  about 870 MB. In  times where PCs with  2 GB of main  memory are
affordable, this is a noticable limit.

I'm using  a statically  linked GAP which  allows to  use up to  2 GB  for a
single GAP process (on 32 bit systems).

On my  Linux system  I use  the following commands  to compile  a statically
linked GAP

mymachine> setenv COPTS '-Wall -O2 -g -fomit-frame-pointer -pipe -mpreferred-stack-boundary=2 -march=i686 -fno-strict-aliasing'
mymachine> setenv LOPTS "-static"
mymachine> ./configure
mymachine> make

(This is csh syntax, use "export  COPTS='...'" with sh/bash/zsh ...) You can
also  set CC  if you  want  to specify  another compiler.  Adjust the  COPTS
settings to your preferred optimization options.


=======================================
Using Coloring of Prompts and GAP Input
=======================================

I like the  possibility of GAP 4.3, to  show the prompt and input  text in a
different color. This is achieved by the following function (could be put in
a user's ~/.gaprc  file or create a  file in 'lib' which  everybody can read
with 'ReadLib'):

-----------------------------------------------
STDOUT := OutputTextUser();;
PrintPromptHook:=CPROMPT;;
EndLineHook:=function() end;;
ColorPrompt := function(b)
  if b=false then
    Unbind(PrintPromptHook);
    Unbind(EndLineHook);
    return;
  fi;
  # my colored interface
  # we stored this above to avoid overwriting last system error with 
  # function call
  ###  STDOUT := OutputTextUser();
  # print the prompt
  PrintPromptHook := function()
    local cp;
    cp := CPROMPT();
    if cp = "gap> " then
      cp := "gap> ";
    fi;
    # different color for brk...> prompts
    if Length(cp)>0 and cp[1] = 'b' then
      WriteAll(STDOUT, "\033[1m\033[31m");
    else
      WriteAll(STDOUT, "\033[1m\033[34m");
    fi;
    # use this instead of Print such that the column counter for the 
    # command line editor is correct
    PRINT_CPROMPT(cp);
    # another color for input
    WriteAll(STDOUT, "\033[0m\033[31m");
  end;
  # reset attributes before going to the next line
  EndLineHook := function()
    WriteAll(STDOUT, "\033[0m");
  end;
end;
Unbind(PrintPromptHook);
Unbind(EndLineHook);
-----------------------------------------------

After reading this one can switch on/off colored prompts with:
    'ColorPrompt(true);'     resp.     'ColorPrompt(false);'  

(You  must have  a  terminal  which interprets  ANSI  color sequences,  most
terminal emulations do.)

Apropos colors: I have a line 

ANSI_COLORS := true;

in my ~/.gaprc  file. This causes that  some help pages are  also shown with
color markup. (See '?GAPDoc: ANSI_COLORS' in the online help.)


----------  and here is  the script 'inst_all.unix'  -----------------------
#!/usr/bin/tcsh

# You need 'gzip', GNU 'tar', a C compiler, sed, pdftex to run this.
# And the files gap4r3.tar.gz, accpkg4r3.tar.gz, deppkg4r3.tar.gz.

# Frank Lübeck, Frank.Luebeck@Math.RWTH-Aachen.De for questions and complaints.

# Note, that this isn't and is not intended to be a sophisticated script.
# Even if it doesn't work completely automatically for you, you may get 
# an idea what to do for a complete installation of GAP.


setenv NAME "4r3"

# adjust settings as you like, the example is  for gcc under Linux ix86
# (use settings like "-v8a -fast" or "-v9a -fast" for 32bit or 64bit
# compilations with SUN's compilers under Solaris, and similar for other
# systems)
#setenv COPTS "-Wall -O2 -g -fomit-frame-pointer -pipe -mpreferred-stack-boundary=2 -march=i686 -fno-strict-aliasing"

# you can also set this to choose a C compiler
#setenv CC ...

# and you can fix extra linker options, e.g.,
#setenv LOPTS "-static"

tar xzvf gap$NAME.tar.gz
cd gap$NAME/pkg
tar xzvf ../../accpkg$NAME.tar.gz
tar xzvf ../../deppkg$NAME.tar.gz

cd ..

# compile GAP
./configure
make
unsetenv COPTS
unsetenv LOPTS
# we collect all start scripts in 'bin'
cp bin/`sed -e 's/GAParch=//' sysinfo.gap`/gac bin

# now the packages
cd pkg

cd ace
./configure ../..
make
cd ..

cd anupq
./configure ../..
# on Linux with gmp in standard place and with GAP 4.3 gap.sh script
# in standard path as: gap  just do: make  (otherwise check installation
# instructions - configure output gives hints)
make
cd ..

# You may not want a writable directory here! In this case substitute
# the directories 'datagens' and 'dataword' by links to somewhere else.
cd atlasrep
chmod 1777 datagens dataword
cd ..

# This produces a lot of data, maybe you want to leave this out until a user
# complains.
cd carat
tar xzf carat*.tar.gz
ln -s carat/bin bin
cd carat
mv Makefile Makefile.orig
echo 'TOPDIR = '`pwd` > Makefile
grep -v "^TOPDIR" Makefile.orig >> Makefile
make
cd ../..

cd cohomolo
./configure ../..
make
cd ..

# create dynamic library and statically linked GAP with EDIM kernel module
cd edim
unsetenv LANG
unsetenv LC_ALL
./configure
make
cd ../../bin/`sed -e 's/GAParch=//' ../../sysinfo.gap`
./gac -o gap-static -P "-static" -p "-DEDIVSTATIC " ../../pkg/edim/src/ediv.c
cd ../../pkg

cd example
./configure ../..
make
cd ..

cd fplsa
./configure ../..
make
cd doc
tex manual
tex manual
cd ../..

cd grape
./configure ../..
make linux-gcc
cd ..

cd guava
./configure ../..
make
cd ..

cd kbmag
./configure ../..
make
make texdoc
cd doc
pdftex manual
pdftex manual
cd ../..

cd openmath
./configure ../..
make
cd ..

#  see the pargap documentation how to use this 
#  (in particular, user needs procgroup file)
cd pargap
./configure ../..
make
cp bin/pargap.sh ../../bin/
cd ..

# For XGap the following shared libraries of the X window system must be 
# installed on your machine together with the development files (header 
# files and so on):
# 
#   libXaw.so, libXmu.so, libXt.so, libXext.so, libX11.so, libSM.so, libICE.so
# 
# In addition you need on XFree Version >= 4:
# 
#   libXpm.so
#
# If you  miss one of  these under Linux you  can usually just  install some
# more packages of your favorite distribution. The development files usually
# come in some package with "dev" in its name.
cd xgap
./configure
make
cp bin/xgap.sh ../../bin/
cd ..

cd ..

cp bin/gap.sh bin/gap

echo ""
echo "Copy scripts in 'gap4r3/bin' to a standard path, e.g., '/usr/local/bin'"
echo "You may also get xtom4r3.tar.gz and unpack it."
echo "Consider creating a workspace for faster startup."
echo "Maybe create a further script which calls 'bin/.../gap-static'."
echo "Have fun using GAP!"