HomeDocs

29. Writing Pike Modules

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.

29.1. Writing Modules in Pike

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.

29.2. Writing Modules in C

FIXME: To be written.

29.2.1. Practical details

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:

    29.3. Special Module Variables and functions

    29.3.1. _module_value

    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.

    29.3.2. The indexing operator

    If a lfun::`[] is defined in a module it will be called when the module is indexed using the .-operator.