% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}

\usepackage{a4wide}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}

\definecolor{linkColor}{rgb}{0.0,0.0,0.554}
\definecolor{citeColor}{rgb}{0.0,0.0,0.554}
\definecolor{fileColor}{rgb}{0.0,0.0,0.554}
\definecolor{urlColor}{rgb}{0.0,0.0,0.554}
\definecolor{promptColor}{rgb}{0.0,0.0,0.589}
\definecolor{brkpromptColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapinputColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapoutputColor}{rgb}{0.0,0.0,0.0}

%%  for a long time these were red and blue by default,
%%  now black, but keep variables to overwrite
\definecolor{FuncColor}{rgb}{0.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,0.0}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}


\usepackage{fancyvrb}

\usepackage{mathptmx,helvet}
\usepackage[T1]{fontenc}
\usepackage{textcomp}


\usepackage[
            pdftex=true,
            bookmarks=true,        
            a4paper=true,
            pdftitle={Written with GAPDoc},
            pdfcreator={LaTeX with hyperref package / GAPDoc},
            colorlinks=true,
            backref=page,
            breaklinks=true,
            linkcolor=linkColor,
            citecolor=citeColor,
            filecolor=fileColor,
            urlcolor=urlColor,
            pdfpagemode={UseNone}, 
           ]{hyperref}

\newcommand{\maintitlesize}{\fontsize{50}{55}\selectfont}

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
%% were never documented, give conflicts with some additional packages

\newcommand{\GAP}{\textsf{GAP}}

%% nicer description environments, allows long labels
\usepackage{enumitem}
\setdescription{style=nextline}

%% depth of toc
\setcounter{tocdepth}{1}





%% command for ColorPrompt style examples
\newcommand{\gapprompt}[1]{\color{promptColor}{\bfseries #1}}
\newcommand{\gapbrkprompt}[1]{\color{brkpromptColor}{\bfseries #1}}
\newcommand{\gapinput}[1]{\color{gapinputColor}{#1}}


\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\mbox{}\vfill

\begin{center}{\maintitlesize \textbf{\textsf{Example}\mbox{}}}\\
\vfill

\hypersetup{pdftitle=\textsf{Example}}
\markright{\scriptsize \mbox{}\hfill \textsf{Example} \hfill\mbox{}}
{\Huge \textbf{Example/Template of a \textsf{GAP} Package and Guidelines for Package Authors\mbox{}}}\\
\vfill

{\Huge Version 3.4.5\mbox{}}\\[1cm]
{28 October 2014\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{ Werner Nickel   \mbox{}}}\\
{\Large \textbf{ Greg Gamble   \mbox{}}}\\
{\Large \textbf{ Alexander Konovalov   \mbox{}}}\\
\hypersetup{pdfauthor= Werner Nickel   ;  Greg Gamble   ;  Alexander Konovalov   }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Werner Nickel   }  Email: \href{mailto://nickel@mathematik.tu-darmstadt.de} {\texttt{nickel@mathematik.tu-darmstadt.de}}\\
  Homepage: \href{http://www.mathematik.tu-darmstadt.de/~nickel} {\texttt{http://www.mathematik.tu-darmstadt.de/\texttt{\symbol{126}}nickel}}}\\
{\mbox{}\\
\small \noindent \textbf{ Greg Gamble   }  Email: \href{mailto://gregg@math.rwth-aachen.de} {\texttt{gregg@math.rwth-aachen.de}}\\
  Homepage: \href{http://www.math.rwth-aachen.de/~Greg.Gamble} {\texttt{http://www.math.rwth-aachen.de/\texttt{\symbol{126}}Greg.Gamble}}}\\
{\mbox{}\\
\small \noindent \textbf{ Alexander Konovalov   }  Email: \href{mailto://alexk@mcs.st-andrews.ac.uk} {\texttt{alexk@mcs.st-andrews.ac.uk}}\\
  Homepage: \href{http://www.cs.st-andrews.ac.uk/~alexk/} {\texttt{http://www.cs.st-andrews.ac.uk/\texttt{\symbol{126}}alexk/}}}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
 \index{License} {\copyright} 1997-2012 by Werner Nickel, Greg Gamble and Alexander Konovalov

 \textsf{Example} package is free software; you can redistribute it and/or modify it under the
terms of the \href{http://www.fsf.org/licenses/gpl.html} {GNU General Public License} as published by the Free Software Foundation; either version 2 of the License,
or (at your option) any later version. \mbox{}}\\[1cm]
{\small 
\section*{Acknowledgements}
\logpage{[ 0, 0, 2 ]}
 We appreciate very much all past and future comments, suggestions and
contributions to this package and its documentation provided by \textsf{GAP} users and developers. \mbox{}}\\[1cm]
\newpage

\def\contentsname{Contents\logpage{[ 0, 0, 3 ]}}

\tableofcontents
\newpage

      
\chapter{\textcolor{Chapter }{The Example Package}}\label{The Example Package}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X8656021F83A3BD80}{}
{
  \index{Example package} This chapter describes the \textsf{GAP} package \textsf{Example}. As its name suggests it is an example of how to create a \textsf{GAP} package. It has little functionality except for being a package. 

 See Sections{\nobreakspace}\ref{Unpacking the Example Package}, \ref{Compiling Binaries of the Example Package} and{\nobreakspace}\ref{Loading the Example Package} for how to install, compile and load the \textsf{Example} package, or Appendix{\nobreakspace}\ref{Guidelines for Writing a GAP Package} for guidelines on how to write a \textsf{GAP} package. 

 If you are viewing this with on-line help, type: 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@?Example package|
\end{Verbatim}
 

 to see the functions provided by the \textsf{Example} package.  
\section{\textcolor{Chapter }{The Main Functions}}\label{The Main Functions}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X7D3DC4ED855DC13C}{}
{
  The following functions are available: 

\subsection{\textcolor{Chapter }{ListDirectory}}
\logpage{[ 1, 1, 1 ]}\nobreak
\hyperdef{L}{X791F84D17C64D56A}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{ListDirectory({\mdseries\slshape [dir]})\index{ListDirectory@\texttt{ListDirectory}}
\label{ListDirectory}
}\hfill{\scriptsize (function)}}\\


 lists the files in directory \mbox{\texttt{\mdseries\slshape dir}} (a string) or the current directory if called with no arguments. }

 

\subsection{\textcolor{Chapter }{FindFile}}
\logpage{[ 1, 1, 2 ]}\nobreak
\hyperdef{L}{X841462157B10C113}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{FindFile({\mdseries\slshape directory{\textunderscore}name, file{\textunderscore}name})\index{FindFile@\texttt{FindFile}}
\label{FindFile}
}\hfill{\scriptsize (function)}}\\


 searches for the file \mbox{\texttt{\mdseries\slshape file{\textunderscore}name}} in the directory tree rooted at \mbox{\texttt{\mdseries\slshape directory{\textunderscore}name}} and returns the absolute path names of all occurrences of this file as a list
of strings. }

 

\subsection{\textcolor{Chapter }{LoadedPackages}}
\logpage{[ 1, 1, 3 ]}\nobreak
\hyperdef{L}{X7856BE147FCE91AC}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{LoadedPackages({\mdseries\slshape })\index{LoadedPackages@\texttt{LoadedPackages}}
\label{LoadedPackages}
}\hfill{\scriptsize (function)}}\\


 returns a list with the names of the packages that have been loaded so far.
All this does is execute 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@RecNames( GAPInfo.PackagesLoaded );|
\end{Verbatim}
 }

 You might like to check out some of the other information in the \texttt{GAPInfo} record (see  (\textbf{Reference: GAPInfo})). 

\subsection{\textcolor{Chapter }{Which}}
\logpage{[ 1, 1, 4 ]}\nobreak
\hyperdef{L}{X7838D0477D8C0571}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{Which({\mdseries\slshape prg})\index{Which@\texttt{Which}}
\label{Which}
}\hfill{\scriptsize (function)}}\\


 returns the path of the program executed if \texttt{Exec(\mbox{\texttt{\mdseries\slshape prg}});} is called, e.g. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@Which("date");         |
  "/bin/date"
  !gapprompt@gap>| !gapinput@Exec("date");|
  Fri 28 Jan 2011 16:22:53 GMT
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{WhereIsPkgProgram}}
\logpage{[ 1, 1, 5 ]}\nobreak
\hyperdef{L}{X79090A0F87898612}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{WhereIsPkgProgram({\mdseries\slshape prg})\index{WhereIsPkgProgram@\texttt{WhereIsPkgProgram}}
\label{WhereIsPkgProgram}
}\hfill{\scriptsize (function)}}\\


 returns a list of paths of programs with name \mbox{\texttt{\mdseries\slshape prg}} in the current packages loaded. Try: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@WhereIsPkgProgram( "hello" );|
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{HelloWorld}}
\logpage{[ 1, 1, 6 ]}\nobreak
\hyperdef{L}{X80F716527825B803}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{HelloWorld({\mdseries\slshape })\index{HelloWorld@\texttt{HelloWorld}}
\label{HelloWorld}
}\hfill{\scriptsize (function)}}\\


 executes the C program \texttt{hello} provided by the \textsf{Example} package. }

 

\subsection{\textcolor{Chapter }{FruitCake}}
\logpage{[ 1, 1, 7 ]}\nobreak
\hyperdef{L}{X84DA2EEC8534A70D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{FruitCake\index{FruitCake@\texttt{FruitCake}}
\label{FruitCake}
}\hfill{\scriptsize (global variable)}}\\


 is a record with the bits and pieces needed to make a boiled fruit cake. Its
fields satisfy the criteria for \texttt{Recipe} (\ref{Recipe}). }

 

\subsection{\textcolor{Chapter }{Recipe}}
\logpage{[ 1, 1, 8 ]}\nobreak
\hyperdef{L}{X85B83BDB83B1C910}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{Recipe({\mdseries\slshape cake})\index{Recipe@\texttt{Recipe}}
\label{Recipe}
}\hfill{\scriptsize (operation)}}\\


 displays the recipe for cooking \mbox{\texttt{\mdseries\slshape cake}}, where \mbox{\texttt{\mdseries\slshape cake}} is a record satisfying certain criteria explained here: its recognised fields
are \texttt{name} (a string giving the type of cake or cooked item), \texttt{ovenTemp} (a string), \texttt{cookingTime} (a string), \texttt{ingredients} (a list of strings each containing an \texttt{{\textunderscore}} which is used to line up the entries and is replaced by a blank), \texttt{method} (a list of steps, each of which is a string or list of strings), and \texttt{notes} (a list of strings). The global variable \texttt{FruitCake} (\ref{FruitCake}) provides an example of such a string. }

 }

 }

        
