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 (http://www.gap-system.org) and in the extension manual 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.
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 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).
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 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:
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).
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.
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 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 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 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:
gap> DirectoriesPackageLibrary( "Example", "gap" );
[ dir("/home/werner/gap/4.0/pkg/example/gap/") ]
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:
gap> DirectoriesPackageLibrary( "somepackage", "data/m11" );
[ dir("/home/werner/gap/4.0/pkg/somepackage/data/m11") ]
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.
gap> DirectoriesPackagePrograms( "nq" );
[ dir("/home/werner/gap/4.0/pkg/nq/bin/i686-unknown-linux2.0.30-gcc/") ]
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 Version Numbers of ``Extending GAP'' for details
about version numbers.
[Top] [Up] [Previous] [Next] [Index]
GAP 4 manual
March 2006