1. Plugins
-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
-standard dissectors.
+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 they are used in standard dissectors.
(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
+If you've chosen "foo" as the name of your plugin (typically, that would
be a short name for your protocol, in all lower case), the following
instructions tell you how to implement it as a plugin. All occurrences
-of "xxx" below should be replaced by the name of your plugin.
+of "foo" below should be replaced by the name of your plugin.
2. The directory for the plugin, and its files
-The plugin should be placed in a new plugins/xxx directory which should
-contain minimally the following files:
+The plugin should be placed in a new plugins/foo directory which should
+contain at least the following files:
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
+And of course the source and header files for your dissector.
-Examples of these files can be found in plugins/agentx.
+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.
-2.2 Makefile.am
+2.2 CMakeLists.txt
-For your plugins/xxx/Makefile.am file, see the corresponding file in
-plugins/agentx. Replace all occurrences of "agentx" in those files with "xxx".
+For your plugins/foo/CMakeLists.txt file, see the corresponding file in
+plugins/gryphon. Replace all occurrences of "gryphon" in those files
+with "foo" 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 all supporting source files
-in the DISSECTOR_SUPPORT_SRC variable.
+For your plugins/foo/Makefile.am file, see the corresponding file in
+plugins/gryphon. Replace all occurrences of "gryphon" in those files
+with "foo".
+
+2.4 Makefile.common
+
+Your plugins/foo/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.
The header files for your dissector, if any, must be listed in the
-DISSECTOR_INCLUDES variable. The DISSECTOR_INCLUDES variable should not
+DISSECTOR_INCLUDES variable. The DISSECTOR_INCLUDES variable should not
include moduleinfo.h.
-2.4 Makefile.nmake
+2.5 Makefile.nmake
-For your plugins/xxx/Makefile.nmake file, see the corresponding file in
-plugins/agentx. No modifications are needed here.
+For your plugins/foo/Makefile.nmake file, see the corresponding file in
+plugins/gryphon. No modifications are needed here.
-2.5 moduleinfo.h
+2.6 moduleinfo.h
-Your plugins/xxx/moduleinfo.h file is used to set the version information
+Your plugins/foo/moduleinfo.h file is used to set the version information
for the plugin.
-2.6 moduleinfo.nmake
+2.7 moduleinfo.nmake
-Your plugins/xxx/moduleinfo.nmake is used to set the version information
-for building the plugin. Its contents should match that in moduleinfo.h
+Your plugins/foo/moduleinfo.nmake is used to set the version information
+for building the plugin. Its contents should match that in moduleinfo.h
-2.7 plugin.rc.in
+2.8 plugin.rc.in
-Your plugins/xxx/plugin.rc.in is the Windows resource template file
-used to add the plugin specific information as resources to the DLL.
+Your plugins/foo/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.
3. Changes to existing Wireshark files
-You will also need to change the plugins/Makefile.am, the
-plugins/Makefile.nmake, the toplevel Makefile.am file, and the
-toplevel configure.in file.
+There are two ways to add your plugin dissector to the build, as a custom
+extension or as a permanent addition. The custom extension is easy to
+configure, but won't be used for inclusion in the distribution if that's
+your goal. Setting up the permanent addition is somewhat more involved.
-3.1 Changes to plugins/Makefile.am
+3.1 Custom extension
-The plugins directory contains a Makefile.am. You need to change the
-SUBDIRS directive to reflect the addition of your plugin:
+Go to the plugins directory and copy the three Custom.*.example files to
+Custom.*. Now you have three files ready for building a plugin with the
+name "foo". Replace the name if you so require.
-SUBDIRS = \
- gryphon \
- mgcp \
- xxx
+If you want to add the plugin to your own Windows installer add a text
+file named custom_plugins.txt to the packaging/nsis directory, with a
+"File" statement for NSIS:
+File "..\..\plugins\foo\foo.dll"
-3.2 Changes to plugins/Makefile.nmake
+Then open packaging/nsis/Custom.nmake and add the relative path to your
+DLL to CUSTOM_PLUGINS:
-To the Makefile.nmake you need to add your plugin to the all: rule
+CUSTOM_PLUGINS= \
+ ../../plugins/foo/foo.dll
-all: \
- gryphon \
- mgcp \
- xxx
+3.2 Permanent addition
-then add a rule for your plugin:
+In order to be able to permanently add a plugin take the following steps.
+You will need to change the following files:
+ configure.ac
+ CMakeLists.txt
+ epan/Makefile.am
+ Makefile.am
+ packaging/nsis/Makefile.nmake
+ packaging/nsis/wireshark.nsi
+ plugins/Makefile.am
+ plugins/Makefile.nmake
-xxx:
- cd xxx
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake
- cd ..
+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,
-and add to the clean rules support for cleaning up after your
-plugin:
+ grep -rl gryphon .
-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 ..
+could be used from a shell prompt.
+3.2.1 Changes to plugins/Makefile.am
-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 ..
+The plugins directory contains a Makefile.am. You need to add to SUBDIRS
+(in alphabetical order) the name of your plugin:
+SUBDIRS = $(_CUSTOM_SUBDIRS_) \
+ ...
+ ethercat \
+ foo \
+ gryphon \
+ irda \
-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 ..
-
-Finally add a copy command to install-plugins rule:
- xcopy mgcp\*.dll $(VERSION) /d
- xcopy xxx\*.dll $(VERSION) /d
+3.2.2 Changes to plugins/Makefile.nmake
-3.3 Changes to the top level Makefile.am
+In plugins/Makefile.nmake you need to add to PLUGINS_LIST (in alphabetical
+order) the name of your plugin:
-Unfortunately there are quite some several places in the top level
-Makefile.am that need to be altered for adding a plugin.
+PLUGIN_LIST = \
+ ...
+ ethercat \
+ foo \
+ gryphon \
+ irda \
-Add your plugin to the plugin_libs and plugin_ldadd:
+3.2.3 Changes to the top level Makefile.am
-plugin_libs = \
- plugins/gryphon/gryphon.la \
- plugins/mgcp/mgcp.la \
- plugins/xxx/xxx.la
+Add your plugin (in alphabetical order) to plugin_ldadd:
-if ENABLE_STATIC
-plugin_ldadd = (plugin_libs)
+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
+plugin_ldadd = $(_CUSTOM_plugin_ldadd_) \
+ ...
+ -dlopen plugins/ethercat/ethercat.la \
+ -dlopen plugins/foo/foo.la \
+ -dlopen plugins/gryphon/gryphon.la \
+ -dlopen plugins/irda/irda.la \
+ ...
-3.4 Changes to top level configure.in
+3.2.4 Changes to the top level configure.ac
-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.ac
AC_OUTPUT(
- Makefile
- doc/Makefile
- gtk/Makefile
- packaging/Makefile
- packaging/nsis/Makefile
- packaging/rpm/Makefile
- packaging/rpm/wireshark.spec
- packaging/svr4/Makefile
- packaging/svr4/checkinstall
- packaging/svr4/pkginfo
- plugins/Makefile
+ ...
+ plugins/ethercat/Makefile
+ plugins/foo/Makefile
plugins/gryphon/Makefile
- plugins/mgcp/Makefile
- plugins/xxx/Makefile
- tools/Makefile
- tools/lemon/Makefile
+ plugins/irda/Makefile
+ ...
,)
-3.5 Changes to the installers
+3.2.5 Changes to epan/Makefile.am
-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, and the U3
-installer makefile.nmake file.
+Add the relative path of all your plugin source files (in alphbetical
+order) to plugin_src:
-For the NSIS installer:
+plugin_src = \
+ ...
+ ../plugins/ethercat/packet-ioraw.c \
+ ../plugins/ethercat/packet-nv.c \
+ ../plugins/foo/packet-foo.c \
+ ../plugins/gryphon/packet-gryphon.c \
+ ../plugins/irda/packet-ircomm.c \
+ ../plugins/irda/packet-irda.c \
+ ...
+
+3.2.6 Changes to CMakeLists.txt
+
+Add your plugin (in alphabetical order) to the PLUGIN_SRC_DIRS:
+
+if(ENABLE_PLUGINS)
+ ...
+ set(PLUGIN_SRC_DIRS
+ ...
+ plugins/ethercat
+ plugins/foo
+ plugins/gryphon
+ plugins/irda
+ ...
+
+3.2.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.
- Add ../../plugins/xxx/xxx.dll to the list of plugins for the
- PLUGINS variable in packaging/nsis/Makefile.nmake.
+3.2.7.1 Changes to packaging/nsis/Makefile.nmake
- Add
+Add the relative path of your plugin DLL (in alphbetical order) to PLUGINS:
- File "..\..\plugins\xxx\xxx.dll"
+PLUGINS= \
+ ...
+ ../../plugins/ethercat/ethercat.dll \
+ ../../plugins/foo/foo.dll \
+ ../../plugins/gryphon/gryphon.dll \
+ ../../plugins/irda/irda.dll \
- to the list of "File" statements in the "Dissector Plugins"
- section in packaging/nsis/wireshark.nsi.
+3.2.7.2 Changes to packaging/nsis/wireshark.nsi
-For the U3 installer:
+Add the relative path of your plugin DLL (in alphbetical order) to the
+list of "File" statements in the "Dissector Plugins" section:
- Add
+File "${STAGING_DIR}\plugins\${VERSION}\ethercat.dll"
+File "${STAGING_DIR}\plugins\${VERSION}\foo.dll"
+File "${STAGING_DIR}\plugins\${VERSION}\gryphon.dll"
+File "${STAGING_DIR}\plugins\${VERSION}\irda.dll"
- $(COPY) $(TOPDIR)\plugins\xxx\xxx.dll $(DEVICE)\plugins\$(VERSION) $(COPY_FLAGS)
+3.2.7.3 Other installers
- to the list of commands for the "distribution" target in
- packaging/u3/win32/makefile.nmake.
+The U3 and PortableApps installers build their manifests, including
+plugins, from 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 first thing is that you'll have to run autogen.sh and configure
-once more to setup your build environment.
+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 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. Use "make -C plugins" to compile just
+your plugins.
-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 Wireshark will not use the plugins unless the plugins
+are installed in one of the places it expects them to find.
One way of dealing with this problem is to set an environment variable
when running Wireshark: WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1.
wireshark, say in $HOME/build/root and build wireshark to install
there
-./configure --prefix=${HOME}/build/root;make install
+./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
+by going to the plugins/foo directory and running
make install
encapsulation in plugin.c. When using the new style build scripts,
stips the parts outlined below:
- o Remove the following include statments:
+ 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;
+ WS_DLL_PUBLIC_NOEXTERN gchar version[] = VERSION;
#endif
o Move relevant code from the blocks and delete these functions:
git.samba.org / metze / wireshark / wip.git / blobdiff