71 Share Packages

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

A share package extends the functionality of GAP as defined by the GAP kernel, the GAP library and the various data libraries. Some share 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 perfom tasks that are not available in GAP or work particularly fast.

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

A share 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. Share 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 share packages. Share packages that consist entirely of GAP code can be used on any platform where GAP runs. However, share packages that contain standalone programs often run only in a UNIX environment.

Sections

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

71.1 Installing Share Packages

Typically, a share package is installed by copying its directory (or unpacking its distribution file using unzoo) into the pkg directory of the GAP distribution. This subdirectory of pkg is called the home directory of the share package. 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. So share packages also provide an easy way to add optional components to the functionality of GAP.

If the share package uses external binaries, additional compilation is necessary. The documentation of each share 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 share package. Then call /bin/sh configure path, where path gives a path to the root directory of the GAP installation. So for example if the share package is in the main GAP path, simply call

/bin/sh configure ../..
This will fetch the name of the system architecture on which GAP has been compiled. Finally call make to invoke the actual compilation. (The standard GAP distribution contains a share package ``example'' which makes use of this mechanism. The configure script in this package also permits to omit the path, using ../.. as a default.)

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 share package binaries always immediately after compiling the system architecture. If you want to add share packages later, you should call configure again in the main GAP directory for each architecture before configuring the share package for this architecture.

71.2 Installing a Share Package in your home directory

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

If your administrator is absent/unwilling/incapable you still can install the share 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 share 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 (in GAP look at the variable GAP_ROOT_PATHS to find out where this is), so your commands would look something like:
you@unix> cd /home/user/mygap/pkg/thepackage
you@unix> configure /usr/local/lib/gap4r1
you@unix> make

Now the share package is installed locally. Finally, to use the package you only have to tell GAP to look in the right place. You can achieve this by giving two paths two 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/gap4r1;/home/user/mygap"

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

71.3 Loading a Share Package

Some share 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 share 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 ext:Version Numbers in ``Extending GAP''). 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 are available as other parts of the GAP library are.

    The documentation of each share package will tell if the package loads automatically or not. If share packages have been loaded automatically, GAP prints a list of the names of all share packages which have been loaded at the end of the initialization process.

    A share 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 share 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 share packages automatically which (for example for reasons of memory usage) you do not want to load automatically, you can disable the automatic loading of share packages by putting a line

    RemoveSet(AUTOLOAD_PACKAGES,"name");
    
    where name is the name of the share package in your .gaprc file (see The .gaprc file).

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

    71.4 Functions for Share Packages

  • DeclarePackage( name, version, tester ) F
  • DeclareAutoPackage( name, version, tester ) F

    This function may only occur within the init.g file of the share 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.)

  • DeclarePackageDocumentation( pkg, doc ) F
  • DeclarePackageAutoDocumentation( pkg, doc ) F

    This function indicates that the documentation of the share package pkg 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 share package.

  • ReadPkg( pkg, file ) F

    reads the file file of the share package pkg. file is given as a relative path to the directory of pkg.

  • TestPackageAvailability( name, version ) F

    tests, whether the share 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.

  • DirectoriesPackageLibrary( name[, path] ) F

    takes the name of a share package and locates the library functions of the share package. The default is that the library functions are in the subdirectory lib of the share package's home directory. If this is not the case, then the second argument needs to be present and specify a string that is a path name relative to the home directory of the share package.

    gap> DirectoriesPackageLibrary( "example", "gap" );  
    [ dir("/home/werner/Gap/4.0/pkg/example/gap/") ]
    

    In order to find a subdirectory hierarchy in the package directory you can pass subdirectories in lib separated by '/'. For example, to find the subdirectory m11 in the directory data, use:

    DirectoriesPackageLibrary( "pkgname", "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 share 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 . and - 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. See Section ext:Version Numbers of ``Extending GAP'' for details about version numbers.

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

    GAP 4 manual
    July 1999