<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %W  gappkg.msk                GAP documentation             Werner Nickel -->
<!-- %W                                                       Alexander Hulpke -->
<!-- %% -->
<!-- %H  @(#)<M>Id: gappkg.msk,v 1.18 2004/01/26 10:09:20 gap Exp </M> -->
<!-- %% -->


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Chapter Label="GAP Packages">
<Heading>Using GAP Packages</Heading>

<Index>package</Index>
The  functionality  of  &GAP;  can  be  extended  by  loading  &GAP;
packages. 
&GAP; distribution already contains all currently redistributed with 
&GAP; packages in the <F>&GAPDIRNAME;/pkg</F> directory.
<P/>
&GAP; packages are written by (groups  of) &GAP; users which may not
be  members  of the  &GAP;  developer  team. The  responsibility  and
copyright of a &GAP; package remains with the original author(s).
<P/>
&GAP;  packages  have  their  own  documentation  which  is  smoothly
integrated into the &GAP; help system.
<P/>
All  &GAP;  users   who  develop  new  code  are   invited  to  share
the  results  of their  efforts  with  other  &GAP; users  by  making
the  code  and its  documentation  available  in  form of  a  package.
Information how  to do  this is  available from  the &GAP;  Web pages
(<URL>http://www.gap-system.org</URL>)
and in the &GAP; package <Package>Example</Package>
(see <URL>http://www.gap-system.org/Packages/example.html</URL>).
There  are  possibilities  to get  a  package  distributed together  with
&GAP;  and it  is possible  to submit  a package  to a formal refereeing
process.
<P/>
In this chapter we describe how to use existing packages.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Installing a GAP Package">
<Heading>Installing a GAP Package</Heading>

Before a  package can be  used it must  be installed. With  a standard
installation of  &GAP; there should  be all currently redistributed with 
&GAP; packages already available. But since &GAP; packages are released 
independently of the main  &GAP; system  it  may be  sensible to  upgrade  
or install new packages between upgrades of your &GAP; installation.
<P/>
A package consists of a collection  of files within a single directory
that must  be a subdirectory of  the <F>pkg</F>  directory   in one  of the
&GAP; root directories, see <Ref Sect="GAP Root Directories"/>. (If you don't
have access  to the <F>pkg</F>  directory in your main  &GAP; installation
you can add private root directories as explained in that section.)
<P/>
Whenever  you  get from  somewhere  an  archive  of a  &GAP;  package
it  should be  accompanied  with  a <F>README</F>  file  that explains  its
installation.  Some packages  just  consist  of  &GAP;  code and  the
installation  is  done  by  unpacking   the  archive  in  one  of  the
places  described above.  There are  also packages  that need  further
installation steps,  there may be  for example some  external programs
which  have  to  be  compiled  (this is  often  done  by  just  saying
<C>./configure; make</C>  inside the unpacked package  directory, but check
the individual <F>README</F> files). Note that if you use Windows you may not 
be able to use some or all external binaries.
</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Loading a GAP Package">
<Heading>Loading a GAP Package</Heading>

<Index>automatic loading of GAP packages</Index>
<Index>disable automatic loading</Index>
Some &GAP; packages are prepared for <E>automatic loading</E>,
that is they will be loaded automatically with &GAP;,
others must in each case be separately loaded by a call to
<Ref Func="LoadPackage"/>.

<#Include Label="LoadPackage">
<#Include Label="SetPackagePath">
<#Include Label="ExtendRootDirectories">
<#Include Label="DisplayPackageLoadingLog">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Functions for GAP Packages">
<Heading>Functions for GAP Packages</Heading>

The following functions are mainly used in files contained in  a
package and not by users of a package.

<#Include Label="ReadPackage">
<#Include Label="TestPackageAvailability">
<#Include Label="InstalledPackageVersion">
<#Include Label="DirectoriesPackageLibrary">
<#Include Label="DirectoriesPackagePrograms">
<#Include Label="CompareVersionNumbers">
<#Include Label="IsPackageMarkedForLoading">
<#Include Label="DeclareAutoreadableVariables">

<Subsection Label="Kernel modules">
<Heading>Kernel modules in &GAP; packages</Heading>

<Index Key="gac"><C>gac</C></Index>
If the package has a kernel module, then it can be compiled using the 
<Package>gac</Package> script. A kernel module is implemented in C
and follows certain conventions to comply with the &GAP; kernel interface,
which we plan to document later. In the meantime, we advice to get in touch
with &GAP; developers if you plan to develop such a package.
<P/>
<!-- %%  The gac script works only on UNIX systems. It was written by -->
<!-- %%  Ferenc&nbsp;R{\'a}k{\'o}czi and Martin Sch{\"o}nert. -->
To use the <Package>gac</Package> script to produce dynamically loadable 
modules, call it with the <C>-d</C> option, for example:
<P/>
<Log><![CDATA[
$ gap4/bin/i386-ibm-linux-gcc2/gac -d test.c
]]></Log>
<P/>
This will produce a file <File>test.so</File>, which then can be loaded into &GAP;
with <Ref Func="LoadDynamicModule"/>.

</Subsection>

<ManSection>
<Func Name="LoadDynamicModule" Arg='filename[, crc]'/>

<Description>
To load a compiled file, the command <Ref Func="LoadDynamicModule"/> is used.
This command loads <A>filename</A> as module. If given, the CRC checksum 
<A>crc</A> must match the value of the module (see <Ref Sect="CrcFile"/>).
<P/>
<Log><![CDATA[
gap> LoadDynamicModule("./test.so");
gap> CrcFile("test.so");
2906458206
gap> LoadDynamicModule("./test.so",1);
Error, <crc> mismatch (or no support for dynamic loading) called from
<function>( <arguments> ) called from read-eval-loop
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
brk> quit;
gap> LoadDynamicModule("./test.so",2906458206);
]]></Log>
<P/>
On some operating systems, once you have loaded a dynamic module with
a certain filename, loading another with the same filename will have
no effect, even if the file on disk has changed.
</Description>
</ManSection>

<Subsection Label="The PackageInfo.g File">
<Heading>The PackageInfo.g File</Heading>

Each package has the file <F>PackageInfo.g</F> which
contains meta-information about  the package
(package  name,  version,  author(s),  relations  to  other  packages,
homepage, download archives, banner, etc.). This file is used by the package
loading mechanism and also for the distribution of a package to other
users.
</Subsection>

<#Include Label="ValidatePackageInfo">
<#Include Label="ShowPackageVariables">
<#Include Label="BibEntry">
<#Include Label="Cite">

</Section>

</Chapter>

