GAP

Main Branches

Downloads  Installation  Overview  Data Libraries  Packages  Documentation  Contacts  FAQ  GAP 3 

Information for GAP Package Authors

If you have written or are going to write programs which enhance the functionality of GAP in some area, you may consider organizing and maybe distributing your code in form of a GAP package. Here is a collection of information for package authors or maintainers. (You may also consult the package Example or just look what other package authors have done.)

Getting Started Writing a Package

The GAP documentation contains a chapter on using GAP packages. All advice on developing GAP packages has been consolidated in the Example package.

The interface between GAP and a GAP package consists of two or three files PackageInfo.g, init.g and read.g. The first of these contains meta information on a package for loading and (possibly) distribution. Probably the easiest way to create it is to fill out this PackageInfo.g template file (which has detailed comments on each entry). The latest version of this template may also be found in the Example package.

As the number of packages and library modules in GAP grows, it is important to try to avoid clashes where two independently developed pieces of code use the same global variable names in inconsistent ways. See the page Use of Global Variable Names as well as the subsection Functions and Variables and Choices of Their Names of the manual of the Example package for advice how to avoid such 'name clashes'.

Do Not Change GAP's Behaviour in a Package

It is generally a bad idea for a package to change the behaviour of the core functionality of GAP, as opposed to extending it, or implementing better algorithms to compute the same results. For instance, if you believe that you can improve the way some kind of GAP object is printed, then please suggest this improvement by an email to support@gap-system.org (by all means include your code), rather than simply implementing it in your package.

There are two reasons for this. Firstly, it can surprise users who may not even know they are using your package (perhaps some other package loaded it). Secondly, we have a variety of tools for testing GAP releases and they work much better if the output produced by "standard" GAP commands is the same with and without packages.

For similar reasons, we would also ask that packages refrain from assigning names to indeterminates, or otherwise changing the appearance of common objects.

Making Your Package Available to Other GAP Users

Once a package works and has documentation of its functionality, you should consider to distribute it for interested GAP users. Of course, you can just do it on your own, say via a web page. In this case we would like to hear about the availability of the package, please write a hint to support@gap-system.org.

Another possibility is to redistribute your package via the web and ftp site of GAP itself. If you want that, also contact us as just stated. The GAP Group will check if your 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 distribution update mechanism described below. It becomes a deposited package.

Please, check if your package would be appropriate for our refereeing process. If yes, we encourage you to submit it! After successful refereeing the package becomes an accepted package.

Writing Documentation for Your Package

An essential feature of any GAP package is that it should have documentation which works smoothly with GAP's on-line help. There are a number of possible ways of achieving this.

Firstly, and the way we recommend, you can use the GAPDoc package which allows you to write documentation in a concise and well-specified XML-like language. This documentation can then be processed using GAPDoc to produce on-line help, printed manuals and web pages. (To get machine independent cross-links in your documentation, copy your package in the standard location pkg/<pkgname> and use MakeGAPDocDoc with ../../.. as 5th argument.)

Alternatively, you can use the "traditional" GAP4 manual format, i.e. TeX with some additional macros, which, provided you use it carefully, can be processed directly by GAP as on-line help, processed by TeX for printing and processed by a perl script provided in the "tools" archive to make HTML. This format is partly documented in the document "The gapmacro.tex Manual Format" which is included in the ``tools'' archive contained in the etc directory of the GAP installation. (Here, also copy your package in the standard location pkg/<pkgname> when building the HTML version of your manual to get cross-links right.)

Finally, you can develop your own solution, complying with the interfaces described in chapter 84 of the programmers reference manual. There are certain technical issues with this approach, and we would advise you to contact us if you are considering it.

Choosing a License for the Distribution of Your Package

We would 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. GAP itself is distributed under the GNU General Public License version 2, a popular "free software" license which allows users to redistribute it freely under the same terms, and requires that any software which incorporates GAP (technically, any "derived work") 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).

Further advice could be found, for example, at choosealicense.com.

The Package Update Mechanism

Setup for Distribution

What you have to do to take part in the update mechanism is also explained in the template PackageInfo.g file mentioned above:

  • Set up a Web page for your package. There are no conditions how this has to look like. You may take an existing such page (like this) and adjust it for your package.
  • Produce an archive of your package in (at least) one of the formats mentioned here. (The update programs can produce the missing formats for you.)
  • Make this archive and as separate files the README (containing installation instructions) and the PackageInfo.g file accessible by copying them to your Web page or to an ftp-site. (Your PackageInfo.g contains the URLs of these files.)
  • Send the URL of your PackageInfo.g file to support@gap-system.org.

Updating a Package Distributed with GAP

Once your package is in the update system, you can publish updates as follows:

  • Create a new archive. Note that you must change the version number of your package. Don't forget to adjust the PackageInfo.g file and maybe other files to the new version number (the new number must be higher, as explained here). Also the name of the archive file must be different from previous names. (Just choose a name which contains the package name and the version number, like example-1.3.tar.gz.)
  • Copy the new archive and README to the URLs given in your PackageInfo.g file.
  • Copy the new PackageInfo.g file to the URL given in the previous PackageInfo.g file (this is where the update mechanism looks for new versions.)
  • Since publishing the update of your package involves some (small) human action, please inform support@gap-system.org about the update of your package.
  • After the next update of the GAP distribution, check if the new version of your package is included there and also listed on the GAP website.
  • We advise package authors to maintain an update "history", which documents the changes from one version to another. A good example is contained in the README file of the DESIGN package of Leonard Soicher.

Online Check of a PackageInfo.g File

GAP packages must contain a file PackageInfo.g in which meta-information is collected: package name, version, authors/maintainers with contact addresses, location of download archive(s), infos on provided manuals, ... This is used for loading a package into GAP and for a possible redistribution of a package via the GAP web and ftp sites.

See this template file for more details and if you want to create such a file for your package.

One basic check for such a file is provided by the command ValidatePackageInfo(filename); from within GAP (at least 4.4).

As further test you can type the URL of a PackageInfo.g file into this form. The file is then downloaded and several checks are applied to it. This should point out to you some common mistakes and hopefully give useful hints for possible improvements.

Of course, this cannot be perfect. There may be errors not detected by the script, and it may happen that the script complains about points you are actually satisfied with.

URL of your PackageInfo.g file:

Please, be patient, several programs have to be started for the check, and files must be downloaded, this can take a little time.

Adjusting Packages from Versions <4.5

The mechanisms for loading and updating packages as described on this page were first introduced with GAP 4.4 and then improved in GAP 4.5. Packages which worked with GAP version <4.4 needed a few adjustments, and hints how to achieve this were collected on this page. To make further use of features introduced in GAP 4.5, we refer to the Checklist for package upgrade to work with GAP 4.5 from the Example package.