[ref] 74 GAP Packages

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

# 74 GAP Packages

### Sections

1. Installing GAP Packages
2. Installing a GAP Package in your home directory
3. Loading a GAP Package
4. Functions for GAP Packages

A GAP package is the way to make software written by (groups of) GAP users available to the computational community together with GAP.

A GAP package extends the functionality of GAP as defined by the GAP kernel, the GAP library and the various data libraries. Some GAP packages are written entirely in the GAP language, while others include one or more standalone programs written in C or some other language which either perform tasks that are not available in GAP or work particularly fast.

The responsibility and copyright of a GAP package remains with the original author while the responsibility of the rest of GAP lies with the GAP developer team.

A GAP package undergoes a formal refereeing process before it becomes part of the GAP distribution. This process is in many ways similar to the refereeing process of a paper submitted to a journal. It assesses the quality and usefulness of the submitted package, it makes sure that it can be started and runs smoothly together with GAP and it ensures that binary parts are portable to other architectures. GAP packages should be submitted to the chairman of the GAP Council, Prof. Charles Wright. See the GAP Web site (see Getting GAP) for more details and addresses.

While much effort has been spent on making GAP available on as many platforms as possible, the same is not always true for GAP packages. GAP packages that consist entirely of GAP code can be used on any platform where GAP runs. However, GAP packages that contain standalone programs often run only in a UNIX environment.

## 74.1 Installing GAP Packages

Typically, a GAP package is installed by copying its directory (or unpacking its distribution file using `unzoo`) into the `pkg` directory of the GAP distribution. The files `accpkg4r3.zoo` and `deppkg4r3.zoo` each contain several GAP packages, but each package can also be obtained individually from each of the GAP web sites; just follow the links from the `GAP Packages` link. The easiest procedure is to change directory to the `pkg` directory; then download or move the ``package`.zoo` file to that directory and do:

`unzoo` package`.zoo`

This typically creates a subdirectory package (or several subdirectories in the case of the omnibus archives: `accpkg4r3.zoo` and `deppkg4r3.zoo`) in the directory `pkg`. Such subdirectories of `pkg` are called the home directories for these GAP packages. It is possible to have several GAP root directories (see GAP Root Directory); therefore it is easy to install a package locally even if a user has no permission to add files to the main GAP installation. Thus, GAP packages also provide an easy way to add optional components to the functionality of GAP.

If the GAP package uses external binaries, additional compilation is necessary. The documentation of each GAP package will describe how to do this, the following paragraph describes a suggested procedure for compiling binaries on a UNIX system:

Go to the directory of the GAP package, i.e. for package package do:

`cd` package``

Then call:

`./configure` path``

where path is the path to the root directory of the GAP installation. So for example if the GAP package is in the main GAP path, simply call

    ./configure ../..

This will fetch the name of the system architecture on which GAP has been compiled. Finally call:

    make

to invoke the actual compilation. You should check the package's `README` in case there are any departures from this procedure.

The standard GAP distribution contains a GAP package `example` which makes use of a default path mechanism. The `configure` script in this package permits one to omit the path, using `../..` as a default.

Note: If GAP is installed on different architectures on a common file system, this configuration process will only work for the last architecture for which GAP was compiled. Therefore compile the GAP package binaries always immediately after compiling the system architecture. If you want to add GAP packages later, you should call `configure` again in the main GAP directory for each architecture before configuring the GAP package for this architecture.

## 74.2 Installing a GAP Package in your home directory

If you are using GAP on a multi-user system installing a GAP package globally in the way described in the last section might require the cooperation of your system administrator.

If your administrator is absent/unwilling/incapable you can still install the GAP package in your local home directory: Create a directory that will serve as ``your'' personal GAP home directory. We will assume now that you are using a UNIX system and that this directory is called

    /home/user/mygap

Go to this directory and create a subdirectory `pkg`

    you@unix> cd /home/user/mygap
    you@unix> mkdir pkg

