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 $(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_FILE)
 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>