From 082062ec3d377885848b0a003b5cb8a0263796e7 Mon Sep 17 00:00:00 2001 From: Alexander Konovalov Date: Sat, 11 Mar 2017 18:00:14 +0000 Subject: [PATCH] Minor rewrites and numerous TODOs in package guidance --- doc/ref/gappkg.xml | 173 ++++++++++++++++++++++++++++++++------------- 1 file changed, 123 insertions(+), 50 deletions(-) diff --git a/doc/ref/gappkg.xml b/doc/ref/gappkg.xml index e94b2c4d1e..28ad40b43b 100644 --- a/doc/ref/gappkg.xml +++ b/doc/ref/gappkg.xml @@ -32,11 +32,19 @@ In this chapter we describe how to use existing packages.
Installing a GAP Package -Before a package can be used it must be installed. With a standard -installation of ⪆ there should be all currently redistributed with -⪆ packages already available. But since ⪆ packages are released -independently of the main ⪆ system it may be sensible to upgrade -or install new packages between upgrades of your ⪆ installation. +Before a package can be used it must be installed. A standard +installation of ⪆ already contains all currently redistributed with +⪆ packages. Such combination of packages is checked for compatibility +with the system and other packages during release preparation. Most of +the packages can be used immediately, but some of them may require further +installation steps such as compilation or installing additional software +to satisfy their dependencies. Most of the packages that require compilation +will be compiled in a single step by changing to the pkg directory +of your ⪆ installation and calling ../bin/BuildPackages.sh script. +

+Also, since ⪆ packages are released independently of the main ⪆ system, +sometimes it may be sensible to upgrade or install new packages between +upgrades of your ⪆ installation.

A package consists of a collection of files within a single directory that must be a subdirectory of the pkg directory in one of the @@ -67,6 +75,9 @@ Some &GAP; packages are prepared for automatic loading, that is they will be loaded automatically with &GAP;, others must in each case be separately loaded by a call to . + <#Include Label="LoadPackage"> <#Include Label="SetPackagePath"> @@ -81,7 +92,10 @@ others must in each case be separately loaded by a call to Functions for GAP Packages The following functions are mainly used in files contained in a -package and not by users of a package. +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. <#Include Label="ReadPackage"> <#Include Label="TestPackageAvailability"> @@ -151,9 +165,8 @@ no effect, even if the file on disk has changed. Each package has the file PackageInfo.g which contains meta-information about the package (package name, version, author(s), relations to other packages, -homepage, download archives, banner, etc.). This file is used by the package -loading mechanism and also for the distribution of a package to other -users. +homepage, download archives, etc.). This file is used by the package +loading mechanism and also for the redistribution of a package with &GAP; <#Include Label="ValidatePackageInfo"> @@ -167,7 +180,7 @@ users. Guidelines for Writing a GAP Package The remaining part of this chapter explains the basics -of how to write a &GAP; package so that it interfaces properly to &GAP;. +of how to write a &GAP; package so that it integrates properly into &GAP;.

There are two basic aspects of creating a &GAP; package. @@ -179,7 +192,7 @@ a package is a way to make your code available to other &GAP; users.

Moreover, the &GAP; Group may provide some help with redistributing your -package via the web and ftp site of &GAP; itself after checking if the +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 @@ -197,8 +210,7 @@ for more details. 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, wrapping and -distribution. +we provide guidelines for the release preparation and its distribution.

@@ -207,6 +219,8 @@ distribution.
Structure of a GAP Package + + home directory A &GAP; package should have an alphanumeric name (package-name, say); mixed case is fine, but there should be no whitespaces. @@ -214,7 +228,7 @@ All files of a &GAP; package package-name must be collected in a single directory package-dir, where package-dir should be just package-name preferably converted to lowercase and optionally followed by the package version (with or without hyphen to separate the -version from package-name). +version from package-name). Let us call this directory the home directory of the package.

