<!-- 

  install.xml            FinInG package documentation
                                                                   John Bamberg                                                                   
                                                              and Philippe Cara
                                                               and Jan De Beule
                                                             and Michel Lavrauw
                                                                  and Maska Law
                                                            and Max Neunhoeffer
                                                             and Michael Pauley
                                                              and Sven Reichard

  Copyright 2008 University of Western Australia, Perth
                 Lehrstuhl D fuer Mathematik, RWTH Aachen
                 Ghent University
                 Colorado State University
                 Vrije Universiteit Brussel

This is the chapter of the documentation describing the installation.

-->

<Chapter Label="install">
<Heading>Installation of the <Package>FinInG</Package>-Package</Heading>
<Index><Package>FinInG</Package></Index>

This package requires the GAP packages <Package>GAPDoc</Package>, version 0.99 or higher,
<Package>Forms</Package>, version 1.2 or higher, <Package>Orb</Package>, version 2.0 or higher,
<Package>GenSS</Package>, version 0.9 or higher, and <Package>GRAPE</Package>, version 4.3 or higher.
Currently, one function will use the <Package>Design</Package> package, but this package is not required to
load <Package>FinInG</Package>. The package <Package>GenSS</Package> requires the package <Package>IO</Package>.

The packages required by <Package>FinInG</Package> are all part of the standard GAP distribution.

The recent development stage of <Package>FinInG</Package> is based on GAP4r5. We have done testing using GAP4r7, 
and no installation differences occured. In this section, we describe in detail the installation procedure   
for <Package>FinInG</Package>, assuming the use of GAP4r7. We have also (succesfully) tested this procedure with 
some older GAP releases but these required manual installation of <Package>GenSS</Package>,  <Package>IO</Package> 
and <Package>Orb</Package>. 

<Section>
<Heading>Installing <Package>FinInG</Package> under UNIX like systems</Heading>

The installation of <Package>FinInG</Package> itself is generic for each UNIX like system, including the different flavours of
MacOSX. You only need a terminal application, and you need acces to the standard unix tools gunzip and tar. The installation procedure
for <Package>FinInG</Package>, a standard GAP package, does <E>not</E> require compilation. Each GAP installation has a 
pkg directory, containing supplemental GAP packages. If you have acces to this filesystem, you can locate it, e.g. 
<Display>/usr/local/gap4r7/pkg/</Display>
Download the <Package>FinInG</Package> archive "fining-....tgz" to this location, and unpack the archive. This can be done by issuing
<Display>gunzip fining-....tar.gz</Display> 
which yields a file "fining-....tar", in the pkg directory, after which issuing the command 
<Display>tar -xf fining-....tar</Display>
unpacks the archive in a subdirectory fining.

After successfully unpacking the archive, you can locate the directory 
<Display>/usr/local/gap4r7/pkg/fining/.</Display> 
This directory contains a subdirectory "./doc", containing an html and pdf version of the manual. The html version is accessible by opening the file "chap0.html" in your favorite browser. 
The pdf version of the manual can be found in the file "manual.pdf".

Please notice that you can unpack your archive in your favorite local "./pkg" directory, e.g. "/home/yourself/pkg/", in case you are using
GAP on a server on which you have only a restricted access.

If you installed <Package>FinInG</Package> in the central GAP pkg directory, you can startup gap using the usual command. We suppose this is gap4r4. If
you installed <Package>FinInG</Package> in your local pkg directory, 
e.g. "/home/yourself/pkg/", then move to "/home/yourself", and issue 
the command 
<Display>gap -l "/usr/local/gap4r7;./"</Display> 
This will cause gap to startup and use as pkg directory both its own central pkg directory, i.e.
"/usr/local/gap4r7/pkg", as well as your local pkg directory, i.e. "/home/yourself/pkg/". You should see something like the following
output. Notice that the packages <Package>GAPDoc</Package> and <Package>IO</Package> are loaded by default. This is not 
necessarily the case, but loading fining will force to load required packages anyway. 

