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 they 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 CMakeLists.txt
  27 Makefile.am
  28 Makefile.common
  29 Makefile.nmake
  30 moduleinfo.h
  31 moduleinfo.nmake
  32 plugin.rc.in
  33 The source files and header files for your dissector
  34
  35 Examples of these files can be found in plugins/gryphon.
  36
  37 2.1 AUTHORS, COPYING, and ChangeLog
  38
  39 The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
  40 files.
  41
  42 2.2 CMakeLists.txt
  43
  44 For your plugins/xxx/CMakeLists.txt file, see the corresponding file in
  45 plugins/gryphon. Replace all occurrences of "gryphon" in those files
  46 with "xxx" and add your source files to the DISSECTOR_SRC variable.
  47
  48 2.3 Makefile.am
  49
  50 For your plugins/xxx/Makefile.am file, see the corresponding file in
  51 plugins/gryphon. Replace all occurrences of "gryphon" in those files
  52 with "xxx".
  53
  54 2.4 Makefile.common
  55
  56 Your plugins/xxx/Makefile.common should only list the main source file(s),
  57 which exports register_*() and handoff_*(), for your dissector in the
  58 DISSECTOR_SRC variable, and all other supporting source files in the
  59 DISSECTOR_SUPPORT_SRC variable.
  60 The header files for your dissector, if any, must be listed in the
  61 DISSECTOR_INCLUDES variable. The DISSECTOR_INCLUDES variable should not
  62 include moduleinfo.h.
  63
  64 2.5 Makefile.nmake
  65
  66 For your plugins/xxx/Makefile.nmake file, see the corresponding file in
  67 plugins/gryphon. No modifications are needed here.
  68
  69 2.6 moduleinfo.h
  70
  71 Your plugins/xxx/moduleinfo.h file is used to set the version information
  72 for the plugin.
  73
  74 2.7 moduleinfo.nmake
  75
  76 Your plugins/xxx/moduleinfo.nmake is used to set the version information
  77 for building the plugin. Its contents should match that in moduleinfo.h
  78
  79 2.8 plugin.rc.in
  80
  81 Your plugins/xxx/plugin.rc.in is the Windows resource template file
  82 used to add the plugin specific information as resources to the DLL.
  83 No modifications are needed here.
  84
  85 3. Changes to existing Wireshark files
  86
  87 You will also need to change the following files:
  88         configure.in
  89         CMakeLists.txt
  90         epan/Makefile.am
  91         Makefile.am
  92         packaging/nsis/Makefile.nmake
  93         packaging/nsis/wireshark.nsi
  94         plugins/Makefile.am
  95         plugins/Makefile.nmake
  96
  97 You might also want to search your Wireshark development directory for
  98 occurrences of an existing plugin name, in case this document is out of
  99 date with the current directory structure. For example,
 100
 101         grep -rl gryphon .
 102
 103 could be used from a shell prompt.
 104
 105 3.1  Changes to plugins/Makefile.am
 106
 107 The plugins directory contains a Makefile.am.  You need to change the
 108 SUBDIRS directive to reflect the addition of your plugin:
 109
 110 SUBDIRS = $(_CUSTOM_SUBDIRS_) \
 111         ...
 112         gryphon \
 113         irda \
 114         xxx \
 115
 116 3.2 Changes to plugins/Makefile.nmake
 117
 118 In plugins/Makefile.nmake you need to add to the PLUGINS_LIST
 119 (in alphabetical order) the name of your dissector (actually:
 120 the name of the plugins sub-directory which contains your dissector).
 121
 122 3.3 Changes to the top level Makefile.am
 123
 124 Add your plugin (in alphabetical order) to the plugin_ldadd:
 125
 126 if HAVE_PLUGINS
 127
 128 plugin_ldadd = \
 129         ...
 130         -dlopen plugins/gryphon/gryphon.la      \
 131         -dlopen plugins/irda/irda.la    \
 132         -dlopen plugins/xxx/xxx.la      \
 133         ...
 134
 135 3.4  Changes to the top level configure.in
 136
 137 You need to add your plugins Makefile (in alphbetical order) to the AC_OUTPUT
 138 rule in the configure.in
 139
 140 AC_OUTPUT(
 141   ...
 142   plugins/gryphon/Makefile
 143   plugins/irda/Makefile
 144   plugins/xxx/Makefile
 145   ...
 146   ,)
 147
 148 3.5  Changes to epan/Makefile.am
 149
 150 Add the relative path of your plugin (in alphbetical order) to plugin_src:
 151
 152 plugin_src = \
 153         ...
 154         ../plugins/gryphon/packet-gryphon.c \
 155         ../plugins/irda/packet-irda.c \
 156         ../plugins/xxx/packet-xxx.c \
 157         ...
 158
 159 3.6  Changes to CMakeLists.txt
 160
 161 Add your plugin (in alphabetical order) to the PLUGIN_SRC_DIRS:
 162
 163 if(ENABLE_PLUGINS)
 164         ...
 165         set(PLUGIN_SRC_DIRS
 166                 ...
 167                 plugins/gryphon
 168                 plugins/irda
 169                 plugins/xxx
 170                 ...
 171
 172 3.7  Changes to the installers
 173
 174 If you want to include your plugin in an installer you have to add lines
 175 in the NSIS installer Makefile.nmake and wireshark.nsi files.
 176
 177 For the NSIS installer:
 178
 179         Add ../../plugins/xxx/xxx.dll to the list of plugins for the
 180         PLUGINS variable in packaging/nsis/Makefile.nmake.
 181
 182         Add
 183
 184                 File "..\..\plugins\xxx\xxx.dll"
 185
 186         to the list of "File" statements in the "Dissector Plugins"
 187         section in packaging/nsis/wireshark.nsi.
 188
 189 The U3 and PortableApps installers build their manifests, including plugins,
 190 from packaging/nsis/wireshark.nsi via the packaging/ws-manifest.pl script.
 191
 192 4. Development and plugins on Unix
 193
 194 Plugins make some aspects of development easier and some harder.
 195
 196 The first thing is that you'll have to run autogen.sh and configure
 197 once more to setup your build environment.
 198
 199 The good news is that if you are working on a single plugin
 200 then you will find recompiling the plugin MUCH faster than
 201 recompiling a dissector and then linking it back into Wireshark.
 202
 203 The bad news is that Wireshark will not use the plugins unless the
 204 plugins are installed in one of the places it expects them to find.
 205
 206 One way of dealing with this problem is to set an environment variable
 207 when running Wireshark: WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1.
 208
 209 Another 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 statements:
 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>