diff --git a/doc/changes/changes45.xml b/doc/changes/changes45.xml index d28bef520c..539b8dabc6 100644 --- a/doc/changes/changes45.xml +++ b/doc/changes/changes45.xml @@ -627,7 +627,7 @@ In addition, there is now a better error management if package loading fails for packages that use the new functionality to log package loading messages (see -and the rest of the Chapter +and the rest of the Chapter which documents how to use ⪆ packages), and package authors are very much encouraged to use these logging facilities.

diff --git a/doc/ref/gappkg.xml b/doc/ref/gappkg.xml index af79b17ede..7fc1fd7bdd 100644 --- a/doc/ref/gappkg.xml +++ b/doc/ref/gappkg.xml @@ -1,14 +1,4 @@ - - - - - - - - - - - + Using and Developing GAP Packages package @@ -27,26 +17,37 @@ integrated into the ⪆ help system. All ⪆ users who develop new code are invited to share the results of their efforts with other ⪆ users by making the code and its documentation available in form of a package. -Information how to do this is available from the ⪆ Web pages +Information how to do this is available from the ⪆ website (https://www.gap-system.org) and in the ⪆ package Example (see https://www.gap-system.org/Packages/example.html). +

There are possibilities to get a package distributed together with ⪆ and it is possible to submit a package to a formal refereeing process.

-In this chapter we describe how to use existing packages. +In this chapter we first describe how to use existing packages, +and then provide guidelines for writing a ⪆ package.

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 ⪆ packages currently redistributed with +⪆. This set 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 +can be compiled in a single step by changing to the pkg directory of +your ⪆ installation and calling the ../bin/BuildPackages.sh script. +

+Also, since ⪆ packages are released independently of the main ⪆ system, +sometimes it may be useful to upgrade or install new packages between +upgrades of your ⪆ installation, e.g. if a new version of a package adds +new capabilities or bug fixes that you need.

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 @@ -73,10 +74,20 @@ be able to use some or all external binaries. automatic loading of GAP packages disable automatic loading -Some ⪆ packages are prepared for automatic loading, -that is they will be loaded automatically with ⪆, -others must in each case be separately loaded by a call to -. +If a package is not loaded, it may be loaded using +the function . +

+Some ⪆ packages are loaded automatically with ⪆. Those belong to +two categories: packages which are needed to start ⪆ (as of this writing, +the only such package is &GAPDoc;; their list is contained in +GAPInfo.Dependencies.NeededOtherPackages), and packages which are +loaded during ⪆ startup by default. The latter list may be obtained by +calling UserPreference("PackagesToLoad") and is customisable as +described in Section . +

+While &GAP; will not start if any of the packages from the former group is +missing, loading of the packages from the latter group may be suppressed by +using the -A command line option (see ). <#Include Label="LoadPackage"> <#Include Label="SetPackagePath"> @@ -91,7 +102,12 @@ 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. +You will find further information about their use in Section + and subsequent sections. <#Include Label="ReadPackage"> <#Include Label="TestPackageAvailability"> @@ -161,9 +177,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"> @@ -177,7 +192,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. @@ -189,26 +204,25 @@ 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 +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 deposited package.

Furthermore, package authors are encouraged to check if the package would be appropriate for the refereeing process and submit it. If the -refereeing has been successful, the package becomes an accepted -package. Check out the &GAP; Web site http://www.gap-system.org -for more details. +refereeing has been successful, the package becomes an accepted package. +Check out https://www.gap-system.org/Packages/Authors/authors.html +on the &GAP; website for more details.

-We start with a description how the directory structure of a +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, wrapping and -distribution. +we provide guidelines for the release preparation and its distribution.

@@ -218,47 +232,66 @@ 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. -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 +A &GAP; package should have an alphanumeric name (packagename, say); +mixed case is fine, but there should be no whitespace characters. +All files of a &GAP; package packagename must be collected in a +single directory packagedir, where packagedir should be +just packagename optionally converted to lowercase and optionally followed by the package version (with or without hyphen to separate the -version from package-name). +version from packagename). Let us call this directory the home directory of the package.

-To use the package with &GAP;, the directory package-dir must +To use the package with &GAP;, the directory packagedir must be a subdirectory of a pkg directory in (one of) the &GAP; root -directories (see ). +directories (see ). For example, if &GAP; is installed in /usr/local/gap4 then the files of the package MyPack may be placed in the directory /usr/local/gap4/pkg/mypack. -The directory package-dir preferably should have the following +The directory packagedir preferably should have the following structure (below, a trailing / distinguishes directories from ordinary files):

\newpage

+This layout of directories and files may be created manually, or automatically +using the tool called PackageMaker, +available at https://github.com/gap-system/PackageMaker. The +PackageMaker 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. +

+ +Packages that contain some code that requires compilation will usually have +it in the src subdirectory. They may also have extra files such as +configure, Makefile.in etc. that automate the build procedure. + There are three file names with a special meaning in the home directory of a package: PackageInfo.g and init.g which must be present, and read.g which is optional. -We now describe the above files and directories: +

+ +On the other hand, the names of CHANGES, LICENSE and +README files are not strictly fixed. They may have extensions +.txt or .md, and instead of LICENSE one could use +e.g. COPYING or GPL for packages distributed under the +GNU General Public License, or use HISTORY instead of CHANGES. +

+ +We now describe the above files and directories in more details:

@@ -267,14 +300,18 @@ 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 + +The filename may optionally have an extension, e.g. .txt or .md. +

+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). +documentation and in the PackageInfo.g (see below). @@ -283,17 +320,44 @@ documentation and in the PackageInfo.g (see below). For further versions of the package, it will be also useful to have a CHANGES file that records the main changes between versions of the package. +

+The filename may optionally have an extension, e.g. .txt or .md. + + + +LICENSE + +The file which explains conditions on which the package is distributed. +

+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. +

+&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). +

