  
  [1XA [33X[0;0YGuidelines for Writing a GAP Package[133X[101X
  
  [33X[0;0YThis  appendix  explains the basics of how to write a [5XGAP[105X package so that it
  interfaces  properly  to  [5XGAP[105X.  For the role of [5XGAP[105X packages and the ways to
  load them, see Chapter [14X'Reference: Using GAP Packages'[114X.[133X
  
  [33X[0;0YThere are two basic aspects of creating a [5XGAP[105X package.[133X
  
  [33X[0;0YFirst,  it is a convenient possibility to load additional functionality into
  [5XGAP[105X  including  a smooth integration of the package documentation. Second, a
  package is a way to make your code available to other [5XGAP[105X users.[133X
  
  [33X[0;0YMoreover,  the  [5XGAP[105X  Group  may  provide  some help with redistributing your
  package via the web and ftp site of GAP itself 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 this
  case  the package can take part in the [5XGAP[105X distribution update mechanism and
  becomes a [13Xdeposited[113X package.[133X
  
  [33X[0;0YFurthermore, package authors are encouraged to check if the package would be
  appropriate  for the refereeing process and [13Xsubmit[113X it. If the refereeing has
  been  successful, the package becomes an [13Xaccepted[113X package. Check out the [5XGAP[105X
  Web site [7Xhttp://www.gap-system.org[107X for more details.[133X
  
  [33X[0;0YWe  start  this  chapter with a description how the directory structure of a
  [5XGAP[105X 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.[133X
  
  
  [1XA.1 [33X[0;0YStructure of a GAP Package[133X[101X
  
  [33X[0;0YA  [5XGAP[105X  package  should have an alphanumeric name ([3Xpackage-name[103X, say); mixed
  case is fine, but there should be no whitespaces. All files of a [5XGAP[105X package
  [3Xpackage-name[103X  must  be  collected  in  a single directory [3Xpackage-dir[103X, where
  [3Xpackage-dir[103X  should  be  just [3Xpackage-name[103X preferably converted to lowercase
  and  optionally  followed  by the package version (with or without hyphen to
  separate the version from [3Xpackage-name[103X). Let us call this directory the [13Xhome
  directory[113X of the package.[133X
  
  [33X[0;0YTo   use  the  package  with  [5XGAP[105X,  the  directory  [3Xpackage-dir[103X  must  be  a
  subdirectory  of  a  [11Xpkg[111X directory in (one of) the [5XGAP[105X root directories (see
  [14X'Reference:  GAP  Root  Directories'[114X).  For  example, if [5XGAP[105X is installed in
  [11X/usr/local/gap4[111X  then  the  files of the package [10XMyPack[110X may be placed in the
  directory  [11X/usr/local/gap4/pkg/mypack[111X.  The directory [3Xpackage-dir[103X preferably
  should  have  the  following  structure  (below,  a trailing [10X/[110X distinguishes
  directories from ordinary files):[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28Xpackage-dir/[128X[104X
    [4X[28X  doc/[128X[104X
    [4X[28X  lib/[128X[104X
    [4X[28X  src/[128X[104X
    [4X[28X  tst/[128X[104X
    [4X[28X  README[128X[104X
    [4X[28X  CHANGES[128X[104X
    [4X[28X  configure[128X[104X
    [4X[28X  Makefile.in[128X[104X
    [4X[28X  PackageInfo.g[128X[104X
    [4X[28X  init.g[128X[104X
    [4X[28X  read.g[128X[104X
  [4X[32X[104X
  
  [33X[0;0YThere are three file names with a special meaning in the home directory of a
  package: [11XPackageInfo.g[111X and [11Xinit.g[111X which must be present, and [11Xread.g[111X which is
  optional. We now describe the above files and directories:[133X
  
  [8X
  [11XREADME[111X[108X
        [33X[0;6YThis  should  contain  [21Xhow to get it[121X (from the [5XGAP[105X [10Xftp[110X- 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 [11Xdoc[111X directory (see [14XA.2[114X). Authors' names and addresses
        should  be  repeated  both  in  the package's documentation and in the
        [11XPackageInfo.g[111X (see below).[133X
  
  [8X
  [11XCHANGES[111X[108X
        [33X[0;6YFor  further versions of the package, it will be also useful to have a
        [11XCHANGES[111X  file  that  records  the main changes between versions of the
        package.[133X
  
  [8X[11Xconfigure[111X, [11XMakefile.in[111X[108X
        [33X[0;6YThese files are only necessary if the package has a non-[5XGAP[105X component,
        e.g. some  C code (the files of which should be in the [11Xsrc[111X directory).
        The  [11Xconfigure[111X  and  [11XMakefile.in[111X  files of the [5XExample[105X package provide
        prototypes.  The [11Xconfigure[111X file typically takes a path [3Xpath[103X to the [5XGAP[105X
        root  directory  as argument and uses the value assigned to [10XGAParch[110X in
        the  file  [11Xsysinfo.gap[111X, created when [5XGAP[105X was compiled to determine the
        compilation   architecture,  inserts  this  in  place  of  the  string
        [10X@GAPARCH@[110X in [11XMakefile.in[111X and creates a file [11XMakefile[111X. When [10Xmake[110X is run
        (which,  of  course,  reads the constructed [11XMakefile[111X), a directory [11Xbin[111X
        (if  necessary)  and  subdirectories of [11Xbin[111X with the path equal to the
        string  assigned to [10XGAParch[110X in the file [11Xsysinfo.gap[111X should be created;
        any binaries constructed by compiling the code in [11Xsrc[111X should end up in
        this subdirectory of [11Xbin[111X.[133X
  
  [8X[11XPackageInfo.g[111X[108X
        [33X[0;6YSince  [5XGAP[105X 4.4,  a  [5XGAP[105X  package  [13Xmust[113X have a [11XPackageInfo.g[111X 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  [5XExample[105X package's [11XPackageInfo.g[111X file is well-commented and should
        be used as a prototype (see also [14XA.5[114X for further details).[133X
  
  [8X[11Xinit.g[111X, [11Xread.g[111X[108X
        [33X[0;6YA  [5XGAP[105X  package  [13Xmust[113X  have  a file [11Xinit.g[111X. As of [5XGAP[105X 4.4, the typical
        [11Xinit.g[111X   and   [11Xread.g[111X   files  should  normally  consist  entirely  of
        [2XReadPackage[102X  ([14XReference: ReadPackage[114X) commands (and possibly also [2XRead[102X
        ([14XReference:  Read[114X) commands) for reading further files of the package.
        If  the  [21Xdeclaration[121X  and  [21Ximplementation[121X  parts  of  the  package are
        separated  (and  this  is recommended), there should be a [11Xread.g[111X file.
        The  [21Xdeclaration[121X  part  of a package consists of function and variable
        [13Xname[113X  declarations  and  these  go in files with [10X.gd[110X extensions; these
        files  are  read  in  via [10XReadPackage[110X commands in the [11Xinit.g[111X file. The
        [21Ximplementation[121X part of a package consists of the actual definitions of
        the   functions  and  variables  whose  names  were  declared  in  the
        [21Xdeclaration[121X  part,  and  these  go in files with [10X.gi[110X extensions; these
        files  are  read  in  via [10XReadPackage[110X commands in the [11Xread.g[111X file. The
        reason  for  following  the above dichotomy is that the [11Xread.g[111X file is
        read  [13Xafter[113X  the  [11Xinit.g[111X  file,  thus  enabling  the  possibility of a
        function's  implementation  to refer to another function whose name is
        known  but  is  not  actually  defined  yet  (see  [14XA.8[114X  below for more
        details).[133X
  
        [33X[0;6YThe  [5XGAP[105X  code  (whether  or  not  it  is  split  into [21Xdeclaration[121X and
        [21Ximplementation[121X  parts)  should  go in the package's [11Xlib[111X directory (see
        below).[133X
  
  [8X[11Xdoc[111X[108X
        [33X[0;6YThis  directory  should  contain  the  package's  documentation. It is
        strongly   recommended   to  use  an  XML-based  documentation  format
        supported  by  the  [5XGAP[105X  package [5XGAPDoc[105X (see [14X'GAPDoc: Introduction and
        Example'[114X)  which  is used for the [5XGAP[105X documentation. An alternative is
        to  use  the TeX-based system, formerly used for the [5XGAP[105X documentation
        in  [5XGAP[105X 4.4  and  earlier  releases.  This  system is described in the
        document     [21XThe     gapmacro.tex     Manual    Format[121X    (the    file
        [11Xgap4r5/doc/gapmacrodoc.pdf[111X  included in the tools archive as described
        in  Section  [14XA.2[114X)  and is still used by some of the [5XGAP[105X packages whose
        authors  are  encouraged  to  switch at some point to the [5XGAPDoc[105X-based
        documenation.  Please  spend  some  time reading the documentation for
        whichever  system  you  decide  to  use  for  writing  your  package's
        documentation.  The  [5XExample[105X package's documentation is written in the
        XML  format supported by the [5XGAPDoc[105X package. If you intend to use this
        format, please use the [5XExample[105X package's [11Xdoc[111X directory as a prototype,
        which  as  you will observe contains the master file [11Xmain.xml[111X, further
        [11X.xml[111X  files  for  manual  chapters (included in the manual via [10XInclude[110X
        directives  in the master file) and the [5XGAP[105X input file [11X../makedocrel.g[111X
        which  generates  the  manuals.  Generally,  one should also provide a
        [11Xmanual.bib[111X BibTeX database file or an [11Xxml[111X file in the BibXMLext format
        (see  [14X'GAPDoc:  The  BibXMLext Format'[114X). With [11Xgapmacro.tex[111X, it is also
        possible to use a [11Xmanual.bbl[111X file.[133X
  
  [8X[11Xlib[111X[108X
        [33X[0;6YThis is the preferred place for the [5XGAP[105X code, i.e. the [10X.g[110X, [10X.gd[110X and [10X.gi[110X
        files   (other  than  [11XPackageInfo.g[111X,  [11Xinit.g[111X  and  [11Xread.g[111X).  For  some
        packages,  the directory [11Xgap[111X has been used instead of [11Xlib[111X; [11Xlib[111X has the
        slight  advantage  that  it  is  the default subdirectory of a package
        directory  searched  for  by the [2XDirectoriesPackageLibrary[102X ([14XReference:
        DirectoriesPackageLibrary[114X) command.[133X
  
  [8X[11Xsrc[111X[108X
        [33X[0;6YIf  the  package  has non-[5XGAP[105X code, e.g. C code, then this [21Xsource[121X code
        should  go in the [11Xsrc[111X directory. If there are [10X.h[110X [21Xinclude[121X files you may
        prefer  to  put  these  all  together in a separate [10Xinclude[110X directory.
        There  is  one further rule for the location of kernel library modules
        or external programs which is explained in [14XA.10-1[114X below.[133X
  
  [8X[11Xtst[111X[108X
        [33X[0;6YIf  the  package  has  test  files,  then  they  should  go in the [11Xtst[111X
        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
        [11XPackageInfo.g[111X  to  be  included  in  the [5XGAP[105X standard test suite. More
        specific and time consuming tests are not supposed to be a part of the
        [5XGAP[105X  standard  test  suite but may be placed in the [11Xtst[111X directory with
        further  instructions  on  how to run them. See Section [14XA.14[114X about the
        requirements to the test files formats and further recommendations.[133X
  
  [33X[0;0YAll other files can be organized 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   [11Xexamples[111X   subdirectory,   data   libraries  in  extra
  subdirectories, and so on.[133X
  
  [33X[0;0YSometimes  there  may be a need to include an empty directory in the package
  distribution  (for example, as a place to store some data that may appear at
  runtime).  In this case package authors are advised to put in this directory
  a  short  [11XREADME[111X  file  describing its purpose to ensure that such directory
  will be included in the redistribution.[133X
  
  [33X[0;0YConcerning  the  [5XGAP[105X  code  in  packages,  it  is  recommended  to  use only
  documented  [5XGAP[105X  functions,  see  [14X'Reference:  Undocumented  Variables'[114X.  In
  particular  if you want to make your package available to other [5XGAP[105X users it
  is  advisable to avoid using [21Xobsolescent[121X variables (see [14X'Reference: Replaced
  and  Removed  Command  Names'[114X).  For  that,  you  can  set  the [10XReadObsolete[110X
  component  in  your  [11Xgap.ini[111X  file to [9Xfalse[109X, see [14X'Reference: The gap.ini and
  gaprc files'[114X.[133X
  
  
  [1XA.2 [33X[0;0YWriting Documentation and Tools Needed[133X[101X
  
  [33X[0;0YIf  you intend to make your package available to other users it is essential
  to include documentation explaining how to install and use your programs.[133X
  
  [33X[0;0YConcerning  the  installation you should produce a file [11XREADME[111X 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.[133X
  
  [33X[0;0YConcerning  the  documentation of the use of the package there are currently
  two recognised ways of producing [5XGAP[105X package documentation.[133X
  
  [33X[0;0YFirst, there is a recommended XML-based documentation format that is defined
  in  and  can  be used with the [5XGAPDoc[105X package (see [14X'GAPDoc: Introduction and
  Example'[114X).[133X
  
  [33X[0;0YSecond,  there is a method which requires the documentation to be written in
  TeX  according  to  the  format  described  in the document [21XThe gapmacro.tex
  Manual Format[121X.[133X
  
  [33X[0;0YIn   principle  it  is  also  possible  to  use  some  completely  different
  documentation format. In that case you need to study the Chapter [14X'Reference:
  Interface  to  the  GAP Help System'[114X to learn how to make your documentation
  available to the [5XGAP[105X help system. There should be at least a text version of
  your  documenation  provided  for  use  in the terminal running [5XGAP[105X and some
  nicely  printable  version in [10X.pdf[110X format. Many [5XGAP[105X 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  [5XGAPDoc[105X  package or follow the guidelines in the
  document      [21XThe      gapmacro.tex     Manual     Format[121X,     (the     file
  [11Xgap4r5/doc/gapmacrodoc.pdf[111X  included  in  the  tools archive as described in
  this  Section below), you should have no trouble in producing one. Moreover,
  using the [5XGAPDoc[105X package, it is also possible to produce HTML version of the
  documentation  supporting  MathJax  ([7Xhttp://www.mathjax.org/[107X)  for  the high
  quality  rendering  of  mathematical  symbols  while  viewing it online. For
  example, if you are viewing the HTML version of the manual, compare how this
  formula will look with MathJax turned on/off:[133X
  
  
        [33X[1;6Y[24X[33X[0;0Y[ χ, ψ ] = ( ∑_{g ∈ G} χ(g) ψ(g^{-1}) ) / |G|.[133X[124X[133X
  
  
  [33X[0;0YThe  manual  of  the  [5XExample[105X  package  is written in the [5XGAPDoc[105X format, and
  commands  needed  to  build  it  are contained in the file [10Xmakedocrel.g[110X (you
  don't  need  to  re-build  the  manual  since  it is already included in the
  package).[133X
  
  [33X[0;0YWhenever  you  use  the [5XGAPDoc[105X or [11Xgapmacro.tex[111X TeX-based system, you need to
  have certain TeX tools installed: to produce manuals in the [10X.pdf[110X format, you
  need  [10Xpdflatex[110X  if the [5XGAPDoc[105X is used, and either [10Xpdftex[110X or [10Xgs[110X together with
  [10Xps2pdf[110X  if  your package uses [11Xgapmacro.tex[111X. Note that using [10Xgs[110X and [10Xps2pdf[110X in
  lieu  of  [10Xpdftex[110X or [10Xpdflatex[110X is a poor substitute unless your [10Xgs[110X is at least
  version 6.[3Xxx[103X for some [3Xxx[103X. In addition, the [10Xgapmacro.tex[110X documentation system
  requires  some  more  tools described below. If you intend to use the [5XGAPDoc[105X
  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 [5XGAP[105X
  package.[133X
  
  [33X[0;0YOtherwise,  to  produce  the  [10X.pdf[110X  manual  formats, the following [5XGAP[105X tools
  (supplied  as  a part of the [5XGAP[105X distribution in the archive [10Xtools.tar.gz[110X in
  the  in  [5XGAP[105X's [11Xetc[111X directory and installed using the script [11Xinstall-tools.sh[111X
  in  the  same  directory)  are  needed:  [11Xgapmacro.tex[111X  (the macros file that
  dictates  the  style and mark-up for the traditional TeX-based system of [5XGAP[105X
  documentation),  [10Xmanualindex[110X  (an  [10Xawk[110X  script that adjusts the TeX-produced
  index  entries  and  calls  [10Xmakeindex[110X  to  process  them),  and [11Xmrabbrev.bib[111X
  (usually   supplied   with  your  TeX  tools  but  nevertheless  a  copy  of
  [11Xmrabbrev.bib[111X  should  be  located in [5XGAP[105X's main [11Xdoc[111X directory. To find it on
  your  system,  try:  [10Xkpsewhich mrabbrev.bib[110X or, if that doesn't work and you
  can't  otherwise  find  it  check  out  a  CTAN site, e.g. search for it at:
  [7Xhttp://www.dante.de/cgi-bin/ctan-index[107X.[133X
  
  [33X[0;0YIf  your  manual  cross-refers  to [5XGAPDoc[105X- or [11Xgapmacro.tex[111X-produced manuals,
  then  [10Xmanual.lab[110X  for  each  such other manual is needed. For packages using
  [5XGAPDoc[105X-manuals since [5XGAP[105X 4.3, this is done by starting [5XGAP[105X and running[133X
  
  [33X[0;0Y  [10Xgap> GapDocManualLab( "[3Xpackage[103X[10X" );[110X[133X
  
  [33X[0;0Yfor  each  such [3Xpackage[103X whose manual is cross-referred to (this includes the
  [21Xmain[121X  manuals,  e.g. those  in  the  [11Xdoc/ref[111X  and  [11Xdoc/tut[111X directories). For
  packages  using  [11Xgapmacro.tex[111X-produced  manuals,  [10Xmanual.lab[110X is generated by
  running  [10Xtex  manual[110X  for each package whose manual is cross-referred to. In
  most cases, packages from the [5XGAP[105X 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  [11Xexample/makedocrel.g[111X  script)  and included in their
  distribution,  so  you  will  probably  not  need to create [10Xmanual.lab[110X files
  yourself.[133X
  
  [33X[0;0YTo  produce  an  HTML  version  of  the  manual one needs the Perl 5 program
  [11Xconvert.pl[111X which is included in the tools archive [10Xtools.tar.gz[110X. This archive
  is supplied as a part of the [5XGAP[105X distribution in the [5XGAP[105X's [11Xetc[111X directory and
  should be installed using the script [11Xinstall-tools.sh[111X in the same directory.[133X
  
  [33X[0;0YFinally,  to  ensure  the mathematical formulae are rendered as well as they
  can  be  in  the  HTML version, one should also have the program [10Xtth[110X (TeX to
  HTML converter); [11Xconvert.pl[111X calls [11Xtth[111X to translate mathmode formulae to HTML
  (if  it's available). The [11Xtth[111X program is easy to compile and can be obtained
  from [7Xhttp://hutchinson.belmont.ma.us/tth/tth-noncom/download.html[107X.[133X
  
  
  [1XA.3 [33X[0;0YAn Example of a GAP Package[133X[101X
  
  [33X[0;0YWe  illustrate  the  creation  of  a  [5XGAP[105X  package  by an example of a basic
  package.[133X
  
  [33X[0;0YCreate  the  following  directories  in  your  home area: [11X.gap[111X, [11X.gap/pkg[111X and
  [11X.gap/pkg/test[111X.  Then inside the directory [11X.gap/pkg/test[111X create an empty file
  [11Xinit.g[111X, and a file [11XPackageInfo.g[111X with the following contents:[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28XSetPackageInfo( rec([128X[104X
    [4X[28X  PackageName := "test",[128X[104X
    [4X[28X  Version := "1.0",[128X[104X
    [4X[28X  PackageDoc := rec([128X[104X
    [4X[28X      BookName  := "test",[128X[104X
    [4X[28X      SixFile   := "doc/manual.six",[128X[104X
    [4X[28X      Autoload  := true ),[128X[104X
    [4X[28X  Dependencies := rec([128X[104X
    [4X[28X      GAP       := "4.5",[128X[104X
    [4X[28X      NeededOtherPackages := [ ["GAPDoc", "1.3"] ],[128X[104X
    [4X[28X      SuggestedOtherPackages := [ ] ),[128X[104X
    [4X[28X  AvailabilityTest := ReturnTrue ) );[128X[104X
  [4X[32X[104X
  
  [33X[0;0YThis  file  declares  the  [5XGAP[105X  package  with  name [21Xtest[121X in version 1.0. The
  package documentation consists of one autoloaded book; the [10XSixFile[110X component
  is  needed  by  the  [5XGAP[105X  help system. Package dependencies require at least
  [5XGAP[105X 4.5  and  [5XGAPDoc[105X  package  at version at least 1.3, and these conditions
  will  be checked when the package will be loaded (see [14XA.13[114X). Since there are
  no   requirements  that  have  to  be  tested,  [10XAvailabilityTest[110X  just  uses
  [2XReturnTrue[102X ([14XReference: ReturnTrue[114X).[133X
  
  [33X[0;0YNow  start  [5XGAP[105X (without using the [10X-r[110X option) and the [11X.gap[111X directory will be
  added  to the [5XGAP[105X root directory to allow [5XGAP[105X to find the packages installed
  there (see [14X'Reference: GAP Root Directories'[114X).[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XLoadPackage("test");[127X[104X
    [4X[28Xtrue[128X[104X
  [4X[32X[104X
  
  [33X[0;0YThis  [5XGAP[105X  package  is  too  simple  to  be useful, but we have succeeded in
  loading   it   via  [2XLoadPackage[102X  ([14XReference:  LoadPackage[114X),  satisfying  all
  specified dependencies.[133X
  
  
  [1XA.4 [33X[0;0YFile Structure[133X[101X
  
  [33X[0;0YPackage  files  may follow the style used for the [5XGAP[105X library. Every file in
  the  [5XGAP[105X  library starts with a header that lists the filename, copyright, a
  short  description  of  the  file  contents and the original authors of this
  file,  and ends with a comment line [10X#E[110X. Indentation in functions and the use
  of  decorative spaces in the code are left to the decision of the authors of
  each  file. Global (i.e. 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.[133X
  
  [33X[0;0YHistorically,  when  the  [5XGAP[105X  main  manuals  were  based  on the TeX macros
  described   in  the  document  [21XThe  gapmacro.tex  Manual  Format[121X  (the  file
  [11Xgap4r5/doc/gapmacrodoc.pdf[111X  included  in  the  tools archive as described in
  Section [14XA.2[114X) such headers were used for the manuals and have the type[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28X#############################################################################[128X[104X
    [4X[28X##[128X[104X
    [4X[28X#X  ExampleFunction(<A>,<B>)[128X[104X
    [4X[28X##[128X[104X
    [4X[28X##  This function does great things.[128X[104X
  [4X[32X[104X
  
  [33X[0;0Ywhere [21XX[121X was one of the letters: [10XF[110X, [10XA[110X, [10XP[110X, [10XO[110X, [10XC[110X, [10XR[110X or [10XV[110X indicating whether the
  object   declared  will  be  a  function,  attribute,  property,  operation,
  category,  representation or variable, respectively. Additionally [10XM[110X was used
  in  [10X.gi[110X  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 [10X\Declaration[110X line in some [10X.msk[110X file together with an appropriate
  configuration file.[133X
  
  [33X[0;0YNowadays,  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  [5XGAPDoc[105X  package  (see  [14X'GAPDoc:
  Distributing   a  Document  into  Several  Files'[114X).  The  same  approach  is
  demonstrated  by  the  [5XExample[105X package. E.g. [11Xexample/doc/example.xml[111X has the
  statement [10X<#Include Label="ListDirectory">[110X and [11Xexample/lib/files.gd[111X contains[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28X#############################################################################[128X[104X
    [4X[28X##[128X[104X
    [4X[28X#F  ListDirectory([<dir>])  . . . . . . . . . . list the files in a directory[128X[104X
    [4X[28X##[128X[104X
    [4X[28X##  <#GAPDoc Label="ListDirectory">[128X[104X
    [4X[28X##  <ManSection>[128X[104X
    [4X[28X##  <Func Name="ListDirectory" Arg="[dir]"/>[128X[104X
    [4X[28X##[128X[104X
    [4X[28X##  <Description>[128X[104X
    [4X[28X##  lists the files in directory <A>dir</A> (a string) [128X[104X
    [4X[28X##  or the current directory if called with no arguments.[128X[104X
    [4X[28X##  </Description>[128X[104X
    [4X[28X##  </ManSection>[128X[104X
    [4X[28X##  <#/GAPDoc>[128X[104X
    [4X[28XDeclareGlobalFunction( "ListDirectory" );[128X[104X
  [4X[32X[104X
  
  [33X[0;0YThis  is  all put together in the file [11Xexample/makedocrel.g[111X which builds the
  package  documentation,  calling  [2XMakeGAPDocDoc[102X ([14XGAPDoc: MakeGAPDocDoc[114X) with
  locations of library files containing parts of the documentation.[133X
  
  
  [1XA.5 [33X[0;0YThe PackageInfo.g File[133X[101X
  
  [33X[0;0YAs  a  first  step  the  example in [14XA.3[114X 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 [10XDependencies[110X
  given  in the [11XPackageInfo.g[111X file becomes important (see [14XA.7[114X 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.[133X
  
  [33X[0;0YWe  suggest  to  create a [11XPackageInfo.g[111X file for your package by copying the
  one  in the [5XExample[105X package, distributed with [5XGAP[105X, and then adjusting it for
  your  package.  Within [5XGAP[105X you can look at this template file for a list and
  explanation of all recognized entries by[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28XPager(StringFile(Filename(DirectoriesLibrary(), [128X[104X
    [4X[28X                          "../pkg/example/PackageInfo.g")));[128X[104X
  [4X[32X[104X
  
  [33X[0;0YOnce  you have created the [11XPackageInfo.g[111X file for your package, you can test
  its    validity    with   the   function   [2XValidatePackageInfo[102X   ([14XReference:
  ValidatePackageInfo[114X).[133X
  
  
  [1XA.6 [33X[0;0YFunctions and Variables and Choices of Their Names[133X[101X
  
  [33X[0;0YIn  writing the [5XGAP[105X code for your package you need to be a little careful on
  just how you define your functions and variables.[133X
  
  [33X[0;0Y[13XFirstly[113X,  in  general  one should avoid defining functions and variables via
  assignment statements in the way you would interactively, e.g.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XSquared := x -> x^2;;[127X[104X
    [4X[25Xgap>[125X [27XCubed := function(x) return x^3; end;;[127X[104X
  [4X[32X[104X
  
  [33X[0;0YThe  reason  for  this  is  that  such  functions  and  variables are [13Xeasily
  overwritten[113X and what's more you are not warned about it when it happens.[133X
  
  [33X[0;0YTo  protect  a function or variable against overwriting there is the command
  [2XBindGlobal[102X  ([14XReference: BindGlobal[114X), or alternatively (and equivalently) you
  may  define  a  global  function  via  a  [2XDeclareGlobalFunction[102X  ([14XReference:
  DeclareGlobalFunction[114X)       and      [2XInstallGlobalFunction[102X      ([14XReference:
  InstallGlobalFunction[114X) pair or a global variable via a [2XDeclareGlobalVariable[102X
  ([14XReference:     DeclareGlobalVariable[114X)    and    [2XInstallValue[102X    ([14XReference:
  InstallValue[114X) pair. There are also operations and their methods, and related
  objects   like  attributes  and  filters  which  also  have  [10XDeclare...[110X  and
  [10XInstall...[110X pairs.[133X
  
  [33X[0;0Y[13XSecondly[113X, 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 [5XExample[105X package begin with [10XEg[110X. 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 receive no warning if she accidentally
  overwrites  them).  It's  also important for functions and variables defined
  via      [10XBindGlobal[110X,     [10XDeclareGlobalFunction[110X/[10XInstallGlobalFunction[110X     and
  [10XDeclareGlobalVariable[110X/[10XInstallValue[110X,  in order to avoid name clashes that may
  occur with (extensions of) the [5XGAP[105X library and other packages.[133X
  
  [33X[0;0YAdditionally,  since  [5XGAP[105X 4.5  a  package  may place global variables into a
  local  namespace as explained in [14X'Reference: Namespaces for GAP packages'[114X 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  [10X@[110X  symbol,  e.g. [10XxYz@[110X. Such variables may be used in your
  package  code  safely, as they may be accessed from outside the package only
  by  their full name, i.e. [10XxYz@YourPackageName[110X. This helps to prevent clashes
  between  different packages or between a package and the [5XGAP[105X library because
  of the same variable names.[133X
  
  [33X[0;0YOn   the   other   hand,   operations   and   their   methods  (defined  via
  [2XDeclareOperation[102X  ([14XReference:  DeclareOperation[114X),  [2XInstallMethod[102X ([14XReference:
  InstallMethod[114X)   etc. pairs)   and   their   relatives   do  not  need  this
  consideration,  as  they  avoid  name  clashes by allowing for more than one
  [21Xmethod[121X for the same-named object.[133X
  
  [33X[0;0YTo     demonstrate     the     definition    of    a    function    via    a
  [10XDeclareOperation[110X/[10XInstallMethod[110X  pair, the method [2XRecipe[102X ([14X1.1-8[114X) was included
  in  the  [5XExample[105X  package;  [10XRecipe( FruitCake );[110X gives a [21Xmethod[121X for making a
  fruit cake (forgive the pun).[133X
  
  [33X[0;0Y[13XThirdly[113X,  functions  or  variables with [10XSet[3XXXX[103X[10X[110X or [10XHas[3XXXX[103X[10X[110X names (even if they
  are defined as operations) should be avoided as these may clash with objects
  associated  with  attributes  or  properties  (attributes and properties [3XXXX[103X
  declared   via   the  [10XDeclareAttribute[110X  and  [10XDeclareProperty[110X  commands  have
  associated with them testers of form [10XHas[3XXXX[103X[10X[110X and setters of form [10XSet[3XXXX[103X[10X[110X).[133X
  
  [33X[0;0Y[13XFourthly[113X,  it  is a good idea to have some convention for internal functions
  and  variables  (i.e. the  functions  and variables you don't intend for the
  user to use). For example, they might be entirely CAPITALISED.[133X
  
  [33X[0;0YAdditionally,  there  is  a  recommended naming convention that the [5XGAP[105X core
  system  and  [5XGAP[105X  packages  should  not use global variables starting in the
  lowercase.  This allows to reserve variables with names starting in lowecase
  to  the  [5XGAP[105X  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 [10Xcs[110X, [10Xexp[110X, [10Xngens[110X, [10Xpc[110X, [10Xpow[110X
  which  are  perfectly  fine  for  local  variables, should never be used for
  globals.  Additionally,  the package must not have writable global variables
  with  very  short names even if they are starting in uppercase, for example,
  [10XC1[110X or [10XORB[110X, since they also could be easily overwritten by the user.[133X
  
  [33X[0;0YIt  is a good practice to follow naming conventions used in [5XGAP[105X as explained
  in  [14X'Reference:  Naming Conventions'[114X and [14X'Tutorial: Changing the Structure'[114X,
  which might help users to memorize or even guess names of functions provided
  by the package.[133X
  
  [33X[0;0Y[13XFinally[113X,         note         the         advantage         of         using
  [10XDeclareGlobalFunction[110X/[10XInstallGlobalFunction[110X,
  [10XDeclareGlobalVariable[110X/[10XInstallValue[110X,  etc. pairs  (rather than [10XBindGlobal[110X) to
  define  functions  and variables, which allow the package author to organise
  her  function- and variable- definitions in any order without worrying about
  any  interdependence.  The [10XDeclare...[110X statements should go in files with [10X.gd[110X
  extensions  and  be  loaded  by [10XReadPackage[110X statements in the package [11Xinit.g[111X
  file,  and the [10XInstall...[110X definitions should go in files with [10X.gi[110X extensions
  and  be  loaded  by  [10XReadPackage[110X statements in the package [11Xread.g[111X file; this
  ensures  that  the [10X.gi[110X files are read [13Xafter[113X the [10X.gd[110X files. All other package
  code  should  go  in  [10X.g[110X  files  (other  than  the  [11Xinit.g[111X  and [11Xread.g[111X files
  themselves) and be loaded via [10XReadPackage[110X statements in the [11Xinit.g[111X file.[133X
  
  [33X[0;0YIn conclusion, here is some practical advice on how to check which variables
  are used by the package.[133X
  
  [33X[0;0YFirstly,    there    is    a   function   [2XShowPackageVariables[102X   ([14XReference:
  ShowPackageVariables[114X).  If  the  package  [3Xpkgname[103X  is  available but not yet
  loaded  then  [10XShowPackageVariables(  pkgname  )[110X  prints  a  list  of  global
  variables  that  become  bound and of methods that become installed when the
  package  is  loaded  (for  that,  the  package  will  be actually loaded, so
  [10XShowPackageVariables[110X  can  be  called  only once for the same package in the
  same  [5XGAP[105X  session.)  The  second  optional  argument  [3Xversion[103X may specify a
  particular package version to be loaded. An error message will be printed if
  (the given version of) the package is not available or already loaded.[133X
  
  [33X[0;0YInfo  lines  for  undocumented  variables will be marked with an asterisk [10X*[110X.
  Note  that  the  [5XGAP[105X  help system is case insensitive, so it is difficult to
  document identifiers that differ only by case.[133X
  
  [33X[0;0YThe  following entries are omitted from the list: default setter methods for
  attributes  and properties that are declared in the package, and [10XSet[3Xattr[103X[10X[110X and
  [10XHas[3Xattr[103X[10X[110X type variables where [3Xattr[103X is an attribute or property.[133X
  
  [33X[0;0YFor example, for this package it currently produces the following output:[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XShowPackageVariables("example");[127X[104X
    [4X[28X----------------------------------------------------------------[128X[104X
    [4X[28XLoading  Example 3.3 (Example/Template of a GAP Package)[128X[104X
    [4X[28Xby Werner Nickel (http://www.mathematik.tu-darmstadt.de/~nickel),[128X[104X
    [4X[28X   Greg Gamble (http://www.math.rwth-aachen.de/~Greg.Gamble), and[128X[104X
    [4X[28X   Alexander Konovalov (http://www.cs.st-andrews.ac.uk/~alexk/).[128X[104X
    [4X[28X----------------------------------------------------------------[128X[104X
    [4X[28Xnew global functions:[128X[104X
    [4X[28X  EgSeparatedString( str, c )*[128X[104X
    [4X[28X  FindFile( dir, file )[128X[104X
    [4X[28X  HelloWorld(  )[128X[104X
    [4X[28X  ListDirectory( arg )[128X[104X
    [4X[28X  LoadedPackages(  )[128X[104X
    [4X[28X  WhereIsPkgProgram( prg )[128X[104X
    [4X[28X  Which( prg )[128X[104X
    [4X[28X[128X[104X
    [4X[28Xnew global variables:[128X[104X
    [4X[28X  FruitCake[128X[104X
    [4X[28X[128X[104X
    [4X[28Xnew operations:[128X[104X
    [4X[28X  Recipe( arg )[128X[104X
    [4X[28X[128X[104X
    [4X[28Xnew methods:[128X[104X
    [4X[28X  Recipe( cake )[128X[104X
  [4X[32X[104X
  
  [33X[0;0YAnother  trick  is  to  start  [5XGAP[105X with [10X-r -A[110X options, immediately load your
  package  and  then  call  [2XNamesUserGVars[102X  ([14XReference:  NamesUserGVars[114X) 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 [5XExample[105X it
  produces[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XNamesUserGVars();[127X[104X
    [4X[28X[ "EgSeparatedString", "FindFile", "FruitCake", "HelloWorld", "ListDirectory",[128X[104X
    [4X[28X  "LoadedPackages", "Recipe", "WhereIsPkgProgram", "Which" ][128X[104X
  [4X[32X[104X
  
  [33X[0;0Ybut for packages with dependencies it will also contain variables created by
  other  packages.  Nevertheless,  it  may  be  a  useful  check to search for
  unwanted  variables appearing after package loading. A potentially dangerous
  situation which should be avoided is when the package uses some simply named
  temporary  variables  at  the loading stage. Such [21Xphantom[121X variables may then
  remain  unnoticed  and,  as  a result, there will be no warnings if the user
  occasionally uses the same name as a local variable name in a function. Even
  more dangerous is the case when the user variable with the same name already
  exists before the package is loaded so it will be silently overwritten.[133X
  
  
  [1XA.7 [33X[0;0YPackage Dependencies (Requesting one [5XGAP[105X[101X[1X Package from within Another)[133X[101X
  
  [33X[0;0YIt is possible for one [5XGAP[105X package [10XA[110X, say, to require another package [10XB[110X. For
  that, one simply adds the name and the (least) version number of the package
  [10XB[110X  to the [10XNeededOtherPackages[110X component of the [10XDependencies[110X component of the
  [11XPackageInfo.g[111X  file of the package [10XA[110X. In this situation, loading the package
  [10XA[110X forces that also the package [10XB[110X is loaded, and that [10XA[110X cannot be loaded if [10XB[110X
  is not available.[133X
  
  [33X[0;0YIf  [10XB[110X  is  not  essential for [10XA[110X but should be loaded if it is available (for
  example  because  [10XB[110X  provides  some improvements of the main system that are
  useful  for  [10XA[110X)  then the name and the (least) version number of [10XB[110X should be
  added  to the [10XSuggestedOtherPackages[110X component of the [10XDependencies[110X component
  of  the  [11XPackageInfo.g[111X  file  of  [10XA[110X.  In this situation, loading [10XA[110X forces an
  attempt to load also [10XB[110X, but [10XA[110X is loaded even if [10XB[110X is not available.[133X
  
  [33X[0;0YAlso     the    component    [10XDependencies.OtherPackagesLoadedInAdvance[110X    in
  [11XPackageInfo.g[111X  is  supported,  which describes needed packages that shall be
  loaded  before the current package is loaded. See [14XA.8[114X for details about this
  and  more  generally  about  the order in which the files of the packages in
  question are read.[133X
  
  [33X[0;0YAll  package dependencies must be documented explicitly in the [11XPackageInfo.g[111X
  file. It is important to properly identify package dependencies and make the
  right  decision whether the other package should be [21Xneeded[121X or [21Xsuggested[121X. For
  example,  declaring package as [21Xneeded[121X when [21Xsuggested[121X might be sufficient may
  prevent loading of packages under Windows for no good reason.[133X
  
  [33X[0;0YIt   is   not   appropriate   to  explicitly  call  [2XLoadPackage[102X  ([14XReference:
  LoadPackage[114X) [13Xwhen the package is loaded[113X, 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  that  it  can be loaded with restricted
  functionality  if another package (or standalone program) is missing, and in
  this  case  the  missing package (or binary) is [13Xsuggested[113X. Alternatively, if
  the  package author decides that loading the package in this situation makes
  no sense, then the missing component is [13Xneeded[113X.[133X
  
  [33X[0;0YOn  the other hand, if [2XLoadPackage[102X ([14XReference: LoadPackage[114X) 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
  [2XLoadPackage[102X ([14XReference: LoadPackage[114X).[133X
  
  [33X[0;0YIt  may  happen  that  a  package B that is listed as a suggested package of
  package  A  is  actually needed by A. If no explicit [2XLoadPackage[102X ([14XReference:
  LoadPackage[114X)  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 [10XOnlyNeeded[110X which can be used to
  (recursively)  suppress  loading  the  suggested  packages of the package in
  question. Using this option, one can check whether errors or warnings appear
  when  B is not available (note that this option should be used only for such
  checks  to simulate the situation when package B is not available; it is not
  supposed  to  be used in an actual [5XGAP[105X session when package B will be loaded
  later,  since  this  may cause 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 [2XLoadPackage[102X ([14XReference:
  LoadPackage[114X)  for  B  at loading time (see above) then package B needs to be
  [13Xdeinstalled[113X (i.e. removed) to test loading of A without B.[133X
  
  [33X[0;0YFinally,  if  the package manual is in the [5XGAPDoc[105X format, then [5XGAPDoc[105X should
  still  be  listed as [13Xneeded[113X for this package (not as [13Xsuggested[113X), even though
  [5XGAPDoc[105X is now a needed package for [5XGAP[105X itself.[133X
  
  
  [1XA.8 [33X[0;0YDeclaration and Implementation Part of a Package[133X[101X
  
  [33X[0;0YWhen  [5XGAP[105X  packages  require  each  other in a circular way, a [21Xbootstrapping[121X
  problem  arises  of  defining  functions  before  they  are called. The same
  problem  occurs  in  the [5XGAP[105X library, and it is resolved there by separating
  declarations  (which define global variables such as filters and operations)
  and   implementations  (which  install  global  functions  and  methods)  in
  different files. Any implementation file may use global variables defined in
  any  declaration  file.  [5XGAP[105X  initially  reads all declaration files (in the
  library  they  have  a  [10X.gd[110X  suffix) and afterwards reads all implementation
  files (which have a [10X.gi[110X suffix).[133X
  
  [33X[0;0YSomething  similar  is possible for [5XGAP[105X packages: if a file [11Xread.g[111X exists in
  the  home  directory  of  the  package, this file is read only [13Xafter[113X all the
  [11Xinit.g[111X  files  of  all (implicitly) required [5XGAP[105X packages are read. Thus one
  can  separate  declaration  and implementation for a [5XGAP[105X package in the same
  way  as  is done for the [5XGAP[105X library, by creating a file [11Xread.g[111X, restricting
  the  [2XReadPackage[102X  ([14XReference: ReadPackage[114X) statements in [11Xinit.g[111X to only read
  those  files  of  the  package  that  provide  declarations, and to read the
  implementation files from [11Xread.g[111X.[133X
  
  [33X[0;0Y[13XExamples:[113X[133X
  
  [33X[0;0YSuppose  that  there  are  two  packages [10XA[110X and [10XB[110X, each with files [11Xinit.g[111X and
  [11Xread.g[111X.[133X
  
  [30X    [33X[0;6YIf  package  [10XA[110X suggests or needs package [10XB[110X and package [10XB[110X does not need
        or  suggest  any  other  package  then first [11Xinit.g[111X of [10XB[110X is read, then
        [11Xread.g[111X of [10XB[110X, then [11Xinit.g[111X of [10XA[110X, then [11Xread.g[111X of [10XA[110X.[133X
  
  [30X    [33X[0;6YIf  package  [10XA[110X suggests or needs package [10XB[110X and package [10XB[110X (or a package
        that  is  suggested  or  needed by [10XB[110X) suggests or needs package [10XA[110X then
        first  the  files [11Xinit.g[111X of [10XA[110X and [10XB[110X are read (in an unspecified order)
        and then the files [11Xread.g[111X of [10XA[110X and [10XB[110X (in the same order).[133X
  
  [33X[0;0YIn  general, when [5XGAP[105X is asked to load a package then first the dependencies
  between  this  packages  and its needed and suggested packages are inspected
  (recursively),  and  a  list of package sets is computed such that no cyclic
  dependencies  occur  between different package sets and such that no package
  in any of the package sets needs any package in later package sets. Then [5XGAP[105X
  runs  through the package sets and reads for each set first all [11Xinit.g[111X files
  and  then  all  [11Xread.g[111X  files  of  the  packages  in  the set. (There is one
  exception  from  this  rule:  Whenever  packages  are  autoloaded before the
  implementation part of the [5XGAP[105X library is read, only the [11Xinit.g[111X files of the
  packages  are  read;  as  soon  as the [5XGAP[105X library has been read, the [11Xread.g[111X
  files of these packages are also read, and afterwards the above rule holds.)[133X
  
  [33X[0;0YIt  can  happen  that  some code of a package depends on the availability of
  suggested  packages, i.e., different initializations are performed depending
  on  whether  a  suggested  package will eventually be loaded or not. One can
  test  this condition with the function [2XIsPackageMarkedForLoading[102X ([14XReference:
  IsPackageMarkedForLoading[114X).  In particular, one should [13Xnot[113X call (and use the
  value   returned   by   this  call)  the  function  [2XLoadPackage[102X  ([14XReference:
  LoadPackage[114X)  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 [10XOnlyNeeded[110X.[133X
  
  [33X[0;0YNote  that  the separation of the [5XGAP[105X code of packages into declaration part
  and  implementation  part  does  in  general  [13Xnot[113X allow one to actually [13Xcall[113X
  functions  from a package when the implementation part is read. For example,
  in  the  case of a [21Xcyclic dependency[121X as in the second example above, suppose
  that  [10XB[110X  provides  a new function [10Xf[110X or a new global record [10Xr[110X, say, which are
  declared  in  the declaration part of [10XB[110X. Then the code in the implementation
  part of [10XA[110X may contain calls to the functions defined in the declaration part
  of  [10XB[110X.  However,  the  implementation  part  of  [10XA[110X  may  be  read [13Xbefore[113X the
  implementation  part  of [10XB[110X. So one can in general not assume that during the
  loading  of  [10XA[110X,  the  function  [10Xf[110X  can  be  called,  or  that one can access
  components of the record [10Xr[110X.[133X
  
  [33X[0;0YIf  one wants to call the function [10Xf[110X or to access components of the record [10Xr[110X
  in the code of the package [10XA[110X then the problem is that it may be not possible
  to  determine  a cyclic dependency between [10XA[110X and [10XB[110X from the packages [10XA[110X and [10XB[110X
  alone.  A  safe  solution  is  then  to  add  the name of [10XB[110X to the component
  [10XDependencies.OtherPackagesLoadedInAdvance[110X  of  the  [11XPackageInfo.g[111X file of [10XA[110X.
  The  effect is that package [10XB[110X is completely loaded before the file [11Xread.g[111X of
  [10XA[110X  is read, provided that there is no cyclic dependency between [10XA[110X and [10XB[110X, and
  that  package  [10XA[110X is regarded as not available in the case that such a cyclic
  dependency between [10XA[110X and [10XB[110X exists.[133X
  
  [33X[0;0YA special case where [10XDependencies.OtherPackagesLoadedInAdvance[110X can be useful
  is  that a package wants to force the complete [5XGAP[105X library to be read before
  the  file  [11Xread.g[111X  of  the package [10XA[110X is read. In this situation, the [21Xpackage
  name[121X [10X"gap"[110X should be added to this component in the [11XPackageInfo.g[111X file of [10XA[110X.[133X
  
  [33X[0;0YIn the case of cyclic dependencies, one solution for the above problem might
  be to delay those computations (typically initializations) in package [10XA[110X that
  require  package  [10XB[110X  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 and to
  declare  these  variables  in  the [11Xinit.g[111X file of the package, via a call to
  [2XDeclareAutoreadableVariables[102X  ([14XReference: DeclareAutoreadableVariables[114X) (see
  also [14XA.9[114X).[133X
  
  
  [1XA.9 [33X[0;0YAutoreadable Variables[133X[101X
  
  [33X[0;0YPackage  files containing method installations must be read when the package
  is  loaded.  For  package  files  [13Xnot[113X  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
  [14XReference: DeclareAutoreadableVariables[114X for further details.[133X
  
  
  [1XA.10 [33X[0;0YStandalone Programs in a [5XGAP[105X[101X[1X Package[133X[101X
  
  [33X[0;0Y[5XGAP[105X  packages  that involve stand-alone programs are fundamentally different
  from [5XGAP[105X packages that consist entirely of [5XGAP[105X code.[133X
  
  [33X[0;0YThis  difference is threefold: A user who installs the [5XGAP[105X package must also
  compile  (or install) the package's binaries, the package must check whether
  the  binaries  are indeed available, and finally the [5XGAP[105X 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.[133X
  
  [33X[0;0YIf 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 [5XGAP[105X
  packages  might  also  require this program. We therefore strongly recommend
  the  provision  of  a  documented  [5XGAP[105X  function that will call the external
  binary.  We  also  suggest  to  create  actually two [5XGAP[105X packages; the first
  providing  only  the  binary and the interface and the second (requiring the
  first, see [14XA.7[114X) being the actual [5XGAP[105X package.[133X
  
  
  [1XA.10-1 [33X[0;0YInstallation of [5XGAP[105X[101X[1X Package Binaries[133X[101X
  
  [33X[0;0YThe  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).[133X
  
  [33X[0;0YA  [5XGAP[105X package which includes external binaries contains a [11Xbin[111X subdirectory.
  This   subdirectory  in  turn  contains  subdirectories  for  the  different
  architectures  on which the [5XGAP[105X package binaries are installed. The names of
  these  directories  must  be  the  same  as  the  names  of the architecture
  dependent  subdirectories  of  the main [11Xbin[111X directory. Unless you use a tool
  like  [10Xautoconf[110X  yourself,  you  must  obtain  the correct name of the binary
  directory  from  the  main  [5XGAP[105X  branch.  To  help  with  this, the main [5XGAP[105X
  directory  contains  a  file  [11Xsysinfo.gap[111X  which  assigns the shell variable
  [10XGAParch[110X  to  the  proper  name as determined by [5XGAP[105X's [10Xconfigure[110X process. For
  example on a Linux system, the file [11Xsysinfo.gap[111X may look like this:[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28XGAParch=i586-unknown-linux2.0.31-gcc[128X[104X
  [4X[32X[104X
  
  [33X[0;0YWe  suggest  that your [5XGAP[105X package contains a file [11Xconfigure[111X which is called
  with  the  path  of the [5XGAP[105X root directory as parameter. This file then will
  read  [11Xsysinfo.gap[111X  and  set  up  everything  for  compiling  under the given
  architecture  (for example creating a [11XMakefile[111X from [11XMakefile.in[111X). As initial
  templates, you may use installation scripts of the [5XExample[105X package.[133X
  
  
  [1XA.10-2 [33X[0;0YTest for the Existence of GAP Package Binaries[133X[101X
  
  [33X[0;0YIf  an  external  binary is essential for the workings of a [5XGAP[105X package, the
  function  stored in the component [10XAvailabilityTest[110X of the [11XPackageInfo.g[111X 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.[133X
  
  [33X[0;0YThe  easiest  way to accomplish this is to use [2XFilename[102X ([14XReference: Filename
  (for  a directory and a string)[114X) for checking for the actual binaries in the
  path       given       by       [2XDirectoriesPackagePrograms[102X       ([14XReference:
  DirectoriesPackagePrograms[114X)  for  the  respective  package.  For example the
  [5Xexample[105X  [5XGAP[105X  package  could  use the following function to test whether the
  binary  [11Xhello[111X  has  been  compiled; it will issue a warning if not, and will
  only load the package if the binary is indeed available:[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28X...[128X[104X
    [4X[28XAvailabilityTest := function()[128X[104X
    [4X[28X  local path,file;[128X[104X
    [4X[28X    # test for existence of the compiled binary[128X[104X
    [4X[28X    path:= DirectoriesPackagePrograms( "example" );[128X[104X
    [4X[28X    file:= Filename( path, "hello" );[128X[104X
    [4X[28X    if file = fail then[128X[104X
    [4X[28X      LogPackageLoadingMessage( PACKAGE_WARNING,[128X[104X
    [4X[28X          [ "The program `hello' is not compiled,",[128X[104X
    [4X[28X            "`HelloWorld()' is thus unavailable.",[128X[104X
    [4X[28X            "See the installation instructions;",[128X[104X
    [4X[28X            "type: ?Installing the Example package" ] );[128X[104X
    [4X[28X    fi;[128X[104X
    [4X[28X    return file <> fail;[128X[104X
    [4X[28X  end,[128X[104X
    [4X[28X...[128X[104X
  [4X[32X[104X
  
  [33X[0;0YHowever,  if  you  look  at  the  actual  [11XPackageInfo.g[111X  file of the [5Xexample[105X
  package,  you  will  see  that  its [10XAvailabilityTest[110X function always returns
  [9Xtrue[109X, and just logs the warning if the binary is not available (which may be
  later       viewed       with      [2XDisplayPackageLoadingLog[102X      ([14XReference:
  DisplayPackageLoadingLog[114X)).  This  means  that the binary is not regarded as
  essential for this package.[133X
  
  [33X[0;0YYou  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 [14X'Reference: Testing for the
  System Architecture'[114X for information on how to test for the architecture.[133X
  
  [33X[0;0YLast  but  not least: do not print anything in the [10XAvailabilityTest[110X function
  of   the   package   via   [10XPrint[110X   or   [10XInfo[110X.   Instead   one   should  call
  [2XLogPackageLoadingMessage[102X  ([14XReference:  LogPackageLoadingMessage[114X)  to store a
  message  which may be viewed later with [2XDisplayPackageLoadingLog[102X ([14XReference:
  DisplayPackageLoadingLog[114X)  (the  latter  two  functions  are  introduced  in
  [5XGAP[105X 4.5)[133X
  
  
  [1XA.10-3 [33X[0;0YCalling of and Communication with External Binaries[133X[101X
  
  [33X[0;0YThere  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 [5XGAP[105X.[133X
  
  [33X[0;0YThere are two principal ways of doing this.[133X
  
  [33X[0;0YThe first possibility is to write all the data for the stand-alone to one or
  several  files, then start the stand-alone with [2XProcess[102X ([14XReference: Process[114X)
  or  [2XExec[102X  ([14XReference:  Exec[114X)  which then writes the output data to file, and
  finally read in the standalone's output file.[133X
  
  [33X[0;0YThe    second   way   is   interfacing   via   input-output   streams,   see
  Section [14X'Reference: Input-Output Streams'[114X.[133X
  
  [33X[0;0YSome  [5XGAP[105X packages use kernel modules (see [14X'Reference: Kernel modules in GAP
  packages'[114X) instead of external binaries. A kernel module is implemented in C
  and  follows  certain  conventions  to comply with the [5XGAP[105X 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 [5XGAP[105X developers if
  you plan to develop such a package.[133X
  
  
  [1XA.11 [33X[0;0YHaving an InfoClass[133X[101X
  
  [33X[0;0YIt  is  a good idea to declare an [10XInfoClass[110X 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 [14X'Reference:  Info
  Functions'[114X). Below, we give a quick overview of its utility.[133X
  
  [33X[0;0YAn  [10XInfoClass[110X  is  defined with a [10XDeclareInfoClass( [3XInfoPkgname[103X[10X );[110X statement
  and  may  be  set  to  have an initial [10XInfoLevel[110X other than the zero default
  (which means no [10XInfo[110X statement is to output information) via a [10XSetInfoLevel(
  [3XInfoPkgname[103X[10X, [3Xlevel[103X[10X );[110X statement. An initial [10XInfoLevel[110X of 1 is typical.[133X
  
  [33X[0;0Y[10XInfo[110X statements have the form: [10XInfo( [3XInfoPkgname[103X[10X, [3Xlevel[103X[10X, [3Xexpr1[103X[10X, [3Xexpr2[103X[10X, ...);[110X
  where  the expression list [10X[3Xexpr1[103X[10X, [3Xexpr2[103X[10X, ...[110X appears just like it would in a
  [10XPrint[110X  statement.  The  only  difference is that the expression list is only
  printed  (or  even  executed)  if  the  [10XInfoLevel[110X of [3XInfoPkgname[103X is at least
  [3Xlevel[103X.[133X
  
  
  [1XA.12 [33X[0;0YThe Banner[133X[101X
  
  [33X[0;0YSince  [5XGAP[105X 4.4, the package banner, if one is desired, should be provided by
  assigning  a  string  to  the  [10XBannerString[110X  field of the record argument of
  [10XSetPackageInfo[110X in the [11XPackageInfo.g[111X file.[133X
  
  [33X[0;0YIt  is  a good idea to have a hook into your package documentation from your
  banner. The banner of the [5XExample[105X package suggests to the [5XGAP[105X user:[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28XFor help, type: ?Example package[128X[104X
  [4X[32X[104X
  
  [33X[0;0YIn  order  for  this  to display the introduction of the [5XExample[105X package the
  index-entry  [10X<Index>Example  package</Index>[110X was added just before the first
  paragraph  of  the introductory section in the file [11Xexample.xml[111X. The [5XExample[105X
  package  uses [5XGAPDoc[105X (see Section [14XA.2[114X) for documentation (you will need some
  different scheme to achieve this using the [11Xgapmacro.tex[111X system).[133X
  
  
  [1XA.13 [33X[0;0YVersion Numbers[133X[101X
  
  [33X[0;0YVersion  numbers  are  strings  containing nonnegative integers separated by
  non-numeric   characters.   They   are   compared  by  [2XCompareVersionNumbers[102X
  ([14XReference:  CompareVersionNumbers[114X)  which  first  splits  them at non-digit
  characters  and then lexicographically compares the resulting integer lists.
  Thus  version  [10X"2-3"[110X is larger than version [10X"2-2-5"[110X but smaller than [10X"4r2p3"[110X
  or [10X"11.0"[110X.[133X
  
  [33X[0;0YIt is possible for code to require [5XGAP[105X 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.[133X
  
  [33X[0;0YLoading  a  specific  version  of  a package (that is, [13Xnot[113X one with a larger
  version  number)  can  be  achieved  by  prepending [10X=[110X to the desired version
  number.  For  example,  [10XLoadPackage(  "example",  "=1.0" )[110X will load version
  [10X"1.0"[110X  of  the  package  [10X"example"[110X, even if version [10X"1.1"[110X is available. As a
  consequence, version numbers must not start with [10X=[110X, so [10X"=1.0"[110X is not a valid
  version number.[133X
  
  [33X[0;0YPackage  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  [5XGAP[105X distribution will only work if a
  package has a new version number.[133X
  
  [33X[0;0YIt   is   a   well-established   custom   to   name  package  archives  like
  [11Xname-version.tar.gz[111X, [11Xname-version.tar.bz2[111X etc., where [10Xname[110X is the lower case
  name,  and  [10Xversion[110X  is the version (another custom is that the archive then
  should extract to a directory that has exactly the name [11Xname-version[111X).[133X
  
  [33X[0;0YIt is very important that there should not ever be, for a given [5XGAP[105X 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.[133X
  
  [33X[0;0YFor  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".[133X
  
  [33X[0;0YSince  version  information  is  duplicated in several places throughout the
  package  documentation,  for [5XGAPDoc[105X-based manuals you may define the version
  and  the  release  manual in the comments in [11XPackageInfo.g[111X file close to the
  place where you specified its [10XVersion[110X and [10XDate[110X components, for example[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28X##  <#GAPDoc Label="PKGVERSIONDATA">[128X[104X
    [4X[28X##  <!ENTITY VERSION "3.3">[128X[104X
    [4X[28X##  <!ENTITY RELEASEDATE "11/11/2011">[128X[104X
    [4X[28X##  <#/GAPDoc>[128X[104X
  [4X[32X[104X
  
  [33X[0;0Ynotify  [2XMakeGAPDocDoc[102X ([14XGAPDoc: MakeGAPDocDoc[114X) that a part of the document is
  stored  in [11XPackageInfo.g[111X (see [11Xexample/makedocrel.g[111X), read this data into the
  header  of the main document via [10X<#Include Label="PKGVERSIONDATA">[110X 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).[133X
  
  
  [1XA.14 [33X[0;0YTesting a [5XGAP[105X[101X[1X package[133X[101X
  
  
  [1XA.14-1 [33X[0;0YTests files for a GAP package[133X[101X
  
  [33X[0;0YThe  (optional)  [11Xtst[111X  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 [11Xtst[111X directory of the [5XGAP[105X
  distribution as documented in [14X'Reference: Test Files'[114X.[133X
  
  [33X[0;0YFor  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 [10XTestFile[110X in the [11XPackageInfo.g[111X
  to  be included in the GAP standard test suite. This file can either consist
  of  [2XTest[102X  ([14XReference:  Test[114X)  calls  (in  this case, it is common to call it
  [11Xtestall.g[111X) or be itself a test file having an extension [11X.tst[111X and supposed to
  be  read  via  [2XTest[102X  ([14XReference:  Test[114X).  It is assumed that the latter case
  occurs if and only if the file contains the substring[133X
  
  [33X[0;0Y [10X"gap> START_TEST("[110X[133X
  
  [33X[0;0Y(with exactly one space after the [5XGAP[105X prompt).[133X
  
  [33X[0;0YFor deposited packages, these tests are run by the [5XGAP[105X Group regularly, as a
  part  of  the  standard  [5XGAP[105X  test  suite.  For  the efficient testing it is
  important that the test specified in the [11XPackageInfo.g[111X 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:[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XTest("tst/testall.tst");[127X[104X
    [4X[28XExample package: testall.tst[128X[104X
    [4X[28XGAP4stones: 3333[128X[104X
    [4X[28Xtrue[128X[104X
  [4X[32X[104X
  
  [33X[0;0YTests  which produce extended output and/or requires substantial runtime are
  not  supposed  to be a part of the [5XGAP[105X standard test suite but may be placed
  in the [11Xtst[111X directory of the packages with further instructions on how to run
  them elsewhere.[133X
  
  
  [1XA.14-2 [33X[0;0YTesting [5XGAP[105X[101X[1X package loading[133X[101X
  
  [33X[0;0YTo  test  that  your package may be loaded into [5XGAP[105X without any problems and
  conflicts  with  other  packages,  test  that  it  may  be loaded in various
  configurations:[133X
  
  [30X    [33X[0;6Ystarting  [5XGAP[105X  with  no  packages  (except needed for [5XGAP[105X) using [10X-r -A[110X
        options and calling [10XLoadPackage("your-package-name");[110X[133X
  
  [30X    [33X[0;6Ystarting  [5XGAP[105X  with  no  packages  (except needed for [5XGAP[105X) using [10X-r -A[110X
        options and calling [10XLoadPackage("your-package-name" : OnlyNeeded );[110X[133X
  
  [30X    [33X[0;6Ystarting  [5XGAP[105X  in  the  default  configuration  (with  no options) and
        calling [10XLoadPackage("your-package-name");[110X[133X
  
  [30X    [33X[0;6Ystarting  [5XGAP[105X  in  the  default  configuration  (with  no options) and
        calling [10XLoadPackage("your-package-name" : OnlyNeeded );[110X[133X
  
  [30X    [33X[0;6Yfinally,  together  with  all  other  packages  using  [2XLoadAllPackages[102X
        ([14XA.14-3[114X)  (see  below)  in  four possible combinations of starting [5XGAP[105X
        with/without  [10X-r  -A[110X  options  and  calling  [2XLoadAllPackages[102X  ([14XA.14-3[114X)
        with/without [10XReversed[110X option.[133X
  
  [33X[0;0YThe  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.[133X
  
  [33X[0;0YFor your convenience, [10Xmake testpackagesload[110X called in the [5XGAP[105X root directory
  will run all package loading tests listed in this subsection and write their
  output in its [10Xdev/log[110X directory.[133X
  
  [33X[0;0YIt  will  produce four files with test logs, corresponding to the four cases
  above  (the  letter  [10XN[110X  in  the  filename  stands  for  [21Xneeded[121X, [10XA[110X stands for
  [21Xautoloaded[121X):[133X
  
  [30X    [33X[0;6Y[11Xdev/log/testpackagesload1_...[111X[133X
  
  [30X    [33X[0;6Y[11Xdev/log/testpackagesloadN1_...[111X[133X
  
  [30X    [33X[0;6Y[11Xdev/log/testpackagesloadA_...[111X[133X
  
  [30X    [33X[0;6Y[11Xdev/log/testpackagesloadNA_...[111X[133X
  
  [33X[0;0YEach  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 [5XExample[105X package looks
  like[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28X%%% Loading example 3.3.3[128X[104X
    [4X[28X[  ][128X[104X
    [4X[28X### Loaded example 3.3.3[128X[104X
  [4X[32X[104X
  
  [33X[0;0Yso it has clearly passed the test. If there are any error messages displayed
  between  [10XLoading ...[110X and [10XLoaded ...[110X lines, they will signal on errors during
  loading of your package.[133X
  
  [33X[0;0YAdditionally,  this  test collects information about variables created since
  the   library   was   read   (obtained   using   [2XNamesUserGVars[102X  ([14XReference:
  NamesUserGVars[114X))  with either short names (no more than three characters) or
  names  breaking a recommended naming convention that the [5XGAP[105X core system and
  [5XGAP[105X  packages should not use global variables starting in the lowercase (see
  Section  [14XA.6[114X).  Their list will be displayed in the test log (in the example
  above, [5XExample[105X 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  [2XShowPackageVariables[102X
  ([14XReference: ShowPackageVariables[114X) (also, [10Xmake testpackagesvars[110X called in the
  [5XGAP[105X root directory produces such reports for each package and writes them to
  a file [11Xdev/log/testpackagesvars_...[111X).[133X
  
  [33X[0;0YFinally,  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 [2XLoadAllPackages[102X
  ([14XA.14-3[114X) 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 [5XGAP[105X,
  it  is  likely  that  your  package triggers this error. If you observe that
  [2XLoadAllPackages[102X ([14XA.14-3[114X) is broken and suspect that this is not the fault of
  your package, please contact the [5XGAP[105X Support.[133X
  
  [1XA.14-3 LoadAllPackages[101X
  
  [29X[2XLoadAllPackages[102X( [3X:[103X [3XReversed[103X ) [32X function
  
  [33X[0;0Yloads  all [5XGAP[105X 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 [5XGAP[105X performance is slower if all
  packages  are  loaded.  To  introduce  some variations of the order in which
  packages  will  be  loaded  for  testing  purposes,  [2XLoadAllPackages[102X accepts
  version  [10XReversed[110X  to  load  packages  from their list sorted in the reverse
  alphabetical order.[133X
  
  
  [1XA.14-4 [33X[0;0YTesting a [5XGAP[105X[101X[1X package with the [5XGAP[105X[101X[1X standard test suite[133X[101X
  
  [33X[0;0YThe [11Xtst[111X directory of the [5XGAP[105X installation contains a selection of test files
  and  two  scripts,  [11Xtestinstall.g[111X  and [11Xtestall.g[111X which are a part of the [5XGAP[105X
  standard test suite.[133X
  
  [33X[0;0YIt  is  important  to  check  that  your package does not break [5XGAP[105X standard
  tests.  To  perform  a clean test and avoid interfering with other packages,
  first  you must start a new [5XGAP[105X session with the following command (assuming
  that [10Xgap[110X starts [5XGAP[105X in your system):[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28Xgap -N -A -x 80 -r -m 100m -o 512m[128X[104X
  [4X[32X[104X
  
  [33X[0;0YAfter  that  load  your package and run either [11Xtestinstall.g[111X or [11Xtestall.g[111X as
  demonstrated below.[133X
  
  [33X[0;0YThe quicker test, [11Xtestinstall.g[111X, 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[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XRead( Filename( DirectoriesLibrary( "tst" ), "testinstall.g" ) );[127X[104X
  [4X[32X[104X
  
  [33X[0;0YYou  will  get a large number of lines with output about the progress of the
  tests.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28Xtest file         GAP4stones     time(msec)[128X[104X
    [4X[28X-------------------------------------------[128X[104X
    [4X[28Xtesting: .../gap4r5/tst/zlattice.tst[128X[104X
    [4X[28Xzlattice.tst               0              0[128X[104X
    [4X[28Xtesting: .../gap4r5/tst/gaussian.tst[128X[104X
    [4X[28Xgaussian.tst               0             10[128X[104X
    [4X[28X... further lines deleted ...[128X[104X
  [4X[32X[104X
  
  [33X[0;0YThe   more  thorough  test  is  [11Xtestall.g[111X  which  exercises  more  of  [5XGAP[105X's
  capabilities,  containing  all test files from [11Xtestinstall.g[111X 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 [5XGAP[105X session with [10Xgap -N -A -x 80 -r -m
  100m -o 512m[110X and then call[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XRead( Filename( DirectoriesLibrary( "tst" ), "testall.g" ) );[127X[104X
  [4X[32X[104X
  
  [33X[0;0YYou  may  repeat the same check loading your package with [10XOnlyNeeded[110X option.
  Remember to perform each subsequent test in a new [5XGAP[105X session.[133X
  
  [33X[0;0YAlso  you  may  perform  individual  tests from the [11Xtst[111X directory of the [5XGAP[105X
  installation loading them with [2XTest[102X ([14XReference: Test[114X), for example, the file
  [11Xbugfix.tst[111X.[133X
  
  
  [1XA.15 [33X[0;0YAccess to the [5XGAP[105X[101X[1X Development Version[133X[101X
  
  [33X[0;0YWe  are  aiming  at  providing a stable platform for package development and
  testing  with  official  [5XGAP[105X releases. However, when it may be of benefit to
  obtain access to the [5XGAP[105X development version, please contact the [5XGAP[105X team by
  mailing to [7Xmailto:support@gap-system.org[107X.[133X
  
  
  [1XA.16 [33X[0;0YSelecting a license for a [5XGAP[105X[101X[1X Package[133X[101X
  
  [33X[0;0YIt 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 [21XChoosing a License for the Distribution of Your Package[121X from
  [7Xhttp://www.gap-system.org/Packages/Authors/authors.html[107X for further details.[133X
  
  [33X[0;0YIn  the  past  many  [5XGAP[105X  packages  used  the  text  [21XWe  adopt the copyright
  regulations  of GAP as detailed in the copyright notice in the [5XGAP[105X manual[121X or
  a  similar  statement.  We now advise to be more explicit and make the exact
  reference to the GPL license, for example:[133X
  
  [33X[0;0Y[13X  [5Xpackage-name[105X  is  free  software; you can redistribute it and/or modify it
  under     the     terms     of    the    GNU    General    Public    License
  ([7Xhttp://www.fsf.org/licenses/gpl.html[107X)  as  published  by  the Free Software
  Foundation;  either  version 2 of the License, or (at your option) any later
  version. [113X[133X
  
  
  [1XA.17 [33X[0;0YWrapping up a [5XGAP[105X[101X[1X Package[133X[101X
  
  [33X[0;0YCurrently, the [5XGAP[105X distribution provides archives in four different formats.[133X
  
  [8X[11X.tar.gz[111X[108X
        [33X[0;6Ya standard UNIX [10Xtar[110X archive, compressed with [10Xgzip[110X[133X
  
  [8X[11X.tar.bz2[111X[108X
        [33X[0;6Ya standard UNIX [10Xtar[110X archive, compressed with [10Xbzip2[110X[133X
  
  [8X[11X.zip[111X[108X
        [33X[0;6Yan archive in [10Xzip[110X format, where text files should have UNIX style line
        breaks[133X
  
  [8X[11X-win.zip[111X[108X
        [33X[0;6Yan  archive  in  [10Xzip[110X  format, where text files should have DOS/Windows
        style line breaks[133X
  
  [33X[0;0YFor convenience of possible users it is sensible that you provide an archive
  of your package in at least one of these formats.[133X
  
  [33X[0;0YFor example, if you wish to supply a [11X.tar.gz[111X archive, you may create it with
  the command[133X
  
  [33X[0;0Y [10Xtar -cvzf package-name-version.tar.gz package-name[110X[133X
  
  [33X[0;0YThe   [11Xetc[111X   directory   obtained   from  [10Xtools.tar.gz[110X  (described  above  in
  Section [14XA.2[114X)  contains  a  file  [11Xpackpack[111X  which  provides  a more versatile
  packing-up script.[133X
  
  [33X[0;0YBecause the release of the [5XGAP[105X package is independent of the version of [5XGAP[105X,
  a  [5XGAP[105X  package  should be wrapped up in separate file that can be installed
  onto  any  version  of  [5XGAP[105X. In this way, a package can be upgraded any time
  without  the  need to wait for new [5XGAP[105X releases. To ensure this, the package
  should  be  archived  from  the  [5XGAP[105X  [11Xpkg[111X  directory,  that is all files are
  archived with the path starting at the package's name.[133X
  
  [33X[0;0YThe  archive  of  a  [5XGAP[105X  package should contain all files necessary for the
  package  to  work.  In  particular there should be a compiled documentation,
  which  includes  the  [11Xmanual.six[111X,  [11Xmanual.toc[111X  and  [11Xmanual.lab[111X  file  in the
  documentation subdirectory which are created by TeXing the documentation, if
  you  use  [5XGAPDoc[105X  or the [11Xgapmacro.tex[111X document formats. (The first two files
  are  needed by the [5XGAP[105X help system, and the [11Xmanual.lab[111X file is needed if the
  main  manuals  or  another  package  is  referring  to your package. Use the
  command  [10XGAPDocManualLab(  packagename  );[110X to create this file for your help
  books if you use [5XGAPDoc[105X.)[133X
  
  [33X[0;0YFor  packages  which  are  redistributed  via  the [5XGAP[105X 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 [5XGAP[105X 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).[133X
  
  [33X[0;0YTo  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 [11X.tar.gz[111X and [11X.tar.bz2[111X archives must have UNIX
  style  line  breaks,  while  text  files  in  [11X-win.zip[111X  archives  must  have
  DOS/Windows line breaks.[133X
  
  [33X[0;0YThe  package wrapping tools for the [5XGAP[105X 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 [11XPackageInfo.g[111X file:[133X
  
  [30X    [33X[0;6Yif  it  has  a  [10X.TextFiles[110X component, then consider the given files as
        text files before [5XGAP[105X defaults will be applied;[133X
  
  [30X    [33X[0;6Yif  it  has  a  [10X.BinaryFiles[110X  component,  then consider given files as
        binary files before [5XGAP[105X defaults will be applied;[133X
  
  [30X    [33X[0;6Yif  it  has a [10X.TextBinaryFilesPatterns[110X component, then apply it before
        [5XGAP[105X defaults will be applied;[133X
  
  [33X[0;0YThe   [11Xetc[111X   directory   obtained   from  [10Xtools.tar.gz[110X  (described  above  in
  Section [14XA.2[114X)    contains    a    file   [11Xclassifyfiles.py[111X   and   two   files
  [11Xpatternscolor.txt[111X  and [11Xpatternstextbinary.txt[111X implementing [5XGAP[105X 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, [10X.TextBinaryFilesPatterns[110X,
  or  [10X.TextFiles[110X,  or  [10X.BinaryFiles[110X 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.[133X
  
  [33X[0;0YUtility     functions     available     in    [11Xgap4r7/lib/lbutil.g[111X,    namely
  [10XDosUnixLinebreaks[110X, [10XUnixDosLinebreaks[110X, [10XMacUnixLinebreaks[110X may be helpful. They
  are described in the comments to their source code.[133X
  
  
  [1XA.18 [33X[0;0YThe WWW Homepage of a Package[133X[101X
  
  [33X[0;0YIf  you  want  to  distribute  your package you should create a WWW homepage
  containing  some  basic  information, archives for download, the [11XREADME[111X file
  with  installation  instructions,  and a copy of the package's [11XPackageInfo.g[111X
  file.[133X
  
  [33X[0;0YThe   responsibility   for   this   WWW   homepage   is   with  the  package
  authors/maintainers.[133X
  
  [33X[0;0YIf    you    tell    us    about    your    package   (say,   by   mail   to
  [7Xmailto:support@gap-system.org[107X) we may consider either[133X
  
  [30X    [33X[0;6Yadding a link to your package homepage from the [5XGAP[105X website (thus, the
        package will be an [13Xundeposited contribution[113X);[133X
  
  [30X    [33X[0;6Yor redistributing the current version of your package as a part of the
        [5XGAP[105X distribution (this, the package will be [13Xdeposited[113X), also ;[133X
  
  [33X[0;0YIn  the  latter case we can also provide some services for producing several
  archive  formats  from  the archive you provide (e.g., you produce a [10X.tar.gz[110X
  version  of  your  archive  and  we  produce  also a [10X.tar.bz2[110X and a [10X-win.zip[110X
  version from it).[133X
  
  [33X[0;0YPlease  also  consider submitting your package to the [5XGAP[105X package refereeing
  process   (see  [7Xhttp://www.gap-system.org/Contacts/submit.html[107X  for  further
  information).[133X
  
  
  [1XA.19 [33X[0;0YUpgrading the package to work with [5XGAP[105X[101X[1X 4.5[133X[101X
  
  
  [1XA.19-1 [33X[0;0YChanges in [5XGAP[105X[101X[1X 4.5 from the packages perspective[133X[101X
  
  [33X[0;0YHere  we  list  only  those changes which may have some implications for the
  packages.[133X
  
  [30X    [33X[0;6YChanging  the  distribution format providing one archive with the core
        system and all currently redistributed packages.[133X
  
  [30X    [33X[0;6YThe [5XGAP[105X 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
        [7Xhttp://www.gap-system.org/Download/[107X      for      [5XGAP[105X     installation
        instructions).[133X
  
  [30X    [33X[0;6YThe  [5XGAP[105X  documentation  has  been  converted to the [5XGAPDoc[105X format and
        extensively  reviewed. Now it has only two books: the Tutorial and the
        Reference  Manual.  The two other books, [21XExtending [5XGAP[105X[121X and [21XProgramming
        Tutorial[121X  became parts of the Reference Manual. Packages that refer to
        parts  of  the  [5XGAP[105X documentation may need to rebuild their manuals to
        update references.[133X
  
        [33X[0;6YSome packages still use the old [21Xgapmacro[121X format for their manuals, for
        which  support  may  be discontinued in the future. There is no urgent
        need  to  convert  such  manuals into the [5XGAPDoc[105X format before [5XGAP[105X 4.5
        release, but we encourage you very much to consider doing this at some
        later point.[133X
  
  [30X    [33X[0;6YThe  old concept of an autoloaded package has been integrated with the
        [13Xneeded[113X  and  [13Xsuggested[113X mechanism that already exists between packages.
        [5XGAP[105X  itself  now  [21Xneeds[121X  certain  packages  (for  instance [5XGAPDoc[105X) and
        [21Xsuggests[121X  others  (typically  the  packages that were autoloaded). The
        decisions  which  packages  [5XGAP[105X  should  need  or  suggest are made by
        developers  based on technical criteria. They can be easily overridden
        by a user using the new [11Xgap.ini[111X (see [14X'Reference: The gap.ini and gaprc
        files'[114X).  The  default  file  ensures  that  all previously autoloaded
        packages are still loaded if present.[133X
  
  [30X    [33X[0;6YOptional  [11X~/.gap[111X directory for user's customisations which may contain
        e.g.   locally   installed   packages   (see   [14X'Reference:   GAP  Root
        Directories'[114X).  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 [11X.gaprc[111X files, but those are still
        supported  for  backwards  compatibility  (see  [14X'Reference: The former
        .gaprc file'[114X).[133X
  
  [30X    [33X[0;6YVarious  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
        [2XLogPackageLoadingMessage[102X   ([14XReference:  LogPackageLoadingMessage[114X)  and
        there    is    a    function    [2XDisplayPackageLoadingLog[102X   ([14XReference:
        DisplayPackageLoadingLog[114X)  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.[133X
  
  [30X    [33X[0;6YSince  [5XGAP[105X 4.5  a  package  may  place  global  variables into a local
        namespace  as explained in [14X'Reference: Namespaces for GAP packages'[114X in
        order to avoid name clashes and preserve compatibility.[133X
  
  [30X    [33X[0;6YIn  [5XGAP[105X 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 [2XRecNames[102X ([14XReference: RecNames[114X) 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  [2XSet[102X ([14XReference: Set[114X), sort lists of records,
        find  records with binary search, etc., but a care should be taken not
        to  rely  on  [2XRecNames[102X ([14XReference: RecNames[114X) always returning names of
        components in the same order.[133X
  
  
  [1XA.20 [33X[0;0YChecklists[133X[101X
  
  
  [1XA.20-1 [33X[0;0YPackage release checklist[133X[101X
  
  [33X[0;0YThe  following  checklist may be used by package authors, members of the [5XGAP[105X
  team responsible for package updates, package editors and referees.[133X
  
  [30X    [33X[0;6YTest that the package:[133X
  
        [30X    [33X[0;12Ydoes  not  break  [11Xtestinstall.g[111X  and [11Xtestall.g[111X and does not slow
              them down noticeably (see [14XA.14-4[114X);[133X
  
        [30X    [33X[0;12Ymay be loaded in various configurations (see [14XA.14-2[114X);[133X
  
        [30X    [33X[0;12Yfollows  the  guidelines of Section [14XA.6[114X about names of functions
              and variables;[133X
  
  [30X    [33X[0;6YPackage documentation:[133X
  
        [30X    [33X[0;12Yis  built  and included in the package archive together with its
              source files;[133X
  
        [30X    [33X[0;12Ystates the version, release date and package authors;[133X
  
        [30X    [33X[0;12Yhas  the  same version, release date and package authors details
              as stated in the [11XPackageInfo.g[111X file;[133X
  
        [30X    [33X[0;12Yis searchable using the [5XGAP[105X help system;[133X
  
        [30X    [33X[0;12Yis   clear   about  the  license  under  which  the  package  is
              distributed;[133X
  
  [30X    [33X[0;6Y[11XPackageInfo.g[111X file:[133X
  
        [30X    [33X[0;12Yhas  the  same version, release date and package authors details
              as stated in the package manual;[133X
  
        [30X    [33X[0;12Yhas  all mandatory components and also optional components where
              appropriate;[133X
  
        [30X    [33X[0;12Yin  particular,  contains  hints  to distinguish binary and text
              files in case of non-standard file names and extensions;[133X
  
        [30X    [33X[0;12Yis     validated     using    [2XValidatePackageInfo[102X    ([14XReference:
              ValidatePackageInfo[114X);[133X
  
  [30X    [33X[0;6YPackage archive(s):[133X
  
        [30X    [33X[0;12Yhave  correct  permisisons  for  all files and directories after
              their  unpacking  (755  for directories and executables, if any;
              644 for other files);[133X
  
        [30X    [33X[0;12Ycontain files with correct line breaks for the given format (see
              [14XA.17[114X);[133X
  
        [30X    [33X[0;12Ycontain  no  hidden  system  files  and directories that are not
              supposed  to  be  included in the package, e.g. [11X.cvsignore[111X, [11X.git[111X
              etc.;[133X
  
  [30X    [33X[0;6YPackage availability:[133X
  
        [30X    [33X[0;12Ynot  only the package archive(s), but also the [11XPackageInfo.g[111X and
              [11XREADME[111X files are available online;[133X
  
        [30X    [33X[0;12Ythe  URL of the [11XPackageInfo.g[111X file is validated using the online
              tool                        available                       from
              [7Xhttp://www.gap-system.org/Packages/Authors/authors.html[107X;[133X
  
  
  [1XA.20-2 [33X[0;0YChecklist for package upgrade to work with [5XGAP[105X[101X[1X 4.5[133X[101X
  
  [33X[0;0YThe  following  checklist  will  help  you to check how well your package is
  ready to work with [5XGAP[105X 4.5.[133X
  
  [30X    [33X[0;6YMandatory changes needed for package upgrade to work with [5XGAP[105X 4.5:[133X
  
        [8X
  Check that the package works as expected:
  [108X
              [30X    [33X[0;18Yverify  that  the package functionality works as required,
                    that  examples  in  the  manual  are correct and that test
                    files show no discrepancies;[133X
  
              [30X    [33X[0;18Yif  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);[133X
  
              [30X    [33X[0;18Ycheck the usage of names of record components in the code:
                    take  care  not  to rely on [2XRecNames[102X ([14XReference: RecNames[114X)
                    always  returning  names  of  components in the same order
                    (see [14XA.19[114X)[133X
  
        [8X
  Revise package dependencies:
  [108X
              [33X[0;12YCheck  the  the [11XPackageInfo.g[111X has the correct list of needed and
              suggested packages (see [14XA.7[114X).[133X
  
        [8X
  Revise licensing information:
  [108X
              [33X[0;12YCheck  that the package states clearly under which conditions it
              is distributed (see [14XA.16[114X).[133X
  
        [8X
  Rebuild the package documentation:
  [108X
              [33X[0;12Ywhenever    your    package    documentation    is   [5XGAPDoc[105X   or
              [10Xgapmacro.tex[110X-based, [5XGAP[105X 4.5 contains new versions of both tools.
              This  will  ensure that cross-references from the package manual
              to the main [5XGAP[105X manuals are correct and that the [5XGAP[105X 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, [5XGAPDoc[105X has a better [11X.css[111X file and
              is capable of producing the HTML version with MathJax support to
              display nicely mathematical formulae.[133X
  
              [33X[0;12YNote that it's not possible for a package to have an HTML manual
              which  contains  correct  links to both [5XGAP[105X 4.4 and [5XGAP[105X 4.5 main
              manuals.[133X
  
  [30X    [33X[0;6YOptional changes recommended for package upgrade to work with [5XGAP[105X 4.5:[133X
  
        [30X    [33X[0;12YWhen  the  [10XAvailabilityTest[110X  component  in [11XPackageInfo.g[111X differs
              from      [2XReturnTrue[102X      ([14XReference:      ReturnTrue[114X),      use
              [2XLogPackageLoadingMessage[102X  ([14XReference:  LogPackageLoadingMessage[114X)
              to   store   a   message   which   may   be  viewed  later  with
              [2XDisplayPackageLoadingLog[102X  ([14XReference:  DisplayPackageLoadingLog[114X)
              instead of calling [10XPrint[110X or [10XInfo[110X directly (see [14XA.10-2[114X).[133X
  
        [30X    [33X[0;12YIt   is   recommended   not   to  call  [2XLoadPackage[102X  ([14XReference:
              LoadPackage[114X)  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
              [10XDisplayPackageLoadingLog(  PACKAGE_WARNING  );[110X.  If  there  is a
              genuine need to decide whether some package will be available at
              runtime,  use the function [2XIsPackageMarkedForLoading[102X ([14XReference:
              IsPackageMarkedForLoading[114X) introduced in [5XGAP[105X 4.5.[133X
  
        [30X    [33X[0;12YCheck  if  the  package  still relies on some obsolete variables
              (see [14X'Reference: Replaced and Removed Command Names'[114X) and try to
              get rid of their usage.[133X
  
