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

1 files changed, 122 insertions, 71 deletions

diff --git a/doc/README.plugins b/doc/README.plugins
index 19ff49e12c..bacc6a67ea 100644
--- a/doc/README.plugins
+++ b/doc/README.plugins
@@ -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
+
+In plugins/Makefile.nmake you need to add to PLUGINS_LIST (in alphabetical
+order) the name of your plugin:
+
+PLUGIN_LIST = \
+	...
+	ethercat    \
+	foo         \
+	gryphon     \
+	irda        \
 
-3.3 Changes to the top level Makefile.am
+3.2.3 Changes to the top level Makefile.am
 
-Add your plugin (in alphabetical order) to the plugin_ldadd:
+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 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 \
 
-	Add ../../plugins/xxx/xxx.dll to the list of plugins for the
-	PLUGINS variable in packaging/nsis/Makefile.nmake.
+3.2.7.2  Changes to packaging/nsis/wireshark.nsi
 
-	Add
+Add the relative path of your plugin DLL (in alphbetical order) to the 
+list of "File" statements in the "Dissector Plugins" section:
 
-		File "..\..\plugins\xxx\xxx.dll"
+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"
 
-	to the list of "File" statements in the "Dissector Plugins"
-	section in packaging/nsis/wireshark.nsi.
+3.2.7.3  Other installers
 
-The U3 and PortableApps installers build their manifests, including plugins,
-from packaging/nsis/wireshark.nsi via the packaging/ws-manifest.pl script.
+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