+The filename may optionally have an extension, e.g. .txt or .md. +Some packages also use different filenames, like COPYING. configure, Makefile.in -These files are only necessary if the package has a non-&GAP; component, +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 src -directory). The configure and Makefile.in files of the &Example; -package provide prototypes. The configure file typically takes a path -path to the &GAP; root directory as argument and uses the value -assigned to GAParch in the file sysinfo.gap, created when &GAP; -was compiled to determine the +directory). The configure and Makefile.in files of the +Example package provide prototypes (or they may be created +using the PackageMaker mentioned above). The configure +file typically takes a path path to the &GAP; root directory as argument +and uses the value assigned to GAParch in the file sysinfo.gap, +created when &GAP; was compiled to determine the compilation architecture, inserts this in place of the string @GAPARCH@ in Makefile.in and creates a file Makefile. When make is run (which, of course, reads the constructed Makefile), a directory @@ -301,28 +365,34 @@ run (which, of course, reads the constructed Makefile), a directory to the string assigned to GAParch in the file sysinfo.gap should be created; any binaries constructed by compiling the code in src should end up in this subdirectory of bin. + PackageInfo.g PackageInfo.g -Since &GAP; 4.4, a &GAP; package must have a PackageInfo.g +Every &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 -PackageInfo.g file is well-commented and should be used as a +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 can be used as a prototype (see also for further details). +It may also be created using the PackageMaker mentioned above. + init.g, read.g init.g read.g -A &GAP; package must have a file init.g. As of &GAP; 4.4, -the typical init.g and read.g files should normally consist -entirely of commands (and possibly -also commands) for reading further files +A &GAP; package must have a file init.g. +Typical init.g and read.g files should normally consist +entirely of commands (and possibly +also commands) for reading further files of the package. If the declaration and implementation parts of the package are separated (and this is recommended), there should be a read.g file. @@ -348,56 +418,45 @@ The &GAP; code (whether or not it is split into declaration and doc GAPDoc format -gapmacro.tex format -This directory should contain the package's documentation. -It is strongly recommended to use an XML-based documentation format -supported by the &GAP; package &GAPDoc; +This directory should contain the package's documentation, written in an +XML-based documentation format supported by the &GAP; package &GAPDoc; (see ) -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 -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 -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 -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 -generates the manuals. +which is used for the &GAP; documentation itself. +

+The Example package's documentation (see its doc +directory) may be used as a prototype. It consists of 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 generates the manuals. Generally, one should also provide a manual.bib Bib&TeX; database file or an xml file in the BibXMLext format (see ). -With gapmacro.tex, it is also possible to use a manual.bbl file. +

+word Example with packagename. --> +One could also use the AutoDoc which simplifies writing +documentation by generating most of the &GAPDoc; code automatically. lib -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 -searched for by the command. +This is the preferred place for the &GAP; code of the package, 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 advantage that it is +the default subdirectory of a package directory searched for by the + command. src -If the package has non-&GAP; code, e.g. C code, then this source +If the package contains non-&GAP; code, e.g. C code, then this source code should go in the src directory. If there are .h include files you may prefer to put these all together in a separate include directory. There is one further rule for the location of kernel @@ -407,11 +466,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. @@ -421,7 +481,7 @@ to the test files formats and further recommendations. -All other files can be organized as you like. But we suggest that you +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 examples subdirectory, data libraries in extra subdirectories, and so on. @@ -434,13 +494,15 @@ its purpose to ensure that such directory will be included in the redistribution.

Concerning the &GAP; code in packages, it is recommended to use only -documented &GAP; functions, see . +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 -A -O command line +options (note that this may also cause problems with loading other +packages that use obsolete variables). @@ -452,38 +514,25 @@ 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 -gives a short description of the purpose of the package and contains +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.

-Concerning the documentation of the use of the package there -are currently two recognised ways of producing &GAP; package -documentation. -

-First, there is a recommended XML-based documentation format -that is defined in and can be used with the &GAPDoc; package -(see ). -

-Second, there is a method which requires the documentation to be -written in &TeX; according to the format described in -the document The gapmacro.tex Manual Format. +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 ).

-In principle it is also possible to use some completely different -documentation format. In that case you need to study the -Chapter  -to learn how to make your documentation available to the &GAP; help system. -There should be at least a text version of your documenation provided for use +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 .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 -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 -tools archive as described in this Section below), -you should have no trouble in producing one. Moreover, using the +to provide an HTML version of your package manual, + +but if you use the &GAPDoc; package you should have no trouble in producing one. +

+Moreover, using the &GAPDoc; package, it is also possible to produce HTML version of the documentation supporting MathJax (http://www.mathjax.org/) for the high quality rendering of mathematical symbols while viewing @@ -493,84 +542,16 @@ compare how this formula will look with MathJax turned on/off: [ \chi, \psi ] = \left( \sum_{{g \in G}} \chi(g) \psi(g^{{-1}}) \right) / |G|.

-The manual of the &Example; package is written in the &GAPDoc; format, +The manual of the Example package is written in the &GAPDoc; format, and commands needed to build it are contained in the file makedocrel.g (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 .pdf format, you need pdflatex.

-Whenever you use the GAPDoc or gapmacro.tex &TeX;-based -system, you need to have certain &TeX; tools installed: to produce manuals -in the .pdf format, you need pdflatex if the GAPDoc -is used, and either pdftex or gs together with ps2pdf if your -package uses gapmacro.tex. -Note that using gs and ps2pdf in lieu of pdftex or -pdflatex is a poor substitute unless your gs is at least -version 6.xx for some xx. -In addition, the gapmacro.tex documentation system requires some more tools -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 -tools.tar.gz in the in &GAP;'s etc directory and installed -using the script install-tools.sh in the same directory) are needed: -gapmacro.tex -(the macros file that dictates the style and mark-up for the traditional -&TeX;-based system of &GAP; documentation), -manualindex -(an awk script that adjusts the &TeX;-produced index entries -and calls makeindex to process them), -and -mrabbrev.bib -(usually supplied with your &TeX; tools but nevertheless a copy of -mrabbrev.bib should be located in &GAP;'s main doc directory. -To find it on your system, try: kpsewhich mrabbrev.bib or, if that -doesn't work and you can't otherwise find it check out a CTAN site, -e.g. search for it at: http://www.dante.de/cgi-bin/ctan-index. -

-If your manual cross-refers to GAPDoc- or -gapmacro.tex-produced manuals, then manual.lab -for each such other manual is needed. For packages using -GAPDoc-manuals since &GAP; 4.3, -this is done by starting &GAP; and running -

-  gap> GapDocManualLab( "package" ); -

-\noindent -for each such package whose manual is cross-referred to -(this includes the main manuals, e.g. those in the -doc/ref and doc/tut directories). -For packages using gapmacro.tex-produced manuals, -manual.lab is generated by running tex manual -for each package whose manual is cross-referred to. -In most cases, packages from the &GAP; distribution will already -have these files since they will be created as a part of building their -manuals (see e.g. the last command of the example/makedocrel.g script) -and included in their distribution, so you will probably not need to -create manual.lab files yourself. -

-To produce an HTML version of the manual one needs the Perl 5 program -convert.pl which is included in the tools archive tools.tar.gz. -This archive is supplied as a part of the &GAP; distribution in the &GAP;'s -etc directory and should be installed using the script -install-tools.sh in the same directory. -

-Finally, to ensure the mathematical formulae are rendered as well as they -can be in the HTML version, one should also have the program tth -(&TeX; to HTML converter); convert.pl calls tth to translate -mathmode formulae to HTML (if it's available). The tth program is easy -to compile and can be obtained from -http://hutchinson.belmont.ma.us/tth/tth-noncom/download.html. - -

- +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. @@ -578,9 +559,9 @@ 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: @@ -594,34 +575,34 @@ SetPackageInfo( rec( SixFile := "doc/manual.six", Autoload := true ), Dependencies := rec( - GAP := "4.5", - NeededOtherPackages := [ ["GAPDoc", "1.3"] ], + GAP := "4.9", + NeededOtherPackages := [ ["GAPDoc", "1.6"] ], SuggestedOtherPackages := [ ] ), AvailabilityTest := ReturnTrue ) ); ]]>

