Skip to content

Rewrite the installation section of the manual #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fingolfin merged 2 commits into from
Oct 2, 2026
Merged

Rewrite the installation section of the manual #62

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
66a5d9a
Rewrite the installation section of the manual
fingolfin Oct 1, 2026
2b8f850
Merge remote-tracking branch 'origin/master' into mh/modernize-instal…
fingolfin Oct 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
244 changes: 39 additions & 205 deletions doc/intro.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,153 +80,39 @@ In Chapter <Ref Chap="classicalpolarspaces"/> the functionality for classical po
<Heading>Getting and installing <Package>FinInG</Package></Heading>
<Index><Package>FinInG</Package></Index>

Since version 4.7.8, the official &GAP; distribution includes the <Package>FinInG</Package> package. The <Package>FinInG</Package> package requires the GAP packages <Package>GAPDoc</Package>, version 1.6 or higher, <Package>Forms</Package>, version 1.2.3 or higher, <Package>Orb</Package>, version 4.7.6 or higher, <Package>GenSS</Package>, version 1.6.4 or higher, and <Package>GRAPE</Package>, version 4.7 or higher, and <Package>cvec</Package>, version 2.5.7 or higher. These required packages are all part of the standard &GAP; distribution. However, the packages <Package>cvec</Package>, <Package>GRAPE</Package>, <Package>IO</Package>, and <Package>Orb</Package> may require additional compilation (cfr. infra for detailed instructions). Note that the <Package>IO</Package> is a package required by <Package>cvec</Package> and <Package>Orb</Package>, and is also part of the standard &GAP; distribution.<P />

Summarized, to get <Package>FinInG</Package> working, download and install &GAP; as explained in its installation instructions, and, under UNIX like systems (including MacOS), make sure that the compilation of the packages <Package>cvec</Package>, <Package>GRAPE</Package>, <Package>IO</Package>, and <Package>Orb</Package> is done. Note that the windows distribution of &GAP; contains precompiled binaries of these packages, so under Windows, no further steps are required after installing &GAP; according to its installation instructions. In the next section we summarize the installation procedure under UNIX like systems.

<!--Finally note that currently, one <Package>FinInG</Package> function will use the
<Package>Design</Package> package. This package is part of the standard &GAP;
distribution too, but it is not a requirement.--><!--This remark is very true, but maybe not relevant here-->

<Subsection>
<Heading>Installation procedure under UNIX like systems</Heading>

The installation of &GAP; itself is generic for each UNIX like system, including the different flavours of Mac OS. You only need a terminal application, and you need access to the standard unix tools gunzip and tar, and the make tools. Detailed information on how to install &GAP;, can be found in the documentation of &GAP;. The installation procedure for <Package>FinInG</Package>, a standard GAP package, does <E>not</E> require compilation, however the packages <Package>cvec</Package>, <Package>GRAPE</Package>, <Package>IO</Package>, and <Package>Orb</Package> do. First install &GAP; according to the installation instructions. If you start &GAP; the output might look like in the example below. Note that <Package>IO</Package> is not listed as loaded package (see line starting with 'Packages' in the example output). This means that <Package>IO</Package> has not been compiled. Trying to load the <Package>IO</Package> will result in an error message.

<Example>
jdebeule ~ $ gap4r8
+-------+ GAP 4.8.8, 20-Aug-2017, build of 2017-09-04 15:17:33 (CEST)
| GAP | https://www.gap-system.org
+-------+ Architecture: x86_64-apple-darwin16.7.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: AClib 1.2, Alnuth 3.0.0, AtlasRep 1.5.1, AutPGrp 1.8,
CRISP 1.4.4, Cryst 4.1.12, CrystCat 1.1.6, CTblLib 1.2.2,
FactInt 1.5.4, FGA 1.3.1, GAPDoc 1.6, IRREDSOL 1.4, LAGUNA 3.7.0,
Polenta 1.3.7, Polycyclic 2.11, RadiRoot 2.7, ResClasses 4.6.0,
Sophus 1.23, SpinSym 1.5, TomLib 1.2.6, Utils 0.46
Try '??help' for help. See also '?copyright', '?cite' and '?authors'
gap> LoadPackage("io");
#I IO package is not available. To see further details, enter
#I SetInfoLevel(InfoPackageLoading,4); and try to load the package again.
fail
</Example>

