install.xml

<!-- %W  install.xml            GAP documentation                  Greg Gamble -->
<!-- %H                                                                        -->
<!-- %Y  Copyright (C) 2001, School of Math & Comp. Sci., St Andrews, Scotland -->


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Chapter Label="Installing and Loading the Example Package">
<Heading>Installing and Loading the Example Package</Heading>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Unpacking the Example Package">
<Heading>Unpacking the Example Package</Heading>

If the &Example; package was obtained as a part of the &GAP; distribution
from the <Q>Download</Q> section of the &GAP; website, you may proceed
to Section <Ref Sect="Compiling Binaries of the Example Package"/>.
Alternatively, the &Example; package may be installed using a separate archive,
for example, for an update or an installation in a non-default location 
(see <Ref Sect="GAP Root Directories" BookName="ref"/>).
<P/>

Below we describe the installation procedure for the <File>.tar.gz</File> 
archive format. Installation using other archive formats is performed in a 
similar way.
<P/>

To install the &Example; package, unpack the archive file, which  should
have a name of form <C>example-<A>XXX</A>.tar.gz</C> for some version number 
<A>XXX</A>, by typing
<P/>
&nbsp;&nbsp;<C>gzip -dc example-<A>XXX</A>.tar.gz | tar xpv</C>
<P/>

It may be unpacked in one of the following locations:
<List>
<Item>
in the <File>pkg</File> directory of your &GAP;&nbsp;4 installation;
</Item>
<Item>
or in a directory named <File>.gap/pkg</File> in your home directory
(to be added to the &GAP; root directory unless &GAP; is started with
<C>-r</C> option);
</Item> 
<Item>
or in a directory named <File>pkg</File> in another directory of your 
choice (e.g.&nbsp;in the directory <File>mygap</File> in your home 
directory).
</Item>
</List>

In the latter case one one must start &GAP; with the <C>-l</C> option,
e.g.&nbsp;if your private <F>pkg</F> directory is a subdirectory of 
<F>mygap</F> in your home directory you might type:
<P/>
&nbsp;&nbsp;<C>gap -l ";<A>myhomedir</A>/mygap"</C>
<P/>
where <A>myhomedir</A> is the  path  to  your  home  directory,  which  (since
&GAP;&nbsp;4.3) may be replaced  by  a  tilde (the  empty  path  before  the
semicolon is  filled  in  by  the  default  path  of  the  &GAP;&nbsp;4  home
directory).

</Section>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Compiling Binaries of the Example Package">
<Heading>Compiling Binaries of the Example Package</Heading>

After unpacking the archive, go to the newly created <F>example</F>  directory
and call <C>./configure</C> to use the default <C>../..</C> path to the
&GAP; home directory or <C>./configure <A>path</A></C> where <A>path</A> is 
the path to the &GAP; home directory, if the package is being installed in a 
non-default location. So for example if you install the package in the
<F>~/.gap/pkg</F> directory and the &GAP; home directory is <F>~/gap4r5</F>
then you have to call
<P/>
<Log><![CDATA[
./configure ../../../gap4r5/
]]></Log>
<P/>
This will fetch the architecture type for which &GAP; has been compiled
last and create a <F>Makefile</F>. Now simply call
<P/>
<Log><![CDATA[
make
]]></Log>
<P/>
to compile the binary and to install it in the appropriate place.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Loading the Example Package">
<Heading>Loading the Example Package</Heading>

To use the &Example; Package you have to request it explicitly. This  is
done by calling <Ref Func="LoadPackage" BookName="ref"/>:
<P/>
<Example><![CDATA[
gap> LoadPackage("example");
----------------------------------------------------------------
Loading  Example 3.3 (Example/Template of a GAP Package)
by Werner Nickel (http://www.mathematik.tu-darmstadt.de/~nickel),
   Greg Gamble (http://www.math.rwth-aachen.de/~Greg.Gamble), and
   Alexander Konovalov (http://www.cs.st-andrews.ac.uk/~alexk/).
----------------------------------------------------------------
true
]]></Example>
<P/>

If &GAP; cannot find a working binary, the call  to  <C>LoadPackage</C>  will
still succeed but a warning is issued informing that  the  <C>HelloWorld()</C>
function will be unavailable.
<P/>
If you want to load the &Example; package by default, you  can  put  the
<C>LoadPackage</C> command  into  your  <F>gaprc</F>  file  
(see  Section&nbsp;<Ref Sect="The gap.ini and gaprc files" BookName="ref"/>).

</Section>
</Chapter>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %E -->