\chapter{\textcolor{Chapter }{Installing and Loading the Example Package}}\label{Installing and Loading the Example Package}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X83473D1A871AB899}{}
{
   
\section{\textcolor{Chapter }{Unpacking the Example Package}}\label{Unpacking the Example Package}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X7A671E2078C9770B}{}
{
  If the \textsf{Example} package was obtained as a part of the \textsf{GAP} distribution from the ``Download'' section of the \textsf{GAP} website, you may proceed to Section \ref{Compiling Binaries of the Example Package}. Alternatively, the \textsf{Example} package may be installed using a separate archive, for example, for an update
or an installation in a non-default location (see  (\textbf{Reference: GAP Root Directories})). 

 Below we describe the installation procedure for the \texttt{.tar.gz} archive format. Installation using other archive formats is performed in a
similar way. 

 To install the \textsf{Example} package, unpack the archive file, which should have a name of form \texttt{example-\mbox{\texttt{\mdseries\slshape XXX}}.tar.gz} for some version number \mbox{\texttt{\mdseries\slshape XXX}}, by typing 

 {\nobreakspace}{\nobreakspace}\texttt{gzip -dc example-\mbox{\texttt{\mdseries\slshape XXX}}.tar.gz | tar xpv} 

 It may be unpacked in one of the following locations: 
\begin{itemize}
\item  in the \texttt{pkg} directory of your \textsf{GAP}{\nobreakspace}4 installation; 
\item  or in a directory named \texttt{.gap/pkg} in your home directory (to be added to the \textsf{GAP} root directory unless \textsf{GAP} is started with \texttt{-r} option); 
\item  or in a directory named \texttt{pkg} in another directory of your choice (e.g.{\nobreakspace}in the directory \texttt{mygap} in your home directory). 
\end{itemize}
 In the latter case one one must start \textsf{GAP} with the \texttt{-l} option, e.g.{\nobreakspace}if your private \texttt{pkg} directory is a subdirectory of \texttt{mygap} in your home directory you might type: 

 {\nobreakspace}{\nobreakspace}\texttt{gap -l ";\mbox{\texttt{\mdseries\slshape myhomedir}}/mygap"} 

 where \mbox{\texttt{\mdseries\slshape myhomedir}} is the path to your home directory, which (since \textsf{GAP}{\nobreakspace}4.3) may be replaced by a tilde (the empty path before the
semicolon is filled in by the default path of the \textsf{GAP}{\nobreakspace}4 home directory). }

  
\section{\textcolor{Chapter }{Compiling Binaries of the Example Package}}\label{Compiling Binaries of the Example Package}
\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X79E203C779518B3D}{}
{
  After unpacking the archive, go to the newly created \texttt{example} directory and call \texttt{./configure} to use the default \texttt{../..} path to the \textsf{GAP} home directory or \texttt{./configure \mbox{\texttt{\mdseries\slshape path}}} where \mbox{\texttt{\mdseries\slshape path}} is the path to the \textsf{GAP} home directory, if the package is being installed in a non-default location.
So for example if you install the package in the \texttt{\texttt{\symbol{126}}/.gap/pkg} directory and the \textsf{GAP} home directory is \texttt{\texttt{\symbol{126}}/gap4r5} then you have to call 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  ./configure ../../../gap4r5/
\end{Verbatim}
 

 This will fetch the architecture type for which \textsf{GAP} has been compiled last and create a \texttt{Makefile}. Now simply call 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  make
\end{Verbatim}
 

 to compile the binary and to install it in the appropriate place. }

  
