diff --git a/doc/ref/gappkg.xml b/doc/ref/gappkg.xml index eae41ac071..46eb45bb0e 100644 --- a/doc/ref/gappkg.xml +++ b/doc/ref/gappkg.xml @@ -1177,5 +1177,1082 @@ details. + +
+Standalone Programs in a ⪆ Package + +⪆ packages that involve stand-alone programs are fundamentally +different from ⪆ packages that consist entirely of ⪆ code. +

+This difference is threefold: A user who installs the ⪆ package +must also compile (or install) the package's binaries, the +package must check whether the binaries are indeed available, +and finally the ⪆ code of the package has to start the external +binary and to communicate with it. +We will cover these three points in the following sections. +

+If the package does not solely consist of an interface to an external +binary and if the external program called is not just special-purpose +code, but a generally available program, chances are high that sooner +or later other ⪆ packages might also require this program. +We therefore strongly recommend the provision of a documented ⪆ +function that will call the external binary. We also suggest to create +actually two ⪆ packages; the first providing only the binary and the +interface and the second (requiring the first, +see ) being the actual ⪆ package. +

+ + + + +Installation of ⪆ Package Binaries + +sysinfo.gap +external binaries +The scheme for the installation of package binaries which is described +further on is intended to permit the installation on different +architectures which share a common file system (and share the +architecture independent file). +

+A ⪆ package which includes external binaries contains a bin +subdirectory. This subdirectory in turn contains subdirectories for +the different architectures on which the ⪆ package binaries are +installed. The names of these directories must be the same as the +names of the architecture dependent subdirectories of the main bin +directory. Unless you use a tool like autoconf yourself, you must +obtain the correct name of the binary directory from the main ⪆ +branch. To help with this, the main ⪆ directory contains a file +sysinfo.gap which assigns the shell variable GAParch to the +proper name as determined by ⪆'s configure process. +For example on a Linux system, the file sysinfo.gap may look like +this: +

+ +

+We suggest that your ⪆ package contains a file configure which +is called with the path of the ⪆ 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. + + + + + + +Test for the Existence of GAP Package Binaries + +If an external binary is essential for the workings of a ⪆ package, +the function stored in the component AvailabilityTest of the +PackageInfo.g file of the package should test whether the program +has been compiled on the architecture (and inhibit package loading +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 ⪆ package could use the +following function to test whether the binary hello has been compiled; +it will issue a warning if not, and will only load the package if the binary +is indeed available: +

+ fail; + end, +... +]]> +

+However, if you look at the actual PackageInfo.g file of the +example package, you will see that its +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  +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 +a message which may be viewed later with + +(the latter two functions are introduced in ⪆ 4.5) + + + + + + +Calling of and Communication with External Binaries + +There are two reasons for this: the input data has to be passed on to +the stand-alone program and the stand-alone program has to be started +from within ⪆. +

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

+Some ⪆ packages use kernel modules +(see ) +instead of external binaries. +A kernel module is implemented in C and follows certain conventions to +comply with the ⪆ kernel interface, which we plan to document later. +In the meantime, we advise you to look at existing examples of such packages +and get in touch with ⪆ developers if you plan to develop such a package. + + + +

+ + + + +
+Having an InfoClass + + + +InfoClass +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 +overview of its utility. +

+An InfoClass is defined with a DeclareInfoClass( InfoPkgname ); +statement and may be set to have an initial InfoLevel other than the +zero default (which means no Info statement is to output information) +via a SetInfoLevel( InfoPkgname, level ); statement. An initial +InfoLevel of 1 is typical. +

+Info statements have the form: +Info( InfoPkgname, level, expr1, expr2, ...); +where the expression list expr1, expr2, ... +appears just like it would in a Print statement. The only difference is +that the expression list is only printed (or even executed) if the +InfoLevel of InfoPkgname is at least level. + +

+ + + + +
+The Banner + +banner +Since ⪆ 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. +

+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 ⪆ user: +

+ +

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

+ + + +
+Version Numbers + +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" +but smaller than "4r2p3" or "11.0". +

+It is possible for code to require ⪆ packages in certain +versions. In this case, all versions, whose number is equal or larger +than the requested number are acceptable. It is the task of the +package author to provide upwards compatibility. +