To use the package with &GAP;, the directory package-dir must @@ -235,11 +249,12 @@ package-dir/ lib/ src/ tst/ - README CHANGES - configure + LICENSE + README Makefile.in PackageInfo.g + configure init.g read.g ]]> @@ -257,16 +272,19 @@ We now describe the above files and directories: README README -This should contain how to get it (from the &GAP; ftp- and -web-sites) instructions, as well as installation instructions and names -of the package authors and their email addresses. The installation -instructions should be repeated in the package's documentation, which -should be in the doc directory +This should contain how to get it 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 doc directory (see ). Authors' names and addresses should be repeated both in the package's documentation and in the PackageInfo.g (see below). + + CHANGES @@ -275,6 +293,13 @@ For further versions of the package, it will be also useful to have a of the package. + +LICENSE + +The file which explains conditions on which the package is distributed. + + + configure, Makefile.in These files are only necessary if the package has a non-&GAP; component, @@ -298,9 +323,9 @@ end up in this subdirectory of bin. PackageInfo.g Since &GAP; 4.4, a &GAP; package must have a PackageInfo.g file which contains meta-information about the package (package name, version, -author(s), relations to other packages, homepage, download archives, banner, -...). This information is used by the package loading mechanism and also for -the distribution of a package to other users. The Example package's +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 Example package's PackageInfo.g file is well-commented and should be used as a prototype (see also for further details). @@ -347,9 +372,10 @@ which is used for the &GAP; documentation. An alternative is to use the &TeX;-based system, formerly used for the &GAP; documentation in &GAP; 4.4 and earlier releases. This system is described in the document The gapmacro.tex Manual Format -(the file gap4r5/doc/gapmacrodoc.pdf included in the +(the file gap4rN/doc/gapmacrodoc.pdf included in the tools archive as described in Section ) + and is still used by some of the &GAP; packages whose authors are encouraged to switch at some point to the &GAPDoc;-based documenation. Please spend some time reading the documentation for whichever @@ -357,7 +383,7 @@ system you decide to use for writing your package's documentation. The Example package's documentation is written in the XML format supported by the GAPDoc package. If you intend to use this format, please use the Example -package's doc directory as a prototype, which as you will observe +package's doc directory as a prototype, which, as you will observe, contains the master file main.xml, further .xml files for manual chapters (included in the manual via Include directives in the master file) and the &GAP; input file ../makedocrel.g which @@ -381,7 +407,7 @@ word Example with package-name. --> This is the preferred place for the &GAP; code, i.e. the .g, .gd and .gi files (other than PackageInfo.g, init.g and read.g). For some packages, the directory gap has been used instead of lib; lib has the -slight advantage that it is the default subdirectory of a package directory +advantage that it is the default subdirectory of a package directory searched for by the command. @@ -397,11 +423,12 @@ library modules or external programs which is explained in tst -If the package has test files, then they should go in the tst -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 -PackageInfo.g to be included in the &GAP; standard test suite. +It is highly recommended that a package should have test files, which then +should go in the tst 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 +PackageInfo.g 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 tst directory with further instructions on how to run them. @@ -426,11 +453,13 @@ redistribution. Concerning the &GAP; code in packages, it is recommended to use only documented &GAP; functions, see . In particular if you want to make your package available to other &GAP; users -it is advisable to avoid using obsolescent variables -(see ). -For that, you can set the ReadObsolete component in your -gap.ini file to false, -see . +it is advisable to avoid using obsolete variables +(see ). To test that +the package does not use obsolete variables you can set the ReadObsolete +component in your gap.ini file to false (see +) or start &GAP; with -O command line +option (this may also cause problems with loading other packages using +obsolete variables).

@@ -442,7 +471,7 @@ 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.

