This chapter will discuss how to extend Pike by writing modules. There are two major ways to write modules, either they can be written in Pike, or they can be written in C. Generally, modules can be seen as a collection of pike programs and functions. This is, obviously, handy for grouping related programs and functions.
A pike module is actually a pike program which is cloned by the pike compiler during compilation of programs. This means that all lfuns that can be used in a pike program also can be used in a module. This is, for instance, useful for overloading the operators of a module to obtain a certain behaviour. Bear in mind that variables defined on a module-wide bases are shared among all clones of programs in the module. FIXME: Explain difference between .pmod and .pike
Pike searches for modules in the module path as defined during the
compilation of a pike program. The module-path defaults to contain
the directory where all standard pike modules are installed. This
can be altered using
/master.CompatResolver()->add_module_path() in a
program or by letting the environment variable
PIKE_MODULE_PATH contain a colon-separated list of
directories to be searched for modules before looking at the
default location.
Writing modules in pike is by far the easiest way to extend pike. They are also useful for structuring a larger programming project into different source files.
There are two ways of create a pike module written in
pike. Either create a file named as the module will be called
with the extension .pmod and place all program and
function definitions in it. The other way, which usually is more
flexible, is to create a directory named as the module with the
extension .pmod and place all program definitions
(.pike-files) within this directory. If a file called
module.pmod is placed in the directory the function and
program definitions within it will be merged with the programs
found in the directory. This file could, as an example, be used
to specify functions residing in the module, while programs in
the module are placed in .pike-files.
Note that Pike modules must not use try to load files relative to __FILE__, since such code will break in Microsoft Windows. FIXME: Explain why.
FIXME: To be written.
First of all your module needs a Makefile.in file. It need not be more complicated than the following example:
# $Id$ @make_variables@ VPATH=@srcdir@:@srcdir@/../..:../.. OBJS= MODULE_LDFLAGS=@LDFLAGS@ @LIBS@ CONFIG_HEADERS=@CONFIG_HEADERS@ @dynamic_module_makefile@ @dependencies@
A few customizations must however be done. The OBJS variable should contain all the object files produced in your module. You should add to the MODULE_LDFLAGS variable all the needed -L<libdir> -R<libdir> options followed by all the needed -l<lib> options. If you want your module to always be linked statically, change @dynamic_module_makefile@ to @static_module_makefile@. Normally you do not need to manually add any dependencies to Makefile.in.
There must be a testsuite.in file in the modules directory, even if it only is an empty file.
You should have a configure.in file for your module and it should test for all features that you need. Do not trust the global configure tests to do thing for you. Further, your configure.in should contain the line sinclude(../module_configuration.in).
All C/C++ files should include "global.h" as the first included file. It is also good if they contain RCSID($Id$).
When building your module for the first time you need to:
If _module_value is non-zero it will be used as
the value of the module. _module_value has to be of
a type which is indicable, ie. an object, mapping or
multiset.
If a lfun::`[] is defined in a module it will be
called when the module is indexed using the .-operator.