doc/README.plugins

   1 $Id: README.plugins,v 1.1 2001/07/10 01:22:58 hagbard 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 noinst_PROGRAMS = 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../../epan /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
 223
 224 PLUGIN_SRC = \
 225         plugins/mgcp/packet-mgcp.c      \
 226         plugins/gryphon/packet-gryphon.c \
 227         plugins/xxx/packet-xxx.c
 228
 229
 230 Add your plugin library to the ethereal_DEPENDENCIES
 231
 232 ethereal_DEPENDENCIES = \
 233         $(ethereal_optional_objects)    \
 234         $(ethereal_additional_libs)     \
 235         plugins/gryphon/gryphon.la \
 236         plugins/mgcp/mgcp.la            \
 237         plugins/xxx/xxx.la
 238
 239 Add your plugin library to the ethereal_LDADD and ethereal_static_LDADD
 240
 241 ethereal_LDADD = \
 242         $(ethereal_optional_objects)    \
 243         $(ethereal_additional_libs)     \
 244         @SNMP_LIBS@ @SSL_LIBS@          \
 245         "-dlopen" self  \
 246         "-dlopen" plugins/gryphon/gryphon.la \
 247         "-dlopen" plugins/mgcp/mgcp.la \
 248         "-dlopen" plugins/xxx/xxx.la \
 249         @PCAP_LIBS@ @GTK_LIBS@
 250
 251 ethereal_static_LDADD = \
 252         "-all-static"                   \
 253         plugins/mgcp/packet-mgcp-static.o               \
 254         plugins/gryphon/packet-gryphon-static.o         \
 255         plugins/xxx/packet-xxx-static.o         \
 256         $(ethereal_optional_objects)    \
 257         $(ethereal_additional_libs)     \
 258         @SNMP_LIBS@ @SSL_LIBS@          \
 259         @PCAP_LIBS@ @GTK_LIBS@
 260
 261 Add your plugin library to the tethereal_DEPENDENCIES
 262
 263 tethereal_DEPENDENCIES = \
 264         $(ethereal_optional_objects)    \
 265         $(tethereal_additional_libs)    \
 266         plugins/gryphon/gryphon.la      \
 267         plugins/mgcp/mgcp.la            \
 268         plugins/xxx/xxx.la
 269
 270 And to tethereal_LDADD and tethereal_static_LDADD
 271
 272 tethereal_LDADD = wiretap/libwiretap.a  \
 273         $(ethereal_optional_objects)    \
 274         $(tethereal_additional_libs)    \
 275         @SNMP_LIBS@ @SSL_LIBS@          \
 276         "-dlopen" self  \
 277         "-dlopen" plugins/gryphon/gryphon.la \
 278         "-dlopen" plugins/mgcp/mgcp.la \
 279         "-dlopen" plugins/xxx/xxx.la \
 280         @GLIB_LIBS@ -lm \
 281         @PCAP_LIBS@ @SOCKET_LIBS@ @NSL_LIBS@
 282
 283 tethereal_static_LDADD = \
 284         "-all-static"           \
 285         plugins/mgcp/packet-mgcp-static.o               \
 286         plugins/gryphon/packet-gryphon-static.o         \
 287         plugins/xxx/packet-xxx-static.o         \
 288         wiretap/libwiretap.a    \
 289         $(ethereal_optional_objects)    \
 290         $(tethereal_additional_libs)    \
 291         @SNMP_LIBS@ @SSL_LIBS@          \
 292         @GLIB_LIBS@ -lm \
 293         @PCAP_LIBS@ @SOCKET_LIBS@ @NSL_LIBS@
 294
 295
 296
 297 4.7  Changes to top level configure.in
 298
 299 You need to add your plugins Makefile to the AC_OUTPUT rule in the
 300 configure.in
 301
 302 AC_OUTPUT(
 303   Makefile
 304   doc/Makefile
 305   gtk/Makefile
 306   packaging/Makefile
 307   packaging/nsis/Makefile
 308   packaging/rpm/Makefile
 309   packaging/rpm/ethereal.spec
 310   packaging/svr4/Makefile
 311   packaging/svr4/checkinstall
 312   packaging/svr4/pkginfo
 313   plugins/Makefile
 314   plugins/gryphon/Makefile
 315   plugins/mgcp/Makefile
 316   plugins/xxx/Makefile
 317   tools/Makefile
 318   tools/lemon/Makefile
 319   ,)
 320
 321
 322 5       Development and plugins
 323
 324 Plugins make some aspects of development easier and some harder.
 325
 326 The good news is that if you are working on a single plugin
 327 then you will find recompiling the plugin MUCH faster than
 328 recompiling a dissector and then linking it back into ethereal.
 329
 330 The bad news is that ethereal will not use the plugin unless the
 331 plugin is installed in one of the places it expects to look.
 332
 333 One way to deal with this problem is to set up a working root for
 334 ethereal, say in $HOME/build/root and build ethereal to install
 335 there
 336
 337 ./configure --prefix=${HOME}/build/root;make install
 338
 339 then subsequent rebuilds/installs of your plugin can be accomplished
 340 by going to the plugin/xxx directory and running
 341
 342 make install
 343
 344
 345 Ed Warnicke <hagbard@physics.rutgers.edu>
 346
 347 Derived and expanded from the plugin section of README.developers
 348 which was originally written by
 349
 350 James Coe <jammer@cin.net>
 351 Gilbert Ramirez <gram@xiexie.org>
 352 Jeff Foster <jfoste@woodward.com>
 353 Olivier Abad <oabad@cybercable.fr>
 354 Laurent Deniel <deniel@worldnet.fr>