| GAP |
Main BranchesDownload Overview Data Libraries Packages Documentation Contacts FAQ GAP 3 |
SitemapNavigation Tree |
Information for GAP Package AuthorsIf 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 PackageThe GAP documentation contains two introductory chapters 74 and 4 on using and creating a GAP package, they include links to further manual sections.
The interface between GAP and a GAP
package consists of two or three files 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 package 'Example' for advice how to avoid such 'name clashes'. Do Not Change GAP's Behaviour in a PackageIt 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 UsersOnce 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 PackageAn 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
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 chapter
2
of the programmers reference manual. (Here, also copy your package in the
standard location Finally, you can develop your own solution, complying with the interfaces described in chapter 5 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 PackageWe 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 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). Please see licensing advice for further details. The Package Update MechanismSetup for Distribution
What you have to do to take part in the update mechanism is
also explained in the template
Updating a Package Distributed with GAPOnce your package is in the update system, you can publish updates as follows:
Online Check of a
|
|
The GAP Group Last updated: Wed Feb 24 21:04:24 2010 |
|