Writing a "plugin" dissector is not very different from writing a
standard one. In fact all of the functions described in
-README.developer can be used in the plugins exactly as the are used in
+README.developer can be used in the plugins exactly as they are used in
standard dissectors.
-(Note, however, that not all OSes on which Ethereal runs can support
+(Note, however, that not all OSes on which Wireshark runs can support
plugins.)
If you've chosen "xxx" as the name of your plugin (typically, that would
AUTHORS
COPYING
ChangeLog
+CMakeLists.txt
Makefile.am
Makefile.common
Makefile.nmake
moduleinfo.h
+moduleinfo.nmake
+plugin.rc.in
The source files and header files for your dissector
+Examples of these files can be found in plugins/gryphon.
+
2.1 AUTHORS, COPYING, and ChangeLog
-The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
-files; see plugins/docsis for examples.
+The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
+files.
-2.2 Makefile.am and Makefile.nmake
+2.2 CMakeLists.txt
-For your plugins/xxx/Makefile.am and plugins/xxx/Makefile.nmake files,
-see the corresponding files in plugins/docsis. Replace all occurrences
-of "docsis" in those files with "xxx".
+For your plugins/xxx/CMakeLists.txt file, see the corresponding file in
+plugins/gryphon. Replace all occurrences of "gryphon" in those files
+with "xxx" and add your source files to the DISSECTOR_SRC variable.
-2.3 Makefile.common
+2.3 Makefile.am
-Your plugins/xxx/Makefile.common should list the source files for your
-dissector, in the DISSECTOR_SRC variable, and the header files for your
-dissector, if any, in the DISSECTOR_INCLUDES variable. (The
-DISSECTOR_INCLUDES variable should not include moduleinfo.h.)
+For your plugins/xxx/Makefile.am file, see the corresponding file in
+plugins/gryphon. Replace all occurrences of "gryphon" in those files
+with "xxx".
-2.4 moduleinfo.h
+2.4 Makefile.common
-Your plugins/xxx/moduleinfo.h file is used to set the version
-information for the plugin. An example follows:
+Your plugins/xxx/Makefile.common should only list the main source file(s),
+which exports register_*() and handoff_*(), for your dissector in the
+DISSECTOR_SRC variable. All other supporting source files should be listed
+in the DISSECTOR_SUPPORT_SRC variable, and this variable added to the
+xxx_la_SOURCES variable in Makefile.am.
+The header files for your dissector, if any, must be listed in the
+DISSECTOR_INCLUDES variable. The DISSECTOR_INCLUDES variable should not
+include moduleinfo.h.
-/* Included *after* config.h, in order to re-define these macros */
+2.5 Makefile.nmake
-#ifdef PACKAGE
-#undef PACKAGE
-#endif
+For your plugins/xxx/Makefile.nmake file, see the corresponding file in
+plugins/gryphon. No modifications are needed here.
-/* Name of package */
-#define PACKAGE "xxx"
+2.6 moduleinfo.h
-#ifdef VERSION
-#undef VERSION
-#endif
+Your plugins/xxx/moduleinfo.h file is used to set the version information
+for the plugin.
-/* Version number of package */
-#define VERSION "0.0.8"
+2.7 moduleinfo.nmake
-3. Changes to existing Ethereal files
+Your plugins/xxx/moduleinfo.nmake is used to set the version information
+for building the plugin. Its contents should match that in moduleinfo.h
-You will also need to change the plugins/Makefile.am toplevel
-Makefile.am, the plugins/Makefile.nmake toplevel Makefile.nmake, the
-toplevel Makefile.am file, and the toplevel configure.in file.
+2.8 plugin.rc.in
-3.1 Changes to plugins/Makefile.am
+Your plugins/xxx/plugin.rc.in is the Windows resource template file
+used to add the plugin specific information as resources to the DLL.
+No modifications are needed here.
-The plugins directory contains a Makefile.am.
-You need to change the SUBDIRS directive to reflect the addition of
-your plugin:
+3. Changes to existing Wireshark files
-SUBDIRS = \
- gryphon \
- mgcp \
- xxx
+You will also need to change the following files:
+ configure.in
+ CMakeLists.txt
+ epan/Makefile.am
+ Makefile.am
+ packaging/nsis/Makefile.nmake
+ packaging/nsis/wireshark.nsi
+ plugins/Makefile.am
+ plugins/Makefile.nmake
+You might also want to search your Wireshark development directory for
+occurrences of an existing plugin name, in case this document is out of
+date with the current directory structure. For example,
-3.2 Changes to plugins/Makefile.nmake
+ grep -rl gryphon .
-To the Makefile.nmake you need to add your plugin to the all: rule
+could be used from a shell prompt.
-all: \
- gryphon \
- mgcp \
- xxx
-
-then add a rule for your plugin:
-
-xxx::
- cd xxx
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake
- cd ..
-
-and finally add to the clean rule support for cleaning up after your
-plugin:
-
-clean:
- cd gryphon
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
- cd ../mgcp
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
- cd ..
- cd xxx
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
- cd ..
-
-
-distclean: clean
- cd gryphon
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
- cd ../mgcp
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
- cd ..
- cd xxx
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
- cd ..
-
-
-maintainer-clean: clean
- cd gryphon
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
- cd ../mgcp
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
- cd ..
- cd xxx
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
- cd ..
+3.1 Changes to plugins/Makefile.am
+The plugins directory contains a Makefile.am. You need to change the
+SUBDIRS directive to reflect the addition of your plugin:
-3.3 Changes to the top level Makefile.am
+SUBDIRS = $(_CUSTOM_SUBDIRS_) \
+ ...
+ gryphon \
+ irda \
+ xxx \
-Unfortunately there are quite some several places in the top level
-Makefile.am that need to be altered for adding a plugin.
+3.2 Changes to plugins/Makefile.nmake
-Add your plugin to the plugin_libs and plugin_ldadd (two times):
+In plugins/Makefile.nmake you need to add to the PLUGINS_LIST
+(in alphabetical order) the name of your dissector (actually:
+the name of the plugins sub-directory which contains your dissector).
-plugin_libs = \
- plugins/gryphon/gryphon.la \
- plugins/mgcp/mgcp.la \
- plugins/xxx/xxx.la
+3.3 Changes to the top level Makefile.am
-if ENABLE_STATIC
-plugin_ldadd = \
- plugins/gryphon/gryphon.o \
- plugins/mgcp/mgcp.o \
- plugins/xxx/xxx.o
+Add your plugin (in alphabetical order) to the plugin_ldadd:
+
+if HAVE_PLUGINS
-else # ENABLE_STATIC
plugin_ldadd = \
- "-dlopen" self \
- "-dlopen" plugins/gryphon/gryphon.la \
- "-dlopen" plugins/mgcp/mgcp.la \
- "-dlopen" plugins/xxx/xxx.la
+ ...
+ -dlopen plugins/gryphon/gryphon.la \
+ -dlopen plugins/irda/irda.la \
+ -dlopen plugins/xxx/xxx.la \
+ ...
-3.4 Changes to top level configure.in
+3.4 Changes to the top level configure.in
-You need to add your plugins Makefile to the AC_OUTPUT rule in the
-configure.in
+You need to add your plugins Makefile (in alphbetical order) to the AC_OUTPUT
+rule in the configure.in
AC_OUTPUT(
- Makefile
- doc/Makefile
- gtk/Makefile
- packaging/Makefile
- packaging/nsis/Makefile
- packaging/rpm/Makefile
- packaging/rpm/ethereal.spec
- packaging/svr4/Makefile
- packaging/svr4/checkinstall
- packaging/svr4/pkginfo
- plugins/Makefile
+ ...
plugins/gryphon/Makefile
- plugins/mgcp/Makefile
+ plugins/irda/Makefile
plugins/xxx/Makefile
- tools/Makefile
- tools/lemon/Makefile
+ ...
,)
+3.5 Changes to epan/Makefile.am
+
+Add the relative path of your plugin (in alphbetical order) to plugin_src:
+
+plugin_src = \
+ ...
+ ../plugins/gryphon/packet-gryphon.c \
+ ../plugins/irda/packet-irda.c \
+ ../plugins/xxx/packet-xxx.c \
+ ...
+
+3.6 Changes to CMakeLists.txt
+
+Add your plugin (in alphabetical order) to the PLUGIN_SRC_DIRS:
+
+if(ENABLE_PLUGINS)
+ ...
+ set(PLUGIN_SRC_DIRS
+ ...
+ plugins/gryphon
+ plugins/irda
+ plugins/xxx
+ ...
+
+3.7 Changes to the installers
+
+If you want to include your plugin in an installer you have to add lines
+in the NSIS installer Makefile.nmake and wireshark.nsi files.
-4. Development and plugins
+For the NSIS installer:
+
+ Add ../../plugins/xxx/xxx.dll to the list of plugins for the
+ PLUGINS variable in packaging/nsis/Makefile.nmake.
+
+ Add
+
+ File "..\..\plugins\xxx\xxx.dll"
+
+ to the list of "File" statements in the "Dissector Plugins"
+ section in packaging/nsis/wireshark.nsi.
+
+The U3 and PortableApps installers build their manifests, including plugins,
+from packaging/nsis/wireshark.nsi via the packaging/ws-manifest.pl script.
+
+4. Development and plugins on Unix
Plugins make some aspects of development easier and some harder.
-The good news is that if you are working on a single plugin
-then you will find recompiling the plugin MUCH faster than
-recompiling a dissector and then linking it back into ethereal.
+The first thing is that you'll have to run autogen.sh and configure
+once more to setup your build environment.
+
+The good news is that if you are working on a single plugin
+then you will find recompiling the plugin MUCH faster than
+recompiling a dissector and then linking it back into Wireshark.
+
+The bad news is that Wireshark will not use the plugins unless the
+plugins are installed in one of the places it expects them to find.
-The bad news is that ethereal will not use the plugin unless the
-plugin is installed in one of the places it expects to look.
+One way of dealing with this problem is to set an environment variable
+when running Wireshark: WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1.
-One way to deal with this problem is to set up a working root for
-ethereal, say in $HOME/build/root and build ethereal to install
+Another way to deal with this problem is to set up a working root for
+wireshark, say in $HOME/build/root and build wireshark to install
there
./configure --prefix=${HOME}/build/root;make install
-then subsequent rebuilds/installs of your plugin can be accomplished
-by going to the plugins/xxx directory and running
+then subsequent rebuilds/installs of your plugin can be accomplished
+by going to the plugins/xxx directory and running
make install
-5. How to update an "old style" plugin (using plugin_init function)
+5. Update "old style" plugins
+
+5.1 How to update an "old style" plugin (using plugin_register and
+ plugin_reg_handoff functions).
+
+The plugin registration has changed with the extension of the build
+scripts. These now generate the additional code needed for plugin
+encapsulation in plugin.c. When using the new style build scripts,
+stips the parts outlined below:
+
+ o Remove the following include statements:
+
+ #include <gmodule.h>
+ #include "moduleinfo.h"
+
+ o Removed the definition:
+
+ #ifndef ENABLE_STATIC
+ G_MODULE_EXPORT gchar version[] = VERSION;
+ #endif
+
+ o Move relevant code from the blocks and delete these functions:
+
+ #ifndef ENABLE_STATIC
+ plugin_reg_handoff()
+ ....
+ #endif
+
+ #ifndef ENABLE_STATIC
+ plugin_register()
+ ....
+ #endif
+
+This will leave a clean dissector source file without plugin specifics.
+
+5.2 How to update an "old style" plugin (using plugin_init function)
The plugin registering has changed between 0.10.9 and 0.10.10; everyone
is encouraged to update their plugins as outlined below:
Jeff Foster <jfoste@woodward.com>
Olivier Abad <oabad@cybercable.fr>
Laurent Deniel <laurent.deniel@free.fr>
+Jaap Keuter <jaap.keuter@xs4all.nl>
git.samba.org / obnox / wireshark / wip.git / blobdiff