doc/README.plugins

   1 $Id$
   2
   3 1. Plugins
   4
   5 Writing a "plugin" dissector is not very different from writing a standard
   6 one.  In fact all of the functions described in README.developer can be
   7 used in the plugins exactly as they are used in standard dissectors.
   8
   9 (Note, however, that not all OSes on which Wireshark runs can support
  10 plugins.)
  11
  12 If you've chosen "foo" as the name of your plugin (typically, that would
  13 be a short name for your protocol, in all lower case), the following
  14 instructions tell you how to implement it as a plugin.  All occurrences
  15 of "foo" below should be replaced by the name of your plugin.
  16
  17 2. The directory for the plugin, and its files
  18
  19 The plugin should be placed in a new plugins/foo directory which should
  20 contain at least the following files:
  21
  22 AUTHORS
  23 COPYING
  24 ChangeLog
  25 CMakeLists.txt
  26 Makefile.am
  27 Makefile.common
  28 Makefile.nmake
  29 moduleinfo.h
  30 moduleinfo.nmake
  31 plugin.rc.in
  32 And of course the source and header files for your dissector.
  33
  34 Examples of these files can be found in plugins/gryphon.
  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 CMakeLists.txt
  42
  43 For your plugins/foo/CMakeLists.txt file, see the corresponding file in
  44 plugins/gryphon.  Replace all occurrences of "gryphon" in those files
  45 with "foo" and add your source files to the DISSECTOR_SRC variable.
  46
  47 2.3 Makefile.am
  48
  49 For your plugins/foo/Makefile.am file, see the corresponding file in
  50 plugins/gryphon.  Replace all occurrences of "gryphon" in those files
  51 with "foo".
  52
  53 2.4 Makefile.common
  54
  55 Your plugins/foo/Makefile.common should only list the main source file(s),
  56 which exports register_*() and handoff_*(), for your dissector in the
  57 DISSECTOR_SRC variable.  All other supporting source files should be
  58 listed in the DISSECTOR_SUPPORT_SRC variable.
  59 The header files for your dissector, if any, must be listed in the
  60 DISSECTOR_INCLUDES variable.  The DISSECTOR_INCLUDES variable should not
  61 include moduleinfo.h.
  62
  63 2.5 Makefile.nmake
  64
  65 For your plugins/foo/Makefile.nmake file, see the corresponding file in
  66 plugins/gryphon.  No modifications are needed here.
  67
  68 2.6 moduleinfo.h
  69
  70 Your plugins/foo/moduleinfo.h file is used to set the version information
  71 for the plugin.
  72
  73 2.7 moduleinfo.nmake
  74
  75 Your plugins/foo/moduleinfo.nmake is used to set the version information
  76 for building the plugin.  Its contents should match that in moduleinfo.h
  77
  78 2.8 plugin.rc.in
  79
  80 Your plugins/foo/plugin.rc.in is the Windows resource template file used
  81 to add the plugin specific information as resources to the DLL.
  82 No modifications are needed here.
  83
  84 3. Changes to existing Wireshark files
  85
  86 There are two ways to add your plugin dissector to the build, as a custom
  87 extension or as a permanent addition.  The custom extension is easy to
  88 configure, but won't be used for inclusion in the distribution if that's
  89 your goal.  Setting up the permanent addition is somewhat more involved.
  90
  91 3.1 Custom extension
  92
  93 Go to the plugins directory and copy the three Custom.*.example files to
  94 Custom.*.  Now you have three files ready for building a plugin with the
  95 name "foo".  Replace the name if you so require.
  96
  97 If you want to add the plugin to your own Windows installer add a text
  98 file named custom_plugins.txt to the packaging/nsis directory, with a
  99 "File" statement for NSIS:
 100
 101 File "..\..\plugins\foo\foo.dll"
 102
 103 Then open packaging/nsis/Custom.nmake and add the relative path to your
 104 DLL to CUSTOM_PLUGINS:
 105
 106 CUSTOM_PLUGINS= \
 107         ../../plugins/foo/foo.dll
 108
 109 3.2 Permanent addition
 110
 111 In order to be able to permanently add a plugin take the following steps.
 112 You will need to change the following files:
 113         configure.ac
 114         CMakeLists.txt
 115         epan/Makefile.am
 116         Makefile.am
 117         packaging/nsis/Makefile.nmake
 118         packaging/nsis/wireshark.nsi
 119         plugins/Makefile.am
 120         plugins/Makefile.nmake
 121
 122 You might also want to search your Wireshark development directory for
 123 occurrences of an existing plugin name, in case this document is out of
 124 date with the current directory structure.  For example,
 125
 126         grep -rl gryphon .
 127
 128 could be used from a shell prompt.
 129
 130 3.2.1  Changes to plugins/Makefile.am
 131
 132 The plugins directory contains a Makefile.am.  You need to add to SUBDIRS
 133 (in alphabetical order) the name of your plugin:
 134
 135 SUBDIRS = $(_CUSTOM_SUBDIRS_) \
 136         ...
 137         ethercat \
 138         foo \
 139         gryphon \
 140         irda \
 141
 142
 143 3.2.2 Changes to plugins/Makefile.nmake
 144
 145 In plugins/Makefile.nmake you need to add to PLUGINS_LIST (in alphabetical
 146 order) the name of your plugin:
 147
 148 PLUGIN_LIST = \
 149         ...
 150         ethercat    \
 151         foo         \
 152         gryphon     \
 153         irda        \
 154
 155 3.2.3 Changes to the top level Makefile.am
 156
 157 Add your plugin (in alphabetical order) to plugin_ldadd:
 158
 159 if HAVE_PLUGINS
 160
 161 plugin_ldadd = $(_CUSTOM_plugin_ldadd_) \
 162         ...
 163         -dlopen plugins/ethercat/ethercat.la \
 164         -dlopen plugins/foo/foo.la \
 165         -dlopen plugins/gryphon/gryphon.la \
 166         -dlopen plugins/irda/irda.la \
 167         ...
 168
 169 3.2.4  Changes to the top level configure.ac
 170
 171 You need to add your plugins Makefile (in alphbetical order) to the
 172 AC_OUTPUT rule in the configure.ac
 173
 174 AC_OUTPUT(
 175   ...
 176   plugins/ethercat/Makefile
 177   plugins/foo/Makefile
 178   plugins/gryphon/Makefile
 179   plugins/irda/Makefile
 180   ...
 181   ,)
 182
 183 3.2.5  Changes to epan/Makefile.am
 184
 185 Add the relative path of all your plugin source files (in alphbetical
 186 order) to plugin_src:
 187
 188 plugin_src = \
 189         ...
 190         ../plugins/ethercat/packet-ioraw.c \
 191         ../plugins/ethercat/packet-nv.c \
 192         ../plugins/foo/packet-foo.c \
 193         ../plugins/gryphon/packet-gryphon.c \
 194         ../plugins/irda/packet-ircomm.c \
 195         ../plugins/irda/packet-irda.c \
 196         ...
 197
 198 3.2.6  Changes to CMakeLists.txt
 199
 200 Add your plugin (in alphabetical order) to the PLUGIN_SRC_DIRS:
 201
 202 if(ENABLE_PLUGINS)
 203         ...
 204         set(PLUGIN_SRC_DIRS
 205                 ...
 206                 plugins/ethercat
 207                 plugins/foo
 208                 plugins/gryphon
 209                 plugins/irda
 210                 ...
 211
 212 3.2.7  Changes to the installers
 213
 214 If you want to include your plugin in an installer you have to add lines
 215 in the NSIS installer Makefile.nmake and wireshark.nsi files.
 216
 217 3.2.7.1  Changes to packaging/nsis/Makefile.nmake
 218
 219 Add the relative path of your plugin DLL (in alphbetical order) to PLUGINS:
 220
 221 PLUGINS= \
 222         ...
 223         ../../plugins/ethercat/ethercat.dll \
 224         ../../plugins/foo/foo.dll \
 225         ../../plugins/gryphon/gryphon.dll \
 226         ../../plugins/irda/irda.dll \
 227
 228 3.2.7.2  Changes to packaging/nsis/wireshark.nsi
 229
 230 Add the relative path of your plugin DLL (in alphbetical order) to the
 231 list of "File" statements in the "Dissector Plugins" section:
 232
 233 File "${STAGING_DIR}\plugins\${VERSION}\ethercat.dll"
 234 File "${STAGING_DIR}\plugins\${VERSION}\foo.dll"
 235 File "${STAGING_DIR}\plugins\${VERSION}\gryphon.dll"
 236 File "${STAGING_DIR}\plugins\${VERSION}\irda.dll"
 237
 238 3.2.7.3  Other installers
 239
 240 The U3 and PortableApps installers build their manifests, including
 241 plugins, from wireshark.nsi via the packaging/ws-manifest.pl script.
 242
 243 4. Development and plugins on Unix
 244
 245 Plugins make some aspects of development easier and some harder.
 246
 247 The first thing is that you'll have to run autogen.sh and configure once
 248 more to setup your build environment.
 249
 250 The good news is that if you are working on a single plugin then you will
 251 find recompiling the plugin MUCH faster than recompiling a dissector and
 252 then linking it back into Wireshark. Use "make -C plugins" to compile just
 253 your plugins.
 254
 255 The bad news is that Wireshark will not use the plugins unless the plugins
 256 are installed in one of the places it expects them to find.
 257
 258 One way of dealing with this problem is to set an environment variable
 259 when running Wireshark: WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1.
 260
 261 Another way to deal with this problem is to set up a working root for
 262 wireshark, say in $HOME/build/root and build wireshark to install
 263 there
 264
 265 ./configure --prefix=${HOME}/build/root && make install
 266
 267 then subsequent rebuilds/installs of your plugin can be accomplished
 268 by going to the plugins/foo directory and running
 269
 270 make install
 271
 272 5. Update "old style" plugins
 273
 274 5.1 How to update an "old style" plugin (using plugin_register and
 275     plugin_reg_handoff functions).
 276
 277 The plugin registration has changed with the extension of the build
 278 scripts. These now generate the additional code needed for plugin
 279 encapsulation in plugin.c. When using the new style build scripts,
 280 stips the parts outlined below:
 281
 282     o Remove the following include statements:
 283
 284         #include <gmodule.h>
 285         #include "moduleinfo.h"
 286
 287     o Removed the definition:
 288
 289         #ifndef ENABLE_STATIC
 290         WS_DLL_PUBLIC_DEF gchar version[] = VERSION;
 291         #endif
 292
 293     o Move relevant code from the blocks and delete these functions:
 294
 295         #ifndef ENABLE_STATIC
 296         plugin_reg_handoff()
 297         ....
 298         #endif
 299
 300         #ifndef ENABLE_STATIC
 301         plugin_register()
 302         ....
 303         #endif
 304
 305 This will leave a clean dissector source file without plugin specifics.
 306
 307 5.2 How to update an "old style" plugin (using plugin_init function)
 308
 309 The plugin registering has changed between 0.10.9 and 0.10.10; everyone
 310 is encouraged to update their plugins as outlined below:
 311
 312     o Remove following include statements from all plugin sources:
 313
 314         #include "plugins/plugin_api.h"
 315         #include "plugins/plugin_api_defs.h"
 316
 317     o Remove the init function.
 318
 319     o Add a new Makefile.common file with the lists of source files and
 320       headers.
 321
 322     o Change the Makefile.am and Makefile.nmake files to match those of
 323       the DOCSIS plugin.
 324
 325 ----------------
 326
 327 Ed Warnicke <hagbard@physics.rutgers.edu>
 328 Guy Harris <guy@alum.mit.edu>
 329
 330 Derived and expanded from the plugin section of README.developers
 331 which was originally written by
 332
 333 James Coe <jammer@cin.net>
 334 Gilbert Ramirez <gram@alumni.rice.edu>
 335 Jeff Foster <jfoste@woodward.com>
 336 Olivier Abad <oabad@cybercable.fr>
 337 Laurent Deniel <laurent.deniel@free.fr>
 338 Jaap Keuter <jaap.keuter@xs4all.nl>