Quellcodebibliothek Statistik Leitseite products/sources/formale Sprachen/GAP/doc/ref/   (Algebra von RWTH Aachen Version 4.15.1©)  Datei vom 18.9.2025 mit Größe 192 kB image not shown  

Quelle  chap76.html   Sprache: HTML

 
 products/sources/formale Sprachen/GAP/doc/ref/chap76.html


<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (ref) - Chapter 76: Using and Developing GAP Packages</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap76"  onload="jscontent()">


<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</a>  <a href="chap4.html">4</a>  <a href="chap5.html">5</a>  <a href="chap6.html">6</a>  <a href="chap7.html">7</a>  <a href="chap8.html">8</a>  <a href="chap9.html">9</a>  <a href="chap10.html">10</a>  <a href="chap11.html">11</a>  <a href="chap12.html">12</a>  <a href="chap13.html">13</a>  <a href="chap14.html">14</a>  <a href="chap15.html">15</a>  <a href="chap16.html">16</a>  <a href="chap17.html">17</a>  <a href="chap18.html">18</a>  <a href="chap19.html">19</a>  <a href="chap20.html">20</a>  <a href="chap21.html">21</a>  <a href="chap22.html">22</a>  <a href="chap23.html">23</a>  <a href="chap24.html">24</a>  <a href="chap25.html">25</a>  <a href="chap26.html">26</a>  <a href="chap27.html">27</a>  <a href="chap28.html">28</a>  <a href="chap29.html">29</a>  <a href="chap30.html">30</a>  <a href="chap31.html">31</a>  <a href="chap32.html">32</a>  <a href="chap33.html">33</a>  <a href="chap34.html">34</a>  <a href="chap35.html">35</a>  <a href="chap36.html">36</a>  <a href="chap37.html">37</a>  <a href="chap38.html">38</a>  <a href="chap39.html">39</a>  <a href="chap40.html">40</a>  <a href="chap41.html">41</a>  <a href="chap42.html">42</a>  <a href="chap43.html">43</a>  <a href="chap44.html">44</a>  <a href="chap45.html">45</a>  <a href="chap46.html">46</a>  <a href="chap47.html">47</a>  <a href="chap48.html">48</a>  <a href="chap49.html">49</a>  <a href="chap50.html">50</a>  <a href="chap51.html">51</a>  <a href="chap52.html">52</a>  <a href="chap53.html">53</a>  <a href="chap54.html">54</a>  <a href="chap55.html">55</a>  <a href="chap56.html">56</a>  <a href="chap57.html">57</a>  <a href="chap58.html">58</a>  <a href="chap59.html">59</a>  <a href="chap60.html">60</a>  <a href="chap61.html">61</a>  <a href="chap62.html">62</a>  <a href="chap63.html">63</a>  <a href="chap64.html">64</a>  <a href="chap65.html">65</a>  <a href="chap66.html">66</a>  <a href="chap67.html">67</a>  <a href="chap68.html">68</a>  <a href="chap69.html">69</a>  <a href="chap70.html">70</a>  <a href="chap71.html">71</a>  <a href="chap72.html">72</a>  <a href="chap73.html">73</a>  <a href="chap74.html">74</a>  <a href="chap75.html">75</a>  <a href="chap76.html">76</a>  <a href="chap77.html">77</a>  <a href="chap78.html">78</a>  <a href="chap79.html">79</a>  <a href="chap80.html">80</a>  <a href="chap81.html">81</a>  <a href="chap82.html">82</a>  <a href="chap83.html">83</a>  <a href="chap84.html">84</a>  <a href="chap85.html">85</a>  <a href="chap86.html">86</a>  <a href="chap87.html">87</a>  <a href="chapBib.html">Bib</a>  <a href="chapInd.html">Ind</a>  </div>

<div class="chlinkprevnexttop"> <a href="chap0.html">[Top of Book]</a>   <a href="chap0.html#contents">[Contents]</a>    <a href="chap75.html">[Previous Chapter]</a>    <a href="chap77.html">[Next Chapter]</a>   </div>

