GAP (Utils) - Chapter 12: The transfer procedure

Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax on]

12 The transfer procedure

### 12 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.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 Bib Ind

generated by GAPDoc2HTML