-$Id: README.plugins,v 1.9 2003/11/06 09:52:28 guy Exp $
+1. Plugins
-Plugins
+Writing a "plugin" dissector is not very different from writing a standard
+one. In fact all of the functions described in README.dissector 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 the README.developer can be
-used in the plugins exactly as the 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 "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 "foo" 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/foo directory which should
+contain at least 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).
+AUTHORS
+COPYING
+ChangeLog
+CMakeLists.txt
+Makefile.am
+Makefile.common
+Makefile.nmake
+moduleinfo.h
+moduleinfo.nmake
+plugin.rc.in
+And of course the source and header files for your dissector.
-#include "moduleinfo.h"
+Examples of these files can be found in plugins/gryphon.
-This header is optional and is described in greater detail further on.
+2.1 AUTHORS, COPYING, and ChangeLog
-#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.
+The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
+files.
-"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".
+2.2 CMakeLists.txt
-#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.
+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 New exported constants in packet-xxx.c
+2.3 Makefile.am
-Plugins need to provide the following exported constants:
+For your plugins/foo/Makefile.am file, see the corresponding file in
+plugins/gryphon. Replace all occurrences of "gryphon" in those files
+with "foo".
-#ifndef __ETHEREAL_STATIC__
-G_MODULE_EXPORT const gchar version[] = VERSION;
-#endif
+2.4 Makefile.common
-version : a version number associated with the plugin.
+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
+include moduleinfo.h.
-the #ifndef is to allow for the building of a non-plugin version of
-the object for linking into a static ethereal binary.
+2.5 Makefile.nmake
-3 New exported functions in packet-xxx.c
+For your plugins/foo/Makefile.nmake file, see the corresponding file in
+plugins/gryphon. No modifications are needed here.
-The following two functions need to be exported by the plugin:
+2.6 moduleinfo.h
-#ifndef __ETHEREAL_STATIC__
-G_MODULE_EXPORT void plugin_init(plugin_address_table_t *pat)
-#endif
+Your plugins/foo/moduleinfo.h file is used to set the version information
+for the plugin.
-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.7 moduleinfo.nmake
-Here is a sample code for the function:
+Your plugins/foo/moduleinfo.nmake is used to set the version information
+for building the plugin. Its contents should match that in moduleinfo.h
- /* initialise the table of pointers needed in Win32 DLLs */
- plugin_address_table_init(pat);
+2.8 plugin.rc.in
- /* register the new protocol, protocol fields, and subtrees */
- if (proto_xxx == -1) { /* execute protocol initialization only once */
- proto_register_xxx();
- }
+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.
-#ifndef __ETHEREAL_STATIC__
-G_MODULE_EXPORT void plugin_reg_handoff(void)
-#endif
+3. Changes to existing Wireshark files
-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.
+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.
-Here is a sample code for the function:
+3.1 Custom extension
- proto_reg_handoff_xxx();
+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.
-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.
+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:
-4 Directory structure and other file changes
+File "..\..\plugins\foo\foo.dll"
-Plugins should be places in plugins/xxx/ which should contain minimally
-the following files:
+Then open packaging/nsis/Custom.nmake and add the relative path to your
+DLL to CUSTOM_PLUGINS:
-AUTHORS
-COPYING
-ChangeLog
-Makefile.am
-Makefile.nmake
-moduleinfo.h
-packet-xxx.c
+CUSTOM_PLUGINS= \
+ ../../plugins/foo/foo.dll
-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.
+3.2 Permanent addition
-3.4.1 plugins/xxx/Makefile.am
+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
-An example of the Makefile.am follows:
+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,
-INCLUDES = -I$(top_srcdir)
+ grep -rl gryphon .
-plugindir = @plugindir@
+could be used from a shell prompt.
-plugin_LTLIBRARIES = xxx.la
-xxx_la_SOURCES = packet-xxx.c moduleinfo.h
-xxx_la_LDFLAGS = -module -avoid-version
+3.2.1 Changes to plugins/Makefile.am
-# 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 =
+The plugins directory contains a Makefile.am. You need to add to SUBDIRS
+(in alphabetical order) the name of your plugin:
-CLEANFILES = \
- xxx
+SUBDIRS = $(_CUSTOM_SUBDIRS_) \
+ ...
+ ethercat \
+ foo \
+ gryphon \
+ irda \
-EXTRA_DIST = \
- Makefile.nmake
+3.2.2 Changes to plugins/Makefile.nmake
-4.2 plugins/xxx/Makefile.nmake
+In plugins/Makefile.nmake you need to add to PLUGINS_LIST (in alphabetical
+order) the name of your plugin:
-Makefile.nmake is used for building the plugin for for Windows.
+PLUGIN_LIST = \
+ ...
+ ethercat \
+ foo \
+ gryphon \
+ irda \
-include ..\..\config.nmake
+3.2.3 Changes to the top level Makefile.am
-############### no need to modify below this line #########
+Add your plugin (in alphabetical order) to plugin_ldadd:
-CFLAGS=/DHAVE_CONFIG_H /I../.. /I../../wiretap $(GLIB_CFLAGS) \
- /I$(PCAP_DIR)\include -D_U_="" $(LOCAL_CFLAGS)
+if HAVE_PLUGINS
-OBJECTS=packet-xxx.obj
+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 \
+ ...
-xxx.dll xxx.exp xxx.lib : $(OBJECTS) ..\plugin_api.obj
- link -dll /out:xxx.dll $(OBJECTS) ..\plugin_api.obj \
- $(GLIB_LIBS)
+3.2.4 Changes to the top level configure.ac
-clean:
- rm -f $(OBJECTS) xxx.dll xxx.exp xxx.lib $(PDB_FILE)
+You need to add your plugins Makefile (in alphbetical order) to the
+AC_OUTPUT rule in the configure.ac
+AC_OUTPUT(
+ ...
+ plugins/ethercat/Makefile
+ plugins/foo/Makefile
+ plugins/gryphon/Makefile
+ plugins/irda/Makefile
+ ...
+ ,)
-4.3 plugins/xxx/moduleinfo.h
-
-moduleinfo.h is used to set the version information for the plugin.
-An example follows:
+3.2.5 Changes to epan/Makefile.am
-/* Included *after* config.h, in order to re-define these macros */
+Add the relative path of all your plugin source files (in alphbetical
+order) to plugin_src:
-#ifdef PACKAGE
-#undef PACKAGE
-#endif
+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 \
+ ...
-/* Name of package */
-#define PACKAGE "xxx"
+3.2.6 Changes to CMakeLists.txt
+Add your plugin (in alphabetical order) to the PLUGIN_SRC_DIRS:
-#ifdef VERSION
-#undef VERSION
-#endif
+if(ENABLE_PLUGINS)
+ ...
+ set(PLUGIN_SRC_DIRS
+ ...
+ plugins/ethercat
+ plugins/foo
+ plugins/gryphon
+ plugins/irda
+ ...
-/* Version number of package */
-#define VERSION "0.0.8"
+3.2.7 Changes to the installers
-4.4 Changes to plugins/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.
-The plugins directory contains a Makefile.am.
-You need to change the SUBDIRS directive to reflect the addition of
-your plugin:
+3.2.7.1 Changes to packaging/nsis/Makefile.nmake
-SUBDIRS = gryphon mgcp xxx
+Add the relative path of your plugin DLL (in alphbetical order) to PLUGINS:
+PLUGINS= \
+ ...
+ ../../plugins/ethercat/ethercat.dll \
+ ../../plugins/foo/foo.dll \
+ ../../plugins/gryphon/gryphon.dll \
+ ../../plugins/irda/irda.dll \
-4.5 Changes to plugins/Makefile.nmake
+3.2.7.2 Changes to packaging/nsis/wireshark.nsi
-To the Makefile.nmake you need to add your plugin to the all: rule
+Add the relative path of your plugin DLL (in alphbetical order) to the
+list of "File" statements in the "Dissector Plugins" section:
-all: plugin_api.obj gryphon mgcp xxx
+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"
-then add a rule for your plugin:
+3.2.7.3 Other installers
-xxx::
- cd xxx
- $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake
- cd ..
+The U3 and PortableApps installers build their manifests, including
+plugins, from wireshark.nsi via the packaging/ws-manifest.pl script.
-and finally add to the clean rule support for cleaning up after your
-plugin:
+4. Development and plugins on Unix
-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 ..
+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.
-4.6 Changes to the top level Makefile.am
+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.
-Unfortunately there are quite some several places in the top level
-Makefile.am that need to be altered for adding a 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.
-Add your plugin to the plugin_src, plugin_static_ldadd, plugin_libs,
-and plugin_ldadd:
+One way of dealing with this problem is to set an environment variable
+when running Wireshark: WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1.
-plugin_src = \
- plugins/mgcp/packet-mgcp.c \
- plugins/gryphon/packet-gryphon.c \
- plugins/xxx/packet-xxx.c
+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
-plugin_static_ldadd = \
- plugins/mgcp/packet-mgcp-static.o \
- plugins/gryphon/packet-gryphon-static.o \
- plugins/xxx/packet-xxx-static.o
+./configure --prefix=${HOME}/build/root && make install
-plugin_libs = \
- plugins/gryphon/gryphon.la \
- plugins/mgcp/mgcp.la \
- plugins/xxx/xxx.la
+then subsequent rebuilds/installs of your plugin can be accomplished
+by going to the plugins/foo directory and running
-plugin_ldadd = \
- "-dlopen" self \
- "-dlopen" plugins/gryphon/gryphon.la \
- "-dlopen" plugins/mgcp/mgcp.la \
- "-dlopen" plugins/xxx/xxx.la
+make install
-4.7 Changes to top level configure.in
+5. Update "old style" plugins
-You need to add your plugins Makefile to the AC_OUTPUT rule in the
-configure.in
+5.1 How to update an "old style" plugin (using plugin_register and
+ plugin_reg_handoff 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
- ,)
+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:
-5 Development and plugins
+ #include <gmodule.h>
+ #include "moduleinfo.h"
-Plugins make some aspects of development easier and some harder.
+ o Removed the definition:
-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.
+ #ifndef ENABLE_STATIC
+ WS_DLL_PUBLIC_DEF gchar version[] = VERSION;
+ #endif
-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 Move relevant code from the blocks and delete these functions:
-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
+ #ifndef ENABLE_STATIC
+ plugin_reg_handoff()
+ ....
+ #endif
-./configure --prefix=${HOME}/build/root;make install
+ #ifndef ENABLE_STATIC
+ plugin_register()
+ ....
+ #endif
-then subsequent rebuilds/installs of your plugin can be accomplished
-by going to the plugins/xxx directory and running
+This will leave a clean dissector source file without plugin specifics.
-make install
+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:
+
+ o Remove following include statements from all plugin sources:
+
+ #include "plugins/plugin_api.h"
+ #include "plugins/plugin_api_defs.h"
+
+ o Remove the init function.
+
+ 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.
+----------------
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 / metze / wireshark / wip.git / blobdiff