The 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. (All active authors should be involved.) (&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, and the transferred functions can only be called if &Home; has been installed. (&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.