% This file was created automatically from gappkg.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  gappkg.msk                GAP documentation             Werner Nickel
%W                                                       Alexander Hulpke
%%
%H  @(#)$Id: gappkg.msk,v 1.17.2.1 2004/01/26 10:12:22 gap Exp $
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{GAP Packages}

\index{package}

The  functionality  of  {\GAP}  can  be  extended  by  loading  {\GAP}
packages. Many packages are distributed  together with the core system
of {\GAP} consisting of the {\GAP}  kernel, the {\GAP} library and the
various data libraries.

{\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).

{\GAP}  packages  have  their  own  documentation  which  is  smoothly
integrated into the {\GAP} help system.

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}) and in the extension manual 
"ext:Writing a GAP Package".
There  are  possibilities  to get  a  package  distributed together  with
{\GAP}  and it  is possible  to submit  a package  to a formal refereeing
process.

In this Chapter we describe how to use existing packages.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing a GAP Package}

Before a  package can be  used it must  be installed. With  a standard
installation of  {\GAP} there should  be quite a few  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.

A package consists of a collection  of files within a single directory
that must  be a subdirectory of  the `pkg'  directory   in one  of the
{\GAP} root directories, see "ref:GAP Root Directory". (If you don't
have access  to the `pkg'  directory in your main  {\GAP} installation
you can add private root directories as explained in that section.)

Whenever  you  get from  somewhere  an  archive  of a  {\GAP}  package
it  should be  accompanied  with  a `README'  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
`./configure; make'  inside the unpacked package  directory, but check
the individual `README' files).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Loading a GAP Package}

\index{automatic loading of GAP packages}
\index{disable automatic loading}
Some {\GAP} packages are prepared for *automatic loading*,
that is they will be loaded automatically with {\GAP},
others must in each case be separately loaded by a call to `LoadPackage'.

\>LoadPackage( <name>[, <version>] ) F
\>LoadPackage( <name>[, <version>, <banner>[, <outercalls>]] ) F

loads the {\GAP} package with name <name>.
If the optional version string <version> is given, the package will only
be loaded in a version number at least as large as <version>,
or equal to <version> if its first character is `='
(see~"ext:Version Numbers" in ``Extending GAP'').
The argument <name> is case insensitive.

`LoadPackage' will return `true' if the package has been successfully
loaded and will return `fail' if the package could not be loaded.
The latter may be the case if the package is not installed, if necessary
binaries have not been compiled, or if the version number of the
available version is too small.

If the package <name> has already been loaded in a version number
at least or equal to <version>, respectively,
`LoadPackage' returns `true' without doing anything else.

If the optional third argument <banner> is `false' then no package banner
is printed.
The fourth argument <outercalls> is used only for recursive calls of
`LoadPackage', when the loading process for a package triggers the
loading of other packages.



After a package  has been loaded its code and  documentation should be
available as other parts of the {\GAP} library are.

The documentation of each {\GAP} package  will tell you if the package
loads automatically or  not. Also, {\GAP} prints the list  of names of
all  {\GAP}  packages which  have  been  loaded (either  by  automatic
loading or  via `LoadPackage' commands  in one's `.gaprc' file  or the
like) at the end of the initialization process.

A {\GAP} package may also install only its documentation automatically
but still need loading by  `LoadPackage'. In this situation the online
help displays `(not  loaded)' in the header lines of  the manual pages
belonging to this {\GAP} package.

If for some reason you don't want certain packages to be automatically
loaded, {\GAP} provides three levels for disabling autoloading:

\indextt{NOAUTO}
The autoloading of  specific packages can be overwritten for the whole
{\GAP} installation by putting a file `NOAUTO' into a `pkg'  directory
that contains lines with the names  of packages  which  should  not be
automatically loaded.

