Hints for GAP Package Authors

Changes of the GAP package interface in GAP 4.4

With the release of GAP 4.4 the package interface has been changed - unfortunately this leads to some small incompatibilities.

On this page we will briefly list some reasons for the changes and explain what you should do to make your package usable with GAP 4.4.

Furthermore we add some comments as to what you should change with your next update after GAP 4.4 has been released. This 2-step procedure cannot be avoided if you want to have a version which can run with GAP 4.3 and 4.4.

Finally we explain how you can take advantage of a new mechanism to (re)distribute your package via the GAP website.

We hope that you will find the necessary changes not too difficult and that you will enjoy the simplifications and improvements resulting from the changes. If you have further questions or need assistance don't hesitate to write to support@gap-system.org.

The two chapters in the GAP manuals on using and creating packages have been adjusted to these changes, see sections 74 and 4 in the Reference Manual and Programming Reference Manual respectively.

Summary

Here is a short TODO list. All points are explained in more detail below.

• create a PackageInfo.g file
• create a WWW homepage for the package
• copy an archive, the README and PackageInfo.g to the Web page
• send mail with URL of the PackageInfo.g to support@gap-system.org
• remove deprecated commands (DeclarePackge and similar, RequirePackage), change ...Pkg... commands to ...Package...

Why the changes?

We noticed several unpleasant problems concerning the package loading in GAP and the distribution of package code with the core GAP system. To mention a few:

• The code for the package loading mechanism (which has to take into account autoloading, command line parameters, order of loading in case of dependencies, ...) had grown very complicated and had become essentially non-maintainable.
• We became aware of the problem mentioned above because with the growing number of packages and their dependencies we detected strange effects with the package loading which were very difficult to resolve.
• We did not have any standard procedure so that package authors could notify the GAP Group of new package versions and to get someone (who?) to adjust the GAP web- and ftp-site systematically to new package versions.
• Vice versa: Before a GAP release it is a difficult task to make sure that of all the packages distributed via the GAP web/ftp-site the newest versions were collected and wrapped.
• So far, the GAP distribution contains two combined archives of ("accepted" and "deposited") packages, containing the package versions at the time of the last GAP release (modulo the problem just mentioned). So, some time after a release new standard GAP installations have tended to contain some outdated package versions.
• So far, basic meta-information about a package was difficult to collect systematically, e.g.: current version and release date, status, current contact information of the authors/maintainers, URL for archive of latest version, what is needed for an online version of the manual?, ... Such information was scattered in the init.g, README, package documentation, source code comments, web page(s), or even not available at all.

The basic idea to try to resolve all these problems at once was to introduce a file PackageInfo.g in the home directory of each package which contains all the meta-information as mentioned above.

Using this information for all installed packages the package loading mechanism is greatly simplified and the init.g files become much simpler.

Furthermore the meta-information allows the set up of an automatic procedure for a daily update of GAP's package overview webpage, package archives for redistribution and the combined package archives for convenient new installations of GAP including the latest package versions.

How to prepare existing packages for use with GAP 4.4?

To make your package loadable with GAP 4.4 you must create a "PackageInfo.g" file in the home directory of your package. Maybe the easiest way to do this is to take this PackageInfo.g file of the "Example" package as a template and to adjust the entries for your package. This template contains explanations of each entry, but if you strip the comments you see that it is not so long. (There is a utility in the development release: With 'ValidatePackageInfo( <filename> );' you can check your file.)

Then remove a possibly explicit statement for printing a package banner (or reading a banner.g file) in your init.g file.

That's it for the moment!

Nevertheless, you should be aware of further changes in GAP 4.4, the most important ones are explained in the next section. Otherwise your package could become unusable with GAP 4.5.

Note for users of the GAP4-dev version

Many of you have already produced a PackageInfo.g file during the development process of the new mechanisms. But maybe you have to adjust a few details which were changed or added recently:

