Introduction The &Utils; package provides a space for utility functions from a variety of &GAP; packages to be collected together into a single package. In this way it is hoped that they will become more visible to other package authors. This package was first distributed as part of the &GAP; 4.8.2 distribution.

The package is loaded with the command
gap> LoadPackage( "utils" );

Functions are currently being transferred from the following packages: &ResClasses;; &RCWA;;

Transfer is complete (for now) for functions from the following packages: &AutoDoc; (with function names changed); &XMod;.

The package may be obtained as a compressed tar file or a .zip file utils-version_number.tar.gz by ftp from one of the following sites: the &Utils; GitHub release site: http://gap-packages.github.io/utils/. any &GAP; archive, e.g. http://www.gap-system.org/Packages/packages.html; repository The package also has a GitHub repository at: https://github.com/gap-packages/utils.

Once the package is loaded, the manual `doc/manual.pdf` can be found in the documentation folder. The `html` versions, with or without MathJax, may be rebuilt as follows:

gap> ReadPackage( "utils", "makedocrel.g" );

It is possible to check that the package has been installed correctly by running the test files:

gap> ReadPackage( "utils", "tst/testall.g" ); #I Testing .../pkg/utils/tst/lists.tst ... #I No errors detected while testing package utils

Note that functions listed in this manual that are currently being transferred are only read from the source package &Home; (say), and so can only be used if &Home; has been previously loaded.
Information for package authors A function (or collection of functions) is suitable for transfer from a package &Home; to &Utils; if the following conditions are satisfied. The function is sufficiently non-specialised so that it might be of use to other authors. The function does not depend on the remaining functions in &Home; The function does not do what can already be done with a &GAP; library function. Documentation of the function and test examples are available.

Authors of packages may be reluctant to let go of their utility functions. The following principles may help to reassure them. (Suggestions for more items here are welcome.) A function that has been transferred to &Utils; will not be changed without the approval of the original author. The current package maintainer has every intention of continuing to maintain &Utils;. In the event that this proves impossible, the &GAP; development team will surely find someone to take over. Function names will not be changed unless specifically requested by &Home;'s author(s) or unless they have the form HOME_FunctionName. In order to speed up the transfer process, only functions from one package will be in transition at any given time. Hopefully a week or two will suffice for most packages. Any package author who transfers a function to &Utils; will become an author of &Utils;.
The current transfer procedure We consider here the process for transferring utility functions from a package &Home; to &Utils; which has to avoid the potential problem of duplicate declarations of a function causing loading problems in &GAP;.

If the functions in &Home; all have names of the form HOME_FunctionName then, in &Utils;, these functions are likely to be renamed as FunctionName or something similar. In this case the problem of duplicate declarations does not arise. This is what has happened with transfers from the AutoDoc package.

The case where the function names are unchanged is more complicated. Initially we tried out a process which allowed repeated declarations and installations of the functions being transferred. This involved additions to the main library files global.g and oper.g. Since there were misgivings about interfering in this way with basic operations such as BIND_GLOBAL, a simpler (but slightly less convenient) process has been adopted.

Using this alternative procedure, the following steps will be followed when making transfers from &Home; to &Utils;. (&Home;:) Offer functions for inclusion. This may be simply done by emailing a list of functions. More usefully, email the declaration, implementation, test and documentation files, e.g.: home.gd, home.gi, home.tst and home.xml. (&Home;:) Declare that m.n is the last version of &Home; to contain these functions, so that m.n+1 (or similar) will be the first version of &Home; to have all these functions removed, and to specify &Utils; as a required package. (&Utils;:) Add strings "home" and "m.n" to the list UtilsPackageVersions in the file utils/lib/start.gd.
UtilsPackageVersions := [ "autodoc", "2016.01.31", "resclasses", "4.2.5", "home", "m.n", ..., ... ];
While the transfers are being made, it is essential that any new versions of &Home; should be tested with the latest version of &Utils; before they are released, so as to avoid loading failures. (&Utils;:) Include the function declaration and implementation sections in suitable files, enclosed within a conditional clause of the form:
if OKtoReadFromUtils( "Home" ) then . . . . . . <the code> . . . . . . fi;
OKtoReadFromUtils The function OKtoReadFromUtils returns true only if there is an installed version of &Home; and if this version is greater than m.n. So, at this stage, the copied code will not be read. (&Utils;:) Add the test and documentation material to the appropriate files. The copied code can be tested by temporarily moving &Home; away from &GAP;'s package directory. (&Utils;:) Release a new version of &Utils; containing all the transferred material. (&Home;:) Edit out the declarations and implementations of all the transferred functions, and remove references to them in the manual and tests. Possibly add a note to the manual that these functions have been transferred. Add &Utils; to the list of &Home;'s required packages in PackageInfo.g. Release a new version of &Home;. (&Utils;:) In due course, when the new version(s) of &Home; are well established, it may be safe to remove the conditional clauses mentioned in item 4 above. The entry for &Home; in UtilsPackageLists may then be removed.

Finally, a note on the procedure for testing these functions. As long as a function being transferred still exists in the &Home; package, the code will not be read from &Utils;. So, when the tests are run, it is necessary to LoadPackage("home") before the function is called. The file utils/tst/testall.g makes sure that all the necessary packages are loaded before the individual tests are called.