+Loading a specific version of a package (that is, not one with a +larger version number) can be achieved by prepending = to the desired +version number. +For example, LoadPackage( "example", "=1.0" ) will load version +"1.0" of the package "example", +even if version "1.1" is available. +As a consequence, version numbers must not start with =, +so "=1.0" is not a valid version number. +

+Package authors should choose a version numbering scheme that admits a +new version number even after tiny changes to the package, and +ensure that version numbers of successive package versions increase. +The automatic update of package archives in the ⪆ distribution will +only work if a package has a new version number. +

+It is a well-established custom to name package archives like +name-version.tar.gz, name-version.tar.bz2 etc., +where name is the lower case name, and version is +the version (another custom is that the archive then should extract +to a directory that has exactly the name name-version). +

+It is very important that there should not ever be, for a given ⪆ +package, two different archives with the same package version number. +If you make changes to your package and place a new archive of the +package onto the public server, please ensure that a new archive has +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". +

+Since version information is duplicated in several places throughout the +package documentation, for &GAPDoc;-based manuals you may define the +version and the release manual in the comments in PackageInfo.g +file close to the place where you specified its Version and +Date components, for example + +## +## +## <#/GAPDoc> +]]> +notify that a part of the +document is stored in PackageInfo.g (see example/makedocrel.g), +read this data into the header of the main document via +<#Include Label="PKGVERSIONDATA"> directive and then use them via +&VERSION; and &RELEASEDATE; entities almost everywhere where you +need to refer to them (most commonly, in the title page and installation +instructions). + +

+ + + +
+Testing a &GAP; package + + +Tests files for a GAP package + +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 +latter case occurs if and only if the file contains the substring

+ "gap> START_TEST(" +

+\noindent +(with exactly one space after the &GAP; prompt). +

+For deposited packages, these tests are run by the &GAP; Group regularly, +as a part of the standard &GAP; test suite. For the efficient testing it +is important that the test specified in the PackageInfo.g file +does not display any output (e.g. no test progress indicators) except +reporting discrepancies if such occur and the completion report as +in the example below: + Test("tst/testall.tst"); +Example package: testall.tst +GAP4stones: 3333 +true +]]> +Tests which produce extended output and/or requires 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. + + + + + +Testing &GAP; package loading + +To test that your package may be loaded into &GAP; without any problems +and conflicts with other packages, test that it may be loaded in various +configurations: + + +starting &GAP; with no packages (except needed for &GAP;) using -r -A options +and calling LoadPackage("your-package-name"); + + +starting &GAP; with no packages (except needed for &GAP;) using -r -A options +and calling LoadPackage("your-package-name" : OnlyNeeded ); + + +starting &GAP; in the default configuration (with no options) +and calling LoadPackage("your-package-name"); + + +starting &GAP; in the default configuration (with no options) +and calling LoadPackage("your-package-name" : OnlyNeeded ); + + +finally, together with all other packages using + (see below) in four possible combinations +of starting &GAP; with/without -r -A options and calling + with/without Reversed option. + + +The test of loading all packages is the most subtle one. Quite often +it reveals problems which do not occur in the default configuration +but may cause difficulties to the users of specialised packages. +

+For your convenience, make testpackagesload called in the &GAP; +root directory will run all package loading tests listed in this subsection +and write their output in its dev/log directory. +

+It will produce four files with test logs, corresponding to the +four cases above (the letter N in the filename stands for +needed, A stands for autoloaded): + + +dev/log/testpackagesload1_... + + +dev/log/testpackagesloadN1_... + + +dev/log/testpackagesloadA_... + + +dev/log/testpackagesloadNA_... + + +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 + +so it has clearly passed the test. If there are any error messages displayed +between 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 ) +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; +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 +(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 +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 +it is broken when you plug in the development version of your package into +the released version of &GAP;, it is likely that your package triggers +this error. If you observe that is broken +and suspect that this is not the fault of your package, please contact +the &GAP; Support. + + + + + +loads all &GAP; packages from their list sorted in alphabetical order +(needed and suggested packages will be loaded when required). This is a +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 +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. +

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

+ +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 + Read( Filename( DirectoriesLibrary( "tst" ), "testinstall.g" ) ); +]]> +You will get a large number of lines with output about the progress of +the tests. + +

