doc/README.plugins

   1 $Id$
   2
   3 1. Plugins
   4
   5 Writing a "plugin" dissector is not very different from writing a
   6 standard one.  In fact all of the functions described in
   7 README.developer can be used in the plugins exactly as the are used in
   8 standard dissectors.
   9
  10 (Note, however, that not all OSes on which Wireshark runs can support
  11 plugins.)
  12
  13 If you've chosen "xxx" as the name of your plugin (typically, that would
  14 be a short name for your protocol, in all lower case), the following
  15 instructions tell you how to implement it as a plugin.  All occurrences
  16 of "xxx" below should be replaced by the name of your plugin.
  17
  18 2. The directory for the plugin, and its files
  19
  20 The plugin should be placed in a new plugins/xxx directory which should
  21 contain minimally the following files:
  22
  23 AUTHORS
  24 COPYING
  25 ChangeLog
  26 Makefile.am
  27 Makefile.common
  28 Makefile.nmake
  29 moduleinfo.h
  30 moduleinfo.nmake
  31 plugin.rc.in
  32 The source files and header files for your dissector
  33
  34 Examples of these files can be found in plugins/h223.
  35
  36 2.1 AUTHORS, COPYING, and ChangeLog
  37
  38 The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
  39 files.
  40
  41 2.2 Makefile.am
  42
  43 For your plugins/xxx/Makefile.am file, see the corresponding file in
  44 plugins/h223. Replace all occurrences of "h223" in those files with "xxx".
  45
  46 2.3 Makefile.common
  47
  48 Your plugins/xxx/Makefile.common should list the source files for your
  49 dissector in the DISSECTOR_SRC variable, and all supporting source files
  50 in the DISSECTOR_SUPPORT_SRC variable.
  51 The header files for your dissector, if any, must be listed in the
  52 DISSECTOR_INCLUDES variable. The DISSECTOR_INCLUDES variable should not
  53 include moduleinfo.h.
  54
  55 2.4 Makefile.nmake
  56
  57 For your plugins/xxx/Makefile.nmake file, see the corresponding file in
  58 plugins/h223. No modifications are needed here.
  59
  60 2.5 moduleinfo.h
  61
  62 Your plugins/xxx/moduleinfo.h file is used to set the version information
  63 for the plugin.
  64
  65 2.6 moduleinfo.nmake
  66
  67 Your plugins/xxx/moduleinfo.nmake is used to set the version information
  68 for building the plugin. Its contents should match that in moduleinfo.h
  69
  70 2.7 plugin.rc.in
  71
  72 Your plugins/xxx/plugin.rc.in is the Windows resource template file
  73 used to add the plugin specific information as resources to the DLL.
  74 No modifications are needed here.
  75
  76 3. Changes to existing Wireshark files
  77
  78 You will also need to change the plugins/Makefile.am, the
  79 plugins/Makefile.nmake, the toplevel Makefile.am file, and the
  80 toplevel configure.in file.
  81
  82 3.1  Changes to plugins/Makefile.am
  83
  84 The plugins directory contains a Makefile.am.
  85 You need to change the SUBDIRS directive to reflect the addition of
  86 your plugin:
  87
  88 SUBDIRS = \
  89         gryphon \
  90         mgcp \
  91         xxx
  92
  93
  94 3.2 Changes to plugins/Makefile.nmake
  95
  96 To the Makefile.nmake you need to add your plugin to the all: rule
  97
  98 all: \
  99         gryphon \
 100         mgcp \
 101         xxx
 102
 103 then add a rule for your plugin:
 104
 105 xxx::
 106         cd xxx
 107         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake
 108         cd ..
 109
 110 and finally add to the clean rule support for cleaning up after your
 111 plugin:
 112
 113 clean:
 114         cd gryphon
 115         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 116         cd ../mgcp
 117         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 118         cd ..
 119         cd xxx
 120         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 121         cd ..
 122
 123
 124 distclean: clean
 125         cd gryphon
 126         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
 127         cd ../mgcp
 128         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
 129         cd ..
 130         cd xxx
 131         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
 132         cd ..
 133
 134
 135 maintainer-clean: clean
 136         cd gryphon
 137         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
 138         cd ../mgcp
 139         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
 140         cd ..
 141         cd xxx
 142         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
 143         cd ..
 144
 145
 146 3.3 Changes to the top level Makefile.am
 147
 148 Unfortunately there are quite some several places in the top level
 149 Makefile.am that need to be altered for adding a plugin.
 150
 151 Add your plugin to the plugin_libs and plugin_ldadd:
 152
 153 plugin_libs = \
 154         plugins/gryphon/gryphon.la \
 155         plugins/mgcp/mgcp.la    \
 156         plugins/xxx/xxx.la
 157
 158 if ENABLE_STATIC
 159 plugin_ldadd = (plugin_libs)
 160
 161 else          # ENABLE_STATIC
 162 plugin_ldadd = \
 163         "-dlopen" self  \
 164         "-dlopen" plugins/gryphon/gryphon.la \
 165         "-dlopen" plugins/mgcp/mgcp.la \
 166         "-dlopen" plugins/xxx/xxx.la
 167
 168 3.4  Changes to top level configure.in
 169
 170 You need to add your plugins Makefile to the AC_OUTPUT rule in the
 171 configure.in
 172
 173 AC_OUTPUT(
 174   Makefile
 175   doc/Makefile
 176   gtk/Makefile
 177   packaging/Makefile
 178   packaging/nsis/Makefile
 179   packaging/rpm/Makefile
 180   packaging/rpm/wireshark.spec
 181   packaging/svr4/Makefile
 182   packaging/svr4/checkinstall
 183   packaging/svr4/pkginfo
 184   plugins/Makefile
 185   plugins/gryphon/Makefile
 186   plugins/mgcp/Makefile
 187   plugins/xxx/Makefile
 188   tools/Makefile
 189   tools/lemon/Makefile
 190   ,)
 191
 192 3.5  Changes to the installers
 193
 194 If you want to include your plugin in an installer you have to add lines
 195 in the NSIS installer wireshark.nsi file, and U3 installer makefile.nmake
 196 file.
 197
 198 4. Development and plugins
 199
 200 Plugins make some aspects of development easier and some harder.
 201
 202 The good news is that if you are working on a single plugin
 203 then you will find recompiling the plugin MUCH faster than
 204 recompiling a dissector and then linking it back into wireshark.
 205
 206 The bad news is that wireshark will not use the plugin unless the
 207 plugin is installed in one of the places it expects to look.
 208
 209 One way to deal with this problem is to set up a working root for
 210 wireshark, say in $HOME/build/root and build wireshark to install
 211 there
 212
 213 ./configure --prefix=${HOME}/build/root;make install
 214
 215 then subsequent rebuilds/installs of your plugin can be accomplished
 216 by going to the plugins/xxx directory and running
 217
 218 make install
 219
 220 5. Update "old style" plugins
 221
 222 5.1 How to update an "old style" plugin (using plugin_register and
 223     plugin_reg_handoff functions).
 224
 225 The plugin registration has changed with the extension of the build
 226 scripts. These now generate the additional code needed for plugin
 227 encapsulation in plugin.c. When using the new style build scripts,
 228 stips the parts outlined below:
 229
 230     o Remove the following include statments:
 231
 232         #include <gmodule.h>
 233         #include "moduleinfo.h"
 234
 235     o Removed the definition:
 236
 237         #ifndef ENABLE_STATIC
 238         G_MODULE_EXPORT gchar version[] = VERSION;
 239         #endif
 240
 241     o Move relevant code from the blocks and delete these functions:
 242
 243         #ifndef ENABLE_STATIC
 244         plugin_reg_handoff()
 245         ....
 246         #endif
 247
 248         #ifndef ENABLE_STATIC
 249         plugin_register()
 250         ....
 251         #endif
 252
 253 This will leave a clean dissector source file without plugin specifics.
 254
 255 5.2 How to update an "old style" plugin (using plugin_init function)
 256
 257 The plugin registering has changed between 0.10.9 and 0.10.10; everyone
 258 is encouraged to update their plugins as outlined below:
 259
 260     o Remove following include statements from all plugin sources:
 261
 262         #include "plugins/plugin_api.h"
 263         #include "plugins/plugin_api_defs.h"
 264
 265     o Remove the init function.
 266
 267     o Add a new Makefile.common file with the lists of source files and
 268       headers.
 269
 270     o Change the Makefile.am and Makefile.nmake files to match those of
 271       the DOCSIS plugin.
 272
 273 ----------------
 274
 275 Ed Warnicke <hagbard@physics.rutgers.edu>
 276 Guy Harris <guy@alum.mit.edu>
 277
 278 Derived and expanded from the plugin section of README.developers
 279 which was originally written by
 280
 281 James Coe <jammer@cin.net>
 282 Gilbert Ramirez <gram@alumni.rice.edu>
 283 Jeff Foster <jfoste@woodward.com>
 284 Olivier Abad <oabad@cybercable.fr>
 285 Laurent Deniel <laurent.deniel@free.fr>
 286 Jaap Keuter <jaap.keuter@xs4all.nl>