Include files from the "epan" directory and subdirectories thereof with
[obnox/wireshark/wip.git] / doc / README.plugins
1 $Id: README.plugins,v 1.5 2002/01/21 07:37:36 guy Exp $
2
3 Plugins
4
5 Writing a "plugin" dissector is not very different from writing a standard one.
6 In fact all of the functions described in the README.developer can be 
7 used in the plugins exactly as the are used in standard dissectors.
8
9 Once you have written a packet-xxx.c to create your plugin 
10 ( where xxx is the name of the protocol you are dissecting ) there are 
11 only a few changes you need to make to "pluginize" your dissector.
12
13 1 New headers needed in packet-xxx.c
14
15 #include "plugins/plugin_api.h"
16
17 Some OSes (Win32) have DLLs that cannot reference symbols in the parent
18 executable. So, the executable needs to provide a table of pointers for the DLL
19 plugin to use. The plugin_api.h header provides definitions for this (or empty
20 definitions on OSes which don't need this).
21
22 #include "moduleinfo.h"
23
24 This header is optional and is described in greater detail further on.
25
26 This header is required to define G_MODULE_EXPORT, which must be used
27 when defining constants and functions exported by the plugin.
28
29 "gmodule.h" includes "glib.h", so you don't need to include "glib.h" if
30 you include "gmodule.h"; however, "glib.h" is protected from multiple
31 inclusion by #ifdefs, so it's safe to include it after including
32 "gmodule.h".
33
34 2 New exported constants in packet-xxx.c
35
36 Plugins need to provide the following exported constants:
37
38 #ifndef __ETHEREAL_STATIC__
39 G_MODULE_EXPORT const gchar version[] = VERSION;
40 #endif 
41
42 version       : a version number associated with the plugin.
43
44 the #ifndef is to allow for the building of a non-plugin version of 
45 the object for linking into a static ethereal binary.
46
47 3 New exported functions in packet-xxx.c
48
49 The following two functions need to be exported by the plugin:
50
51 #ifndef __ETHEREAL_STATIC__
52 G_MODULE_EXPORT void plugin_init(plugin_address_table_t *pat)
53 #endif
54
55 This function is called by Ethereal when the plugin is initialized; it's
56 similar to the "proto_register_XXX()" routine for a non-plugin
57 dissector, except for the name and the call to
58 "plugin_address_table_init()".
59
60 Here is a sample code for the function:
61
62         /* initialise the table of pointers needed in Win32 DLLs */
63         plugin_address_table_init(pat);
64
65         /* register the new protocol, protocol fields, and subtrees */
66         if (proto_xxx == -1) { /* execute protocol initialization only once */
67                 proto_register_xxx();
68         }
69
70 #ifndef __ETHEREAL_STATIC__
71 G_MODULE_EXPORT void plugin_reg_handoff(void)
72 #endif
73
74 This function is called by Ethereal after all dissectors, including all
75 plugins, are initialized; it's similar to the "proto_reg_handoff_XXX()"
76 routine for a non-plugin dissector, except for the name. 
77
78 Here is a sample code for the function:
79
80   proto_reg_handoff_xxx();
81
82 As you can see the plugin_reg_handoff and plugin_init are just 
83 wrappers for the proto_reg_handoff_xxx and proto_register_xxx functions.
84
85 4 Directory structure and other file changes
86
87 Plugins should be places in plugin/xxx/ which should contain minimally 
88 the following files:
89
90 AUTHORS
91 COPYING
92 ChangeLog
93 Makefile.am
94 Makefile.nmake
95 moduleinfo.h
96 packet-xxx.c
97
98 The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project 
99 files, see plugins/mgcp for examples.  You will also need to change 
100 the plugin/Makefile.am toplevel Makefile.am and toplevel configure.in 
101 files.
102
103 3.4.1 plugin/xxx/Makefile.am
104
105 An example of the Makefile.am follows:
106
107 INCLUDES = -I$(top_srcdir) -I$(includedir)
108
109 plugindir = @PLUGIN_DIR@
110
111 plugin_LTLIBRARIES = xxx.la
112 xxx_la_SOURCES = packet-xxx.c moduleinfo.h
113 xxx_la_LDFLAGS = -module -avoid-version
114
115 # Libs must be cleared, or else libtool won't create a shared module.
116 # If your module needs to be linked against any particular libraries,
117 # add them here.
118 LIBS =
119
120
121 # The following allows a non-plugin version of the module to be built to 
122 # be linked with a static ethereal binary.
123 #
124 xxx_la_DEPENDENCIES = packet-xxx-static.o
125
126 packet-xxx-static.o:   packet-xxx.c moduleinfo.h
127         $(LTCOMPILE) -c -o packet-xxx-static.o -D__ETHEREAL_STATIC__ $(srcdir)/packet-xxx.c 
128
129 CLEANFILES = \
130         xxx \
131 EXTRA_DIST = \
132         Makefile.nmake
133
134
135 4.2 plugin/xxx/Makefile.nmake
136
137 Makefile.nmake is used for building the plugin for for Windows.
138
139 include ..\..\config.nmake
140
141 ############### no need to modify below this line #########
142
143 CFLAGS=/DHAVE_CONFIG_H /I../.. /I../../wiretap \
144         /I$(GLIB_DIR) /I$(GTK_DIR) /I$(GLIB_DIR)/gmodule \
145         /I$(GTK_DIR)\gdk /I$(GTK_DIR)\gdk\win32 \
146         /I$(PCAP_DIR)\include $(LOCAL_CFLAGS)
147
148 OBJECTS=packet-xxx.obj 
149
150 xxx.dll xxx.exp xxx.lib : packet-xxx.obj ..\plugin_api.obj
151         link -dll /out:xxx.dll packet-mgcp.obj ..\plugin_api.obj \
152         $(GLIB_DIR)\glib-$(GLIB_VERSION).lib
153
154 clean:
155         rm -f $(OBJECTS) xxx.dll xxx.exp xxx.lib
156
157
158 4.3 plugin/xxx/moduleinfo.h
159         
160 moduleinfo.h is used to set the version information for the plugin.  
161 An example follows:
162
163 /* Included *after* config.h, in order to re-define these macros */
164
165 #ifdef PACKAGE
166 #undef PACKAGE
167 #endif
168
169 /* Name of package */
170 #define PACKAGE "xxx"
171
172
173 #ifdef VERSION
174 #undef VERSION
175 #endif
176
177 /* Version number of package */
178 #define VERSION "0.0.8"
179
180 4.4  Changes to plugins/Makefile.am
181
182 The plugins directory contains a Makefile.am.
183 You need to change the SUBDIRS directive to reflect the addition of 
184 your plugin:
185
186 SUBDIRS = gryphon mgcp xxx
187
188
189 4.5 Changes to plugins/Makefile.nmake
190
191 To the Makefile.nmake you need to add your plugin to the all: rule
192
193 all: plugin_api.obj gryphon mgcp xxx
194
195 then add a rule for your plugin:
196
197 xxx::
198         cd xxx
199         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake
200         cd ..
201
202 and finally add to the clean rule support for cleaning up after your 
203 plugin:
204
205 clean:
206         rm -f plugin_api.obj
207         cd gryphon
208         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
209         cd ../mgcp
210         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean   
211         cd ..
212         cd xxx
213         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
214         cd ..
215
216
217 4.6 Changes to the top level Makefile.am
218
219 Unfortunately there are quite some several places in the top level
220 Makefile.am that need to be altered for adding a plugin.
221
222 Add your plugin to the plugin_src, plugin_static_ldadd, plugin_libs,
223 and plugin_ldadd:
224
225 plugin_src = \
226         plugins/mgcp/packet-mgcp.c      \
227         plugins/gryphon/packet-gryphon.c \
228         plugins/xxx/packet-xxx.c
229
230 plugin_static_ldadd = \
231         plugins/mgcp/packet-mgcp-static.o               \
232         plugins/gryphon/packet-gryphon-static.o         \
233         plugins/xxx/packet-xxx-static.o          
234
235 plugin_libs = \
236         plugins/gryphon/gryphon.la \
237         plugins/mgcp/mgcp.la    \
238         plugins/xxx/xxx.la
239
240 plugin_ldadd = \
241         "-dlopen" self  \
242         "-dlopen" plugins/gryphon/gryphon.la \
243         "-dlopen" plugins/mgcp/mgcp.la \
244         "-dlopen" plugins/xxx/xxx.la 
245
246 4.7  Changes to top level configure.in
247
248 You need to add your plugins Makefile to the AC_OUTPUT rule in the 
249 configure.in
250
251 AC_OUTPUT(
252   Makefile
253   doc/Makefile
254   gtk/Makefile
255   packaging/Makefile
256   packaging/nsis/Makefile
257   packaging/rpm/Makefile
258   packaging/rpm/ethereal.spec
259   packaging/svr4/Makefile
260   packaging/svr4/checkinstall
261   packaging/svr4/pkginfo
262   plugins/Makefile
263   plugins/gryphon/Makefile
264   plugins/mgcp/Makefile
265   plugins/xxx/Makefile
266   tools/Makefile
267   tools/lemon/Makefile
268   ,)
269
270
271 5       Development and plugins
272
273 Plugins make some aspects of development easier and some harder.
274
275 The good news is that if you are working on a single plugin 
276 then you will find recompiling the plugin MUCH faster than 
277 recompiling a dissector and then linking it back into ethereal.
278
279 The bad news is that ethereal will not use the plugin unless the 
280 plugin is installed in one of the places it expects to look.
281
282 One way to deal with this problem is to set up a working root for 
283 ethereal, say in $HOME/build/root and build ethereal to install
284 there
285
286 ./configure --prefix=${HOME}/build/root;make install
287
288 then subsequent rebuilds/installs of your plugin can be accomplished 
289 by going to the plugin/xxx directory and running 
290
291 make install
292
293
294 Ed Warnicke <hagbard@physics.rutgers.edu>
295
296 Derived and expanded from the plugin section of README.developers
297 which was originally written by
298
299 James Coe <jammer@cin.net>
300 Gilbert Ramirez <gram@alumni.rice.edu>
301 Jeff Foster <jfoste@woodward.com>
302 Olivier Abad <oabad@cybercable.fr>
303 Laurent Deniel <deniel@worldnet.fr>