<Chapter Label="Installation">
<Heading>Installation</Heading>

This package provides an interface between &GAP; and either PARI/GP or
OSCAR. When &Alnuth; is loaded in &GAP; running inside OSCAR, it
automatically uses OSCAR. Otherwise, &Alnuth; uses PARI/GP, which has to be
obtained and installed independently of this package. &Alnuth; works with
PARI/GP Version 2.5 or higher.

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Installing Alnuth">
<Heading>Installing Alnuth</Heading>

The package &Alnuth; is part of the standard distribution of &GAP; so that
in most cases there is no need to install it separately. If you are using
&GAP; inside OSCAR, then &Alnuth; is already bundled and automatically uses
OSCAR, so no further installation is required. Otherwise, to use &Alnuth;
you need to have PARI/GP installed. See the following section for
information on PARI/GP.
<P/>

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;
in the form of gzipped tar-archives at
<URL>https://github.com/gap-packages/alnuth/releases</URL>
<P/>

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 <C>pkg</C> subdirectory of the &GAP;
installation tree. Otherwise you may install &Alnuth; in a private
<C>pkg</C> directory (for details see Subsections
<Ref BookName="ref" Sect="Installing a GAP Package"/> and
<Ref BookName="ref" Sect="GAP Root Directories"/>
in the &GAP; reference manual).
<P/>

To install the latest version of &Alnuth; download one of
the archives <C>alnuth.tar.gz</C>, move it to the
directory <C>pkg</C> in which you want to install, and unpack the
archive. If you are using the command line you can unpack with the
command <C>tar xzf alnuth.tar.gz</C>.
<P/>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Getting PARI/GP">
<Heading>Getting PARI/GP</Heading>

Using &Alnuth; outside OSCAR requires an installation of PARI/GP in
Version 2.5 or higher. The software PARI/GP is freely available at
<URL>https://pari.math.u-bordeaux.fr/</URL>
<P/>

Note that the place where PARI/GP is located in your system is
independent of the place where &Alnuth; is installed.
<P/>

<Enum>
<Item>
<E>Installing under Linux</E>
<P/>
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 <C>--version-short</C> will show you the version number.)
<P/>
If you install PARI/GP from source make sure you install with GMP
support for better performance and complete the installation with
<C>make install</C> so that you can start GP by just calling <C>gp</C> from the
command line.
</Item>
<Item>
 <E>Installing under Windows</E>
<P/>
For Windows it is sufficient to get the basic GP binary which can be found at
<URL>https://pari.math.u-bordeaux.fr/download.html</URL>
</Item>
</Enum>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Adjust the path of the executable for GP">
<Heading>Adjust the path of the executable for GP</Heading>

When &Alnuth; is used outside OSCAR, it needs to know where the executable
for GP is. In the default setting &Alnuth; looks for an executable program
named <C>gp</C> in the search paths of the system. More precisely, for a
file <C>gp</C> inside one of the directories in the list returned by
<C>DirectoriesSystemPrograms()</C> (called in a &GAP; session).
<P/>

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

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

To check whether an executable of GP in Version 2.5 or higher is
available with the default setting, you can use the function
<ManSection>
<Func Name="PariVersion" Arg=""/>
<Description>
which prints the version number, if the user preference
<C>PariGpPath</C> refers to a usable GP executable.
</Description>
</ManSection>

If you cannot use the default setting for you purpose, you have
several ways to configure Alnuth.
<P/>

The recommended approach is to use the &GAP; user preference system:
<Log><![CDATA[
gap> SetUserPreference("alnuth", "PariGpPath", "/home/my/pari-2.5.0/gp");
gap> SetUserPreference("alnuth", "PariStackSize", 256);
gap> WriteGapIniFile();
]]></Log>
This changes the current session immediately. <C>WriteGapIniFile()</C> writes
the current non-default settings to your personal <F>gap.ini</F>, so they are
used again in future &GAP; sessions. See
<Ref BookName="ref" Sect="Configuring User preferences"/> for background on the
user preference system.
<P/>

The user preferences relevant for Alnuth are shown by
<C>ShowUserPreferences("alnuth");</C>. The most important ones are
<C>PariGpPath</C>, <C>PariGpOptions</C>, <C>PariStackSize</C>, and
<C>PrimitiveElementTrials</C>.
<P/>