<p id="mathjaxlink" class="pcenter"><a href="chap76_mj.html">[MathJax on]</a></p>
<p><a id="X79F76C1E834BFDCC" name="X79F76C1E834BFDCC"></a></p>
<div class="ChapSects"><a href="chap76.html#X79F76C1E834BFDCC">76 <span class="Heading">Using and Developing <strong class="pkg">GAP</strong> Packages</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X82473E4B8756C6CD">76.1 <span class="Heading">Installing a <strong class="pkg">GAP</strong> Package</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X825CBC5B86F8F811">76.2 <span class="Heading">Loading a <strong class="pkg">GAP</strong> Package</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X79B373A77B29D1F5">76.2-1 LoadPackage</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X7E6767B485F23BFC">76.2-2 <span class="Heading">Automatic loading of <strong class="pkg">GAP</strong> packages</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X858E8985840BFA72">76.2-3 SetPackagePath</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X7CD0A2F27D19BA03">76.2-4 ExtendRootDirectories</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X81BFC5C87EE2E02A">76.2-5 ExtendPackageDirectories</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X7D162DDF813D2BBA">76.2-6 DisplayPackageLoadingLog</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X7C6CE28B7E142804">76.3 <span class="Heading">Functions for <strong class="pkg">GAP</strong> Packages</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X870954577B27DCAB">76.3-1 ReadPackage</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X8580DF257E4D7046">76.3-2 TestPackageAvailability</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X7C8724C183E24665">76.3-3 IsPackageLoaded</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X8067348B836BAF37">76.3-4 IsPackageMarkedForLoading</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X866ADD4E814A54F0">76.3-5 TestPackage</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X7B79FEE57DBDBD71">76.3-6 InstalledPackageVersion</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X807D835C7B032D4E">76.3-7 DirectoriesPackageLibrary</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X794508E5811D3BC9">76.3-8 DirectoriesPackagePrograms</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X787DFEB383545A49">76.3-9 CompareVersionNumbers</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X8495E5327D563AC3">76.3-10 DeclareAutoreadableVariables</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X85672DDD7D34D5F0">76.3-11 <span class="Heading">Kernel modules in <strong class="pkg">GAP</strong> packages</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X7D23646086F33A9E">76.3-12 IsKernelExtensionAvailable</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X85F1B83079A11F89">76.3-13 LoadKernelExtension</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X7C99782886B18C77">76.3-14 LoadDynamicModule</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X85C8DE357EE424D8">76.3-15 <span class="Heading">The PackageInfo.g File</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X79767C2482FF6F55">76.3-16 ValidatePackageInfo</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X7D34AC3287611B15">76.3-17 ShowPackageVariables</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X79EA4BD37940AD25">76.3-18 BibEntry</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X79637D9A7B1AD7F7">76.3-19 Cite</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X7EE8E5D97B0F8AFF">76.4 <span class="Heading">Guidelines for Writing a <strong class="pkg">GAP</strong> Package</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X8383876782480702">76.5 <span class="Heading">Structure of a <strong class="pkg">GAP</strong> Package</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X84164AA2859A195F">76.6 <span class="Heading">Writing Documentation and Tools Needed</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X79AB306684AC8E7A">76.7 <span class="Heading">An Example of a <strong class="pkg">GAP</strong> Package</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X7A61B1AE7D632E01">76.8 <span class="Heading">File Structure</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X7A09C63685065B01">76.9 <span class="Heading">Creating the PackageInfo.g File</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X7DEACD9786DE29F1">76.10 <span class="Heading">Functions and Variables and Choices of Their Names</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X7928799186F9B2FE">76.11 <span class="Heading">Package Dependencies (Requesting one <strong class="pkg">GAP</strong> Package from within Another)</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X783A5F3D87F9AF78">76.12 <span class="Heading">Extensions Provided by a Package</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X7A7835A5797AF766">76.13 <span class="Heading">Declaration and Implementation Part of a Package</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X7D7F236A78106358">76.14 <span class="Heading">Autoreadable Variables</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X7C8CCF057806EFD0">76.15 <span class="Heading">Standalone Programs in a <strong class="pkg">GAP</strong> Package</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X7CD9ED5C86725ACF">76.15-1 <span class="Heading">Installation of <strong class="pkg">GAP</strong> Package Binaries</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X7E4F39867CCC6026">76.15-2 <span class="Heading">Test for the Existence of GAP Package Binaries</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X8438685184FCEFEC">76.15-3 <span class="Heading">Calling of and Communication with External Binaries</span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X78969BA778DDE385">76.16 <span class="Heading">Having an InfoClass</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X784E0A5A7DB88332">76.17 <span class="Heading">The Banner</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X8180BCDA82587F41">76.18 <span class="Heading">Version Numbers</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X8559D1FF7C9B7D14">76.19 <span class="Heading">Testing a <strong class="pkg">GAP</strong> package</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X85CA2F547CF87666">76.19-1 <span class="Heading">Tests files for a GAP package</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X84CD542B7C4C73A0">76.19-2 <span class="Heading">Testing <strong class="pkg">GAP</strong> package loading</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X80A0D21D78CF8494">76.19-3 LoadAllPackages</a></span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X7C90C8B87BF6EF0B">76.19-4 <span class="Heading">Testing a <strong class="pkg">GAP</strong> package with the <strong class="pkg">GAP</strong> standard test suite</span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X81B52B657CA75BDA">76.20 <span class="Heading">Access to the <strong class="pkg">GAP</strong> Development Version</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X836CDF8F7A846A1C">76.21 <span class="Heading">Version control and continuous integration for <strong class="pkg">GAP</strong> packages</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X82EBCBC5829B6001">76.22 <span class="Heading">Selecting a license for a <strong class="pkg">GAP</strong> Package</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X8074AAAE79911BE5">76.23 <span class="Heading">Releasing a GAP Package</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X8232CC1385C4B1DD">76.24 <span class="Heading">The homepage of a Package</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X796D7F7583E845BE">76.25 <span class="Heading">Some things to keep in mind</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap76.html#X82CE0A518440CCBB">76.26 <span class="Heading">Package release checklists</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X80E3926A7CF8B6DC">76.26-1 <span class="Heading">Checklist for releasing a new package</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">  </span><a href="chap76.html#X820D4B207A41AEA6">76.26-2 <span class="Heading">Checklist for upgrading the package for the next major release of <strong class="pkg">GAP</strong></span></a>
</span>
</div></div>
</div>

<h3>76 <span class="Heading">Using and Developing <strong class="pkg">GAP</strong> Packages</span></h3>

<p>The functionality of <strong class="pkg">GAP</strong> can be extended by loading <strong class="pkg">GAP</strong> packages. The <strong class="pkg">GAP</strong> distribution already contains all currently redistributed <strong class="pkg">GAP</strong> packages in the <code class="file">gap-4.15.1/pkg</code> directory.</p>

<p><strong class="pkg">GAP</strong> packages are written by (groups of) <strong class="pkg">GAP</strong> users who may not necessarily be members of the <strong class="pkg">GAP</strong> developer team. The responsibility and copyright of a <strong class="pkg">GAP</strong> package remains with the original author(s).</p>

<p><strong class="pkg">GAP</strong> packages have their own documentation which is smoothly integrated into the <strong class="pkg">GAP</strong> help system. (When <strong class="pkg">GAP</strong> is started, <code class="code">LoadPackageDocumentation</code> is called for all packages.)</p>