This file declares the &GAP; package with name test in version 1.0. The package documentation consists of one autoloaded book; the SixFile -component is needed by the &GAP; help system. Package dependencies require at -least &GAP; 4.5 and &GAPDoc; package at version at least 1.3, and these -conditions will be checked when the package will be loaded -(see ). -Since there are no requirements that have to be tested, -AvailabilityTest just uses . +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 ). +Since there are no requirements that have to be tested, +AvailabilityTest just uses .

Now start &GAP; (without using the -r option) and the .gap directory will be added to the &GAP; root directory to allow &GAP; to find the packages installed there -(see ). +(see ).

LoadPackage("test"); true ]]>

-This &GAP; package is too simple to be useful, but we have succeeded -in loading it via , satisfying -all specified dependencies. +This &GAP; package is too simple to be useful, but we have succeeded +in loading it via , satisfying all specified +dependencies.

@@ -640,32 +621,7 @@ 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.

-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 -tools archive as described in Section -) -such headers were used for the manuals and have the type -

-,) -## -## This function does great things. -]]> -

-where X was one of the letters: F, A, P, O, -C, R or V indicating whether the object declared will -be a function, attribute, property, operation, category, representation or -variable, respectively. Additionally M was used in .gi files -for method installations. Then a sample usage of the function was given, -followed by a comment which described the identifier. -This description was automatically be extracted to build the -manual source, if there is a \Declaration line in some -.msk file together with an appropriate configuration file. -

-Nowadays, facilities to distribute a document over several files +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 ). @@ -674,10 +630,6 @@ E.g. example/doc/example.xml has the statement <#Include Label="ListDirectory"> and example/lib/files.gd contains ]) . . . . . . . . . . list the files in a directory -## ## <#GAPDoc Label="ListDirectory"> ## ## @@ -695,40 +647,74 @@ builds the package documentation, calling with locations of library files containing parts of the documentation. - +

+Alternatively, one could use the AutoDoc, which simplifies +writing documentation by generating most of the &GAPDoc; code automatically. +The equivalent of the fragment of the code above for AutoDoc +would look like +dir (a string) +#! or the current directory if called with no arguments. +DeclareGlobalFunction( "ListDirectory" ); +]]> -

-The PackageInfo.g File +
+Creating the PackageInfo.g File ValidatePackageInfo -As a first step the example in -shows the information needed for the package loading mechanism to load -a simple package. However, if your package depends on the functionality -of other packages, the component Dependencies given in the -PackageInfo.g file becomes important -(see below), -and more entries 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 Web -page, and so on. -

+While the minimalistic PackageInfo.g file described in + 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;. +

