doc/README.plugins

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