<p>All <strong class="pkg">GAP</strong> users who develop new code are invited to share the results of their efforts with other <strong class="pkg">GAP</strong> users by making the code and its documentation available in form of a package. Guidance on how to do this is available from the <strong class="pkg">GAP</strong> website (<span class="URL"><a href="https://www.gap-system.org">https://www.gap-system.org</a></span>) and in the <strong class="pkg">GAP</strong> package <strong class="pkg">Example</strong> (see <span class="URL"><a href="https://www.gap-system.org/Packages/example.html">https://www.gap-system.org/Packages/example.html</a></span>).</p>

<p>The <strong class="pkg">GAP</strong> development team will assist in making any new package suitable for distribution with <strong class="pkg">GAP</strong>. It is also possible to submit a package to a formal refereeing process.</p>

<p>In this chapter we first describe how to use existing packages, and then provide guidelines for writing a <strong class="pkg">GAP</strong> package.</p>

<p><a id="X82473E4B8756C6CD" name="X82473E4B8756C6CD"></a></p>

<h4>76.1 <span class="Heading">Installing a <strong class="pkg">GAP</strong> Package</span></h4>

<p>Before a package can be used it must be installed. A standard distribution of <strong class="pkg">GAP</strong> already contains all the packages currently redistributed with <strong class="pkg">GAP</strong>. This set of packages has been checked for compatibility with the system and with each other during release preparation. Most of the packages can be used immediately, but some of them may require further installation steps (see below).</p>

<p>Also, since <strong class="pkg">GAP</strong> packages are released independently of the main <strong class="pkg">GAP</strong> system, it may sometimes be useful to upgrade or install new packages between upgrades of your <strong class="pkg">GAP</strong> installation, e.g. if a new version of a package adds new capabilities or bug fixes that you need.</p>

<p>A package consists of a collection of files within a single directory that must be a subdirectory of the <code class="file">pkg</code> directory in one of the <strong class="pkg">GAP</strong> root directories (see <a href="chap9.html#X7A4973627A5DB27D"><span class="RefLink">9.2</span></a>). If you don't have access to the pkg directory in your main GAP installation you can add private root directories as explained in section 9.2.



<p>Whenever you download or clone an archive of a <strong class="pkg">GAP</strong> package, it will contain a <code class="file">README</code> file (or <code class="file">README.md</code> etc.) that explains how it should be installed. Some packages just consist of <strong class="pkg">GAP</strong> code and the installation is done by unpacking the archive in one of the places described above. There are also packages that need further installation steps, such as compilation or installing additional software to satisfy their dependencies. If there are some external programs which have to be compiled, this is often done by executing <code class="code">./configure; make</code> inside the unpacked package directory (but check the individual <code class="file">README</code> files).</p>

<p>Most of the packages that require compilation can be compiled in a single step by changing to the <code class="file">pkg</code> directory of your <strong class="pkg">GAP</strong> installation and calling the <code class="code">../bin/BuildPackages.sh</code> script.</p>

<p>Note that if you use Windows you may not be able to use some or all external binaries.</p>

<p><a id="X825CBC5B86F8F811" name="X825CBC5B86F8F811"></a></p>

<h4>76.2 <span class="Heading">Loading a <strong class="pkg">GAP</strong> Package</span></h4>

<p>If a package is not already loaded, it may be loaded using the function <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>).</p>

<p>Some <strong class="pkg">GAP</strong> packages are prepared for automatic loading, that is they will be loaded automatically when <strong class="pkg">GAP</strong> starts (see <a href="chap76.html#X7E6767B485F23BFC"><span class="RefLink">76.2-2</span></a>).</p>

<p><a id="X79B373A77B29D1F5" name="X79B373A77B29D1F5"></a></p>

<h5>76.2-1 LoadPackage</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ LoadPackage</code>( <var class="Arg">name</var>[, <var class="Arg">version</var>][, <var class="Arg">banner</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>loads the <strong class="pkg">GAP</strong> package with name <var class="Arg">name</var>.</p>

<p>As an example, the following loads the <strong class="pkg">GAP</strong> package <strong class="pkg">SONATA</strong> (case insensitive) which provides methods for the construction and analysis of finite nearrings:</p>


<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">LoadPackage("sonata");</span>
... some more lines with package banner(s) ...
true
</pre></div>

<p>The package name is case insensitive and may be appropriately abbreviated. At the time of writing, for example, <code class="code">LoadPackage("semi");</code> will load the <strong class="pkg">Semigroups</strong> package, and <code class="code">LoadPackage("js");</code> will load the <strong class="pkg">json</strong> package. If the abbreviation cannot be uniquely completed, a list of available completions will be offered, and <code class="func">LoadPackage</code> returns <code class="keyw">fail</code>. Thus the names of <em>all</em> installed packages can be shown by calling <code class="code">LoadPackage("");</code>.</p>

<p>When the optional argument string <var class="Arg">version</var> is present, the package will only be loaded in a version number equal to or greater than <var class="Arg">version</var> (see <code class="func">CompareVersionNumbers</code> (<a href="chap76.html#X787DFEB383545A49"><span class="RefLink">76.3-9</span></a>)). If the first character of <var class="Arg">version</var> is <code class="code">=</code> then only that version will be loaded.</p>

<p><code class="func">LoadPackage</code> will return <code class="keyw">true</code> if the package has been successfully loaded, and will return <code class="keyw">fail</code> if the package could not be loaded. The latter may be the case if the package is not installed, if necessary binaries have not been compiled, or if the version number of the available version is too small. If the package cannot be loaded, <code class="func">TestPackageAvailability</code> (<a href="chap76.html#X8580DF257E4D7046"><span class="RefLink">76.3-2</span></a>) can be used to find the reasons. Also, <code class="func">DisplayPackageLoadingLog</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-6</span></a>) can be used to find out more about the failure. To see the problems directly, one can change the verbosity using the user preference <code class="code">InfoPackageLoadingLevel</code>, see <code class="func">InfoPackageLoading</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-6</span></a>) for details.</p>

<p>If the package <var class="Arg">name</var> has already been loaded in a version number equal to or greater than <var class="Arg">version</var>, <code class="func">LoadPackage</code> returns <code class="keyw">true</code> without doing anything else.</p>

<p>If the optional argument <var class="Arg">banner</var> is present then it must be either <code class="keyw">true</code> or <code class="keyw">false</code>; in the latter case, the effect is that no package banner is printed.</p>

<p>After a package has been loaded, all its code becomes available to use with the rest of the <strong class="pkg">GAP</strong> library.</p>

<p><a id="X7E6767B485F23BFC" name="X7E6767B485F23BFC"></a></p>

<h5>76.2-2 <span class="Heading">Automatic loading of <strong class="pkg">GAP</strong> packages</span></h5>

<p>When <strong class="pkg">GAP</strong> is started some packages are loaded automatically, and these belong to two categories. The first are those packages which are needed to start <strong class="pkg">GAP</strong> (at the present time, the only such package is <strong class="pkg">GAPDoc</strong>). Their list is contained in <code class="code">GAPInfo.Dependencies.NeededOtherPackages</code>. The second are packages which are loaded during <strong class="pkg">GAP</strong> startup by default. The latter list may be obtained by calling <code class="code">UserPreference("PackagesToLoad")</code> and is customisable as described in Section <span class="RefLink">Reference: Configuring User preferences</span>.</p>

<p>While <strong class="pkg">GAP</strong> will not start if any of the packages from the former group is missing, loading of the packages from the latter group may be suppressed by using the <code class="code">-A</code> command line option (see <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>).</p>

<p>If for some reason you don't want certain packages to be automatically loaded, GAP provides three levels for disabling autoloading.



<p>The autoloading of specific packages can be overwritten <em>for the whole <strong class="pkg">GAP</strong> installation</em> by putting a file <code class="file">NOAUTO</code> into a <code class="file">pkg</code> directory that contains lines with the names of packages which should not be automatically loaded.</p>

