[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 acceptedpkg4r3.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: acceptedpkg4r3.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