-$Id: README.plugins,v 1.11 2004/04/14 22:13:21 obiot Exp $
+$Id$
-Plugins
+1. Plugins
-Writing a "plugin" dissector is not very different from writing a standard one.
-In fact all of the functions described in the 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 Ethereal runs can support
+(Note, however, that not all OSes on which Wireshark runs can support
plugins.)
-Once you have written a packet-xxx.c to create your plugin
-( where xxx is the name of the protocol you are dissecting ) there are
-only a few changes you need to make to "pluginize" your dissector.
+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.
-1 New headers needed in packet-xxx.c
+2. The directory for the plugin, and its files
-#include "plugins/plugin_api.h"
+The plugin should be placed in a new plugins/xxx directory which should
+contain minimally the following files:
-Some OSes (Win32) have DLLs that cannot reference symbols in the parent
-executable. So, the executable needs to provide a table of pointers for the DLL
-plugin to use. The plugin_api.h header provides definitions for this (or empty
-definitions on OSes which don't need this).
-
-#include "moduleinfo.h"
-
-This header is optional and is described in greater detail further on.
-
-#include <gmodule.h>
-This header is required to define G_MODULE_EXPORT, which must be used
-when defining constants and functions exported by the plugin.
-
-"gmodule.h" includes "glib.h", so you don't need to include "glib.h" if
-you include "gmodule.h"; however, "glib.h" is protected from multiple
-inclusion by #ifdefs, so it's safe to include it after including
-"gmodule.h".
-
-#include "plugins/plugin_api_defs.h"
-Only include this in one source file if you have more than one. It defines,
-(as opposed to declares,) the function pointer variables that the plugin uses
-to reference the address table.
-
-2 New exported constants in packet-xxx.c
+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
-Plugins need to provide the following exported constants:
+Examples of these files can be found in plugins/gryphon.
-#ifndef ENABLE_STATIC
-G_MODULE_EXPORT const gchar version[] = VERSION;
-#endif
+2.1 AUTHORS, COPYING, and ChangeLog
-version : a version number associated with the plugin.
+The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
+files.
-the #ifndef is to allow for the building of a non-plugin version of
-the object for linking into a static ethereal binary.
+2.2 CMakeLists.txt
-3 New exported functions in packet-xxx.c
+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.
-The following two functions need to be exported by the plugin:
+2.3 Makefile.am
-#ifndef ENABLE_STATIC
-G_MODULE_EXPORT void
-plugin_init(plugin_address_table_t *pat)
-#endif
+For your plugins/xxx/Makefile.am file, see the corresponding file in
+plugins/gryphon. Replace all occurrences of "gryphon" in those files
+with "xxx".
-This function is called by Ethereal when the plugin is initialized; it's
-similar to the "proto_register_XXX()" routine for a non-plugin
-dissector, except for the name and the call to
-"plugin_address_table_init()".
+2.4 Makefile.common
-Here is a sample code for the function:
+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.
- /* initialise the table of pointers needed in Win32 DLLs */
- plugin_address_table_init(pat);
+2.5 Makefile.nmake
- /* register the new protocol, protocol fields, and subtrees */
- if (proto_xxx == -1) { /* execute protocol initialization only once */
- proto_register_xxx();
- }
+For your plugins/xxx/Makefile.nmake file, see the corresponding file in
+plugins/gryphon. No modifications are needed here.
-#ifndef ENABLE_STATIC
-G_MODULE_EXPORT void
-plugin_reg_handoff(void)
-#endif
+2.6 moduleinfo.h
-This function is called by Ethereal after all dissectors, including all
-plugins, are initialized; it's similar to the "proto_reg_handoff_XXX()"
-routine for a non-plugin dissector, except for the name.
+Your plugins/xxx/moduleinfo.h file is used to set the version information
+for the plugin.
-Here is a sample code for the function:
+2.7 moduleinfo.nmake
- proto_reg_handoff_xxx();
+Your plugins/xxx/moduleinfo.nmake is used to set the version information
+for building the plugin. Its contents should match that in moduleinfo.h
-As you can see the plugin_reg_handoff and plugin_init are just
-wrappers for the proto_reg_handoff_xxx and proto_register_xxx functions.
+2.8 plugin.rc.in
-4 Directory structure and other file changes
+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.
-Plugins should be places in plugins/xxx/ which should contain minimally
-the following files:
+3. Changes to existing Wireshark files
-AUTHORS
-COPYING
-ChangeLog
-Makefile.am
-Makefile.nmake
-moduleinfo.h
-packet-xxx.c
+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
-The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
-files, see plugins/mgcp for examples. You will also need to change
-the plugins/Makefile.am toplevel Makefile.am, the plugins/Makefile.nmake
-toplevel Makefile.nmake, and toplevel configure.in 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,
-3.4.1 plugins/xxx/Makefile.am
+ grep -rl gryphon .
-An example of the Makefile.am follows:
+could be used from a shell prompt.
-INCLUDES = -I$(top_srcdir)
+3.1 Changes to plugins/Makefile.am
-plugindir = @plugindir@
+The plugins directory contains a Makefile.am. You need to change the
+SUBDIRS directive to reflect the addition of your plugin:
-plugin_LTLIBRARIES = xxx.la
-xxx_la_SOURCES = packet-xxx.c moduleinfo.h
-xxx_la_LDFLAGS = -module -avoid-version
-xxx_la_LIBADD = -L../../epan -lethereal @GLIB_LIBS@
+SUBDIRS = $(_CUSTOM_SUBDIRS_) \
+ ...
+ gryphon \
+ irda \
+ xxx \
-# Libs must be cleared, or else libtool won't create a shared module.
-# If your module needs to be linked against any particular libraries,
-# add them here.
-LIBS =
+3.2 Changes to plugins/Makefile.nmake
-CLEANFILES = \
- xxx
+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).
-EXTRA_DIST = \
- Makefile.nmake
+3.3 Changes to the top level Makefile.am
+Add your plugin (in alphabetical order) to the plugin_ldadd:
-4.2 plugins/xxx/Makefile.nmake
+if HAVE_PLUGINS
-Makefile.nmake is used for building the plugin for for Windows.
+plugin_ldadd = \
+ ...
+ -dlopen plugins/gryphon/gryphon.la \
+ -dlopen plugins/irda/irda.la \
+ -dlopen plugins/xxx/xxx.la \
+ ...
-include ..\..\config.nmake
+3.4 Changes to the top level configure.in
-############### no need to modify below this line #########
+You need to add your plugins Makefile (in alphbetical order) to the AC_OUTPUT
+rule in the configure.in
-CFLAGS=/DHAVE_CONFIG_H /I../.. /I../../wiretap $(GLIB_CFLAGS) \
- /I$(PCAP_DIR)\include -D_U_="" $(LOCAL_CFLAGS)
+AC_OUTPUT(
+ ...
+ plugins/gryphon/Makefile
+ plugins/irda/Makefile
+ plugins/xxx/Makefile
+ ...
+ ,)
-OBJECTS=packet-xxx.obj
+3.5 Changes to epan/Makefile.am
-xxx.dll xxx.exp xxx.lib : $(OBJECTS) ..\plugin_api.obj
- link -dll /out:xxx.dll $(OBJECTS) ..\plugin_api.obj \
- $(GLIB_LIBS)
+Add the relative path of your plugin (in alphbetical order) to plugin_src:
-clean:
- rm -f $(OBJECTS) xxx.dll xxx.exp xxx.lib $(PDB_FILE)
+plugin_src = \
+ ...
+ ../plugins/gryphon/packet-gryphon.c \
+ ../plugins/irda/packet-irda.c \
+ ../plugins/xxx/packet-xxx.c \
+ ...
+3.6 Changes to CMakeLists.txt
-4.3 plugins/xxx/moduleinfo.h
-
-moduleinfo.h is used to set the version information for the plugin.
-An example follows:
+Add your plugin (in alphabetical order) to the PLUGIN_SRC_DIRS:
-/* Included *after* config.h, in order to re-define these macros */
+if(ENABLE_PLUGINS)
+ ...
+ set(PLUGIN_SRC_DIRS
+ ...
+ plugins/gryphon
+ plugins/irda
+ plugins/xxx
+ ...
-#ifdef PACKAGE
-#undef PACKAGE
-#endif
+3.7 Changes to the installers
-/* Name of package */
-#define PACKAGE "xxx"
+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:
-#ifdef VERSION
-#undef VERSION
-#endif
+ Add ../../plugins/xxx/xxx.dll to the list of plugins for the
+ PLUGINS variable in packaging/nsis/Makefile.nmake.
-/* Version number of package */
-#define VERSION "0.0.8"
+ Add
-4.4 Changes to plugins/Makefile.am
+ File "..\..\plugins\xxx\xxx.dll"
-The plugins directory contains a Makefile.am.
-You need to change the SUBDIRS directive to reflect the addition of
-your plugin:
+ to the list of "File" statements in the "Dissector Plugins"
+ section in packaging/nsis/wireshark.nsi.
-SUBDIRS = gryphon mgcp xxx
+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
-4.5 Changes to plugins/Makefile.nmake
+Plugins make some aspects of development easier and some harder.
-To the Makefile.nmake you need to add your plugin to the all: rule
+The first thing is that you'll have to run autogen.sh and configure
+once more to setup your build environment.
-all: plugin_api.obj gryphon mgcp xxx
+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.
-then add a rule for your plugin:
+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.
-xxx::
- cd xxx
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake
- cd ..
+One way of dealing with this problem is to set an environment variable
+when running Wireshark: WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1.
-and finally add to the clean rule support for cleaning up after your
-plugin:
+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
-clean:
- rm -f plugin_api.obj
- 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 ..
+./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
-4.6 Changes to the top level Makefile.am
+make install
-Unfortunately there are quite some several places in the top level
-Makefile.am that need to be altered for adding a plugin.
+5. Update "old style" plugins
-Add your plugin to the plugin_src, plugin_static_ldadd, plugin_libs,
-and plugin_ldadd:
+5.1 How to update an "old style" plugin (using plugin_register and
+ plugin_reg_handoff functions).
-plugin_src = \
- plugins/mgcp/packet-mgcp.c \
- plugins/gryphon/packet-gryphon.c \
- plugins/xxx/packet-xxx.c
+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:
-plugin_static_ldadd = \
- plugins/mgcp/packet-mgcp-static.o \
- plugins/gryphon/packet-gryphon-static.o \
- plugins/xxx/packet-xxx-static.o
+ o Remove the following include statements:
-plugin_libs = \
- plugins/gryphon/gryphon.la \
- plugins/mgcp/mgcp.la \
- plugins/xxx/xxx.la
+ #include <gmodule.h>
+ #include "moduleinfo.h"
-plugin_ldadd = \
- "-dlopen" self \
- "-dlopen" plugins/gryphon/gryphon.la \
- "-dlopen" plugins/mgcp/mgcp.la \
- "-dlopen" plugins/xxx/xxx.la
+ o Removed the definition:
-4.7 Changes to top level configure.in
+ #ifndef ENABLE_STATIC
+ G_MODULE_EXPORT gchar version[] = VERSION;
+ #endif
-You need to add your plugins Makefile to the AC_OUTPUT rule in the
-configure.in
+ o Move relevant code from the blocks and delete these functions:
-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
- ,)
+ #ifndef ENABLE_STATIC
+ plugin_reg_handoff()
+ ....
+ #endif
+ #ifndef ENABLE_STATIC
+ plugin_register()
+ ....
+ #endif
-5 Development and plugins
+This will leave a clean dissector source file without plugin specifics.
-Plugins make some aspects of development easier and some harder.
+5.2 How to update an "old style" plugin (using plugin_init function)
-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 plugin registering has changed between 0.10.9 and 0.10.10; everyone
+is encouraged to update their plugins as outlined below:
-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.
+ o Remove following include statements from all plugin sources:
-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
+ #include "plugins/plugin_api.h"
+ #include "plugins/plugin_api_defs.h"
-./configure --prefix=${HOME}/build/root;make install
+ o Remove the init function.
-then subsequent rebuilds/installs of your plugin can be accomplished
-by going to the plugins/xxx directory and running
+ o Add a new Makefile.common file with the lists of source files and
+ headers.
-make install
+ o Change the Makefile.am and Makefile.nmake files to match those of
+ the DOCSIS plugin.
+----------------
Ed Warnicke <hagbard@physics.rutgers.edu>
+Guy Harris <guy@alum.mit.edu>
Derived and expanded from the plugin section of README.developers
which was originally written by
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