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
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
] ) F
]] ) 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,
true without doing anything else.
If the optional third argument banner is
false then no package banner
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
(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
that contains lines with the names of packages which should not be
Furthermore, individual users can disable the autoloading of specific
packages by using the following command in their
(see The .gaprc file).
where pkgnames is the list of names of the GAP packages in question.
-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.
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
TestPackageAvailability (see TestPackageAvailability), without
prescribed version number, is used.
(Note that the
ReadPackage call does not force the package to be
If the file is readable then
true is returned, otherwise
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).
For strings name and version,
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
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
TestPackageAvailability being not equal to
The argument name is case insensitive.
The optional argument intest is a list of pairs
] such that the function has been called with
these arguments on outer levels.
(Note that several packages may require each other, with different
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
(Note that loading another package might force loading another version
of the package name, so the result of
InstalledPackageVersion will be
If the package is not available then
fail is returned.
The argument name is case insensitive.
] ) F
takes the string name, a name of a GAP package and returns a list of
directory objects for the sub-directory/ies containing the library
functions of this GAP package,
up to one for each
pkg sub-directory of a path in
The default is that the library functions are in the subdirectory
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.
As an example, the following returns a directory object for the library
functions of the GAP package
gap> DirectoriesPackageLibrary( "Example", "gap" ); [ dir("/home/werner/gap/4.0/pkg/example/gap/") ]
Observe that we needed the second argument
"gap" here, since
library functions are in the sub-directory
gap rather than
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
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") ]
returns a list of the
subdirectories of all
packages name where architecture is the architecture on which GAP
has been compiled.
The directories returned by
DirectoriesPackagePrograms are the place
where external binaries for the GAP package name 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/") ]
, "equal" ) F
compares two version numbers, given as strings. They are split at
non-digit characters, the resulting integer lists are compared
The routine tests whether supplied is at least as large as required,
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