Goto Chapter: Top 1 2 3 4 5 6 Bib Ind
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 

1 Introduction
 1.1 Information for package authors
 1.2 The current transfer procedure

1 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:

Transfer is complete (for now) for functions from the following packages:

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

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

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

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

  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.

  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.

  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 Bib Ind

generated by GAPDoc2HTML