-Concerning the installation you should produce a file README which +Concerning the installation you should produce a README 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. @@ -468,10 +497,12 @@ in the terminal running &GAP; and some nicely printable version in .pdf 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, but if you +to provide an HTML version of your package manual, + +but if you will either use the &GAPDoc; package or follow the guidelines in the document The gapmacro.tex Manual Format, -(the file gap4r5/doc/gapmacrodoc.pdf included in the +(the file gap4rN/doc/gapmacrodoc.pdf included in the tools archive as described in this Section below), you should have no trouble in producing one. Moreover, using the &GAPDoc; package, it is also possible to produce HTML version of the @@ -500,6 +531,7 @@ described below. If you intend to use the &GAPDoc; package for the documenation of your package, you may skip the rest of this section and proceed to the next one to see a minimalistic example of a &GAP; package.

+ tools archive for package authors Otherwise, to produce the .pdf manual formats, the following &GAP; tools (supplied as a part of the &GAP; distribution in the archive @@ -568,9 +600,11 @@ you need them.

An Example of a GAP Package -We illustrate the creation of a &GAP; package by an example of a basic package. + + +We illustrate the creation of a &GAP; package by an example of a very basic package.

-Create the following directories in your home area: +Create the following directories in your home directory: .gap, .gap/pkg and .gap/pkg/test. Then inside the directory .gap/pkg/test create an empty file init.g, and a file PackageInfo.g with the following contents: @@ -632,7 +666,7 @@ installation which is not only of local scope is separated by a header.

Historically, when the &GAP; main manuals were based on the &TeX; macros described in the document The gapmacro.tex Manual Format -(the file gap4r5/doc/gapmacrodoc.pdf included in the +(the file gap4rN/doc/gapmacrodoc.pdf included in the tools archive as described in Section ) such headers were used for the manuals and have the type @@ -1172,6 +1206,8 @@ details.

Standalone Programs in a &GAP; Package + + &GAP; packages that involve stand-alone programs are fundamentally different from &GAP; packages that consist entirely of &GAP; code.

@@ -1368,6 +1404,8 @@ that the expression list is only printed (or even executed) if the

The Banner + + banner Since &GAP; 4.4, the package banner, if one is desired, should be provided by assigning a string to the BannerString field of the record @@ -1463,6 +1501,12 @@ read this data into the header of the main document via need to refer to them (most commonly, in the title page and installation instructions). + + + + + +
@@ -1510,6 +1554,10 @@ are not supposed to be a part of the &GAP; standard test suite but may be placed in the tst directory of the packages with further instructions on how to run them elsewhere. + + + + @@ -1617,7 +1665,7 @@ 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, - accepts version Reversed to load + accepts option Reversed to load packages from their list sorted in the reverse alphabetical order. @@ -1626,6 +1674,8 @@ packages from their list sorted in the reverse alphabetical order. Testing a &GAP; package with the &GAP; standard test suite + + The tst directory of the &GAP; installation contains a selection of test files and two scripts, testinstall.g and testall.g which are a part of the &GAP; standard test suite. @@ -1688,6 +1738,8 @@ for example, the file bugfix.tst.
Access to the &GAP; Development Version + + We are aiming at providing a stable platform for package development and testing with official &GAP; releases. However, when it may be of benefit to obtain access to the &GAP; development version, please contact the &GAP; @@ -1700,6 +1752,8 @@ team by mailing to support@gap-system.org.
Selecting a license for 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 @@ -1711,6 +1765,8 @@ from http://www.gap-system.org/Packages/Authors/authors.html for further details.

+ + In the past many &GAP; packages used the text We adopt the copyright regulations of &GAP; as detailed in the copyright notice in the &GAP; manual or a similar statement. We now advise to be @@ -1727,11 +1783,13 @@ or (at your option) any later version.

-
-Wrapping up a &GAP; Package +
+Releasing a GAP Package + + Currently, the &GAP; distribution provides archives in four different formats.

@@ -1752,7 +1810,7 @@ formats. -win.zip an archive in zip format, where text files should have - DOS/Windows style line breaks + Windows style line breaks

@@ -1765,12 +1823,14 @@ you may create it with the command  tar -cvzf package-name-version.tar.gz package-name

\noindent + The etc directory obtained from tools.tar.gz (described above in Section ) contains a file packpack which provides a more versatile packing-up script.

+ In the past, it was recommended that your &GAP; package should be packed with the zoo archiver. We do not redistribute .zoo archives since &GAP; 4.5, but we still accept package archives in .zoo @@ -1836,6 +1896,8 @@ before &GAP; defaults will be applied;

+ + The etc directory obtained from tools.tar.gz (described above in Section ) @@ -1863,6 +1925,8 @@ may be helpful. They are described in the comments to their source code.

The WWW Homepage of a Package + + If you want to distribute your package you should create a WWW homepage containing some basic information, @@ -1902,6 +1966,10 @@ further information).
Upgrading the package to work with &GAP; 4.5 + + Changes in &GAP; 4.5 from the packages perspective @@ -1923,6 +1991,7 @@ dynamically loaded modules (see http://www.gap-system.org/Download/ for &GAP; installation instructions). + The &GAP; documentation has been converted to the &GAPDoc; format and extensively reviewed. Now it has only two books: the Tutorial and the Reference Manual. @@ -2032,7 +2101,7 @@ The following checklist may be used by package authors, members of the Test that the package: - + does not break testinstall.g and testall.g and does not slow them down noticeably (see ); @@ -2087,6 +2156,7 @@ The following checklist may be used by package authors, members of the is validated using ; + @@ -2101,7 +2171,7 @@ The following checklist may be used by package authors, members of the contain files with correct line breaks for the given format - (see ); + (see ); contain no hidden system files and directories that are not supposed @@ -2121,7 +2191,7 @@ The following checklist may be used by package authors, members of the the URL of the PackageInfo.g file is validated using - the online tool available from + the online tool available from http://www.gap-system.org/Packages/Authors/authors.html; @@ -2131,6 +2201,9 @@ The following checklist may be used by package authors, members of the + Checklist for package upgrade to work with &GAP; 4.5