2004-07-18 00:24:25 +00:00
|
|
|
$Id$
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
1. Plugins
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
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.
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2003-11-06 09:52:28 +00:00
|
|
|
(Note, however, that not all OSes on which Ethereal runs can support
|
|
|
|
plugins.)
|
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
If you've chosen "xxx" 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.
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
2. The directory for the plugin, and its files
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
The plugin should be placed in a new plugins/xxx directory which should
|
|
|
|
contain minimally the following files:
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
AUTHORS
|
|
|
|
COPYING
|
|
|
|
ChangeLog
|
|
|
|
Makefile.am
|
2006-04-20 02:39:04 +00:00
|
|
|
Makefile.common
|
2001-07-10 01:22:58 +00:00
|
|
|
Makefile.nmake
|
|
|
|
moduleinfo.h
|
2006-04-20 02:39:04 +00:00
|
|
|
The source files and header files for your dissector
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
2.1 AUTHORS, COPYING, and ChangeLog
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
|
|
|
|
files; see plugins/docsis for examples.
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
2.2 Makefile.am and Makefile.nmake
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
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".
|
2005-03-05 06:28:10 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
2.3 Makefile.common
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
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.)
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
2.4 moduleinfo.h
|
2005-03-05 06:28:10 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
Your plugins/xxx/moduleinfo.h file is used to set the version
|
|
|
|
information for the plugin. An example follows:
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
/* Included *after* config.h, in order to re-define these macros */
|
|
|
|
|
|
|
|
#ifdef PACKAGE
|
|
|
|
#undef PACKAGE
|
|
|
|
#endif
|
|
|
|
|
|
|
|
/* Name of package */
|
|
|
|
#define PACKAGE "xxx"
|
|
|
|
|
|
|
|
#ifdef VERSION
|
|
|
|
#undef VERSION
|
|
|
|
#endif
|
|
|
|
|
|
|
|
/* Version number of package */
|
|
|
|
#define VERSION "0.0.8"
|
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
3. Changes to existing Ethereal files
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
3.1 Changes to plugins/Makefile.am
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
The plugins directory contains a Makefile.am.
|
|
|
|
You need to change the SUBDIRS directive to reflect the addition of
|
|
|
|
your plugin:
|
|
|
|
|
2005-07-25 18:27:35 +00:00
|
|
|
SUBDIRS = \
|
|
|
|
gryphon \
|
|
|
|
mgcp \
|
|
|
|
xxx
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
3.2 Changes to plugins/Makefile.nmake
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
To the Makefile.nmake you need to add your plugin to the all: rule
|
|
|
|
|
2005-07-25 18:27:35 +00:00
|
|
|
all: \
|
|
|
|
gryphon \
|
|
|
|
mgcp \
|
|
|
|
xxx
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
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 ..
|
|
|
|
|
|
|
|
|
2004-07-03 21:50:05 +00:00
|
|
|
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 ..
|
|
|
|
|
|
|
|
|
2005-03-05 06:28:10 +00:00
|
|
|
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 ..
|
|
|
|
|
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
3.3 Changes to the top level Makefile.am
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
Unfortunately there are quite some several places in the top level
|
|
|
|
Makefile.am that need to be altered for adding a plugin.
|
|
|
|
|
2004-07-03 21:50:05 +00:00
|
|
|
Add your plugin to the plugin_libs and plugin_ldadd (two times):
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2001-07-20 02:40:42 +00:00
|
|
|
plugin_libs = \
|
|
|
|
plugins/gryphon/gryphon.la \
|
|
|
|
plugins/mgcp/mgcp.la \
|
2004-07-03 21:50:05 +00:00
|
|
|
plugins/xxx/xxx.la
|
|
|
|
|
|
|
|
if ENABLE_STATIC
|
|
|
|
plugin_ldadd = \
|
|
|
|
plugins/gryphon/gryphon.o \
|
|
|
|
plugins/mgcp/mgcp.o \
|
|
|
|
plugins/xxx/xxx.o
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2004-07-03 21:50:05 +00:00
|
|
|
else # ENABLE_STATIC
|
2001-07-20 02:40:42 +00:00
|
|
|
plugin_ldadd = \
|
|
|
|
"-dlopen" self \
|
|
|
|
"-dlopen" plugins/gryphon/gryphon.la \
|
|
|
|
"-dlopen" plugins/mgcp/mgcp.la \
|
|
|
|
"-dlopen" plugins/xxx/xxx.la
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
3.4 Changes to top level configure.in
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
You need to add your plugins Makefile 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/xxx/Makefile
|
|
|
|
tools/Makefile
|
|
|
|
tools/lemon/Makefile
|
|
|
|
,)
|
|
|
|
|
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
4. Development and plugins
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2006-05-22 09:05:24 +00:00
|
|
|
The bad news is that wireshark will not use the plugin unless the
|
2001-07-10 01:22:58 +00:00
|
|
|
plugin is installed in one of the places it expects to look.
|
|
|
|
|
|
|
|
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
|
|
|
|
there
|
|
|
|
|
|
|
|
./configure --prefix=${HOME}/build/root;make install
|
|
|
|
|
|
|
|
then subsequent rebuilds/installs of your plugin can be accomplished
|
2003-11-06 09:52:28 +00:00
|
|
|
by going to the plugins/xxx directory and running
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
make install
|
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
5. How to update an "old style" plugin (using plugin_init function)
|
2005-03-08 19:03:09 +00:00
|
|
|
|
2005-03-08 19:31:01 +00:00
|
|
|
The plugin registering has changed between 0.10.9 and 0.10.10; everyone
|
|
|
|
is encouraged to update their plugins as outlined below:
|
2005-03-08 19:03:09 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
o Remove following include statements from all plugin sources:
|
2005-03-08 19:03:09 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
#include "plugins/plugin_api.h"
|
|
|
|
#include "plugins/plugin_api_defs.h"
|
2005-03-08 19:03:09 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
o Remove the init function.
|
2005-03-08 19:03:09 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
o Add a new Makefile.common file with the lists of source files and
|
|
|
|
headers.
|
|
|
|
|
|
|
|
o Change the Makefile.am and Makefile.nmake files to match those of
|
|
|
|
the DOCSIS plugin.
|
2005-03-08 19:03:09 +00:00
|
|
|
|
|
|
|
----------------
|
|
|
|
|
2001-07-10 01:22:58 +00:00
|
|
|
Ed Warnicke <hagbard@physics.rutgers.edu>
|
2006-04-20 02:39:04 +00:00
|
|
|
Guy Harris <guy@alum.mit.edu>
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
Derived and expanded from the plugin section of README.developers
|
|
|
|
which was originally written by
|
|
|
|
|
|
|
|
James Coe <jammer@cin.net>
|
2001-11-13 23:55:44 +00:00
|
|
|
Gilbert Ramirez <gram@alumni.rice.edu>
|
2001-07-10 01:22:58 +00:00
|
|
|
Jeff Foster <jfoste@woodward.com>
|
|
|
|
Olivier Abad <oabad@cybercable.fr>
|
2003-01-26 19:35:31 +00:00
|
|
|
Laurent Deniel <laurent.deniel@free.fr>
|