+ +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 + Read( Filename( DirectoriesLibrary( "tst" ), "testall.g" ) ); +]]> +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. +

+ + + + +

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

+

+ + + +
+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 +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). See Choosing a License for the Distribution of Your Package +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 +more explicit and make the exact reference to the GPL license, for example: +

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

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

+ +.tar.gz + + a standard UNIX tar archive, compressed with gzip + +.tar.bz2 + + a standard UNIX tar archive, compressed with bzip2 + +.zip + + an archive in zip format, where text files should have + UNIX style line breaks + +-win.zip + + an archive in zip format, where text files should have + DOS/Windows style line breaks + + +

+For convenience of possible users it is sensible that you provide an +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 +

+\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 +be upgraded any time without the need to wait for new &GAP; releases. +To ensure this, the package should be archived from the &GAP; pkg +directory, that is all files are archived with the path starting at the +package's name. +

+GAPDocManualLab +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. +(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. +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, +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 +core system and all currently redistributed packages, will +change file timestamps, so one should not rely on them anywhere +in the package). +

+ +To use the conversion and repackaging service, you can provide any of +the four archive formats or even more than one, however you should +adhere to the following rule: text files in .tar.gz +and .tar.bz2 archives must have UNIX style line breaks, +while text files in -win.zip archives must have +DOS/Windows line breaks. +

+ +The package wrapping tools for the &GAP; distribution and web pages +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 +PackageInfo.g file: + + +if it has a .TextFiles component, then consider the given files +as text files before &GAP; defaults will be applied; + + +if it has a .BinaryFiles component, then consider given files +as binary files before &GAP; defaults will be applied; + + +if it has a .TextBinaryFilesPatterns component, then apply it +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 +DosUnixLinebreaks, UnixDosLinebreaks, MacUnixLinebreaks +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, +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 +authors/maintainers. +

+If you tell us about your package +(say, by mail to support@gap-system.org) +we may consider either + + +adding a link to your package homepage from the &GAP; website +(thus, the package will be an undeposited contribution); + + +or redistributing the current version of your package as a part of +the &GAP; distribution (this, the package will be deposited), +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 +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). +

+ + + +
+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. + + + + +Changing the distribution format providing one archive with the core system +and all currently redistributed packages. + + + +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 +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 +still loaded if present. + + + +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 ). + + + +Various improvements in the packages loading mechanism make it 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 +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. + + + + + + +

+ + + +
+Checklists + +checklists + +Package release checklist + +The following checklist may be used by package authors, members of the +&GAP; team responsible for package updates, package editors and referees. + + + + + Test that the package: + + + does not break testinstall.g and testall.g + and does not slow them down noticeably + (see ); + + + may be loaded in various configurations (see ); + + + follows the guidelines of Section + + about names of functions and variables; + + + + + + Package documentation: + + + is built and included in the package archive together with + its source files; + + + states the version, release date and package authors; + + + has the same version, release date and package authors + details as stated in the PackageInfo.g file; + + + is searchable using the &GAP; help system; + + + is clear about the license under which the package is distributed; + + + + + + PackageInfo.g file: + + + has the same version, release date and package authors + details as stated in the package manual; + + + has all mandatory components and also optional components where appropriate; + + + in particular, contains hints to distinguish binary and text files in + case of non-standard file names and extensions; + + + is validated using ; + + + + + + Package archive(s): + + + have correct permisisons 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 ); + + + contain no hidden system files and directories that are not supposed + to be included in the package, e.g. .cvsignore, + .git etc.; + + + + + + Package availability: + + + not only the package archive(s), but also 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; + + + + + + + + + + +Checklist for package upgrade to work with &GAP; 4.5 + +The following checklist will help you to check how well your package is +ready to work with &GAP; 4.5. +

+ + + + +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 ) + + + + + +Revise package dependencies: + + +Check the the PackageInfo.g has the correct list of +needed and suggested packages (see ). + + + +Revise licensing information: + + +Check that the package states clearly under which conditions it is distributed +(see ). + + + +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. + + + + + + + +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 ). + + + +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 if the package still relies on some obsolete variables +(see ) +and try to get rid of their usage. + + + + + + + +

+