<html><head><title>[ext] 4 Writing a GAP Package</title></head> <body text="#000000" bgcolor="#ffffff"> [<a href="../index.htm">Top</a>] [<a href = "chapters.htm">Up</a>] [<a href ="CHAP003.htm">Previous</a>] [<a href ="CHAP005.htm">Next</a>] [<a href = "theindex.htm">Index</a>] <h1>4 Writing a GAP Package</h1><p> <P> <H3>Sections</H3> <oL> <li> <A HREF="CHAP004.htm#SECT001">The Files of a GAP Package</a> <li> <A HREF="CHAP004.htm#SECT002">Writing Documentation</a> <li> <A HREF="CHAP004.htm#SECT003">An Example of a GAP Package</a> <li> <A HREF="CHAP004.htm#SECT004">The WWW Homepage of a Package</a> <li> <A HREF="CHAP004.htm#SECT005">The PackageInfo.g File</a> <li> <A HREF="CHAP004.htm#SECT006">Requesting one GAP Package from within Another</a> <li> <A HREF="CHAP004.htm#SECT007">Declaration and Implementation Part</a> <li> <A HREF="CHAP004.htm#SECT008">Standalone Programs in a GAP Package</a> <li> <A HREF="CHAP004.htm#SECT009">Installation of GAP Package Binaries</a> <li> <A HREF="CHAP004.htm#SECT010">Test for the Existence of GAP Package Binaries</a> <li> <A HREF="CHAP004.htm#SECT011">Calling of and Communication with External Binaries</a> <li> <A HREF="CHAP004.htm#SECT012">Package Completion</a> <li> <A HREF="CHAP004.htm#SECT013">DeclareAutoreadableVariables</a> <li> <A HREF="CHAP004.htm#SECT014">Version Numbers</a> <li> <A HREF="CHAP004.htm#SECT015">Wrapping Up a GAP Package</a> </ol><p> <p> This chapter explains the basics of how to write a <font face="Gill Sans,Helvetica,Arial">GAP</font> package so that it interfaces properly to <font face="Gill Sans,Helvetica,Arial">GAP</font>. For the role of <font face="Gill Sans,Helvetica,Arial">GAP</font> packages and the ways to load them, see Chapter <a href="../ref/CHAP074.htm">GAP Packages</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual. <p> There are two basic aspects of creating a <font face="Gill Sans,Helvetica,Arial">GAP</font> package. First, it is a convenient possibility to load additional functionality into <font face="Gill Sans,Helvetica,Arial">GAP</font> including a smooth integration of the package documentation. And secondly, a package is a way to make your code available to other <font face="Gill Sans,Helvetica,Arial">GAP</font> users. The <font face="Gill Sans,Helvetica,Arial">GAP</font> Team provides some help with the distribution of packages. In particular, a package can be submitted to a refereeing process. Check out the <font face="Gill Sans,Helvetica,Arial">GAP</font> Web pages <a href="http://www.gap-system.org">http://www.gap-system.org</a> for more details. <p> We start this chapter with a description how the directory structure of a <font face="Gill Sans,Helvetica,Arial">GAP</font> package must look like and then add remarks on certain aspects of creating a package, some of these only apply to some packages. <p> <p> <h2><a name="SECT001">4.1 The Files of a GAP Package</a></h2> <p><p> All files of a <font face="Gill Sans,Helvetica,Arial">GAP</font> package must be collected in a single directory. To use the package with <font face="Gill Sans,Helvetica,Arial">GAP</font> this directory must be a subdirectory of a <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> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual). (For example, if <font face="Gill Sans,Helvetica,Arial">GAP</font> is installed in <code>/usr/local/gap4</code> then put the files of your package <code>MyPack</code> in the directory <code>/usr/local/gap4/pkg/mypack</code>.) Let us call this directory the <strong>home directory</strong> of the package. <p> There are three file names with a special meaning in the home directory of a package: <code>PackageInfo.g</code> and <code>init.g</code> which must be present and <code>read.g</code> which is optional. <p> The file <code>PackageInfo.g</code> contains meta-information about the package (package name, version, author(s), relations to other packages, homepage, download archives, banner, ...). This is used by the package loading mechanism and also for the distribution of a package to other users. The content of this file is explained via a template file below (see <a href="CHAP004.htm#SECT005">The PackageInfo.g File</a>). <p> The <code>init.g</code> is read when the package is loaded (see <a href="../ref/CHAP074.htm#SSEC002.1">LoadPackage</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual). In principle this file could contain the whole <font face="Gill Sans,Helvetica,Arial">GAP</font> code of a package, but usually it contains mainly <code>Read</code> or <code>ReadPackage</code> statements for reading further files of the package. For many packages it may be useful to have declaration and implementation parts in different files, see <a href="CHAP004.htm#SECT007">Declaration and Implementation Part</a> below for more details. In that case it can be useful to read in only the declaration parts from the <code>init.g</code> file and to add <p> a file <code>read.g</code> which contains the <code>ReadPackage</code> statements for the implementation parts. <p> There is one further rule for the location of kernel library modules or external programs which is explained in <a href="CHAP004.htm#SECT009">Installation of GAP Package Binaries</a> below. <p> All other files can be organized as you like. But we suggest that you have a look at existing packages and use a similar scheme. For example, collect your <font face="Gill Sans,Helvetica,Arial">GAP</font> code in files in a subdirectory <code>lib</code> or <code>gap</code>, put the documentation in a subdirectory <code>doc</code>, put source code for compilation in <code>src</code>, data libraries in extra subdirectories and so on. <p> <p> <h2><a name="SECT002">4.2 Writing Documentation</a></h2> <p><p> <a name = "I0"></a> If you intend to make your package available to other users it is essential to include a documentation how to install and use your programs. <p> Concerning the installation you should produce a file <code>README</code> which gives a short description of the purpose of the package and contains proper instructions how to install your package. Again, check out some existing packages to get an idea how this could look like. <p> Concerning the documentation of the use of the package there are currently two recognised ways of producing <font face="Gill Sans,Helvetica,Arial">GAP</font> package documentation. There is the method that has been used to produce the main manuals for <font face="Gill Sans,Helvetica,Arial">GAP</font> which requires the documentation to be written in TeX according to the format described in Chapter <a href="CHAP002.htm">The gapmacro.tex Manual format</a>. There is also an XML-based documentation format that is defined in and can be used with the <font face="Gill Sans,Helvetica,Arial">GAPDoc</font> package (see <a href="badlink:GAPDoc:Introduction and Example">GAPDoc:Introduction and Example</a>). <p> In principle it is also possible to use some completely different documentation format. In that case you need to study the Chapter <a href="CHAP005.htm">Interface to the GAP Help System</a> to learn how to make your documentation available to the <font face="Gill Sans,Helvetica,Arial">GAP</font> help system. There should be at least a text version of your documenation provided for use in the terminal running <font face="Gill Sans,Helvetica,Arial">GAP</font> and some nicely printable version in <code>.dvi</code> and/or <code>.pdf</code> format. Many <font face="Gill Sans,Helvetica,Arial">GAP</font> users like to browse the documentation in HTML-format via their Web-browser. <p> <p> <h2><a name="SECT003">4.3 An Example of a GAP Package</a></h2> <p><p> We illustrate the creation of a <font face="Gill Sans,Helvetica,Arial">GAP</font> package by an example of a basic package. <p> Create the following directories in your home area: <code>pkg</code> and <code>pkg/test</code>. Inside the directory <code>test</code> create an empty file <code>init.g</code>, and a file <code>PackageInfo.g</code> with the following contents. <p> <pre> SetPackageInfo( rec( PackageName := "test", Version := "1.0", AvailabilityTest := ReturnTrue, Autoload := false, BannerString := Concatenation( [ "#I loading the GAP package ``test'' in version ", ~.Version, "\n" ] ), PackageDoc := rec( BookName := "test", SixFile := "doc/manual.six", Autoload := true ) ) ); </pre> <p> This file declares the <font face="Gill Sans,Helvetica,Arial">GAP</font> package with name ``test'' in version 1.0. There are no requirements that have to be tested, so <code>ReturnTrue</code> (see <a href="../ref/CHAP005.htm#SSEC003.1">ReturnTrue</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual) is used as test function. The package is not autoloaded, and it has its individual banner string. The package documentation consists of one autoloaded book; the <code>SixFile</code> component is needed by the <font face="Gill Sans,Helvetica,Arial">GAP</font> help system. <p> Now start <font face="Gill Sans,Helvetica,Arial">GAP</font> with the command <pre> gap -l "./;" </pre> <p> (the <code>-l "./;"</code> option adds the current directory to the <font face="Gill Sans,Helvetica,Arial">GAP</font> root directories and allows <font face="Gill Sans,Helvetica,Arial">GAP</font> to find the packages installed in the <code>./pkg</code> directory. <p> <pre> gap> LoadPackage("test"); #I loading the GAP package ``test'' in version 1.0 true </pre> <p> This <font face="Gill Sans,Helvetica,Arial">GAP</font> package is too simple to be useful, but we have succeeded in loading it via <code>LoadPackage</code>. <p> <p> <h2><a name="SECT004">4.4 The WWW Homepage of a Package</a></h2> <p><p> If you want to distribute your package you should create a WWW homepage containing some basic information, archives for download and the <code>README</code> file with installation instructions, and maybe a copy of the packages <code>PackageInfo.g</code> file. <p> The responsibility for this WWW homepage is with the package authors/maintainers. <p> If you tell us about your package (say, by mail to <code>support@gap-system.org</code>) we may agree to add a link to your package homepage from the <font face="Gill Sans,Helvetica,Arial">GAP</font> website and to redistribute the current version of your package via the <font face="Gill Sans,Helvetica,Arial">GAP</font> download sites. We can also provide some service for producing several archive formats from the archive you provide (e.g., you produce a <code>.tar.gz</code> version of your archive and we produce also a <code>.tar.bz2</code>, a <code>.zoo</code> and a <code>-win.zip</code> version from this). <p> Please, consider to submit your package to the <font face="Gill Sans,Helvetica,Arial">GAP</font> package refereeing process. <p> <p> <h2><a name="SECT005">4.5 The PackageInfo.g File</a></h2> <p><p> We suggest to create a <code>PackageInfo.g</code> file for your package by copying the one in the <code>Example</code> package, distributed with <font face="Gill Sans,Helvetica,Arial">GAP</font>, and to adjust it for your package. Within <font face="Gill Sans,Helvetica,Arial">GAP</font> you can look at that file by <p> <pre> Pager(StringFile(Filename(DirectoriesLibrary(), "../pkg/example/PackageInfo.g"))); </pre> <p> As a first step the example in <a href="CHAP004.htm#SECT003">An Example of a GAP Package</a> shows the information needed for the package loading mechanism of a simple package. If your package depends on the functionality of other packages, the component <code>Dependencies</code> given in the <code>PackageInfo.g</code> file becomes important, see <a href="CHAP004.htm#SECT006">Requesting one GAP Package from within Another</a> below. <p> The other entries become relevant if you want to distribute your package: they contain lists of authors and/or maintainers including contact information, URLs of the package archives and README files, status information, text for a package overview Web page, and so on. See the mentioned template file for a list and explanation of all recognized entries. <p> Once you have created the <code>PackageInfo.g</code> file for your package, you can test its validity with the command <code>ValidatePackageInfo(filename);</code>. <p> <p> <h2><a name="SECT006">4.6 Requesting one GAP Package from within Another</a></h2> <p><p> It is possible for one <font face="Gill Sans,Helvetica,Arial">GAP</font> package <code>A</code>, say, to require another package <code>B</code>. For that, one simply adds the name and the (least) version number of the package <code>B</code> to the <code>NeededOtherPackages</code> component of the <code>Dependencies</code> component of the <code>PackageInfo.g</code> file of the package <code>A</code>. In this situation, loading the package <code>A</code> forces that also the package <code>B</code> is loaded, and that <code>A</code> cannot be loaded if <code>B</code> is not available. <p> If <code>B</code> is not essential for <code>A</code> but should be loaded if it is available (for example because <code>B</code> provides some improvements of the main system that are useful for <code>A</code>) then the name and the (least) version number of <code>B</code> should be added to the <code>SuggestedOtherPackages</code> component of the <code>PackageInfo.g</code> file of <code>A</code>. In this situation, loading <code>A</code> forces an attempt to load also <code>B</code>, but <code>A</code> is loaded even if <code>B</code> is not available. <p> <p> <h2><a name="SECT007">4.7 Declaration and Implementation Part</a></h2> <p><p> <a name = "I1"></a> <a name = "I2"></a> When <font face="Gill Sans,Helvetica,Arial">GAP</font> packages require each other in a circular way, a ``bootstrapping'' problem arises of defining functions before they are called. The same problem occurs in the <font face="Gill Sans,Helvetica,Arial">GAP</font> library, it is resolved there by separating declarations (which define global variables such as filters and operations) and implementations (which install global functions and methods) in different files. Any implementation file may use global variables defined in any declaration file. <font face="Gill Sans,Helvetica,Arial">GAP</font> initially reads all declaration files (in the library they have a <code>.gd</code> suffix) and afterwards reads all implementation files (which have a <code>.gi</code> suffix). <p> Something similar is possible for <font face="Gill Sans,Helvetica,Arial">GAP</font> packages: If a file <code>read.g</code> exists in the home directory of the package, this file is read only <strong>after</strong> all the <code>init.g</code> files of all (implicitly) required <font face="Gill Sans,Helvetica,Arial">GAP</font> packages are read. Thus one can separate declaration and implementation for a <font face="Gill Sans,Helvetica,Arial">GAP</font> package in the same way as done for the <font face="Gill Sans,Helvetica,Arial">GAP</font> library, by creating a file <code>read.g</code>, restricting the <code>ReadPackage</code> statements in <code>init.g</code> to only load those files of the package that provide declarations, and to load the implementation files from <code>read.g</code>. <p> See Section <a href="../prg/CHAP003.htm#SECT018">Declaration and Implementation Part</a> in the Programmers' Tutorial which discusses further the commands that should appear in the declaration part (i.e., in the files read with <code>ReadPackage</code> from <code>init.g</code>) and in the implementation part (i.e., in the files read with <code>ReadPackage</code> from <code>read.g</code>) of a package. <p> <p> <h2><a name="SECT008">4.8 Standalone Programs in a GAP Package</a></h2> <p><p> <font face="Gill Sans,Helvetica,Arial">GAP</font> packages that involve stand-alone programs are fundamentally different from <font face="Gill Sans,Helvetica,Arial">GAP</font> packages that consist entirely of <font face="Gill Sans,Helvetica,Arial">GAP</font> code. <p> This difference is threefold: A user who installs the <font face="Gill Sans,Helvetica,Arial">GAP</font> package must also compile (or install) the package's binaries, the package must check whether the binaries are indeed available, and finally the <font face="Gill Sans,Helvetica,Arial">GAP</font> code of the package has to start the external binary and to communicate with it. We will treat these three points in the following sections. <p> If the package does not solely consist of an interface to an external binary and if the external program called is not just special-purpose code, but a generally available program, chances are high that sooner or later other <font face="Gill Sans,Helvetica,Arial">GAP</font> packages might also require this program. <p> We therefore strongly suggest to provide a documented <font face="Gill Sans,Helvetica,Arial">GAP</font> function that will call the external binary. We also suggest to create actually two <font face="Gill Sans,Helvetica,Arial">GAP</font> packages; the first providing only the binary and the interface and the second (requiring the first, see <a href="CHAP004.htm#SECT006">Requesting one GAP Package from within Another</a>) being the actual <font face="Gill Sans,Helvetica,Arial">GAP</font> package. <p> <p> <h2><a name="SECT009">4.9 Installation of GAP Package Binaries</a></h2> <p><p> The scheme for the installation of package binaries which is described further on is intended to permit the installation on different architectures which share a common file system (and share the architecture independent file). <p> A <font face="Gill Sans,Helvetica,Arial">GAP</font> package which includes external binaries contains a <code>bin</code> subdirectory. This subdirectory in turn contains subdirectories for the different architectures on which the <font face="Gill Sans,Helvetica,Arial">GAP</font> package binaries are installed. The names of these directories must be the same as the names of the architecture dependent subdirectories of the main <code>bin</code> directory. Unless you use a tool like <code>autoconf</code> yourself, you must obtain the correct name of the binary directory from the main <font face="Gill Sans,Helvetica,Arial">GAP</font> branch. To help with this, the main <font face="Gill Sans,Helvetica,Arial">GAP</font> directory contains a file <code>sysinfo.gap</code> which assigns the shell variable <code>GAParch</code> to the proper name as determined by <font face="Gill Sans,Helvetica,Arial">GAP</font>'s <code>configure</code> process. For example on a Linux system, the file <code>sysinfo.gap</code> may look like this: <p> <pre> GAParch=i586-unknown-linux2.0.31-gcc </pre> <p> We suggest that your <font face="Gill Sans,Helvetica,Arial">GAP</font> package contains a file <code>configure</code> which is called with the path of the <font face="Gill Sans,Helvetica,Arial">GAP</font> root directory as parameter. This file then will read <code>sysinfo.gap</code> and set up everything for compiling under the given architecture (for example creating a <code>Makefile</code> from <code>Makefile.in</code>. <p> The standard <font face="Gill Sans,Helvetica,Arial">GAP</font> distribution contains a <font face="Gill Sans,Helvetica,Arial">GAP</font> package ``example'' whose installation script shows an example way of how to do this. <p> <p> <h2><a name="SECT010">4.10 Test for the Existence of GAP Package Binaries</a></h2> <p><p> If an external binary is essential for the workings of a <font face="Gill Sans,Helvetica,Arial">GAP</font> package, the function stored in the component <code>AvailabilityTest</code> of the <code>PackageInfo.g</code> file of the package should test whether the program has been compiled on the architecture (and inhibit package loading if this is not the case). This is especially important if the package is loaded automatically. <p> The easiest way to accomplish this is to use <code>Filename</code> (see <a href="../ref/CHAP009.htm#SSEC004.1">Filename</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual) for checking for the actual binaries in the path given by <code>DirectoriesPackagePrograms</code> (see <a href="../ref/CHAP074.htm#SSEC003.5">DirectoriesPackagePrograms</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual) for the respective package. For example the ``example'' <font face="Gill Sans,Helvetica,Arial">GAP</font> package could use the following commands to test whether the binary <code>hello</code> has been compiled; they issue a warning if not and will only load if it is indeed available. <p> <pre> ... AvailabilityTest := function() local path,file; # test for existence of the compiled binary path:=DirectoriesPackagePrograms("example"); file:=Filename(path,"hello"); if file=fail then Info(InfoWarning,1, "Package ``example'': The program `hello' is not compiled"); Info(InfoWarning,1, "`HelloWorld()' is thus unavailable"); Info(InfoWarning,1, "See the installation instructions; ", "type: ?Installing the Example package"); fi; return file<>fail; end, ... </pre> <p> (In fact the <code>AvailabilityTest</code> function that is actually used in the ``example'' package always returns <code>true</code>, just the warnings are printed if the binary is not available. This means that the binary is not regarded as essential for this package.) <p> You might also have to cope with the situation that external binaries will only run under UNIX (and not, say on a Macintosh). See <a href="../ref/CHAP003.htm#SECT006">Testing for the System Architecture</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual for information on how to test for the architecture. <p> <p> <h2><a name="SECT011">4.11 Calling of and Communication with External Binaries</a></h2> <p><p> There are two reasons for this: the input data has to be passed on to the stand-alone program and the stand-alone program has to be started from within <font face="Gill Sans,Helvetica,Arial">GAP</font>. <p> There are two principal ways of doing this. <p> The first possibility is to write all the data for the stand-alone to one or several files, then start the stand-alone with <code>Process</code> or <code>Exec</code> (see <a href="../ref/CHAP011.htm#SSEC001.1">Process</a> and <a href="../ref/CHAP011.htm#SSEC002.1">Exec</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual) which then writes the output data to file, and finally read in the standalone's output file. <p> The second way is interfacing via iostreams (see Section <a href="../ref/CHAP010.htm#SECT008">Input-Output Streams</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual). The support for this is in its infancy. <p> <p> <h2><a name="SECT012">4.12 Package Completion</a></h2> <p><p> Reading a larger package can take a few moments and will take up user workspace. This might be a nuisance to users, especially if the package is loaded automatically. The same problem of course affects the <font face="Gill Sans,Helvetica,Arial">GAP</font> library, the problem there is solved using completion files (see <a href="../ref/CHAP003.htm#SECT005">Completion Files</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual). <p> Completion files make it possible to read only short function headers initially which are completed to full functions only when the functions are actually called. This section explains how to set up completion for a <font face="Gill Sans,Helvetica,Arial">GAP</font> package. <p> Completion works for those files which are read (using <code>ReadPackage</code>) from the <code>read.g</code> file. (This is no real restriction as completion affects only the implementation part.) To create completion files, load the <font face="Gill Sans,Helvetica,Arial">GAP</font> package, and then use the following command. <p> <a name = "SSEC012.1"></a> <li><code>CreateCompletionFilesPackage( </code><var>pkgname</var><code> )</code> <p> This will create a new file <code>read.co</code> in the home directory of the loaded version of the <font face="Gill Sans,Helvetica,Arial">GAP</font> package <var>pkgname</var> (so you must have write permissions there). When the <font face="Gill Sans,Helvetica,Arial">GAP</font> package is loaded, this file is used in place of <code>read.g</code>, and automatically takes care of completion. <p> When you change files which are completed, <font face="Gill Sans,Helvetica,Arial">GAP</font> will complain about non-matching CRC files and will not load them. In this case simply remove the <code>read.co</code> file and create it anew. <p> As a <font face="Gill Sans,Helvetica,Arial">GAP</font> package author you should consider including a completion file with the package. <p> If you start <font face="Gill Sans,Helvetica,Arial">GAP</font> with the command line option <code>-D</code>, it displays information about reading and completion, the command line option <code>-N</code> turns completion off (as if all <code>.co</code> files were erased). (Section <a href="../ref/CHAP003.htm#SECT002">Advanced Features of GAP</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual describes the options <code>-D</code> and <code>-N</code>.) <p> <p> <h2><a name="SECT013">4.13 DeclareAutoreadableVariables</a></h2> <p><p> Package files containing method installations must be read when the package is loaded. Note that the completion mechanism used in the main <font face="Gill Sans,Helvetica,Arial">GAP</font> library (see Section <a href="badlink:ext:Completion Files">Completion Files</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual) cannot be used for packages. <p> For package files <strong>not</strong> containing method installations --this applies to many data files-- another mechanism allows one to delay reading such files until the data are actually accessed. <p> <a name = "SSEC013.1"></a> <li><code>DeclareAutoreadableVariables( </code><var>pkgname</var><code>, </code><var>filename</var><code>, </code><var>varlist</var><code> )</code> <p> Let <var>pkgname</var> be the name of a package, let <var>filename</var> be the name of a file relative to the home directory of this package, and let <var>varlist</var> be a list of strings that are the names of global variables which get bound when the file is read. <code>DeclareAutoreadableVariables</code> notifies the names in <var>varlist</var> such that the first attempt to access one of the variables causes the file <var>filename</var> to be read. <p> <p> <h2><a name="SECT014">4.14 Version Numbers</a></h2> <p><p> <a name = "I3"></a> A version number is a string which contains nonnegative integers separated by non-numeric characters. Examples of valid version numbers are for example: <p> <pre> "1.0" "3.141.59" "2-7-8.3" "5 release 2 patchlevel 666" </pre> <p> Version numbers are interpreted as lists of integers and are compared in that way. Thus version <code>"2-3"</code> is larger than version <code>"2-2-5"</code> but smaller than <code>"11.0"</code>. <p> It is possible for code to require <font face="Gill Sans,Helvetica,Arial">GAP</font> packages in certain versions. In this case, all versions, whose number is equal or larger than the requested number are acceptable. It is the task of the package author to provide upwards compatibility. <p> Loading a specific version of a package (that is, <strong>not</strong> one with a larger version number) can be achieved by prepending <code>=</code> to the desired version number. For example, <code>LoadPackage( "example", "=1.0" )</code> will load version <code>"1.0"</code> of the package <a href="badlink:ext:example">example</a>, even if version <code>"1.1"</code> is avaiable. As a consequence, version numbers must not start with <code>=</code>, so <code>"=1.0"</code> is not a valid version number. <p> The global variable <code>GAPInfo.Version</code> contains the version number of the version of <font face="Gill Sans,Helvetica,Arial">GAP</font> and also can be checked against (using <code>CompareVersionNumbers</code>, see <a href="../ref/CHAP074.htm#SSEC003.6">CompareVersionNumbers</a> in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Reference Manual). <p> Package authors should choose a version numbering scheme that admits a new version number even after tiny changes to the package. The automatic update of package archives in the <font face="Gill Sans,Helvetica,Arial">GAP</font> distribution will only work if a package has a new version number. <p> <p> <h2><a name="SECT015">4.15 Wrapping Up a GAP Package</a></h2> <p><p> <a name = "I4"></a> The releases of <font face="Gill Sans,Helvetica,Arial">GAP</font> packages are independent of releases of <font face="Gill Sans,Helvetica,Arial">GAP</font>. Therefore <font face="Gill Sans,Helvetica,Arial">GAP</font> packages should be wrapped up in separate files that can be installed onto any version of <font face="Gill Sans,Helvetica,Arial">GAP</font>. Similarly a <font face="Gill Sans,Helvetica,Arial">GAP</font> package can be upgraded any time without the need to wait for new releases of <font face="Gill Sans,Helvetica,Arial">GAP</font>. <p> Because it is independent of the version of <font face="Gill Sans,Helvetica,Arial">GAP</font> a <font face="Gill Sans,Helvetica,Arial">GAP</font> package should be archived from the <font face="Gill Sans,Helvetica,Arial">GAP</font> <code>pkg</code> directory, that is all files are archived with the path starting the package's name. <p> <a name = "I5"></a> The archive of a <font face="Gill Sans,Helvetica,Arial">GAP</font> package should contain all files necessary for the package to work. In particular there should be a compiled documentation, which includes the <code>manual.six</code>, <code>manual.toc</code> and <code>manual.lab</code> file in the documentation subdirectory which are created by TeXing the documentation, if you use the <code>gapmacro.tex</code> or <font face="Gill Sans,Helvetica,Arial">GAPDoc</font> document formats. (The first two are needed by the <font face="Gill Sans,Helvetica,Arial">GAP</font> help system, and the <code>manual.lab</code> file is needed if the main manual is referring to your package. Use the command <code>GAPDocManualLab( packagename );</code> to create this file for your help books if you use <font face="Gill Sans,Helvetica,Arial">GAPDoc</font>.) <p> Currently, the <font face="Gill Sans,Helvetica,Arial">GAP</font> distribution provides archives in four different formats. <dl compact> <dt>-<dd><code>.tar.gz</code>, a standard UNIX <code>tar</code> archive, compressed with <code>gzip</code> <dt>-<dd><code>.tar.bz2</code>, a standard UNIX <code>tar</code> archive, compressed with <code>bzip2</code> <dt>-<dd><code>.zoo</code>, a special version of <code>zoo</code> archives, that can essentially be used on all operating systems with the <code>unzoo</code> utility provided with the <font face="Gill Sans,Helvetica,Arial">GAP</font> distribution <dt>-<dd><code>-win.zip</code>, an archive in <code>zip</code> format, where text files should have DOS/Windows style line breaks </dl> <p> For convenience of possible users it is sensible that you archive your package also in one or several of these formats. <p> For packages which are redistributed via the <font face="Gill Sans,Helvetica,Arial">GAP</font> Web site, we offer an automatic conversion of any of the formats listed above to all the others. <p> <p> [<a href="../index.htm">Top</a>] [<a href = "chapters.htm">Up</a>] [<a href ="CHAP003.htm">Previous</a>] [<a href ="CHAP005.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>