<Example>
 ┌───────┐   GAP, Version 4.7.5 of 24-May-2014 (free software, GPL)
 │  GAP  │   http://www.gap-system.org
 └───────┘   Architecture: x86_64-unknown-linux-gnu-gcc-default64
 Libs used:  gmp
 Loading the library and packages ...
 Components: trans 1.0, prim 2.1, small* 1.0, id* 1.0
 Packages:   AClib 1.2, Alnuth 3.0.0, AtlasRep 1.5.0, AutPGrp 1.6, 
             CRISP 1.3.8, Cryst 4.1.12, CrystCat 1.1.6, CTblLib 1.2.2, 
             FactInt 1.5.3, FGA 1.2.0, GAPDoc 1.5.1, IO 4.3.1, IRREDSOL 1.2.4, 
             LAGUNA 3.6.4, Polenta 1.3.2, Polycyclic 2.11, RadiRoot 2.7, 
             ResClasses 3.3.2, Sophus 1.23, SpinSym 1.5, TomLib 1.2.4
 Try '?help' for help. See also  '?copyright' and  '?authors'
gap>
</Example>
To load <Package>FinInG</Package>, issue 
<Display>
LoadPackage("fining");
</Display>
If this fails, in most cases, the reason is that either GAP does not 
find the directory in which <Package>FinInG</Package> is installed, or one of the required packages for <Package>FinInG</Package> is not installed. The easiest way to find out
is to load each required package before issuing the LoadPackage command to load <Package>FinInG</Package>. The example below shows this situation, the packages
<Package>Forms</Package> and <Package>FinInG</Package> itself are installed in a local pkg directory, the other packages are installed
centrally. Starting up gap not pointing to the local pkg directory, causes the locally installed packages to be unloadable.
<Example>
gap> LoadPackage("fining");
fail
gap> LoadPackage("forms");
fail
gap> LoadPackage("grape");

Loading  GRAPE 4.3  (GRaph Algorithms using PErmutation groups),
by L.H.Soicher@qmul.ac.uk.

