1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
|
<?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 <code class="file">pkg</code> directory in your main <strong class="pkg">GAP</strong> installation you can add private root directories as explained in section <a href="chap9.html#X7A4973627A5DB27D"><span class="RefLink">9.2</span></a>.</p>
<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, <strong class="pkg">GAP</strong> provides three levels for disabling autoloading.</p>
<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 <code class="file">gap.ini</code> file (see <a href="chap3.html#X87DF11C885E73583"><span class="RefLink">3.2-1</span></a>).</p>
<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 <code class="code">AvailabilityTest</code> 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 <code class="code">AvailabilityTest</code> function (see <a href="chap76.html#X85C8DE357EE424D8"><span class="RefLink">76.3-15</span></a>) or is called from a package file that is read from <code class="file">init.g</code> or <code class="file">read.g</code>; in these cases, the name of the current package (stored in the record <code class="code">GAPInfo.PackageCurrent</code>) is taken. According to the above list, the <var class="Arg">severity</var> argument of <code class="func">LogPackageLoadingMessage</code> 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 <code class="file">PackageInfo.g</code> file (see <a href="chap76.html#X85C8DE357EE424D8"><span class="RefLink">76.3-15</span></a>).</p>
<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 <code class="file">gap</code> rather than <code class="file">lib</code>.</p>
<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 <code class="file">lib</code>. The directories in <var class="Arg">path</var> should be separated by <code class="code">/</code> (even on systems, like Windows, which use <code class="code">\</code> as the directory separator). For example, suppose there is a package <code class="code">somepackage</code> with a subdirectory <code class="file">m11</code> in the directory <code class="file">data</code>, then we might expect the following:</p>
<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 <code class="file">PackageInfo.g</code> file (see <a href="chap76.html#X85C8DE357EE424D8"><span class="RefLink">76.3-15</span></a>).</p>
<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,</p>
</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>
<dt><strong class="Mark"><code class="code">AbstractHTML</code></strong></dt>
<dd><p>a string that describes the package's contents in a few lines, in HTML format; this text will be displayed on the package overview web page of <strong class="pkg">GAP</strong>,</p>
</dd>
<dt><strong class="Mark"><code class="code">PackageWWWHome</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 the address of the package's home page,</p>
</dd>
<dt><strong class="Mark"><code class="code">PackageDoc</code></strong></dt>
<dd><p>a record or a list of records; each record describes a book of the package documentation, with the following components</p>
<dl>
<dt><strong class="Mark"><code class="code">BookName</code></strong></dt>
<dd><p>a string, the name of the book,</p>
</dd>
<dt><strong class="Mark"><code class="code">LongTitle</code></strong></dt>
<dd><p>a string shown by <code class="code">?books</code>,</p>
</dd>
<dt><strong class="Mark"><code class="code">SixFile</code></strong></dt>
<dd><p>a string denoting a relative path to the <code class="file">manual.six</code> file of the book,</p>
</dd>
<dt><strong class="Mark"><code class="code">HTMLStart</code></strong></dt>
<dd><p>a string denoting a relative path to the start file of the HTML version of the book,</p>
</dd>
<dt><strong class="Mark"><code class="code">PDFFile</code></strong></dt>
<dd><p>a string denoting a relative path to the <code class="file">.pdf</code> file of the book,</p>
</dd>
<dt><strong class="Mark"><code class="code">ArchiveURLSubset</code></strong></dt>
<dd><p>a list of strings denoting relative paths to those files and directories from the archive that are needed for the online manual; typically, <code class="code">[ "doc" ]</code> suffices,</p>
</dd>
</dl>
</dd>
</dl>
<p>The following components of the record are <em>optional</em>.</p>
<dl>
<dt><strong class="Mark"><code class="code">TextFiles</code> or <code class="code">BinaryFiles</code> or <code class="code">TextBinaryFilesPatterns</code></strong></dt>
<dd><p>a list of strings that specify which files in the archive are text files or binary files (at most one of the three components can be available, each string in <code class="code">TextBinaryFilesPatterns</code> must start with <code class="code">T</code> for text files and by <code class="code">B</code> for binary files),</p>
</dd>
<dt><strong class="Mark"><code class="code">Persons</code></strong></dt>
<dd><p>a list of records, each with the mandatory components</p>
<dl>
<dt><strong class="Mark"><code class="code">LastName</code></strong></dt>
<dd><p>a string,</p>
</dd>
<dt><strong class="Mark">at least one of <code class="code">IsAuthor</code> or <code class="code">IsMaintainer</code></strong></dt>
<dd><p><code class="keyw">true</code> or <code class="keyw">false</code>,</p>
</dd>
</dl>
<p>and optional components</p>
<dl>
<dt><strong class="Mark"><code class="code">FirstNames</code></strong></dt>
<dd><p>a string (was mandatory before <strong class="pkg">GAP</strong> 4.14),</p>
</dd>
<dt><strong class="Mark"><code class="code">Place</code></strong></dt>
<dd><p>a string,</p>
</dd>
<dt><strong class="Mark"><code class="code">Institution</code></strong></dt>
<dd><p>a string,</p>
</dd>
</dl>
<p>If the <code class="code">IsMaintainer</code> value is <code class="keyw">true</code> then also one of the following components is mandatory, otherwise these components are optional.</p>
<dl>
<dt><strong class="Mark"><code class="code">Email</code></strong></dt>
<dd><p>a string,</p>
</dd>
<dt><strong class="Mark"><code class="code">WWWHome</code></strong></dt>
<dd><p>a string denoting an URL, or</p>
</dd>
<dt><strong class="Mark"><code class="code">PostalAddress</code></strong></dt>
<dd><p>a string.</p>
</dd>
</dl>
</dd>
<dt><strong class="Mark"><code class="code">SourceRepository</code></strong></dt>
<dd><p>a record with the components <code class="code">Type</code> (the version control system, e.g. <code class="code">"git"</code> or <code class="code">"hg"</code>) and <code class="code">URL</code> (the URL of the repository), both strings,</p>
</dd>
<dt><strong class="Mark"><code class="code">IssueTrackerURL</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>,</p>
</dd>
<dt><strong class="Mark"><code class="code">SupportEmail</code></strong></dt>
<dd><p>a string denoting an e-mail address,</p>
</dd>
<dt><strong class="Mark"><code class="code">Dependencies</code></strong></dt>
<dd><p>a record describing the dependencies of the package (see Section <a href="chap76.html#X7928799186F9B2FE"><span class="RefLink">76.11</span></a>), with the following optional components</p>
<dl>
<dt><strong class="Mark"><code class="code">GAP</code></strong></dt>
<dd><p>a string denoting the needed version of <strong class="pkg">GAP</strong>,</p>
</dd>
<dt><strong class="Mark"><code class="code">NeededOtherPackages</code></strong></dt>
<dd><p>a list of pairs <code class="code">[ pkgname, pkgversion ]</code> of strings, denoting the other packages which must be available if the current package shall be loadable,</p>
</dd>
<dt><strong class="Mark"><code class="code">SuggestedOtherPackages</code></strong></dt>
<dd><p>a list of pairs <code class="code">[ pkgname, pkgversion ]</code> of strings, denoting the other packages which shall be loaded together with the current package if they are available,</p>
</dd>
<dt><strong class="Mark"><code class="code">ExternalConditions</code></strong></dt>
<dd><p>a list of strings or of pairs <code class="code">[ text, URL ]</code> of strings, denoting conditions on external programs,</p>
</dd>
</dl>
</dd>
<dt><strong class="Mark"><code class="code">AvailabilityTest</code></strong></dt>
<dd><p>a function with no arguments that returns <code class="keyw">true</code> if the package is available, and <code class="keyw">false</code> otherwise (can be <code class="func">ReturnTrue</code> (<a href="chap5.html#X7DB422A2876CCC4D"><span class="RefLink">5.4-1</span></a>) if the package consists only of <strong class="pkg">GAP</strong> code; this is also the default value),</p>
</dd>
<dt><strong class="Mark"><code class="code">BannerString</code> or <code class="code">BannerFunction</code></strong></dt>
<dd><p>a string or a function, respectively, that is used to create a package banner different from the default banner (see Section <a href="chap76.html#X784E0A5A7DB88332"><span class="RefLink">76.17</span></a>),</p>
</dd>
<dt><strong class="Mark"><code class="code">TestFile</code></strong></dt>
<dd><p>a string denoting a relative path to a readable file which contains tests of the package's functionality (see Section <a href="chap76.html#X8559D1FF7C9B7D14"><span class="RefLink">76.19</span></a>),</p>
</dd>
<dt><strong class="Mark"><code class="code">Keywords</code></strong></dt>
<dd><p>a list of strings that are keywords related to the topic of the package,</p>
</dd>
<dt><strong class="Mark"><code class="code">Extensions</code></strong></dt>
<dd><p>a list of records that describe conditional extensions of the package (see Section <a href="chap76.html#X783A5F3D87F9AF78"><span class="RefLink">76.12</span></a>).</p>
</dd>
</dl>
<p>Other components of the record can be supported; for example, <code class="code">AutoDoc</code> is used by the <strong class="pkg">AutoDoc</strong> package if applicable.</p>
<p><a id="X79767C2482FF6F55" name="X79767C2482FF6F55"></a></p>
<h5>76.3-16 ValidatePackageInfo</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ValidatePackageInfo</code>( <var class="Arg">info</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function is intended to support package authors who create or modify <code class="file">PackageInfo.g</code> files. (It is <em>not</em> called when these files are read during the startup of <strong class="pkg">GAP</strong> or when packages are actually loaded.)</p>
<p>The argument <var class="Arg">info</var> must be either a record as is contained in a <code class="file">PackageInfo.g</code> file or a string which describes the path to such a file. The result is <code class="keyw">true</code> if the record or the contents of the file, respectively, has correct format, and <code class="keyw">false</code> otherwise; in the latter case information about the incorrect components is printed. These diagnostic messages can be suppressed by setting the global option <code class="code">quiet</code> to <code class="keyw">true</code>.</p>
<p>Note that the components used for package loading are checked as well as the components that are needed for composing the package overview web page or for updating the package archives.</p>
<p>If <var class="Arg">info</var> is a string then <code class="func">ValidatePackageInfo</code> checks additionally whether those package files exist that are mentioned in the file <code class="file">info</code>, for example the <code class="file">manual.six</code> file of the package documentation.</p>
<p><a id="X7D34AC3287611B15" name="X7D34AC3287611B15"></a></p>
<h5>76.3-17 ShowPackageVariables</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ShowPackageVariables</code>( <var class="Arg">pkgname</var>[, <var class="Arg">version</var>][, <var class="Arg">arec</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">‣ PackageVariablesInfo</code>( <var class="Arg">pkgname</var>, <var class="Arg">version</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Let <var class="Arg">pkgname</var> be the name of a <strong class="pkg">GAP</strong> package. If the package <var class="Arg">pkgname</var> is available but not yet loaded then <code class="func">ShowPackageVariables</code> prints a list of global variables that become bound and of methods that become installed when the package is loaded. (For that, <strong class="pkg">GAP</strong> actually loads the package.)</p>
<p>If a version number <var class="Arg">version</var> is given (see Section <span class="RefLink">Reference: Version Numbers</span>) then this version of the package is considered.</p>
<p>An error message is printed if (the given version of) the package is not available or already loaded.</p>
<p>Information is printed about new and redeclared global variables, and about names of global variables introduced in the package that differ from existing globals only by case; note that the <strong class="pkg">GAP</strong> help system is case insensitive, so it is difficult to document identifiers that differ only by case.</p>
<p>Info lines for undocumented variables are marked with an asterisk <code class="code">*</code>.</p>
<p>The following entries are omitted from the list: default setter methods for attributes and properties that are declared in the package, and <code class="code">Set<var class="Arg">attr</var></code> and <code class="code">Has<var class="Arg">attr</var></code> type variables where <var class="Arg">attr</var> is an attribute or property.</p>
<p>The output can be customized using the optional record <var class="Arg">arec</var>, the following components of this record are supported.</p>
<dl>
<dt><strong class="Mark"><code class="code">show</code></strong></dt>
<dd><p>a list of strings describing those kinds of variables which shall be shown, such as <code class="code">"new global functions"</code>; the default are all kinds that appear in the package,</p>
</dd>
<dt><strong class="Mark"><code class="code">showDocumented</code></strong></dt>
<dd><p><code class="keyw">true</code> (the default) if documented variables shall be shown, and <code class="keyw">false</code> otherwise,</p>
</dd>
<dt><strong class="Mark"><code class="code">showUndocumented</code></strong></dt>
<dd><p><code class="keyw">true</code> (the default) if undocumented variables shall be shown, and <code class="keyw">false</code> otherwise,</p>
</dd>
<dt><strong class="Mark"><code class="code">showPrivate</code></strong></dt>
<dd><p><code class="keyw">true</code> (the default) if variables from the package's name space (see Section <a href="chap4.html#X7DF8774F7D542298"><span class="RefLink">4.10</span></a>) shall be shown, and <code class="keyw">false</code> otherwise,</p>
</dd>
<dt><strong class="Mark"><code class="code">Display</code></strong></dt>
<dd><p>a function that takes a string and shows it on the screen; the default is <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>), another useful value is <code class="func">Pager</code> (<a href="chap2.html#X7ED03E41792C3840"><span class="RefLink">2.4-1</span></a>).</p>
</dd>
</dl>
<p>An interactive variant of <code class="func">ShowPackageVariables</code> is the function <code class="func">BrowsePackageVariables</code> (<a href="../../pkg/browse/doc/chap6.html#X8030B1688335783D"><span class="RefLink">Browse: BrowsePackageVariables</span></a>) that is provided by the <strong class="pkg">GAP</strong> package <strong class="pkg">Browse</strong>. For this function, it is not sensible to assume that the package <var class="Arg">pkgname</var> is not yet loaded before the function call, because one might be interested in packages that must be loaded before <strong class="pkg">Browse</strong> itself can be loaded. The solution is that <code class="func">BrowsePackageVariables</code> (<a href="../../pkg/browse/doc/chap6.html#X8030B1688335783D"><span class="RefLink">Browse: BrowsePackageVariables</span></a>) takes the output of <code class="func">PackageVariablesInfo</code> as its second argument. The function <code class="func">PackageVariablesInfo</code> is used by both <code class="func">ShowPackageVariables</code> and <code class="func">BrowsePackageVariables</code> (<a href="../../pkg/browse/doc/chap6.html#X8030B1688335783D"><span class="RefLink">Browse: BrowsePackageVariables</span></a>) for collecting the information about the package in question, and can be called before the package <strong class="pkg">Browse</strong> is loaded.</p>
<p><a id="X79EA4BD37940AD25" name="X79EA4BD37940AD25"></a></p>
<h5>76.3-18 BibEntry</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ BibEntry</code>( <var class="Arg">pkgname</var>[, <var class="Arg">key</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: a string in BibXMLext format (see <a href="../../pkg/gapdoc/doc/chap7.html#X7FB8F6BD80D859D1"><span class="RefLink">GAPDoc: The BibXMLext Format</span></a>) that can be used for referencing the <strong class="pkg">GAP</strong> system or a <strong class="pkg">GAP</strong> package.</p>
<p>If the argument <var class="Arg">pkgname</var> is the string <code class="code">"GAP"</code>, the function returns an entry for the current version of <strong class="pkg">GAP</strong>.</p>
<p>Otherwise, if a string <var class="Arg">pkgname</var> is given, which is the name of a <strong class="pkg">GAP</strong> package, an entry for this package is returned; this entry is computed from the <code class="file">PackageInfo.g</code> file of <em>the current version</em> of the package, see <code class="func">InstalledPackageVersion</code> (<a href="chap76.html#X7B79FEE57DBDBD71"><span class="RefLink">76.3-6</span></a>). If no package with name <var class="Arg">pkgname</var> is installed then the empty string is returned.</p>
<p>A string for <em>a different version</em> of <strong class="pkg">GAP</strong> or a package can be computed by entering, as the argument <var class="Arg">pkgname</var>, the desired record from the <code class="file">PackageInfo.g</code> file. (One can access these records using the function <code class="code">PackageInfo</code>.)</p>
<p>In each of the above cases, an optional argument <var class="Arg">key</var> can be given, a string which is then used as the key of the BibTeX entry instead of the default key that is generated from the system/package name and the version number.</p>
<p><code class="func">BibEntry</code> requires the functions <code class="func">FormatParagraph</code> (<a href="../../pkg/gapdoc/doc/chap6.html#X812058CE7C8E9022"><span class="RefLink">GAPDoc: FormatParagraph</span></a>) and <code class="func">NormalizedNameAndKey</code> (<a href="../../pkg/gapdoc/doc/chap7.html#X7C9F0C337A0A0FF0"><span class="RefLink">GAPDoc: NormalizedNameAndKey</span></a>) from the <strong class="pkg">GAP</strong> package <strong class="pkg">GAPDoc</strong>.</p>
<p>The functions <code class="func">ParseBibXMLextString</code> (<a href="../../pkg/gapdoc/doc/chap7.html#X86BD29AE7A453721"><span class="RefLink">GAPDoc: ParseBibXMLextString</span></a>) and <code class="func">StringBibXMLEntry</code> (<a href="../../pkg/gapdoc/doc/chap7.html#X790A295680F7CD24"><span class="RefLink">GAPDoc: StringBibXMLEntry</span></a>) can be used to create for example a BibTeX entry from the return value, as follows.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">bib:= BibEntry( "GAP", "GAP4.5" );;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">Print( bib, "\n" );</span>
<entry id="GAP4.5"><misc>
<title><C>GAP</C> &ndash; <C>G</C>roups, <C>A</C>lgorithms,
and <C>P</C>rogramming, <C>V</C>ersion 4.5.1</title>
<howpublished><URL>https://www.gap-system.org</URL></howpublished>
<key>GAP</key>
<keywords>groups; *; gap; manual</keywords>
<other type="organization">The GAP <C>G</C>roup</other>
</misc></entry>
<span class="GAPprompt">gap></span> <span class="GAPinput">parse:= ParseBibXMLextString( bib );;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">Print( StringBibXMLEntry( parse.entries[1], "BibTeX" ) );</span>
@misc{ GAP4.5,
title = {{GAP} {\textendash} {G}roups, {A}lgorithms, and
{P}rogramming, {V}ersion 4.5.1},
organization = {The GAP {G}roup},
howpublished = {\href {https://www.gap-system.org}
{\texttt{https://www.gap-system.org}}},
key = {GAP},
keywords = {groups; *; gap; manual}
}
</pre></div>
<p><a id="X79637D9A7B1AD7F7" name="X79637D9A7B1AD7F7"></a></p>
<h5>76.3-19 Cite</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ Cite</code>( [<var class="Arg">pkgname</var>[, <var class="Arg">key</var>]] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Used with no arguments or with argument <code class="code">"GAP"</code> (case-insensitive), <code class="func">Cite</code> displays instructions on citing the version of <strong class="pkg">GAP</strong> that is being used. Suggestions are given in plain text, HTML, BibXML and BibTeX formats. The same instructions are also contained in the <code class="file">CITATION</code> file in the <strong class="pkg">GAP</strong> root directory.</p>
<p>If <var class="Arg">pkgname</var> is the name of a <strong class="pkg">GAP</strong> package, instructions on citing this package will be displayed. They will be produced from the <code class="file">PackageInfo.g</code> file of the working version of this package that must be available in the <strong class="pkg">GAP</strong> installation being used. Otherwise, one will get a warning that no working version of the package is available.</p>
<p>The optional 2nd argument <var class="Arg">key</var> has the same meaning as in <code class="func">BibEntry</code> (<a href="chap76.html#X79EA4BD37940AD25"><span class="RefLink">76.3-18</span></a>).</p>
<p><a id="X7EE8E5D97B0F8AFF" name="X7EE8E5D97B0F8AFF"></a></p>
<h4>76.4 <span class="Heading">Guidelines for Writing a <strong class="pkg">GAP</strong> Package</span></h4>
<p>The remaining part of this chapter explains the basics of how to write a <strong class="pkg">GAP</strong> package so that it integrates properly into <strong class="pkg">GAP</strong>.</p>
<p>There are two basic aspects of creating a <strong class="pkg">GAP</strong> package.</p>
<p>First, it is a convenient possibility to load additional functionality into <strong class="pkg">GAP</strong> including a smooth integration of the package documentation. Second, a package is a way to make your code available to other <strong class="pkg">GAP</strong> users.</p>
<p>Moreover, the <strong class="pkg">GAP</strong> Group may provide some help with redistributing your package via the <strong class="pkg">GAP</strong> website after checking if the package provides some new or improved functionality which looks interesting for other users, if it contains reasonable documentation, and if it seems to work smoothly with the <strong class="pkg">GAP</strong> library and other distributed packages. In this case the package can take part in the <strong class="pkg">GAP</strong> distribution update mechanism and becomes a <em>deposited</em> package.</p>
<p>Furthermore, package authors are encouraged to check if the package would be appropriate for the refereeing process and <em>submit</em> it. If the refereeing has been successful, the package becomes an <em>accepted</em> package. Check out <span class="URL"><a href="https://www.gap-system.org/Packages/Authors/authors.html">https://www.gap-system.org/Packages/Authors/authors.html</a></span> on the <strong class="pkg">GAP</strong> website for more details.</p>
<p>Below we start with a description how the directory structure of a <strong class="pkg">GAP</strong> package should be constructed and then add remarks on certain aspects of creating a package, some of these only apply to some packages. Finally, we provide guidelines for the release preparation and its distribution.</p>
<p><a id="X8383876782480702" name="X8383876782480702"></a></p>
<h4>76.5 <span class="Heading">Structure of a <strong class="pkg">GAP</strong> Package</span></h4>
<p>A <strong class="pkg">GAP</strong> package should have an alphanumeric name; mixed case is fine, but there should be no whitespace characters. All files of a <strong class="pkg">GAP</strong> package <var class="Arg">packagename</var> must be collected in a single directory <var class="Arg">packagedir</var>, where <var class="Arg">packagedir</var> should be just <var class="Arg">packagename</var> optionally converted to lowercase and optionally followed by the package version (with or without hyphen to separate the version from <var class="Arg">packagename</var>). Let us call this directory the <em>home directory</em> of the package.</p>
<p>To use the package with <strong class="pkg">GAP</strong>, the directory <var class="Arg">packagedir</var> must be a subdirectory of a <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>). For example, if <strong class="pkg">GAP</strong> is installed in <code class="file">/usr/local/gap4</code> then the files of the package <code class="code">MyPack</code> may be placed in the directory <code class="file">/usr/local/gap4/pkg/mypack</code>. The directory <var class="Arg">packagedir</var> preferably should have the following structure (below, a trailing <code class="code">/</code> distinguishes directories from ordinary files):</p>
<div class="example"><pre>
packagedir/
doc/
lib/
tst/
CHANGES
LICENSE
README
PackageInfo.g
init.g
read.g
</pre></div>
<p>This layout of directories and files may be created manually, or automatically using the tool called <strong class="pkg">PackageMaker</strong>, available at <span class="URL"><a href="https://github.com/gap-system/PackageMaker">https://github.com/gap-system/PackageMaker</a></span>. The <strong class="pkg">PackageMaker</strong> asks several questions about the intended package and then creates a new directory for it and populates it with all the files needed for a basic package.</p>
<p>Packages that contain some code that requires compilation will usually have it in the <code class="file">src</code> subdirectory. They may also have extra files such as <code class="file">configure</code>, <code class="file">Makefile.in</code> etc. that automate the build procedure. There are three file names with a special meaning in the home directory of a package: <code class="file">PackageInfo.g</code> and <code class="file">init.g</code> which must be present, and <code class="file">read.g</code> which is optional.</p>
<p>On the other hand, the names of <code class="file">CHANGES</code>, <code class="file">LICENSE</code> and <code class="file">README</code> files are not strictly fixed. They may have extensions <code class="file">.txt</code> or <code class="file">.md</code>, and instead of <code class="file">LICENSE</code> one could use e.g. <code class="file">COPYING</code> or <code class="file">GPL</code> for packages distributed under the GNU General Public License, or use <code class="file">HISTORY</code> instead of <code class="file">CHANGES</code>.</p>
<p>We now describe the above files and directories in more details:</p>
<dl>
<dt><strong class="Mark">
<code class="file">README</code></strong></dt>
<dd><p>The filename may optionally have an extension, e.g. <code class="file">.txt</code> or <code class="file">.md</code>.</p>
<p>This should contain <q>how to get it</q> instructions (covering the way of getting it with the <strong class="pkg">GAP</strong> distribution and from the <strong class="pkg">GAP</strong> website, if applicable), as well as installation instructions and names of the package authors and their email addresses. These installation instructions should be repeated or referenced from the package's documentation, which should be in the <code class="file">doc</code> directory (see <a href="chap76.html#X84164AA2859A195F"><span class="RefLink">76.6</span></a>). Authors' names and addresses should be repeated both in the package's documentation and in the <code class="file">PackageInfo.g</code> (see below).</p>
</dd>
<dt><strong class="Mark">
<code class="file">CHANGES</code></strong></dt>
<dd><p>For further versions of the package, it will be also useful to have a <code class="file">CHANGES</code> file that records the main changes between versions of the package.</p>
<p>The filename may optionally have an extension, e.g. <code class="file">.txt</code> or <code class="file">.md</code>.</p>
</dd>
<dt><strong class="Mark">
<code class="file">LICENSE</code></strong></dt>
<dd><p>The file which explains conditions on which the package is distributed.</p>
<p>We advise all package authors to make clear in the documentation of their package the basis on which it is being distributed to users. Technically, this is the terms of the license which you give the users to copy, modify and redistribute your software (of which you presumably own the copyright) for their purposes.</p>
<p><strong class="pkg">GAP</strong> itself is distributed under the GNU General Public License version 2, a popular <q>free software</q> license which allows users to redistribute it freely under the same terms, and requires that any software which incorporates <strong class="pkg">GAP</strong> (technically, any <q>derived work</q>) also be distributed under those terms. We would encourage you to consider the GPL for your packages, but you might wish to be more restrictive (for instance forbidding redistribution for profit) or less restrictive (allowing your software to be incorporated into commercial software).</p>
<p>The filename may optionally have an extension, e.g. <code class="file">.txt</code> or <code class="file">.md</code>. Some packages also use different filenames, like <code class="file">COPYING</code>.</p>
</dd>
<dt><strong class="Mark"><code class="file">configure</code>, <code class="file">Makefile.in</code></strong></dt>
<dd><p>These files are typically only used by packages which have a non-<strong class="pkg">GAP</strong> component, e.g. some C code (the files of which should be in the <code class="file">src</code> directory). The <code class="file">configure</code> and <code class="file">Makefile.in</code> files of the <strong class="pkg">Example</strong> package provide prototypes (or they may be created using the <strong class="pkg">PackageMaker</strong> mentioned above). The <code class="file">configure</code> file typically takes a path <var class="Arg">path</var> to the <strong class="pkg">GAP</strong> root directory as argument and uses the value assigned to <code class="code">GAParch</code> in the file <code class="file">sysinfo.gap</code>, created when <strong class="pkg">GAP</strong> was compiled to determine the compilation architecture, inserts this in place of the string <code class="code">@GAPARCH@</code> in <code class="file">Makefile.in</code> and creates a file <code class="file">Makefile</code>. When <code class="code">make</code> is run (which, of course, reads the constructed <code class="file">Makefile</code>), a directory <code class="file">bin</code> (if necessary) and subdirectories of <code class="file">bin</code> with the path equal to the string assigned to <code class="code">GAParch</code> in the file <code class="file">sysinfo.gap</code> should be created; any binaries constructed by compiling the code in <code class="file">src</code> should end up in this subdirectory of <code class="file">bin</code>.</p>
</dd>
<dt><strong class="Mark"><code class="file">PackageInfo.g</code></strong></dt>
<dd><p>Every <strong class="pkg">GAP</strong> package <em>must</em> have a <code class="file">PackageInfo.g</code> file which contains meta-information about the package (package name, version, author(s), relations to other packages, homepage, download archives, etc.). This information is used by the package loading mechanism and also for the redistribution of a package with <strong class="pkg">GAP</strong>. The <strong class="pkg">Example</strong> package's <code class="file">PackageInfo.g</code> file is well-commented and can be used as a prototype (see also <a href="chap76.html#X85C8DE357EE424D8"><span class="RefLink">76.3-15</span></a> for further details). It may also be created using the <strong class="pkg">PackageMaker</strong> mentioned above.</p>
</dd>
<dt><strong class="Mark"><code class="file">init.g</code>, <code class="file">read.g</code></strong></dt>
<dd><p>A <strong class="pkg">GAP</strong> package <em>must</em> have a file <code class="file">init.g</code>. Typical <code class="file">init.g</code> and <code class="file">read.g</code> files should normally consist entirely of <code class="func">ReadPackage</code> (<a href="chap76.html#X870954577B27DCAB"><span class="RefLink">76.3-1</span></a>) commands (and possibly also <code class="func">Read</code> (<a href="chap9.html#X8373AC6B7D5F9167"><span class="RefLink">9.8-1</span></a>) commands) for reading further files of the package. If the <q>declaration</q> and <q>implementation</q> parts of the package are separated (and this is recommended), there should be a <code class="file">read.g</code> file. The <q>declaration</q> part of a package consists of function and variable <em>name</em> declarations and these go in files with <code class="code">.gd</code> extensions; these files are read in via <code class="code">ReadPackage</code> commands in the <code class="file">init.g</code> file. The <q>implementation</q> part of a package consists of the actual definitions of the functions and variables whose names were declared in the <q>declaration</q> part, and these go in files with <code class="code">.gi</code> extensions; these files are read in via <code class="code">ReadPackage</code> commands in the <code class="file">read.g</code> file. The reason for following the above dichotomy is that the <code class="file">read.g</code> file is read <em>after</em> the <code class="file">init.g</code> file, thus enabling the possibility of a function's implementation to refer to another function whose name is known but is not actually defined yet (see <a href="chap76.html#X7A7835A5797AF766"><span class="RefLink">76.13</span></a> below for more details).</p>
<p>The <strong class="pkg">GAP</strong> code (whether or not it is split into <q>declaration</q> and <q>implementation</q> parts) should go in the package's <code class="file">lib</code> directory (see below).</p>
</dd>
<dt><strong class="Mark"><code class="file">doc</code></strong></dt>
<dd><p>This directory should contain the package's documentation, written in an XML-based documentation format supported by the <strong class="pkg">GAP</strong> package <strong class="pkg">GAPDoc</strong> (see <a href="../../pkg/gapdoc/doc/chap1.html#X7D4EE663818DA109"><span class="RefLink">GAPDoc: Introduction and Example</span></a>) which is used for the <strong class="pkg">GAP</strong> documentation itself.</p>
<p>The <strong class="pkg">Example</strong> package's documentation (see its <code class="file">doc</code> directory) may be used as a prototype. It consists of the master file <code class="file">main.xml</code>, further <code class="file">.xml</code> files for manual chapters (included in the manual via <code class="code">Include</code> directives in the master file) and the <strong class="pkg">GAP</strong> input file <code class="file">../makedocrel.g</code> which generates the manuals. Generally, one should also provide a <code class="file">manual.bib</code> BibTeX database file or an <code class="file">xml</code> file in the BibXMLext format (see <a href="../../pkg/gapdoc/doc/chap7.html#X7FB8F6BD80D859D1"><span class="RefLink">GAPDoc: The BibXMLext Format</span></a>).</p>
<p>One could also use the <strong class="pkg">AutoDoc</strong> which simplifies writing documentation by generating most of the <strong class="pkg">GAPDoc</strong> code automatically.</p>
</dd>
<dt><strong class="Mark"><code class="file">lib</code></strong></dt>
<dd><p>This is the preferred place for the <strong class="pkg">GAP</strong> code of the package, i.e. the <code class="code">.g</code>, <code class="code">.gd</code> and <code class="code">.gi</code> files (other than <code class="file">PackageInfo.g</code>, <code class="file">init.g</code> and <code class="file">read.g</code>). For some packages, the directory <code class="file">gap</code> has been used instead of <code class="file">lib</code>; <code class="file">lib</code> has the advantage that it is the default subdirectory of a package directory searched for by the <code class="func">DirectoriesPackageLibrary</code> (<a href="chap76.html#X807D835C7B032D4E"><span class="RefLink">76.3-7</span></a>) command.</p>
</dd>
<dt><strong class="Mark"><code class="file">src</code></strong></dt>
<dd><p>If the package contains non-<strong class="pkg">GAP</strong> code, e.g. C code, then this source code should go in the <code class="file">src</code> directory. If there are <code class="code">.h</code> <q>include</q> files you may prefer to put these all together in a separate <code class="code">include</code> directory. There is one further rule for the location of kernel library modules or external programs which is explained in <a href="chap76.html#X7CD9ED5C86725ACF"><span class="RefLink">76.15-1</span></a> below.</p>
</dd>
<dt><strong class="Mark"><code class="file">tst</code></strong></dt>
<dd><p>It is highly recommended that a package should have test files, which then should go in the <code class="file">tst</code> directory. For a deposited package, a test file with a basic test of the package (for example, to check that it works as expected and/or that the manual examples are correct) may be specified in the <code class="file">PackageInfo.g</code> to be included in the <strong class="pkg">GAP</strong> standard test suite and run as a part of the <strong class="pkg">GAP</strong> release preparation. More specific and time consuming tests are not supposed to be a part of the <strong class="pkg">GAP</strong> standard test suite but may be placed in the <code class="file">tst</code> directory with further instructions on how to run them. See Section <a href="chap76.html#X8559D1FF7C9B7D14"><span class="RefLink">76.19</span></a> about the requirements to the test files formats and further recommendations.</p>
</dd>
</dl>
<p>All other files can be organised as you like. But we suggest that you have a look at existing packages and use a similar scheme, for example, put examples in the <code class="file">examples</code> subdirectory, data libraries in extra subdirectories, and so on.</p>
<p>Sometimes there may be a need to include an empty directory in the package distribution (for example, as a place to store some data that may appear at runtime). In this case package authors are advised to put in this directory a short <code class="file">README</code> file describing its purpose to ensure that such directory will be included in the redistribution.</p>
<p>Concerning the <strong class="pkg">GAP</strong> code in packages, it is recommended to use only documented <strong class="pkg">GAP</strong> functions, see <a href="chap83.html#X801428EB86E7113C"><span class="RefLink">83.3</span></a>. In particular if you want to make your package available to other <strong class="pkg">GAP</strong> users it is advisable to avoid using <q>obsolete</q> variables (see <a href="chap77.html#X78C85ED17F00DCC1"><span class="RefLink">77</span></a>). To test that the package does not use obsolete variables you can set the <code class="code">ReadObsolete</code> component in your <code class="file">gap.ini</code> file to <code class="keyw">false</code> (see <a href="chap3.html#X7FD66F977A3B02DF"><span class="RefLink">3.2</span></a>) or start <strong class="pkg">GAP</strong> with <code class="code">-A -O</code> command line options (note that this may also cause problems with loading other packages that use <q>obsolete</q> variables).</p>
<p><a id="X84164AA2859A195F" name="X84164AA2859A195F"></a></p>
<h4>76.6 <span class="Heading">Writing Documentation and Tools Needed</span></h4>
<p>If you intend to make your package available to other users it is essential to include documentation explaining how to install and use your programs.</p>
<p>Concerning the installation you should produce a <code class="file">README</code> file which gives a short description of the purpose of the package and contains proper instructions how to install your package. Again, check out some existing packages to get an idea how this could look like.</p>
<p>Documentation for <strong class="pkg">GAP</strong> package should be prepared in an XML-based documentation format that is defined in and can be used with the <strong class="pkg">GAPDoc</strong> package (see <a href="../../pkg/gapdoc/doc/chap1.html#X7D4EE663818DA109"><span class="RefLink">GAPDoc: Introduction and Example</span></a>).</p>
<p>There should be at least a text version of your documentation provided for use in the terminal running <strong class="pkg">GAP</strong> and some nicely printable version in <code class="code">.pdf</code> format. Many <strong class="pkg">GAP</strong> users like to browse the documentation in HTML format via their Web browser. As a package author, you are not obliged to provide an HTML version of your package manual, but if you use the <strong class="pkg">GAPDoc</strong> package you should have no trouble in producing one.</p>
<p>Moreover, using the <strong class="pkg">GAPDoc</strong> package, it is also possible to produce HTML version of the documentation supporting MathJax (<span class="URL"><a href="https://www.mathjax.org/">https://www.mathjax.org/</a></span>) for the high quality rendering of mathematical symbols while viewing it online. For example, if you are viewing the HTML version of the manual, compare how this formula will look with MathJax turned on/off:</p>
<p class="pcenter">[ χ, ψ ] = ( ∑_{g ∈ G} χ(g) ψ(g^{-1}) ) / |G|.</p>
<p>The manual of the <strong class="pkg">Example</strong> package is written in the <strong class="pkg">GAPDoc</strong> format, and commands needed to build it are contained in the file <code class="code">makedocrel.g</code> (you don't need to re-build the manual since it is already included in the package). You will also need to have certain TeX tools installed: to produce manuals in the <code class="code">.pdf</code> format, you need <code class="code">pdflatex</code>.</p>
<p>In principle it is also possible to use alternative documentation systems. Historically, there is one such TeX-based system, which predates <strong class="pkg">GAPDoc</strong>, and which is still in use by several packages. However, we do not recommend using it for new packages.</p>
<p><a id="X79AB306684AC8E7A" name="X79AB306684AC8E7A"></a></p>
<h4>76.7 <span class="Heading">An Example of a <strong class="pkg">GAP</strong> Package</span></h4>
<p>We illustrate the creation of a <strong class="pkg">GAP</strong> package by an example of a very basic package.</p>
<p>Create the following directories in your home directory: <code class="file">.gap</code>, <code class="file">.gap/pkg</code> and <code class="file">.gap/pkg/test</code>. Then inside the directory <code class="file">.gap/pkg/test</code> create an empty file <code class="file">init.g</code>, and a file <code class="file">PackageInfo.g</code> with the following contents:</p>
<div class="example"><pre>
SetPackageInfo( rec(
PackageName := "test",
Version := "1.0",
PackageDoc := rec(
BookName := "test",
SixFile := "doc/manual.six",
),
Dependencies := rec(
GAP := "4.9",
NeededOtherPackages := [ ["GAPDoc", "1.6"] ],
SuggestedOtherPackages := [ ] ),
AvailabilityTest := ReturnTrue ) );
</pre></div>
<p>This file declares the <strong class="pkg">GAP</strong> package with name <q>test</q> in version 1.0. The package documentation consists of one autoloaded book; the <code class="code">SixFile</code> component is needed by the <strong class="pkg">GAP</strong> help system. Package dependencies (picked for the purposes of this example) require at least <strong class="pkg">GAP</strong> 4.9 and <strong class="pkg">GAPDoc</strong> package at version at least 1.6, and these conditions will be checked when the package will be loaded (see <a href="chap76.html#X8180BCDA82587F41"><span class="RefLink">76.18</span></a>). Since there are no requirements that have to be tested, <code class="code">AvailabilityTest</code> just uses <code class="func">ReturnTrue</code> (<a href="chap5.html#X7DB422A2876CCC4D"><span class="RefLink">5.4-1</span></a>).</p>
<p>Now start <strong class="pkg">GAP</strong> (without using the <code class="code">-r</code> option) and the <code class="file">.gap</code> directory will be added to the <strong class="pkg">GAP</strong> root directory to allow <strong class="pkg">GAP</strong> to find the packages installed there (see <a href="chap9.html#X7A4973627A5DB27D"><span class="RefLink">9.2</span></a>).</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">LoadPackage("test");</span>
true
</pre></div>
<p>This <strong class="pkg">GAP</strong> package is too simple to be useful, but we have succeeded in loading it via <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>), satisfying all specified dependencies.</p>
<p><a id="X7A61B1AE7D632E01" name="X7A61B1AE7D632E01"></a></p>
<h4>76.8 <span class="Heading">File Structure</span></h4>
<p>Package files may follow the style used for the <strong class="pkg">GAP</strong> library. Every file in the <strong class="pkg">GAP</strong> library starts with a header that lists the filename, copyright, a short description of the file contents and the original authors of this file, and ends with a comment line <code class="code">#E</code>. Indentation in functions and the use of decorative spaces in the code are left to the decision of the authors of each file. Global (i.e. re-used elsewhere) comments usually are indented by two hash marks and two blanks, in particular, every declaration or method or function installation which is not only of local scope is separated by a header.</p>
<p>Facilities to distribute a document over several files to allow the documentation for parts of some code to be stored in the same file as the code itself are provided by the <strong class="pkg">GAPDoc</strong> package (see <a href="../../pkg/gapdoc/doc/chap4.html#X7A3355C07F57C280"><span class="RefLink">GAPDoc: Distributing a Document into Several Files</span></a>). The same approach is demonstrated by the <strong class="pkg">Example</strong> package. E.g. <code class="file">example/doc/example.xml</code> has the statement <code class="code"><#Include Label="ListDirectory"></code> and <code class="file">example/lib/files.gd</code> contains</p>
<div class="example"><pre>
## <#GAPDoc Label="ListDirectory">
## <ManSection>
## <Func Name="ListDirectory" Arg="[dir]"/>
##
## <Description>
## lists the files in directory <A>dir</A> (a string)
## or the current directory if called with no arguments.
## </Description>
## </ManSection>
## <#/GAPDoc>
DeclareGlobalFunction( "ListDirectory" );
</pre></div>
<p>This is all put together in the file <code class="file">example/makedocrel.g</code> which builds the package documentation, calling <code class="func">MakeGAPDocDoc</code> (<a href="../../pkg/gapdoc/doc/chap5.html#X826F530686F4D052"><span class="RefLink">GAPDoc: MakeGAPDocDoc</span></a>) with locations of library files containing parts of the documentation.</p>
<p>Alternatively, one could use the <strong class="pkg">AutoDoc</strong>, which simplifies writing documentation by generating most of the <strong class="pkg">GAPDoc</strong> code automatically. The equivalent of the fragment of the code above for <strong class="pkg">AutoDoc</strong> would look like</p>
<div class="example"><pre>
#! @Arguments [dir]
#! @Description
#! lists the files in directory <A>dir</A> (a string)
#! or the current directory if called with no arguments.
DeclareGlobalFunction( "ListDirectory" );
</pre></div>
<p><a id="X7A09C63685065B01" name="X7A09C63685065B01"></a></p>
<h4>76.9 <span class="Heading">Creating the PackageInfo.g File</span></h4>
<p>While the minimalistic <code class="file">PackageInfo.g</code> file described in <a href="chap76.html#X79AB306684AC8E7A"><span class="RefLink">76.7</span></a> is enough to let <strong class="pkg">GAP</strong> load the package, and check all specified dependencies, it is actually missing many extra fields which become relevant if you want to distribute your package: they contain lists of authors and/or maintainers including contact information, URLs of the package archives and README files, status information, text for a package overview webpage, and so on. All these details are required for a package to be redistributed with <strong class="pkg">GAP</strong>.</p>
<p>The command <code class="func">ValidatePackageInfo</code> (<a href="chap76.html#X79767C2482FF6F55"><span class="RefLink">76.3-16</span></a>) can be used to get a quick idea about which fields are missing:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">ValidatePackageInfo("PackageInfo.g");</span>
#E component `Subtitle' must be bound to a string
#E component `Date' must be bound to a string of the form `dd/mm/yyyy'
#E component `ArchiveURL' must be bound to a string started with http://, https:// or ftp://
#E component `ArchiveFormats' must be bound to a string
#E component `README_URL' must be bound to a string started with http://, https:// or ftp://
#E component `PackageInfoURL' must be bound to a string started with http://, https:// or ftp://
#E component `AbstractHTML' must be bound to a string
#E component `PackageWWWHome' must be bound to a string started with http://, https:// or ftp://
#E component `ArchiveURLSubset' must be bound to a list of strings denoting relative paths to readable files or directories
#E component `HTMLStart' must be bound to a string denoting a relative path to a readable file
#E component `PDFFile' must be bound to a string denoting a relative path to a readable file
#E component `SixFile' must be bound to a string denoting a relative path to a readable file
#E component `LongTitle' must be bound to a string
false
</pre></div>
<p>We suggest to create a <code class="file">PackageInfo.g</code> file for your package by copying the one in the <strong class="pkg">Example</strong> package, distributed with <strong class="pkg">GAP</strong>, or using the <strong class="pkg">PackageMaker</strong> (<span class="URL"><a href="https://github.com/gap-system/PackageMaker">https://github.com/gap-system/PackageMaker</a></span>), and then adjusting it for your package. Within <strong class="pkg">GAP</strong> you can look at this template file for a list and explanation of all recognised entries by</p>
<div class="example"><pre>
Pager(StringFile(Filename(DirectoriesLibrary(),
"../pkg/example/PackageInfo.g")));
</pre></div>
<p>Instead of populating the rest of the <code class="file">PackageInfo.g</code> by hands, you can also create a basic <strong class="pkg">GAP</strong> package with the help of the tool called <strong class="pkg">PackageMaker</strong>, available at <span class="URL"><a href="https://github.com/gap-system/PackageMaker">https://github.com/gap-system/PackageMaker</a></span>. The <strong class="pkg">PackageMaker</strong> asks several questions about the intended package and then creates a new directory for it and populates it with all the files needed for a basic package.</p>
<p><a id="X7DEACD9786DE29F1" name="X7DEACD9786DE29F1"></a></p>
<h4>76.10 <span class="Heading">Functions and Variables and Choices of Their Names</span></h4>
<p>In writing the <strong class="pkg">GAP</strong> code for your package you need to be a little careful on just how you define your functions and variables.</p>
<p><em>Firstly</em>, in general one should avoid defining functions and variables via assignment statements in the way you would interactively, e.g.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">Squared := x -> x^2;;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">Cubed := function(x) return x^3; end;;</span>
</pre></div>
<p>The reason for this is that such functions and variables are <em>easily overwritten</em> and what's more you are not warned about it when it happens.</p>
<p>To protect a function or variable against overwriting there is the function <code class="func">BindGlobal</code> (<a href="chap4.html#X7D39D3E17CF49F5B"><span class="RefLink">4.9-8</span></a>), or alternatively (and equivalently) you may define a global function via a <code class="func">DeclareGlobalFunction</code> (<a href="chap79.html#X834A8CC587A609BE"><span class="RefLink">79.10-5</span></a>) and <code class="func">InstallGlobalFunction</code> (<a href="chap79.html#X834A8CC587A609BE"><span class="RefLink">79.10-5</span></a>) pair or a global variable via a <code class="func">DeclareGlobalVariable</code> (<a href="chap79.html#X8324B5DE8300E0F2"><span class="RefLink">79.10-2</span></a>) and <code class="func">InstallValue</code> (<a href="chap79.html#X7A23F09886E936D2"><span class="RefLink">79.10-3</span></a>) pair. There are also operations and their methods, and related objects like attributes and filters which also have <code class="code">Declare...</code> and <code class="code">Install...</code> pairs.</p>
<p><em>Secondly</em>, it is a good idea to reduce the chance of accidental overwriting by choosing names for your functions and variables that begin with a string that identifies it with the package, e.g. some of the undocumented functions in the <strong class="pkg">Example</strong> package begin with <code class="code">Eg</code>. This is especially important in cases where you actually want the user to be able to change the value of a function or variable defined by your package, for which you have used direct assignments (for which the user will receive no warning if she accidentally overwrites them). It is also important for functions and variables defined via <code class="code">BindGlobal</code>, <code class="code">DeclareGlobalFunction</code>/<code class="code">InstallGlobalFunction</code> and <code class="code">DeclareGlobalVariable</code>/<code class="code">InstallValue</code>, in order to avoid name clashes that may occur with (extensions of) the <strong class="pkg">GAP</strong> library and other packages.</p>
<p>Additionally, since <strong class="pkg">GAP</strong> 4.5 a package may place global variables into a local namespace as explained in <a href="chap4.html#X7DF8774F7D542298"><span class="RefLink">4.10</span></a> in order to avoid name clashes and preserve compatibility. This new feature allows you to define in your package global variables with the identifier ending with the <code class="code">@</code> symbol, e.g. <code class="code">xYz@</code>. Such variables may be used in your package code safely, as they may be accessed from outside the package only by their full name, i.e. <code class="code">xYz@YourPackageName</code>. This helps to prevent clashes between different packages or between a package and the <strong class="pkg">GAP</strong> library because of the same variable names.</p>
<p>On the other hand, operations and their methods (defined via <code class="func">DeclareOperation</code> (<a href="chap78.html#X843F48137B899BC3"><span class="RefLink">78.1-5</span></a>), <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.3-1</span></a>) etc. pairs) and their relatives do not need this consideration, as they avoid name clashes by allowing for more than one <q>method</q> for the same-named object.</p>
<p>To demonstrate the definition of a function via a <code class="code">DeclareOperation</code>/<code class="code">InstallMethod</code> pair, the method <code class="func">Recipe</code> (<a href="../../pkg/example/doc/chap1.html#X85B83BDB83B1C910"><span class="RefLink">Example: Recipe</span></a>) was included in the <strong class="pkg">Example</strong> package; <code class="code">Recipe( FruitCake );</code> gives a <q>method</q> for making a fruit cake (forgive the pun).</p>
<p><em>Thirdly</em>, functions or variables with <code class="code">Set<var class="Arg">XXX</var></code> or <code class="code">Has<var class="Arg">XXX</var></code> names (even if they are defined as operations) should be avoided as these may clash with objects associated with attributes or properties (attributes and properties <var class="Arg">XXX</var> declared via the <code class="code">DeclareAttribute</code> and <code class="code">DeclareProperty</code> commands have associated with them testers of form <code class="code">Has<var class="Arg">XXX</var></code> and setters of form <code class="code">Set<var class="Arg">XXX</var></code>).</p>
<p><em>Fourthly</em>, it is a good idea to have some convention for internal functions and variables (i.e. the functions and variables you don't intend for the user to use). For example, they might be entirely CAPITALISED.</p>
<p>Additionally, there is a recommended naming convention that the <strong class="pkg">GAP</strong> core system and <strong class="pkg">GAP</strong> packages should not use global variables starting in the lowercase. This allows to reserve variables with names starting in lowercase to the <strong class="pkg">GAP</strong> user so they will never clash with the system. It is extremely important to avoid using for package global variables very short names started in lowercase. For example, such names like <code class="code">cs</code>, <code class="code">exp</code>, <code class="code">ngens</code>, <code class="code">pc</code>, <code class="code">pow</code> which are perfectly fine for local variables, should never be used for globals. Additionally, the package must not have writable global variables with very short names even if they are starting in uppercase, for example, <code class="code">C1</code> or <code class="code">ORB</code>, since they also could be easily overwritten by the user.</p>
<p>It is a good practice to follow naming conventions used in <strong class="pkg">GAP</strong> as explained in <a href="chap5.html#X81F732457F7BC851"><span class="RefLink">5.6</span></a> and <a href="../../doc/tut/chap7.html#X7EA77DE17DD8A231"><span class="RefLink">Tutorial: Changing the Structure</span></a>, which might help users to memorize or even guess names of functions provided by the package.</p>
<p><em>Finally</em>, note the advantage of using <code class="code">DeclareGlobalFunction</code>/<code class="code">InstallGlobalFunction</code>, <code class="code">DeclareGlobalVariable</code>/<code class="code">InstallValue</code>, etc. pairs (rather than <code class="code">BindGlobal</code>) to define functions and variables, which allow the package author to organise her function- and variable- definitions in any order without worrying about any interdependence. The <code class="code">Declare...</code> statements should go in files with <code class="code">.gd</code> extensions and be loaded by <code class="code">ReadPackage</code> statements in the package <code class="file">init.g</code> file, and the <code class="code">Install...</code> definitions should go in files with <code class="code">.gi</code> extensions and be loaded by <code class="code">ReadPackage</code> statements in the package <code class="file">read.g</code> file; this ensures that the <code class="code">.gi</code> files are read <em>after</em> the <code class="code">.gd</code> files. All other package code should go in <code class="code">.g</code> files (other than the <code class="file">init.g</code> and <code class="file">read.g</code> files themselves) and be loaded via <code class="code">ReadPackage</code> statements in the <code class="file">init.g</code> file.</p>
<p>In conclusion, here is some practical advice on how to check which variables are used by the package.</p>
<p>Firstly, there is a function <code class="func">ShowPackageVariables</code> (<a href="chap76.html#X7D34AC3287611B15"><span class="RefLink">76.3-17</span></a>). If the package <var class="Arg">pkgname</var> is available but not yet loaded then <code class="code">ShowPackageVariables( pkgname )</code> prints a list of global variables that become bound and of methods that become installed when the package is loaded (for that, the package will be actually loaded, so <code class="code">ShowPackageVariables</code> can be called only once for the same package in the same <strong class="pkg">GAP</strong> session.) The second optional argument <var class="Arg">version</var> may specify a particular package version to be loaded. An error message will be printed if (the given version of) the package is not available or already loaded.</p>
<p>Info lines for undocumented variables will be marked with an asterisk <code class="code">*</code>. Note that the <strong class="pkg">GAP</strong> help system is case insensitive, so it is difficult to document identifiers that differ only by case.</p>
<p>The following entries are omitted from the list: default setter methods for attributes and properties that are declared in the package, and <code class="code">Set<var class="Arg">attr</var></code> and <code class="code">Has<var class="Arg">attr</var></code> type variables where <var class="Arg">attr</var> is an attribute or property.</p>
<p>For example, for the <strong class="pkg">Example</strong> package it may produce the output looking like this:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">ShowPackageVariables("example");</span>
----------------------------------------------------------------
Loading Example 3.3 (Example/Template of a GAP Package)
by Werner Nickel (http://www.mathematik.tu-darmstadt.de/~nickel),
Greg Gamble (http://www.math.rwth-aachen.de/~Greg.Gamble), and
Alexander Konovalov (http://www.cs.st-andrews.ac.uk/~alexk/).
----------------------------------------------------------------
new global functions:
EgSeparatedString( str, c )*
FindFile( dir, file )
HelloWorld( )
ListDirectory( arg )
LoadedPackages( )
WhereIsPkgProgram( prg )
Which( prg )
new global variables:
FruitCake
new operations:
Recipe( arg )
new methods:
Recipe( cake )
</pre></div>
<p>Another trick is to start <strong class="pkg">GAP</strong> with <code class="code">-r -A</code> options, immediately load your package and then call <code class="func">NamesUserGVars</code> (<a href="chap4.html#X870169447AF490D8"><span class="RefLink">4.9-11</span></a>) which returns a list of the global variable names created since the library was read, to which a value is currently bound. For example, for the <strong class="pkg">Example</strong> it produces</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">NamesUserGVars();</span>
[ "EgSeparatedString", "FindFile", "FruitCake", "HelloWorld", "ListDirectory",
"LoadedPackages", "Recipe", "WhereIsPkgProgram", "Which" ]
</pre></div>
<p>but for packages with dependencies it will also contain variables created by other packages. Nevertheless, it may be a useful check to search for unwanted variables appearing after package loading. A potentially dangerous situation which should be avoided is when the package uses some simply named temporary variables at the loading stage. Such <q>phantom</q> variables may then remain unnoticed and, as a result, there will be no warnings if the user occasionally uses the same name as a local variable name in a function. Even more dangerous is the case when the user variable with the same name already exists before the package is loaded so it will be silently overwritten.</p>
<p><a id="X7928799186F9B2FE" name="X7928799186F9B2FE"></a></p>
<h4>76.11 <span class="Heading">Package Dependencies (Requesting one <strong class="pkg">GAP</strong> Package from within Another)</span></h4>
<p>It is possible for one <strong class="pkg">GAP</strong> package <code class="code">A</code> to require another package <code class="code">B</code>. For that, one simply adds the name and the (least) version number of the package <code class="code">B</code> to the <code class="code">NeededOtherPackages</code> component of the <code class="code">Dependencies</code> component of the <code class="file">PackageInfo.g</code> file of the package <code class="code">A</code>. In this situation, loading the package <code class="code">A</code> forces that also the package <code class="code">B</code> is loaded, and that <code class="code">A</code> cannot be loaded if <code class="code">B</code> is not available.</p>
<p>If <code class="code">B</code> is not essential for <code class="code">A</code> but should be loaded if it is available (for example because <code class="code">B</code> provides some improvements of the main system that are useful for <code class="code">A</code>) then the name and the (least) version number of <code class="code">B</code> should be added to the <code class="code">SuggestedOtherPackages</code> component of the <code class="code">Dependencies</code> component of the <code class="file">PackageInfo.g</code> file of <code class="code">A</code>. In this situation, loading <code class="code">A</code> forces an attempt to load also <code class="code">B</code>, but <code class="code">A</code> is loaded even if <code class="code">B</code> is not available.</p>
<p>All package dependencies must be documented explicitly in the <code class="file">PackageInfo.g</code> file. It is important to properly identify package dependencies and make the right decision whether the other package should be <q>needed</q> or <q>suggested</q>. For example, declaring package as <q>needed</q> when <q>suggested</q> might be sufficient may prevent loading of packages under Windows for no good reason.</p>
<p>It is not appropriate to explicitly call <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>) <em>when the package is loaded</em>, since this may distort the order of package loading and result in warning messages. It is recommended to turn such dependencies into needed or suggested packages. For example, a package can be designed in such a way that it can be loaded with restricted functionality if another package (or standalone program) is missing, and in this case the missing package (or binary) is <em>suggested</em>. Alternatively, if the package author decides that loading the package in this situation makes no sense, then the missing component is <em>needed</em>.</p>
<p>On the other hand, if <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>) is called inside functions of the package then there is no such problem, provided that these functions are called only after the package has been loaded, so it is not necessary to specify the other package as suggested. The same applies to test files and manual examples, which may be simply extended by calls to <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>).</p>
<p>It may happen that a package B that is listed as a suggested package of package A is actually needed by A. If no explicit <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>) calls for B occur in A at loading time, this can now be detected using the new possibility to load a package without loading its suggested packages using the global option <code class="code">OnlyNeeded</code> which can be used to (recursively) suppress loading the suggested packages of the package in question. Using this option, one can check whether errors or warnings appear when B is not available (note that this option should be used only for such checks to simulate the situation when package B is not available; it is not supposed to be used in an actual <strong class="pkg">GAP</strong> session when package B will be loaded later, since this may cause problems). In case of any errors or warnings, their consequence can then be either turning B into a needed package or (since apparently B was not intended to become a needed package) changing the code accordingly. Only if package A calls <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>) for B at loading time (see above) then package B needs to be <em>deinstalled</em> (i.e. removed) to test loading of A without B.</p>
<p><a id="X783A5F3D87F9AF78" name="X783A5F3D87F9AF78"></a></p>
<h4>76.12 <span class="Heading">Extensions Provided by a Package</span></h4>
<p>Sometimes a package <code class="code">A</code> can provide additional functionality, such as better methods or additional data, if some other packages <code class="code">B</code>, <code class="code">C</code>, etc. are loaded. However, one would like package <code class="code">A</code> to still be usable without these additional packages, and therefore <code class="code">B</code>, <code class="code">C</code>, etc. shall not be regarded as needed packages (see Section <a href="chap76.html#X7928799186F9B2FE"><span class="RefLink">76.11</span></a>) of <code class="code">A</code>.</p>
<p>One way to deal with this situation is to put those parts of code of <code class="code">A</code> that depend on <code class="code">B</code>, <code class="code">C</code>, etc., into files that get read only in the situation that the packages in question have actually been loaded into the current <strong class="pkg">GAP</strong> session.</p>
<p>However, this leaves the question when to load these files of a conditional <em>extension</em> of <code class="code">A</code>. In the past, the only option for <code class="code">A</code> was to check for the presence of <code class="code">B</code>, <code class="code">C</code>, etc., while it itself was being loaded. With this setup, it depends on the order in which packages get loaded whether some feature is available or not: If <code class="code">B</code> is loaded before <code class="code">A</code>, the extension might be loaded as well; if <code class="code">B</code> is loaded only after <code class="code">A</code>, then the extension is not loaded.</p>
<p>To deal with this issue of conditional extensions of packages, <strong class="pkg">GAP</strong> offers a dedicated mechanism: The <code class="code">Extensions</code> component of the <code class="file">PackageInfo.g</code> file of <code class="code">A</code> is a list of declarations of conditional extension of <code class="code">A</code>, each being a record with the following components.</p>
<dl>
<dt><strong class="Mark"><code class="code">needed</code></strong></dt>
<dd><p>a list of the form <code class="code">[ [ pkgname1, version1 ], [ pkgname2, version2 ], </code><span class="SimpleMath">...</span><code class="code"> ]</code>, meaning that the extension shall be loaded as soon as all packages <code class="code">pkgname1</code>, <code class="code">pkgname2</code>, <span class="SimpleMath">...</span>, with versions (at least) <code class="code">version1</code>, <code class="code">version2</code>, <span class="SimpleMath">...</span>, have been loaded, and</p>
</dd>
<dt><strong class="Mark"><code class="code">filename</code></strong></dt>
<dd><p>the path, relative to the package directory of <code class="code">A</code>, of a file such that reading this file will load the code of the extension.</p>
</dd>
</dl>
<p>As an example suppose the following is part of the <code class="file">PackageInfo.g</code>. Then <strong class="pkg">GAP</strong> will load the file <code class="file">fileForB.gd</code> as soon as package <code class="code">B</code> is loaded in version 0.6 or newer, and <code class="file">fileForCD.gi</code> once package <code class="code">C</code> and <code class="code">D</code> are loaded in version 1.2 and 0.1 or newer respectively.</p>
<div class="example"><pre>
Extensions := [
rec(
needed := [ ["B", "0.6"] ],
filename := "gap/fileForB.gd",
),
rec(
needed := [ ["C", "1.2"] , ["D", "0.1"] ],
filename := "gap/fileForCD.gi",
)
],
</pre></div>
<p>Whenever <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>) is called, <strong class="pkg">GAP</strong> checks for package extensions whose conditions now are satisfied, and loads them.</p>
<p>For example, package <code class="code">A</code> can be loaded early in a <strong class="pkg">GAP</strong> session, and declare in its <code class="file">PackageInfo.g</code> the availability of an extension that requires package <code class="code">B</code>. If <code class="code">B</code> has not yet been loaded then this extension will not be loaded together with <code class="code">A</code>. However, as soon as <code class="code">B</code> gets (installed and) loaded later in the session, also the extension of <code class="code">A</code> will automatically get loaded.</p>
<p>The contents of <code class="code">Extensions</code> in a <code class="file">PackageInfo.g</code> file does not affect the lists of needed or suggested packages. If an extension of <code class="code">A</code> is beneficial for the functions of <code class="code">A</code> then it makes sense to list the packages needed for the extension among the suggested packages of <code class="code">A</code>, but this may not be the case if the extension is beneficial only for the functions of its needed packages.</p>
<p><a id="X7A7835A5797AF766" name="X7A7835A5797AF766"></a></p>
<h4>76.13 <span class="Heading">Declaration and Implementation Part of a Package</span></h4>
<p>When <strong class="pkg">GAP</strong> packages require each other in a circular way, a <q>bootstrapping</q> problem arises of defining functions before they are called. The same problem occurs in the <strong class="pkg">GAP</strong> library, and it is resolved there by separating declarations (which define global variables such as filters and operations) and implementations (which install global functions and methods) in different files. Any implementation file may use global variables defined in any declaration file. <strong class="pkg">GAP</strong> initially reads all declaration files (in the library they have a <code class="code">.gd</code> suffix) and afterwards reads all implementation files (which have a <code class="code">.gi</code> suffix).</p>
<p>Something similar is possible for <strong class="pkg">GAP</strong> packages: if a file <code class="file">read.g</code> exists in the home directory of the package, this file is read only <em>after</em> all the <code class="file">init.g</code> files of all (implicitly) required <strong class="pkg">GAP</strong> packages are read. Thus one can separate declaration and implementation for a <strong class="pkg">GAP</strong> package in the same way as is done for the <strong class="pkg">GAP</strong> library, by creating a file <code class="file">read.g</code>, restricting the <code class="func">ReadPackage</code> (<a href="chap76.html#X870954577B27DCAB"><span class="RefLink">76.3-1</span></a>) statements in <code class="file">init.g</code> to only read those files of the package that provide declarations, and to read the implementation files from <code class="file">read.g</code>.</p>
<p><em>Examples:</em></p>
<p>Suppose that there are two packages <code class="code">A</code> and <code class="code">B</code>, each with files <code class="file">init.g</code> and <code class="file">read.g</code>.</p>
<ul>
<li><p>If package <code class="code">A</code> suggests or needs package <code class="code">B</code> and package <code class="code">B</code> does not need or suggest any other package then first <code class="file">init.g</code> of <code class="code">B</code> is read, then <code class="file">read.g</code> of <code class="code">B</code>, then <code class="file">init.g</code> of <code class="code">A</code>, then <code class="file">read.g</code> of <code class="code">A</code>.</p>
</li>
<li><p>If package <code class="code">A</code> suggests or needs package <code class="code">B</code> and package <code class="code">B</code> (or a package that is suggested or needed by <code class="code">B</code>) suggests or needs package <code class="code">A</code> then first the files <code class="file">init.g</code> of <code class="code">A</code> and <code class="code">B</code> are read (in an unspecified order) and then the files <code class="file">read.g</code> of <code class="code">A</code> and <code class="code">B</code> (in the same order).</p>
</li>
</ul>
<p>In general, when <strong class="pkg">GAP</strong> is asked to load a package then first the dependencies between this packages and its needed and suggested packages are inspected (recursively), and a list of package sets is computed such that no cyclic dependencies occur between different package sets and such that no package in any of the package sets needs any package in later package sets. Then <strong class="pkg">GAP</strong> runs through the package sets and reads for each set first all <code class="file">init.g</code> files and then all <code class="file">read.g</code> files of the packages in the set. (There is one exception from this rule: Whenever packages are autoloaded before the implementation part of the <strong class="pkg">GAP</strong> library is read, only the <code class="file">init.g</code> files of the packages are read; as soon as the <strong class="pkg">GAP</strong> library has been read, the <code class="file">read.g</code> files of these packages are also read, and afterwards the above rule holds.)</p>
<p>It can happen that some code of a package depends on the availability of suggested packages, i.e., different initialisations are performed depending on whether a suggested package will eventually be loaded or not. One can test this condition with the function <code class="func">IsPackageMarkedForLoading</code> (<a href="chap76.html#X8067348B836BAF37"><span class="RefLink">76.3-4</span></a>). In particular, one should <em>not</em> call (and use the value returned by this call) the function <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>) inside package code that is read during package loading. Note that for debugging purposes loading suggested packages may have been deliberately disabled via the global option <code class="code">OnlyNeeded</code>.</p>
<p>Note that the separation of the <strong class="pkg">GAP</strong> code of packages into declaration part and implementation part does in general <em>not</em> allow one to actually <em>call</em> functions from a package when the implementation part is read. For example, in the case of a <q>cyclic dependency</q> as in the second example above, suppose that <code class="code">B</code> provides a new function <code class="code">f</code> or a new global record <code class="code">r</code> which are declared in the declaration part of <code class="code">B</code>. Then the code in the implementation part of <code class="code">A</code> may contain calls to the functions defined in the declaration part of <code class="code">B</code>. However, the implementation part of <code class="code">A</code> may be read <em>before</em> the implementation part of <code class="code">B</code>. So one can in general not assume that during the loading of <code class="code">A</code>, the function <code class="code">f</code> can be called, or that one can access components of the record <code class="code">r</code>.</p>
<p>If one wants to call the function <code class="code">f</code> or to access components of the record <code class="code">r</code> in the code of the package <code class="code">A</code> then the problem is that it may be not possible to determine a cyclic dependency between <code class="code">A</code> and <code class="code">B</code> from the packages <code class="code">A</code> and <code class="code">B</code> alone. A safe solution is then to design <code class="code">A</code> in such a way that the code that calls <code class="code">f</code> or accesses <code class="code">r</code> belongs to <em>package extensions</em> of <code class="code">A</code> that get loaded only after <code class="code">B</code> has been loaded; see Section <a href="chap76.html#X783A5F3D87F9AF78"><span class="RefLink">76.12</span></a> for details.</p>
<p>In the case of cyclic dependencies, one solution for the above problem might be to delay those computations (typically initialisations) in package <code class="code">A</code> that require package <code class="code">B</code> to be loaded until all required packages are completely loaded. This can be done by moving the declaration and implementation of the variables that are created in the initialisation into a separate file and to declare these variables in the <code class="file">init.g</code> file of the package, via a call to <code class="func">DeclareAutoreadableVariables</code> (<a href="chap76.html#X8495E5327D563AC3"><span class="RefLink">76.3-10</span></a>) (see also <a href="chap76.html#X7D7F236A78106358"><span class="RefLink">76.14</span></a>).</p>
<p><a id="X7D7F236A78106358" name="X7D7F236A78106358"></a></p>
<h4>76.14 <span class="Heading">Autoreadable Variables</span></h4>
<p>Package files containing method installations must be read when the package is loaded. For package files <em>not</em> containing method installations (this applies, for example, to many data files) another mechanism allows one to delay reading such files until the data are actually accessed. See <a href="chap76.html#X8495E5327D563AC3"><span class="RefLink">76.3-10</span></a> for further details.</p>
<p><a id="X7C8CCF057806EFD0" name="X7C8CCF057806EFD0"></a></p>
<h4>76.15 <span class="Heading">Standalone Programs in a <strong class="pkg">GAP</strong> Package</span></h4>
<p><strong class="pkg">GAP</strong> packages that involve stand-alone programs are fundamentally different from <strong class="pkg">GAP</strong> packages that consist entirely of <strong class="pkg">GAP</strong> code.</p>
<p>This difference is threefold: A user who installs the <strong class="pkg">GAP</strong> package must also compile (or install) the package's binaries, the package must check whether the binaries are indeed available, and finally the <strong class="pkg">GAP</strong> code of the package has to start the external binary and to communicate with it. We will cover these three points in the following sections.</p>
<p>If the package does not solely consist of an interface to an external binary and if the external program called is not just special-purpose code, but a generally available program, chances are high that sooner or later other <strong class="pkg">GAP</strong> packages might also require this program. We therefore strongly recommend the provision of a documented <strong class="pkg">GAP</strong> function that will call the external binary. We also suggest to create actually two <strong class="pkg">GAP</strong> packages; the first providing only the binary and the interface and the second (requiring the first, see <a href="chap76.html#X7928799186F9B2FE"><span class="RefLink">76.11</span></a>) being the actual <strong class="pkg">GAP</strong> package.</p>
<p><a id="X7CD9ED5C86725ACF" name="X7CD9ED5C86725ACF"></a></p>
<h5>76.15-1 <span class="Heading">Installation of <strong class="pkg">GAP</strong> Package Binaries</span></h5>
<p>The scheme for the installation of package binaries which is described further on is intended to permit the installation on different architectures which share a common file system (and share the architecture independent file).</p>
<p>A <strong class="pkg">GAP</strong> package which includes external binaries contains a <code class="file">bin</code> subdirectory. This subdirectory in turn contains subdirectories for the different architectures on which the <strong class="pkg">GAP</strong> package binaries are installed. The names of these directories must be the same as the names of the architecture dependent subdirectories of the main <code class="file">bin</code> directory. Unless you use a tool like <code class="code">autoconf</code> yourself, you must obtain the correct name of the binary directory from the main <strong class="pkg">GAP</strong> branch. To help with this, the main <strong class="pkg">GAP</strong> directory contains a file <code class="file">sysinfo.gap</code> which assigns the shell variable <code class="code">GAParch</code> to the proper name as determined by <strong class="pkg">GAP</strong>'s <code class="code">configure</code> process. For example on a Linux system, the file <code class="file">sysinfo.gap</code> may look like this:</p>
<div class="example"><pre>
GAParch=i586-unknown-linux2.0.31-gcc
</pre></div>
<p>We suggest that your <strong class="pkg">GAP</strong> package contains a file <code class="file">configure</code> which is called with the path of the <strong class="pkg">GAP</strong> root directory as parameter. This file then will read <code class="file">sysinfo.gap</code> and set up everything for compiling under the given architecture (for example creating a <code class="file">Makefile</code> from <code class="file">Makefile.in</code>). As initial templates, you may use installation scripts of the <strong class="pkg">Example</strong> package or files generated with the help of <strong class="pkg">PackageMaker</strong>.</p>
<p><a id="X7E4F39867CCC6026" name="X7E4F39867CCC6026"></a></p>
<h5>76.15-2 <span class="Heading">Test for the Existence of GAP Package Binaries</span></h5>
<p>If an external binary is essential for the workings of a <strong class="pkg">GAP</strong> package, the function stored in the component <code class="code">AvailabilityTest</code> of the <code class="file">PackageInfo.g</code> file of the package should test whether the program has been compiled on the architecture (and inhibit package loading if this is not the case). This is especially important if the package is loaded automatically.</p>
<p>The easiest way to accomplish this is to use <code class="func">Filename</code> (<a href="chap9.html#X7E352E1F87060602"><span class="RefLink">9.5-1</span></a>) for checking for the actual binaries in the path given by <code class="func">DirectoriesPackagePrograms</code> (<a href="chap76.html#X794508E5811D3BC9"><span class="RefLink">76.3-8</span></a>) for the respective package. For example the <strong class="pkg">example</strong> <strong class="pkg">GAP</strong> package could use the following function to test whether the binary <code class="file">hello</code> has been compiled; it will issue a warning if not, and will only load the package if the binary is indeed available:</p>
<div class="example"><pre>
...
AvailabilityTest := function()
local path,file;
# test for existence of the compiled binary
path:= DirectoriesPackagePrograms( "example" );
file:= Filename( path, "hello" );
if file = fail then
LogPackageLoadingMessage( PACKAGE_WARNING,
[ "The program `hello' is not compiled,",
"`HelloWorld()' is thus unavailable.",
"See the installation instructions;",
"type: ?Installing the Example package" ] );
fi;
return file <> fail;
end,
...
</pre></div>
<p>However, if you look at the actual <code class="file">PackageInfo.g</code> file of the <strong class="pkg">example</strong> package, you will see that its <code class="code">AvailabilityTest</code> function always returns <code class="keyw">true</code>, and just logs the warning if the binary is not available (which may be later viewed with <code class="func">DisplayPackageLoadingLog</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-6</span></a>)). This means that the binary is not regarded as essential for this package.</p>
<p>You might also have to cope with the situation that external binaries will only run under UNIX (and not e.g. under Windows), or may not compile with some compilers or default compiler options. See <a href="chap3.html#X83BF07587F2CC6CD"><span class="RefLink">3.4</span></a> for information on how to test for the architecture.</p>
<p>Package using a kernel module (see <a href="chap76.html#X85672DDD7D34D5F0"><span class="RefLink">76.3-11</span></a>), one may use a test like this:</p>
<div class="example"><pre>
...
AvailabilityTest := function()
# see if example.so exists and is a loadable kernel extension
if not IsKernelExtensionAvailable("example") then
LogPackageLoadingMessage( PACKAGE_WARNING,
[ "The kernel extension `example' is unavailable,",
"perhaps it needs to be recompiled?",
"See the installation instructions;",
"type: ?Installing the Example package" ] );
return false;
fi;
return true;
end,
...
</pre></div>
<p>Last but not least: do not print anything in the <code class="code">AvailabilityTest</code> function of the package via <code class="code">Print</code> or <code class="code">Info</code>. Instead one should call <code class="func">LogPackageLoadingMessage</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-6</span></a>) to store a message which may be viewed later with <code class="func">DisplayPackageLoadingLog</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-6</span></a>) (the latter two functions have been introduced in <strong class="pkg">GAP</strong> 4.5)</p>
<p><a id="X8438685184FCEFEC" name="X8438685184FCEFEC"></a></p>
<h5>76.15-3 <span class="Heading">Calling of and Communication with External Binaries</span></h5>
<p>There are two reasons for this: the input data has to be passed on to the stand-alone program and the stand-alone program has to be started from within <strong class="pkg">GAP</strong>.</p>
<p>There are two principal ways of doing this.</p>
<p>The first possibility is to write all the data for the stand-alone to one or several files, then start the stand-alone with <code class="func">Process</code> (<a href="chap11.html#X7B09033178D1107A"><span class="RefLink">11.1-1</span></a>) or <code class="func">Exec</code> (<a href="chap11.html#X81402C91833986FC"><span class="RefLink">11.1-2</span></a>) which then writes the output data to file, and finally read in the standalone's output file.</p>
<p>The second way is interfacing via input-output streams, see Section <a href="chap10.html#X8563EF8387236417"><span class="RefLink">10.8</span></a>.</p>
<p>Some <strong class="pkg">GAP</strong> packages use kernel modules (see <a href="chap76.html#X85672DDD7D34D5F0"><span class="RefLink">76.3-11</span></a>) instead of external binaries. 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 advise you to look at existing examples of such packages and get in touch with <strong class="pkg">GAP</strong> developers if you plan to develop such a package.</p>
<p><a id="X78969BA778DDE385" name="X78969BA778DDE385"></a></p>
<h4>76.16 <span class="Heading">Having an InfoClass</span></h4>
<p>It is a good idea to declare an <code class="code">InfoClass</code> for your package. This gives the package user the opportunity to control the verbosity of output and/or the possibility of receiving debugging information (see <a href="chap7.html#X7A9C902479CB6F7C"><span class="RefLink">7.4</span></a>). Below, we give a quick overview of its utility.</p>
<p>An <code class="code">InfoClass</code> is defined with a <code class="code">DeclareInfoClass( <var class="Arg">InfoPkgname</var> );</code> statement and may be set to have an initial <code class="code">InfoLevel</code> other than the zero default (which means no <code class="code">Info</code> statement is to output information) via a <code class="code">SetInfoLevel( <var class="Arg">InfoPkgname</var>, <var class="Arg">level</var> );</code> statement. An initial <code class="code">InfoLevel</code> of 1 is typical.</p>
<p><code class="code">Info</code> statements have the form: <code class="code">Info( <var class="Arg">InfoPkgname</var>, <var class="Arg">level</var>, <var class="Arg">expr1</var>, <var class="Arg">expr2</var>, ...);</code> where the expression list <code class="code"><var class="Arg">expr1</var>, <var class="Arg">expr2</var>, ...</code> appears just like it would in a <code class="code">Print</code> statement. The only difference is that the expression list is only printed (or even executed) if the <code class="code">InfoLevel</code> of <var class="Arg">InfoPkgname</var> is at least <var class="Arg">level</var>.</p>
<p><a id="X784E0A5A7DB88332" name="X784E0A5A7DB88332"></a></p>
<h4>76.17 <span class="Heading">The Banner</span></h4>
<p>When the package is loaded, <strong class="pkg">GAP</strong> will display a default package banner, constructed from the package metadata provided in the <code class="file">PackageInfo.g</code> file.</p>
<p>Alternatively, the package may establish its own banner by assigning either a string to the <code class="code">BannerString</code> field of the record argument of <code class="code">SetPackageInfo</code> in the <code class="file">PackageInfo.g</code> file or a function to the <code class="code">BannerFunction</code> field, which takes this record as its unique argument. The latter possibility can be useful if the banner shall show information that is available only at runtime.</p>
<p>If you will be designing a banner for your package, it is a good idea to suggest there how to access package documentation. For example, the banner of the <strong class="pkg">Example</strong> package says:</p>
<div class="example"><pre>
For help, type: ?Example package
</pre></div>
<p>In order for this to display the introduction of the <strong class="pkg">Example</strong> package the index-entry <code class="code"><Index>Example package</Index></code> was added just before the first paragraph of the introductory section in the file <code class="file">doc/example.xml</code> of the <strong class="pkg">Example</strong> package.</p>
<p><a id="X8180BCDA82587F41" name="X8180BCDA82587F41"></a></p>
<h4>76.18 <span class="Heading">Version Numbers</span></h4>
<p>Version numbers are strings containing nonnegative integers separated by non-numeric characters. They are compared by <code class="func">CompareVersionNumbers</code> (<a href="chap76.html#X787DFEB383545A49"><span class="RefLink">76.3-9</span></a>) which first splits them at non-digit characters and then lexicographically compares the resulting integer lists. Thus version <code class="code">"2-3"</code> is larger than version <code class="code">"2-2-5"</code> but smaller than <code class="code">"4r2p3"</code> or <code class="code">"11.0"</code>.</p>
<p>It is possible for code to require <strong class="pkg">GAP</strong> packages in certain versions. In this case, all versions, whose number is equal or larger than the requested number are acceptable. It is the task of the package author to provide upwards compatibility.</p>
<p>Loading a specific version of a package (that is, <em>not</em> one with a larger version number) can be achieved by prepending <code class="code">=</code> to the desired version number. For example, <code class="code">LoadPackage( "example", "=1.0" )</code> will load version <code class="code">"1.0"</code> of the package <code class="code">"example"</code>, even if version <code class="code">"1.1"</code> is available. As a consequence, version numbers must not start with <code class="code">=</code>, so <code class="code">"=1.0"</code> is not a valid version number.</p>
<p>Package authors should choose a version numbering scheme that admits a new version number even after tiny changes to the package, and ensure that version numbers of successive package versions increase. The automatic update of package archives in the <strong class="pkg">GAP</strong> distribution will only work if a package has a new version number.</p>
<p>It is a well-established custom to name package archives like <code class="file">name-version.tar.gz</code>, <code class="file">name-version.tar.bz2</code> etc., where <code class="code">name</code> is the lower case name, and <code class="code">version</code> is the version (another custom is that the archive then should extract to a directory that has exactly the name <code class="file">name-version</code>).</p>
<p>It is very important that there should not ever be, for a given <strong class="pkg">GAP</strong> package, two different archives with the same package version number. If you make changes to your package and place a new archive of the package onto the public server, please ensure that a new archive has a new version number. This should be done even for very minor changes.</p>
<p>For most of the packages it will be inappropriate to re-use the date of the release as a version number. It is much more obvious how big are the changes between versions "4.4.12", "4.5.1" and "4.5.2" than between versions "2008.12.17", "2011.04.15" and "2011.09.14". The concept of using version numbers to convey the meaning of the status of the code and the way it has been modified is known as <q>Semantic Versioning</q>, see <span class="URL"><a href="https://semver.org/">https://semver.org/</a></span> for further recommendations on its use.</p>
<p>Since version information is duplicated in several places throughout the package documentation, for <strong class="pkg">GAPDoc</strong>-based manuals you may define the version and the release manual in the comments in <code class="file">PackageInfo.g</code> file close to the place where you specified its <code class="code">Version</code> and <code class="code">Date</code> components, for example</p>
<div class="example"><pre>
## <#GAPDoc Label="PKGVERSIONDATA">
## <!ENTITY VERSION "3.3">
## <!ENTITY RELEASEDATE "12/09/2017">
## <!ENTITY RELEASEYEAR "2017">
## <#/GAPDoc>
</pre></div>
<p>notify <code class="func">MakeGAPDocDoc</code> (<a href="../../pkg/gapdoc/doc/chap5.html#X826F530686F4D052"><span class="RefLink">GAPDoc: MakeGAPDocDoc</span></a>) that a part of the document is stored in <code class="file">PackageInfo.g</code> (see <code class="file">example/makedocrel.g</code>), read this data into the header of the main document via <code class="code"><#Include Label="PKGVERSIONDATA"></code> directive and then use them via &VERSION; and &RELEASEDATE; entities almost everywhere where you need to refer to them (most commonly, in the title page and installation instructions).</p>
<p><a id="X8559D1FF7C9B7D14" name="X8559D1FF7C9B7D14"></a></p>
<h4>76.19 <span class="Heading">Testing a <strong class="pkg">GAP</strong> package</span></h4>
<p>There are several aspects of testing a <strong class="pkg">GAP</strong> package.</p>
<p>First, one should ensure that the package functionality works as expected. Below we give an advice on creating test files for automated tests that may be run by package authors, by <strong class="pkg">GAP</strong> developers as part of the release preparation, and by package users interested in checking that the package works. Such tests should be included in the package distribution, and the responsibility for ensuring that they pass stays with package authors.</p>
<p>Second, the package should cleanly integrate into the <strong class="pkg">GAP</strong> system and other packages, and should not break their functionality. In particular, all tests from the standard <strong class="pkg">GAP</strong> testing suite should pass if the package is loaded. This is more comprehensive and time consuming test, which <strong class="pkg">GAP</strong> developers regularly run using special tools. They will report to you any detected issues. Below we explain how to do several simple and less time consuming checks which package authors are recommended to perform themselves.</p>
<p><a id="X85CA2F547CF87666" name="X85CA2F547CF87666"></a></p>
<h5>76.19-1 <span class="Heading">Tests files for a GAP package</span></h5>
<p>The (optional) <code class="file">tst</code> directory of your package may contain as many tests of the package functionality as appears appropriate. These tests should be organised into test files similarly to those in the <code class="file">tst</code> directory of the <strong class="pkg">GAP</strong> distribution as documented in <a href="chap7.html#X801051CC86594630"><span class="RefLink">7.10</span></a>.</p>
<p>For a deposited package, a test file with a basic test of the package (for example, to check that it works as expected and/or that the manual examples are correct) may be specified in the component <code class="code">TestFile</code> in the <code class="file">PackageInfo.g</code> to be included in the <strong class="pkg">GAP</strong> standard test suite. This file can either consist of calls of <code class="func">TestDirectory</code> (<a href="chap7.html#X87AF67528799481F"><span class="RefLink">7.10-3</span></a>) or <code class="func">Test</code> (<a href="chap7.html#X87712F9D8732193C"><span class="RefLink">7.10-2</span></a>) (in this case, it is common to call it <code class="file">testall.g</code>) or be itself a test file having an extension <code class="file">.tst</code> and supposed to be read via <code class="func">Test</code> (<a href="chap7.html#X87712F9D8732193C"><span class="RefLink">7.10-2</span></a>). It is assumed that the latter case occurs if and only if the file contains the substring</p>
<p> <code class="code">"gap> START_TEST("</code></p>
<p>(with exactly one space after the <strong class="pkg">GAP</strong> prompt).</p>
<p>For deposited packages, these tests are run by the <strong class="pkg">GAP</strong> Group regularly, as a part of the standard <strong class="pkg">GAP</strong> test suite. For the efficient testing it is important that the test specified in the <code class="file">PackageInfo.g</code> file does not display any output (e.g. no test progress indicators) except reporting discrepancies if such occur and the completion report as in the example below:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">Test("tst/testall.tst");</span>
Example package: testall.tst
true
</pre></div>
<p>Tests which produce extended output and/or require substantial runtime are not supposed to be a part of the <strong class="pkg">GAP</strong> standard test suite but may be placed in the <code class="file">tst</code> directory of the packages with further instructions on how to run them elsewhere.</p>
<p>Because of different approaches to testing, used by different packages, it is not always easy to identify whether an automated test passed or failed. Presently, automated detection works fine if a package uses a single <code class="file">.tst</code> file or uses <code class="func">TestDirectory</code> (<a href="chap7.html#X87AF67528799481F"><span class="RefLink">7.10-3</span></a>) with the <code class="code">exitGAP</code> option set to <code class="keyw">true</code> to run a collection of tests and then exits <strong class="pkg">GAP</strong> in a way that allows an automated test setup to determine whether the test passed or failed:</p>
<div class="example"><pre>
TestDirectory(DirectoriesPackageLibrary("packagename", "tst"), rec(exitGAP := true));
</pre></div>
<p>If one needs a more sophisticated test file, then it should end with an invocation of <code class="func">ForceQuitGap</code> (<a href="chap6.html#X85A8DD6B7A20DD89"><span class="RefLink">6.7-4</span></a>) with an argument that indicates whether the tests overall passed (<code class="keyw">true</code>) or failed (<code class="keyw">false</code> or <code class="keyw">fail</code>). For example, if the test result is stored in a variable <code class="code">testresult</code> then you can do this:</p>
<div class="example"><pre>
ForceQuitGap(testresult);
</pre></div>
<p><a id="X84CD542B7C4C73A0" name="X84CD542B7C4C73A0"></a></p>
<h5>76.19-2 <span class="Heading">Testing <strong class="pkg">GAP</strong> package loading</span></h5>
<p>To test that your package may be loaded into <strong class="pkg">GAP</strong> without any problems and conflicts with other packages, test that it may be loaded in various configurations:</p>
<ul>
<li><p>starting <strong class="pkg">GAP</strong> with no packages (except needed for <strong class="pkg">GAP</strong>) using <code class="code">-r -A</code> options and calling <code class="code">LoadPackage("packagename");</code></p>
</li>
<li><p>starting <strong class="pkg">GAP</strong> with no packages (except needed for <strong class="pkg">GAP</strong>) using <code class="code">-r -A</code> options and calling <code class="code">LoadPackage("packagename" : OnlyNeeded );</code></p>
</li>
<li><p>starting <strong class="pkg">GAP</strong> in the default configuration (with no options) and calling <code class="code">LoadPackage("packagename");</code></p>
</li>
<li><p>starting <strong class="pkg">GAP</strong> in the default configuration (with no options) and calling <code class="code">LoadPackage("packagename" : OnlyNeeded );</code></p>
</li>
<li><p>finally, together with all other packages using <code class="func">LoadAllPackages</code> (<a href="chap76.html#X80A0D21D78CF8494"><span class="RefLink">76.19-3</span></a>) (see below) in four possible combinations of starting <strong class="pkg">GAP</strong> with/without <code class="code">-r -A</code> options and calling <code class="func">LoadAllPackages</code> (<a href="chap76.html#X80A0D21D78CF8494"><span class="RefLink">76.19-3</span></a>) with/without <code class="code">reversed</code> option.</p>
</li>
</ul>
<p>The test of loading all packages is the most subtle one. Quite often it reveals problems which do not occur in the default configuration but may cause difficulties to the users of specialised packages.</p>
<p>Additionally, we recommend using <code class="func">ShowPackageVariables</code> (<a href="chap76.html#X7D34AC3287611B15"><span class="RefLink">76.3-17</span></a>) to see information about variables created by your package to check if any have either short names (no more than three characters) or names breaking a recommended naming convention that the <strong class="pkg">GAP</strong> core system. <strong class="pkg">GAP</strong> packages also should not use global variables starting in the lowercase (see Section <a href="chap76.html#X7DEACD9786DE29F1"><span class="RefLink">76.10</span></a>).</p>
<p><a id="X80A0D21D78CF8494" name="X80A0D21D78CF8494"></a></p>
<h5>76.19-3 LoadAllPackages</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ LoadAllPackages</code>( <var class="Arg">:</var> <var class="Arg">reversed</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>loads all <strong class="pkg">GAP</strong> packages from their list sorted in alphabetical order (needed and suggested packages will be loaded when required). This is a technical function to check packages compatibility, so it should NOT be used to run anything except tests; it is known that <strong class="pkg">GAP</strong> performance is slower if all packages are loaded. To introduce some variations of the order in which packages will be loaded for testing purposes, <code class="func">LoadAllPackages</code> accepts option <code class="code">reversed</code> to load packages from their list sorted in the reverse alphabetical order.</p>
<p><a id="X7C90C8B87BF6EF0B" name="X7C90C8B87BF6EF0B"></a></p>
<h5>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></h5>
<p>The <code class="file">tst</code> directory of the <strong class="pkg">GAP</strong> installation contains a selection of test files and scripts such as <code class="file">testinstall.g</code> and <code class="file">teststandard.g</code> which are a part of the <strong class="pkg">GAP</strong> standard test suite.</p>
<p>It is important to check that your package does not break <strong class="pkg">GAP</strong> standard tests. To perform a clean test and avoid interfering with other packages, first you must start a new <strong class="pkg">GAP</strong> session and then read either <code class="file">testinstall.g</code> or <code class="file">teststandard.g</code> as demonstrated below.</p>
<p>The quicker test, <code class="file">testinstall.g</code>, should run in about a minute depending on your hardware speed. It may be started with the command</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">Read( Filename( DirectoriesLibrary( "tst" ), "testinstall.g" ) );</span>
</pre></div>
<p>You will get a large number of lines with output about the progress of the tests, for example:</p>
<div class="example"><pre>
You should start GAP4 using `gap -A -x 80 -r'.
Architecture: SOMETHING-SOMETHING-gcc-default64
testing: ..../gap-4.X.Y/tst/testinstall/alghom.tst
84 ms (55 ms GC) and 2.90MB allocated for alghom.tst
testing: ..../gap-4.X.Y/tst/testinstall/algmat.tst
839 ms (114 ms GC) and 219MB allocated for algmat.tst
[ further lines deleted ]
testing: ..../gap-4.X.Y/tst/testinstall/zmodnze.tst
127 ms (119 ms GC) and 1.29MB allocated for zmodnze.tst
-----------------------------------
total 62829 ms (24136 ms GC) and 8.61GB allocated
0 failures in 252 files
#I No errors detected while testing
</pre></div>
<p>(optionally, you may start <strong class="pkg">GAP</strong> with the command line options which you will see in the test output, to run it in a more conservative settings).</p>
<p>The more thorough test is <code class="file">teststandard.g</code> which exercises more of <strong class="pkg">GAP</strong>'s capabilities, also including all test files from <code class="file">teststandard.g</code>. It runs quite a bit longer, maybe 10-20 minutes, and produces an output similar to the testinstall.g test. To run it, also start a new <strong class="pkg">GAP</strong> session and then call</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">Read( Filename( DirectoriesLibrary( "tst" ), "teststandard.g" ) );</span>
</pre></div>
<p>You may repeat the same check loading your package with <code class="code">OnlyNeeded</code> option. Remember to perform each subsequent test in a new <strong class="pkg">GAP</strong> session.</p>
<p>Also you may perform individual tests from the <code class="file">tst</code> directory of the <strong class="pkg">GAP</strong> installation loading them with <code class="func">Test</code> (<a href="chap7.html#X87712F9D8732193C"><span class="RefLink">7.10-2</span></a>).</p>
<p><a id="X81B52B657CA75BDA" name="X81B52B657CA75BDA"></a></p>
<h4>76.20 <span class="Heading">Access to the <strong class="pkg">GAP</strong> Development Version</span></h4>
<p>We are aiming at providing a stable platform for package development and testing with official <strong class="pkg">GAP</strong> releases. We also invite everyone to contribute by submitting patches, pull requests, and bug reports. We would like to make the contributing process as easy as possible.</p>
<p>The main GAP development repository is hosted on GitHub at <span class="URL"><a href="https://github.com/gap-system/gap">https://github.com/gap-system/gap</a></span>. Many <strong class="pkg">GAP</strong> packages also have public repositories and issue trackers, and we are keeping a list of such packages at <span class="URL"><a href="https://gap-packages.github.io/">https://gap-packages.github.io/</a></span>.</p>
<p>For further information about contributing to the GAP development, please see <span class="URL"><a href="https://github.com/gap-system/gap/blob/master/CONTRIBUTING.md">https://github.com/gap-system/gap/blob/master/CONTRIBUTING.md</a></span>.</p>
<p><a id="X836CDF8F7A846A1C" name="X836CDF8F7A846A1C"></a></p>
<h4>76.21 <span class="Heading">Version control and continuous integration for <strong class="pkg">GAP</strong> packages</span></h4>
<p>As we have mentioned above, many <strong class="pkg">GAP</strong> packages have public repositories and issue trackers on GitHub, and we are keeping a list of such packages at <span class="URL"><a href="https://gap-packages.github.io/">https://gap-packages.github.io/</a></span>. We welcome establishing public repositories for new packages and migrating existing package repositories there as well. Such repositories may be hosted under their authors' accounts or under the gap-packages organisation (<span class="URL"><a href="https://github.com/gap-packages/">https://github.com/gap-packages/</a></span>). The latter has the benefit that while the authors will preserve their deciding role on all aspects of the package development, the package will become more visible for potential collaborators and <strong class="pkg">GAP</strong> developers may help to set up <em>continuous integration</em> for your package so that every commit to the repository will trigger automated running of package tests and reporting any failures to package maintainers.</p>
<p><a id="X82EBCBC5829B6001" name="X82EBCBC5829B6001"></a></p>
<h4>76.22 <span class="Heading">Selecting a license for a <strong class="pkg">GAP</strong> Package</span></h4>
<p>As it was mentioned in the description of the <code class="file">LICENSE</code> file in Section <a href="chap76.html#X8383876782480702"><span class="RefLink">76.5</span></a>, it is advised to make clear in the documentation of the package the basis on which it is being distributed to users. <strong class="pkg">GAP</strong> itself is distributed under the GNU Public License version 2 (version 2 or later). We would encourage you to consider the GPL license for your packages, but you might wish to be more restrictive (for instance forbidding redistribution for profit) or less restrictive (allowing your software to be incorporated into commercial software). See <q>Choosing a License for the Distribution of Your Package</q> from <span class="URL"><a href="https://www.gap-system.org/Packages/Authors/authors.html">https://www.gap-system.org/Packages/Authors/authors.html</a></span> and also <span class="URL"><a href="https://choosealicense.com/">https://choosealicense.com/</a></span> for further details.</p>
<p>In the past many <strong class="pkg">GAP</strong> packages used the text <q>We adopt the copyright regulations of <strong class="pkg">GAP</strong> as detailed in the copyright notice in the <strong class="pkg">GAP</strong> manual</q> or a similar statement. We now advise to be more explicit by making the exact reference to the GPL license, for example:</p>
<p><em> <strong class="pkg">packagename</strong> is free software; you can redistribute it and/or modify it under the terms of the <span class="URL"><a href="https://www.fsf.org/licenses/gpl.html">GNU General Public License</a></span> as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. </em> and also including a copy of the full text of the license.</p>
<p><a id="X8074AAAE79911BE5" name="X8074AAAE79911BE5"></a></p>
<h4>76.23 <span class="Heading">Releasing a GAP Package</span></h4>
<p>The <strong class="pkg">GAP</strong> distribution provides archives in several different formats.</p>
<dl>
<dt><strong class="Mark"><code class="file">.tar.gz</code></strong></dt>
<dd><p>a standard UNIX <code class="code">tar</code> archive, compressed with <code class="code">gzip</code></p>
</dd>
<dt><strong class="Mark"><code class="file">.tar.bz2</code></strong></dt>
<dd><p>a standard UNIX <code class="code">tar</code> archive, compressed with <code class="code">bzip2</code></p>
</dd>
<dt><strong class="Mark"><code class="file">.zip</code></strong></dt>
<dd><p>an archive in <code class="code">zip</code> format, where text files should have UNIX style line breaks</p>
</dd>
</dl>
<p>For convenience of possible users it is sensible that you provide an archive of your package in at least one of these formats.</p>
<p>For example, if you wish to supply a <code class="file">.tar.gz</code> archive, you may create it with the command</p>
<p> <code class="code">tar -cvzf packagename-version.tar.gz packagename</code></p>
<p>Because the release of the <strong class="pkg">GAP</strong> package is independent of the version of <strong class="pkg">GAP</strong>, a <strong class="pkg">GAP</strong> package should be wrapped up in separate file that can be installed onto any version of <strong class="pkg">GAP</strong>. In this way, a package can be upgraded any time without the need to wait for new <strong class="pkg">GAP</strong> releases. To ensure this, the package should be archived from the <strong class="pkg">GAP</strong> <code class="file">pkg</code> directory, that is all files are archived with the path starting at the package's name.</p>
<p>The archive of a <strong class="pkg">GAP</strong> package should contain all files necessary for the package to work. In particular there should be a compiled documentation, which includes the <code class="file">manual.six</code>, <code class="file">manual.toc</code> and <code class="file">manual.lab</code> file in the documentation subdirectory which are created by <strong class="pkg">GAPDoc</strong> while TeXing the documentation. (The first two files are needed by the <strong class="pkg">GAP</strong> help system, and the <code class="file">manual.lab</code> file is needed if the main manuals or another package is referring to your package. Use the command <code class="code">GAPDocManualLab( packagename );</code> to create this file for your help books if you use <strong class="pkg">GAPDoc</strong>.)</p>
<p>Note that wrapping the <strong class="pkg">GAP</strong> distribution as a single archive containing the core system and all currently redistributed packages, will change file timestamps, so one should not rely on them anywhere in the package.</p>
<p>For packages hosted on GitHub publishing package release and establishing its website can be very efficiently automated using two tools: ReleaseTools (<span class="URL"><a href="https://github.com/gap-system/ReleaseTools">https://github.com/gap-system/ReleaseTools</a></span>) and GitHubPagesForGAP (<span class="URL"><a href="https://github.com/gap-system/GitHubPagesForGAP">https://github.com/gap-system/GitHubPagesForGAP</a></span>).</p>
<p><a id="X8232CC1385C4B1DD" name="X8232CC1385C4B1DD"></a></p>
<h4>76.24 <span class="Heading">The homepage of a Package</span></h4>
<p>If you want to distribute your package you should create its homepage containing some basic information, archives for download, the <code class="file">README</code> file with installation instructions, and a copy of the package's <code class="file">PackageInfo.g</code> file.</p>
<p>The responsibility to maintain this homepage is with the package authors/maintainers.</p>
<p>If you tell the <strong class="pkg">GAP</strong> Group about your package (say, by mail to <span class="URL"><a href="mailto:support@gap-system.org">support@gap-system.org</a></span>) we may consider either</p>
<ul>
<li><p>adding a link to your package homepage from the <strong class="pkg">GAP</strong> website (thus, the package will be an <em>undeposited contribution</em>);</p>
</li>
<li><p>or redistributing the current version of your package as a part of the <strong class="pkg">GAP</strong> distribution (this, the package will be <em>deposited</em>), also ;</p>
</li>
</ul>
<p>Please also consider submitting your package to the <strong class="pkg">GAP</strong> package refereeing process (see <span class="URL"><a href="https://www.gap-system.org/Contacts/submit.html">https://www.gap-system.org/Contacts/submit.html</a></span> for further information).</p>
<p>For packages hosted on GitHub publishing package release and establishing its website can be very efficiently automated using two tools: GitHubPagesForGAP (<span class="URL"><a href="https://github.com/gap-system/GitHubPagesForGAP">https://github.com/gap-system/GitHubPagesForGAP</a></span>) and ReleaseTools (<span class="URL"><a href="https://github.com/gap-system/ReleaseTools">https://github.com/gap-system/ReleaseTools</a></span>).</p>
<p><a id="X796D7F7583E845BE" name="X796D7F7583E845BE"></a></p>
<h4>76.25 <span class="Heading">Some things to keep in mind</span></h4>
<ul>
<li><p>Some packages still use for their manuals the old <q>gapmacro</q> format, support for which may be discontinued in the future. We encourage authors of those packages to eventually convert their documentation <strong class="pkg">GAPDoc</strong>. New packages are recommended to use <strong class="pkg">GAPDoc</strong>, which, for example, is capable of creating HTML documentation with MathJax support, allows easy extraction of examples from documentation for testing, etc. One could also use the <strong class="pkg">AutoDoc</strong> which simplifies writing documentation by generating most of the <strong class="pkg">GAPDoc</strong> code automatically.</p>
</li>
<li><p>The concept of an autoloaded package, which existed before <strong class="pkg">GAP</strong> 4.5, has been integrated with the <em>needed</em> and <em>suggested</em> mechanism that exists between packages. <strong class="pkg">GAP</strong> itself now <q>needs</q> certain packages (for instance <strong class="pkg">GAPDoc</strong>) and <q>suggests</q> others (typically the packages that were autoloaded). The decisions which packages <strong class="pkg">GAP</strong> should need or suggest are made by developers based on technical criteria. They can be easily overridden by a user using the new <code class="file">gap.ini</code> (see <a href="chap3.html#X7FD66F977A3B02DF"><span class="RefLink">3.2</span></a>). The default file ensures that all formerly autoloaded packages are still loaded if present.</p>
</li>
<li><p>Optional <code class="file">~/.gap</code> directory for user's customisations which may contain e.g. locally installed packages (see <a href="chap9.html#X7A4973627A5DB27D"><span class="RefLink">9.2</span></a>). If package installation instructions explain how to install the package in a non-standard location, they should mention this.</p>
</li>
<li><p>Packages loading mechanism allows to make loading packages more informative, while avoiding confusing the user with warning and error messages for packages they didn't know they were loading. For example, many messages are stored but not displayed using the function <code class="func">LogPackageLoadingMessage</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-6</span></a>) and there is a function <code class="func">DisplayPackageLoadingLog</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-6</span></a>) to show log messages that occur during package loading. Packages are encouraged to use these mechanisms to report problems in loading (e.g. binaries not compiled), rather than printing messages directly.</p>
</li>
</ul>
<p><a id="X82CE0A518440CCBB" name="X82CE0A518440CCBB"></a></p>
<h4>76.26 <span class="Heading">Package release checklists</span></h4>
<p>The following checklists should be useful to package authors and maintainers, as well as to everyone involved in the depositing and refereeing of <strong class="pkg">GAP</strong> packages.</p>
<p><a id="X80E3926A7CF8B6DC" name="X80E3926A7CF8B6DC"></a></p>
<h5>76.26-1 <span class="Heading">Checklist for releasing a new package</span></h5>
<ul>
<li><p>Test that the package:</p>
<ul>
<li><p>does not break <code class="file">testinstall.g</code> and <code class="file">teststandard.g</code>, and does not slow them down noticeably (see <a href="chap76.html#X7C90C8B87BF6EF0B"><span class="RefLink">76.19-4</span></a>);</p>
</li>
<li><p>may be loaded in various configurations (see <a href="chap76.html#X84CD542B7C4C73A0"><span class="RefLink">76.19-2</span></a>);</p>
</li>
<li><p>follows the guidelines of Section <a href="chap76.html#X7DEACD9786DE29F1"><span class="RefLink">76.10</span></a> about names of functions and variables;</p>
</li>
</ul>
</li>
<li><p><code class="file">PackageInfo.g</code> file:</p>
<ul>
<li><p>correctly specifies package version, release date, and package authors;</p>
</li>
<li><p>passes validation using <code class="func">ValidatePackageInfo</code> (<a href="chap76.html#X79767C2482FF6F55"><span class="RefLink">76.3-16</span></a>);</p>
</li>
<li><p>besides mandatory components, which are required to pass validation, also has relevant optional components (such as, for example, URLs of public source code repository and issue tracker; hints to distinguish binary and text files in case of non-standard file names and extensions, etc.);</p>
</li>
</ul>
</li>
<li><p>Package documentation:</p>
<ul>
<li><p>is built and included in the package archive together with its source files;</p>
</li>
<li><p>states the same version, release date and package authors as specified in the <code class="file">PackageInfo.g</code> file;</p>
</li>
<li><p>has the same version, release date and package authors details as stated in the <code class="file">PackageInfo.g</code> file;</p>
</li>
<li><p>is searchable using the <strong class="pkg">GAP</strong> help system in all formats (text, HTML and PDF);</p>
</li>
<li><p>is clear about the license under which the package is distributed, and refers to the <code class="file">LICENSE</code> file which should be included in the package;</p>
</li>
</ul>
</li>
<li><p>Package archive(s):</p>
<ul>
<li><p>have correct permissions for all files and directories after their unpacking (755 for directories and executables, if any; 644 for other files);</p>
</li>
<li><p>contain files with correct line breaks for the given format (see Section <a href="chap76.html#X8074AAAE79911BE5"><span class="RefLink">76.23</span></a>);</p>
</li>
<li><p>contain no hidden system files and directories that are not supposed to be included in the package, e.g. <code class="file">.gitignore</code>, <code class="file">.git</code> etc.;</p>
</li>
</ul>
</li>
<li><p>Package availability:</p>
<ul>
<li><p>not only the package archive(s), but also the <code class="file">PackageInfo.g</code> and <code class="file">README</code> files are available online;</p>
</li>
</ul>
</li>
</ul>
<p><a id="X820D4B207A41AEA6" name="X820D4B207A41AEA6"></a></p>
<h5>76.26-2 <span class="Heading">Checklist for upgrading the package for the next major release of <strong class="pkg">GAP</strong></span></h5>
<p><strong class="pkg">GAP</strong> ecosystem is not static: both the core <strong class="pkg">GAP</strong> system and packages redistributed with <strong class="pkg">GAP</strong> are in constant development. <strong class="pkg">GAP</strong> has a policy that changes that may have a disruptive effect on packages redistributed with <strong class="pkg">GAP</strong> should only be introduced in major <strong class="pkg">GAP</strong> releases. When the next <strong class="pkg">GAP</strong> major release is prepared, a beta version for package authors will be made available in order to give them an opportunity to check and update, if necessary, their packages for the public release of the next major version of <strong class="pkg">GAP</strong>.</p>
<p>The following checklist will help you to check how well your package is ready to work with the next major release of <strong class="pkg">GAP</strong></p>
<ul>
<li><p>Check that the package functionality works as expected, package tests run with no discrepancies, and manual examples correspond to new version of <strong class="pkg">GAP</strong>. This is a convenient opportunity to polish existing and add new tests, and improve manual examples.</p>
</li>
<li><p>Revise package dependencies: check that the <code class="file">PackageInfo.g</code> file has correct list of needed and suggested packages (see Section <a href="chap76.html#X7928799186F9B2FE"><span class="RefLink">76.11</span></a>).</p>
</li>
<li><p>Revise licensing information: check that the package states clearly under which conditions it is distributed and includes a <code class="file">LICENSING</code> file with the text of a license (see Section <a href="chap76.html#X82EBCBC5829B6001"><span class="RefLink">76.22</span></a>).</p>
</li>
<li><p>Rebuild the package documentation to update cross-references to main <strong class="pkg">GAP</strong> manuals and, if relevant, to the documentation of other <strong class="pkg">GAP</strong> packages. This will ensure that cross-references from the package manual to the main <strong class="pkg">GAP</strong> manuals are correct and that the <strong class="pkg">GAP</strong> help system will be able to navigate to the more precise location in the package manual. This will also improve the layout of the package documentation by picking up the changes in documenting tools.</p>
</li>
<li><p>Check if the package still relies on some obsolete variables (see Chapter <a href="chap77.html#X78C85ED17F00DCC1"><span class="RefLink">77</span></a>) and replace their usage by the new commands. To perform such check, start <strong class="pkg">GAP</strong> with `-O` command line option to disable loading obsoletes, and then load your package.</p>
</li>
<li><p>Check for any specific advice in release notes for the beta release for package authors.</p>
</li>
</ul>
<div class="chlinkprevnextbot"> <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>
<div class="chlinkbot"><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>
<hr />
<p class="foot">generated by <a href="https://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>
|