In older versions of &Alnuth; configuration was done via the global
variables <C>AL_EXECUTABLE</C>, <C>AL_PATH</C>, <C>AL_OPTIONS</C>,
<C>AL_STACKSIZE</C>, and <C>PRIM_TEST</C>. These globals are deprecated,
and they trigger a warning when used. The globals except for <C>AL_PATH</C>
still serve as a fallback if the corresponding user preference is unusable.
Their replacements are as follows:
<List>
<Mark><C>AL_EXECUTABLE</C></Mark>
<Item>use the user preference <C>PariGpPath</C></Item>
<Mark><C>AL_OPTIONS</C></Mark>
<Item>use the user preference <C>PariGpOptions</C></Item>
<Mark><C>AL_STACKSIZE</C></Mark>
<Item>use the user preference <C>PariStackSize</C></Item>
<Mark><C>PRIM_TEST</C></Mark>
<Item>use the user preference <C>PrimitiveElementTrials</C></Item>
<Mark><C>AL_PATH</C></Mark>
<Item>has been removed; Alnuth now always uses the bundled GP helper files.</Item>
</List>
<P/>

For backwards compatibility, the following functions still exist after loading
the package (see Section <Ref Sect="Loading and testing the package"/>), but
they are deprecated wrappers around the user preference system.
<ManSection>
<Func Name="SetAlnuthExternalExecutable" Arg="path"/>
<Description>
sets the user preference <C>PariGpPath</C> for the current &GAP; session.
Depending on your installation of PARI/GP and your operating system the string
<A>path</A> can be either the command to start GP in a terminal (for example
<C>gp</C>) or the complete path to the executable of GP. The function is
deprecated; new code should call
<C>SetUserPreference("alnuth", "PariGpPath", path);</C> directly.
<P/>
The function returns the stored preference value.
</Description>
</ManSection>

<ManSection>
<Func Name="SetAlnuthExternalExecutablePermanently" Arg="path"/>
<Description>
does the same as <C>SetAlnuthExternalExecutable</C> and then calls
<C>WriteGapIniFile()</C> to persist the current user preference settings in
your personal <F>gap.ini</F>. The function is deprecated; new code should call
<C>SetUserPreference("alnuth", "PariGpPath", path); WriteGapIniFile();</C>
instead.
</Description>
</ManSection>

<ManSection>
<Func Name="RestoreAlnuthExternalExecutablePermanently" Arg=""/>
<Description>
restores the default value of <C>PariGpPath</C> and then calls
<C>WriteGapIniFile()</C>. The function is deprecated; new code should set
<C>PariGpPath</C> to the desired default command or path and then call
<C>WriteGapIniFile()</C> directly.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Loading and testing the package">
<Heading>Loading and testing the package</Heading>

If &Alnuth; is not loaded when GAP is started you have to request it
explicitly to use it. This is done by calling <C>LoadPackage("alnuth");</C>
in a GAP session. If &Alnuth; had not been loaded already a short
banner will be displayed.
<P/>
<Log><![CDATA[
gap> LoadPackage("alnuth");
Loading Alnuth 4.0.0 (ALgebraic NUmber THeory and an interface to PARI/GP and OSCAR)
by Björn Assmann,
   Andreas Distler (a.distler@tu-bs.de), and
   Bettina Eick (http://www.iaa.tu-bs.de/beick).
maintained by:
   Max Horn (https://www.quendi.de/math) and
   The GAP Team (support@gap-system.org).
Homepage: https://gap-packages.github.io/alnuth
Report issues at https://github.com/gap-packages/alnuth/issues
true
gap>
]]></Log>
To load a certain version of &Alnuth; you can specify the version number as
second argument in the call to <C>LoadPackage</C>. (See <Ref BookName="ref" Func="LoadPackage"/>
in the &GAP; reference manual or type <C>?LoadPackage</C> within a GAP session).
<P/>

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

<Log><![CDATA[
gap> ReadPackage("Alnuth", "tst/testinstall.g");
Architecture: aarch64-apple-darwin21.4.0-default64-kv8

testing: GAPROOT/pkg/alnuth/tst/ALNUTH.tst
      66 ms (33 ms GC) and 11.0MB allocated for GAPROOT/pkg/alnuth/tst/ALNUTH.tst
testing: GAPROOT/pkg/alnuth/tst/version.tst
      21 ms (21 ms GC) and 29.6KB allocated for GAPROOT/pkg/alnuth/tst/version.tst
-----------------------------------
total        87 ms (54 ms GC) and 11.0MB allocated
              0 failures in 2 files

#I  No errors detected while testing
gap>
]]></Log>

The architecture, timings and memory usage will usually differ; other
discrepancies in the output indicate some problem.
<P/>

If the test suite runs into an error in the first part, which when running
outside OSCAR 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.
<P/>

If you find any bugs or have any suggestions or comments, we would very much
appreciate it if you would let us know by submitting an issue at the &Alnuth;
issue tracker on GitHub <URL>https://github.com/gap-packages/alnuth/issues</URL>
or by writing an mail to <Email>support@gap-system.org</Email>.

</Section>
</Chapter>
