GAP Packages
package
The functionality of &GAP; can be extended by loading &GAP; packages. &GAP; distribution already contains all currently redistributed with &GAP; packages in the &GAPDIRNAME;/pkg directory.

&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 &GAP; package `Example` (see http://www.gap-system.org/Packages/example.html). 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.

Installing a GAP Package

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.

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 . (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). Note that if you use Windows you may not be able to use some or all external binaries.
Loading a GAP Package
automatic loading of GAP packages
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 .

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

Functions for GAP Packages

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">

Kernel modules in &GAP; packages
gac
If the package has a kernel module, then it can be compiled using the `gac` 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.

To use the `gac` script to produce dynamically loadable modules, call it with the -d option, for example:

$ gap4/bin/i386-ibm-linux-gcc2/gac -d test.c

This will produce a file test.so, which then can be loaded into &GAP; with .

To load a compiled file, the command is used. This command loads filename as module. If given, the CRC checksum crc must match the value of the module (see ).

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);

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.
The PackageInfo.g File

Each package has the file PackageInfo.g 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.
<#Include Label="ValidatePackageInfo"> <#Include Label="ShowPackageVariables"> <#Include Label="BibEntry">