\section{\textcolor{Chapter }{Loading the Example Package}}\label{Loading the Example Package}
\logpage{[ 2, 3, 0 ]}
\hyperdef{L}{X7A242BA97D904EDF}{}
{
  To use the \textsf{Example} Package you have to request it explicitly. This is done by calling \texttt{LoadPackage} (\textbf{Reference: LoadPackage}): 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@LoadPackage("example");|
  ----------------------------------------------------------------
  Loading  Example 3.3 (Example/Template of a GAP Package)
  by Werner Nickel (http://www.mathematik.tu-darmstadt.de/~nickel),
     Greg Gamble (http://www.math.rwth-aachen.de/~Greg.Gamble), and
     Alexander Konovalov (http://www.cs.st-andrews.ac.uk/~alexk/).
  ----------------------------------------------------------------
  true
\end{Verbatim}
 

 If \textsf{GAP} cannot find a working binary, the call to \texttt{LoadPackage} will still succeed but a warning is issued informing that the \texttt{HelloWorld()} function will be unavailable. 

 If you want to load the \textsf{Example} package by default, you can put the \texttt{LoadPackage} command into your \texttt{gaprc} file (see Section{\nobreakspace} (\textbf{Reference: The gap.ini and gaprc files})). }

 }

    

\appendix


\chapter{\textcolor{Chapter }{Guidelines for Writing a GAP Package}}\label{Guidelines for Writing a GAP Package}
\logpage{[ "A", 0, 0 ]}
\hyperdef{L}{X7EE8E5D97B0F8AFF}{}
{
  This appendix explains the basics of how to write a \textsf{GAP} package so that it interfaces properly to \textsf{GAP}. For the role of \textsf{GAP} packages and the ways to load them, see Chapter{\nobreakspace} (\textbf{Reference: Using GAP Packages}). 

 There are two basic aspects of creating a \textsf{GAP} package. 

 First, it is a convenient possibility to load additional functionality into \textsf{GAP} including a smooth integration of the package documentation. Second, a package
is a way to make your code available to other \textsf{GAP} users. 

 Moreover, the \textsf{GAP} 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 \textsf{GAP} distribution update mechanism and becomes a \emph{deposited} package. 

 Furthermore, package authors are encouraged to check if the package would be
appropriate for the refereeing process and \emph{submit} it. If the refereeing has been successful, the package becomes an \emph{accepted} package. Check out the \textsf{GAP} Web site \href{http://www.gap-system.org} {\texttt{http://www.gap-system.org}} for more details. 

 We start this chapter with a description how the directory structure of a \textsf{GAP} package should be constructed and then add remarks on certain aspects of
creating a package, some of these only apply to some packages. Finally, we
provide guidelines for the release preparation, wrapping and distribution. 

   
\section{\textcolor{Chapter }{Structure of a GAP Package}}\label{Structure of a GAP Package}
\logpage{[ "A", 1, 0 ]}
\hyperdef{L}{X8383876782480702}{}
{
  \index{home directory!for a GAP package} A \textsf{GAP} package should have an alphanumeric name (\mbox{\texttt{\mdseries\slshape package-name}}, say); mixed case is fine, but there should be no whitespaces. All files of a \textsf{GAP} package \mbox{\texttt{\mdseries\slshape package-name}} must be collected in a single directory \mbox{\texttt{\mdseries\slshape package-dir}}, where \mbox{\texttt{\mdseries\slshape package-dir}} should be just \mbox{\texttt{\mdseries\slshape package-name}} preferably converted to lowercase and optionally followed by the package
version (with or without hyphen to separate the version from \mbox{\texttt{\mdseries\slshape package-name}}). Let us call this directory the \emph{home directory} of the package. 

 To use the package with \textsf{GAP}, the directory \mbox{\texttt{\mdseries\slshape package-dir}} must be a subdirectory of a \texttt{pkg} directory in (one of) the \textsf{GAP} root directories (see  (\textbf{Reference: GAP Root Directories})). For example, if \textsf{GAP} is installed in \texttt{/usr/local/gap4} then the files of the package \texttt{MyPack} may be placed in the directory \texttt{/usr/local/gap4/pkg/mypack}. The directory \mbox{\texttt{\mdseries\slshape package-dir}} preferably should have the following structure (below, a trailing \texttt{/} distinguishes directories from ordinary files): 

 \newpage 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  package-dir/
    doc/
    lib/
    src/
    tst/
    README
    CHANGES
    configure
    Makefile.in
    PackageInfo.g
    init.g
    read.g
\end{Verbatim}
 

 There are three file names with a special meaning in the home directory of a
package: \texttt{PackageInfo.g} and \texttt{init.g} which must be present, and \texttt{read.g} which is optional. We now describe the above files and directories: 

 
\begin{description}
\item[{ \texttt{README}}]  \index{README@\texttt{README}!for a GAP package} This should contain ``how to get it'' (from the \textsf{GAP} \texttt{ftp}- and web-sites) instructions, as well as installation instructions and names
of the package authors and their email addresses. The installation
instructions should be repeated in the package's documentation, which should
be in the \texttt{doc} directory (see \ref{Writing Documentation and Tools Needed}). Authors' names and addresses should be repeated both in the package's
documentation and in the \texttt{PackageInfo.g} (see below). 
\item[{ \texttt{CHANGES}}]  For further versions of the package, it will be also useful to have a \texttt{CHANGES} file that records the main changes between versions of the package. 
\item[{\texttt{configure}, \texttt{Makefile.in}}]  These files are only necessary if the package has a non-\textsf{GAP} component, e.g.{\nobreakspace}some C code (the files of which should be in the \texttt{src} directory). The \texttt{configure} and \texttt{Makefile.in} files of the \textsf{Example} package provide prototypes. The \texttt{configure} file typically takes a path \mbox{\texttt{\mdseries\slshape path}} to the \textsf{GAP} root directory as argument and uses the value assigned to \texttt{GAParch} in the file \texttt{sysinfo.gap}, created when \textsf{GAP} was compiled to determine the compilation architecture, inserts this in place
of the string \texttt{@GAPARCH@} in \texttt{Makefile.in} and creates a file \texttt{Makefile}. When \texttt{make} is run (which, of course, reads the constructed \texttt{Makefile}), a directory \texttt{bin} (if necessary) and subdirectories of \texttt{bin} with the path equal to the string assigned to \texttt{GAParch} in the file \texttt{sysinfo.gap} should be created; any binaries constructed by compiling the code in \texttt{src} should end up in this subdirectory of \texttt{bin}. 
\item[{\texttt{PackageInfo.g}}]  \index{PackageInfo.g@\texttt{PackageInfo.g}!for a GAP package} Since \textsf{GAP}{\nobreakspace}4.4, a \textsf{GAP} package \emph{must} have a \texttt{PackageInfo.g} file which contains meta-information about the package (package name, version,
author(s), relations to other packages, homepage, download archives, banner,
...). This information is used by the package loading mechanism and also for
the distribution of a package to other users. The \textsf{Example} package's \texttt{PackageInfo.g} file is well-commented and should be used as a prototype (see also \ref{The PackageInfo.g File} for further details). 
\item[{\texttt{init.g}, \texttt{read.g}}]  \index{init.g@\texttt{init.g}!for a GAP package} \index{read.g@\texttt{read.g}!for a GAP package} A \textsf{GAP} package \emph{must} have a file \texttt{init.g}. As of \textsf{GAP}{\nobreakspace}4.4, the typical \texttt{init.g} and \texttt{read.g} files should normally consist entirely of \texttt{ReadPackage} (\textbf{Reference: ReadPackage}) commands (and possibly also \texttt{Read} (\textbf{Reference: Read}) commands) for reading further files of the package. If the ``declaration'' and ``implementation'' parts of the package are separated (and this is recommended), there should be
a \texttt{read.g} file. The ``declaration'' part of a package consists of function and variable \emph{name} declarations and these go in files with \texttt{.gd} extensions; these files are read in via \texttt{ReadPackage} commands in the \texttt{init.g} file. The ``implementation'' part of a package consists of the actual definitions of the functions and
variables whose names were declared in the ``declaration'' part, and these go in files with \texttt{.gi} extensions; these files are read in via \texttt{ReadPackage} commands in the \texttt{read.g} file. The reason for following the above dichotomy is that the \texttt{read.g} file is read \emph{after} the \texttt{init.g} 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 \ref{Declaration and Implementation Part of a Package} below for more details). 

 The \textsf{GAP} code (whether or not it is split into ``declaration'' and ``implementation'' parts) should go in the package's \texttt{lib} directory (see below). 
\item[{\texttt{doc}}]  \index{GAPDoc@GAPDoc format!for writing package documentation} \index{gapmacro.tex@\texttt{gapmacro.tex} format!for writing package documentation} This directory should contain the package's documentation. It is strongly
recommended to use an XML-based documentation format supported by the \textsf{GAP} package \textsf{GAPDoc} (see  (\textbf{GAPDoc: Introduction and Example})) which is used for the \textsf{GAP} documentation. An alternative is to use the {\TeX}-based system, formerly used for the \textsf{GAP} documentation in \textsf{GAP}{\nobreakspace}4.4 and earlier releases. This system is described in the
document ``The gapmacro.tex Manual Format'' (the file \texttt{gap4r5/doc/gapmacrodoc.pdf} included in the tools archive as described in Section \ref{Writing Documentation and Tools Needed}) and is still used by some of the \textsf{GAP} packages whose authors are encouraged to switch at some point to the \textsf{GAPDoc}-based documenation. Please spend some time reading the documentation for
whichever system you decide to use for writing your package's documentation.
The \textsf{Example} package's documentation is written in the XML format supported by the \textsf{GAPDoc} package. If you intend to use this format, please use the \textsf{Example} package's \texttt{doc} directory as a prototype, which as you will observe contains the master file \texttt{main.xml}, further \texttt{.xml} files for manual chapters (included in the manual via \texttt{Include} directives in the master file) and the \textsf{GAP} input file \texttt{../makedocrel.g} which generates the manuals. Generally, one should also provide a \texttt{manual.bib} Bib{\TeX} database file or an \texttt{xml} file in the BibXMLext format (see  (\textbf{GAPDoc: The BibXMLext Format})). With \texttt{gapmacro.tex}, it is also possible to use a \texttt{manual.bbl} file.  
\item[{\texttt{lib}}]  This is the preferred place for the \textsf{GAP} code, i.e.{\nobreakspace}the \texttt{.g}, \texttt{.gd} and \texttt{.gi} files (other than \texttt{PackageInfo.g}, \texttt{init.g} and \texttt{read.g}). For some packages, the directory \texttt{gap} has been used instead of \texttt{lib}; \texttt{lib} has the slight advantage that it is the default subdirectory of a package
directory searched for by the \texttt{DirectoriesPackageLibrary} (\textbf{Reference: DirectoriesPackageLibrary}) command. 
\item[{\texttt{src}}]  If the package has non-\textsf{GAP} code, e.g.{\nobreakspace}C code, then this ``source'' code should go in the \texttt{src} directory. If there are \texttt{.h} ``include'' files you may prefer to put these all together in a separate \texttt{include} directory. There is one further rule for the location of kernel library
modules or external programs which is explained in \ref{Installation of GAP Package Binaries} below. 
\item[{\texttt{tst}}]  If the package has test files, then they should go in the \texttt{tst} directory. For a deposited package, a test file with a basic test of the
package (for example, to check that it works as expected and/or that the
manual examples are correct) may be specified in the \texttt{PackageInfo.g} to be included in the \textsf{GAP} standard test suite. More specific and time consuming tests are not supposed
to be a part of the \textsf{GAP} standard test suite but may be placed in the \texttt{tst} directory with further instructions on how to run them. See Section \ref{Testing a GAP package} about the requirements to the test files formats and further recommendations. 
\end{description}
 All 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 \texttt{examples} subdirectory, data libraries in extra subdirectories, and so on. 

 Sometimes 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 \texttt{README} file describing its purpose to ensure that such directory will be included in
the redistribution. 

 Concerning the \textsf{GAP} code in packages, it is recommended to use only documented \textsf{GAP} functions, see  (\textbf{Reference: Undocumented Variables}). In particular if you want to make your package available to other \textsf{GAP} users it is advisable to avoid using ``obsolescent'' variables (see  (\textbf{Reference: Replaced and Removed Command Names})). For that, you can set the \texttt{ReadObsolete} component in your \texttt{gap.ini} file to \texttt{false}, see  (\textbf{Reference: The gap.ini and gaprc files}). }

  
\section{\textcolor{Chapter }{Writing Documentation and Tools Needed}}\label{Writing Documentation and Tools Needed}
\logpage{[ "A", 2, 0 ]}
\hyperdef{L}{X84164AA2859A195F}{}
{
  If you intend to make your package available to other users it is essential to
include documentation explaining how to install and use your programs. 

 Concerning the installation you should produce a file \texttt{README} which gives a short description of the purpose of the package and contains
proper instructions how to install your package. Again, check out some
existing packages to get an idea how this could look like. 

 Concerning the documentation of the use of the package there are currently two
recognised ways of producing \textsf{GAP} package documentation. 

 First, there is a recommended XML-based documentation format that is defined
in and can be used with the \textsf{GAPDoc} package (see{\nobreakspace} (\textbf{GAPDoc: Introduction and Example})). 

 Second, there is a method which requires the documentation to be written in {\TeX} according to the format described in the document ``The gapmacro.tex Manual Format''. 

 In principle it is also possible to use some completely different
documentation format. In that case you need to study the
Chapter{\nobreakspace} (\textbf{Reference: Interface to the GAP Help System}) to learn how to make your documentation available to the \textsf{GAP} help system. There should be at least a text version of your documenation
provided for use in the terminal running \textsf{GAP} and some nicely printable version in \texttt{.pdf} format. Many \textsf{GAP} users like to browse the documentation in HTML format via their Web browser.
As a package author, you are not obliged to provide an HTML version of your
package manual, but if you will either use the \textsf{GAPDoc} package or follow the guidelines in the document ``The gapmacro.tex Manual Format'', (the file \texttt{gap4r5/doc/gapmacrodoc.pdf} included in the tools archive as described in this Section below), you should
have no trouble in producing one. Moreover, using the \textsf{GAPDoc} package, it is also possible to produce HTML version of the documentation
supporting MathJax (\href{http://www.mathjax.org/} {\texttt{http://www.mathjax.org/}}) 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: 
\[ [ \chi, \psi ] = \left( \sum_{{g \in G}} \chi(g) \psi(g^{{-1}}) \right) / |G|. \]
 

 The manual of the \textsf{Example} package is written in the \textsf{GAPDoc} format, and commands needed to build it are contained in the file \texttt{makedocrel.g} (you don't need to re-build the manual since it is already included in the
package). 

 Whenever you use the \textsf{GAPDoc} or \texttt{gapmacro.tex} {\TeX}-based system, you need to have certain {\TeX} tools installed: to produce manuals in the \texttt{.pdf} format, you need \texttt{pdflatex} if the \textsf{GAPDoc} is used, and either \texttt{pdftex} or \texttt{gs} together with \texttt{ps2pdf} if your package uses \texttt{gapmacro.tex}. Note that using \texttt{gs} and \texttt{ps2pdf} in lieu of \texttt{pdftex} or \texttt{pdflatex} is a poor substitute unless your \texttt{gs} is at least version 6.\mbox{\texttt{\mdseries\slshape xx}} for some \mbox{\texttt{\mdseries\slshape xx}}. In addition, the \texttt{gapmacro.tex} documentation system requires some more tools described below. If you intend
to use the \textsf{GAPDoc} package for the documenation of your package, you may skip the rest of this
section and proceed to the next one to see a minimalistic example of a \textsf{GAP} package. 

 \index{tools archive for package authors} Otherwise, to produce the \texttt{.pdf} manual formats, the following \textsf{GAP} tools (supplied as a part of the \textsf{GAP} distribution in the archive \texttt{tools.tar.gz} in the in \textsf{GAP}'s \texttt{etc} directory and installed using the script \texttt{install-tools.sh} in the same directory) are needed: \texttt{gapmacro.tex} (the macros file that dictates the style and mark-up for the traditional {\TeX}-based system of \textsf{GAP} documentation), \texttt{manualindex} (an \texttt{awk} script that adjusts the {\TeX}-produced index entries and calls \texttt{makeindex} to process them), and \texttt{mrabbrev.bib} (usually supplied with your {\TeX} tools but nevertheless a copy of \texttt{mrabbrev.bib} should be located in \textsf{GAP}'s main \texttt{doc} directory. To find it on your system, try: \texttt{kpsewhich mrabbrev.bib} or, if that doesn't work and you can't otherwise find it check out a CTAN
site, e.g.{\nobreakspace}search for it at: \href{http://www.dante.de/cgi-bin/ctan-index} {\texttt{http://www.dante.de/cgi-bin/ctan-index}}. 

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

 {\nobreakspace}{\nobreakspace}\texttt{gap{\textgreater} GapDocManualLab( "\mbox{\texttt{\mdseries\slshape package}}" );} 

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

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

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

 }

  
\section{\textcolor{Chapter }{An Example of a GAP Package}}\label{An Example of a GAP Package}
\logpage{[ "A", 3, 0 ]}
\hyperdef{L}{X79AB306684AC8E7A}{}
{
  We illustrate the creation of a \textsf{GAP} package by an example of a basic package. 

 Create the following directories in your home area: \texttt{.gap}, \texttt{.gap/pkg} and \texttt{.gap/pkg/test}. Then inside the directory \texttt{.gap/pkg/test} create an empty file \texttt{init.g}, and a file \texttt{PackageInfo.g} with the following contents: 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  SetPackageInfo( rec(
    PackageName := "test",
    Version := "1.0",
    PackageDoc := rec(
        BookName  := "test",
        SixFile   := "doc/manual.six",
        Autoload  := true ),
    Dependencies := rec(
        GAP       := "4.5",
        NeededOtherPackages := [ ["GAPDoc", "1.3"] ],
        SuggestedOtherPackages := [ ] ),
    AvailabilityTest := ReturnTrue ) );
\end{Verbatim}
 

 This file declares the \textsf{GAP} package with name ``test'' in version 1.0. The package documentation consists of one autoloaded book; the \texttt{SixFile} component is needed by the \textsf{GAP} help system. Package dependencies require at least \textsf{GAP}{\nobreakspace}4.5 and \textsf{GAPDoc} package at version at least 1.3, and these conditions will be checked when the
package will be loaded (see \ref{Version Numbers}). Since there are no requirements that have to be tested, \texttt{AvailabilityTest} just uses \texttt{ReturnTrue} (\textbf{Reference: ReturnTrue}). 

 Now start \textsf{GAP} (without using the \texttt{-r} option) and the \texttt{.gap} directory will be added to the \textsf{GAP} root directory to allow \textsf{GAP} to find the packages installed there (see  (\textbf{Reference: GAP Root Directories})). 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@LoadPackage("test");|
  true
\end{Verbatim}
 

 This \textsf{GAP} package is too simple to be useful, but we have succeeded in loading it via \texttt{LoadPackage} (\textbf{Reference: LoadPackage}), satisfying all specified dependencies. }

  
\section{\textcolor{Chapter }{File Structure}}\label{File Structure}
\logpage{[ "A", 4, 0 ]}
\hyperdef{L}{X7A61B1AE7D632E01}{}
{
  Package files may follow the style used for the \textsf{GAP} library. Every file in the \textsf{GAP} 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 \texttt{\#E}. 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. 

 Historically, when the \textsf{GAP} main manuals were based on the {\TeX} macros described in the document ``The gapmacro.tex Manual Format'' (the file \texttt{gap4r5/doc/gapmacrodoc.pdf} included in the tools archive as described in Section \ref{Writing Documentation and Tools Needed}) such headers were used for the manuals and have the type 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  #############################################################################
  ##
  #X  ExampleFunction(<A>,<B>)
  ##
  ##  This function does great things.
\end{Verbatim}
 

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

 Nowadays, 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 \textsf{GAPDoc} package (see  (\textbf{GAPDoc: Distributing a Document into Several Files})). The same approach is demonstrated by the \textsf{Example} package. E.g. \texttt{example/doc/example.xml} has the statement \texttt{{\textless}\#Include Label="ListDirectory"{\textgreater}} and \texttt{example/lib/files.gd} contains 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  #############################################################################
  ##
  #F  ListDirectory([<dir>])  . . . . . . . . . . list the files in a directory
  ##
  ##  <#GAPDoc Label="ListDirectory">
  ##  <ManSection>
  ##  <Func Name="ListDirectory" Arg="[dir]"/>
  ##
  ##  <Description>
  ##  lists the files in directory <A>dir</A> (a string) 
  ##  or the current directory if called with no arguments.
  ##  </Description>
  ##  </ManSection>
  ##  <#/GAPDoc>
  DeclareGlobalFunction( "ListDirectory" );
\end{Verbatim}
 This is all put together in the file \texttt{example/makedocrel.g} which builds the package documentation, calling \texttt{MakeGAPDocDoc} (\textbf{GAPDoc: MakeGAPDocDoc}) with locations of library files containing parts of the documentation. }

  
\section{\textcolor{Chapter }{The PackageInfo.g File}}\label{The PackageInfo.g File}
\logpage{[ "A", 5, 0 ]}
\hyperdef{L}{X85C8DE357EE424D8}{}
{
  \index{ValidatePackageInfo@\texttt{ValidatePackageInfo}} As a first step the example in \ref{An Example of a GAP Package} 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 \texttt{Dependencies} given in the \texttt{PackageInfo.g} file becomes important (see \ref{Package dependencies} 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. 

 We suggest to create a \texttt{PackageInfo.g} file for your package by copying the one in the \textsf{Example} package, distributed with \textsf{GAP}, and then adjusting it for your package. Within \textsf{GAP} you can look at this template file for a list and explanation of all
recognized entries by 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  Pager(StringFile(Filename(DirectoriesLibrary(), 
                            "../pkg/example/PackageInfo.g")));
\end{Verbatim}
 

 Once you have created the \texttt{PackageInfo.g} file for your package, you can test its validity with the function \texttt{ValidatePackageInfo} (\textbf{Reference: ValidatePackageInfo}). }

  
\section{\textcolor{Chapter }{Functions and Variables and Choices of Their Names}}\label{Functions and Variables and Choices of Their Names}
\logpage{[ "A", 6, 0 ]}
\hyperdef{L}{X7DEACD9786DE29F1}{}
{
  In writing the \textsf{GAP} code for your package you need to be a little careful on just how you define
your functions and variables. 

 \emph{Firstly}, in general one should avoid defining functions and variables via assignment
statements in the way you would interactively, e.g. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@Squared := x -> x^2;;|
  !gapprompt@gap>| !gapinput@Cubed := function(x) return x^3; end;;|
\end{Verbatim}
 

 The reason for this is that such functions and variables are \emph{easily overwritten} and what's more you are not warned about it when it happens. 

 To protect a function or variable against overwriting there is the command \texttt{BindGlobal} (\textbf{Reference: BindGlobal}), or alternatively (and equivalently) you may define a global function via a \texttt{DeclareGlobalFunction} (\textbf{Reference: DeclareGlobalFunction}) and \texttt{InstallGlobalFunction} (\textbf{Reference: InstallGlobalFunction}) pair or a global variable via a \texttt{DeclareGlobalVariable} (\textbf{Reference: DeclareGlobalVariable}) and \texttt{InstallValue} (\textbf{Reference: InstallValue}) pair. There are also operations and their methods, and related objects like
attributes and filters which also have \texttt{Declare...} and \texttt{Install...} pairs. 

 \emph{Secondly}, it's a good idea to reduce the chance of accidental overwriting by choosing
names for your functions and variables that begin with a string that
identifies it with the package, e.g.{\nobreakspace}some of the undocumented
functions in the \textsf{Example} package begin with \texttt{Eg}. This is especially important in cases where you actually want the user to be
able to change the value of a function or variable defined by your package,
for which you have used direct assignments (for which the user will receive no
warning if she accidentally overwrites them). It's also important for
functions and variables defined via \texttt{BindGlobal}, \texttt{DeclareGlobalFunction}/\texttt{InstallGlobalFunction} and \texttt{DeclareGlobalVariable}/\texttt{InstallValue}, in order to avoid name clashes that may occur with (extensions of) the \textsf{GAP} library and other packages. 

 \index{local namespace!for a GAP package} Additionally, since \textsf{GAP}{\nobreakspace}4.5 a package may place global variables into a local namespace
as explained in  (\textbf{Reference: Namespaces for GAP packages}) 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 \texttt{@} symbol, e.g. \texttt{xYz@}. 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. \texttt{xYz@YourPackageName}. This helps to prevent clashes between different packages or between a
package and the \textsf{GAP} library because of the same variable names.  

 On the other hand, operations and their methods (defined via \texttt{DeclareOperation} (\textbf{Reference: DeclareOperation}), \texttt{InstallMethod} (\textbf{Reference: InstallMethod}) etc.{\nobreakspace}pairs) and their relatives do not need this consideration,
as they avoid name clashes by allowing for more than one ``method'' for the same-named object. 

 To demonstrate the definition of a function via a \texttt{DeclareOperation}/\texttt{InstallMethod} pair, the method \texttt{Recipe} (\ref{Recipe}) was included in the \textsf{Example} package; \texttt{Recipe( FruitCake );} gives a ``method'' for making a fruit cake (forgive the pun). 

 \emph{Thirdly}, functions or variables with \texttt{Set\mbox{\texttt{\mdseries\slshape XXX}}} or \texttt{Has\mbox{\texttt{\mdseries\slshape XXX}}} 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 \mbox{\texttt{\mdseries\slshape XXX}} declared via the \texttt{DeclareAttribute} and \texttt{DeclareProperty} commands have associated with them testers of form \texttt{Has\mbox{\texttt{\mdseries\slshape XXX}}} and setters of form \texttt{Set\mbox{\texttt{\mdseries\slshape XXX}}}). 

 \emph{Fourthly}, it is a good idea to have some convention for internal functions and
variables (i.e.{\nobreakspace}the functions and variables you don't intend for
the user to use). For example, they might be entirely CAPITALISED. 

 Additionally, there is a recommended naming convention that the \textsf{GAP} core system and \textsf{GAP} packages should not use global variables starting in the lowercase. This
allows to reserve variables with names starting in lowecase to the \textsf{GAP} user so they will never clash with the system. It is extremely important to
avoid using for package global variables very short names started in
lowercase. For example, such names like \texttt{cs}, \texttt{exp}, \texttt{ngens}, \texttt{pc}, \texttt{pow} 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, \texttt{C1} or \texttt{ORB}, since they also could be easily overwritten by the user. 

 It is a good practice to follow naming conventions used in \textsf{GAP} as explained in  (\textbf{Reference: Naming Conventions}) and  (\textbf{Tutorial: Changing the Structure}), which might help users to memorize or even guess names of functions provided
by the package. 

 \emph{Finally}, note the advantage of using \texttt{DeclareGlobalFunction}/\texttt{InstallGlobalFunction}, \texttt{DeclareGlobalVariable}/\texttt{InstallValue}, etc.{\nobreakspace}pairs (rather than \texttt{BindGlobal}) 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 \texttt{Declare...} statements should go in files with \texttt{.gd} extensions and be loaded by \texttt{ReadPackage} statements in the package \texttt{init.g} file, and the \texttt{Install...} definitions should go in files with \texttt{.gi} extensions and be loaded by \texttt{ReadPackage} statements in the package \texttt{read.g} file; this ensures that the \texttt{.gi} files are read \emph{after} the \texttt{.gd} files. All other package code should go in \texttt{.g} files (other than the \texttt{init.g} and \texttt{read.g} files themselves) and be loaded via \texttt{ReadPackage} statements in the \texttt{init.g} file. 

 \index{ShowPackageVariables@\texttt{ShowPackageVariables}} In conclusion, here is some practical advice on how to check which variables
are used by the package. 

 Firstly, there is a function \texttt{ShowPackageVariables} (\textbf{Reference: ShowPackageVariables}). If the package \mbox{\texttt{\mdseries\slshape pkgname}} is available but not yet loaded then \texttt{ShowPackageVariables( pkgname )} 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 \texttt{ShowPackageVariables} can be called only once for the same package in the same \textsf{GAP} session.) The second optional argument \mbox{\texttt{\mdseries\slshape version}} 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. 

 Info lines for undocumented variables will be marked with an asterisk \texttt{*}. Note that the \textsf{GAP} help system is case insensitive, so it is difficult to document identifiers
that differ only by case. 

 The following entries are omitted from the list: default setter methods for
attributes and properties that are declared in the package, and \texttt{Set\mbox{\texttt{\mdseries\slshape attr}}} and \texttt{Has\mbox{\texttt{\mdseries\slshape attr}}} type variables where \mbox{\texttt{\mdseries\slshape attr}} is an attribute or property. 

 For example, for this package it currently produces the following output: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@ShowPackageVariables("example");|
  ----------------------------------------------------------------
  Loading  Example 3.3 (Example/Template of a GAP Package)
  by Werner Nickel (http://www.mathematik.tu-darmstadt.de/~nickel),
     Greg Gamble (http://www.math.rwth-aachen.de/~Greg.Gamble), and
     Alexander Konovalov (http://www.cs.st-andrews.ac.uk/~alexk/).
  ----------------------------------------------------------------
  new global functions:
    EgSeparatedString( str, c )*
    FindFile( dir, file )
    HelloWorld(  )
    ListDirectory( arg )
    LoadedPackages(  )
    WhereIsPkgProgram( prg )
    Which( prg )
  
  new global variables:
    FruitCake
  
  new operations:
    Recipe( arg )
  
  new methods:
    Recipe( cake )
\end{Verbatim}
 Another trick is to start \textsf{GAP} with \texttt{-r -A} options, immediately load your package and then call \texttt{NamesUserGVars} (\textbf{Reference: NamesUserGVars}) 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 \textsf{Example} it produces 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@NamesUserGVars();|
  [ "EgSeparatedString", "FindFile", "FruitCake", "HelloWorld", "ListDirectory",
    "LoadedPackages", "Recipe", "WhereIsPkgProgram", "Which" ]
\end{Verbatim}
 but 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 ``phantom'' 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 already exists before the package is loaded so it will be silently
overwritten. }

  
\section{\textcolor{Chapter }{Package Dependencies (Requesting one \textsf{GAP} Package from within Another)}}\label{Package dependencies}
\logpage{[ "A", 7, 0 ]}
\hyperdef{L}{X7FB5FECD7C271688}{}
{
  \index{needed package} \index{suggested package} \index{dependencies!for a GAP package} It is possible for one \textsf{GAP} package \texttt{A}, say, to require another package \texttt{B}. For that, one simply adds the name and the (least) version number of the
package \texttt{B} to the \texttt{NeededOtherPackages} component of the \texttt{Dependencies} component of the \texttt{PackageInfo.g} file of the package \texttt{A}. In this situation, loading the package \texttt{A} forces that also the package \texttt{B} is loaded, and that \texttt{A} cannot be loaded if \texttt{B} is not available. 

 If \texttt{B} is not essential for \texttt{A} but should be loaded if it is available (for example because \texttt{B} provides some improvements of the main system that are useful for \texttt{A}) then the name and the (least) version number of \texttt{B} should be added to the \texttt{SuggestedOtherPackages} component of the \texttt{Dependencies} component of the \texttt{PackageInfo.g} file of \texttt{A}. In this situation, loading \texttt{A} forces an attempt to load also \texttt{B}, but \texttt{A} is loaded even if \texttt{B} is not available. 

 Also the component \texttt{Dependencies.OtherPackagesLoadedInAdvance} in \texttt{PackageInfo.g} is supported, which describes needed packages that shall be loaded before the
current package is loaded. See \ref{Declaration and Implementation Part of a Package} for details about this and more generally about the order in which the files
of the packages in question are read. 

 All package dependencies must be documented explicitly in the \texttt{PackageInfo.g} file. It is important to properly identify package dependencies and make the
right decision whether the other package should be ``needed'' or ``suggested''. For example, declaring package as ``needed'' when ``suggested'' might be sufficient may prevent loading of packages under Windows for no good
reason. 

 It is not appropriate to explicitly call \texttt{LoadPackage} (\textbf{Reference: LoadPackage}) \emph{when the package is loaded}, since this may distort the order of package loading and result in warning
messages. It is recommended to turn such dependencies into needed or suggested
packages. For example, a package can be designed in such a way 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 \emph{suggested}. Alternatively, if the package author decides that loading the package in
this situation makes no sense, then the missing component is \emph{needed}. 

 On the other hand, if \texttt{LoadPackage} (\textbf{Reference: LoadPackage}) 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 \texttt{LoadPackage} (\textbf{Reference: LoadPackage}). 

 \index{OnlyNeeded@\texttt{OnlyNeeded}!option} It may happen that a package B that is listed as a suggested package of
package A is actually needed by A. If no explicit \texttt{LoadPackage} (\textbf{Reference: LoadPackage}) 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 \texttt{OnlyNeeded} 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 \textsf{GAP} 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 \texttt{LoadPackage} (\textbf{Reference: LoadPackage}) for B at loading time (see above) then package B needs to be \emph{deinstalled} (i.e. removed) to test loading of A without B.  

 Finally, if the package manual is in the \textsf{GAPDoc} format, then \textsf{GAPDoc} should still be listed as \emph{needed} for this package (not as \emph{suggested}), even though \textsf{GAPDoc} is now a needed package for \textsf{GAP} itself. 

 }

  
\section{\textcolor{Chapter }{Declaration and Implementation Part of a Package}}\label{Declaration and Implementation Part of a Package}
\logpage{[ "A", 8, 0 ]}
\hyperdef{L}{X7A7835A5797AF766}{}
{
  When \textsf{GAP} packages require each other in a circular way, a ``bootstrapping'' problem arises of defining functions before they are called. The same problem
occurs in the \textsf{GAP} 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. \textsf{GAP} initially reads all declaration files (in the library they have a \texttt{.gd} suffix) and afterwards reads all implementation files (which have a \texttt{.gi} suffix). 

 Something similar is possible for \textsf{GAP} packages: if a file \texttt{read.g} exists in the home directory of the package, this file is read only \emph{after} all the \texttt{init.g} files of all (implicitly) required \textsf{GAP} packages are read. Thus one can separate declaration and implementation for a \textsf{GAP} package in the same way as is done for the \textsf{GAP} library, by creating a file \texttt{read.g}, restricting the \texttt{ReadPackage} (\textbf{Reference: ReadPackage}) statements in \texttt{init.g} to only read those files of the package that provide declarations, and to read
the implementation files from \texttt{read.g}. 

 \emph{Examples:} 

 Suppose that there are two packages \texttt{A} and \texttt{B}, each with files \texttt{init.g} and \texttt{read.g}. 

 
\begin{itemize}
\item  If package \texttt{A} suggests or needs package \texttt{B} and package \texttt{B} does not need or suggest any other package then first \texttt{init.g} of \texttt{B} is read, then \texttt{read.g} of \texttt{B}, then \texttt{init.g} of \texttt{A}, then \texttt{read.g} of \texttt{A}. 
\item  If package \texttt{A} suggests or needs package \texttt{B} and package \texttt{B} (or a package that is suggested or needed by \texttt{B}) suggests or needs package \texttt{A} then first the files \texttt{init.g} of \texttt{A} and \texttt{B} are read (in an unspecified order) and then the files \texttt{read.g} of \texttt{A} and \texttt{B} (in the same order). 
\end{itemize}
 

 In general, when \textsf{GAP} 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 \textsf{GAP} runs through the package sets and reads for each set first all \texttt{init.g} files and then all \texttt{read.g} files of the packages in the set. (There is one exception from this rule:
Whenever packages are autoloaded before the implementation part of the \textsf{GAP} library is read, only the \texttt{init.g} files of the packages are read; as soon as the \textsf{GAP} library has been read, the \texttt{read.g} files of these packages are also read, and afterwards the above rule holds.) 

 \index{IsPackageMarkedForLoading@\texttt{IsPackageMarkedForLoading}} It 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 \texttt{IsPackageMarkedForLoading} (\textbf{Reference: IsPackageMarkedForLoading}). In particular, one should \emph{not} call (and use the value returned by this call) the function \texttt{LoadPackage} (\textbf{Reference: LoadPackage}) 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 \texttt{OnlyNeeded}. 

 Note that the separation of the \textsf{GAP} code of packages into declaration part and implementation part does in general \emph{not} allow one to actually \emph{call} functions from a package when the implementation part is read. For example, in
the case of a ``cyclic dependency'' as in the second example above, suppose that \texttt{B} provides a new function \texttt{f} or a new global record \texttt{r}, say, which are declared in the declaration part of \texttt{B}. Then the code in the implementation part of \texttt{A} may contain calls to the functions defined in the declaration part of \texttt{B}. However, the implementation part of \texttt{A} may be read \emph{before} the implementation part of \texttt{B}. So one can in general not assume that during the loading of \texttt{A}, the function \texttt{f} can be called, or that one can access components of the record \texttt{r}. 

 If one wants to call the function \texttt{f} or to access components of the record \texttt{r} in the code of the package \texttt{A} then the problem is that it may be not possible to determine a cyclic
dependency between \texttt{A} and \texttt{B} from the packages \texttt{A} and \texttt{B} alone. A safe solution is then to add the name of \texttt{B} to the component \texttt{Dependencies.OtherPackagesLoadedInAdvance} of the \texttt{PackageInfo.g} file of \texttt{A}. The effect is that package \texttt{B} is completely loaded before the file \texttt{read.g} of \texttt{A} is read, provided that there is no cyclic dependency between \texttt{A} and \texttt{B}, and that package \texttt{A} is regarded as not available in the case that such a cyclic dependency between \texttt{A} and \texttt{B} exists. 

 A special case where \texttt{Dependencies.OtherPackagesLoadedInAdvance} can be useful is that a package wants to force the complete \textsf{GAP} library to be read before the file \texttt{read.g} of the package \texttt{A} is read. In this situation, the ``package name'' \texttt{"gap"} should be added to this component in the \texttt{PackageInfo.g} file of \texttt{A}. 

 \index{autoreadable variables} In the case of cyclic dependencies, one solution for the above problem might
be to delay those computations (typically initializations) in package \texttt{A} that require package \texttt{B} to be loaded until all required packages are completely loaded. This can be
done by moving the declaration and implementation of the variables that are
created in the initialization into a separate file and to declare these
variables in the \texttt{init.g} file of the package, via a call to \texttt{DeclareAutoreadableVariables} (\textbf{Reference: DeclareAutoreadableVariables}) (see also \ref{Autoreadable Variables}). 

 }

  
\section{\textcolor{Chapter }{Autoreadable Variables}}\label{Autoreadable Variables}
\logpage{[ "A", 9, 0 ]}
\hyperdef{L}{X7D7F236A78106358}{}
{
  Package files containing method installations must be read when the package is
loaded. For package files \emph{not} containing method installations (this applies, for example, to many data
files) another mechanism allows one to delay reading such files until the data
are actually accessed. See  \textbf{Reference: DeclareAutoreadableVariables} for further details. }

  
\section{\textcolor{Chapter }{Standalone Programs in a \textsf{GAP} Package}}\label{Standalone Programs in a GAP Package}
\logpage{[ "A", 10, 0 ]}
\hyperdef{L}{X84F13D358249EC3C}{}
{
  \textsf{GAP} packages that involve stand-alone programs are fundamentally different from \textsf{GAP} packages that consist entirely of \textsf{GAP} code. 

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

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

  
\subsection{\textcolor{Chapter }{Installation of \textsf{GAP} Package Binaries}}\label{Installation of GAP Package Binaries}
\logpage{[ "A", 10, 1 ]}
\hyperdef{L}{X83EF9C32795BAD9F}{}
{
  \index{sysinfo.gap@\texttt{sysinfo.gap}} \index{external binaries!for a GAP package} The scheme for the installation of package binaries which is described further
on is intended to permit the installation on different architectures which
share a common file system (and share the architecture independent file). 

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

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  GAParch=i586-unknown-linux2.0.31-gcc
\end{Verbatim}
 

 We suggest that your \textsf{GAP} package contains a file \texttt{configure} which is called with the path of the \textsf{GAP} root directory as parameter. This file then will read \texttt{sysinfo.gap} and set up everything for compiling under the given architecture (for example
creating a \texttt{Makefile} from \texttt{Makefile.in}). As initial templates, you may use installation scripts of the \textsf{Example} package. }

  
\subsection{\textcolor{Chapter }{Test for the Existence of GAP Package Binaries}}\label{Test for the Existence of GAP Package Binaries}
\logpage{[ "A", 10, 2 ]}
\hyperdef{L}{X7E4F39867CCC6026}{}
{
  If an external binary is essential for the workings of a \textsf{GAP} package, the function stored in the component \texttt{AvailabilityTest} of the \texttt{PackageInfo.g} file of the package should test whether the program has been compiled on the
architecture (and inhibit package loading if this is not the case). This is
especially important if the package is loaded automatically. 

 The easiest way to accomplish this is to use \texttt{Filename} (\textbf{Reference: Filename (for a directory and a string)}) for checking for the actual binaries in the path given by \texttt{DirectoriesPackagePrograms} (\textbf{Reference: DirectoriesPackagePrograms}) for the respective package. For example the \textsf{example} \textsf{GAP} package could use the following function to test whether the binary \texttt{hello} has been compiled; it will issue a warning if not, and will only load the
package if the binary is indeed available: 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  ...
  AvailabilityTest := function()
    local path,file;
      # test for existence of the compiled binary
      path:= DirectoriesPackagePrograms( "example" );
      file:= Filename( path, "hello" );
      if file = fail then
        LogPackageLoadingMessage( PACKAGE_WARNING,
            [ "The program `hello' is not compiled,",
              "`HelloWorld()' is thus unavailable.",
              "See the installation instructions;",
              "type: ?Installing the Example package" ] );
      fi;
      return file <> fail;
    end,
  ...
\end{Verbatim}
 

 However, if you look at the actual \texttt{PackageInfo.g} file of the \textsf{example} package, you will see that its \texttt{AvailabilityTest} function always returns \texttt{true}, and just logs the warning if the binary is not available (which may be later
viewed with \texttt{DisplayPackageLoadingLog} (\textbf{Reference: DisplayPackageLoadingLog})). This means that the binary is not regarded as essential for this package. 

 You might also have to cope with the situation that external binaries will
only run under UNIX (and not, say, under Windows), or may not compile with
some compilers or default compiler options. See{\nobreakspace} (\textbf{Reference: Testing for the System Architecture}) for information on how to test for the architecture. 

 \index{LogPackageLoadingMessage@\texttt{LogPackageLoadingMessage}} Last but not least: do not print anything in the \texttt{AvailabilityTest} function of the package via \texttt{Print} or \texttt{Info}. Instead one should call \texttt{LogPackageLoadingMessage} (\textbf{Reference: LogPackageLoadingMessage}) to store a message which may be viewed later with \texttt{DisplayPackageLoadingLog} (\textbf{Reference: DisplayPackageLoadingLog}) (the latter two functions are introduced in \textsf{GAP}{\nobreakspace}4.5) }

  
\subsection{\textcolor{Chapter }{Calling of and Communication with External Binaries}}\label{Calling of and Communication with External Binaries}
\logpage{[ "A", 10, 3 ]}
\hyperdef{L}{X8438685184FCEFEC}{}
{
  There are two reasons for this: the input data has to be passed on to the
stand-alone program and the stand-alone program has to be started from within \textsf{GAP}. 

 There are two principal ways of doing this. 

 The first possibility is to write all the data for the stand-alone to one or
several files, then start the stand-alone with \texttt{Process} (\textbf{Reference: Process}) or \texttt{Exec} (\textbf{Reference: Exec}) which then writes the output data to file, and finally read in the
standalone's output file. 

 The second way is interfacing via input-output streams, see
Section{\nobreakspace} (\textbf{Reference: Input-Output Streams}). 

 Some \textsf{GAP} packages use kernel modules (see  (\textbf{Reference: Kernel modules in GAP packages})) instead of external binaries. A kernel module is implemented in C and
follows certain conventions to comply with the \textsf{GAP} 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 \textsf{GAP} developers if you plan to develop such a package. }

 }

  
\section{\textcolor{Chapter }{Having an InfoClass}}\label{Having an InfoClass}
\logpage{[ "A", 11, 0 ]}
\hyperdef{L}{X78969BA778DDE385}{}
{
   \index{InfoClass@\texttt{InfoClass}!for a GAP package} It is a good idea to declare an \texttt{InfoClass} for your package. This gives the package user the opportunity to control the
verbosity of output and/or the possibility of receiving debugging information
(see{\nobreakspace} (\textbf{Reference: Info Functions})). Below, we give a quick overview of its utility. 

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

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

  
\section{\textcolor{Chapter }{The Banner}}\label{The Banner}
\logpage{[ "A", 12, 0 ]}
\hyperdef{L}{X784E0A5A7DB88332}{}
{
  \index{banner!for a GAP package} Since \textsf{GAP}{\nobreakspace}4.4, the package banner, if one is desired, should be provided
by assigning a string to the \texttt{BannerString} field of the record argument of \texttt{SetPackageInfo} in the \texttt{PackageInfo.g} file. 

 It is a good idea to have a hook into your package documentation from your
banner. The banner of the \textsf{Example} package suggests to the \textsf{GAP} user: 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  For help, type: ?Example package
\end{Verbatim}
 

 In order for this to display the introduction of the \textsf{Example} package the index-entry \texttt{{\textless}Index{\textgreater}Example package{\textless}/Index{\textgreater}} was added just before the first paragraph of the introductory section in the
file \texttt{example.xml}. The \textsf{Example} package uses \textsf{GAPDoc} (see Section{\nobreakspace}\ref{Writing Documentation and Tools Needed}) for documentation (you will need some different scheme to achieve this using
the \texttt{gapmacro.tex} system). }

  
\section{\textcolor{Chapter }{Version Numbers}}\label{Version Numbers}
\logpage{[ "A", 13, 0 ]}
\hyperdef{L}{X8180BCDA82587F41}{}
{
  \index{version number!for a GAP package} Version numbers are strings containing nonnegative integers separated by
non-numeric characters. They are compared by \texttt{CompareVersionNumbers} (\textbf{Reference: CompareVersionNumbers}) which first splits them at non-digit characters and then lexicographically
compares the resulting integer lists. Thus version \texttt{"2-3"} is larger than version \texttt{"2-2-5"} but smaller than \texttt{"4r2p3"} or \texttt{"11.0"}. 

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

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

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

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

 It is very important that there should not ever be, for a given \textsf{GAP} package, two different archives with the same package version number. If you
make changes to your package and place a new archive of the package onto the
public server, please ensure that a new archive has a new version number. This
should be done even for very minor changes. 

 For most of the packages it will be inappropriate to re-use the date of the
release as a version number. It's much more obvious how big are the changes
between versions "4.4.12", "4.5.1" and "4.5.2" than between versions
"2008.12.17", "2011.04.15" and "2011.09.14". 

 Since version information is duplicated in several places throughout the
package documentation, for \textsf{GAPDoc}-based manuals you may define the version and the release manual in the
comments in \texttt{PackageInfo.g} file close to the place where you specified its \texttt{Version} and \texttt{Date} components, for example 
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=Example]
  ##  <#GAPDoc Label="PKGVERSIONDATA">
  ##  <!ENTITY VERSION "3.3">
  ##  <!ENTITY RELEASEDATE "11/11/2011">
  ##  <#/GAPDoc>
\end{Verbatim}
 notify \texttt{MakeGAPDocDoc} (\textbf{GAPDoc: MakeGAPDocDoc}) that a part of the document is stored in \texttt{PackageInfo.g} (see \texttt{example/makedocrel.g}), read this data into the header of the main document via \texttt{{\textless}\#Include Label="PKGVERSIONDATA"{\textgreater}} 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). }

  
\section{\textcolor{Chapter }{Testing a \textsf{GAP} package}}\label{Testing a GAP package}
\logpage{[ "A", 14, 0 ]}
\hyperdef{L}{X79EE09BC85E32640}{}
{
  
\subsection{\textcolor{Chapter }{Tests files for a GAP package}}\label{Tests files for a GAP package}
\logpage{[ "A", 14, 1 ]}
\hyperdef{L}{X85CA2F547CF87666}{}
{
  The (optional) \texttt{tst} directory of your package may contain as many tests of the package
functionality as appears appropriate. These tests should be organised into
test files similarly to those in the \texttt{tst} directory of the \textsf{GAP} distribution as documented in  (\textbf{Reference: Test Files}). 

 For a deposited package, a test file with a basic test of the package (for
example, to check that it works as expected and/or that the manual examples
are correct) may be specified in the component \texttt{TestFile} in the \texttt{PackageInfo.g} to be included in the GAP standard test suite. This file can either consist of \texttt{ReadTest} (\textbf{Reference: ReadTest}) calls (in this case, it is common to call it \texttt{testall.g}) or be itself a test file having an extension \texttt{.tst} and supposed to be read via \texttt{ReadTest} (\textbf{Reference: ReadTest}). It is assumed that the latter case occurs if and only if the file contains
the substring

 {\nobreakspace}\texttt{"gap{\textgreater} START{\textunderscore}TEST("} 

 \noindent (with exactly one space after the \textsf{GAP} prompt). 

 For deposited packages, these tests are run by the \textsf{GAP} Group regularly, as a part of the standard \textsf{GAP} test suite. For the efficient testing it is important that the test specified
in the \texttt{PackageInfo.g} file does not display any output (e.g. no test progress indicators) except
reporting discrepancies if such occur and the completion report as in the
example below: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@ReadTest("tst/testall.tst");|
  Line 50 : 
  + Example package: testall.tst
  Line 50 : 
  + GAP4stones: 10000
  true
\end{Verbatim}
 Tests which produce extended output and/or requires substantial runtime are
not supposed to be a part of the \textsf{GAP} standard test suite but may be placed in the \texttt{tst} directory of the packages with further instructions on how to run them
elsewhere. }

 
\subsection{\textcolor{Chapter }{Testing \textsf{GAP} package loading}}\label{Testing GAP package loading}
\logpage{[ "A", 14, 2 ]}
\hyperdef{L}{X7BE11072850F07CD}{}
{
  To test that your package may be loaded into \textsf{GAP} without any problems and conflicts with other packages, test that it may be
loaded in various configurations: 
\begin{itemize}
\item  starting \textsf{GAP} with no packages (except needed for \textsf{GAP}) using \texttt{-r -A} options and calling \texttt{LoadPackage("your-package-name");} 
\item  starting \textsf{GAP} with no packages (except needed for \textsf{GAP}) using \texttt{-r -A} options and calling \texttt{LoadPackage("your-package-name" : OnlyNeeded );} 
\item  starting \textsf{GAP} in the default configuration (with no options) and calling \texttt{LoadPackage("your-package-name");} 
\item  starting \textsf{GAP} in the default configuration (with no options) and calling \texttt{LoadPackage("your-package-name" : OnlyNeeded );} 
\item  finally, together with all other packages using \texttt{LoadAllPackages} (\ref{LoadAllPackages}) (see below) in four possible combinations of starting \textsf{GAP} with/without \texttt{-r -A} options and calling \texttt{LoadAllPackages} (\ref{LoadAllPackages}) with/without \texttt{Reversed} option. 
\end{itemize}
 The test of loading all packages is the most subtle one. Quite often it
reveals problems which do not occur in the default configuration but may cause
difficulties to the users of specialised packages. 

 For your convenience, \texttt{make testpackagesload} called in the \textsf{GAP} root directory will run all package loading tests listed in this subsection
and write their output in its \texttt{dev/log} directory. 

 It will produce four files with test logs, corresponding to the four cases
above (the letter \texttt{N} in the filename stands for ``needed'', \texttt{A} stands for ``autoloaded''): 
\begin{itemize}
\item  \texttt{dev/log/testpackagesload1{\textunderscore}...} 
\item  \texttt{dev/log/testpackagesloadN1{\textunderscore}...} 
\item  \texttt{dev/log/testpackagesloadA{\textunderscore}...} 
\item  \texttt{dev/log/testpackagesloadNA{\textunderscore}...} 
\end{itemize}
 Each file contains small sections for loading individual packages: among
those, you need to find the section related to your package and may ignore all
other sections. For example, the section for the \textsf{Example} package looks like 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  %%% Loading example 3.3.3
  [  ]
  ### Loaded example 3.3.3
\end{Verbatim}
 so it has clearly passed the test. If there are any error messages displayed
between \texttt{Loading ...} and \texttt{Loaded ...} lines, they will signal on errors during loading of your package. 

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

 Finally, each log file finishes with two large sections for loading all
packages in the alphabetical and reverse aplhabetical order (to check more
combinations of loading one package after another). We are aiming at releasing
only collections of package which do not break \texttt{LoadAllPackages} (\ref{LoadAllPackages}) 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 \textsf{GAP}, it is likely that your package triggers this error. If you observe that \texttt{LoadAllPackages} (\ref{LoadAllPackages}) is broken and suspect that this is not the fault of your package, please
contact the \textsf{GAP} Support. }

 

\subsection{\textcolor{Chapter }{LoadAllPackages}}
\logpage{[ "A", 14, 3 ]}\nobreak
\hyperdef{L}{X80A0D21D78CF8494}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{LoadAllPackages({\mdseries\slshape : Reversed})\index{LoadAllPackages@\texttt{LoadAllPackages}}
\label{LoadAllPackages}
}\hfill{\scriptsize (function)}}\\


 loads all \textsf{GAP} packages from their list sorted in alphabetical order (needed and suggested
packages will be loaded when required). This is a technical function to check
packages compatibility, so it should NOT be used to run anything except tests;
it is known that \textsf{GAP} performance is slower if all packages are loaded. To introduce some variations
of the order in which packages will be loaded for testing purposes, \texttt{LoadAllPackages} accepts version \texttt{Reversed} to load packages from their list sorted in the reverse alphabetical order. }

 
\subsection{\textcolor{Chapter }{Testing a \textsf{GAP} package with the \textsf{GAP} standard test suite}}\label{Testing a GAP package with the GAP standard test suite}
\logpage{[ "A", 14, 4 ]}
\hyperdef{L}{X7ECAB2357B024ABA}{}
{
  The \texttt{tst} directory of the \textsf{GAP} installation contains a selection of test files and two scripts, \texttt{testinstall.g} and \texttt{testall.g} which are a part of the \textsf{GAP} standard test suite. 

 It is important to check that your package does not break \textsf{GAP} standard tests. To perform a clean test and avoid interfering with other
packages, first you must start a new \textsf{GAP} session with the following command (assuming that \texttt{gap} starts \textsf{GAP} in your system): 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  gap -N -A -x 80 -r -m 100m -o 512m
\end{Verbatim}
 After that load your package and run either \texttt{testinstall.g} or \texttt{testall.g} as demonstrated below. 

 The quicker test, \texttt{testinstall.g}, requires about 512MB of memory and runs for about one minute on an Intel
Core 2 Duo / 2.53 GHz machine. It may be started with the command 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@Read( Filename( DirectoriesLibrary( "tst" ), "testinstall.g" ) );|
\end{Verbatim}
 You will get a large number of lines with output about the progress of the
tests. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  test file         GAP4stones     time(msec)
  -------------------------------------------
  testing: .../gap4r5/tst/zlattice.tst
  zlattice.tst               0              0
  testing: .../gap4r5/tst/gaussian.tst
  gaussian.tst               0             10
  ... further lines deleted ...
\end{Verbatim}
 

 The more thorough test is \texttt{testall.g} which exercises more of \textsf{GAP}'s capabilities, containing all test files from \texttt{testinstall.g} as a subset. It requires about 512MB of memory, runs for about one hour on an
Intel Core 2 Duo / 2.53 GHz machine, and produces an output similar to the
testinstall.g test. To run it, also start a new \textsf{GAP} session with \texttt{gap -N -A -x 80 -r -m 100m -o 512m} and then call 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@Read( Filename( DirectoriesLibrary( "tst" ), "testall.g" ) );|
\end{Verbatim}
 You may repeat the same check loading your package with \texttt{OnlyNeeded} option. Remember to perform each subsequent test in a new \textsf{GAP} session. 

 Also you may perform individual tests from the \texttt{tst} directory of the \textsf{GAP} installation loading them with \texttt{ReadTest} (\textbf{Reference: ReadTest}), for example, the file \texttt{bugfix.tst}. 

 }

 }

  
\section{\textcolor{Chapter }{Access to the \textsf{GAP} Development Version}}\label{Access to the GAP Development Version}
\logpage{[ "A", 15, 0 ]}
\hyperdef{L}{X86DEFDA57A0976C0}{}
{
  We are aiming at providing a stable platform for package development and
testing with official \textsf{GAP} releases. However, when it may be of benefit to obtain access to the \textsf{GAP} development version, please contact the \textsf{GAP} team by mailing to \href{mailto://support@gap-system.org} {\texttt{support@gap-system.org}}. 

 }

  
\section{\textcolor{Chapter }{Selecting a license for a \textsf{GAP} Package}}\label{Selecting a license for a GAP Package}
\logpage{[ "A", 16, 0 ]}
\hyperdef{L}{X8296209D82C12A73}{}
{
  It is advised to make clear in the documentation of the package the basis on
which it is being distributed to users. GAP itself is distributed under the
GNU Public License version 2 (version 2 or later). We would encourage you to
consider the GPL for your packages, but you might wish to be more restrictive
(for instance forbidding redistribution for profit) or less restrictive
(allowing your software to be incorporated into commercial software). See ``Choosing a License for the Distribution of Your Package'' from \href{http://www.gap-system.org/Packages/Authors/authors.html} {\texttt{http://www.gap-system.org/Packages/Authors/authors.html}} for further details. 

 In the past many \textsf{GAP} packages used the text ``We adopt the copyright regulations of GAP as detailed in the copyright notice
in the \textsf{GAP} manual'' or a similar statement. We now advise to be more explicit and make the exact
reference to the GPL license, for example: 

 \emph{ \textsf{package-name} is free software; you can redistribute it and/or modify it under the terms of
the \href{http://www.fsf.org/licenses/gpl.html} {GNU General Public License} as published by the Free Software Foundation; either version 2 of the License,
or (at your option) any later version. } }

  
\section{\textcolor{Chapter }{Wrapping up a \textsf{GAP} Package}}\label{Wrapping up a GAP Package}
\logpage{[ "A", 17, 0 ]}
\hyperdef{L}{X85AA25B97FEFA49E}{}
{
   Currently, the \textsf{GAP} distribution provides archives in four different formats. 

 
\begin{description}
\item[{\texttt{.tar.gz}}]  a standard UNIX \texttt{tar} archive, compressed with \texttt{gzip} 
\item[{\texttt{.tar.bz2}}]  a standard UNIX \texttt{tar} archive, compressed with \texttt{bzip2} 
\item[{\texttt{.zip}}]  an archive in \texttt{zip} format, where text files should have UNIX style line breaks 
\item[{\texttt{-win.zip}}]  an archive in \texttt{zip} format, where text files should have DOS/Windows style line breaks 
\end{description}
 

 For convenience of possible users it is sensible that you provide an archive
of your package in at least one of these formats. 

 For example, if you wish to supply a \texttt{.tar.gz} archive, you may create it with the command 

 {\nobreakspace}\texttt{tar -cvzf package-name-version.tar.gz package-name} 

 \noindent The \texttt{etc} directory obtained from \texttt{tools.tar.gz} (described above in Section{\nobreakspace}\ref{Writing Documentation and Tools Needed}) contains a file \texttt{packpack} which provides a more versatile packing-up script. 

 In the past, it was recommended that your \textsf{GAP} package should be packed with the \texttt{zoo} archiver. We do not redistribute \texttt{.zoo} archives since \textsf{GAP}{\nobreakspace}4.5, but we still accept package archives in \texttt{.zoo} format for backwards compatibility, if no other formats are available. 

 Because the release of the \textsf{GAP} package is independent of the version of \textsf{GAP}, a \textsf{GAP} package should be wrapped up in separate file that can be installed onto any
version of \textsf{GAP}. In this way, a package can be upgraded any time without the need to wait for
new \textsf{GAP} releases. To ensure this, the package should be archived from the \textsf{GAP} \texttt{pkg} directory, that is all files are archived with the path starting at the
package's name. 

 \index{GAPDocManualLab@\texttt{GAPDocManualLab}} The archive of a \textsf{GAP} package should contain all files necessary for the package to work. In
particular there should be a compiled documentation, which includes the \texttt{manual.six}, \texttt{manual.toc} and \texttt{manual.lab} file in the documentation subdirectory which are created by {\TeX}ing the documentation, if you use \textsf{GAPDoc} or the \texttt{gapmacro.tex} document formats. (The first two files are needed by the \textsf{GAP} help system, and the \texttt{manual.lab} file is needed if the main manuals or another package is referring to your
package. Use the command \texttt{GAPDocManualLab( packagename );} to create this file for your help books if you use \textsf{GAPDoc}.) 

 For packages which are redistributed via the \textsf{GAP} Web site, we offer an automatic conversion of any of the formats listed above
to all the others (this, as well as wrapping the \textsf{GAP} distribution as a single archive containing the core system and all currently
redistributed packages, will change file timestamps, so one should not rely on
them anywhere in the package). 

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

 The package wrapping tools for the \textsf{GAP} distribution and web pages then will use a sensible list of file extensions to
decide if a file is a text file (being conservative, it may miss a few text
files). These rules may be prepended by the application of rules from the \texttt{PackageInfo.g} file: 
\begin{itemize}
\item  if it has a \texttt{.TextFiles} component, then consider the given files as text files before \textsf{GAP} defaults will be applied; 
\item  if it has a \texttt{.BinaryFiles} component, then consider given files as binary files before \textsf{GAP} defaults will be applied; 
\item  if it has a \texttt{.TextBinaryFilesPatterns} component, then apply it before \textsf{GAP} defaults will be applied; 
\end{itemize}
 

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

 Utility functions available in \texttt{gap4r7/lib/lbutil.g}, namely \texttt{DosUnixLinebreaks}, \texttt{UnixDosLinebreaks}, \texttt{MacUnixLinebreaks} may be helpful. They are described in the comments to their source code. }

  
\section{\textcolor{Chapter }{The WWW Homepage of a Package}}\label{The WWW Homepage of a Package}
\logpage{[ "A", 18, 0 ]}
\hyperdef{L}{X80A75C09812F9B7A}{}
{
  If you want to distribute your package you should create a WWW homepage
containing some basic information, archives for download, the \texttt{README} file with installation instructions, and a copy of the package's \texttt{PackageInfo.g} file. 

 The responsibility for this WWW homepage is with the package
authors/maintainers. 

 If you tell us about your package (say, by mail to \href{mailto://support@gap-system.org} {\texttt{support@gap-system.org}}) we may consider either 
\begin{itemize}
\item  adding a link to your package homepage from the \textsf{GAP} website (thus, the package will be an \emph{undeposited contribution}); 
\item  or redistributing the current version of your package as a part of the \textsf{GAP} distribution (this, the package will be \emph{deposited}), also ; 
\end{itemize}
 In the latter case we can also provide some services for producing several
archive formats from the archive you provide (e.g., you produce a \texttt{.tar.gz} version of your archive and we produce also a \texttt{.tar.bz2} and a \texttt{-win.zip} version from it). 

 Please also consider submitting your package to the \textsf{GAP} package refereeing process (see \href{http://www.gap-system.org/Contacts/submit.html} {\texttt{http://www.gap-system.org/Contacts/submit.html}} for further information). }

  
\section{\textcolor{Chapter }{Upgrading the package to work with \textsf{GAP}{\nobreakspace}4.5}}\label{Upgrading the package to work with GAP 4.5}
\logpage{[ "A", 19, 0 ]}
\hyperdef{L}{X86C2A6A08063E0D2}{}
{
  
\subsection{\textcolor{Chapter }{Changes in \textsf{GAP}{\nobreakspace}4.5 from the packages perspective}}\label{Changes in GAP 4.5 from the packages perspective}
\logpage{[ "A", 19, 1 ]}
\hyperdef{L}{X8631074083FC19DA}{}
{
  Here we list only those changes which may have some implications for the
packages. 
\begin{itemize}
\item  Changing the distribution format providing one archive with the core system
and all currently redistributed packages. 
\item  The \textsf{GAP} kernel is now compiled by default to use the GMP large integer arithmetic
library, speeding up arithmetic by a factor of 4 or more in many cases. This
slightly changes the build process, affecting mainly packages with dynamically
loaded modules (see \href{http://www.gap-system.org/Download/} {\texttt{http://www.gap-system.org/Download/}} for \textsf{GAP} installation instructions). 
\item  The \textsf{GAP} documentation has been converted to the \textsf{GAPDoc} format and extensively reviewed. Now it has only two books: the Tutorial and
the Reference Manual. The two other books, ``Extending \textsf{GAP}'' and ``Programming Tutorial'' became parts of the Reference Manual. Packages that refer to parts of the \textsf{GAP} documentation may need to rebuild their manuals to update references. 

 Some packages still use the old ``gapmacro'' format for their manuals, for which support may be discontinued in the future.
There is no urgent need to convert such manuals into the \textsf{GAPDoc} format before \textsf{GAP}{\nobreakspace}4.5 release, but we encourage you very much to consider doing
this at some later point. 
\item  The old concept of an autoloaded package has been integrated with the \emph{needed} and \emph{suggested} mechanism that already exists between packages. \textsf{GAP} itself now ``needs'' certain packages (for instance \textsf{GAPDoc}) and ``suggests'' others (typically the packages that were autoloaded). The decisions which
packages \textsf{GAP} should need or suggest are made by developers based on technical criteria.
They can be easily overridden by a user using the new \texttt{gap.ini} (see  (\textbf{Reference: The gap.ini and gaprc files})). The default file ensures that all previously autoloaded packages are still
loaded if present. 
\item  Optional \texttt{\texttt{\symbol{126}}/.gap} directory for user's customisations which may contain e.g. locally installed
packages (see  (\textbf{Reference: GAP Root Directories})). 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 \texttt{.gaprc} files, but those are still supported for backwards compatibility (see  (\textbf{Reference: The former .gaprc file})). 
\item  Various improvements in the packages loading mechanism make it more
informative, while avoiding confusing the user with warning and error messages
for packages they didn't know they were loading. For example, many messages
are stored but not displayed using the function \texttt{LogPackageLoadingMessage} (\textbf{Reference: LogPackageLoadingMessage}) and there is a function \texttt{DisplayPackageLoadingLog} (\textbf{Reference: DisplayPackageLoadingLog}) 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. 
\item  Since \textsf{GAP}{\nobreakspace}4.5 a package may place global variables into a local namespace
as explained in  (\textbf{Reference: Namespaces for GAP packages}) in order to avoid name clashes and preserve compatibility. 
\item  In \textsf{GAP}{\nobreakspace}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 \texttt{RecNames} (\textbf{Reference: RecNames}) 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 \texttt{Set} (\textbf{Reference: Set}), sort lists of records, find records with binary search, etc., but a care
should be taken not to rely on \texttt{RecNames} (\textbf{Reference: RecNames}) always returning names of components in the same order. 
\end{itemize}
 }

 }

  
\section{\textcolor{Chapter }{Checklists}}\label{Checklists}
\logpage{[ "A", 20, 0 ]}
\hyperdef{L}{X84619DEB8161417E}{}
{
  \index{checklists} 
\subsection{\textcolor{Chapter }{Package release checklist}}\label{Package release checklist}
\logpage{[ "A", 20, 1 ]}
\hyperdef{L}{X8393B9AC87D358FD}{}
{
  The following checklist may be used by package authors, members of the \textsf{GAP} team responsible for package updates, package editors and referees. 
\begin{itemize}
\item  Test that the package: 
\begin{itemize}
\item  does not break \texttt{testinstall.g} and \texttt{testall.g} and does not slow them down noticeably (see \ref{Testing a GAP package with the GAP standard test suite}); 
\item  may be loaded in various configurations (see \ref{Testing GAP package loading}); 
\item  follows the guidelines of Section \ref{Functions and Variables and Choices of Their Names} about names of functions and variables; 
\end{itemize}
 
\item  Package documentation: 
\begin{itemize}
\item  is built and included in the package archive together with its source files; 
\item  states the version, release date and package authors; 
\item  has the same version, release date and package authors details as stated in
the \texttt{PackageInfo.g} file; 
\item  is searchable using the \textsf{GAP} help system; 
\item  is clear about the license under which the package is distributed; 
\end{itemize}
 
\item  \texttt{PackageInfo.g} file: 
\begin{itemize}
\item  has the same version, release date and package authors details as stated in
the package manual; 
\item  has all mandatory components and also optional components where appropriate; 
\item  in particular, contains hints to distinguish binary and text files in case of
non-standard file names and extensions; 
\item  is validated using \texttt{ValidatePackageInfo} (\textbf{Reference: ValidatePackageInfo}); 
\end{itemize}
 
\item  Package archive(s): 
\begin{itemize}
\item  have correct permisisons for all files and directories after their unpacking
(755 for directories and executables, if any; 644 for other files); 
\item  contain files with correct line breaks for the given format (see \ref{Wrapping up a GAP Package}); 
\item  contain no hidden system files and directories that are not supposed to be
included in the package, e.g. \texttt{.cvsignore}, \texttt{.git} etc.; 
\end{itemize}
 
\item  Package availability: 
\begin{itemize}
\item  not only the package archive(s), but also the \texttt{PackageInfo.g} and \texttt{README} files are available online; 
\item  the URL of the \texttt{PackageInfo.g} file is validated using the online tool available from \href{http://www.gap-system.org/Packages/Authors/authors.html} {\texttt{http://www.gap-system.org/Packages/Authors/authors.html}}; 
\end{itemize}
 
\end{itemize}
 }

 
\subsection{\textcolor{Chapter }{Checklist for package upgrade to work with \textsf{GAP}{\nobreakspace}4.5}}\label{Checklist for package upgrade to work with GAP 4.5}
\logpage{[ "A", 20, 2 ]}
\hyperdef{L}{X7FB5FFF082351DA6}{}
{
  The following checklist will help you to check how well your package is ready
to work with \textsf{GAP}{\nobreakspace}4.5. 

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

 Note that it's not possible for a package to have an HTML manual which
contains correct links to both \textsf{GAP}{\nobreakspace}4.4 and \textsf{GAP}{\nobreakspace}4.5 main manuals. 
\end{description}
 
\item  Optional changes recommended for package upgrade to work with \textsf{GAP}{\nobreakspace}4.5: 
\begin{itemize}
\item  When the \texttt{AvailabilityTest} component in \texttt{PackageInfo.g} differs from \texttt{ReturnTrue} (\textbf{Reference: ReturnTrue}), use \texttt{LogPackageLoadingMessage} (\textbf{Reference: LogPackageLoadingMessage}) to store a message which may be viewed later with \texttt{DisplayPackageLoadingLog} (\textbf{Reference: DisplayPackageLoadingLog}) instead of calling \texttt{Print} or \texttt{Info} directly (see \ref{Test for the Existence of GAP Package Binaries}). 
\item  It is recommended not to call \texttt{LoadPackage} (\textbf{Reference: LoadPackage}) 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 \texttt{DisplayPackageLoadingLog( PACKAGE{\textunderscore}WARNING );}. If there is a genuine need to decide whether some package will be available
at runtime, use the function \texttt{IsPackageMarkedForLoading} (\textbf{Reference: IsPackageMarkedForLoading}) introduced in \textsf{GAP}{\nobreakspace}4.5. 
\item  Check if the package still relies on some obsolete variables (see  (\textbf{Reference: Replaced and Removed Command Names})) and try to get rid of their usage. 
\end{itemize}
 
\end{itemize}
 }

 }

 }

\def\indexname{Index\logpage{[ "Ind", 0, 0 ]}
\hyperdef{L}{X83A0356F839C696F}{}
}

\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{Index}


\printindex

\newpage
\immediate\write\pagenrlog{["End"], \arabic{page}];}
\immediate\closeout\pagenrlog
\end{document}
