| 4c60a4 | 2003-11-07 | Martin Nilsson | | <!doctype html><html><head><title>Pike Reference Manual</title>
<meta charset='utf-8'></head>
|
| 57bd3c | 2019-08-05 | Henrik Grubbström (Grubba) | | <body><dl><dt><h1 class='header'>21. Writing Pike Modules</h1></dt><dd><p>
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.
</p><p>
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.
<span class='fixme'>FIXME: Explain difference between .pmod and .pike</span>
</p><p>
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
<code>/master.CompatResolver()->add_module_path()</code> in a
program or by letting the environment variable
<b>PIKE_MODULE_PATH</b> contain a colon-separated list of
directories to be searched for modules before looking at the
default location.
</p></dd>
|
| 9add81 | 2019-07-04 | Henrik Grubbström (Grubba) | | <dt><a name='21.1'></a>
|
| 57bd3c | 2019-08-05 | Henrik Grubbström (Grubba) | | <h2 class='header'>21.1. Writing Modules in Pike</h2></dt>
<dd><p>
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.
</p><p>
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 <code class='expr'>.pmod</code> 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 <code class='expr'>.pmod</code> and place all program definitions
(<code class='expr'>.pike</code>-files) within this directory. If a file called
<code class='expr'>module.pmod</code> 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 <code class='expr'>.pike</code>-files.
</p><p>
Note that Pike modules must not use try to load files relative to
__FILE__, since such code will break in Microsoft Windows.
<span class='fixme'>FIXME: Explain why.</span>
</p></dd>
<dt><a name='21.2'></a>
<h2 class='header'>21.2. Writing Modules in C</h2></dt>
<dd><p><span class='fixme'>FIXME: To be written.</span></p></dd>
<dt><a name='21.2.1'></a>
<h3 class='header'>21.2.1. Practical details</h3></dt>
<dd><p>First of all your module needs a Makefile.in file. It need not be
more complicated than the following example:
|
| 0f6ad7 | 2019-07-07 | Henrik Grubbström (Grubba) | | <pre>
|
| 57bd3c | 2019-08-05 | Henrik Grubbström (Grubba) | | # $Id$
@make_variables@
VPATH=@srcdir@:@srcdir@/../..:../..
OBJS=
MODULE_LDFLAGS=@LDFLAGS@ @LIBS@
|
| 0f6ad7 | 2019-07-07 | Henrik Grubbström (Grubba) | |
|
| 57bd3c | 2019-08-05 | Henrik Grubbström (Grubba) | | CONFIG_HEADERS=@CONFIG_HEADERS@
|
| 0f6ad7 | 2019-07-07 | Henrik Grubbström (Grubba) | |
|
| 57bd3c | 2019-08-05 | Henrik Grubbström (Grubba) | | @dynamic_module_makefile@
@dependencies@
</pre></p><p>A few customizations must however be done. The <tt>OBJS</tt> variable should
contain all the object files produced in your module. You should
add to the <tt>MODULE_LDFLAGS</tt> variable all the needed <tt>-L<libdir> -R<libdir></tt>
options followed by all the needed <tt>-l<lib></tt> options. If you want your
module to always be linked statically, change <tt>@dynamic_module_makefile@</tt>
to <tt>@static_module_makefile@</tt>. Normally you do not need to manually add
any dependencies to Makefile.in.</p><p>There must be a testsuite.in file in the modules directory, even if it
only is an empty file.</p><p>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
<tt>sinclude(../module_configuration.in)</tt>.</p><p>All C/C++ files should include <tt>"global.h"</tt> as the first included file. It
is also good if they contain <tt>RCSID($Id$)</tt>.</p><p>When building your module for the first time you need to:
<ol>
</ol></p></dd>
<dt><a name='21.3'></a>
<h2 class='header'>21.3. Special Module Variables and functions</h2></dt>
|
| 0f6ad7 | 2019-07-07 | Henrik Grubbström (Grubba) | | <dd></dd>
|
| 57bd3c | 2019-08-05 | Henrik Grubbström (Grubba) | | <dt><a name='21.3.1'></a>
<h3 class='header'>21.3.1. _module_value</h3></dt>
<dd><p>
If <code class='expr'>_module_value</code> is non-zero it will be used as
the value of the module. <code class='expr'>_module_value</code> has to be of
a type which is indicable, ie. an object, mapping or
multiset.
</p></dd>
<dt><a name='21.3.2'></a>
<h3 class='header'>21.3.2. The indexing operator</h3></dt>
<dd><p>
If a <code>lfun::`[]</code> is defined in a module it will be
called when the module is indexed using the .-operator.
</p></dd></dl></body></html>
|