<h3>12 <span class="Heading">The transfer procedure</span></h3>
<p>We consider here the process for transferring utility functions from a package <strong class="pkg">Home</strong> to <strong class="pkg">Utils</strong> which has to avoid the potential problem of duplicate declarations of a function causing loading problems in <strong class="pkg">GAP</strong>.</p>
<p>If the functions in <strong class="pkg">Home</strong> all have names of the form <code class="code">HOME_FunctionName</code> then, in <strong class="pkg">Utils</strong>, these functions are likely to be renamed as <code class="code">FunctionName</code> or something similar. In this case the problem of duplicate declarations does not arise. This is what has happened with transfers from the <strong class="pkg">AutoDoc</strong> package.</p>
<p>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 <code class="file">global.g</code> and <code class="file">oper.g</code>. Since there were misgivings about interfering in this way with basic operations such as <code class="code">BIND_GLOBAL</code>, a simpler (but slightly less convenient) process has been adopted.</p>
<p>Using this alternative procedure, the following steps will be followed when making transfers from <strong class="pkg">Home</strong> to <strong class="pkg">Utils</strong>.</p>
<ol>
<li><p>(<strong class="pkg">Home</strong>:) 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.: <code class="file">home.gd</code>, <code class="file">home.gi</code>, <code class="file">home.tst</code> and <code class="file">home.xml</code>. (All active authors should be involved.)</p>
</li>
<li><p>(<strong class="pkg">Home</strong>:) Declare that <strong class="button">m.n</strong> is the last version of <strong class="pkg">Home</strong> to contain these functions, so that <strong class="button">m.n+1</strong> (or similar) will be the first version of <strong class="pkg">Home</strong> to have all these functions removed, and to specify <strong class="pkg">Utils</strong> as a required package.</p>
</li>
<li><p>(<strong class="pkg">Utils</strong>:) Add strings <var class="Arg">"home"</var> and <var class="Arg">"m.n"</var> to the list <code class="code">UtilsPackageVersions</code> in the file <code class="file">utils/lib/start.gd</code>.</p>
<p>While the transfers are being made, it is essential that any new versions of <strong class="pkg">Home</strong> should be tested with the latest version of <strong class="pkg">Utils</strong> before they are released, so as to avoid loading failures.</p>
</li>
<li><p>(<strong class="pkg">Utils</strong>:) Include the function declaration and implementation sections in suitable files, enclosed within a conditional clause of the form:</p>
<div class="example"><pre>
if OKtoReadFromUtils( "Home" ) then
. . . . . .
<the code>
. . . . . .
fi;
</pre></div>
<p>The function <code class="code">OKtoReadFromUtils</code> returns <code class="keyw">true</code> only if there is an installed version of <strong class="pkg">Home</strong> and if this version is greater than <strong class="button">m.n</strong>. So, at this stage, <em>the copied code will not be read</em>, and the transferred functions can only be called if <strong class="pkg">Home</strong> has been installed.</p>
</li>
<li><p>(<strong class="pkg">Utils</strong>:) Add the test and documentation material to the appropriate files. The copied code can be tested by temporarily moving <strong class="pkg">Home</strong> away from <strong class="pkg">GAP</strong>'s package directory.
</li>
<li><p>(<strong class="pkg">Utils</strong>:) Release a new version of <strong class="pkg">Utils</strong> containing all the transferred material.</p>
</li>
<li><p>(<strong class="pkg">Home</strong>:) 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 <strong class="pkg">Utils</strong> to the list of <strong class="pkg">Home</strong>'s required packages in PackageInfo.g. Release a new version of Home.
</li>
<li><p>(<strong class="pkg">Utils</strong>:) In due course, when the new version(s) of <strong class="pkg">Home</strong> are well established, it may be safe to remove the conditional clauses mentioned in item 4 above. The entry for <strong class="pkg">Home</strong> in <code class="code">UtilsPackageLists</code> may then be removed.</p>
</li>
</ol>
<p>Finally, a note on the procedure for testing these functions. As long as a function being transferred still exists in the <strong class="pkg">Home</strong> package, the code will not be read from <strong class="pkg">Utils</strong>. So, when the tests are run, it is necessary to <code class="code">LoadPackage("home")</code> before the function is called. The file <code class="file">utils/tst/testall.g</code> makes sure that all the necessary packages are loaded before the individual tests are called.</p>
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