• The file itself was called PkgInfo.g in the beginning, please rename it to PackageInfo.g.
• Similarly, look for entry names containing the substring "Pkg" and change these substrings to "Package".
• Change the strings "AutoLoad" to "Autoload" in record components.
• There is a new entry .Subtitle that should explain the package name in less than one line (for use with a default banner or on an overview Web page).
• There is a new possibility to specify the files for an online copy of a help book (so far one had to give an URL in the subentry .Archive of a .PackageDoc entry for a separate archive containing the documentation): Alternatively, you can now give a list .ArchiveURLSubset of file and directory names from the whole package archive.

How to adjust a package after the release of GAP 4.4?

There are further changes in GAP which will probably lead to little changes in most packages. In particular some functions and variable names are made obsolete and will be removed in GAP 4.5.

If you are happy with a new release of your package together with the GAP 4.4 release you may incorporate the changes explained here now. But then the package can no longer be used with the current version GAP 4.3.

With the new package loading mechanism the following commands become obsolete: "DeclarePackage", "DeclareAutoPackage", "DeclarePackageDocumentation", "DeclarePackageAutoDocumentation" and "RequirePackage". All the corresponding lines in your init.g file can be deleted. The new loading mechanism gets the information given in the arguments of these functions from equivalent information in the PackageInfo.g file. You don't need to load other packages explicitly any longer (see the .Dependencies entry in PackageInfo.g). Also, the availability test function (so far given as third argument in Declare(Auto)Package) does no longer need to test the availabitiy of other packages explicitly.

By the way, a package is now loaded explicitly with the new command "LoadPackage" (but, as said, you probably don't need this in your package code).

We noticed that the names of functions concerning packages were spelled inconsistently. We have now made all commands containing the substring "Pkg" obsolete and substituted them by the corresponding commands with the substring "Package". In particular the change from "ReadPkg" to the new "ReadPackage" is relevant for init.g and read.g files of most packages.

Some packages use certain (undocumented) global variables (for example, "VERSION", "BANNER", "QUIET", ..., see the file lib/obsolete.g in the pre-release for a complete list). All of these are obsolete now, their values are now stored as entries in a record named "GAPInfo". But maybe you just don't need these any longer with the new package loading.

With the new package loading mechanism the file pkg/ALLPKG becomes unnecessary. So, it doesn't need to be mentioned in README files or the documentation after the release of GAP 4.4.

Starting from GAP 4.4 there is also more freedom for file and directory names. Some packages already gave up the rule that file names should use only lowercase letters and be of length at most 8 with an extension of length at most 3. Longer filenames and mixed case spelling doesn't seem to be a problem any longer on all systems which allow to run GAP 4. Note, however, that the filenames must remain unique in case that they are converted to lowercase (for instande FileName.G and filename.g together are not allowed).
Also, the package directory name need no longer be the lower case version of the package name, e.g., one could now include the version number. (For example, the Example package could be in directory "pkg/Example-1.5" instead of "pkg/example".)

How to set up a package for the new archive update mechanism?

We are setting up the following service for package maintainers using an automatic update mechanism.

• List your package in an overview page on the GAP website.
• Provide an online version of the documentation of your package.
• Offer archives of your package for download in (currently) four formats from the GAP website (.zoo, .tar.gz, .tar.bz2, -win.zip).
• Also offer two combined archives of packages for easier installation (one containing the "accepted", that is refereed, packages and one containing further "deposited" packages.)

The best possibility to take part in this service is to submit your package to our formal refereeing system such that it becomes an "accepted" refereed package.

A package can become a "deposited" package upon agreement with the GAP Group. For this the package must load properly and not produce conflicts with other distributed packages, and it must contain a README file with installation instructions and a documentation of its functionality which is available via the GAP help system.

What you have to do to take part in the automatic update mechanism is also explained in the example 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 above. (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.)
• For the setup send the URL of your PackageInfo.g file to support@gap-system.org.

Once your package is in the update system, it is easy to publish updates of your package:

• 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. 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.
• Check if after a few days the GAP website has updated your package to the new version.