Moved documentation for plugins to README.plugins and expanded

it.  Removed most of the Plugins section from README.developers

svn path=/trunk/; revision=3675

2 files changed, 360 insertions, 80 deletions

diff --git a/doc/README.developer b/doc/README.developer
index ef40451385..584d07b264 100644
--- a/doc/README.developer
+++ b/doc/README.developer
@@ -1,4 +1,4 @@
-$Id: README.developer,v 1.28 2001/04/20 22:00:27 guy Exp $
+$Id: README.developer,v 1.29 2001/07/10 01:22:58 hagbard Exp $
 
 This file is a HOWTO for Ethereal developers. It describes how to start coding
 a Ethereal protocol dissector and the use some of the important functions and
@@ -62,7 +62,7 @@ code inside
 
 is needed only if you are using the "snprintf()" function.
 
-The "$Id: README.developer,v 1.28 2001/04/20 22:00:27 guy Exp $"
+The "$Id: README.developer,v 1.29 2001/07/10 01:22:58 hagbard Exp $"
 in the comment will be updated by CVS when the file is
 checked in; it will allow the RCS "ident" command to report which
 version of the file is currently checked out.
@@ -72,7 +72,7 @@ version of the file is currently checked out.
  * Routines for PROTONAME dissection
  * Copyright 2000, YOUR_NAME <YOUR_EMAIL_ADDRESS>
  *
- * $Id: README.developer,v 1.28 2001/04/20 22:00:27 guy Exp $
+ * $Id: README.developer,v 1.29 2001/07/10 01:22:58 hagbard Exp $
  *
  * Ethereal - Network traffic analyzer
  * By Gerald Combs <gerald@ethereal.com>
@@ -1661,83 +1661,8 @@ An example from packet-bxxp.c -
 
 3. Plugins
 
-Writing a "plugin" dissector is not very different from writing a standard one.
-All the functions described in the first part of this file can be used in
-plugins exactly as they are used in standard dissectors.
-
-However, there are a few things you need to do (you can look at the gryphon
-plugin for an example) :
-
-3.1 Needed headers
-
-#include "plugins/plugin_api.h"
-
-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. It is used by the gryphon plugin to provide a VERSION
-macro (different from the ethereal VERSION).
-
-Ex :
-$ cat moduleinfo.h
-/* Included *after* config.h, in order to re-define these macros */
-#ifdef VERSION
-#undef VERSION
-#endif
-
-/* Plugin version number */
-#define VERSION "0.1.2"
-
-#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".
-
-3.2 Exported constants
-
-Plugins need to provide the following exported constants:
-
-G_MODULE_EXPORT const gchar version[] = VERSION;
-
-version       : a version number associated with the plugin.
-
-3.3 Exported functions
-
-The following two functions need to be exported by the plugin:
-
-G_MODULE_EXPORT void plugin_init(plugin_address_table_t *pat)
-
-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()".
-
-Here is a sample code for the function:
-
-	/* initialise the table of pointers needed in Win32 DLLs */
-	plugin_address_table_init(pat);
-
-	/* register the new protocol, protocol fields, and subtrees */
-	if (proto_xxx == -1) { /* execute protocol initialization only once */
-	  proto_xxx = proto_register_protocol("XXX Protocol", "XXX", "xxx");
-	  proto_register_field_array(proto_xxx, hf, array_length(hf));
-	  proto_register_subtree_array(ett, array_length(ett));
-	}
-
-G_MODULE_EXPORT void plugin_reg_handoff(void)
-
-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. 
+See the README.plugins for more information on how to "pluginize" 
+a dissector.
 
 4.0 Extending Wiretap.
 
@@ -1751,3 +1676,4 @@ Gilbert Ramirez <gram@xiexie.org>
 Jeff Foster <jfoste@woodward.com>
 Olivier Abad <oabad@cybercable.fr>
 Laurent Deniel <deniel@worldnet.fr>
