<Chapter Label="Using and Developing GAP Packages">
<Heading>Using and Developing &GAP; Packages</Heading>

<Index>package</Index>
The  functionality  of  &GAP;  can  be  extended  by  loading  &GAP;
packages.
The &GAP; distribution already contains all currently redistributed
&GAP; packages in the <F>&GAPDIRNAME;/pkg</F> directory.
<P/>
&GAP; packages are written by (groups of) &GAP; users who may not
necessarily be  members of the  &GAP; developer team.
The responsibility and copyright of a &GAP; package remains
with the original author(s).
<P/>
&GAP;  packages  have  their  own  documentation  which  is  smoothly
integrated into the &GAP; help system.
(When &GAP; is started, <C>LoadPackageDocumentation</C> is called
for all packages.)
<P/>
All  &GAP;  users   who  develop  new  code  are   invited  to  share
the  results  of their  efforts  with  other  &GAP; users  by  making
the  code  and its  documentation  available  in  form of  a  package.
Guidance on how  to do  this is  available from  the &GAP; website
(<URL>https://www.gap-system.org</URL>)
and in the &GAP; package <Package>Example</Package>
(see <URL>https://www.gap-system.org/Packages/example.html</URL>).
<P/>
The &GAP; development team will assist in making any new package
suitable for distribution with &GAP;.
It is also possible to submit a package to a formal refereeing process.
<P/>
In this chapter we first describe how to use existing packages,
and then provide guidelines for writing a &GAP; package.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Installing a GAP Package">
<Heading>Installing a &GAP; Package</Heading>

Before a  package can be  used it must  be installed.
A standard distribution of &GAP; already contains all the packages
currently redistributed with &GAP;.
This set of packages has been checked for compatibility
with the system and with each other during release preparation.
Most of the packages can be used immediately, but some of them may require further installation steps (see below).
<P/>
Also, since &GAP; packages are released independently of the main &GAP; system,
it may sometimes be useful to upgrade or install new packages between
upgrades of your &GAP; installation, e.g. if a new version of a package adds
new capabilities or bug fixes that you need.
<P/>
A package consists of a collection  of files within a single directory
that must  be a subdirectory of  the <F>pkg</F>  directory   in one  of the
&GAP; root directories (see <Ref Sect="GAP Root Directories"/>).
If you don't have access  to the <F>pkg</F>  directory in your main  &GAP; installation you can add private root directories as explained in section
<Ref Sect="GAP Root Directories"/>.
<P/>
Whenever you download or clone an archive of a &GAP; package,
it will contain a <F>README</F> file (or <F>README.md</F> etc.)
that explains how it should be installed.
Some packages just consist of &GAP; 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,
such as compilation or installing additional software
to satisfy their dependencies.
If there are some  external programs which have to be compiled,
this is often done by executing <C>./configure; make</C>
inside the unpacked package directory
(but check the individual <F>README</F> files).
<P/>
Most of the packages that require compilation can be compiled
in a single step by changing to the <F>pkg</F> directory of your &GAP;
installation and calling the <C>../bin/BuildPackages.sh</C> script.
<P/>
Note that if you use Windows you may not be able to use some or all
external binaries.
</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Loading a GAP Package">
<Heading>Loading a &GAP; Package</Heading>

If a package is not already loaded, it may be loaded using
the function <Ref Func="LoadPackage"/>.
<P/>
Some &GAP; packages are prepared for automatic loading,
that is they will be loaded automatically when &GAP; starts
(see <Ref Subsect="LoadPackageAutomatic"/>).

<#Include Label="LoadPackage">

<Index Key="automatic loading of GAP packages">automatic loading of &GAP; packages</Index>
<Index>disable automatic loading</Index>
<#Include Label="LoadPackageAutomatic">

<#Include Label="SetPackagePath">
<#Include Label="ExtendRootDirectories">
<#Include Label="ExtendPackageDirectories">
<#Include Label="DisplayPackageLoadingLog">

</Section>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Functions for GAP Packages">
<Heading>Functions for &GAP; Packages</Heading>

The following functions are mainly used in files contained in  a
package and not by users of a package. They are needed to organise
reading package files into &GAP; in the right order, performing
maintenance tasks like building documentation and running package
tests, checking package dependencies, etc.
You will find further information about their use in Section
<Ref Sect="Guidelines for Writing a GAP Package"/> and subsequent sections.

<#Include Label="ReadPackage">
<#Include Label="TestPackageAvailability">
<#Include Label="IsPackageLoaded">
<#Include Label="IsPackageMarkedForLoading">
<#Include Label="TestPackage">
<#Include Label="InstalledPackageVersion">
<#Include Label="DirectoriesPackageLibrary">
<#Include Label="DirectoriesPackagePrograms">
<#Include Label="CompareVersionNumbers">
<#Include Label="DeclareAutoreadableVariables">

<Subsection Label="Kernel modules">
<Heading>Kernel modules in &GAP; packages</Heading>

<Index Key="gac"><C>gac</C></Index>
If the package has a kernel module, then it can be compiled using the
<Package>gac</Package> script. A kernel module is implemented in C
and follows certain conventions to comply with the &GAP; kernel interface,
which we plan to document later. In the meantime, we advice to get in touch
with &GAP; developers if you plan to develop such a package.
<P/>
To use the <Package>gac</Package> script to produce dynamically loadable
modules, call it with the <C>-d</C> option, for example:
<P/>
<Log><![CDATA[
$ gap4/gac -d test.c
]]></Log>
<P/>
This will produce a file <F>test.so</F>, which then can be loaded into &GAP;
with <Ref Func="LoadKernelExtension"/>. If the kernel module is required
for the package to work, then its <F>PackageInfo.g</F> should define
a <C>AvailabilityTest</C> which calls <Ref Func="IsKernelExtensionAvailable"/>,
see <Ref Subsect="Test for the Existence of GAP Package Binaries"/> for details.
<P/>
Note that before &GAP; 4.12, <Ref Func="LoadDynamicModule"/> was used for this.
It is still available and in fact <Ref Func="LoadKernelExtension"/> call it;
but the latter provides a higher level abstraction and is more convenient to use.

</Subsection>

<#Include Label="IsKernelExtensionAvailable">
<#Include Label="LoadKernelExtension">
<#Include Label="LoadDynamicModule">

<Subsection Label="The PackageInfo.g File">
<Heading>The PackageInfo.g File</Heading>

Each package has the file <F>PackageInfo.g</F> which
contains meta-information about  the package
(package  name,  version,  author(s),  relations  to  other  packages,
homepage, download archives, etc.).
This file is used by the package loading mechanism,
by the &GAP; webpages about packages,
and also for the redistribution of a package with &GAP;.

<P/>

A <F>PackageInfo.g</F> file contains a call to the function
<C>SetPackageInfo</C>, with argument a record.
The following components of this record are <E>mandatory</E>.

<List>
<Mark><C>PackageName</C></Mark>
<Item>
  a nonempty string denoting the name of the package,
</Item>
<Mark><C>Subtitle</C></Mark>
<Item>
  a string that describes the package's contents,
  may be used by a default banner or on a web page,
  should fit on one line,
</Item>
<Mark><C>Version</C></Mark>
<Item>
  a nonempty string that does not start with <C>=</C>,
  denoting the version number of the package
  (see Section <Ref Sect="Version Numbers"/>),
</Item>
<Mark><C>Date</C></Mark>
<Item>
  a string of the form <C>yyyy-mm-dd</C>
  <!-- the recommended format; a currently still supported format
       that is expected to become deprecated is dd/mm/yyyy -->
  denoting the release date of the current version of the package
  (a date since 1999, when &GAP;&nbsp;4 appeared),
</Item>
<Mark><C>License</C></Mark>
<Item>
  a nonempty string containing an SPDX ID
  (see Section <Ref Sect="Selecting a license for a GAP Package"/>),
</Item>
<Mark><C>ArchiveURL</C></Mark>
<Item>
  a string started with <C>http://</C>, <C>https://</C>, or <C>ftp://</C>,
  denoting an URL from where the current package archive can be downloaded,
  but without the suffix describing the format
  (see the <C>ArchiveFormats</C> component),
</Item>
<Mark><C>ArchiveFormats</C></Mark>
<Item>
  a string that lists the supported formats (among <C>.tar.gz</C>,
  <C>.tar.bz2</C>, <C>-win.zip</C>), separated by whitespace or commas,
</Item>
<Mark><C>README_URL</C></Mark>
<Item>
  a string started with <C>http://</C>, <C>https://</C>, or <C>ftp://</C>,
  denoting an URL from where the current <F>README.md</F> or <F>README</F>
  file of the package can be downloaded,
</Item>
<Mark><C>PackageInfoURL</C></Mark>
<Item>
  a string started with <C>http://</C>, <C>https://</C>, or <C>ftp://</C>,
  denoting an URL from where the current <F>PackageInfo.g</F> file of the
  package can be downloaded,
</Item>
<Mark><C>AbstractHTML</C></Mark>
<Item>
  a string that describes the package's contents in a few lines,
  in HTML format; this text will be displayed on the package overview
  web page of &GAP;,
</Item>
<Mark><C>PackageWWWHome</C></Mark>
<Item>
  a string started with <C>http://</C>, <C>https://</C>, or <C>ftp://</C>,
  denoting the address of the package's home page,
</Item>
<Mark><C>PackageDoc</C></Mark>
<Item>
  a record or a list of records; each record describes a book of the package
  documentation, with the following components
  <List>
  <Mark><C>BookName</C></Mark>
  <Item>
    a string, the name of the book,
  </Item>
  <Mark><C>LongTitle</C></Mark>
  <Item>
    a string shown by <C>?books</C>,
  </Item>
  <Mark><C>SixFile</C></Mark>
  <Item>
    a string denoting a relative path to the <F>manual.six</F>
    file of the book,
  </Item>
  <Mark><C>HTMLStart</C></Mark>
  <Item>
    a string denoting a relative path to the start file of
    the HTML version of the book,
  </Item>
  <Mark><C>PDFFile</C></Mark>
  <Item>
    a string denoting a relative path to the <F>.pdf</F> file of the book,
  </Item>
  <Mark><C>ArchiveURLSubset</C></Mark>
  <Item>
    a list of strings denoting relative paths to those
    files and directories from the archive that are needed for the online
    manual; typically, <C>[ "doc" ]</C> suffices,
  </Item>
  </List>
</Item>
</List>

The following components of the record are <E>optional</E>.

<List>
<Mark><C>TextFiles</C> or <C>BinaryFiles</C> or <C>TextBinaryFilesPatterns</C></Mark>
<Item>
  a list of strings that specify which files in the archive are text files
  or binary files (at most one of the three components can be available,
  each string in <C>TextBinaryFilesPatterns</C> must start with <C>T</C>
  for text files and by <C>B</C> for binary files),
</Item>
<Mark><C>Persons</C></Mark>
<Item>
  a list of records, each with the mandatory components
  <List>
  <Mark><C>LastName</C></Mark>
  <Item>
    a string,
  </Item>
  <Mark>at least one of <C>IsAuthor</C> or <C>IsMaintainer</C></Mark>
  <Item>
    <K>true</K> or <K>false</K>,
  </Item>
  </List>
  and optional components
  <List>
  <Mark><C>FirstNames</C></Mark>
  <Item>
    a string (was mandatory before &GAP; 4.14),
  </Item>
  <Mark><C>Place</C></Mark>
  <Item>
    a string,
  </Item>
  <Mark><C>Institution</C></Mark>
  <Item>
    a string,
  </Item>
  </List>
  If the <C>IsMaintainer</C> value is <K>true</K> then also one of the
  following components is mandatory, otherwise these components are optional.
  <List>
  <Mark><C>Email</C></Mark>
  <Item>
    a string,
  </Item>
  <Mark><C>WWWHome</C></Mark>
  <Item>
    a string denoting an URL, or
  </Item>
  <Mark><C>PostalAddress</C></Mark>
  <Item>
    a string.
  </Item>
  </List>
</Item>
<Mark><C>SourceRepository</C></Mark>
<Item>
  a record with the components
  <C>Type</C> (the version control system, e.g. <C>"git"</C> or <C>"hg"</C>)
 and <C>URL</C> (the URL of the repository), both strings,
</Item>
<Mark><C>IssueTrackerURL</C></Mark>
<Item>
  a string started with <C>http://</C>, <C>https://</C>, or <C>ftp://</C>,
</Item>
<Mark><C>SupportEmail</C></Mark>
<Item>
  a string denoting an e-mail address,
</Item>
<Mark><C>Dependencies</C></Mark>
<Item>
  a record describing the dependencies of the package
  (see Section <Ref Sect="Package dependencies"/>),
  with the following optional components
  <List>
  <Mark><C>GAP</C></Mark>
  <Item>
    a string denoting the needed version of &GAP;,
  </Item>
  <Mark><C>NeededOtherPackages</C></Mark>
  <Item>
    a list of pairs <C>[ pkgname, pkgversion ]</C> of strings,
    denoting the other packages which must be available if the current package
    shall be loadable,
  </Item>
  <Mark><C>SuggestedOtherPackages</C></Mark>
  <Item>
    a list of pairs <C>[ pkgname, pkgversion ]</C> of strings,
    denoting the other packages which shall be loaded together with the
    current package if they are available,
  </Item>
  <Mark><C>ExternalConditions</C></Mark>
  <Item>
    a list of strings or of pairs <C>[ text, URL ]</C> of strings,
    denoting conditions on external programs,
  </Item>
  </List>
</Item>
<Mark><C>AvailabilityTest</C></Mark>
<Item>
  a function with no arguments that returns <K>true</K> if the package is
  available, and <K>false</K> otherwise
  (can be <Ref Func="ReturnTrue"/> if the package consists only of &GAP;
  code; this is also the default value),
</Item>
<Mark><C>BannerString</C> or <C>BannerFunction</C></Mark>
<Item>
  a string or a function, respectively,
  that is used to create a package banner different from the default banner
  (see Section <Ref Sect="The Banner"/>),
</Item>
<Mark><C>TestFile</C></Mark>
<Item>
  a string denoting a relative path to a readable file
  which contains tests of the package's functionality
  (see Section <Ref Sect="Testing a GAP package"/>),
</Item>
<Mark><C>Keywords</C></Mark>
<Item>
  a list of strings that are keywords related to the topic of the package,
</Item>
<Mark><C>Extensions</C></Mark>
<Item>
  a list of records that describe conditional extensions of the package
  (see Section <Ref Sect="Extensions Provided by a Package"/>).
</Item>
</List>

Other components of the record can be supported;
for example, <C>AutoDoc</C> is used by the <Package>AutoDoc</Package>
package if applicable.

</Subsection>

<#Include Label="ValidatePackageInfo">
<#Include Label="ShowPackageVariables">
<#Include Label="BibEntry">
<#Include Label="Cite">

</Section>

<Section Label="Guidelines for Writing a GAP Package">
<Heading>Guidelines for Writing a &GAP; Package</Heading>

The remaining part of this chapter explains the basics
of how to write a &GAP; package so that it integrates properly into &GAP;.
<P/>

There are two basic aspects of creating a &GAP; package.
<P/>

First, it is a convenient possibility to load additional functionality into
&GAP; including a smooth integration of the package documentation. Second,
a package is a way to make your code available to other &GAP; users.
<P/>

Moreover, the &GAP; Group may provide some help with redistributing your
package via the &GAP; website after checking if the
package provides some new or improved functionality which looks interesting
for other users, if it contains reasonable documentation, and if it seems
to work smoothly with the &GAP; library and other distributed packages. In
this case the package can take part in the &GAP; distribution update
mechanism and becomes a <E>deposited</E> package.
<P/>

Furthermore, package authors are encouraged to check if the package would
be appropriate for the refereeing process and <E>submit</E> it. If the
refereeing has been successful, the package becomes an <E>accepted</E> package.
Check out <URL>https://www.gap-system.org/Packages/Authors/authors.html</URL>
on the &GAP; website for more details.
<P/>

Below we start with a description how the directory structure of a
&GAP; package should be constructed and then add remarks on certain aspects
of creating a package, some of these only apply to some packages. Finally,
we provide guidelines for the release preparation and its distribution.
<P/>

</Section>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Structure of a GAP Package">
<Heading>Structure of a &GAP; Package</Heading>

<Index Subkey="for a GAP package">home directory</Index>
A &GAP; package should have an alphanumeric name;
mixed case is fine, but there should be no whitespace characters.
All files of a &GAP; package <A>packagename</A> must be collected in a
single directory <A>packagedir</A>, where <A>packagedir</A> should  be
just <A>packagename</A> optionally converted to lowercase and optionally
followed by the package version (with or without hyphen to separate the
version from <A>packagename</A>).
Let us call this directory the <E>home directory</E> of the package.
<P/>
To use the  package with &GAP;, the directory <A>packagedir</A> must
be a subdirectory of a <F>pkg</F> directory in (one of) the &GAP; root
directories (see <Ref Sect="GAP Root Directories"/>).
For  example, if  &GAP; is  installed in <F>/usr/local/gap4</F> then the
files of the package <C>MyPack</C> may be placed in the directory
<F>/usr/local/gap4/pkg/mypack</F>.

The directory <A>packagedir</A> preferably should have the following
structure (below, a trailing  <C>/</C> distinguishes directories from
ordinary files):
<P/>
<Alt Only="LaTeX">\newpage</Alt>
<Log><![CDATA[
packagedir/
  doc/
  lib/
  tst/
  CHANGES
  LICENSE
  README
  PackageInfo.g
  init.g
  read.g
]]></Log>
<P/>

This layout of directories and files may be created manually, or automatically
using the tool called <Package>PackageMaker</Package>,
available at <URL>https://github.com/gap-system/PackageMaker</URL>. The
<Package>PackageMaker</Package> asks several questions about the intended
package and then creates a new directory for it and populates it with all
the files needed for a basic package.
<P/>

Packages that contain some code that requires compilation will usually have
it in the <F>src</F> subdirectory. They may also have extra files such as
<F>configure</F>, <F>Makefile.in</F> etc. that automate the build procedure.

There are three file names with a special meaning in the home
directory of a package: <F>PackageInfo.g</F> and <F>init.g</F>
which must be present, and <F>read.g</F> which is optional.
<P/>

On the other hand, the names of <F>CHANGES</F>, <F>LICENSE</F> and
<F>README</F> files are not strictly fixed. They may have extensions
<F>.txt</F> or <F>.md</F>, and instead of <F>LICENSE</F> one could use
e.g. <F>COPYING</F> or <F>GPL</F> for packages distributed under the
GNU General Public License, or use <F>HISTORY</F> instead of <F>CHANGES</F>.
<P/>

We now describe the above files and directories in more details:
<P/>

<List>

<Mark>
<F>README</F></Mark>
<Item>
<Index Key="README" Subkey="for a GAP package"><F>README</F></Index>

The filename may optionally have an extension, e.g. <F>.txt</F> or <F>.md</F>.
<P/>
This should contain <Q>how to get it</Q> instructions (covering the
way of getting it with the &GAP; distribution and from the &GAP; website,
if applicable), as well as installation instructions and names
of the package  authors and their email addresses. These installation
instructions should be repeated or referenced from the package's
documentation, which  should be in the <F>doc</F> directory
(see <Ref Sect="Writing Documentation and Tools Needed"/>).
Authors' names and addresses should be repeated both in the package's
documentation and in the <F>PackageInfo.g</F> (see below).
</Item>

<Mark>
<F>CHANGES</F></Mark>
<Item>
For further versions of the package, it will be also useful to have a
<F>CHANGES</F> file that records the main changes between versions
of the package.
<P/>
The filename may optionally have an extension, e.g. <F>.txt</F> or <F>.md</F>.
</Item>

<Mark>
<F>LICENSE</F></Mark>
<Item>
The file which explains conditions on which the package is distributed.
<P/>
We advise all package authors to make clear in the documentation of their
package the basis on which it is being distributed to users. Technically,
this is the terms of the license which you give the users to copy, modify
and redistribute your software (of which you presumably own the copyright)
for their purposes.
<P/>
&GAP; itself is distributed under the GNU General Public License version 2,
a popular <Q>free software</Q> license which allows users to redistribute it
freely under the same terms, and requires that any software which
incorporates &GAP; (technically, any <Q>derived work</Q>) also be distributed
under those terms. We would encourage you to consider the GPL for your
packages, but you might wish to be more restrictive (for instance
forbidding redistribution for profit) or less restrictive (allowing
your software to be incorporated into commercial software).
<P/>
The filename may optionally have an extension, e.g. <F>.txt</F> or <F>.md</F>.
Some packages also use different filenames, like <F>COPYING</F>.
</Item>

<Mark><F>configure</F>, <F>Makefile.in</F></Mark>
<Item>
These files are typically only used by packages which have a non-&GAP; component,
e.g.&nbsp;some C code (the files of which should be in the <F>src</F>
directory). The <F>configure</F> and <F>Makefile.in</F> files of the
<Package>Example</Package> package provide prototypes (or they may be created
using the <Package>PackageMaker</Package> mentioned above). The <F>configure</F>
file typically takes a path <A>path</A> to the &GAP; root directory as argument
and uses the value assigned to <C>GAParch</C> in the file <F>sysinfo.gap</F>,
created when &GAP; was compiled to determine the
compilation architecture, inserts this in place of the string <C>@GAPARCH@</C>
in <F>Makefile.in</F> and creates a file <F>Makefile</F>. When <C>make</C> is
run (which, of course, reads the constructed <F>Makefile</F>), a directory
<F>bin</F> (if necessary) and subdirectories of <F>bin</F> with the path equal
to the string assigned to <C>GAParch</C> in the file <F>sysinfo.gap</F> should
be created; any binaries constructed by compiling the code in <F>src</F> should
end up in this subdirectory of <F>bin</F>.
<!-- Max Horn says that this information is outdated with the new build system.
While this still works (due to the "compatibility mode"), the plan is for
sysinfo.gap to go away, or at last change substantially. This text should be
updated then. -->
</Item>

<Mark><F>PackageInfo.g</F></Mark>
<Item>
<Index Key="PackageInfo.g" Subkey="for a GAP package"><C>PackageInfo.g</C></Index>
Every &GAP; package <E>must</E> have a <F>PackageInfo.g</F>
file which contains meta-information about the package (package name, version,
author(s), relations to other packages, homepage, download archives, etc.).
This information is used by the package loading mechanism and also for
the redistribution of a package with &GAP;. The <Package>Example</Package> package's
<F>PackageInfo.g</F> file  is  well-commented  and can be used as a
prototype (see also <Ref Sect="The PackageInfo.g File"/> for further details).
It may also be created using the <Package>PackageMaker</Package> mentioned above.

</Item>

<Mark><F>init.g</F>, <F>read.g</F></Mark>
<Item>
<Index Key="init.g" Subkey="for a GAP package"><C>init.g</C></Index>
<Index Key="read.g" Subkey="for a GAP package"><C>read.g</C></Index>
A &GAP; package <E>must</E> have a file <F>init.g</F>.
Typical <F>init.g</F> and <F>read.g</F> files should normally consist
entirely of <Ref Func="ReadPackage"/> commands (and possibly
also <Ref Oper="Read"/> commands) for reading further files
of the package. If the <Q>declaration</Q> and <Q>implementation</Q> parts of
the package are separated (and this is recommended), there should be a
<F>read.g</F> file.
The <Q>declaration</Q>  part
of a package consists of function and variable <E>name</E> declarations  and
these go in files with <C>.gd</C> extensions; these  files  are  read  in  via
<C>ReadPackage</C> commands in the <F>init.g</F> file. The <Q>implementation</Q>  part
of a package consists of the actual  definitions  of  the  functions  and
variables whose names were declared  in  the  <Q>declaration</Q>  part,  and
these go in files with <C>.gi</C> extensions; these  files  are  read  in  via
<C>ReadPackage</C> commands in the <F>read.g</F> file. The reason for following the
above dichotomy is that the <F>read.g</F> file is read  <E>after</E>  the  <F>init.g</F>
file, thus enabling the possibility of  a  function's  implementation  to
refer to another function whose name is known but is not actually defined
yet (see <Ref Sect="Declaration and Implementation Part of a Package"/>
below for more details).
<P/>
The &GAP; code (whether or not it is split into <Q>declaration</Q> and
<Q>implementation</Q> parts) should go in the package's <F>lib</F> directory
(see below).
</Item>

<Mark><F>doc</F></Mark>
<Item>
<Index Key="GAPDoc" Subkey="for writing package documentation">GAPDoc format</Index>
This directory should contain the package's documentation, written in an
XML-based documentation format supported by the &GAP; package &GAPDoc;
(see <Ref Sect="Introduction  and  Example" BookName="gapdoc"/>)
which is used for the &GAP; documentation itself.
<P/>
The <Package>Example</Package> package's documentation (see its <F>doc</F>
directory) may be used as a prototype. It consists of the master file
<F>main.xml</F>, further <F>.xml</F> files for manual chapters (included in
the manual via <C>Include</C> directives in the master file) and the &GAP;
input file <F>../makedocrel.g</F> which generates the manuals.
Generally, one should also provide a <F>manual.bib</F> Bib&TeX; database
file or an <F>xml</F> file in the BibXMLext format (see
<Ref Sect="The BibXMLext Format" BookName="gapdoc"/>).
<P/>
<!--  Generating  the
various formats of the manuals requires various software tools which  are
called directly or indirectly by  <C>make&uscore;doc</C>  and  these  are  listed  in
Section&nbsp;<Ref Sect="Writing Documentation and Tools Needed"/>. The file  <C>manual.mst</C>  is
needed for generating a manual index; it should be  a  copy  of  the  one
provided in the <Package>Example</Package> package. The only adjustments that  a  package
writer should need to make to <C>make&uscore;doc</C> is to replace occurrences of the
word <C>Example</C> with <A>packagename</A>. -->
One could also use the <Package>AutoDoc</Package> which simplifies writing
documentation by generating most of the &GAPDoc; code automatically.
</Item>

<Mark><F>lib</F></Mark>
<Item>
This is the preferred place for the &GAP; code of the package, i.e.&nbsp;the
<C>.g</C>, <C>.gd</C> and <C>.gi</C> files (other than <F>PackageInfo.g</F>,
<F>init.g</F> and <F>read.g</F>). For some packages, the directory <F>gap</F>
has been used instead of <F>lib</F>; <F>lib</F> has the advantage that it is
the default subdirectory of a package directory searched for by the
<Ref Func="DirectoriesPackageLibrary"/> command.
</Item>

<Mark><F>src</F></Mark>
<Item>
If the package contains non-&GAP; code, e.g.&nbsp;C code, then this source
code should go in the <F>src</F> directory. If there are <C>.h</C>
<Q>include</Q> files you may prefer to put these all together in a separate
<C>include</C> directory. There is one further rule for the location of kernel
library modules or external programs which is explained in
<Ref Sect="Installation of GAP Package Binaries"/> below.
</Item>

<Mark><F>tst</F></Mark>
<Item>
It is highly recommended that a package should have test files, which then
should go in the <F>tst</F> directory. For a deposited package, a test file
with a basic test of the package (for example, to check that it works as
expected and/or that the manual examples are correct) may be specified in the
<F>PackageInfo.g</F> to be included in the &GAP; standard test suite
and run as a part of the &GAP; release preparation.
More specific and time consuming tests are not supposed to be a part of the
&GAP; standard test suite but may be placed in the <F>tst</F> directory
with further instructions on how to run them.
See Section <Ref Sect="Testing a GAP package"/> about the requirements
to the test files formats and further recommendations.
</Item>

</List>

All other files can be organised as you like. But we suggest that you
have a look at existing packages and use a similar scheme, for
example, put examples in the <F>examples</F> subdirectory, data
libraries in extra subdirectories, and so on.
<P/>
Sometimes there may be a need to include an empty directory in the
package distribution (for example, as a place to store some data that
may appear at runtime). In this case package authors are
advised to put in this directory a short <F>README</F> file describing
its purpose to ensure that such directory will be included in the
redistribution.
<P/>
Concerning the &GAP; code in packages, it is recommended to use only
documented &GAP; functions, see <Ref Sect="Undocumented Variables"/>.
In particular if you want to make your package available to other &GAP; users
it is advisable to avoid using <Q>obsolete</Q> variables
(see <Ref Chap="Replaced and Removed Command Names"/>). To test that
the package does not use obsolete variables you can set the <C>ReadObsolete</C>
component in your <F>gap.ini</F> file to <K>false</K> (see
<Ref Sect="sect:gap.ini"/>) or start &GAP; with <C>-A -O</C> command line
options (note that this may also cause problems with loading other
packages that use <Q>obsolete</Q> variables).

</Section>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Writing Documentation and Tools Needed">
<Heading>Writing Documentation and Tools Needed</Heading>

If you  intend to  make your  package available to  other users  it is
essential  to include documentation explaining how to install and use your
programs.
<P/>
Concerning the installation you should produce a <F>README</F> file 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/>
Documentation for &GAP; package should be prepared in an XML-based
documentation format that is defined in and can be used with the &GAPDoc;
package (see&nbsp;<Ref Chap="Introduction and Example" BookName="gapdoc"/>).
<P/>
There should be at least a text version of your documentation provided for use
in the terminal running  &GAP; and some nicely printable version in
<C>.pdf</C> format.
Many &GAP; users like to browse the documentation in HTML format
via their Web browser. As a package author, you are not obliged
to provide an HTML version of your package  manual,
<!-- TODO: What about requiring an HTML version? -->
but if you use the &GAPDoc; package you should have no trouble in producing one.
<P/>
Moreover, using the
&GAPDoc; package, it is also possible to produce HTML version of the
documentation supporting MathJax (<URL>https://www.mathjax.org/</URL>)
for the high quality rendering of mathematical symbols while viewing
it online. For example, if you are viewing the HTML version of the manual,
compare how this formula will look with MathJax turned on/off:
<Display Mode="M">
[ \chi, \psi ] = \left( \sum_{{g \in G}} \chi(g) \psi(g^{{-1}}) \right) / |G|.
</Display>
<P/>
The manual of the <Package>Example</Package> package is written in the &GAPDoc; format,
and commands needed to build it are contained in the file <C>makedocrel.g</C>
(you don't need to re-build the manual since it is already included in the package).
You will also need to have certain &TeX; tools installed: to produce manuals in
the <C>.pdf</C> format, you need <C>pdflatex</C>.
<P/>
In principle it is also possible to use alternative documentation
systems. Historically, there is one such &TeX;-based system,
which predates &GAPDoc;, and which is still in use by several packages.
However, we do not recommend using it for new packages.
</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="An Example of a GAP Package">
<Heading>An Example of a &GAP; Package</Heading>

We illustrate the creation of a &GAP; package by an example of a very basic package.
<P/>
Create the following directories in your home directory:
<F>.gap</F>, <F>.gap/pkg</F> and <F>.gap/pkg/test</F>.
Then inside the directory <F>.gap/pkg/test</F> create an empty file
<F>init.g</F>, and a file <F>PackageInfo.g</F> with the following contents:
<P/>
<Log><![CDATA[
SetPackageInfo( rec(
  PackageName := "test",
  Version := "1.0",
  PackageDoc := rec(
      BookName  := "test",
      SixFile   := "doc/manual.six",
  ),
  Dependencies := rec(
      GAP       := "4.9",
      NeededOtherPackages := [ ["GAPDoc", "1.6"] ],
      SuggestedOtherPackages := [ ] ),
  AvailabilityTest := ReturnTrue ) );
]]></Log>
<P/>
This file  declares the &GAP; package with name <Q>test</Q> in version 1.0.
The package documentation consists of one autoloaded book; the <C>SixFile</C>
component is needed by the &GAP; help system. Package dependencies (picked
for the purposes of this example) require at least &GAP;&nbsp;4.9 and &GAPDoc;
package at version at least 1.6, and these conditions will be checked when the
package will be loaded (see <Ref Sect="Version Numbers"/>).
Since there are no requirements that have to be tested,
<C>AvailabilityTest</C> just uses <Ref Func="ReturnTrue"/>.
<P/>
Now start &GAP; (without using the <C>-r</C> option) and the <F>.gap</F>
directory will be added to the &GAP; root directory to
allow &GAP; to find the packages installed there
(see <Ref Sect="GAP Root Directories"/>).
<P/>
<Log><![CDATA[
gap> LoadPackage("test");
true
]]></Log>
<P/>
This &GAP; package is too simple to be useful, but we have succeeded
in loading it via <Ref Func="LoadPackage"/>, satisfying all specified
dependencies.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="File Structure">
<Heading>File Structure</Heading>

Package files may follow the style used for the &GAP; library.
Every file in the &GAP; library starts with a header that lists the
filename, copyright, a short description of the file contents and the
original authors of this file, and ends with a comment line <C>#E</C>.
Indentation in functions and the use of decorative spaces in the code
are left to the decision of the authors of each file. Global (i.e.
re-used elsewhere) comments usually are indented by two hash marks and
two blanks, in particular, every declaration or method or function
installation which is not only of local scope is separated by a header.
<P/>
Facilities to distribute a document over several files
to allow the documentation for parts of some code to be stored in
the same file as the code itself are provided by the &GAPDoc; package (see
<Ref Sect="Distributing a Document into Several Files" BookName="gapdoc"/>).
The same approach is demonstrated by the <Package>Example</Package> package.
E.g. <F>example/doc/example.xml</F> has the statement
<C>&lt;#Include Label="ListDirectory"></C>
and <F>example/lib/files.gd</F> contains
<Log><![CDATA[
##  <#GAPDoc Label="ListDirectory">
##  <ManSection>
##  <Func Name="ListDirectory" Arg="[dir]"/>
##
##  <Description>
##  lists the files in directory <A>dir</A> (a string)
##  or the current directory if called with no arguments.
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
DeclareGlobalFunction( "ListDirectory" );
]]></Log>
This is all put together in the file <F>example/makedocrel.g</F> which
builds the package documentation, calling
<Ref Func="MakeGAPDocDoc" BookName="gapdoc"/> with
locations of library files containing parts of the
documentation.
<P/>
Alternatively, one could use the <Package>AutoDoc</Package>, which simplifies
writing documentation by generating most of the &GAPDoc; code automatically.
The equivalent of the fragment of the code above for <Package>AutoDoc</Package>
would look like
<Log><![CDATA[
#! @Arguments [dir]
#! @Description
#!  lists the files in directory <A>dir</A> (a string)
#!  or the current directory if called with no arguments.
DeclareGlobalFunction( "ListDirectory" );
]]></Log>
</Section>



<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Creating the PackageInfo.g File">
<Heading>Creating the PackageInfo.g File</Heading>
<Index Key="ValidatePackageInfo"><C>ValidatePackageInfo</C></Index>
While the minimalistic <F>PackageInfo.g</F> file described in
<Ref Sect="An Example of a GAP Package"/> is enough to let &GAP;
load the package, and check all specified dependencies, it is
actually missing many extra fields which 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 webpage, and so on. All
these details are required for a package to be redistributed with &GAP;.
<P/>
The command <Ref Func="ValidatePackageInfo"/> can be used to get a quick idea about which
fields are missing:
<Log><![CDATA[
gap> ValidatePackageInfo("PackageInfo.g");
#E  component `Subtitle' must be bound to a string
#E  component `Date' must be bound to a string of the form `dd/mm/yyyy'
#E  component `ArchiveURL' must be bound to a string started with http://, https:// or ftp://
#E  component `ArchiveFormats' must be bound to a string
#E  component `README_URL' must be bound to a string started with http://, https:// or ftp://
#E  component `PackageInfoURL' must be bound to a string started with http://, https:// or ftp://
#E  component `AbstractHTML' must be bound to a string
#E  component `PackageWWWHome' must be bound to a string started with http://, https:// or ftp://
#E  component `ArchiveURLSubset' must be bound to a list of strings denoting relative paths to readable files or directories
#E  component `HTMLStart' must be bound to a string denoting a relative path to a readable file
#E  component `PDFFile' must be bound to a string denoting a relative path to a readable file
#E  component `SixFile' must be bound to a string denoting a relative path to a readable file
#E  component `LongTitle' must be bound to a string
false
]]></Log>
<P/>
We suggest to create a <F>PackageInfo.g</F> file for your package by
copying the one in the <Package>Example</Package> package, distributed
with &GAP;, or using the <Package>PackageMaker</Package>
(<URL>https://github.com/gap-system/PackageMaker</URL>), and then adjusting
it for your package. Within &GAP; you can look at this template file for a
list and explanation of all recognised entries by
<Log><![CDATA[
Pager(StringFile(Filename(DirectoriesLibrary(),
                          "../pkg/example/PackageInfo.g")));
]]></Log>
<P/>
Instead of populating the rest of the <F>PackageInfo.g</F> by hands,
you can also create a basic &GAP; package with the help of the
tool called <Package>PackageMaker</Package>, available at
<URL>https://github.com/gap-system/PackageMaker</URL>. The
<Package>PackageMaker</Package> asks several questions about the intended
package and then creates a new directory for it and populates it with all
the files needed for a basic package.

</Section>



<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Functions and Variables and Choices of Their Names">
<Heading>Functions and Variables and Choices of Their Names</Heading>

In writing the &GAP; code for your package  you  need  to  be  a  little
careful on just how you define your functions and variables.
<P/>
<E>Firstly</E>, in general one should avoid defining functions  and  variables
via assignment statements in the way you would interactively, e.g.
<P/>
<Example><![CDATA[
gap> Squared := x -> x^2;;
gap> Cubed := function(x) return x^3; end;;
]]></Example>
<P/>
The reason for this is that such  functions  and  variables  are  <E>easily
overwritten</E> and what's more you are not warned about it when it happens.
<P/>
To protect a function  or  variable  against  overwriting  there  is  the
function <Ref Func="BindGlobal"/>,
or alternatively (and equivalently)  you  may  define  a  global
function via a <Ref Func="DeclareGlobalFunction"/>
and <Ref Func="InstallGlobalFunction"/> pair
or a global variable via a <Ref Func="DeclareGlobalVariable"/>
and <Ref Func="InstallValue"/> pair. There are also operations
and their methods,  and  related  objects like attributes and filters which
also have <C>Declare...</C> and <C>Install...</C> pairs.
<P/>
<E>Secondly</E>,  it is a  good  idea  to  reduce  the  chance  of  accidental
overwriting by choosing names for your functions and variables that begin
with a string that identifies it  with  the  package,  e.g.&nbsp;some  of  the
undocumented functions in the <Package>Example</Package> package begin with <C>Eg</C>. This is
especially important in cases where you actually want the user to be able
to change the value of a function or variable defined  by  your  package,
for which you have used direct assignments  (for  which  the  user  will
receive no warning  if  she  accidentally  overwrites  them).  It is  also
important  for  functions  and  variables   defined   via   <C>BindGlobal</C>,
<C>DeclareGlobalFunction</C>/<C>InstallGlobalFunction</C>                       and
<C>DeclareGlobalVariable</C>/<C>InstallValue</C>, in order to  avoid  name  clashes
that may  occur  with  (extensions  of)  the  &GAP;  library  and  other
packages.
<P/>
<Index Subkey="for a GAP package">local namespace</Index>
Additionally, since &GAP;&nbsp;4.5 a package may place global variables into
a local namespace as explained in
<Ref Sect="Namespaces"/> in order to avoid
name clashes and preserve compatibility. This new feature
allows you to define in your package global variables with the identifier
ending with the <C>@</C> symbol, e.g. <C>xYz@</C>. Such variables may be used
in your package code safely, as they may be accessed from outside the package
only by their full name, i.e. <C>xYz@YourPackageName</C>. This helps to prevent
clashes between different packages or between a package and the &GAP; library
because of the same variable names.
<!-- TODO: demonstrate in the example package how this is actually used -->
<P/>
On the other hand, operations and their methods (defined  via
<Ref Func="DeclareOperation"/>,
<Ref Func="InstallMethod"/> etc.&nbsp;pairs)
and their  relatives  do not need this consideration, as they
avoid name clashes by allowing for more than one <Q>method</Q>
for the same-named object.
<P/>
To demonstrate the definition of a function via a
<C>DeclareOperation</C>/<C>InstallMethod</C> pair,
the method <Ref Oper="Recipe" BookName="example"/> was included in the <Package>Example</Package> package;
<C>Recipe( FruitCake );</C> gives a <Q>method</Q> for making a
fruit cake (forgive the pun).
<P/>
<E>Thirdly</E>, functions or variables with  <C>Set<A>XXX</A></C>  or  <C>Has<A>XXX</A></C>  names
(even if they are defined as operations) should be avoided as  these  may
clash with objects associated with attributes or  properties  (attributes
and  properties   <A>XXX</A>   declared   via   the   <C>DeclareAttribute</C>   and
<C>DeclareProperty</C> commands have associated  with  them  testers  of  form
<C>Has<A>XXX</A></C> and setters of form <C>Set<A>XXX</A></C>).
<P/>
<E>Fourthly</E>, it is a good  idea  to  have  some  convention  for  internal
functions and variables  (i.e.&nbsp;the  functions  and  variables  you  don't
intend for the  user  to  use).  For  example,  they  might  be  entirely
CAPITALISED.
<P/>
Additionally, there is a recommended naming convention that the &GAP; core
system and &GAP; packages should not use global variables starting in the
lowercase. This allows to reserve variables with names starting in lowercase
to the &GAP; user so they will never clash with the system. It is extremely
important to avoid using for package global variables very short names
started in lowercase. For example, such names like <C>cs</C>, <C>exp</C>,
<C>ngens</C>, <C>pc</C>, <C>pow</C> which are perfectly fine for local
variables, should never be used for globals. Additionally, the package must
not have writable global variables with very short names even if they are
starting in uppercase, for example, <C>C1</C> or <C>ORB</C>, since they
also could be easily overwritten by the user.
<P/>
It is a good practice to follow naming conventions used in &GAP; as
explained in <Ref Sect="Naming Conventions"/> and
<Ref Sect="Changing the Structure" BookName="tut"/>, which
might help users to memorize or even guess names of functions
provided by the package.
<P/>
<E>Finally</E>, note the advantage of using
<C>DeclareGlobalFunction</C>/<C>InstallGlobalFunction</C>,
<C>DeclareGlobalVariable</C>/<C>InstallValue</C>, etc.&nbsp;pairs (rather than
<C>BindGlobal</C>) to define functions and variables, which allow the  package
author to organise her function- and variable- definitions in  any  order
without worrying about any interdependence. The  <C>Declare...</C>  statements
should go in files with <C>.gd</C> extensions and be loaded  by  <C>ReadPackage</C>
statements in the package <F>init.g</F> file, and the <C>Install...</C> definitions
should go in files with <C>.gi</C> extensions and be loaded  by  <C>ReadPackage</C>
statements in the package <F>read.g</F> file;  this  ensures  that  the  <C>.gi</C>
files are read <E>after</E> the <C>.gd</C> files. All other package code should  go
in <C>.g</C> files (other than the <F>init.g</F> and <F>read.g</F> files themselves) and
be loaded via <C>ReadPackage</C> statements in the <F>init.g</F> file.
<P/>

<Index Key="ShowPackageVariables"><C>ShowPackageVariables</C></Index>
In conclusion, here is some practical advice on how to check which variables
are used by the package.
<P/>
Firstly, there is a function
<Ref Func="ShowPackageVariables"/>.
If the package <A>pkgname</A> is available
but not yet loaded then <C>ShowPackageVariables( pkgname )</C>
prints a list of global variables that become bound and of methods
that become installed when the package is loaded (for that, the package
will be actually loaded, so <C>ShowPackageVariables</C> can be called
only once for the same package in the same &GAP; session.)
The second optional argument <A>version</A> may specify a particular
package version to be loaded.
An error message will be printed if (the given version of) the package
is not available or already loaded.
<P/>
Info lines for undocumented variables will be marked with an asterisk
<C>*</C>. Note that the &GAP; help system is case insensitive,
so it is difficult to document identifiers that differ only by case.
<P/>
The following entries are omitted from the list:
default setter methods for attributes and properties that are declared
in the package,
and <C>Set<A>attr</A></C> and <C>Has<A>attr</A></C> type variables
where <A>attr</A> is an attribute or property.
<P/>
For example, for the <Package>Example</Package> package
it may produce the output looking like this:
<Log><![CDATA[
gap> ShowPackageVariables("example");
----------------------------------------------------------------
Loading Example 3.3 (Example/Template of a GAP Package)
by Werner Nickel (http://www.mathematik.tu-darmstadt.de/~nickel),
   Greg Gamble (http://www.math.rwth-aachen.de/~Greg.Gamble), and
   Alexander Konovalov (http://www.cs.st-andrews.ac.uk/~alexk/).
----------------------------------------------------------------
new global functions:
  EgSeparatedString( str, c )*
  FindFile( dir, file )
  HelloWorld(  )
  ListDirectory( arg )
  LoadedPackages(  )
  WhereIsPkgProgram( prg )
  Which( prg )

new global variables:
  FruitCake

new operations:
  Recipe( arg )

new methods:
  Recipe( cake )
]]></Log>

Another trick is to start &GAP; with <C>-r -A</C> options, immediately
load your package and then call <Ref Func="NamesUserGVars"/>
which returns a list of the global variable names created since the
library was read, to which a value is currently bound. For example, for the
<Package>Example</Package> it produces
<Log><![CDATA[
gap> NamesUserGVars();
[ "EgSeparatedString", "FindFile", "FruitCake", "HelloWorld", "ListDirectory",
  "LoadedPackages", "Recipe", "WhereIsPkgProgram", "Which" ]
]]></Log>
but for packages with dependencies it will also contain variables created by
other packages. Nevertheless, it may be a useful check to search for unwanted
variables appearing after package loading. A potentially dangerous situation
which should be avoided is when the package uses some simply named temporary
variables at the loading stage. Such <Q>phantom</Q> variables may then remain
unnoticed and, as a result, there will be no warnings if the user occasionally
uses the same name as a local variable name in a function. Even more
dangerous is the case when the user variable with the same name already exists
before the package is loaded so it will be silently overwritten.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Package dependencies">
<Heading>Package Dependencies (Requesting one &GAP; Package from within Another)</Heading>

<Index>needed package</Index>
<Index>suggested package</Index>
<Index Subkey="for a GAP package">dependencies</Index>
It is possible for one &GAP; package <C>A</C>
to require another package <C>B</C>.
For that, one simply adds the name and the (least) version number of the
package <C>B</C> to the <C>NeededOtherPackages</C> component of the
<C>Dependencies</C> component of the <F>PackageInfo.g</F> file of the package
<C>A</C>.
In this situation, loading the package <C>A</C> forces that also the package
<C>B</C> is loaded, and that <C>A</C> cannot be loaded if <C>B</C> is not
available.
<P/>

If <C>B</C> is not essential for <C>A</C> but should be loaded if it is
available
(for example because <C>B</C> provides some improvements of the main system
that are useful for <C>A</C>)
then the name and the (least) version number of <C>B</C> should be added to
the <C>SuggestedOtherPackages</C> component of the
<C>Dependencies</C> component of the <F>PackageInfo.g</F> file of <C>A</C>.
In this situation, loading <C>A</C> forces an attempt to load also <C>B</C>,
but <C>A</C> is loaded even if <C>B</C> is not available.
<P/>

All package dependencies must be documented explicitly in the
<F>PackageInfo.g</F> file. It is important to properly
identify package dependencies and make the right decision
whether the other package should be <Q>needed</Q> or <Q>suggested</Q>.
For example, declaring package as <Q>needed</Q> when <Q>suggested</Q>
might be sufficient may prevent loading of packages under Windows for
no good reason.
<P/>

It is not appropriate to explicitly call
<Ref Func="LoadPackage"/> <E>when the package is loaded</E>,
since this may distort the order of package loading and result in warning
messages. It is recommended to turn such dependencies into needed or
suggested packages. For example, a package can be designed in such a way
that it can be loaded with restricted functionality if another package
(or standalone program) is missing, and in this case the missing package
(or binary) is <E>suggested</E>. Alternatively, if the package author
decides that loading the package in this situation makes no sense,
then the missing component is <E>needed</E>.
<P/>

On the other hand, if <Ref Func="LoadPackage"/> is called
inside functions of the package then there is no such problem, provided
that these functions are called only after the package has been loaded,
so it is not necessary to specify the other package as suggested. The same
applies to test files and manual examples, which may be simply extended
by calls to <Ref Func="LoadPackage"/>.
<P/>

<Index Key="OnlyNeeded" Subkey="option"><C>OnlyNeeded</C></Index>
It may happen that a package B that is listed as a suggested
package of package A is actually needed by A.
If no explicit <Ref Func="LoadPackage"/> calls for B
occur in A at loading time, this can now be detected using
the new possibility to load a package without loading its suggested
packages using the global option <C>OnlyNeeded</C> which
can be used to (recursively) suppress loading the suggested packages
of the package in question. Using this option, one can check whether
errors or warnings appear when B is not available (note that this option
should be used only for such checks to simulate the situation when
package B is not available; it is not supposed to be used in an actual
&GAP; session when package B will be loaded later, since this may cause
problems). In case of any errors or warnings, their consequence can
then be either turning B into a needed package or (since apparently B
was not intended to become a needed package) changing the code accordingly.
Only if package A calls <Ref Func="LoadPackage"/> for B at
loading time (see above) then package B needs to be <E>deinstalled</E>
(i.e. removed) to test loading of A without B.
<!-- TODO: write a new subsection telling how to uninstall GAP package
or what are other ways to disable its loading -->
<P/>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Extensions Provided by a Package">
<Heading>Extensions Provided by a Package</Heading>

Sometimes a package <C>A</C> can provide additional functionality,
such as better methods or additional data,
if some other packages <C>B</C>, <C>C</C>, etc. are loaded.
However, one would like package <C>A</C> to still be usable without these
additional packages,
and therefore <C>B</C>, <C>C</C>, etc. shall not be regarded as needed
packages (see Section <Ref Sect="Package dependencies"/>) of <C>A</C>.

<P/>

One way to deal with this situation is to put those parts of code of <C>A</C>
that depend on <C>B</C>, <C>C</C>, etc., into files that get read only
in the situation that the packages in question have actually been loaded
into the current &GAP; session.

<P/>

However, this leaves the question when to load these files
of a conditional <E>extension</E> of <C>A</C>.
In the past, the only option for <C>A</C> was to check for the presence of
<C>B</C>, <C>C</C>, etc., while it itself was being loaded.
With this setup, it depends on the order in which packages get loaded
whether some feature is available or not:
If <C>B</C> is loaded before <C>A</C>, the extension might be loaded as well;
if <C>B</C> is loaded only after <C>A</C>, then the extension is not loaded.

<P/>

To deal with this issue of conditional extensions of packages,
&GAP; offers a dedicated mechanism:

The <C>Extensions</C> component of the <F>PackageInfo.g</F> file of <C>A</C>
is a list of declarations of conditional extension of <C>A</C>,
each being a record with the following components.

<List>
<Mark><C>needed</C></Mark>
<Item>
  a list of the form
  <C>[ [ pkgname1, version1 ], [ pkgname2, version2 ], </C><M>\ldots</M><C> ]</C>,
  meaning that the extension shall be loaded as soon as all packages
  <C>pkgname1</C>, <C>pkgname2</C>, <M>\ldots</M>, with versions (at least)
  <C>version1</C>, <C>version2</C>, <M>\ldots</M>, have been loaded,
  and
</Item>
<Mark><C>filename</C></Mark>
<Item>
  the path, relative to the package directory of <C>A</C>,
  of a file such that reading this file will load the code of the extension.
</Item>
</List>

<P/>

As an example suppose the following is part of the <F>PackageInfo.g</F>.
Then &GAP; will load the file <F>fileForB.gd</F> as soon as package
<C>B</C> is loaded in version 0.6 or newer, and <F>fileForCD.gi</F> once
package <C>C</C> and <C>D</C> are loaded in version 1.2 and 0.1 or newer respectively.

<Log><![CDATA[
Extensions := [
  rec(
    needed := [ ["B", "0.6"] ],
    filename := "gap/fileForB.gd",
  ),
  rec(
    needed := [ ["C", "1.2"] , ["D", "0.1"] ],
    filename := "gap/fileForCD.gi",
  )
],
]]></Log>

Whenever <Ref Func="LoadPackage"/> is called,
&GAP; checks for package extensions whose conditions now are satisfied,
and loads them.

<P/>

For example, package <C>A</C> can be loaded early in a &GAP; session,
and declare in its <F>PackageInfo.g</F> the availability of an extension
that requires package <C>B</C>.
If <C>B</C> has not yet been loaded then this extension will not be loaded
together with <C>A</C>.
However, as soon as <C>B</C> gets (installed and) loaded later in the
session, also the extension of <C>A</C> will automatically get loaded.

<P/>

The contents of <C>Extensions</C> in a <F>PackageInfo.g</F> file
does not affect the lists of needed or suggested packages.
If an extension of <C>A</C> is beneficial for the functions of <C>A</C>
then it makes sense to list the packages needed for the extension among the
suggested packages of <C>A</C>,
but this may not be the case if the extension is beneficial only for the
functions of its needed packages.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Declaration and Implementation Part of a Package">
<Heading>Declaration and Implementation Part of a Package</Heading>

When &GAP; packages require each other in a circular way,
a <Q>bootstrapping</Q> problem arises of defining functions before they are
called.
The same problem occurs in the &GAP; library, and 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.
&GAP; initially reads all declaration files (in the library they have a
<C>.gd</C> suffix) and afterwards reads all implementation files
(which have a <C>.gi</C> suffix).
<P/>
Something similar is possible for &GAP; packages:
if a file <F>read.g</F> exists in the home directory of the package,
this file is read only <E>after</E> all the <F>init.g</F> files of all
(implicitly) required &GAP; packages are read.
Thus one can separate declaration and implementation for a &GAP; package
in the same way as is done for the &GAP; library,
by creating a file <F>read.g</F>,
restricting the <Ref Func="ReadPackage"/> statements in
<F>init.g</F> to only read those files of the package that provide
declarations,
and to read the implementation files from <F>read.g</F>.
<P/>
<E>Examples:</E>
<P/>
Suppose that there are two packages <C>A</C> and <C>B</C>,
each with files <F>init.g</F> and <F>read.g</F>.
<P/>
<List>
<Item>
  If package <C>A</C> suggests or needs package <C>B</C>
  and package <C>B</C> does not need or suggest any other package
  then first <F>init.g</F> of <C>B</C> is read,
  then <F>read.g</F> of <C>B</C>,
  then <F>init.g</F> of <C>A</C>,
  then <F>read.g</F> of <C>A</C>.
</Item>
<Item>
  If package <C>A</C> suggests or needs package <C>B</C>
  and package <C>B</C> (or a package that is suggested or needed by <C>B</C>)
  suggests or needs package <C>A</C>
  then first the files <F>init.g</F> of <C>A</C> and <C>B</C> are read
  (in an unspecified order)
  and then the files <F>read.g</F> of <C>A</C> and <C>B</C>
  (in the same order).
</Item>
</List>
<P/>

In general, when &GAP; is asked to load a package then first the dependencies
between this packages and its needed and suggested packages are inspected
(recursively), and a list of package sets is computed such that no cyclic
dependencies occur between different package sets and such that no package
in any of the package sets needs any package in later package sets.
Then &GAP; runs through the package sets and reads for each set first all
<F>init.g</F> files and then all <F>read.g</F> files of the packages in the
set.
(There is one exception from this rule:
Whenever packages are autoloaded before the implementation part of the &GAP;
library is read, only the <F>init.g</F> files of the packages are read;
as soon as the &GAP; library has been read, the <F>read.g</F> files of these
packages are also read, and afterwards the above rule holds.)
<P/>

<Index Key="IsPackageMarkedForLoading"><C>IsPackageMarkedForLoading</C></Index>
It can happen that some code of a package depends on the availability of
suggested packages, i.e., different initialisations are performed
depending on whether a suggested package will eventually be loaded or not.
One can test this condition with the function
<Ref Func="IsPackageMarkedForLoading"/>.
In particular, one should <E>not</E> call
(and use the value returned by this call) the function
<Ref Func="LoadPackage"/> inside
package code that is read during package loading.
Note that for debugging purposes loading suggested packages may
have been deliberately disabled via the global option <C>OnlyNeeded</C>.
<P/>

Note that the separation of the &GAP; code of packages into declaration
part and implementation part does in general <E>not</E> allow one to actually
<E>call</E> functions from a package when the implementation part is read.
For example,
in the case of a <Q>cyclic dependency</Q> as in the second example above,
suppose that <C>B</C> provides a new function <C>f</C> or a new global record
<C>r</C> which are declared in the declaration part of <C>B</C>.
Then the code in the implementation part of <C>A</C> may contain
calls to the functions defined in the declaration part of <C>B</C>.
However, the implementation part of <C>A</C> may be read
<E>before</E> the implementation part of <C>B</C>.
So one can in general not assume that during the loading of <C>A</C>,
the function <C>f</C> can be called, or that one can access components of
the record <C>r</C>.
<P/>

If one wants to call the function <C>f</C> or to access components of the
record <C>r</C> in the code of the package <C>A</C> then the problem is
that it may be not possible to determine a cyclic dependency between <C>A</C>
and <C>B</C> from the packages <C>A</C> and <C>B</C> alone.
A safe solution is then to design <C>A</C> in such a way that the code that
calls <C>f</C> or accesses <C>r</C> belongs to <E>package extensions</E>
of <C>A</C> that get loaded only after <C>B</C> has been loaded;
see Section <Ref Sect="Extensions Provided by a Package"/> for details.
<P/>

<Index>autoreadable variables</Index>
In the case of cyclic dependencies, one solution for the above problem
might be to delay those computations (typically initialisations)
in package <C>A</C> that require package <C>B</C> to be loaded
until all required packages are completely loaded.
This can be done by moving the declaration and implementation of the
variables that are created in the initialisation into a separate file
and to declare these variables in the <F>init.g</F> file of the package,
via a call to <Ref Func="DeclareAutoreadableVariables"/>
(see also <Ref Sect="Autoreadable Variables"/>).
<P/>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Autoreadable Variables">
<Heading>Autoreadable Variables</Heading>

Package files containing method installations must be read
when the package is loaded.
For package files <E>not</E> containing method installations
(this applies, for example, to many data files)
another mechanism allows one to delay reading such files
until the data are actually accessed. See
<Ref Label="DeclareAutoreadableVariables"/> for further
details.

</Section>



<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Standalone Programs in a GAP Package">
<Heading>Standalone Programs in a &GAP; Package</Heading>

<!-- TODO: this should also cover kernel modules -->

&GAP; packages that  involve stand-alone programs are fundamentally
different from &GAP; packages that consist entirely of &GAP; code.
<P/>
This difference is threefold: A  user who installs the &GAP; package
must also  compile (or install) the package's  binaries, the
package must  check whether the binaries  are indeed available,
and finally the &GAP; code of the package has to start the external
binary and to communicate with it.
We will cover 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 &GAP; packages might also require this program.
We therefore strongly recommend the provision of a documented &GAP;
function that will call the external binary. We also suggest to create
actually two &GAP; packages; the first providing only the binary and the
interface and the second (requiring the first,
see&nbsp;<Ref Label="Package dependencies"/>) being the actual &GAP; package.
<P/>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="Installation of GAP Package Binaries">
<Heading>Installation of &GAP; Package Binaries</Heading>

<Index Key="sysinfo.gap"><C>sysinfo.gap</C></Index>
<Index Subkey="for a GAP package">external binaries</Index>
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 &GAP; package  which includes external binaries contains a <F>bin</F>
subdirectory. This subdirectory in turn contains subdirectories for
the different architectures on which the &GAP; package binaries are
installed.  The names of these directories must be the same as the
names of the architecture dependent subdirectories of the main <F>bin</F>
directory. Unless you use a tool like <C>autoconf</C> yourself, you must
obtain the correct name of the binary directory from the main &GAP;
branch. To help with this, the main &GAP; directory contains a file
<F>sysinfo.gap</F> which assigns the shell variable <C>GAParch</C> to the
proper name as determined by &GAP;'s <C>configure</C> process.
For example on a Linux system, the file <F>sysinfo.gap</F> may look like
this:
<P/>
<Log><![CDATA[
GAParch=i586-unknown-linux2.0.31-gcc
]]></Log>
<P/>
We suggest that your &GAP; package contains a file <F>configure</F> which
is  called with the  path of  the  &GAP; root directory  as
parameter. This file then  will  read <F>sysinfo.gap</F> and set  up
everything for compiling under the given architecture (for example
creating a <F>Makefile</F> from <F>Makefile.in</F>). As initial templates,
you may use installation scripts of the <Package>Example</Package> package
or files generated with the help of <Package>PackageMaker</Package>.

</Subsection>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="Test for the Existence of GAP Package Binaries">
<Heading>Test for the Existence of GAP Package Binaries</Heading>

If an external binary is essential for the  workings of a &GAP; package,
the function stored in the component <C>AvailabilityTest</C> of the
<F>PackageInfo.g</F> 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
<Ref Oper="Filename" Label="for a directory and a string"/>
for checking for the actual binaries in the path given by
<Ref Func="DirectoriesPackagePrograms"/>
for the respective package.
For example the <Package>example</Package> &GAP; package could use the
following function to test whether the binary <F>hello</F> has been compiled;
it will issue a warning if not, and will only load the package if the binary
is indeed available:
<P/>
<Log><![CDATA[
...
AvailabilityTest := function()
  local path,file;
    # test for existence of the compiled binary
    path:= DirectoriesPackagePrograms( "example" );
    file:= Filename( path, "hello" );
    if file = fail then
      LogPackageLoadingMessage( PACKAGE_WARNING,
          [ "The program `hello' is not compiled,",
            "`HelloWorld()' is thus unavailable.",
            "See the installation instructions;",
            "type: ?Installing the Example package" ] );
    fi;
    return file <> fail;
  end,
...
]]></Log>
<P/>
However, if you look at the actual <F>PackageInfo.g</F> file of the
<Package>example</Package> package, you will see that its
<C>AvailabilityTest</C> function always returns <K>true</K>,
and just logs the warning if the binary is not available
(which may be later viewed with
<Ref Func="DisplayPackageLoadingLog"/>).
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 e.g. under Windows), or may not compile with
some compilers or default compiler options.
See&nbsp;<Ref Sect="Testing for the System Architecture"/>
for information on how to test for the architecture.
<P/>
Package using a kernel module (see <Ref Subsect="Kernel modules"/>),
one may use a test like this:
<Listing><![CDATA[
...
AvailabilityTest := function()
    # see if example.so exists and is a loadable kernel extension
    if not IsKernelExtensionAvailable("example") then
      LogPackageLoadingMessage( PACKAGE_WARNING,
          [ "The kernel extension `example' is unavailable,",
            "perhaps it needs to be recompiled?",
            "See the installation instructions;",
            "type: ?Installing the Example package" ] );
      return false;
    fi;
    return true;
  end,
...
]]></Listing>
<P/>
<Index Key="LogPackageLoadingMessage"><C>LogPackageLoadingMessage</C></Index>
Last but not least: do not print anything in the <C>AvailabilityTest</C>
function of the package via <C>Print</C> or <C>Info</C>. Instead one should
call <Ref Func="LogPackageLoadingMessage"/> to store
a message which may be viewed later with
<Ref Func="DisplayPackageLoadingLog"/>
(the latter two functions have been introduced in &GAP;&nbsp;4.5)
</Subsection>



<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="Calling of and Communication with External Binaries">
<Heading>Calling of and Communication with External Binaries</Heading>

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 &GAP;.
<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
<Ref Oper="Process"/> or
<Ref Func="Exec"/>
which then writes the output data to file, and finally read in
the standalone's output file.
<P/>
The second way is interfacing via input-output streams,
see Section&nbsp;<Ref Sect="Input-Output Streams"/>.
<P/>
Some &GAP; packages use kernel modules
(see <Ref Sect="Kernel modules"/>)
instead of external binaries.
A kernel module is implemented in C and follows certain conventions to
comply with the &GAP; kernel interface, which we plan to document later.
In the meantime, we advise you to look at existing examples of such packages
and get in touch with &GAP; developers if you plan to develop such a package.

</Subsection>

</Section>



<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Having an InfoClass">
<Heading>Having an InfoClass</Heading>

<!-- TODO: (CW) the Example package does not declare an InfoExample,
     and it ought to do so! It might be a good idea to suggest
     _where_ to put this declaration.-->

<Index Key="InfoClass" Subkey="for a GAP package"><C>InfoClass</C></Index>
It is a good idea to declare an <C>InfoClass</C> for your package. This  gives
the package user the opportunity  to  control  the  verbosity  of  output
and/or the possibility of receiving debugging information
(see&nbsp;<Ref Sect="Info Functions"/>).  Below,  we  give  a  quick
overview of its utility.
<P/>
An <C>InfoClass</C> is defined with  a  <C>DeclareInfoClass(  <A>InfoPkgname</A>  );</C>
statement and may be set to have an initial <C>InfoLevel</C>  other  than  the
zero default (which means no <C>Info</C> statement is to  output  information)
via a <C>SetInfoLevel( <A>InfoPkgname</A>, <A>level</A>  );</C>  statement.  An  initial
<C>InfoLevel</C> of 1 is typical.
<P/>
<C>Info</C> statements have the form:
<C>Info( <A>InfoPkgname</A>, <A>level</A>, <A>expr1</A>, <A>expr2</A>, ...);</C>
where  the  expression  list  <C><A>expr1</A>,  <A>expr2</A>,  ...</C>
appears just like it would in a <C>Print</C> statement. The only difference is
that the expression list is  only  printed  (or  even  executed)  if  the
<C>InfoLevel</C> of <A>InfoPkgname</A> is at least <A>level</A>.

</Section>



<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="The Banner">
<Heading>The Banner</Heading>

<Index Subkey="for a GAP package">banner</Index>

When the package is loaded, &GAP; will display a default package banner,
constructed from the package metadata provided in the <F>PackageInfo.g</F> file.
<P/>
Alternatively,
the package may establish its own banner by assigning either a string
to the <C>BannerString</C> field of the record argument of <C>SetPackageInfo</C>
in the <F>PackageInfo.g</F> file
or a function to the <C>BannerFunction</C> field,
which takes this record as its unique argument.
The latter possibility can be useful if the banner shall show information
that is available only at runtime.
<P/>
If you will be designing a banner for your package, it is a good idea to suggest
there how to access package  documentation. For example, the banner of the
<Package>Example</Package> package says:
<P/>
<Log><![CDATA[
For help, type: ?Example package
]]></Log>
<P/>
In order for this to display the introduction of the
<Package>Example</Package>  package the index-entry
<C>&tlt;Index&tgt;Example package&tlt;/Index&tgt;</C>
was added just before the first paragraph of the introductory section  in
the file <F>doc/example.xml</F> of the <Package>Example</Package> package.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Version Numbers">
<Heading>Version Numbers</Heading>

<Index Subkey="for a GAP package">version number</Index>
Version numbers are strings containing nonnegative integers separated
by non-numeric characters. They are compared by
<Ref Func="CompareVersionNumbers"/>
which first splits them at non-digit characters and then lexicographically
compares the resulting integer lists.
Thus version <C>"2-3"</C> is larger than version <C>"2-2-5"</C>
but smaller than <C>"4r2p3"</C> or <C>"11.0"</C>.
<P/>
It  is  possible  for  code  to require  &GAP;  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, <E>not</E> one with a
larger version number) can be achieved by prepending <C>=</C> to the desired
version number.
For example, <C>LoadPackage( "example", "=1.0" )</C> will load version
<C>"1.0"</C> of the package <C>"example"</C>,
even if version <C>"1.1"</C> is available.
As a consequence, version numbers must not start with <C>=</C>,
so <C>"=1.0"</C> is not a valid version number.
<P/>
Package authors should choose a version numbering scheme that admits a
new  version  number even  after  tiny  changes  to the  package, and
ensure that  version  numbers  of  successive  package  versions increase.
The automatic update of package archives in the  &GAP; distribution will
only work if a package has a new version number.
<P/>
It is a well-established custom to name package archives like
<F>name-version.tar.gz</F>, <F>name-version.tar.bz2</F> etc.,
where <C>name</C> is the lower case name, and <C>version</C> is
the version (another custom is that the archive then should extract
to a directory that has exactly the name <F>name-version</F>).
<P/>
It is very important that there should not ever be, for a given &GAP;
package, two different archives with the same package version number.
If you make changes to your package and place a new archive of the
package onto the public server, please ensure that a new archive has
a new version number. This should be done even for very minor changes.
<P/>
For most of the packages it will be inappropriate to re-use the date
of the release as a version number. It is much more obvious how big are
the changes between versions "4.4.12", "4.5.1" and "4.5.2" than between
versions "2008.12.17", "2011.04.15" and "2011.09.14". The concept of
using version numbers to convey the meaning of the status of the code
and the way it has been modified is known as <Q>Semantic Versioning</Q>,
see <URL>https://semver.org/</URL> for further recommendations on its use.
<P/>
Since version information is duplicated in several places throughout the
package documentation, for &GAPDoc;-based manuals you may define the
version and the release manual in the comments in <F>PackageInfo.g</F>
file close to the place where you specified its <C>Version</C> and
<C>Date</C> components, for example
<Log><![CDATA[
##  <#GAPDoc Label="PKGVERSIONDATA">
##  <!ENTITY VERSION "3.3">
##  <!ENTITY RELEASEDATE "12/09/2017">
##  <!ENTITY RELEASEYEAR "2017">
##  <#/GAPDoc>
]]></Log>
notify <Ref Func="MakeGAPDocDoc" BookName="gapdoc"/> that a part of the
document is stored in <F>PackageInfo.g</F> (see <F>example/makedocrel.g</F>),
read this data into the header of the main document via
<C>&lt;#Include Label="PKGVERSIONDATA"></C> directive and then use them via
&amp;VERSION; and &amp;RELEASEDATE; entities almost everywhere where you
need to refer to them (most commonly, in the title page and installation
instructions).

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Testing a GAP package">
<Heading>Testing a &GAP; package</Heading>

There are several aspects of testing a &GAP; package.
<P/>
First, one should ensure that the package functionality works as expected.
Below we give an advice on creating test files for automated tests that may
be run by package authors, by &GAP; developers as part of the release
preparation, and by package users interested in checking that the package
works. Such tests should be included in the package distribution, and the
responsibility for ensuring that they pass stays with package authors.
<P/>
Second, the package should cleanly integrate into the &GAP; system and other
packages, and should not break their functionality. In particular, all tests
from the standard &GAP; testing suite should pass if the package is loaded.
This is more comprehensive and time consuming test, which &GAP; developers
regularly run using special tools. They will report to you any detected issues.
Below we explain how to do several simple and less time consuming checks
which package authors are recommended to perform themselves.

<Subsection Label="Tests files for a GAP package">
<Heading>Tests files for a GAP package</Heading>

The (optional) <F>tst</F> directory of your package may contain as
many tests of the package functionality as appears appropriate. These tests
should be organised into test files similarly to those in the <F>tst</F>
directory of the &GAP; distribution as documented in
<Ref Sect="Test Files"/>.
<P/>
For a deposited package, a test file with a basic test of the package
(for example, to check that it works as expected and/or that the manual
examples are correct) may be specified in the component <C>TestFile</C>
in the <F>PackageInfo.g</F> to be included in the &GAP; standard test suite.
This file can either consist of calls of <Ref Func="TestDirectory"/> or
<Ref Func="Test"/> (in this case, it is common to call it <F>testall.g</F>)
or be itself a test file having an extension <F>.tst</F> and supposed to be
read via <Ref Func="Test"/>. It is assumed that the
latter case occurs if and only if the file contains the substring<P/>
&nbsp;<C>"gap> START_TEST("</C>
<P/>
<Alt Only="LaTeX">\noindent</Alt>
(with exactly one space after the &GAP; prompt).
<P/>
For deposited packages, these tests are run by the &GAP; Group regularly,
as a part of the standard &GAP; test suite. For the efficient testing it
is important that the test specified in the <F>PackageInfo.g</F> file
does not display any output (e.g. no test progress indicators) except
reporting discrepancies if such occur and the completion report as
in the example below:
<Log><![CDATA[
gap> Test("tst/testall.tst");
Example package: testall.tst
true
]]></Log>
Tests which produce extended output and/or require substantial runtime
are not supposed to be a part of the &GAP; standard test suite but may
be placed in the <F>tst</F> directory of the packages with further
instructions on how to run them elsewhere.
<P/>
Because of different approaches to testing, used by different packages,
it is not always easy to identify whether an automated test passed or failed.
Presently, automated detection works fine if a package uses a single
<F>.tst</F> file or uses <Ref Func="TestDirectory"/> with the <C>exitGAP</C>
option set to <K>true</K> to run a collection of tests and then exits &GAP;
in a way that allows an automated test setup to determine whether the test passed or failed:
<Log><![CDATA[
TestDirectory(DirectoriesPackageLibrary("packagename", "tst"), rec(exitGAP := true));
]]></Log>
If one needs a more sophisticated test file, then it should end with an invocation
of <Ref Func="ForceQuitGap"/> with an argument that indicates whether the tests overall
passed (<K>true</K>) or failed (<K>false</K> or <K>fail</K>). For example,
if the test result is stored in a variable <C>testresult</C> then you can do this:
<Log><![CDATA[
ForceQuitGap(testresult);
]]></Log>
</Subsection>


<Subsection Label="Testing GAP package loading">
<Heading>Testing &GAP; package loading</Heading>

To test that your package may be loaded into &GAP; without any problems
and conflicts with other packages, test that it may be loaded in various
configurations:
<List>
<Item>
starting &GAP; with no packages (except needed for &GAP;) using <C>-r -A</C> options
and calling <C>LoadPackage("packagename");</C>
</Item>
<Item>
starting &GAP; with no packages (except needed for &GAP;) using <C>-r -A</C> options
and calling <C>LoadPackage("packagename" : OnlyNeeded );</C>
</Item>
<Item>
starting &GAP; in the default configuration (with no options)
and calling <C>LoadPackage("packagename");</C>
</Item>
<Item>
starting &GAP; in the default configuration (with no options)
and calling <C>LoadPackage("packagename" : OnlyNeeded );</C>
</Item>
<Item>
finally, together with all other packages using
<Ref Func="LoadAllPackages"/> (see below) in four possible combinations
of starting &GAP; with/without <C>-r -A</C> options and calling
<Ref Func="LoadAllPackages"/> with/without <C>reversed</C> option.
</Item>
</List>
The test of loading all packages is the most subtle one. Quite often
it reveals problems which do not occur in the default configuration
but may cause difficulties to the users of specialised packages.
<P/>
Additionally, we recommend using <Ref Func="ShowPackageVariables"/> to
see information about variables created by your package to check if any
have either short names (no more than three characters) or names breaking a
recommended naming convention that the &GAP; core system. &GAP; packages also
should not use global variables starting in the lowercase
(see Section <Ref Sect="Functions and Variables and Choices of Their Names"/>).
</Subsection>

<ManSection>
<Func Name="LoadAllPackages" Arg=": reversed"/>
<Description>
loads all &GAP; packages from their list sorted in alphabetical order
(needed and suggested packages will be loaded when required). This is a
technical function to check packages compatibility, so it should NOT be
used to run anything except tests; it is known that &GAP; performance is
slower if all packages are loaded. To introduce some variations of the
order in which packages will be loaded for testing purposes,
<Ref Func="LoadAllPackages"/> accepts option <C>reversed</C> to load
packages from their list sorted in the reverse alphabetical order.
</Description>
</ManSection>


<Subsection Label="Testing a GAP package with the GAP standard test suite">
<Heading>Testing a &GAP; package with the &GAP; standard test suite</Heading>

The <F>tst</F> directory of the &GAP; installation contains a selection of
test files and scripts such as <F>testinstall.g</F> and <F>teststandard.g</F>
which are a part of the &GAP; standard test suite.
<P/>

It is important to check that your package does not break &GAP; standard
tests. To perform a clean test and avoid interfering with other packages,
first you must start a new &GAP; session and then read either <F>testinstall.g</F>
or <F>teststandard.g</F> as demonstrated below.
<P/>

The quicker test, <F>testinstall.g</F>, should run in about a minute depending
on your hardware speed. It may be started with the command
<Log><![CDATA[
gap> Read( Filename( DirectoriesLibrary( "tst" ), "testinstall.g" ) );
]]></Log>
You will get a large number of lines with output about the progress of
the tests, for example:
<Log><![CDATA[
You should start GAP4 using `gap -A -x 80 -r'.

Architecture: SOMETHING-SOMETHING-gcc-default64

testing: ..../gap-4.X.Y/tst/testinstall/alghom.tst
      84 ms (55 ms GC) and 2.90MB allocated for alghom.tst
testing: ..../gap-4.X.Y/tst/testinstall/algmat.tst
     839 ms (114 ms GC) and 219MB allocated for algmat.tst
[ further lines deleted ]
testing: ..../gap-4.X.Y/tst/testinstall/zmodnze.tst
     127 ms (119 ms GC) and 1.29MB allocated for zmodnze.tst
-----------------------------------
total     62829 ms (24136 ms GC) and 8.61GB allocated
              0 failures in 252 files

#I  No errors detected while testing
]]></Log>
<P/>

(optionally, you may start &GAP; with the command line options which you
will see in the test output, to run it in a more conservative settings).
<P/>

The more thorough test is <F>teststandard.g</F> which exercises more of &GAP;'s
capabilities, also including all test files from <F>teststandard.g</F>.
It runs quite a bit longer, maybe 10-20 minutes, and produces
an output similar to the testinstall.g test.
To run it, also start a new &GAP; session and then call
<Log><![CDATA[
gap> Read( Filename( DirectoriesLibrary( "tst" ), "teststandard.g" ) );
]]></Log>
You may repeat the same check loading your package with <C>OnlyNeeded</C>
option. Remember to perform each subsequent test in a new &GAP; session.
<P/>
Also you may perform individual tests from the <F>tst</F> directory of the
&GAP; installation loading them with <Ref Func="Test"/>.
<P/>

</Subsection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Access to the GAP Development Version">
<Heading>Access to the &GAP; Development Version</Heading>

We are aiming at providing a stable platform for package development and
testing with official &GAP; releases. We also invite everyone to contribute
by submitting patches, pull requests, and bug reports. We would like to
make the contributing process as easy as possible.
<P/>
The main GAP development repository is hosted on GitHub at
<URL>https://github.com/gap-system/gap</URL>. Many &GAP; packages
also have public repositories and issue trackers, and we are keeping
a list of such packages at <URL>https://gap-packages.github.io/</URL>.
<P/>
For further information about contributing to the GAP development, please see
<URL>https://github.com/gap-system/gap/blob/master/CONTRIBUTING.md</URL>.
</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Version control and continuous integration for GAP packages">
<Heading>Version control and continuous integration for &GAP; packages</Heading>

As we have mentioned above, many &GAP; packages have public repositories and
issue trackers on GitHub, and we are keeping a list of such packages at
<URL>https://gap-packages.github.io/</URL>. We welcome establishing public
repositories for new packages and migrating existing package repositories
there as well. Such repositories may be hosted under their authors' accounts
or under the gap-packages organisation (<URL>https://github.com/gap-packages/</URL>).
The latter has the benefit that while the authors will preserve their deciding
role on all aspects of the package development, the package will become more
visible for potential collaborators and &GAP; developers may help to set up
<E>continuous integration</E> for your package so that every commit to the
repository will trigger automated running of package tests and reporting any
failures to package maintainers.
</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Selecting a license for a GAP Package">
<Heading>Selecting a license for a &GAP; Package</Heading>

As it was mentioned in the description of the <F>LICENSE</F> file in
Section <Ref Sect="Structure of a GAP Package"/>,
it is advised to make clear in the documentation of the package the basis
on which it is being distributed to users. &GAP; itself is distributed under
the GNU Public License version 2 (version 2 or later). We would encourage
you to consider the GPL license for your packages, but you might wish to be more
restrictive (for instance forbidding redistribution for profit) or less
restrictive (allowing your software to be incorporated into commercial
software). See <Q>Choosing a License for the Distribution of Your Package</Q>
from <URL>https://www.gap-system.org/Packages/Authors/authors.html</URL> and also
<URL>https://choosealicense.com/</URL> for further details.
<P/>

In the past many &GAP; packages used the text
<Q>We adopt the copyright regulations of &GAP; as detailed in the copyright
notice in the &GAP; manual</Q> or a similar statement. We now advise to be
more explicit by making the exact reference to the GPL license, for example:
<P/>
<E>
<Package>packagename</Package> is free software; you can redistribute it
and/or modify it under the terms of the
<URL Text="GNU General Public License">https://www.fsf.org/licenses/gpl.html</URL>
as published by the Free Software Foundation; either version 2 of the License,
or (at your option) any later version.
</E>
and also including a copy of the full text of the license.

</Section>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Releasing a GAP Package">
<Heading>Releasing a GAP Package</Heading>

The &GAP; distribution provides archives in several different formats.
<P/>
<List>
<Mark><F>.tar.gz</F></Mark>
<Item>
  a standard UNIX <C>tar</C> archive, compressed with <C>gzip</C>
</Item>
<Mark><F>.tar.bz2</F></Mark>
<Item>
  a standard UNIX <C>tar</C> archive, compressed with <C>bzip2</C>
</Item>
<Mark><F>.zip</F></Mark>
<Item>
  an archive in <C>zip</C> format, where text files should have
  UNIX style line breaks
</Item>
</List>
<P/>
For convenience of possible users it is sensible that you provide an
archive of your package in at least one of these formats.
<P/>
For example, if you wish to supply a <F>.tar.gz</F> archive,
you may create it with the command
<P/>
&nbsp;<C>tar -cvzf packagename-version.tar.gz packagename</C>
<P/>
<Alt Only="LaTeX">\noindent</Alt>
Because the release of the &GAP; package is independent of the version
of &GAP;, a &GAP; package should be wrapped up in separate file that
can be installed onto any version of &GAP;. In this way, a package can
be upgraded any time without the need to wait for new &GAP; releases.
To ensure this, the package should be archived from the &GAP; <F>pkg</F>
directory, that is all files are archived with the path starting at the
package's name.
<P/>
<Index Key="GAPDocManualLab"><C>GAPDocManualLab</C></Index>
The archive of  a &GAP; package should contain all  files necessary for the
package to  work. In  particular there should  be a  compiled documentation,
which includes the <F>manual.six</F>, <F>manual.toc</F> and <F>manual.lab</F>
file in the
documentation subdirectory which are created by &GAPDoc; while &TeX;ing
the documentation.
(The first two files are needed by the &GAP; help system,
and the <F>manual.lab</F> file is needed if the main manuals or another
package is referring to your package.
Use the command <C>GAPDocManualLab( packagename );</C> to create this file
for your help books if you use &GAPDoc;.)
<P/>

Note that wrapping the &GAP; distribution as a single archive containing
the core system and all currently redistributed packages, will change
file timestamps, so one should not rely on them anywhere in the package.
<P/>

For packages hosted on GitHub publishing package release and establishing its
website can be very efficiently automated using two tools:
ReleaseTools (<URL>https://github.com/gap-system/ReleaseTools</URL>) and
GitHubPagesForGAP (<URL>https://github.com/gap-system/GitHubPagesForGAP</URL>).

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="The homepage of a Package">
<Heading>The homepage of a Package</Heading>

If you want to distribute your package you should create its homepage containing
some basic information, archives for download,
the <F>README</F> file with installation  instructions,
and a copy of the package's <F>PackageInfo.g</F> file.
<P/>
The responsibility to maintain this homepage is with the package
authors/maintainers.
<P/>
If you tell the &GAP; Group about your package
(say, by mail to <Email>support@gap-system.org</Email>)
we may consider either
<List>
<Item>
adding a link to your package homepage from the &GAP; website
(thus, the package will be an <E>undeposited contribution</E>);
</Item>
<Item>
or redistributing the current version of your package as a part of
the &GAP; distribution (this, the package will be <E>deposited</E>),
also ;
</Item>
</List>
Please also consider submitting your package to the &GAP; package refereeing
process (see <URL>https://www.gap-system.org/Contacts/submit.html</URL> for
further information).
<P/>
For packages hosted on GitHub publishing package release and establishing its
website can be very efficiently automated using two tools:
GitHubPagesForGAP (<URL>https://github.com/gap-system/GitHubPagesForGAP</URL>)
and ReleaseTools (<URL>https://github.com/gap-system/ReleaseTools</URL>).

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Some things to keep in mind">
<Heading>Some things to keep in mind</Heading>

<List>

<Item>
Some packages still use for their manuals the old <Q>gapmacro</Q> format,
support for which may be discontinued in the future. We encourage authors
of those packages to eventually convert their documentation &GAPDoc;.
New packages are recommended to use &GAPDoc;, which, for example, is
capable of creating HTML documentation with MathJax support, allows
easy extraction of examples from documentation for testing, etc. One could
also use the <Package>AutoDoc</Package> which simplifies writing documentation
by generating most of the &GAPDoc; code automatically.
</Item>

<Item>
The concept of an autoloaded package, which existed before &GAP;&nbsp;4.5,
has been integrated with the <E>needed</E>
and <E>suggested</E> mechanism that exists between packages. &GAP; itself
now <Q>needs</Q> certain packages (for instance &GAPDoc;) and <Q>suggests</Q> others
(typically the packages that were autoloaded). The decisions
which packages &GAP; should need or suggest are made by developers based on
technical criteria. They can be easily overridden by a user
using the new <F>gap.ini</F>
(see <Ref Sect="sect:gap.ini"/>).
The default file ensures that all formerly autoloaded packages are
still loaded if present.
</Item>

<Item>
Optional <F>~/.gap</F> directory for user's customisations which may
contain e.g. locally installed packages (see <Ref Sect="GAP Root Directories"/>).
If package installation instructions explain how to install the package in a
non-standard location, they should mention this.
</Item>

<Item>
Packages loading mechanism allows to make loading packages more
informative, while avoiding confusing the user with warning and error
messages for packages they didn't know they were loading.
For example, many messages are stored but not
displayed using the function <Ref Func="LogPackageLoadingMessage"/>
and there is a function <Ref Func="DisplayPackageLoadingLog"/>
to show log messages that occur during package loading.
Packages are encouraged to use these mechanisms to report
problems in loading (e.g. binaries not compiled),
rather than printing messages directly.
</Item>

</List>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Package release checklists">
<Heading>Package release checklists</Heading>

The following checklists should be useful to package authors and maintainers, as
well as to everyone involved in the depositing and refereeing of &GAP; packages.

<Subsection Label="Checklist for releasing a new package">
<Heading>Checklist for releasing a new package</Heading>

<List>

<Item>
    Test that the package:
    <List>
    <Item>
    does not break <F>testinstall.g</F> and <F>teststandard.g</F>,
    and does not slow them down noticeably
    (see <Ref Label="Testing a GAP package with the GAP standard test suite"/>);
    </Item>
    <Item>
    may be loaded in various configurations (see <Ref Label="Testing GAP package loading"/>);
    </Item>
    <Item>
    follows the guidelines of Section
    <Ref Label="Functions and Variables and Choices of Their Names"/>
    about names of functions and variables;
    </Item>
    </List>
</Item>

<Item>
    <F>PackageInfo.g</F> file:
    <List>
    <Item>
        correctly specifies package version, release date, and package authors;
    </Item>
    <Item>
        passes validation using <Ref Func="ValidatePackageInfo"/>;
    </Item>
    <Item>
        besides mandatory components, which are required to pass validation,
        also has relevant optional components (such as, for example, URLs of
        public source code repository and issue tracker; hints to distinguish
        binary and text files in case of non-standard file names and extensions,
        etc.);
    </Item>
    </List>
</Item>

<Item>
    Package documentation:
    <List>
    <Item>
        is built and included in the package archive together with
        its source files;
    </Item>
    <Item>
        states the same version, release date and package authors
        as specified in the <F>PackageInfo.g</F> file;
    </Item>
    <Item>
        has the same version, release date and package authors
        details as stated in the <F>PackageInfo.g</F> file;
    </Item>
    <Item>
        is searchable using the &GAP; help system in all formats
        (text, HTML and PDF);
    </Item>
    <Item>
        is clear about the license under which the package is distributed,
        and refers to the <F>LICENSE</F> file which should be included in
        the package;
    </Item>
    </List>
</Item>


<Item>
    Package archive(s):
    <List>
    <Item>
        have correct permissions for all files and directories after their
        unpacking (755 for directories and executables, if any; 644 for other
        files);
    </Item>
    <Item>
        contain files with correct line breaks for the given format
        (see Section <Ref Sect="Releasing a GAP Package"/>);
    </Item>
    <Item>
        contain no hidden system files and directories that are not supposed
        to be included in the package, e.g. <F>.gitignore</F>,
        <F>.git</F> etc.;
    </Item>
    </List>
</Item>

<Item>
    Package availability:
    <List>
    <Item>
        not only the package archive(s), but also the
        <F>PackageInfo.g</F> and <F>README</F> files
        are available online;
    </Item>
    </List>
</Item>

</List>

</Subsection>

<Subsection Label="Checklist for upgrading the package for the next major release of GAP">
<Heading>Checklist for upgrading the package for the next major release of &GAP;</Heading>

&GAP; ecosystem is not static: both the core &GAP; system and packages
redistributed with &GAP; are in constant development. &GAP; has a policy
that changes that may have a disruptive effect on packages redistributed
with &GAP; should only be introduced in major &GAP; releases. When the next
&GAP; major release is prepared, a beta version for package authors will be
made available in order to give them an opportunity to check and update,
if necessary, their packages for the public release of the next major version
of &GAP;.
<P/>

The following checklist will help you to check how well your package is
ready to work with the next major release of &GAP;
<P/>

<List>

<Item>
Check that the package functionality works as expected,
package tests run with no discrepancies, and manual examples
correspond to new version of &GAP;. This is a convenient opportunity
to polish existing and add new tests, and improve manual examples.
</Item>

<Item>
Revise package dependencies: check that the <F>PackageInfo.g</F> file
has correct list of needed and suggested packages
(see Section <Ref Label="Package dependencies"/>).
</Item>

<Item>
Revise licensing information:
check that the package states clearly under which conditions it is distributed
and includes a <F>LICENSING</F> file with the text of a license
(see Section <Ref Label="Selecting a license for a GAP Package"/>).
</Item>

<Item>
Rebuild the package documentation to update cross-references to main &GAP;
manuals and, if relevant, to the documentation of other &GAP; packages.
This will ensure that cross-references from the package manual to the main &GAP;
manuals are correct and that the &GAP; help system will be able to navigate to
the more precise location in the package manual. This will also improve the layout of
the package documentation by picking up the changes in documenting tools.
</Item>

<Item>
Check if the package still relies on some obsolete variables
(see Chapter <Ref Chap="Replaced and Removed Command Names"/>)
and replace their usage by the new commands. To perform such check, start &GAP;
with `-O` command line option to disable loading obsoletes, and then load
your package.
</Item>

<Item>
Check for any specific advice in release notes for the beta release for
package authors.
</Item>

</List>

</Subsection>

</Section>

</Chapter>