[Top] [Up] [Previous] [Next] [Index]

# 74 GAP Packages

### Sections

1. Installing a GAP Package
2. Loading a GAP Package
3. Functions for GAP Packages

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.

## 74.1 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 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).

## 74.2 Loading a GAP Package

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.

  ## 74.3 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 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
  September 2006