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
|
<chapter title="Writing Pike Modules">
<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.
<fixme>Explain difference between .pmod and .pike</fixme>
</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
<ref>/master.CompatResolver()->add_module_path()</ref> 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>
<section title="Writing Modules in Pike">
<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 <expr>.pmod</expr> 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 <expr>.pmod</expr> and place all program definitions
(<expr>.pike</expr>-files) within this directory. If a file called
<expr>module.pmod</expr> 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 <expr>.pike</expr>-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.
<fixme>Explain why.</fixme>
</p>
</section>
<section title="Writing Modules in C">
<p><fixme>To be written.</fixme></p>
<subsection title="Practical details">
<p>First of all your module needs a Makefile.in file. It need not be
more complicated than the following example:
<pre>
# $Id$
@make_variables@
VPATH=@srcdir@:@srcdir@/../..:../..
OBJS=
MODULE_LDFLAGS=@LDFLAGS@ @LIBS@
CONFIG_HEADERS=@CONFIG_HEADERS@
@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>
<li>run autoconf</li>
<li>do "make depend" from your build dir</li>
<li>re-run configure from your build dir</li>
<li>run make in your build dir</li>
</ol></p>
</subsection>
</section>
<section title="Special Module Variables and functions">
There are a few variables and functions that have a special
meaning in a module.
<subsection title="_module_value">
<p>
If <expr>_module_value</expr> is non-zero it will be used as
the value of the module. <expr>_module_value</expr> has to be of
a type which is indicable, ie. an object, mapping or
multiset.
</p>
</subsection>
<subsection title="The indexing operator">
<p>
If a <ref>lfun::`[]</ref> is defined in a module it will be
called when the module is indexed using the .-operator.
</p>
</subsection>
</section>
</chapter>
|
