Implement and document the Custom plugin system. Create relevant example files and add them to the distribution. Rewrite README.plugins to describe how to use this system.
svn path=/trunk/; revision=45142
This commit is contained in:
Jaap Keuter
parent
be0a9dcfa2
commit
d249038a65
@ -2,23 +2,22 @@ $Id$
|
||||
|
||||
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 they 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
|
||||
@ -30,7 +29,7 @@ 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/gryphon.
|
||||
|
||||
@ -41,51 +40,76 @@ files.
|
||||
|
||||
2.2 CMakeLists.txt
|
||||
|
||||
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.
|
||||
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.am
|
||||
|
||||
For your plugins/xxx/Makefile.am file, see the corresponding file in
|
||||
plugins/gryphon. Replace all occurrences of "gryphon" in those files
|
||||
with "xxx".
|
||||
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/xxx/Makefile.common should only list the main source file(s),
|
||||
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, and this variable added to the
|
||||
xxx_la_SOURCES variable in Makefile.am.
|
||||
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.5 Makefile.nmake
|
||||
|
||||
For your plugins/xxx/Makefile.nmake file, see the corresponding file in
|
||||
plugins/gryphon. 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.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.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.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 following files:
|
||||
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 Custom extension
|
||||
|
||||
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.
|
||||
|
||||
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"
|
||||
|
||||
Then open packaging/nsis/Custom.nmake and add the relative path to your
|
||||
DLL to CUSTOM_PLUGINS:
|
||||
|
||||
CUSTOM_PLUGINS= \
|
||||
../../plugins/foo/foo.dll
|
||||
|
||||
3.2 Permanent addition
|
||||
|
||||
In order to be able to permanently add a plugin take the following steps.
|
||||
You will need to change the following files:
|
||||
configure.in
|
||||
CMakeLists.txt
|
||||
epan/Makefile.am
|
||||
@ -97,67 +121,81 @@ You will also need to change the following files:
|
||||
|
||||
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,
|
||||
date with the current directory structure. For example,
|
||||
|
||||
grep -rl gryphon .
|
||||
|
||||
could be used from a shell prompt.
|
||||
|
||||
3.1 Changes to plugins/Makefile.am
|
||||
3.2.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:
|
||||
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 \
|
||||
xxx \
|
||||
|
||||
3.2 Changes to plugins/Makefile.nmake
|
||||
|
||||
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).
|
||||
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:
|
||||
|
||||
Add your plugin (in alphabetical order) to the plugin_ldadd:
|
||||
PLUGIN_LIST = \
|
||||
...
|
||||
ethercat \
|
||||
foo \
|
||||
gryphon \
|
||||
irda \
|
||||
|
||||
3.2.3 Changes to the top level Makefile.am
|
||||
|
||||
Add your plugin (in alphabetical order) to plugin_ldadd:
|
||||
|
||||
if HAVE_PLUGINS
|
||||
|
||||
plugin_ldadd = \
|
||||
plugin_ldadd = $(_CUSTOM_plugin_ldadd_) \
|
||||
...
|
||||
-dlopen plugins/gryphon/gryphon.la \
|
||||
-dlopen plugins/irda/irda.la \
|
||||
-dlopen plugins/xxx/xxx.la \
|
||||
-dlopen plugins/ethercat/ethercat.la \
|
||||
-dlopen plugins/foo/foo.la \
|
||||
-dlopen plugins/gryphon/gryphon.la \
|
||||
-dlopen plugins/irda/irda.la \
|
||||
...
|
||||
|
||||
3.4 Changes to the top level configure.in
|
||||
3.2.4 Changes to the top level configure.in
|
||||
|
||||
You need to add your plugins Makefile (in alphbetical order) 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(
|
||||
...
|
||||
plugins/ethercat/Makefile
|
||||
plugins/foo/Makefile
|
||||
plugins/gryphon/Makefile
|
||||
plugins/irda/Makefile
|
||||
plugins/xxx/Makefile
|
||||
...
|
||||
,)
|
||||
|
||||
3.5 Changes to epan/Makefile.am
|
||||
3.2.5 Changes to epan/Makefile.am
|
||||
|
||||
Add the relative path of your plugin (in alphbetical order) to plugin_src:
|
||||
Add the relative path of all your plugin source files (in alphbetical
|
||||
order) to plugin_src:
|
||||
|
||||
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 \
|
||||
../plugins/xxx/packet-xxx.c \
|
||||
...
|
||||
|
||||
3.6 Changes to CMakeLists.txt
|
||||
3.2.6 Changes to CMakeLists.txt
|
||||
|
||||
Add your plugin (in alphabetical order) to the PLUGIN_SRC_DIRS:
|
||||
|
||||
@ -165,44 +203,57 @@ if(ENABLE_PLUGINS)
|
||||
...
|
||||
set(PLUGIN_SRC_DIRS
|
||||
...
|
||||
plugins/ethercat
|
||||
plugins/foo
|
||||
plugins/gryphon
|
||||
plugins/irda
|
||||
plugins/xxx
|
||||
...
|
||||
|
||||
3.7 Changes to the installers
|
||||
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.
|
||||
|
||||
For the NSIS installer:
|
||||
3.2.7.1 Changes to packaging/nsis/Makefile.nmake
|
||||
|
||||
Add ../../plugins/xxx/xxx.dll to the list of plugins for the
|
||||
PLUGINS variable in packaging/nsis/Makefile.nmake.
|
||||
Add the relative path of your plugin DLL (in alphbetical order) to PLUGINS:
|
||||
|
||||
Add
|
||||
PLUGINS= \
|
||||
...
|
||||
../../plugins/ethercat/ethercat.dll \
|
||||
../../plugins/foo/foo.dll \
|
||||
../../plugins/gryphon/gryphon.dll \
|
||||
../../plugins/irda/irda.dll \
|
||||
|
||||
File "..\..\plugins\xxx\xxx.dll"
|
||||
3.2.7.2 Changes to packaging/nsis/wireshark.nsi
|
||||
|
||||
to the list of "File" statements in the "Dissector Plugins"
|
||||
section in packaging/nsis/wireshark.nsi.
|
||||
Add the relative path of your plugin DLL (in alphbetical order) to the
|
||||
list of "File" statements in the "Dissector Plugins" section:
|
||||
|
||||
The U3 and PortableApps installers build their manifests, including plugins,
|
||||
from packaging/nsis/wireshark.nsi via the packaging/ws-manifest.pl script.
|
||||
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"
|
||||
|
||||
3.2.7.3 Other installers
|
||||
|
||||
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.
|
||||
@ -211,10 +262,10 @@ 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
|
||||
./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
|
||||
|
||||
|
||||
5
plugins/Custom.m4.example
Normal file
5
plugins/Custom.m4.example
Normal file
@ -0,0 +1,5 @@
|
||||
#
|
||||
# $Id$
|
||||
#
|
||||
|
||||
m4_define([_CUSTOM_AC_OUTPUT_], [plugins/foo/Makefile])
|
||||
13
plugins/Custom.make.example
Normal file
13
plugins/Custom.make.example
Normal file
@ -0,0 +1,13 @@
|
||||
#
|
||||
# $Id$
|
||||
#
|
||||
|
||||
_CUSTOM_SUBDIRS_ = \
|
||||
foo
|
||||
|
||||
_CUSTOM_EXTRA_DIST_ = \
|
||||
Custom.m4 \
|
||||
Custom.make
|
||||
|
||||
_CUSTOM_plugin_ldadd_ = \
|
||||
-dlopen plugins/foo/foo.la
|
||||
@ -4,22 +4,6 @@
|
||||
|
||||
include ..\config.nmake
|
||||
|
||||
#
|
||||
# Custom plugin build template.
|
||||
#
|
||||
# If you need to develop a custom plugin (a plugin not yet released to the
|
||||
# public) this file is for you.
|
||||
#
|
||||
# To generate a custom plugin:
|
||||
#
|
||||
# 1. Create the new plugin directory and implement the plugin (at least to be
|
||||
# ready for a first build try). The easiest way to do this is to copy an
|
||||
# existing plugin and modify the contents.
|
||||
# 2. Rename this file to Custom.nmake
|
||||
# 3. Replace every appearance of foo in this file with your plugin dir name
|
||||
# 4. Build Wireshark as usual
|
||||
#
|
||||
|
||||
all: foo
|
||||
|
||||
foo::
|
||||
|
||||
@ -42,8 +42,11 @@ plugindir = @plugindir@
|
||||
|
||||
EXTRA_DIST = \
|
||||
$(_CUSTOM_EXTRA_DIST_) \
|
||||
plugins.vcproj \
|
||||
Makefile.nmake
|
||||
plugins.vcproj \
|
||||
Makefile.nmake \
|
||||
Custom.make.example \
|
||||
Custom.m4.example \
|
||||
Custom.nmake.example
|
||||
|
||||
MAINTAINERCLEANFILES = \
|
||||
Makefile.in
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user