+
diff --git a/doc/README.plugins b/doc/README.plugins
new file mode 100644
index 0000000000..ebb336a7b0
--- /dev/null
+++ b/doc/README.plugins
@@ -0,0 +1,354 @@
+$Id: README.plugins,v 1.1 2001/07/10 01:22:58 hagbard Exp $
+
+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.
+
+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.
+
+1 New headers needed in packet-xxx.c
+
+#include "plugins/plugin_api.h"
+
+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.
+
+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".
+
+2 New exported constants in packet-xxx.c
+
+Plugins need to provide the following exported constants:
+
+#ifndef __ETHEREAL_STATIC__
+G_MODULE_EXPORT const gchar version[] = VERSION;
+#endif 
+
+version       : a version number associated with the plugin.
+
+the #ifndef is to allow for the building of a non-plugin version of 
+the object for linking into a static ethereal binary.
+
+3 New exported functions in packet-xxx.c
+
+The following two functions need to be exported by the plugin:
+
+#ifndef __ETHEREAL_STATIC__
+G_MODULE_EXPORT void plugin_init(plugin_address_table_t *pat)
+#endif
+
+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()".
+
+Here is a sample code for the function:
+
+	/* initialise the table of pointers needed in Win32 DLLs */
+	plugin_address_table_init(pat);
+
+	/* register the new protocol, protocol fields, and subtrees */
+	if (proto_xxx == -1) { /* execute protocol initialization only once */
+		proto_register_xxx();
+	}
+
+#ifndef __ETHEREAL_STATIC__
+G_MODULE_EXPORT void plugin_reg_handoff(void)
+#endif
+
+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. 
+
+Here is a sample code for the function:
+
+  proto_reg_handoff_xxx();
+
+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.
+
+4 Directory structure and other file changes
+
+Plugins should be places in plugin/xxx/ which should contain minimally 
+the following files:
+
+AUTHORS
+COPYING
+ChangeLog
+Makefile.am
+Makefile.nmake
+moduleinfo.h
+packet-xxx.c
+
+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 plugin/Makefile.am toplevel Makefile.am and toplevel configure.in 
+files.
+
+3.4.1 plugin/xxx/Makefile.am
+
+An example of the Makefile.am follows:
+
+INCLUDES = -I$(top_srcdir) -I$(includedir)
+
+plugindir = @PLUGIN_DIR@
+
+plugin_LTLIBRARIES = xxx.la
+xxx_la_SOURCES = packet-xxx.c moduleinfo.h
+xxx_la_LDFLAGS = -module -avoid-version
+
+# 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 following allows a non-plugin version of the module to be built to 
+# be linked with a static ethereal binary.
+#
+noinst_PROGRAMS = packet-xxx-static.o
+
+packet-xxx-static.o:   packet-xxx.c moduleinfo.h
+        $(LTCOMPILE) -c -o packet-xxx-static.o -D__ETHEREAL_STATIC__ $(srcdir)/packet-xxx.c 
+
+CLEANFILES = \
+        xxx \
+EXTRA_DIST = \
+        Makefile.nmake
+
+
+4.2 plugin/xxx/Makefile.nmake
+
+Makefile.nmake is used for building the plugin for for Windows.
+
+include ..\..\config.nmake
+
+############### no need to modify below this line #########
+
+CFLAGS=/DHAVE_CONFIG_H /I../.. /I../../epan /I../../wiretap \
+	/I$(GLIB_DIR) /I$(GTK_DIR) /I$(GLIB_DIR)/gmodule \
+	/I$(GTK_DIR)\gdk /I$(GTK_DIR)\gdk\win32 \
+	/I$(PCAP_DIR)\include $(LOCAL_CFLAGS)
+
+OBJECTS=packet-xxx.obj 
+
+xxx.dll xxx.exp xxx.lib : packet-xxx.obj ..\plugin_api.obj
+	link -dll /out:xxx.dll packet-mgcp.obj ..\plugin_api.obj \
+	$(GLIB_DIR)\glib-$(GLIB_VERSION).lib
+
+clean:
+	rm -f $(OBJECTS) xxx.dll xxx.exp xxx.lib
+
+
+4.3 plugin/xxx/moduleinfo.h
+	
+moduleinfo.h is used to set the version information for the plugin.  
+An example follows:
+
+/* 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"
+
+4.4  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:
+
+SUBDIRS = gryphon mgcp xxx
+
+
+4.5 Changes to plugins/Makefile.nmake
+
+To the Makefile.nmake you need to add your plugin to the all: rule
+
+all: plugin_api.obj gryphon mgcp xxx
+
+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:
+	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 ..
+
+
+4.6 Changes to the top level Makefile.am
+
+Unfortunately there are quite some several places in the top level
+Makefile.am that need to be altered for adding a plugin.
+
+Add your plugin to the PLUGIN_SRC
+
+PLUGIN_SRC = \
+	plugins/mgcp/packet-mgcp.c	\
+	plugins/gryphon/packet-gryphon.c \
+	plugins/xxx/packet-xxx.c
+
+
+Add your plugin library to the ethereal_DEPENDENCIES
+
+ethereal_DEPENDENCIES = \
+	$(ethereal_optional_objects)	\
+	$(ethereal_additional_libs)	\
+	plugins/gryphon/gryphon.la \
+	plugins/mgcp/mgcp.la		\
+	plugins/xxx/xxx.la
+
+Add your plugin library to the ethereal_LDADD and ethereal_static_LDADD
+
+ethereal_LDADD = \
+	$(ethereal_optional_objects)	\
+	$(ethereal_additional_libs)	\
+	@SNMP_LIBS@ @SSL_LIBS@ 		\
+	"-dlopen" self	\
+	"-dlopen" plugins/gryphon/gryphon.la \
+	"-dlopen" plugins/mgcp/mgcp.la \
+	"-dlopen" plugins/xxx/xxx.la \
+	@PCAP_LIBS@ @GTK_LIBS@
+
+ethereal_static_LDADD = \
+	"-all-static" 			\
+	plugins/mgcp/packet-mgcp-static.o		\
+	plugins/gryphon/packet-gryphon-static.o		\
+	plugins/xxx/packet-xxx-static.o		\
+	$(ethereal_optional_objects)	\
+	$(ethereal_additional_libs)	\
+	@SNMP_LIBS@ @SSL_LIBS@		\
+	@PCAP_LIBS@ @GTK_LIBS@		
+
+Add your plugin library to the tethereal_DEPENDENCIES 
+
+tethereal_DEPENDENCIES = \
+	$(ethereal_optional_objects)	\
+	$(tethereal_additional_libs)	\
+	plugins/gryphon/gryphon.la	\
+	plugins/mgcp/mgcp.la		\
+	plugins/xxx/xxx.la
+
+And to tethereal_LDADD and tethereal_static_LDADD
+
+tethereal_LDADD = wiretap/libwiretap.a	\
+	$(ethereal_optional_objects)	\
+	$(tethereal_additional_libs)	\
+	@SNMP_LIBS@ @SSL_LIBS@		\
+	"-dlopen" self	\
+	"-dlopen" plugins/gryphon/gryphon.la \
+	"-dlopen" plugins/mgcp/mgcp.la \
+	"-dlopen" plugins/xxx/xxx.la \
+	@GLIB_LIBS@ -lm \
+	@PCAP_LIBS@ @SOCKET_LIBS@ @NSL_LIBS@
+
+tethereal_static_LDADD = \
+	"-all-static"		\
+	plugins/mgcp/packet-mgcp-static.o		\
+	plugins/gryphon/packet-gryphon-static.o		\
+	plugins/xxx/packet-xxx-static.o		\
+	wiretap/libwiretap.a	\
+	$(ethereal_optional_objects)	\
+	$(tethereal_additional_libs)	\
+	@SNMP_LIBS@ @SSL_LIBS@		\
+	@GLIB_LIBS@ -lm \
+	@PCAP_LIBS@ @SOCKET_LIBS@ @NSL_LIBS@
+
+
+
+4.7  Changes to top level configure.in
+
+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
+  ,)
+
+
+5	Development and plugins
+
+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.
+
+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.
+
+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 
+by going to the plugin/xxx directory and running 
+
+make install
+
+
+Ed Warnicke <hagbard@physics.rutgers.edu>
+
+Derived and expanded from the plugin section of README.developers
+which was originally written by
+
+James Coe <jammer@cin.net>
+Gilbert Ramirez <gram@xiexie.org>
+Jeff Foster <jfoste@woodward.com>
+Olivier Abad <oabad@cybercable.fr>
+Laurent Deniel <deniel@worldnet.fr>