<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 pkg 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">
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<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.
<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.
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; 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 HTMLversion 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.
<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. 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 lib 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 doc
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 <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. 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. 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 <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 HTMLversion 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 HTMLversion 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 HTMLversion 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; 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.
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><#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. 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; 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. 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. 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. 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.
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/>
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 <Ref Label="Package dependencies"/>) being the actual &GAP; package.
<P/>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="Installation of GAP Package Binaries">
<Heading>Installation of &GAP; Package Binaries</Heading>
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