Now extract the GAP package in the `pkg` subdirectory, creating a directory with the package name. Configure the package as usual. However you now have to give the correct path to the main GAP home directory (start up GAP and look at the variable `GAP_ROOT_PATHS` to find out where this is, e.g.

    gap> GAP_ROOT_PATHS;
    [ "/usr/local/lib/gap4r3/" ]

indicates that the main GAP directory is `/usr/local/lib/gap4r3/`), so your commands would look something like:

    you@unix> cd /home/user/mygap/pkg/thepackage
    you@unix> ./configure /usr/local/lib/gap4r3
    you@unix> make

Now the GAP package is installed locally. Finally, to use the package you only need to tell GAP to look in the right place. You can achieve this by giving two paths to home directories, the old one and your new one, separated by a semicolon as arguments to the `-l` command line option to your usual `gap4` command. (See Command Line Options for details.)

    you@unix> gap4 -l "/usr/local/lib/gap4r3;/home/user/mygap"

Now GAP starts as usual, and the new package ought to be available.

Of course, it may be a little tedious to type this each time, and you may be tempted to create an alias and put this in your `.cshrc` (or `.bashrc` or whatever) file. In general, this is not the best solution. It is far better to create a shell script (let's call it `mygap`), put this script into your private `bin` directory and add that `bin` directory to your path. The easy way to create `mygap` is to copy the one that runs your `gap4` (it better be a script! ... if not tell your administrator to read Section Installation of GAP for UNIX), e.g.

    you@unix> mkdir /home/user/bin
    you@unix> cd /home/user/bin
    you@unix> which gap4
    /usr/local/bin/gap4
    you@unix> cp /usr/local/bin/gap4 mygap

(If you already have a `bin` directory you can, of course, skip the first step).

Now edit the `-l` part of the last line of `mygap` which should initially look something like:

    exec $GAP_DIR/bin/$GAP_PRG -m $GAP_MEM -o 970m -l $GAP_DIR $*

so that it becomes:

    exec $GAP_DIR/bin/$GAP_PRG -m $GAP_MEM -o 970m -l "$GAP_DIR;/home/user/mygap" $*

Then to start `gap4` with your locally installed package you only need to type `mygap`.

For the GAP package ANUPQ the above strategy is actually necessary if one wants to run the binary as a stand-alone; when computing stabilisers it needs to call a GAP that knows where the packages ANUPQ and AutPGrp are installed. So, take the hint, always use an appropriate script when running GAP; don't use aliases. (Most of the time aliases work ok; but when that approach doesn't work you will be left puzzling!!)

## 74.3 Loading a GAP Package

Some GAP packages will be 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 `RequirePackage`.

- `RequirePackage(` name`, [`version`] ) F`

  loads the GAP package 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 (see Version Numbers in ``Extending GAP''). The argument name is case insensitive.

  `RequirePackage` 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 available version is too small. If the package name has already been loaded in a version number at least version, `RequirePackage` returns `true` without doing anything.

  After a package has been loaded its code and documentation should be available as other parts of the GAP library are. Each package has a `doc` directory containing the package's documentation; generally this contains `.tex` files, and `manual.dvi` and `manual.six` files. Some packages have an `htm` directory containing an HTML version of the manual. If the documentation was produced using GAPDoc there will be `.txt` files (plain text files that are read by GAP when one types `?`topic`` commands) and `.html` files (which contains the HTML version of the manual) as well as `manual.dvi` (the TeX `.dvi` version of the manual), all in the package's `doc` directory. In any case, the `manual.six` file must be present to enable GAP's on-line help to display a GAP package's documentation by reading from either the package's `.txt` or `.tex` files; if it is not check the package's `README` for instructions on how to obtain it.

  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 `RequirePackage` 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 `RequirePackage`. In this situation the online help displays `(not loaded)` in the header lines of the manual pages belonging to this GAP package.

  (At the moment automatic loading is only possible for the packages listed in the file `pkg/ALLPKG`. (This is due to the fact that there is no standard C-Function that will list the contents of a subdirectory.) This file must list each package name on a line of its own without any heading or trailing extra characters. Under UNIX you can create such a file easily by issuing the command

      find * -type d -maxdepth 0 -print > ALLPKG

  in the `pkg` directory.)

  If the GAP installation you are using loads GAP packages automatically which (for example for reasons of memory usage) you do not want to load automatically, you can disable the automatic loading of GAP packages by putting a line

  `RemoveSet(AUTOLOAD_PACKAGES, "`name`");`

  where name is the name of the GAP package, in your `.gaprc` file (see The .gaprc file).

  You can disable automatic loading globally, by listing the name of the GAP package in a file `NOAUTO` in the `pkg` directory.

  ## 74.4 Functions for GAP Packages