</Subsection>
<Package>FinInG</Package> is part of the &GAP; distribution, so it is already present in a standard
&GAP; installation. It requires the packages <Package>cvec</Package>, <Package>Forms</Package>,
<Package>GenSS</Package>, <Package>GRAPE</Package> and <Package>Orb</Package>, and <Package>cvec</Package>
in turn requires <Package>IO</Package>. All of these are part of the &GAP; distribution too. The required
versions are listed in the file <F>PackageInfo.g</F> of <Package>FinInG</Package>.

<Subsection>
<Heading>Compiling packages</Heading>
In this subsection it is explained how to compile the necessary packages in case this is not yet done for your &GAP; installation. We assume that you have write access to the &GAP; installation on your computer. If this is not the case, you should ask your system administrator to do this for you. Locate your &GAP; installation. The examples below are generated using a GAP4.8.8 installation residing in "/opt/gap4r8". Clearly, subsequent versions of gap will reside in a differently named directory, e.g. "/opt/gap4r9". Another commonly used directory under UNIX like systems to install software is "/usr/local", so gap might reside in "/usr/local/gap4r8" too. In all examples in this section, we assume your &GAP; installation resides in "/opt/gap4r8". Therefore, replace any occurrence of "/opt/gap4r8" with the actual directory of your &GAP; installation when executing the installation steps.<P/>

Three steps will be necessary to compile the <Package>IO</Package> package: go into the correct directory, and issue the 'configure' command and then issue the 'make' command. Note that the directory name of the package is dependent on its version number. The correct name can be found as follows:
<Example>
jdebeule ~ $ ls /opt/gap4r8/pkg/ |grep io-
io-4.4.6
</Example>

From this output, it can be determined that the <Package>IO</Package> resides in "/opt/gap4r8/pkg/io-4.4.6/". The three steps to be taken to compile <Package>io</Package> are demonstrated in the example below.
<Heading>Compiling the required packages</Heading>

Some of the required packages contain code that must be compiled:
<List>
<Item><Package>IO</Package> and <Package>cvec</Package> must be compiled, otherwise
<Package>FinInG</Package> cannot be loaded.</Item>
<Item><Package>GRAPE</Package> uses the program <C>nauty</C> to compute automorphism groups of graphs.
<Package>FinInG</Package> relies on this for the collineation groups of generalised polygons (see Chapter
<Ref Chap="gpolygons"/>) and for <F>AutGroupIncidenceStructureWithNauty</F> and
<F>IsIsomorphicIncidenceStructureWithNauty</F>.</Item>
<Item><Package>Orb</Package> works without compilation, but its compiled part makes it faster.</Item>
</List>

The &GAP; installer for Windows contains compiled versions of these packages, so no further steps are
needed there. On Linux, macOS and other UNIX-like systems, use the script <F>BuildPackages.sh</F>
that comes with &GAP;. Run it from the <F>pkg</F> directory of your &GAP; installation; when given
package directories as arguments, it compiles only those:

<Log>
cd /path/to/gap/pkg
../bin/BuildPackages.sh io* cvec* orb* grape*
</Log>

Afterwards, start &GAP; and load <Package>FinInG</Package>. The output should end as follows.

<Example>
root ~ $ cd /opt/gap4r8/pkg/io-4.4.6/
root /opt/gap4r8/pkg/io-4.4.6 $ ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... cnf/install-sh -c -d
...
...lots of output
...
config.status: creating Makefile
config.status: creating src/pkgconfig.h
config.status: src/pkgconfig.h is unchanged
config.status: executing depfiles commands
config.status: executing libtool commands
root /opt/gap4r8/pkg/io-4.4.6 $ make
CC src/io_la-io.lo
CCLD io.la
cnf/install-sh -c -d ./bin/x86_64-apple-darwin16.7.0-gcc-default64
cp .libs/io.so bin/x86_64-apple-darwin16.7.0-gcc-default64/io.so
</Example>