<p>Furthermore, <em>individual users</em> can disable the autoloading of specific packages by putting the names of these packages into the list that is assigned to the user preference <q>ExcludeFromAutoload</q>, for example in the user's gap.ini file (see 3.2-1).



<p>Using the <code class="code">-A</code> command line option when starting <strong class="pkg">GAP</strong> (see <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>), automatic loading of packages is switched off <em>for this <strong class="pkg">GAP</strong> session</em>.</p>

<p>In any of the above three cases, the packages listed in <code class="code">GAPInfo.Dependencies.NeededOtherPackages</code> are still loaded automatically, and an error is signalled if any of these packages is unavailable.</p>

<p>See <code class="func">SetPackagePath</code> (<a href="chap76.html#X858E8985840BFA72"><span class="RefLink">76.2-3</span></a>) for a way to force the loading of a prescribed package version. See also <code class="func">ExtendRootDirectories</code> (<a href="chap76.html#X7CD0A2F27D19BA03"><span class="RefLink">76.2-4</span></a>) and <code class="func">ExtendPackageDirectories</code> (<a href="chap76.html#X81BFC5C87EE2E02A"><span class="RefLink">76.2-5</span></a>) for methods of adding directories containing packages <em>after</em> <strong class="pkg">GAP</strong> has been started.</p>

<p><a id="X858E8985840BFA72" name="X858E8985840BFA72"></a></p>

<h5>76.2-3 SetPackagePath</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ SetPackagePath</code>( <var class="Arg">pkgname</var>, <var class="Arg">pkgpath</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function can be used to force <strong class="pkg">GAP</strong> to load a particular version of a package, even though newer versions of the package are available.</p>

<p>Let <var class="Arg">pkgname</var> and <var class="Arg">pkgpath</var> be strings denoting the name of a <strong class="pkg">GAP</strong> package and the path to a directory where a version of this package can be found (i. e., calling <code class="func">Directory</code> (<a href="chap9.html#X86A71E927EEC7EAD"><span class="RefLink">9.4-2</span></a>) with the argument <var class="Arg">pkgpath</var> will yield a directory that contains the file <code class="file">PackageInfo.g</code> of the package).</p>

<p>If the package <var class="Arg">pkgname</var> is already loaded with an installation path different from <var class="Arg">pkgpath</var> then <code class="func">SetPackagePath</code> signals an error. If the package <var class="Arg">pkgname</var> is not yet loaded then <code class="func">SetPackagePath</code> erases the information about available versions of the package <var class="Arg">pkgname</var>, and stores the record that is contained in the <code class="file">PackageInfo.g</code> file at <var class="Arg">pkgpath</var> instead, such that only the version installed at <var class="Arg">pkgpath</var> can be loaded with <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>).</p>

<p>One should call <code class="func">SetPackagePath</code> immediately before loading the package in question. Note that calling <code class="func">ExtendPackageDirectories</code> (<a href="chap76.html#X81BFC5C87EE2E02A"><span class="RefLink">76.2-5</span></a>) or <code class="func">ExtendRootDirectories</code> (<a href="chap76.html#X7CD0A2F27D19BA03"><span class="RefLink">76.2-4</span></a>) may change the available versions of the package <var class="Arg">pkgname</var>.</p>

<p><a id="X7CD0A2F27D19BA03" name="X7CD0A2F27D19BA03"></a></p>

<h5>76.2-4 ExtendRootDirectories</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ExtendRootDirectories</code>( <var class="Arg">paths</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Let <var class="Arg">paths</var> be a list of strings that denote paths to intended <strong class="pkg">GAP</strong> root directories (see <a href="chap9.html#X7A4973627A5DB27D"><span class="RefLink">9.2</span></a>). The function <code class="func">ExtendRootDirectories</code> adds these paths to the global list <code class="code">GAPInfo.RootPaths</code> and calls the initialization of available <strong class="pkg">GAP</strong> packages, such that later calls to <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>) will find the <strong class="pkg">GAP</strong> packages that are contained in <code class="file">pkg</code> subdirectories of the directories given by <var class="Arg">paths</var>.</p>

<p>Note that the purpose of this function is to make <strong class="pkg">GAP</strong> packages in the given directories available. It cannot be used to influence the start of <strong class="pkg">GAP</strong>, because the <strong class="pkg">GAP</strong> library is loaded before <code class="func">ExtendRootDirectories</code> can be called (and because <code class="code">GAPInfo.RootPaths</code> is not used for reading the <strong class="pkg">GAP</strong> library).</p>

<p><a id="X81BFC5C87EE2E02A" name="X81BFC5C87EE2E02A"></a></p>

<h5>76.2-5 ExtendPackageDirectories</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ExtendPackageDirectories</code>( <var class="Arg">paths</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Let <var class="Arg">paths</var> be a list of strings that denote paths to intended <strong class="pkg">GAP</strong> package directories (see <a href="chap9.html#X8223D52E78AF4420"><span class="RefLink">9.3</span></a>). The function <code class="func">ExtendPackageDirectories</code> adds these paths to the global list <code class="code">GAPInfo.PackageDirectories</code> and calls the initialization of available <strong class="pkg">GAP</strong> packages, such that later calls to <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>) will find the <strong class="pkg">GAP</strong> packages that are contained in the directories given by <var class="Arg">paths</var>.</p>

<p><a id="X7D162DDF813D2BBA" name="X7D162DDF813D2BBA"></a></p>

