Sophie

Sophie

distrib > Mandriva > 2010.0 > i586 > media > contrib-release > by-pkgid > 5e1854624d3bc613bdd0dd13d1ef9ac7 > files > 30

gap-system-4.4.12-5mdv2010.0.i586.rpm

<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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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&gt; 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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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&lt;&gt;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&nbsp;<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&nbsp;<a href="../ref/CHAP011.htm#SSEC001.1">Process</a>  and&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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>