[MathJax off]

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

1. (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.)

2. (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.

3. (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.

4. (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;
   
   

   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.

5. (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.

6. (Utils:) Release a new version of Utils containing all the transferred material.

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

8. (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.

generated by GAPDoc2HTML