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 The source files and header files for your dissector
  31
  32 2.1 AUTHORS, COPYING, and ChangeLog
  33
  34 The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
  35 files; see plugins/docsis for examples.
  36
  37 2.2 Makefile.am and Makefile.nmake
  38
  39 For your plugins/xxx/Makefile.am and plugins/xxx/Makefile.nmake files,
  40 see the corresponding files in plugins/docsis.  Replace all occurrences
  41 of "docsis" in those files with "xxx".
  42
  43 2.3 Makefile.common
  44
  45 Your plugins/xxx/Makefile.common should list the source files for your
  46 dissector, in the DISSECTOR_SRC variable, and the header files for your
  47 dissector, if any, in the DISSECTOR_INCLUDES variable.  (The
  48 DISSECTOR_INCLUDES variable should not include moduleinfo.h.)
  49
  50 2.4 moduleinfo.h
  51
  52 Your plugins/xxx/moduleinfo.h file is used to set the version
  53 information for the plugin.  An example follows:
  54
  55 /* Included *after* config.h, in order to re-define these macros */
  56
  57 #ifdef PACKAGE
  58 #undef PACKAGE
  59 #endif
  60
  61 /* Name of package */
  62 #define PACKAGE "xxx"
  63
  64 #ifdef VERSION
  65 #undef VERSION
  66 #endif
  67
  68 /* Version number of package */
  69 #define VERSION "0.0.8"
  70
  71 3. Changes to existing Wireshark files
  72
  73 You will also need to change the plugins/Makefile.am toplevel
  74 Makefile.am, the plugins/Makefile.nmake toplevel Makefile.nmake, the
  75 toplevel Makefile.am file, and the toplevel configure.in file.
  76
  77 3.1  Changes to plugins/Makefile.am
  78
  79 The plugins directory contains a Makefile.am.
  80 You need to change the SUBDIRS directive to reflect the addition of
  81 your plugin:
  82
  83 SUBDIRS = \
  84         gryphon \
  85         mgcp \
  86         xxx
  87
  88
  89 3.2 Changes to plugins/Makefile.nmake
  90
  91 To the Makefile.nmake you need to add your plugin to the all: rule
  92
  93 all: \
  94         gryphon \
  95         mgcp \
  96         xxx
  97
  98 then add a rule for your plugin:
  99
 100 xxx::
 101         cd xxx
 102         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake
 103         cd ..
 104
 105 and finally add to the clean rule support for cleaning up after your
 106 plugin:
 107
 108 clean:
 109         cd gryphon
 110         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 111         cd ../mgcp
 112         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 113         cd ..
 114         cd xxx
 115         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 116         cd ..
 117
 118
 119 distclean: clean
 120         cd gryphon
 121         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
 122         cd ../mgcp
 123         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
 124         cd ..
 125         cd xxx
 126         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
 127         cd ..
 128
 129
 130 maintainer-clean: clean
 131         cd gryphon
 132         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
 133         cd ../mgcp
 134         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
 135         cd ..
 136         cd xxx
 137         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
 138         cd ..
 139
 140
 141 3.3 Changes to the top level Makefile.am
 142
 143 Unfortunately there are quite some several places in the top level
 144 Makefile.am that need to be altered for adding a plugin.
 145
 146 Add your plugin to the plugin_libs and plugin_ldadd (two times):
 147
 148 plugin_libs = \
 149         plugins/gryphon/gryphon.la \
 150         plugins/mgcp/mgcp.la    \
 151         plugins/xxx/xxx.la
 152
 153 if ENABLE_STATIC
 154 plugin_ldadd = \
 155         plugins/gryphon/gryphon.o \
 156         plugins/mgcp/mgcp.o \
 157         plugins/xxx/xxx.o
 158
 159 else          # ENABLE_STATIC
 160 plugin_ldadd = \
 161         "-dlopen" self  \
 162         "-dlopen" plugins/gryphon/gryphon.la \
 163         "-dlopen" plugins/mgcp/mgcp.la \
 164         "-dlopen" plugins/xxx/xxx.la
 165
 166 3.4  Changes to top level configure.in
 167
 168 You need to add your plugins Makefile to the AC_OUTPUT rule in the
 169 configure.in
 170
 171 AC_OUTPUT(
 172   Makefile
 173   doc/Makefile
 174   gtk/Makefile
 175   packaging/Makefile
 176   packaging/nsis/Makefile
 177   packaging/rpm/Makefile
 178   packaging/rpm/wireshark.spec
 179   packaging/svr4/Makefile
 180   packaging/svr4/checkinstall
 181   packaging/svr4/pkginfo
 182   plugins/Makefile
 183   plugins/gryphon/Makefile
 184   plugins/mgcp/Makefile
 185   plugins/xxx/Makefile
 186   tools/Makefile
 187   tools/lemon/Makefile
 188   ,)
 189
 190
 191 4. Development and plugins
 192
 193 Plugins make some aspects of development easier and some harder.
 194
 195 The good news is that if you are working on a single plugin
 196 then you will find recompiling the plugin MUCH faster than
 197 recompiling a dissector and then linking it back into wireshark.
 198
 199 The bad news is that wireshark will not use the plugin unless the
 200 plugin is installed in one of the places it expects to look.
 201
 202 One way to deal with this problem is to set up a working root for
 203 wireshark, say in $HOME/build/root and build wireshark to install
 204 there
 205
 206 ./configure --prefix=${HOME}/build/root;make install
 207
 208 then subsequent rebuilds/installs of your plugin can be accomplished
 209 by going to the plugins/xxx directory and running
 210
 211 make install
 212
 213 5. How to update an "old style" plugin (using plugin_init function)
 214
 215 The plugin registering has changed between 0.10.9 and 0.10.10; everyone
 216 is encouraged to update their plugins as outlined below:
 217
 218     o Remove following include statements from all plugin sources:
 219
 220         #include "plugins/plugin_api.h"
 221         #include "plugins/plugin_api_defs.h"
 222
 223     o Remove the init function.
 224
 225     o Add a new Makefile.common file with the lists of source files and
 226       headers.
 227
 228     o Change the Makefile.am and Makefile.nmake files to match those of
 229       the DOCSIS plugin.
 230
 231 ----------------
 232
 233 Ed Warnicke <hagbard@physics.rutgers.edu>
 234 Guy Harris <guy@alum.mit.edu>
 235
 236 Derived and expanded from the plugin section of README.developers
 237 which was originally written by
 238
 239 James Coe <jammer@cin.net>
 240 Gilbert Ramirez <gram@alumni.rice.edu>
 241 Jeff Foster <jfoste@woodward.com>
 242 Olivier Abad <oabad@cybercable.fr>
 243 Laurent Deniel <laurent.deniel@free.fr>