Now starting &GAP; should produce the following output, notice the presence
of "IO 4.4.6" as one of the loaded packages.

<Example>
jdebeule ~ $ gap4r8
+-------+ GAP 4.8.8, 20-Aug-2017, build of 2017-09-04 15:17:33 (CEST)
| GAP | https://www.gap-system.org
+-------+ Architecture: x86_64-apple-darwin16.7.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: AClib 1.2, Alnuth 3.0.0, AtlasRep 1.5.1, AutPGrp 1.8,
CRISP 1.4.4, Cryst 4.1.12, CrystCat 1.1.6, CTblLib 1.2.2,
FactInt 1.5.4, FGA 1.3.1, GAPDoc 1.6, IO 4.4.6, IRREDSOL 1.4,
LAGUNA 3.7.0, Polenta 1.3.7, Polycyclic 2.11, RadiRoot 2.7,
ResClasses 4.6.0, Sophus 1.23, SpinSym 1.5, TomLib 1.2.6,
Utils 0.46
Try '??help' for help. See also '?copyright', '?cite' and '?authors'
gap>
</Example>

Similar steps are now necessary to compile the package <Package>cvec</Package>, <Package>Orb</Package>, and <Package>grape</Package>:
go into the correct directory, and issue the 'configure' and 'make' command. In the example below, we include
the determination of the correct directory names. Note that the directory name of the <Package>grape</Package> package
is not dependent on its version number, so it resides in "/opt/gap4r8/pkg/grape".

<Example>
root /opt/gap4r8/pkg/cvec-2.5.7 $ cd
root ~ $ ls /opt/gap4r8/pkg/ |grep cvec-
cvec-2.5.7
root ~ $ cd /opt/gap4r8/pkg/cvec-2.5.7/
root /opt/gap4r8/pkg/cvec-2.5.7 $ ./configure
...
...lots of output
...
config.status: executing libtool commands
root /opt/gap4r8/pkg/cvec-2.5.7 $ make
CC src/cvec_la-cvec.lo
CCLD cvec.la
cnf/install-sh -c -d ./bin/x86_64-apple-darwin16.7.0-gcc-default64
cp .libs/cvec.so bin/x86_64-apple-darwin16.7.0-gcc-default64/cvec.so
root ~ $ ls /opt/gap4r8/pkg/ |grep orb-
orb-4.7.6
root ~ $ cd /opt/gap4r8/pkg/orb-4.7.6/
root /opt/gap4r8/pkg/orb-4.7.6 $ ./configure
...
...lots of output
...
config.status: executing libtool commands
root /opt/gap4r8/pkg/orb-4.7.6 $ make
...some output
cp .libs/orb.so bin/x86_64-apple-darwin16.7.0-gcc-default64/orb.so
root ~ $ cd /opt/gap4r8/pkg/grape
root /opt/gap4r8/pkg/grape $ ./configure
root /opt/gap4r8/pkg/grape $ make
...lots of output
root /opt/gap4r8/pkg/grape $
</Example>

Note that warnings may occur during the compilation process, which can all be ignored. If compilation of
these packages has been successful, restart &GAP; and load <Package>FinInG</Package> using "LoadPackage("fining")".
The output should look as follows.

<Example>
jdebeule ~ $ gap4r8
+-------+ GAP 4.8.8, 20-Aug-2017, build of 2017-09-04 15:17:33 (CEST)
| GAP | https://www.gap-system.org
+-------+ Architecture: x86_64-apple-darwin16.7.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: AClib 1.2, Alnuth 3.0.0, AtlasRep 1.5.1, AutPGrp 1.8,
CRISP 1.4.4, Cryst 4.1.12, CrystCat 1.1.6, CTblLib 1.2.2,
FactInt 1.5.4, FGA 1.3.1, GAPDoc 1.6, IO 4.4.6, IRREDSOL 1.4,
LAGUNA 3.7.0, Polenta 1.3.7, Polycyclic 2.11, RadiRoot 2.7,
ResClasses 4.6.0, Sophus 1.23, SpinSym 1.5, TomLib 1.2.6,
Utils 0.46
Try '??help' for help. See also '?copyright', '?cite' and '?authors'