+The command can be used to get a quick idea about which +fields are missing: + 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 `Status' must be bound to one of "accepted", "deposited", "dev", "other" +#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 +]]> +

We suggest to create a PackageInfo.g file for your package by -copying the one in the Example package, -distributed with &GAP;, and then adjusting it for your package. -Within &GAP; you can look at this template file for a list and explanation -of all recognized entries by +copying the one in the Example package, distributed +with &GAP;, or using the PackageMaker +(https://github.com/gap-system/PackageMaker), 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

-Once you have created the PackageInfo.g file for your package, -you can test its validity with the function -. +Instead of populating the rest of the PackageInfo.g by hands, +you can also create a basic &GAP; package with the help of the +tool called PackageMaker, available at +https://github.com/gap-system/PackageMaker. The +PackageMaker 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.

@@ -753,19 +739,19 @@ The reason for this is that such functions and variables are easily overwritten and what's more you are not warned about it when it happens.

To protect a function or variable against overwriting there is the -command , +function , or alternatively (and equivalently) you may define a global -function via a -and pair -or a global variable via a -and pair. There are also operations +function via a +and pair +or a global variable via a +and pair. There are also operations and their methods, and related objects like attributes and filters which also have Declare... and Install... pairs.

Secondly, it's 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 &Example; package begin with Eg. This is +undocumented functions in the Example package begin with Eg. 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 @@ -779,7 +765,7 @@ packages. local namespace Additionally, since &GAP; 4.5 a package may place global variables into a local namespace as explained in - in order to avoid + 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 @ symbol, e.g. xYz@. Such variables may be used @@ -790,15 +776,15 @@ because of the same variable names.

On the other hand, operations and their methods (defined via -, - etc. pairs) +, + etc. pairs) and their relatives do not need this consideration, as they avoid name clashes by allowing for more than one method for the same-named object.

To demonstrate the definition of a function via a DeclareOperation/InstallMethod pair, -the method was included in the &Example; package; +the method was included in the Example package; Recipe( FruitCake ); gives a method for making a fruit cake (forgive the pun).

@@ -816,7 +802,7 @@ CAPITALISED.

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 lowecase +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 cs, exp, @@ -827,7 +813,7 @@ starting in uppercase, for example, C1 or ORB, since they also could be easily overwritten by the user.

It is a good practice to follow naming conventions used in &GAP; as -explained in and +explained in and , which might help users to memorize or even guess names of functions provided by the package. @@ -852,7 +838,7 @@ In conclusion, here is some practical advice on how to check which variables are used by the package.

Firstly, there is a function -. +. If the package pkgname is available but not yet loaded then ShowPackageVariables( pkgname ) prints a list of global variables that become bound and of methods @@ -874,7 +860,8 @@ in the package, and Setattr and Hasattr type variables where attr is an attribute or property.

-For example, for this package it currently produces the following output: +For example, for the Example package +it may produce the output looking like this: ShowPackageVariables("example"); ---------------------------------------------------------------- @@ -903,7 +890,7 @@ new methods: ]]> Another trick is to start &GAP; with -r -A options, immediately -load your package and then call +load your package and then call 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 Example it produces @@ -972,7 +959,7 @@ no good reason.

It is not appropriate to explicitly call - when the package is loaded, + when the package is loaded, 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 @@ -983,18 +970,18 @@ decides that loading the package in this situation makes no sense, then the missing component is needed.

-On the other hand, if is called +On the other hand, if 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 . +by calls to .

OnlyNeeded 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 calls for B +If no explicit 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 OnlyNeeded which @@ -1007,11 +994,11 @@ package B is not available; it is not supposed to be used in an actual 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 for B at +Only if package A calls for B at loading time (see above) then package B needs to be deinstalled (i.e. removed) to test loading of A without B. - +

Finally, if the package manual is in the &GAPDoc; format, @@ -1049,7 +1036,7 @@ this file is read only after all the init.g files of all 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 read.g, -restricting the statements in +restricting the statements in init.g to only read those files of the package that provide declarations, and to read the implementation files from read.g. @@ -1097,13 +1084,13 @@ packages are also read, and afterwards the above rule holds.) IsPackageMarkedForLoading It can happen that some code of a package depends on the availability of -suggested packages, i.e., different initializations are performed +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 -. +. In particular, one should not call (and use the value returned by this call) the function - inside + 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 OnlyNeeded. @@ -1148,13 +1135,13 @@ to this component in the PackageInfo.g file of A. autoreadable variables In the case of cyclic dependencies, one solution for the above problem -might be to delay those computations (typically initializations) +might be to delay those computations (typically initialisations) in package A that require package B 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 initialization into a separate file +variables that are created in the initialisation into a separate file and to declare these variables in the init.g file of the package, -via a call to +via a call to (see also ).

@@ -1171,7 +1158,7 @@ For package files not 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 - for further + for further details.

@@ -1182,6 +1169,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.

@@ -1237,7 +1226,8 @@ is called with the path of the &GAP; root directory as parameter. This file then will read sysinfo.gap and set up everything for compiling under the given architecture (for example creating a Makefile from Makefile.in). As initial templates, -you may use installation scripts of the Example package. +you may use installation scripts of the Example package +or files generated with the help of PackageMaker. @@ -1254,9 +1244,9 @@ if this is not the case). This is especially important if the package is loaded automatically.

The easiest way to accomplish this is to use - + for checking for the actual binaries in the path given by - + for the respective package. For example the example &GAP; package could use the following function to test whether the binary hello has been compiled; @@ -1287,23 +1277,23 @@ However, if you look at the actual PackageInfo.g file of the AvailabilityTest function always returns true, and just logs the warning if the binary is not available (which may be later viewed with -). +). This means that the binary is not regarded as essential for this package.

You might also have to cope with the situation that external binaries will only run under UNIX (and not, say, under Windows), or may not compile with some compilers or default compiler options. -See  +See  for information on how to test for the architecture.

LogPackageLoadingMessage Last but not least: do not print anything in the AvailabilityTest function of the package via Print or Info. Instead one should -call to store +call to store a message which may be viewed later with - -(the latter two functions are introduced in &GAP; 4.5) + +(the latter two functions have been introduced in &GAP; 4.5) @@ -1320,16 +1310,16 @@ There are two principal ways of doing this.

The first possibility is to write all the data for the stand-alone to one or several files, then start the stand-alone with - or - + or + which then writes the output data to file, and finally read in the standalone's output file.

The second way is interfacing via input-output streams, -see Section . +see Section .

Some &GAP; packages use kernel modules -(see ) +(see ) instead of external binaries. A kernel module is implemented in C and follows certain conventions to comply with the &GAP; kernel interface, which we plan to document later. @@ -1354,7 +1344,7 @@ and get in touch with &GAP; developers if you plan to develop such a package. It is a good idea to declare an InfoClass for your package. This gives the package user the opportunity to control the verbosity of output and/or the possibility of receiving debugging information -(see ). Below, we give a quick +(see ). Below, we give a quick overview of its utility.

An InfoClass is defined with a DeclareInfoClass( InfoPkgname ); @@ -1378,28 +1368,30 @@ 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 -argument of SetPackageInfo in the PackageInfo.g file. + +When the package is loaded, &GAP; will display a default package banner, +constructed from the package metadata provided in the PackageInfo.g file. +

+Alternatively, the package may establish its own banner by assigning a string +to the BannerString field of the record argument of SetPackageInfo +in the PackageInfo.g file.

-It is a good idea to have a hook into your package documentation from -your banner. The banner of the &Example; package suggests to the &GAP; user: +If you will be designing a banner for your package, it is a good idea to suggest +there how to access package documentation. For example, the banner of the +Example package says:

-In order for this to display the introduction of the &Example; package -the index-entry +In order for this to display the introduction of the +Example package the index-entry &tlt;Index&tgt;Example package&tlt;/Index&tgt; was added just before the first paragraph of the introductory section in -the file example.xml. The &Example; package uses -GAPDoc -(see Section ) -for documentation -(you will need some different scheme to achieve this using -the gapmacro.tex system). +the file doc/example.xml of the Example package.

@@ -1411,7 +1403,7 @@ the gapmacro.tex system). version number Version numbers are strings containing nonnegative integers separated by non-numeric characters. They are compared by - + which first splits them at non-digit characters and then lexicographically compares the resulting integer lists. Thus version "2-3" is larger than version "2-2-5" @@ -1452,7 +1444,10 @@ a new version number. This should be done even for very minor changes. For most of the packages it will be inappropriate to re-use the date of the release as a version number. It's much more obvious how big are the changes between versions "4.4.12", "4.5.1" and "4.5.2" than between -versions "2008.12.17", "2011.04.15" and "2011.09.14". +versions "2008.12.17", "2011.04.15" and "2011.09.14". The concept of +using version numbers to convey the meaning of the status of the code +and the way it has been modified is known as Semantic Versioning, +see http://semver.org/ for further recommendations on its use.

Since version information is duplicated in several places throughout the package documentation, for &GAPDoc;-based manuals you may define the @@ -1462,7 +1457,8 @@ file close to the place where you specified its Version and ## -## +## +## ## <#/GAPDoc> ]]> notify that a part of the @@ -1480,6 +1476,23 @@ instructions).

Testing a &GAP; package +There are several aspects of testing a &GAP; package. +

+First, one should ensure that the package functionality works as expected. +Below we give an advice on creating test files for automated tests that may +be run by package authors, by &GAP; developers as part of the release +preparation, and by package users interested in checking that the package +works. Such tests should be included in the package distribution, and the +responsibility for ensuring that they pass stays with package authors. +

+Second, the package should cleanly integrate into the &GAP; system and other +packages, and should not break their functionality. In particular, all tests +from the standard &GAP; testing suite should pass if the package is loaded. +This is more comprehensive and time consuming test, which &GAP; developers +regularly run using special tools. They will report to you any detected issues. +Below we explain how to do several simple and less time consuming checks +which package authors are recommended to perform themselves. + Tests files for a GAP package @@ -1487,16 +1500,16 @@ The (optional) tst directory of your package may contain as many tests of the package functionality as appears appropriate. These tests should be organised into test files similarly to those in the tst directory of the &GAP; distribution as documented in -. +.

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 component TestFile -in the PackageInfo.g to be included in the GAP standard test suite. -This file can either consist of -calls (in this case, it is common to call it testall.g) or be -itself a test file having an extension .tst and supposed to be -read via . It is assumed that the +in the PackageInfo.g to be included in the &GAP; standard test suite. +This file can either consist of calls of or + (in this case, it is common to call it testall.g) +or be itself a test file having an extension .tst and supposed to be +read via . It is assumed that the latter case occurs if and only if the file contains the substring

 "gap> START_TEST("

@@ -1515,11 +1528,25 @@ Example package: testall.tst GAP4stones: 3333 true ]]> -Tests which produce extended output and/or requires substantial runtime +Tests which produce extended output and/or require substantial runtime 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. - +

+Because of different approaches to testing, used by different packages, +it is not always easy to identify whether an automated test passed or failed. +Presently, automated detection works fine if a package uses a single +.tst file or uses to run a collection of +tests. Otherwise, one should follow the convention to output a string of a +fixed format to indicate the result of the test in the test script along the +following lines: + @@ -1532,19 +1559,19 @@ configurations: starting &GAP; with no packages (except needed for &GAP;) using -r -A options -and calling LoadPackage("your-package-name"); +and calling LoadPackage("packagename"); starting &GAP; with no packages (except needed for &GAP;) using -r -A options -and calling LoadPackage("your-package-name" : OnlyNeeded ); +and calling LoadPackage("packagename" : OnlyNeeded ); starting &GAP; in the default configuration (with no options) -and calling LoadPackage("your-package-name"); +and calling LoadPackage("packagename"); starting &GAP; in the default configuration (with no options) -and calling LoadPackage("your-package-name" : OnlyNeeded ); +and calling LoadPackage("packagename" : OnlyNeeded ); finally, together with all other packages using @@ -1580,7 +1607,7 @@ four cases above (the letter N in the filename stands for Each file contains small sections for loading individual packages: among those, you need to find the section related to your package and may ignore all other -sections. For example, the section for the &Example; package looks like +sections. For example, the section for the Example package looks like Loading ... and Loaded ... lines, they will signal on errors during loading of your package.

Additionally, this test collects information about variables created since -the library was read (obtained using ) +the library was read (obtained using ) with either short names (no more than three characters) or names breaking a recommended naming convention that the &GAP; core system and &GAP; packages should not use global variables starting in the lowercase (see Section ). -Their list will be displayed in the test log (in the example above, &Example; +Their list will be displayed in the test log (in the example above, Example packages does not create any such variables, so an empty list is displayed). It may be hard to attribute a particular identifier to a package, since it may be created by another package loaded because of dependencies, so when a more detailed and precise report on package variables is needed, it may -be obtained using +be obtained using (also, make testpackagesvars called in the &GAP; root directory produces such reports for each package and writes them to a file dev/log/testpackagesvars_...).

Finally, each log file finishes with two large sections for loading all -packages in the alphabetical and reverse aplhabetical order (to check more +packages in the alphabetical and reverse alphabetical order (to check more combinations of loading one package after another). We are aiming at releasing only collections of package which do not break in any of the four configurations, so if @@ -1627,7 +1654,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. @@ -1637,46 +1664,47 @@ 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 +test files and scripts such as testinstall.g and teststandard.g which are a part of the &GAP; standard test suite.

+ It is important to check that your package does not break &GAP; standard tests. To perform a clean test and avoid interfering with other packages, -first you must start a new &GAP; session with the following command -(assuming that gap starts &GAP; in your system): - -After that load your package and run either testinstall.g or -testall.g as demonstrated below. +first you must start a new &GAP; session and then read either testinstall.g +or teststandard.g as demonstrated below.

-The quicker test, testinstall.g, requires about 512MB of memory and -runs for about one minute on an Intel Core 2 Duo / 2.53 GHz machine. It may -be started with the command +The quicker test, testinstall.g, requires about 1 GB of memory and +runs for several minutes. It may be started with the command Read( Filename( DirectoriesLibrary( "tst" ), "testinstall.g" ) ); ]]> You will get a large number of lines with output about the progress of -the tests. +the tests, for example:

-The more thorough test is testall.g which exercises more of &GAP;'s -capabilities, containing all test files from testinstall.g as -a subset. It requires about 512MB of memory, runs for about one hour -on an Intel Core 2 Duo / 2.53 GHz machine, and produces an output -similar to the testinstall.g test. -To run it, also start a new &GAP; session with -gap -N -A -x 80 -r -m 100m -o 512m and then call +(optionally, you may start &GAP; with the command line options which you +will see in the test output, to run it in a more conservative settings). +

+ +The more thorough test is teststandard.g which exercises more of &GAP;'s +capabilities, also including all test files from teststandard.g. +It requires about 1 GB of memory, runs for about one hour, and produces +an output similar to the testinstall.g test. +To run it, also start a new &GAP; session and then call Read( Filename( DirectoriesLibrary( "tst" ), "testall.g" ) ); ]]> @@ -1684,11 +1712,9 @@ You may repeat the same check loading your package with OnlyNeeded option. Remember to perform each subsequent test in a new &GAP; session.

Also you may perform individual tests from the tst directory of the -&GAP; installation loading them with , -for example, the file bugfix.tst. +&GAP; installation loading them with .

-

@@ -1699,10 +1725,36 @@ 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; -team by mailing to support@gap-system.org. +testing with official &GAP; releases. We also invite everyone to contribute +by submitting patches, pull requests, and bug reports. We would like to +make the contributing process as easy as possible. +

+The main GAP development repository is hosted on GitHub at +https://github.com/gap-system/gap. Many &GAP; packages +also have public repositories and issue trackers, and we are keeping +a list of such packages at https://gap-packages.github.io/.

+For further information about contributing to the GAP development, please see +https://github.com/gap-system/gap/blob/master/CONTRIBUTING.md. +

+ + + +
+Version control and continuous integration for &GAP; packages + +As we have mentioned above, many &GAP; packages have public repositories and +issue trackers on GitHub, and we are keeping a list of such packages at +https://gap-packages.github.io/. We welcome establishing public +repositories for new packages and migrating existing package repositories +there as well. Such repositories may be hosted under their authors' accounts +or under the gap-packages organisation (https://github.com/gap-packages/). +The latter has the benefit that while the authors will preserve their deciding +role on all aspects of the package development, the package will become more +visible for potential collaborators and &GAP; developers may help to set up +continuous integration for your package so that every commit to the +repository will trigger automated running of package tests and reporting any +failures to package maintainers.
@@ -1710,37 +1762,38 @@ 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 +As it was mentioned in the description of the LICENSE file in +Section , +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 -you to consider the GPL for your packages, but you might wish to be more +you to consider the GPL license 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). See Choosing a License for the Distribution of Your Package -from http://www.gap-system.org/Packages/Authors/authors.html -for further details. +from http://www.gap-system.org/Packages/Authors/authors.html and also +https://choosealicense.com/ for further details.

In the past many &GAP; packages used the text -We adopt the copyright regulations of GAP as detailed in the copyright +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 -more explicit and make the exact reference to the GPL license, for example: +more explicit by making the exact reference to the GPL license, for example:

-package-name is free software; you can redistribute it +packagename is free software; you can redistribute it and/or modify it under the terms of the http://www.fsf.org/licenses/gpl.html as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. +and also including a copy of the full text of the license.

-
-Wrapping up a &GAP; Package - - +
+Releasing a GAP Package Currently, the &GAP; distribution provides archives in four different formats. @@ -1762,7 +1815,7 @@ formats. -win.zip an archive in zip format, where text files should have - DOS/Windows style line breaks + Windows style line breaks

@@ -1772,20 +1825,9 @@ archive of your package in at least one of these formats. For example, if you wish to supply a .tar.gz archive, you may create it with the command

- tar -cvzf package-name-version.tar.gz package-name + tar -cvzf packagename-version.tar.gz packagename

\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 -format for backwards compatibility, if no other formats are available. -

Because the release of the &GAP; package is independent of the version of &GAP;, a &GAP; package should be wrapped up in separate file that can be installed onto any version of &GAP;. In this way, a package can @@ -1799,8 +1841,8 @@ The archive of a &GAP; package should contain all files necessary for the package to work. In particular there should be a compiled documentation, which includes the manual.six, manual.toc and manual.lab file in the -documentation subdirectory which are created by &TeX;ing the documentation, -if you use &GAPDoc; or the gapmacro.tex document formats. +documentation subdirectory which are created by &GAPDoc; while &TeX;ing +the documentation. (The first two files are needed by the &GAP; help system, and the manual.lab file is needed if the main manuals or another package is referring to your package. @@ -1808,7 +1850,7 @@ Use the command GAPDocManualLab( packagename ); to create this file for your help books if you use &GAPDoc;.)

-For packages which are redistributed via the &GAP; Web site, +For packages which are redistributed via the &GAP; website, we offer an automatic conversion of any of the formats listed above to all the others (note that this, as well as wrapping the &GAP; distribution as a single archive containing the @@ -1825,7 +1867,7 @@ while text files in -win.zip archives must have DOS/Windows line breaks.

-The package wrapping tools for the &GAP; distribution and web pages +The package wrapping tools for the &GAP; distribution and webpages then will use a sensible list of file extensions to decide if a file is a text file (being conservative, it may miss a few text files). These rules may be prepended by the application of rules from the @@ -1846,44 +1888,32 @@ before &GAP; defaults will be applied;

-The etc directory obtained from tools.tar.gz -(described above in -Section ) -contains a file classifyfiles.py and two files patternscolor.txt -and patternstextbinary.txt implementing &GAP; default rules used -to classify files in packages. -For most of the packages these default rules perfecty detect binary and -text files, so there is no need for them to use any of the three optional -components. However, .TextBinaryFilesPatterns, or .TextFiles, -or .BinaryFiles will become useful if the package has e.g. data -files which are recognised as binary files by the default rules, or if the -package uses standard extensions in a non-standard way (this is not -recommended, of course). If things will go wrong, it is possible that one -(or indeed all) created archives have wrong line breaks. -

- -Utility functions available in gap4r7/lib/lbutil.g, namely +Utility functions from the lib/lbutil.g file in &GAP;, namely DosUnixLinebreaks, UnixDosLinebreaks, MacUnixLinebreaks may be helpful. They are described in the comments to their source code. +

+ +For packages hosted on GitHub publishing package release and establishing its +website can be very efficiently automated using two tools: +ReleaseTools (https://github.com/gap-system/ReleaseTools) and +GitHubPagesForGAP (https://github.com/gap-system/GitHubPagesForGAP).

-
-The WWW Homepage of a Package +
+The homepage of a Package -If you want to distribute your package -you should create a WWW homepage containing -some basic information, -archives for download, +If you want to distribute your package you should create its homepage containing +some basic information, archives for download, the README file with installation instructions, and a copy of the package's PackageInfo.g file.

-The responsibility for this WWW homepage is with the package +The responsibility to maintain this homepage is with the package authors/maintainers.

-If you tell us about your package +If you tell the &GAP; Group about your package (say, by mail to support@gap-system.org) we may consider either @@ -1898,144 +1928,87 @@ also ; In the latter case we can also provide some services for producing several -archive formats from the archive you provide (e.g., you produce a -.tar.gz version of your archive and we produce also a .tar.bz2 +archive formats from the archive you provide (e.g., you produce a .tar.gz +version of your archive and we produce also a .tar.bz2, .zip and a -win.zip version from it).

Please also consider submitting your package to the &GAP; package refereeing process (see http://www.gap-system.org/Contacts/submit.html for further information). +

+For packages hosted on GitHub publishing package release and establishing its +website can be very efficiently automated using two tools: +GitHubPagesForGAP (https://github.com/gap-system/GitHubPagesForGAP) +and ReleaseTools (https://github.com/gap-system/ReleaseTools). +

-
-Upgrading the package to work with &GAP; 4.5 - - -Changes in &GAP; 4.5 from the packages perspective - -Here we list only those changes which may have some implications for the -packages. +
+Some things to keep in mind -Changing the distribution format providing one archive with the core system -and all currently redistributed packages. +Some packages still use for their manuals the old gapmacro format, +support for which may be discontinued in the future. We encourage authors +of those packages to eventually convert their documentation &GAPDoc;. +New packages are recommended to use &GAPDoc;, which, for example, is +capable of creating HTML documentation with MathJax support, allows +easy extraction of examples from documentation for testing, etc. One could +also use the AutoDoc which simplifies writing documentation +by generating most of the &GAPDoc; code automatically. -The &GAP; kernel is now compiled by default to use the GMP large integer -arithmetic library, speeding up arithmetic by a factor of 4 or more in many cases. -This slightly changes the build process, affecting mainly packages with -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. -The two other books, Extending &GAP; and Programming Tutorial became -parts of the Reference Manual. Packages that refer to parts of the &GAP; documentation -may need to rebuild their manuals to update references. -

-Some packages still use the -old gapmacro format for their manuals, for which support may be discontinued -in the future. There is no urgent need to convert such manuals into the &GAPDoc; -format before &GAP; 4.5 release, but we encourage you very much to consider -doing this at some later point. - - - -The old concept of an autoloaded package has been integrated with the needed -and suggested mechanism that already exists between packages. &GAP; itself +The concept of an autoloaded package, which existed before &GAP; 4.5, +has been integrated with the needed +and suggested mechanism that exists between packages. &GAP; itself now needs certain packages (for instance &GAPDoc;) and suggests others (typically the packages that were autoloaded). The decisions which packages &GAP; should need or suggest are made by developers based on technical criteria. They can be easily overridden by a user using the new gap.ini -(see ). -The default file ensures that all previously autoloaded packages are +(see ). +The default file ensures that all formerly autoloaded packages are still loaded if present. -Optional ~/.gap directory for user's customisations which may contain e.g. -locally installed packages (see ). +Optional ~/.gap directory for user's customisations which may +contain e.g. locally installed packages (see ). If package installation instructions explain how to install the package in a -non-standard location, they may need an update. This is intended to replace -.gaprc files, but those are still supported for backwards -compatibility (see ). +non-standard location, they should mention this. -Various improvements in the packages loading mechanism make it more +Packages loading mechanism allows to make loading packages more informative, while avoiding confusing the user with warning and error -messages for packages they didn't -know they were loading. For example, many messages are stored but not -displayed using the function -and there is a function +messages for packages they didn't know they were loading. +For example, many messages are stored but not +displayed using the function +and there is a function to show log messages that occur during package loading. Packages are encouraged to use these mechanisms to report -problems in loading (e.g. binaries not compiled), rather than printing messages directly. - - - -Since &GAP; 4.5 a package may place global variables into a local -namespace as explained in -in order to avoid name clashes and preserve compatibility. - - - -In &GAP; 4.5 the internal representation of a record has changed, -as well as some of the basic functions to manipulate records. This speeds -up considerably the creation of and access to records with many components. -Record components are now internally stored in the order in which they were used -first, and this means that the internal ordering of components (returned by - and so the ordering of records, depends -on the GAP session. - -Therefore, within each session everything is consistent, so one can -efficiently remove duplicates with , -sort lists of records, find records with binary search, etc., but a -care should be taken not to rely on -always returning names of components in the same order. +problems in loading (e.g. binaries not compiled), +rather than printing messages directly. - -

-
-Checklists +
+Package release checklists -checklists - -Package release checklist +The following checklists should be useful to package authors and maintainers, as +well as to everyone involved in the depositing and refereeing of &GAP; packages. -The following checklist may be used by package authors, members of the -&GAP; team responsible for package updates, package editors and referees. + +Checklist for releasing a new package @@ -2043,7 +2016,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 + does not break testinstall.g and teststandard.g, and does not slow them down noticeably (see ); @@ -2059,63 +2032,67 @@ The following checklist may be used by package authors, members of the - Package documentation: + PackageInfo.g file: - is built and included in the package archive together with - its source files; - - - states the version, release date and package authors; + correctly specifies package version, release date, and package authors; - has the same version, release date and package authors - details as stated in the PackageInfo.g file; + passes validation using ; - is searchable using the &GAP; help system; - - - is clear about the license under which the package is distributed; + besides mandatory components, which are required to pass validation, + also has relevant optional components (such as, for example, URLs of + public source code repository and issue tracker; hints to distinguish + binary and text files in case of non-standard file names and extensions, + etc.); - + - PackageInfo.g file: + Package documentation: - has the same version, release date and package authors - details as stated in the package manual; + is built and included in the package archive together with + its source files; + + + states the same version, release date and package authors + as specified in the PackageInfo.g file; - has all mandatory components and also optional components where appropriate; + has the same version, release date and package authors + details as stated in the PackageInfo.g file; - in particular, contains hints to distinguish binary and text files in - case of non-standard file names and extensions; + is searchable using the &GAP; help system in all formats + (text, HTML and PDF); - is validated using ; + is clear about the license under which the package is distributed, + and refers to the LICENSE file which should be included in + the package; - + + Package archive(s): - have correct permisisons for all files and directories after their + have correct permissions for all files and directories after their unpacking (755 for directories and executables, if any; 644 for other files); contain files with correct line breaks for the given format - (see ); + (see Section ); contain no hidden system files and directories that are not supposed - to be included in the package, e.g. .cvsignore, + to be included in the package, e.g. .gitignore, .git etc.; @@ -2129,11 +2106,6 @@ The following checklist may be used by package authors, members of the PackageInfo.g and README files are available online; - - the URL of the PackageInfo.g file is validated using - the online tool available from - http://www.gap-system.org/Packages/Authors/authors.html; - @@ -2141,114 +2113,67 @@ The following checklist may be used by package authors, members of the + +Checklist for upgrading the package for the next major release of &GAP; - -Checklist for package upgrade to work with &GAP; 4.5 +&GAP; ecosystem is not static: both the core &GAP; system and packages +redistributed with &GAP; are in constant development. &GAP; has a policy +that changes that may have a disruptive effect on packages redistributed +with &GAP; should only be introduced in major &GAP; releases. When the next +&GAP; major release is prepared, a beta version for package authors will be +made available in order to give them an opportunity to check and update, +if necessary, their packages for the public release of the next major version +of &GAP;. +

The following checklist will help you to check how well your package is -ready to work with &GAP; 4.5. +ready to work with the next major release of &GAP;

-Mandatory changes needed for package upgrade to work with &GAP; 4.5: - - - - -Check that the package works as expected: - - - - -verify that the package functionality works as required, that examples -in the manual are correct and that test files show no discrepancies; - - -if necessary, update manual examples and test files because the order -in which record components are printed has changed -(but now it will be more consistent and less dependent on how the record -was created); - - -check the usage of names of record components in the code: -take care not to rely on -always returning names of components in the same order -(see ) - - +Check that the package functionality works as expected, +package tests run with no discrepancies, and manual examples +correspond to new version of &GAP;. This is a convenient opportunity +to polish existing and add new tests, and improve manual examples. - -Revise package dependencies: - -Check the the PackageInfo.g has the correct list of -needed and suggested packages (see ). +Revise package dependencies: check that the PackageInfo.g file +has correct list of needed and suggested packages +(see Section ). - -Revise licensing information: - -Check that the package states clearly under which conditions it is distributed -(see ). +Revise licensing information: +check that the package states clearly under which conditions it is distributed +and includes a LICENSING file with the text of a license +(see Section ). - -Rebuild the package documentation: - -whenever your package documentation is &GAPDoc; or gapmacro.tex-based, -&GAP; 4.5 contains new versions of both tools. This will ensure that -cross-references from the package manual to the main &GAP; manuals are -correct and that the &GAP; help system will be able to navigate to the more -precise location in the package manual. This will also improve the layout of -the package documentation. In particular, &GAPDoc; has a better -.css file and is capable of producing the HTML version with -MathJax support to display nicely mathematical formulae. -

Note that it's not possible for a package to have an HTML manual which -contains correct links to both &GAP; 4.4 and &GAP; 4.5 main manuals. - - - - +Rebuild the package documentation to update cross-references to main &GAP; +manuals and, if relevant, to the documentation of other &GAP; packages. +This will ensure that cross-references from the package manual to the main &GAP; +manuals are correct and that the &GAP; help system will be able to navigate to +the more precise location in the package manual. This will also improve the layout of +the package documentation by picking up the changes in documenting tools. -Optional changes recommended for package upgrade to work with &GAP; 4.5: - - - - -When the AvailabilityTest component in PackageInfo.g -differs from , use - to store -a message which may be viewed later with - -instead of calling Print or Info directly -(see ). +Check if the package still relies on some obsolete variables +(see Chapter ) +and replace their usage by the new commands. To perform such check, start &GAP; +with `-O` command line option to disable loading obsoletes, and then load +your package. -It is recommended not to call -from a package file while this file is read: instead one should list the -package in question in the lists of needed or suggested packages. -To verify whether such calls occur in the package first load it and -then call DisplayPackageLoadingLog( PACKAGE_WARNING );. If there is -a genuine need to decide whether some package will be available at runtime, -use the function -introduced in &GAP; 4.5. +Check for any specific advice in release notes for the beta release for +package authors. - -Check if the package still relies on some obsolete variables -(see ) -and try to get rid of their usage. - - - @@ -2256,4 +2181,3 @@ and try to get rid of their usage.

- diff --git a/doc/ref/overview.xml b/doc/ref/overview.xml index d3bd4a3044..9fd2f9596f 100644 --- a/doc/ref/overview.xml +++ b/doc/ref/overview.xml @@ -24,8 +24,8 @@ the &GAP; language, and use them in just the same way as the programs which form part of the system (the library). Indeed, we actively support the contribution, refereeing and distribution of extensions to the system, in the form of &GAP; packages. Further details of this -can be found in chapter , and -on our website. +can be found in chapter , +and on our website.

Development of &GAP; began at Lehrstuhl D für Mathematik, RWTH-Aachen, under the leadership of Joachim Neubüser @@ -143,8 +143,8 @@ data sources such as the electronic version of the Atlas of Finite Group Representations; therefore, installation and usage of packages is recommended.

Further details about &GAP; packages can be found in chapter -, and on the &GAP; -website here: https://www.gap-system.org/Packages/packages.html. +, and on the +&GAP; website here: https://www.gap-system.org/Packages/packages.html. diff --git a/doc/ref/run.xml b/doc/ref/run.xml index 10d3529980..ba5f1bfa63 100644 --- a/doc/ref/run.xml +++ b/doc/ref/run.xml @@ -73,7 +73,7 @@ whose component names are the command line options -A By default, some needed and suggested &GAP; packages -(see ) are loaded, +(see ) are loaded, if present, into the &GAP; session when it starts. This option disables (actually toggles) the loading of suggested packages, which can be useful for debugging or testing. diff --git a/lib/package.gd b/lib/package.gd index 919efc77bd..2c4cbe4cf1 100644 --- a/lib/package.gd +++ b/lib/package.gd @@ -702,11 +702,11 @@ DeclareGlobalFunction( "LoadPackageDocumentation" ); ## true ## ]]> ##

-## The package name may be appropriately abbreviated. For example, -## LoadPackage("semi"); will load the Semigroups -## package, and LoadPackage("d"); will load the -## DESIGN package. If the abbreviation can not be uniquely -## completed, further suggestions will be offered. +## The package name may be appropriately abbreviated. For example, at the time +## of writing, LoadPackage("semi"); will load the +## Semigroups package, and LoadPackage("j"); will +## load the json package. If the abbreviation can not be +## uniquely completed, further suggestions will be offered. ##

## If the optional version string version is given, ## the package will only be loaded in a version number at least as large as