- `DeclarePackage(` name`,` version`,` tester`) F`
- `DeclareAutoPackage(` name`,` version`,` tester`) F`

  This function may only occur within the `init.g` file of the GAP package name. It prepares the installation of the package name, which will be installed in version version. The third argument tester is a function which tests for necessary conditions for the package to be loadable, like the availability of other packages (using `TestPackageAvailability`, see TestPackageAvailability) or -- if necessary -- the existence of compiled binaries. It should return `true` only if all conditions are fulfilled (and `false` or `fail` otherwise). If it does not return `true`, the package will not be loaded, and the documentation will not be available. The second version `DeclareAutoPackage` declares the package and enables automatic loading when GAP is started. (Because potentially all installed packages are automatically loaded, the tester function should take little time.)

  The argument name is case sensitive. But note that the package name is internally converted to a lower case string; so, there cannot be different packages with names which are only distinguished by case.

  The difference between the `Auto` and the other version is that in case of IS_IN_AUTOLOAD the component PACKAGES_VERSIONS.(lname) is bound only with the `Auto` version. This leads to different behaviour in `RequirePackage` when it asks for package availability.

- `DeclarePackageDocumentation(` name`,` doc`[,` short`[,` long`] ] ) F`
- `DeclarePackageAutoDocumentation(` name`,` doc`[,` short`[,` long`] ] ) F`

  This function indicates that the documentation of the GAP package name can be found in its doc subdirectory. The second version will enable that the documentation is loaded automatically when GAP starts, even if the package itself will not be loaded.

  Both functions may only occur within the `init.g` file of a GAP package.

  The string name is case insensitive (but internally converted to lower case, e.g., for the directory name of the package).

  There are two optional arguments: short is a short string which is used as identifying name of the book in GAP's online help. And long is a short description of the book. This is shown with the `?books` query, so short and long together should easily fit on a line.

  If short and long are not given, the default values name for short and `GAP Package ``name``' for long are used.

- `ReadPkg(` name`,` file`) F`

  reads the file file of the GAP package name, where file is given as a relative path to the directory of name. The name argument is case insensitive.

- `TestPackageAvailability(` name`,` version`) F`

  tests, whether the GAP package name is available for loading in a version that is at least version. It returns `true` if the package is already loaded, `fail` if it is not available, and the directory path to the package if it is available, but not yet loaded. A test function (the third parameter to `DeclarePackage`) should therefore test for the result of `TestPackageAvailability` being not equal to `fail`. The argument name is case insensitive.

- `InstalledPackageVersion(` name`) F`

  returns the version number string of the package name if it is installed and `fail` otherwise. The name argument 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 the sub-directory/ies containing the library functions of the GAP package, up to one for each `pkg` sub-directory of a path in `GAP_ROOT_PATHS`. 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.

  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. The directories returned by `DirectoriesPackagePrograms` is 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/") ]

- `CompareVersionNumbers(` supplied`,` required`) F`

  compares two version numbers, given as strings. They are split at non-number 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
  May 2002