<html><head><title>[ref] 74 GAP Packages</title></head> <body text="#000000" bgcolor="#ffffff"> [<a href="../index.htm">Top</a>] [<a href = "chapters.htm">Up</a>] [<a href ="CHAP073.htm">Previous</a>] [<a href ="CHAP075.htm">Next</a>] [<a href = "theindex.htm">Index</a>] <h1>74 GAP Packages</h1><p> <P> <H3>Sections</H3> <oL> <li> <A HREF="CHAP074.htm#SECT001">Installing a GAP Package</a> <li> <A HREF="CHAP074.htm#SECT002">Loading a GAP Package</a> <li> <A HREF="CHAP074.htm#SECT003">Functions for GAP Packages</a> </ol><p> <p> <a name = "I0"></a> The functionality of <font face="Gill Sans,Helvetica,Arial">GAP</font> can be extended by loading <font face="Gill Sans,Helvetica,Arial">GAP</font> packages. Many packages are distributed together with the core system of <font face="Gill Sans,Helvetica,Arial">GAP</font> consisting of the <font face="Gill Sans,Helvetica,Arial">GAP</font> kernel, the <font face="Gill Sans,Helvetica,Arial">GAP</font> library and the various data libraries. <p> <font face="Gill Sans,Helvetica,Arial">GAP</font> packages are written by (groups of) <font face="Gill Sans,Helvetica,Arial">GAP</font> users which may not be members of the <font face="Gill Sans,Helvetica,Arial">GAP</font> developer team. The responsibility and copyright of a <font face="Gill Sans,Helvetica,Arial">GAP</font> package remains with the original author(s). <p> <font face="Gill Sans,Helvetica,Arial">GAP</font> packages have their own documentation which is smoothly integrated into the <font face="Gill Sans,Helvetica,Arial">GAP</font> help system. <p> All <font face="Gill Sans,Helvetica,Arial">GAP</font> users who develop new code are invited to share the results of their efforts with other <font face="Gill Sans,Helvetica,Arial">GAP</font> users by making the code and its documentation available in form of a package. Information how to do this is available from the <font face="Gill Sans,Helvetica,Arial">GAP</font> Web pages (<a href="http://www.gap-system.org">http://www.gap-system.org</a>) and in the extension manual <a href="../ext/CHAP004.htm">Writing a GAP Package</a>. There are possibilities to get a package distributed together with <font face="Gill Sans,Helvetica,Arial">GAP</font> and it is possible to submit a package to a formal refereeing process. <p> In this Chapter we describe how to use existing packages. <p> <p> <h2><a name="SECT001">74.1 Installing a GAP Package</a></h2> <p><p> Before a package can be used it must be installed. With a standard installation of <font face="Gill Sans,Helvetica,Arial">GAP</font> there should be quite a few packages already available. But since <font face="Gill Sans,Helvetica,Arial">GAP</font> packages are released independently of the main <font face="Gill Sans,Helvetica,Arial">GAP</font> system it may be sensible to upgrade or install new packages between upgrades of your <font face="Gill Sans,Helvetica,Arial">GAP</font> installation. <p> A package consists of a collection of files within a single directory that must be a subdirectory of the <code>pkg</code> directory in one of the <font face="Gill Sans,Helvetica,Arial">GAP</font> root directories, see <a href="../ref/CHAP009.htm#SECT002">GAP Root Directory</a>. (If you don't have access to the <code>pkg</code> directory in your main <font face="Gill Sans,Helvetica,Arial">GAP</font> installation you can add private root directories as explained in that section.) <p> Whenever you get from somewhere an archive of a <font face="Gill Sans,Helvetica,Arial">GAP</font> package it should be accompanied with a <code>README</code> file that explains its installation. Some packages just consist of <font face="Gill Sans,Helvetica,Arial">GAP</font> 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 <code>./configure; make</code> inside the unpacked package directory, but check the individual <code>README</code> files). <p> <p> <h2><a name="SECT002">74.2 Loading a GAP Package</a></h2> <p><p> <a name = "I1"></a> <a name = "I2"></a> Some <font face="Gill Sans,Helvetica,Arial">GAP</font> packages are prepared for <strong>automatic loading</strong>, that is they will be loaded automatically with <font face="Gill Sans,Helvetica,Arial">GAP</font>, others must in each case be separately loaded by a call to <code>LoadPackage</code>. <p> <a name = "SSEC002.1"></a> <li><code>LoadPackage( </code><var>name</var><code>[, </code><var>version</var><code>] ) F</code> <li><code>LoadPackage( </code><var>name</var><code>[, </code><var>version</var><code>, </code><var>banner</var><code>[, </code><var>outercalls</var><code>]] ) F</code> <p> loads the <font face="Gill Sans,Helvetica,Arial">GAP</font> package with name <var>name</var>. If the optional version string <var>version</var> is given, the package will only be loaded in a version number at least as large as <var>version</var>, or equal to <var>version</var> if its first character is <code>=</code> (see <a href="../ext/CHAP004.htm#SECT014">Version Numbers</a> in ``Extending GAP''). The argument <var>name</var> is case insensitive. <p> <code>LoadPackage</code> will return <code>true</code> if the package has been successfully loaded and will return <code>fail</code> 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. <p> If the package <var>name</var> has already been loaded in a version number at least or equal to <var>version</var>, respectively, <code>LoadPackage</code> returns <code>true</code> without doing anything else. <p> If the optional third argument <var>banner</var> is <code>false</code> then no package banner is printed. The fourth argument <var>outercalls</var> is used only for recursive calls of <code>LoadPackage</code>, when the loading process for a package triggers the loading of other packages. <p> After a package has been loaded its code and documentation should be available as other parts of the <font face="Gill Sans,Helvetica,Arial">GAP</font> library are. <p> The documentation of each <font face="Gill Sans,Helvetica,Arial">GAP</font> package will tell you if the package loads automatically or not. Also, <font face="Gill Sans,Helvetica,Arial">GAP</font> prints the list of names of all <font face="Gill Sans,Helvetica,Arial">GAP</font> packages which have been loaded (either by automatic loading or via <code>LoadPackage</code> commands in one's <code>.gaprc</code> file or the like) at the end of the initialization process. <p> A <font face="Gill Sans,Helvetica,Arial">GAP</font> package may also install only its documentation automatically but still need loading by <code>LoadPackage</code>. In this situation the online help displays <code>(not loaded)</code> in the header lines of the manual pages belonging to this <font face="Gill Sans,Helvetica,Arial">GAP</font> package. <p> If for some reason you don't want certain packages to be automatically loaded, <font face="Gill Sans,Helvetica,Arial">GAP</font> provides three levels for disabling autoloading: <p> <a name = "I3"></a> The autoloading of specific packages can be overwritten for the whole <font face="Gill Sans,Helvetica,Arial">GAP</font> installation by putting a file <code>NOAUTO</code> into a <code>pkg</code> directory that contains lines with the names of packages which should not be automatically loaded. <p> Furthermore, individual users can disable the autoloading of specific packages by using the following command in their <code>.gaprc</code> file (see <a href="CHAP003.htm#SECT004">The .gaprc file</a>). <p> <code>ExcludeFromAutoload( </code><var>pkgnames</var><code> );</code> <p> where <var>pkgnames</var> is the list of names of the <font face="Gill Sans,Helvetica,Arial">GAP</font> packages in question. <p> Using the <code>-A</code> command line option when starting up <font face="Gill Sans,Helvetica,Arial">GAP</font> (see <a href="CHAP003.htm#SECT001">Command Line Options</a>), automatic loading is switched off, and the scanning of the <code>pkg</code> directories containing the installed packages is delayed until the first call of <a href="CHAP074.htm#SSEC002.1">LoadPackage</a>. <p> <p> <h2><a name="SECT003">74.3 Functions for GAP Packages</a></h2> <p><p> The following functions are mainly used in files contained in a package and not by users of a package. <p> <a name = "SSEC003.1"></a> <li><code>ReadPackage( </code><var>name</var><code>, </code><var>file</var><code> ) F</code> <li><code>ReadPackage( </code><var>pkg-file</var><code> ) F</code> <a name = "SSEC003.1"></a> <li><code>RereadPackage( </code><var>name</var><code>, </code><var>file</var><code> ) F</code> <li><code>RereadPackage( </code><var>pkg-file</var><code> ) F</code> <p> In the first form, <code>ReadPackage</code> reads the file <var>file</var> of the <font face="Gill Sans,Helvetica,Arial">GAP</font> package <var>name</var>, where <var>file</var> is given as a path relative to the home directory of <var>name</var>. In the second form where only one argument <var>pkg-file</var> is given, this should be the path of a file relative to the <code>pkg</code> subdirectory of <font face="Gill Sans,Helvetica,Arial">GAP</font> root paths (see <a href="../ref/CHAP009.htm#SECT002">GAP Root Directory</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual). Note that in this case, the package name is assumed to be equal to the first part of <var>pkg-file</var>, <strong>so this form is not recommended</strong>. <p> 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 <code>TestPackageAvailability</code> (see <a href="CHAP074.htm#SSEC003.2">TestPackageAvailability</a>), without prescribed version number, is used. (Note that the <code>ReadPackage</code> call does <strong>not</strong> force the package to be loaded.) <p> If the file is readable then <code>true</code> is returned, otherwise <code>false</code>. <p> Each of <var>name</var>, <var>file</var> and <var>pkg-file</var> should be a string. The <var>name</var> argument is case insensitive. <p> <code>RereadPackage</code> does the same as <code>ReadPackage</code>, except that also read-only global variables are overwritten (cf <a href="../ref/CHAP009.htm#SSEC007.13">Reread</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual). <p> <a name = "SSEC003.2"></a> <li><code>TestPackageAvailability( </code><var>name</var><code>, </code><var>version</var><code> ) F</code> <li><code>TestPackageAvailability( </code><var>name</var><code>, </code><var>version</var><code>, </code><var>intest</var><code> ) F</code> <p> For strings <var>name</var> and <var>version</var>, <code>TestPackageAvailability</code> tests whether the <font face="Gill Sans,Helvetica,Arial">GAP</font> package <var>name</var> is available for loading in a version that is at least <var>version</var>, or equal to <var>version</var> if the first character of <var>version</var> is <code>=</code>, see Section <a href="../ext/CHAP004.htm#SECT014">Version Numbers</a> of ``Extending GAP'' for details about version numbers. <p> The result is <code>true</code> if the package is already loaded, <code>fail</code> if it is not available, and the string denoting the <font face="Gill Sans,Helvetica,Arial">GAP</font> root path where the package resides if it is available, but not yet loaded. A test function (the value of the component <code>AvailabilityTest</code> in the <code>PackageInfo.g</code> file of the package) should therefore test for the result of <code>TestPackageAvailability</code> being not equal to <code>fail</code>. <p> The argument <var>name</var> is case insensitive. <p> The optional argument <var>intest</var> is a list of pairs <code>[ </code><var>pkgnam</var><code>, </code><var>pkgversion</var><code> ]</code> 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.) <p> <a name = "SSEC003.3"></a> <li><code>InstalledPackageVersion( </code><var>name</var><code> ) F</code> <p> If the <font face="Gill Sans,Helvetica,Arial">GAP</font> package with name <var>name</var> has already been loaded then <code>InstalledPackageVersion</code> 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 <strong>another</strong> package might force loading another version of the package <var>name</var>, so the result of <code>InstalledPackageVersion</code> will be different afterwards.) If the package is not available then <code>fail</code> is returned. <p> The argument <var>name</var> is case insensitive. <p> <a name = "SSEC003.4"></a> <li><code>DirectoriesPackageLibrary( </code><var>name</var><code>[, </code><var>path</var><code>] ) F</code> <p> takes the string <var>name</var>, a name of a <font face="Gill Sans,Helvetica,Arial">GAP</font> package and returns a list of directory objects for those sub-directory/ies containing the library functions of this <font face="Gill Sans,Helvetica,Arial">GAP</font> 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 <code>pkg</code> sub-directory of a path in <code>GAPInfo.RootPaths</code>. The default is that the library functions are in the subdirectory <code>lib</code> of the <font face="Gill Sans,Helvetica,Arial">GAP</font> package's home directory. If this is not the case, then the second argument <var>path</var> needs to be present and must be a string that is a path name relative to the home directory of the <font face="Gill Sans,Helvetica,Arial">GAP</font> package with name <var>name</var>. <p> Note that <code>DirectoriesPackageLibrary</code> may be called in the <code>AvailabilityTest</code> function in the package's <code>PackageInfo.g</code> file, so we cannot guarantee that the returned directories belong to a version that really can be loaded. <p> As an example, the following returns a directory object for the library functions of the <font face="Gill Sans,Helvetica,Arial">GAP</font> package <code>Example</code>: <p> <pre> gap> DirectoriesPackageLibrary( "Example", "gap" ); [ dir("/home/werner/gap/4.0/pkg/example/gap/") ] </pre> <p> Observe that we needed the second argument <code>"gap"</code> here, since <code>Example</code>'s library functions are in the sub-directory <code>gap</code> rather than <code>lib</code>. <p> 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 <code>lib</code>. The directories in <var>path</var> should be separated by <code>/</code> (even on systems, like Windows, which use <code>\</code> as the directory separator). For example, suppose there is a package <code>somepackage</code> with a subdirectory <code>m11</code> in the directory <code>data</code>, then we might expect the following: <p> <pre> gap> DirectoriesPackageLibrary( "somepackage", "data/m11" ); [ dir("/home/werner/gap/4.0/pkg/somepackage/data/m11") ] </pre> <p> <a name = "SSEC003.5"></a> <li><code>DirectoriesPackagePrograms( </code><var>name</var><code> ) F</code> <p> returns a list of the <code>bin/</code><var>architecture</var><code></code> subdirectories of all packages <var>name</var> where <var>architecture</var> is the architecture on which <font face="Gill Sans,Helvetica,Arial">GAP</font> has been compiled and the version of the installed package coincides with the version of the package <var>name</var> that either is already loaded or that would be the first version <font face="Gill Sans,Helvetica,Arial">GAP</font> would try to load (if no other version is explicitly prescribed). <p> Note that <code>DirectoriesPackagePrograms</code> is likely to be called in the <code>AvailabilityTest</code> function in the package's <code>PackageInfo.g</code> file, so we cannot guarantee that the returned directories belong to a version that really can be loaded. <p> The directories returned by <code>DirectoriesPackagePrograms</code> are the place where external binaries of the <font face="Gill Sans,Helvetica,Arial">GAP</font> package <var>name</var> for the current package version and the current architecture should be located. <p> <pre> gap> DirectoriesPackagePrograms( "nq" ); [ dir("/home/werner/gap/4.0/pkg/nq/bin/i686-unknown-linux2.0.30-gcc/") ] </pre> <p> <a name = "SSEC003.6"></a> <li><code>CompareVersionNumbers( </code><var>supplied</var><code>, </code><var>required</var><code> ) F</code> <li><code>CompareVersionNumbers( </code><var>supplied</var><code>, </code><var>required</var><code>, "equal" ) F</code> <p> 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 <var>supplied</var> is at least as large as <var>required</var>, and returns <code>true</code> or <code>false</code> accordingly. A version number ending in <code>dev</code> is considered to be infinite. See Section <a href="../ext/CHAP004.htm#SECT014">Version Numbers</a> of ``Extending GAP'' for details about version numbers. <p> <p> [<a href="../index.htm">Top</a>] [<a href = "chapters.htm">Up</a>] [<a href ="CHAP073.htm">Previous</a>] [<a href ="CHAP075.htm">Next</a>] [<a href = "theindex.htm">Index</a>] <P> <font face="Gill Sans,Helvetica,Arial">GAP 4 manual<br>December 2008 </font></body></html>