Add toy plugin to doc/ as an out-of-tree build example

Change-Id: I9b7abb27d30dbe83996a01b7f722693a974948c5
Reviewed-on: https://code.wireshark.org/review/23665
Reviewed-by: João Valverde <j@v6e.pt>

6 files changed, 151 insertions, 2 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 89ae792b5c..a54ccc9477 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -342,6 +342,10 @@ EXTRA_DIST =				\
 	mergecap.pod			\
 	packet-PROTOABBREV.c		\
 	perlnoutf.pl			\
+	plugins.example/configure.ac	\
+	plugins.example/hello.c		\
+	plugins.example/Makefile.am	\
+	plugins.example/README		\
 	randpkt.pod			\
 	randpkt.txt			\
 	randpktdump.pod			\
diff --git a/doc/plugins.example/Makefile.am b/doc/plugins.example/Makefile.am
new file mode 100644
index 0000000000..1b9b5b0d27
--- /dev/null
+++ b/doc/plugins.example/Makefile.am
@@ -0,0 +1,40 @@
+# Makefile.am
+#
+# Wireshark - Network traffic analyzer
+# By Gerald Combs <gerald@wireshark.org>
+# Copyright 1998 Gerald Combs
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+
+WARNFLAGS = -Wall -Wextra
+
+plugindir := $(shell PKG_CONFIG_PATH=$(PKG_CONFIG_PATH) $(PKG_CONFIG) --define-variable=libdir=$(libdir) --variable plugindir wireshark)
+
+plugin_LTLIBRARIES = hello.la
+
+hello_la_SOURCES = hello.c
+
+hello_la_CFLAGS = $(WIRESHARK_CFLAGS) -fvisibility=hidden $(WARNFLAGS)
+
+hello_la_LDFLAGS = -module -avoid-version -shared
+
+hello_la_LIBADD = $(WIRESHARK_LIBS)
+
+homedir = $${HOME}/.local/lib/wireshark/plugins/$(notdir $(plugindir))
+
+install-home:
+	$(MKDIR_P) $(homedir) || exit 1; \
+	$(INSTALL) $(builddir)/.libs/hello.so $(homedir)
diff --git a/doc/plugins.example/README b/doc/plugins.example/README
new file mode 100644
index 0000000000..04bc5885eb
--- /dev/null
+++ b/doc/plugins.example/README
@@ -0,0 +1,13 @@
+
+This is an example of how to build a Wireshark plugin out-of-tree.
+
+Tested on Linux using GCC 7. Note this builds against Wireshark's *installed*
+version. You should of course adapt to your own needs.
+
+To build/install the plugin:
+
+$ autoreconf -v -i
+$ PREFIX=/usr/local
+$ ./configure --prefix="$PREFIX" PKG_CONFIG_PATH="$PREFIX/lib/pkgconfig"
+$ make
+$ sudo make install # or single-user: make install-home
diff --git a/doc/plugins.example/configure.ac b/doc/plugins.example/configure.ac
new file mode 100644
index 0000000000..07e9845d10
--- /dev/null
+++ b/doc/plugins.example/configure.ac
@@ -0,0 +1,29 @@
+dnl Process this file with autoconf to produce a configure script.
+dnl
+dnl This file is free software; as a special exception the author gives
+dnl unlimited permission to copy and/or distribute it, with or without
+dnl modifications, as long as this notice is preserved.
+dnl
+dnl This program is distributed in the hope that it will be useful, but
+dnl WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
+dnl implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+AC_INIT([Wireshark Hello Plugin], [0.0.1])
+
+AM_INIT_AUTOMAKE([foreign])
+
+AC_PREREQ([2.62])
+
+LT_PREREQ([2.2.2])
+LT_INIT([disable-static dlopen])
+
+AC_CONFIG_SRCDIR([hello.c])
+
+dnl Requires Wireshark 2.5.0 or greater.
+PKG_CHECK_MODULES([WIRESHARK], [wireshark >= 2.5])
+
+AC_CONFIG_HEADER([config.h])
+
+AC_CONFIG_FILES([Makefile])
+
+AC_OUTPUT
diff --git a/doc/plugins.example/hello.c b/doc/plugins.example/hello.c
new file mode 100644
index 0000000000..af78239e3a
--- /dev/null
+++ b/doc/plugins.example/hello.c
@@ -0,0 +1,62 @@
+/* hello.c
+ *
+ * Wireshark - Network traffic analyzer
+ * By Gerald Combs <gerald@wireshark.org>
+ * Copyright 1998 Gerald Combs
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <epan/packet.h>
+#include <ws_attributes.h>
+
+#ifndef VERSION
+#define VERSION "0.0.0"
+#endif
+
+#define DLL_PUBLIC __attribute__((__visibility__("default")))
+
+DLL_PUBLIC const gchar version[] = VERSION;
+
+DLL_PUBLIC void plugin_register(void);
+
+DLL_PUBLIC void plugin_reg_handoff(void);
+
+
+static int proto_hello = -1;
+static dissector_handle_t handle_hello;
+
+static int
+dissect_hello(tvbuff_t *tvb, packet_info *pinfo _U_, proto_tree *tree, void *data _U_)
+{
+    proto_tree_add_protocol_format(tree, proto_hello, tvb, 0, -1, "This is Hello version %s, a Wireshark postdissector plugin prototype", version);
+    return tvb_captured_length(tvb);
+}
+
+void plugin_register(void)
+{
+    proto_hello = proto_register_protocol("Wireshark Hello Plugin", "Hello", "hello");
+    handle_hello = create_dissector_handle(dissect_hello, proto_hello);
+    register_postdissector(handle_hello);
+}
+
+void plugin_reg_handoff(void)
+{
+    /* empty */
+}
diff --git a/docbook/release-notes.asciidoc b/docbook/release-notes.asciidoc
index 2b3e81346c..1060e28027 100644
--- a/docbook/release-notes.asciidoc
+++ b/docbook/release-notes.asciidoc
@@ -14,8 +14,9 @@ used for troubleshooting, analysis, development and education.
 == What's New
 
 * The installation step for Wireshark will now install headers required to
-  build plugins. A pkg-config file is provided to help with this. Note you
-  must still rebuild all plugins between minor releases (X.Y).
+  build plugins. A pkg-config file is provided to help with this
+  (see doc/plugins.example for details). Note you must still rebuild all
+  plugins between minor releases (X.Y).
 
 //=== Bug Fixes