install.tex

\Chapter{Installation}

This package provides an interface between {\GAP} and PARI/GP. 
PARI/GP itself is not part of this package.  It has to be obtained and
installed independently of this package. {\Alnuth} works with PARI/GP
Version 2.5 or higher.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing Alnuth}

The package {\Alnuth} is part of the standard distribution of {\GAP} so that
in most cases there is no need to install it separately. To use {\Alnuth}
you need to have PARI/GP installed. See the following section for
information on PARI/GP.

In case you want to update {\Alnuth} independently of your main {\GAP}
installation or if you are interested in an old version of {\Alnuth}
interfacing to KANT/KASH you can find all released versions of {\Alnuth}
at the package's homepage
\URL{http://www.icm.tu-bs.de/ag_algebra/software/Alnuth/}

in the form of gzipped tar-archives or as uncompressed tar-archives,
and starting with Version 3.0.0 also as zip archives for Windows. The
main page always contains the latest version of {\Alnuth}, while older
versions can be found under `Archives'.

There are two ways of installing a {\GAP} package. If you have
permission to add files to the installation of {\GAP} on your system
you may install {\Alnuth} into the `pkg' subdirectory of the {\GAP}
installation tree. Otherwise you may install {\Alnuth} in a private
`pkg' directory (for details see Subsections "ref:Installing a GAP
Package" and "ref:GAP Root Directories" in the {\GAP} reference manual).

To install the latest version of {\Alnuth} under Linux download one of
the archives `alnuth.tar' and `alnuth.tar.gz', move it to the
directory `pkg' in which you want to install, and unpack the
archive. If you are using the command line you can unpack the former
with the command `tar xf alnuth.tar', respectively `tar xzf
alnuth.tar.gz' for the gzipped tar-archive.

For installation under Windows download the archive `alnuth-win.zip',
move it to the `pkg' directory in which you want to install, and
extract the archive (If you right click on the archive there should
appear a menu containing the entry `Extract here'.).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Getting PARI/GP}
 
Using {\Alnuth} requires an installation of PARI/GP in Version 2.5 or
higher. The software PARI/GP is freely available at
\URL{http://pari.math.u-bordeaux.fr/}

Note that the place where PARI/GP is located in your system is
independent of the place where {\Alnuth} is installed.

\beginlist
\item{\bf a.} 
{\bf Installing under Linux}

In many Linux distributions PARI/GP can be installed via the software
package manager, but this might sometimes be an older version which
cannot be used together with {\Alnuth}. (Starting GP from the command line
with the option `--version-short' will show you the version number.)

If you install PARI/GP from source make sure you install with GMP
support for better performance and complete the installation with
`make install' so that you can start GP by just calling `gp' from the
command line.

\item{\bf b.} 
{\bf Installing under Windows}

For Windows it is sufficient to get the basic GP binary which can be found at
\URL{http://pari.math.u-bordeaux.fr/download.html}
\endlist

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Adjust the path of the executable for GP}

This package needs to know where the executable for GP is. In the
default setting {\Alnuth} looks for an executable program named `gp' in
the search paths of the system. More precisely, for a file `gp' inside
one of the directories in the list returned by
`DirectoriesSystemPrograms()' (called in a {\GAP} session).

Under Linux the default setting should work with a standard
installation of PARI/GP.

For the default setting to work under Windows the downloaded
executable file, for example `gp-2-5-0.exe' has to be renamed to
`gp.exe' and moved to one of the directories listed by
`DirectoriesSystemPrograms()' (Ignore the leading `cygdrive' in each
path name and note that the single letter specifies the drive, for
example `/cygdrive/c/Windows/' denotes the folder `Windows' on drive
`C:').

To check whether an executable of GP in Version 2.5 or higher is
available with the default setting, you can use the function
\> PariVersion( )

which prints the verion number, if the global variable `AL_EXECUTABLE'
is bound to the file name of a GP executable.

If you cannot use the default setting for you purpose, you have
two options to specify a new place and name for the GP executable.

If you are able to edit the file `defs.g' in the main directory of
{\Alnuth}, then you can change the line 
\beginexample
    BindGlobal("AL_EXECUTABLE", Filename(DirectoriesSystemPrograms(), "gp"));
\endexample
to something like
\beginexample
    BindGlobal("AL_EXECUTABLE", "/home/my/pari-2.5.0/gp");
\endexample 
under Linux or
\beginexample
    BindGlobal("AL_EXECUTABLE", "/cygdrive/c/Users/my/Downloads/gp-2-5-0");
\endexample 
under Windows, where the second argument gives the path to the GP
executable you want to use (Change the strings given above to reflect
the actual path on your system.). Please note that in case of a new
installation of {\Alnuth} you will have to change `defs.g' again. 

Alternatively you can also change your personal `gaprc' file (see 
the Subsection "ref:The gaprc file" in the {\GAP} reference manual)
for setting the variable AL_EXECUTABLE to a proper value. To do this
add the appropriate line from above with the `BindGlobal' command to
`gaprc'.

The third possibility is to change the path to the GP executable from
within {\GAP} using one of the following two functions. To do this you
first have to load the package (see Section "Loading and testing the
package").
\> SetAlnuthExternalExecutable( <path> )

adjusts the global variable `AL_EXECUTABLE' for the current {\GAP}
session. Depending on your installation of PARI/GP and your operating
system the string <path> has to be either the command to start GP in a
terminal (for example `gp') or the complete path to the executable of GP 
(for example `/cygwindrive/c/windows/gp'). The function returns `fail'
if <path> does not execute GP in Version 2.5.0 or higher.

To make the change take effect for all of your {\GAP} sessions, you can
add `SetKantExecutable' with the path to the GP executable as argument
to your personal `gaprc' file (see the Subsection "ref:The gaprc file"
in the {\GAP} reference manual). 

If you want the change to affect all {\GAP} session of all users of the
{\GAP} installation you can use the following function:
\> SetAlnuthExternalExecutablePermanently( <path> )

does the same as `SetAlnuthExternalExecutable' and in addition trys to
change the file `defs.g' accordingly in the currently loaded version
of {\Alnuth}. A warning is issued if there is no write access to `defs.g'
from the current {\GAP} session.

\> RestoreAlnuthExternalExecutable( )

trys to restore the original content of the file `defs.g' in the
directory corresponding to the loaded version of {\Alnuth}. The function
returns `fail' if there is no write access to `defs.g'
from the current {\GAP} session.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Loading and testing the package}

If {\Alnuth} is not loaded when GAP is started you have to request it
explicitly to use it. This is done by calling `LoadPackage("Alnuth");'
in a GAP session. If {\Alnuth} had not been loaded already a short
banner will be displayed.

\beginexample
    gap> LoadingPackage("alnuth");
    Loading Alnuth 3.0.0 ...
    true
    gap>
\endexample
To load a certain version of Alnuth you can specify the version number as
second argument in the call to `LoadPackage'. (See `77.2 Loading a GAP
package' in the reference manual or type `?LoadPackage' within a GAP session).

Once the package is loaded, it is possible to check the correct installation
running a short test by calling `ReadPackage("Alnuth",
"tst/testinstall.tst");'.

\beginexample
    gap> ReadPackage("Alnuth", "tst/testinstall.g");
    Line 5 :
    + Test availability and version of PARI/GP
    Line 5 :
    + GAP4stones: 25000
    Line 85 :
    + Installation test of Alnuth package
    Line 85 :
    + GAP4stones: 609
    true
    gap>
\endexample

The number of GAP4stones will usually differ; other discrepancies in the 
output indicate some problem.

If the test suite runs into an error in the first part, which verifies the
availability of PARI/GP, check your installation of PARI/GP and consult the
last chapter of the documentation of Alnuth for more information.

If you find any bugs or have any suggestions or comments, we would very much
appreciate it if you would let us know by writing to `a.distler(at)tu-bs.de'.