gap> LoadPackage("fining");
...
---------------------------------------------------------------------
Expand All @@ -246,75 +132,23 @@ by John Bamberg (https://johnbamberg.github.io)
For help, type: ?FinInG
---------------------------------------------------------------------
true
gap>
</Example>

If <C>LoadPackage</C> returns <K>fail</K> instead, enter <C>SetInfoLevel(InfoPackageLoading, 4);</C>
and load the package again to see which requirement is missing.

</Subsection>

<Subsection>
<Heading>Updating <Package>FinInG</Package></Heading>

New releases of <Package>FinInG</Package> will be distributed automatically with new releases of &GAP;. However,
it is possible easily to update <Package>FinInG</Package> in an existing installation of &GAP;, provided
the new version of <Package>FinInG</Package> does not require newer versions of existing packages in the
installation. It is also possible to have different versions of <Package>FinInG</Package> installed on
one system.

To update <Package>FinInG</Package> it is sufficient to download and unpack the archive containing the new release. First find the
location of your existing &GAP; installation. We assume in the example below that it is
<Log>/opt/gap4r8/</Log>
Make sure you have write permission on this location. If this is not the case, you must ask your system administrator to do
this. Download the <Package>FinInG</Package> archive "fining-....tgz" to this location, and unpack the archive. This can be done by issuing
<Log>gunzip fining-....tgz</Log>
which yields a file "fining-....tar", in the pkg directory, after which issuing the command
<Log>tar -xf fining-....tar</Log>
Unpack the archive in a subdirectory fining. Starting &GAP; and loading <Package>FinInG</Package> the usual
way should give you the newly installed version.

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.
In this case, i.e. 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
<Log>gap -l "/opt/gap4r8;./"</Log>
This will cause gap to startup and use as pkg directory both its own central pkg directory, i.e.
"/opt/gap4r8/pkg/", as well as your local pkg directory, i.e. "/home/yourself/pkg/".
You should see something like the following output.

<Example>
+-------+ GAP 4.8.8, 20-Aug-2017, build of 2017-09-04 15:17:33 (CEST)
| GAP | https://www.gap-system.org
+-------+ Architecture: x86_64-apple-darwin16.7.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: AClib 1.2, Alnuth 3.0.0, AtlasRep 1.5.0, AutPGrp 1.6,
Browse 1.8.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.4.4,
IRREDSOL 1.2.4, LAGUNA 3.7.0, Polenta 1.3.2, Polycyclic 2.11,
RadiRoot 2.7, ResClasses 3.4.0, Sophus 1.23, SpinSym 1.5,
TomLib 1.2.5
Try '?help' for help. See also '?copyright' and '?authors'
gap> LoadPackage("fining");
...
---------------------------------------------------------------------
______________ ________ _________
___ ____/__(_)__________ _/________ ____/
__ /_ __ /__ __ __ / __ __ / __
_ __/ _ / _ / / /_/ / _ / / / /_/ /
/_/ /_/ /_/ /_//___/ /_/ /_/____/
---------------------------------------------------------------------
Loading FinInG &VERSION; (Finite Incidence Geometry)
by John Bamberg (https://johnbamberg.github.io)
Anton Betten (https://www.math.colostate.edu/~betten)
Philippe Cara (https://wids.research.vub.be/nl/philippe-cara)
Jan De Beule (https://wids.research.vub.be/en/node/149)
Michel Lavrauw (https://mlavrauw.github.io)
Max Neunhoeffer
For help, type: ?FinInG
---------------------------------------------------------------------
true
</Example>
New releases of <Package>FinInG</Package> are included in new releases of &GAP;, and are also
available from <URL>https://github.com/gap-packages/FinInG/releases</URL>. To use a newer release
with an existing &GAP; installation, unpack its archive in the <F>pkg</F> subdirectory of your user
&GAP; root directory, which is given by <C>GAPInfo.UserGapRoot</C> (see
<Ref BookName="ref" Sect="GAP Root Directories"/>). If several versions of a package are installed,
&GAP; loads the newest one that can be loaded. The <Package>PackageManager</Package> package can
download and install releases into this directory for you.

</Subsection>
</Section>
Expand Down
Loading