Furthermore, individual users can disable the autoloading of specific
packages by using the following command in their `.gaprc' file
(see~"The .gaprc file").

\){\kernttindent}ExcludeFromAutoload( <pkgnames> );

where <pkgnames> is the list of names of the {\GAP} packages in question.

Using  the  `-A' command  line  option  when  starting up  {\GAP}
(see~"Command Line Options"), automatic loading is switched off,
and the scanning of the `pkg' directories containing the installed
packages is delayed until the first call of "LoadPackage".


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Functions for GAP Packages}

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

\>ReadPackage( <name>, <file> ) F
\>ReadPackage( <pkg-file> ) F
\>RereadPackage( <name>, <file> ) F
\>RereadPackage( <pkg-file> ) F

In the first form, `ReadPackage' reads the file <file> of the {\GAP}
package <name>, where <file> is given as a path relative to the home
directory of <name>.
In the second form where only one argument <pkg-file> is given, this
should be the path of a file relative to the `pkg' subdirectory of {\GAP}
root paths (see~"ref:GAP Root Directory" in the {\GAP} Reference Manual).
Note that in this case, the package name is assumed to be equal to the
first part of <pkg-file>, *so this form is not recommended*.

The absolute path is determined as follows.
If the package in question has already been loaded then the file in the
directory of the loaded version is read.
If the package is available but not yet loaded then the directory given
by `TestPackageAvailability' (see~"TestPackageAvailability"), without
prescribed version number, is used.
(Note that the `ReadPackage' call does *not* force the package to be
loaded.)

If the file is readable then `true' is returned, otherwise `false'.

Each of <name>, <file> and <pkg-file> should be a string.
The <name> argument is case insensitive.

`RereadPackage' does the same as `ReadPackage', except that also
read-only global variables are overwritten
(cf~"ref:Reread" in the {\GAP} Reference Manual).



\>TestPackageAvailability( <name>, <version> ) F
\>TestPackageAvailability( <name>, <version>, <intest> ) F

For strings <name> and <version>, `TestPackageAvailability' tests
whether the  {\GAP} package <name> is available for loading in a
version that is at least <version>, or equal to <version> if the first
character of <version> is `=',
see Section "ext:Version Numbers" of ``Extending GAP'' for details about
version numbers.

The result is `true' if the package is already loaded,
`fail' if it is not available,
and the string denoting the {\GAP} root path where the package resides
if it is available, but not yet loaded.
A test function (the value of the component `AvailabilityTest' in the
`PackageInfo.g' file of the package) should therefore test for the result
of `TestPackageAvailability' being not equal to `fail'.

The argument <name> is case insensitive.

The optional argument <intest> is a list of pairs
`[ <pkgnam>, <pkgversion> ]' such that the function has been called with
these arguments on outer levels.
(Note that several packages may require each other, with different
required versions.)



\>InstalledPackageVersion( <name> ) F

If the {\GAP} package with name <name> has already been loaded then
`InstalledPackageVersion' returns the string denoting the version number
of this version of the package.
If the package is available but has not yet been loaded then the version
number string for that version of the package that currently would be
loaded.
(Note that loading *another* package might force loading another version
of the package <name>, so the result of `InstalledPackageVersion' will be
different afterwards.)
If the package is not available then `fail' is returned.

The argument <name> is case insensitive.



\>DirectoriesPackageLibrary( <name>[, <path>] ) F

takes the string <name>, a name of a {\GAP} package and returns a list of
directory objects for those sub-directory/ies containing the library
functions of this {\GAP} package, for the version that is already loaded
or would be loaded if no other version is explicitly prescribed,
up to one directory for each `pkg' sub-directory of a path in
`GAPInfo.RootPaths'.
The default is that the library functions are in the subdirectory `lib'
of the {\GAP} package's home directory.
If this is not the case, then the second argument <path> needs to be
present and must be a string that is a path name relative to the home
directory  of the {\GAP} package with name <name>.

Note that `DirectoriesPackageLibrary' may be called in the
`AvailabilityTest' function in the package's `PackageInfo.g' file,
so we cannot guarantee that the returned directories belong to a version
that really can be loaded.



As an example, the following returns a directory object for the library
functions of the {\GAP} package `Example':

%notest
\beginexample
gap> DirectoriesPackageLibrary( "Example", "gap" );
[ dir("/home/werner/gap/4.0/pkg/example/gap/") ]
\endexample

Observe that we needed the second argument `"gap"' here, since `Example''s
library functions are in the sub-directory `gap' rather than `lib'.

In order to  find  a  subdirectory  deeper  than  one  level  in  a  package
directory, the second argument is again necessary whether or not the desired
subdirectory relative to the package's  directory  begins  with  `lib'.  The
directories in <path> should be separated by  `/'  (even  on  systems,  like
Windows, which use `\\' as the directory separator).  For  example,  suppose
there is a package `somepackage' with a subdirectory `m11' in the  directory
`data', then we might expect the following:

%notest
\beginexample
gap> DirectoriesPackageLibrary( "somepackage", "data/m11" );
[ dir("/home/werner/gap/4.0/pkg/somepackage/data/m11") ]
\endexample

\>DirectoriesPackagePrograms( <name> ) F

returns a list of the `bin/<architecture>' subdirectories of all
packages <name> where <architecture> is the architecture on which {\GAP}
has been compiled and the version of the installed package coincides with
the version of the package <name> that either is already loaded or that
would be the first version {\GAP} would try to load (if no other version
is explicitly prescribed).

Note that `DirectoriesPackagePrograms' is likely to be called in the
`AvailabilityTest' function in the package's `PackageInfo.g' file,
so we cannot guarantee that the returned directories belong to a version
that really can be loaded.

The directories returned by `DirectoriesPackagePrograms' are the place
where external binaries of the {\GAP} package <name> for the current
package version and the current architecture should be located.



%notest
\beginexample
gap> DirectoriesPackagePrograms( "nq" );
[ dir("/home/werner/gap/4.0/pkg/nq/bin/i686-unknown-linux2.0.30-gcc/") ]
\endexample

\>CompareVersionNumbers( <supplied>, <required> ) F
\>CompareVersionNumbers( <supplied>, <required>, \"equal\" ) F

compares two version numbers, given as strings. They are split at
non-digit characters, the resulting integer lists are compared
lexicographically.
The routine tests whether <supplied> is at least as large as <required>,
and returns `true' or `false' accordingly.
A version number ending in `dev' is considered to be infinite.
See Section~"ext:Version Numbers" of ``Extending GAP'' for details
about version numbers.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E