The initialization file of a share package is a file init.g in the
home directory of the share package. This file tells GAP about the
version number of the share package, about the documentation and about
the actual code. It is a proper GAP file (so syntax and comments
are standard), but only the following GAP functions may be called
(if further functions are called the loading process, which proceeds
in two stages, may not work):
The first command in the file will be a call to DeclarePackage (see
DeclarePackage in the Reference Manual). This indicates the package's
version number and permits to test whether necessary external binaries or
other share packages are installed. If instead DeclareAutoPackage
(see DeclareAutoPackage in the Reference Manual) is called, the
package will be loaded automatically when GAP has started. (To be exact:
GAP loads the library, then reads the users gaprc file and then loads
the share packages which are intended for automatic loading and which are
not yet loaded via the users gaprc file.)
At the moment automatic loading is only available for the packages listed
in the file pkg/ALLPKG. This is due to the fact that there is no standard
C-Function that will list the contents of a subdirectory.
The next command will be a call to DeclarePackageDocumentation (see
DeclarePackageDocumentation in the Reference Manual) to indicate the
location of the share packages documentation to GAP. If instead
DeclarePackageAutoDocumentation (see DeclarePackageAutoDocumentation
in the Reference Manual) is called, the documentation will be read
automatically when GAP starts (however RequirePackage still has to be
used to load the actual package in case the first command in the file is
DeclarePackage).
If the package requires other share packages (see Requesting one Share Package from within Another) this is followed by calls to RequirePackage.
Finally, calls to ReadPkg will read files which contain the actual GAP
functions the package provides.
To separate declaration and implementation parts, for larger packages it is
recommended to only load the declaration part from within init.g and to
use the separate read.g file to load the implementation part.
See sections Declaration and Implementation Part and Package Completion
for details.
For example this is the init.g file of a simple ``test'' share package:
# announce the package version
DeclarePackage("test","1.0",ReturnTrue);
# install the documentation
DeclarePackageDocumentation( "test", "doc" );
# read the actual code.
ReadPkg( "test", "gap/code.g");
This file installs the share package ``test'' in version 1.0. There
are no requirements that have to be tested, so ReturnTrue is used as
test function. It then installs documentation for the share package,
which can be found in the doc subdirectory. Finally, it reads the
file code.g in the gap subdirectory, which contains the actual
code.
If the package author wants the share package to display a separate
banner the printing of the banner must be issued from within a file
which will be read via ReadPkg from the init.g file. If the share
package is intended for automatic loading we however recommend not to print
any separate banner as the user will get a list of the loaded share packages
at the end of the initialization process.
A share package which has been loaded once
cannot be unloaded and also cannot be loaded again.
When writing (and debugging) a share package it may be therefore
helpful to use RereadPkg on single files or to use a separate
``reader'' file which does not use the RequirePackage mechanism.
[Top] [Previous] [Up] [Next] [Index]
GAP 4 manual