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