true
gap> LoadPackage("orb");
-----------------------------------------------------------------------------
Loading  orb 3.8 (orb - Methods to enumerate orbits)
by Juergen Mueller (http://www.math.rwth-aachen.de/~Juergen.Mueller),
   Max Neunhoeffer (http://www-groups.mcs.st-and.ac.uk/~neunhoef), and
   Felix Noeske (http://www.math.rwth-aachen.de/~Felix.Noeske).
-----------------------------------------------------------------------------
true
gap> LoadPackage("genss");
-----------------------------------------------------------------------------
Loading  genss 1.3 (genss - generic Schreier-Sims)
by Max Neunhoeffer (http://www-groups.mcs.st-and.ac.uk/~neunhoef) and
   Felix Noeske (http://www.math.rwth-aachen.de/~Felix.Noeske).
-----------------------------------------------------------------------------
true
</Example>
If the installation was successful, then, the following output should be visible.
<Example>
gap> LoadPackage("fining");
---------------------------------------------------------------------
Loading 'Forms' 1.2.2 (29/08/2011)
by John Bamberg (http://school.maths.uwa.edu.au/~bamberg/)
   Jan De Beule (http://cage.ugent.be/~jdebeule)
For help, type: ?Forms 
---------------------------------------------------------------------
─────────────────────────────────────────────────────────────────────────────
Loading  orb 4.7.1 (Methods to enumerate orbits)
by Juergen Mueller (http://www.math.rwth-aachen.de/~Juergen.Mueller),
   Max Neunhoeffer (http://www-groups.mcs.st-and.ac.uk/~neunhoef), and
   Felix Noeske (http://www.math.rwth-aachen.de/~Felix.Noeske).
Homepage: http://neunhoef.github.io/orb/
─────────────────────────────────────────────────────────────────────────────
─────────────────────────────────────────────────────────────────────────────
Loading  genss 1.6.1 (Generic Schreier-Sims)
by Max Neunhoeffer (http://www-groups.mcs.st-and.ac.uk/~neunhoef) and
   Felix Noeske (http://www.math.rwth-aachen.de/~Felix.Noeske).
Homepage: http://neunhoef.github.io/genss/
─────────────────────────────────────────────────────────────────────────────
─────────────────────────────────────────────────────────────────────────────
Loading  GRAPE 4.6.1 (GRaph Algorithms using PErmutation groups)
by Leonard H. Soicher (http://www.maths.qmul.ac.uk/~leonard/).
Homepage: http://www.maths.qmul.ac.uk/~leonard/grape/
─────────────────────────────────────────────────────────────────────────────
patching: forms loading: geometry, liegeometry, group, projectivespace, 
correlations, polarspace/morphisms, enumerators, diagram, varieties, 
affinespace/affinegroup, gpolygons, stabilisers
---------------------------------------------------------------------
      ______________       ________      _________   _____________   
      ___  ____/__(_)__________  _/________  ____/   __&lt;  /__  __   
      __  /_   __  /__  __ __  / __  __   / __     __  / _  / / /  
      _  __/   _  / _  / / /_/ /  _  / / / /_/ /     _  /__/ /_/ /   
      /_/      /_/  /_/ /_//___/  /_/ /_/____/      /_/_(_)____/    
---------------------------------------------------------------------
Loading  FinInG 1.0 (Finite Incidence Geometry) 
by John Bamberg (http://school.maths.uwa.edu.au/~bamberg/)
   Anton Betten (http://www.math.colostate.edu/~betten)
   Jan De Beule (http://cage.ugent.be/~jdebeule)
   Philippe Cara (http://homepages.vub.ac.be/~pcara)
   Michel Lavrauw (http://cage.ugent.be/~ml)
   Max Neunhoeffer (http://www-groups.mcs.st-and.ac.uk/~neunhoef/)
For help, type: ?FinInG 
---------------------------------------------------------------------
true
gap> 
</Example>
For the sake of completeness, we show the output under GAP4r5
<Example>
 *********   GAP, Version 4.5.2(beta) of 27-Nov-2011 (free software, GPL)
 *  GAP  *   http://www.gap-system.org
 *********   Architecture: x86_64-apple-darwin10.8.0-gcc-default64
 Libs used:  gmp
 Loading the library and packages ...
 Components: trans 1.0, prim 2.1, small* 1.0, id* 1.0
 Packages:   GAPDoc 1.4, IO 3.3, TomLib 1.2.2
 Try '?help' for help. See also  '?copyright' and  '?authors'
gap> LoadPackage("fining"); 
---------------------------------------------------------------------
Loading 'Forms' 1.2.3 (29/08/2011)
by John Bamberg (http://school.maths.uwa.edu.au/~bamberg/)
   Jan De Beule (http://cage.ugent.be/~jdebeule)
For help, type: ?Forms 
---------------------------------------------------------------------
---------------------------------------------------------------------------------------------
Loading  orb 3.8 (orb - Methods to enumerate orbits)
by Juergen Mueller (http://www.math.rwth-aachen.de/~Juergen.Mueller),
   Max Neunhoeffer (http://www-groups.mcs.st-and.ac.uk/~neunhoef), and
   Felix Noeske (http://www.math.rwth-aachen.de/~Felix.Noeske).
Homepage: http://www-groups.mcs.st-and.ac.uk/~neunhoef/Computer/Software/Gap/orb.html
---------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------
Loading  genss 1.3 (genss - generic Schreier-Sims)
by Max Neunhoeffer (http://www-groups.mcs.st-and.ac.uk/~neunhoef) and
   Felix Noeske (http://www.math.rwth-aachen.de/~Felix.Noeske).
Homepage: http://www-groups.mcs.st-and.ac.uk/~neunhoef/Computer/Software/Gap/genss.html
---------------------------------------------------------------------------------------------

Loading  GRAPE 4.3  (GRaph Algorithms using PErmutation groups),
by L.H.Soicher@qmul.ac.uk.

loading: geometry, liegeometry, group, projectivespace, correlations, polarspace/morphis
ms, enumerators, diagram, varieties, affinespace/affinegroup, gpolygons
---------------------------------------------------------------------
      ______________       ________      _________   _____________   
      ___  ____/__(_)__________  _/________  ____/   __&lt;  /__  __   
      __  /_   __  /__  __ __  / __  __   / __     __  / _  / / /  
      _  __/   _  / _  / / /_/ /  _  / / / /_/ /     _  /__/ /_/ /   
      /_/      /_/  /_/ /_//___/  /_/ /_/____/      /_/_(_)____/    
---------------------------------------------------------------------
Loading  FinInG 1.0 (Finite Incidence Geometry) 
by John Bamberg (http://cage.ugent.be/~bamberg)
   Anton Betten (http://www.math.colostate.edu/~betten)
   Jan De Beule (http://cage.ugent.be/~jdebeule)
   Philippe Cara (http://homepages.vub.ac.be/~pcara)
   Michel Lavrauw (http://cage.ugent.be/~ml)
   Max Neunhoeffer (http://www.math.rwth-aachen.de/~Max.Neunhoeffer)
For help, type: ?FinInG 
---------------------------------------------------------------------
true
gap> 
</Example>
</Section>

<Section>
<Heading>Installing other required packages</Heading>

The packages <Package>orb</Package> and <Package>IO</Package> require compilation and the linking of 
some binaries to the gap kernel. On some UNIX like system, dynamical linking seems to be impossible. In 
such a case, the binaries must be statically linked to the GAP kernel. We describe the procedure here, assuming that
we have to link the binaries of both packages to the gap-kernel. We assume that gap is installed in the directory 
<Display>/usr/local/gap4r4/</Display> 
and that we use the central ./pkg/ directory for the packages <Package>IO</Package> and
<Package>orb</Package>
<Table Align="l">
<Row><Item>1. Move to your gap directory, which is in this example /usr/loca/gap4r4/. Move further to the /bin directory, and locate 
a directory that is named accordingly to your system architecure. You can derive its name from the startyp banner of GAP. Here
we use that example of the banner above, which is 'i686-apple-darwin10.8.0-gcc'</Item></Row>
<Row><Item>2. We are in the directory '/usr/loca/gap4r4/bin/i686-apple-darwin10.8.0-gcc/'. Locate the file 'gac'. This is a shell script
that will allow you to compile extra libraries, and to link them statically to the GAP kernel. Recall that we want to compile and link 
orb and IO to the kernel.</Item></Row>
<Row><Item>3. Recall that the pkg directoy is now '/usr/local/gap4r4/pkg/'. So the source files of orb and io are to be found
in '/usr/local/gap4r4/pkg/orb' and '/usr/local/gap4r4/pkg/io', after the execution of the normal installation procedure</Item></Row>
<Row><Item>4. Issue the command './gac gap-static -p "-DIOSTATIC -I/usr/local/gap4r4/pkg/io/bin/i686-apple-darwin10.8.0-gcc -DORBSTATIC" 
/usr/local/gap4r4/pkg/io/src/io.c /usr/local/gap4r4/pkg/io/src/orb.c'. This will link the binaries to the GAP kernel, and 
produce a new GAP executable called 'gap-static'.</Item></Row>
<Row><Item>5. Adapt the shell script to start GAP. In this example, we assumed GAP is started up using 'gap'. Locate this shell script,
use 'which gap', which should output something like
<Display>'/usr/bin/gap'</Display>
Adapt this file, find the line containing the pointer to the GAP binary, and replace this by a pointer to the 'gap-static' binary:
<Display>if [ "x$GAP_PRG" = "x" ];  then
GAP_PRG=i686-apple-darwin10.8.0-gcc/gap-static
fi
</Display>
</Item></Row>

</Table>

</Section>

<!-- ############################################################ -->

</Chapter>