<h5>76.2-6 DisplayPackageLoadingLog</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ DisplayPackageLoadingLog</code>( [<var class="Arg">severity</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InfoPackageLoading</code></td><td class="tdright">( info class )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ PACKAGE_ERROR</code></td><td class="tdright">( global variable )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ PACKAGE_WARNING</code></td><td class="tdright">( global variable )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ PACKAGE_INFO</code></td><td class="tdright">( global variable )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ PACKAGE_DEBUG</code></td><td class="tdright">( global variable )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ LogPackageLoadingMessage</code>( <var class="Arg">severity</var>, <var class="Arg">message</var>[, <var class="Arg">name</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Whenever <strong class="pkg">GAP</strong> considers loading a package, log messages are collected in a global list. The messages for the current <strong class="pkg">GAP</strong> session can be displayed with <code class="func">DisplayPackageLoadingLog</code>. To each message, a <q>severity</q> is assigned, which is one of <code class="func">PACKAGE_ERROR</code>, <code class="func">PACKAGE_WARNING</code>, <code class="func">PACKAGE_INFO</code>, <code class="func">PACKAGE_DEBUG</code>, in increasing order. The function <code class="func">DisplayPackageLoadingLog</code> shows only the messages whose severity is at most <var class="Arg">severity</var>, the default for <var class="Arg">severity</var> is <code class="func">PACKAGE_WARNING</code>.</p>

<p>The intended meaning of the severity levels is as follows.</p>


<dl>
<dt><strong class="Mark">PACKAGE_ERROR</strong></dt>
<dd><p>should be used whenever <strong class="pkg">GAP</strong> will run into an error during package loading, where the reason of the error shall be documented in the global list.</p>

</dd>
<dt><strong class="Mark">PACKAGE_WARNING</strong></dt>
<dd><p>should be used whenever <strong class="pkg">GAP</strong> has detected a reason why a package cannot be loaded, and where the message describes how to solve this problem, for example if a package binary is missing.</p>

</dd>
<dt><strong class="Mark">PACKAGE_INFO</strong></dt>
<dd><p>should be used whenever <strong class="pkg">GAP</strong> has detected a reason why a package cannot be loaded, and where it is not clear how to solve this problem, for example if the package is not compatible with other installed packages.</p>

</dd>
<dt><strong class="Mark">PACKAGE_DEBUG</strong></dt>
<dd><p>should be used for other messages reporting what <strong class="pkg">GAP</strong> does when it loads packages (checking dependencies, reading files, etc.). One purpose is to record in which order packages have been considered for loading or have actually been loaded.</p>

</dd>
</dl>
<p>The log messages are created either by the functions of <strong class="pkg">GAP</strong>'s package loading mechanism or in the code of your package, for example in the AvailabilityTest function of the package's <code class="file">PackageInfo.g</code> file (see <a href="chap76.html#X85C8DE357EE424D8"><span class="RefLink">76.3-15</span></a>), using <code class="func">LogPackageLoadingMessage</code>. The arguments of this function are <var class="Arg">severity</var> (which must be one of the above severity levels), <var class="Arg">message</var> (which must be either a string or a list of strings), and optionally <var class="Arg">name</var> (which must be the name of the package to which the message belongs). The argument <var class="Arg">name</var> is not needed if the function is called from a call of a package's AvailabilityTest function (see 76.3-15) or is called from a package file that is read from init.g or read.g; in these cases, the name of the current package (stored in the record GAPInfo.PackageCurrent) is taken. According to the above list, the severity argument of LogPackageLoadingMessage calls in a package's <code class="code">AvailabilityTest</code> function is either <code class="func">PACKAGE_WARNING</code> or <code class="func">PACKAGE_INFO</code>.</p>

<p>If you want to see the log messages already during the package loading process, you can set the level of the info class <code class="func">InfoPackageLoading</code> to one of the severity values listed above; afterwards the messages with at most this severity are shown immediately when they arise. In order to make this work already for autoloaded packages, you can call <code class="code">SetUserPreference("InfoPackageLoadingLevel", <var class="Arg">lev</var>);</code> to set the desired severity level <var class="Arg">lev</var>. This can for example be done in your <code class="file">gap.ini</code> file, see Section <a href="chap3.html#X87DF11C885E73583"><span class="RefLink">3.2-1</span></a>.</p>

<p><a id="X7C6CE28B7E142804" name="X7C6CE28B7E142804"></a></p>

<h4>76.3 <span class="Heading">Functions for <strong class="pkg">GAP</strong> Packages</span></h4>

<p>The following functions are mainly used in files contained in a package and not by users of a package. They are needed to organise reading package files into <strong class="pkg">GAP</strong> in the right order, performing maintenance tasks like building documentation and running package tests, checking package dependencies, etc. You will find further information about their use in Section <a href="chap76.html#X7EE8E5D97B0F8AFF"><span class="RefLink">76.4</span></a> and subsequent sections.</p>

<p><a id="X870954577B27DCAB" name="X870954577B27DCAB"></a></p>

<h5>76.3-1 ReadPackage</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ReadPackage</code>( [<var class="Arg">name</var>, ]<var class="Arg">file</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ RereadPackage</code>( [<var class="Arg">name</var>, ]<var class="Arg">file</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Called with two strings <var class="Arg">name</var> and <var class="Arg">file</var>, <code class="func">ReadPackage</code> reads the file <var class="Arg">file</var> of the <strong class="pkg">GAP</strong> package <var class="Arg">name</var>, where <var class="Arg">file</var> is given as a path relative to the home directory of <var class="Arg">name</var>. Note that <var class="Arg">file</var> is read in the namespace of the package, see Section <a href="chap4.html#X7DF8774F7D542298"><span class="RefLink">4.10</span></a> for details.</p>

<p>If only one argument <var class="Arg">file</var> is given, this should be the path of a file relative to the <code class="file">pkg</code> subdirectory of <strong class="pkg">GAP</strong> root paths (see <a href="chap9.html#X7A4973627A5DB27D"><span class="RefLink">9.2</span></a>). Note that in this case, the package name is assumed to be equal to the first part of <var class="Arg">file</var>, <em>so the one argument form is not recommended</em>.</p>

<p>The absolute path is determined as follows. If the package in question has already been loaded then the file in the directory of the loaded version is read. If the package is available but not yet loaded then the directory given by <code class="func">TestPackageAvailability</code> (<a href="chap76.html#X8580DF257E4D7046"><span class="RefLink">76.3-2</span></a>) is used, without prescribed version number. (Note that the <code class="func">ReadPackage</code> call does <em>not</em> force the package to be loaded.)</p>

<p>If the file is readable then <code class="keyw">true</code> is returned, otherwise a warning is displayed (for <code class="func">ReadPackage</code>) or <code class="keyw">false</code> is returned (for <code class="func">RereadPackage</code>).</p>

<p>Each of <var class="Arg">name</var> and <var class="Arg">file</var> should be a string. The <var class="Arg">name</var> argument is case insensitive.</p>

<p><code class="func">RereadPackage</code> does the same as <code class="func">ReadPackage</code>, except that also read-only global variables are overwritten (cf. <code class="func">Reread</code> (<a href="chap9.html#X79EE267A7FAF28A6"><span class="RefLink">9.8-10</span></a>)).</p>

<p><a id="X8580DF257E4D7046" name="X8580DF257E4D7046"></a></p>

<h5>76.3-2 TestPackageAvailability</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TestPackageAvailability</code>( <var class="Arg">name</var>[, <var class="Arg">version</var>][, <var class="Arg">checkall</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>For strings <var class="Arg">name</var> and <var class="Arg">version</var>, this function tests whether the <strong class="pkg">GAP</strong> package <var class="Arg">name</var> is available for loading in a version that is at least <var class="Arg">version</var>, or equal to <var class="Arg">version</var> if the first character of <var class="Arg">version</var> is <code class="code">=</code> (see <code class="func">CompareVersionNumbers</code> (<a href="chap76.html#X787DFEB383545A49"><span class="RefLink">76.3-9</span></a>) for further details about version numbers).</p>

<p>The result is <code class="keyw">true</code> if the package is already loaded, <code class="keyw">fail</code> if it is not available, and the string denoting the <strong class="pkg">GAP</strong> root path where the package resides if it is available, but not yet loaded. So the package <var class="Arg">name</var> is available if the result of <code class="func">TestPackageAvailability</code> is not equal to <code class="keyw">fail</code>.</p>

<p>If the optional argument <var class="Arg">checkall</var> is <code class="keyw">true</code> then all dependencies are checked, even if some have turned out to be not satisfied. This is useful when one is interested in the reasons why the package <var class="Arg">name</var> cannot be loaded. In this situation, calling first <code class="func">TestPackageAvailability</code> and then <code class="func">DisplayPackageLoadingLog</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-6</span></a>) with argument <code class="func">PACKAGE_INFO</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-6</span></a>) will give an overview of these reasons.</p>

<p>You should <em>not</em> call <code class="func">TestPackageAvailability</code> in the test function of a package (the value of the component <code class="code">AvailabilityTest</code> in the <code class="file">PackageInfo.g</code> file of the package, see <a href="chap76.html#X85C8DE357EE424D8"><span class="RefLink">76.3-15</span></a>), because <code class="func">TestPackageAvailability</code> calls this test function.</p>

<p>The argument <var class="Arg">name</var> is case insensitive.</p>

<p><a id="X7C8724C183E24665" name="X7C8724C183E24665"></a></p>

<h5>76.3-3 IsPackageLoaded</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ IsPackageLoaded</code>( <var class="Arg">name</var>[, <var class="Arg">version</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>For strings <var class="Arg">name</var> and <var class="Arg">version</var>, this function tests whether the <strong class="pkg">GAP</strong> package <var class="Arg">name</var> is already loaded in a version that is at least <var class="Arg">version</var>, or equal to <var class="Arg">version</var> if the first character of <var class="Arg">version</var> is <code class="code">=</code> (see <code class="func">CompareVersionNumbers</code> (<a href="chap76.html#X787DFEB383545A49"><span class="RefLink">76.3-9</span></a>) for further details about version numbers).</p>

<p>The result is <code class="keyw">true</code> if the package is already loaded, <code class="keyw">false</code> otherwise.</p>

<p><a id="X8067348B836BAF37" name="X8067348B836BAF37"></a></p>

<h5>76.3-4 IsPackageMarkedForLoading</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ IsPackageMarkedForLoading</code>( <var class="Arg">name</var>, <var class="Arg">version</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function can be used in the code of a package <span class="SimpleMath">A</span> for testing whether the package <var class="Arg">name</var> in version <var class="Arg">version</var> will be loaded after the <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>) call for the package <span class="SimpleMath">A</span> has been executed. This means that the package <var class="Arg">name</var> had been loaded before, or has been (directly or indirectly) requested as a needed or suggested package of the package <span class="SimpleMath">A</span> or of a package whose loading requested that <span class="SimpleMath">A</span> was loaded.</p>

<p><a id="X866ADD4E814A54F0" name="X866ADD4E814A54F0"></a></p>

<h5>76.3-5 TestPackage</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TestPackage</code>( <var class="Arg">pkgname</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>It is recommended that a <strong class="pkg">GAP</strong> package specifies a standard test in its <code class="file">PackageInfo.g</code> file. If <var class="Arg">pkgname</var> is a string with the name of a <strong class="pkg">GAP</strong> package, then <code class="code">TestPackage(pkgname)</code> will check if this package is loadable and has the standard test, and will run this test in the current <strong class="pkg">GAP</strong> session.</p>

<p>The output of the test depends on the particular package, and it also may depend on the current <strong class="pkg">GAP</strong> session (loaded packages, state of the random sources, defined global variables etc.).</p>

<p><a id="X7B79FEE57DBDBD71" name="X7B79FEE57DBDBD71"></a></p>

<h5>76.3-6 InstalledPackageVersion</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InstalledPackageVersion</code>( <var class="Arg">name</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>If the <strong class="pkg">GAP</strong> package with name <var class="Arg">name</var> has already been loaded then <code class="func">InstalledPackageVersion</code> returns the string denoting the version number of this version of the package. If the package is available but has not yet been loaded then the version number string for that version of the package that currently would be loaded. (Note that loading <em>another</em> package might force loading another version of the package <var class="Arg">name</var>, so the result of <code class="func">InstalledPackageVersion</code> will be different afterwards.) If the package is not available then <code class="keyw">fail</code> is returned.</p>

<p>The argument <var class="Arg">name</var> is case insensitive.</p>

<p><a id="X807D835C7B032D4E" name="X807D835C7B032D4E"></a></p>

<h5>76.3-7 DirectoriesPackageLibrary</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ DirectoriesPackageLibrary</code>( <var class="Arg">name</var>[, <var class="Arg">path</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>takes the string <var class="Arg">name</var>, a name of a <strong class="pkg">GAP</strong> package, and returns a list that is either empty or contains one directory object <code class="code">dir</code> that describes the place where the library functions of this <strong class="pkg">GAP</strong> package should be located.</p>

<p>In the latter case, <code class="code">dir</code> is the <var class="Arg">path</var> subdirectory of a directory where the package <var class="Arg">name</var> is installed, where the default for <var class="Arg">path</var> is <code class="code">"lib"</code>, and where the package directory belongs to the version of <var class="Arg">name</var> that is already loaded or is currently going to be loaded or would be the first version <strong class="pkg">GAP</strong> would try to load if no other version is explicitly prescribed. (If the package <var class="Arg">name</var> is not yet loaded then we cannot guarantee that the directory belongs to a version that really can be loaded.)</p>

<p>Note that <code class="func">DirectoriesPackageLibrary</code> is likely to be called in the <code class="code">AvailabilityTest</code> function in the package's PackageInfo.g file (see 76.3-15).



<p>As an example, the following returns a directory object for the library functions of the <strong class="pkg">GAP</strong> package <strong class="pkg">Example</strong>:</p>


<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">DirectoriesPackageLibrary( "Example", "gap" );</span>
[ dir("/home/werner/gap/4.0/pkg/example/gap/") ]
</pre></div>

<p>Observe that we needed the second argument <code class="code">"gap"</code> here, since <strong class="pkg">Example</strong>'s library functions are in the subdirectory gap rather than lib.



<p>In order to find a subdirectory deeper than one level in a package directory, the second argument is again necessary whether or not the desired subdirectory relative to the package's directory begins with lib. The directories in path should be separated by / (even on systems, like Windows, which use \ as the directory separator). For example, suppose there is a package somepackage with a subdirectory m11 in the directory data, then we might expect the following:




<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">DirectoriesPackageLibrary( "somepackage", "data/m11" );</span>
[ dir("/home/werner/gap/4.0/pkg/somepackage/data/m11") ]
</pre></div>

<p><a id="X794508E5811D3BC9" name="X794508E5811D3BC9"></a></p>

<h5>76.3-8 DirectoriesPackagePrograms</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ DirectoriesPackagePrograms</code>( <var class="Arg">name</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>returns a list that is either empty or contains one directory object <code class="code">dir</code> that describes the place where external binaries of the <strong class="pkg">GAP</strong> package <var class="Arg">name</var> should be located.</p>

<p>In the latter case, <code class="code">dir</code> is the <code class="code">bin/</code><var class="Arg">architecture</var> subdirectory of a directory where the package <var class="Arg">name</var> is installed, where <var class="Arg">architecture</var> is the architecture on which <strong class="pkg">GAP</strong> has been compiled (this can be accessed as <code class="code">GAPInfo.Architecture</code>, see <code class="func">GAPInfo</code> (<a href="chap3.html#X8354754E7935F935"><span class="RefLink">3.5-1</span></a>)), and where the package directory belongs to the version of <var class="Arg">name</var> that is already loaded or is currently going to be loaded or would be the first version <strong class="pkg">GAP</strong> would try to load if no other version is explicitly prescribed. (If the package <var class="Arg">name</var> is not yet loaded then we cannot guarantee that the directory belongs to a version that really can be loaded.)</p>

<p>Note that <code class="func">DirectoriesPackagePrograms</code> is likely to be called in the <code class="code">AvailabilityTest</code> function in the package's PackageInfo.g file (see 76.3-15).




<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">DirectoriesPackagePrograms( "nq" );</span>
[ dir("/home/gap/4.0/pkg/nq/bin/x86_64-pc-linux-gnu-default64-kv3/") ]
</pre></div>

<p><a id="X787DFEB383545A49" name="X787DFEB383545A49"></a></p>

<h5>76.3-9 CompareVersionNumbers</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ CompareVersionNumbers</code>( <var class="Arg">supplied</var>, <var class="Arg">required</var>[, <var class="Arg">"equal"</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>A version number is a string which contains nonnegative integers separated by non-numeric characters. Examples of valid version numbers are for example:</p>


<div class="example"><pre>
"1.0"   "3.141.59"  "2-7-8.3" "5 release 2 patchlevel 666"
</pre></div>

<p><code class="func">CompareVersionNumbers</code> compares two version numbers, given as strings. They are split at non-digit characters, the resulting integer lists are compared lexicographically. The routine tests whether <var class="Arg">supplied</var> is at least as large as <var class="Arg">required</var>, and returns <code class="keyw">true</code> or <code class="keyw">false</code> accordingly. A version number ending in <code class="code">dev</code> is considered to be infinite.</p>

<p><a id="X8495E5327D563AC3" name="X8495E5327D563AC3"></a></p>

<h5>76.3-10 DeclareAutoreadableVariables</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ DeclareAutoreadableVariables</code>( <var class="Arg">pkgname</var>, <var class="Arg">filename</var>, <var class="Arg">varlist</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Let <var class="Arg">pkgname</var> be the name of a package, let <var class="Arg">filename</var> be the name of a file relative to the home directory of this package, and let <var class="Arg">varlist</var> be a list of strings that are the names of global variables which get bound when the file is read. <code class="func">DeclareAutoreadableVariables</code> notifies the names in <var class="Arg">varlist</var> such that the first attempt to access one of the variables causes the file to be read.</p>

<p><a id="X85672DDD7D34D5F0" name="X85672DDD7D34D5F0"></a></p>

<h5>76.3-11 <span class="Heading">Kernel modules in <strong class="pkg">GAP</strong> packages</span></h5>

<p>If the package has a kernel module, then it can be compiled using the <strong class="pkg">gac</strong> script. A kernel module is implemented in C and follows certain conventions to comply with the <strong class="pkg">GAP</strong> kernel interface, which we plan to document later. In the meantime, we advice to get in touch with <strong class="pkg">GAP</strong> developers if you plan to develop such a package.</p>

<p>To use the <strong class="pkg">gac</strong> script to produce dynamically loadable modules, call it with the <code class="code">-d</code> option, for example:</p>


<div class="example"><pre>
$ gap4/gac -d test.c
</pre></div>

<p>This will produce a file <code class="file">test.so</code>, which then can be loaded into <strong class="pkg">GAP</strong> with <code class="func">LoadKernelExtension</code> (<a href="chap76.html#X85F1B83079A11F89"><span class="RefLink">76.3-13</span></a>). If the kernel module is required for the package to work, then its <code class="file">PackageInfo.g</code> should define a <code class="code">AvailabilityTest</code> which calls <code class="func">IsKernelExtensionAvailable</code> (<a href="chap76.html#X7D23646086F33A9E"><span class="RefLink">76.3-12</span></a>), see <a href="chap76.html#X7E4F39867CCC6026"><span class="RefLink">76.15-2</span></a> for details.</p>

<p>Note that before <strong class="pkg">GAP</strong> 4.12, <code class="func">LoadDynamicModule</code> (<a href="chap76.html#X7C99782886B18C77"><span class="RefLink">76.3-14</span></a>) was used for this. It is still available and in fact <code class="func">LoadKernelExtension</code> (<a href="chap76.html#X85F1B83079A11F89"><span class="RefLink">76.3-13</span></a>) call it; but the latter provides a higher level abstraction and is more convenient to use.</p>

<p><a id="X7D23646086F33A9E" name="X7D23646086F33A9E"></a></p>

<h5>76.3-12 IsKernelExtensionAvailable</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ IsKernelExtensionAvailable</code>( <var class="Arg">pkgname</var>[, <var class="Arg">modname</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>For use by packages: Search for a loadable kernel module inside package <var class="Arg">pkgname</var> with name <var class="Arg">modname</var> and return <code class="keyw">true</code> if found, otherwise <code class="keyw">false</code>. If <var class="Arg">modname</var> is omitted, then <var class="Arg">pkgname</var> is used instead. Note that package names are case insensitive, but <var class="Arg">modname</var> is not.</p>

<p>This function first appeared in GAP 4.12. It is typically called in the <code class="code">AvailabilityTest</code> function of a package (see <a href="chap76.html#X7E4F39867CCC6026"><span class="RefLink">76.15-2</span></a>).</p>


<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">IsKernelExtensionAvailable("myPackageWithKernelExtension");</span>
true
</pre></div>

<p><a id="X85F1B83079A11F89" name="X85F1B83079A11F89"></a></p>

<h5>76.3-13 LoadKernelExtension</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ LoadKernelExtension</code>( <var class="Arg">pkgname</var>[, <var class="Arg">modname</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>For use by packages: Search for a loadable kernel module inside package <var class="Arg">pkgname</var> with name <var class="Arg">modname</var>, and load it if found. If <var class="Arg">modname</var> is omitted, then <var class="Arg">pkgname</var> is used instead. Note that package names are case insensitive, but <var class="Arg">modname</var> is not.</p>

<p>This function first appeared in GAP 4.12. It is typically called in the <code class="file">init.g</code> file of a package.</p>

<p>Previously, packages with a kernel module typically used code like this:</p>


<div class="example"><pre>
path := Filename(DirectoriesPackagePrograms("SomePackage"), "SomePackage.so");
if path <> fail then
  LoadDynamicModule(path);
fi;
</pre></div>

<p>That can now be replaced by the following, which also produces more helpful error messages for the user:</p>


<div class="example"><pre>
LoadKernelExtension("SomePackage");
</pre></div>

<p>For packages where the name of the kernel extension is not identical to that of the package, you can either rename the kernel extension to have a matching name (recommended if you only have a single kernel extension in your package, which is how we recommend to set up things anyway), or else use the two argument version:</p>


<div class="example"><pre>
LoadKernelExtension("SomePackage", "kext"); # this will look for kext.so
</pre></div>

<p><a id="X7C99782886B18C77" name="X7C99782886B18C77"></a></p>

<h5>76.3-14 LoadDynamicModule</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ LoadDynamicModule</code>( <var class="Arg">filename</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>To load a compiled file, the command <code class="func">LoadDynamicModule</code> is used. This command loads <var class="Arg">filename</var> as module.</p>


<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">LoadDynamicModule("./test.so");</span>
</pre></div>

<p>On some operating systems, once you have loaded a dynamic module with a certain filename, loading another with the same filename will have no effect, even if the file on disk has changed.</p>

<p><a id="X85C8DE357EE424D8" name="X85C8DE357EE424D8"></a></p>

<h5>76.3-15 <span class="Heading">The PackageInfo.g File</span></h5>

<p>Each package has the file <code class="file">PackageInfo.g</code> which contains meta-information about the package (package name, version, author(s), relations to other packages, homepage, download archives, etc.). This file is used by the package loading mechanism, by the <strong class="pkg">GAP</strong> webpages about packages, and also for the redistribution of a package with <strong class="pkg">GAP</strong>.</p>

<p>A <code class="file">PackageInfo.g</code> file contains a call to the function <code class="code">SetPackageInfo</code>, with argument a record. The following components of this record are <em>mandatory</em>.</p>


<dl>
<dt><strong class="Mark"><code class="code">PackageName</code></strong></dt>
<dd><p>a nonempty string denoting the name of the package,</p>

</dd>
<dt><strong class="Mark"><code class="code">Subtitle</code></strong></dt>
<dd><p>a string that describes the package's contents, may be used by a default banner or on a web page, should fit on one line,



</dd>
<dt><strong class="Mark"><code class="code">Version</code></strong></dt>
<dd><p>a nonempty string that does not start with <code class="code">=</code>, denoting the version number of the package (see Section <a href="chap76.html#X8180BCDA82587F41"><span class="RefLink">76.18</span></a>),</p>

</dd>
<dt><strong class="Mark"><code class="code">Date</code></strong></dt>
<dd><p>a string of the form <code class="code">yyyy-mm-dd</code> denoting the release date of the current version of the package (a date since 1999, when <strong class="pkg">GAP</strong> 4 appeared),</p>

</dd>
<dt><strong class="Mark"><code class="code">License</code></strong></dt>
<dd><p>a nonempty string containing an SPDX ID (see Section <a href="chap76.html#X82EBCBC5829B6001"><span class="RefLink">76.22</span></a>),</p>

</dd>
<dt><strong class="Mark"><code class="code">ArchiveURL</code></strong></dt>
<dd><p>a string started with <code class="code">http://</code>, <code class="code">https://</code>, or <code class="code">ftp://</code>, denoting an URL from where the current package archive can be downloaded, but without the suffix describing the format (see the <code class="code">ArchiveFormats</code> component),</p>

</dd>
<dt><strong class="Mark"><code class="code">ArchiveFormats</code></strong></dt>
<dd><p>a string that lists the supported formats (among <code class="code">.tar.gz</code>, <code class="code">.tar.bz2</code>, <code class="code">-win.zip</code>), separated by whitespace or commas,</p>

</dd>
<dt><strong class="Mark"><code class="code">README_URL</code></strong></dt>
<dd><p>a string started with <code class="code">http://</code>, <code class="code">https://</code>, or <code class="code">ftp://</code>, denoting an URL from where the current <code class="file">README.md</code> or <code class="file">README</code> file of the package can be downloaded,</p>

</dd>
<dt><strong class="Mark"><code class="code">PackageInfoURL</code></strong></dt>
<dd><p>a string started with <code class="code">http://</code>, <code class="code">https://</code>, or <code class="code">ftp://</code>, denoting an URL from where the current <code class="file">PackageInfo.g</code> file of the package can be downloaded,</p>

</dd>
--> --------------------

--> maximum size reached

--> --------------------

100%


¤ Dauer der Verarbeitung: 0.28 Sekunden  (vorverarbeitet)  ¤

*© Formatika GbR, Deutschland




Wurzel

Suchen

Beweissystem der NASA

Beweissystem Isabelle

NIST Cobol Testsuite

Cephes Mathematical Library

Wiener Entwicklungsmethode

Haftungshinweis

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.