3 files changed, 167 insertions, 0 deletions
diff --git a/doc/plugins.example/CMakeLists.txt b/doc/plugins.example/CMakeLists.txt
new file mode 100644
index 0000000..26e3ad2
--- /dev/null
+++ b/doc/plugins.example/CMakeLists.txt
@@ -0,0 +1,74 @@
+# CMakeLists.txt
+#
+# Wireshark - Network traffic analyzer
+# By Gerald Combs <gerald@wireshark.org>
+# Copyright 1998 Gerald Combs
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+#
+
+cmake_minimum_required(VERSION 3.12)
+cmake_policy(SET CMP0048 NEW)
+
+project(Hello VERSION 0.0.1 DESCRIPTION "Wireshark Hello Plugin" LANGUAGES C)
+
+find_package(Wireshark CONFIG REQUIRED)
+
+if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
+	set(CMAKE_INSTALL_PREFIX "${Wireshark_INSTALL_PREFIX}"
+		CACHE PATH "Installation prefix" FORCE
+	)
+endif()
+
+if(NOT Wireshark_PLUGINS_ENABLED)
+	message(WARNING "Wireshark was compiled without support for plugins")
+endif()
+
+# External plugins must define HAVE_SSIZE_T for the plugin toolchain.
+include(CheckTypeSize)
+check_type_size("ssize_t" SSIZE_T)
+
+set(CMAKE_C_VISIBILITY_PRESET hidden)
+if(CMAKE_COMPILER_IS_GNUCC)
+    set(CMAKE_C_FLAGS  "-Wall -Wextra ${CMAKE_C_FLAGS}")
+endif()
+
+add_compile_definitions(
+	VERSION=\"${PROJECT_VERSION}\"
+	$<$<BOOL:${HAVE_SSIZE_T}>:HAVE_SSIZE_T>
+)
+
+add_library(hello MODULE hello.c)
+set_target_properties(hello PROPERTIES PREFIX "" DEFINE_SYMBOL "")
+target_link_libraries(hello epan)
+
+# This is the normal installation target to CMAKE_INSTALL_PREFIX. It is relocatable
+# using DESTDIR or cmake --install. By default CMAKE_INSTALL_PREFIX should be configured
+# correctly for Wireshark's system installation prefix.
+install(TARGETS hello
+	LIBRARY DESTINATION "${Wireshark_PLUGIN_LIBDIR}/epan" NAMELINK_SKIP
+)
+
+# This custom target installs the plugin to the plugin dir in WiresharkConfig.cmake.
+# It does not use CMAKE_INSTALL_PREFIX.
+add_custom_target(copy_plugin
+	COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_FILE:hello> "${Wireshark_PLUGIN_INSTALL_DIR}/epan"
+	COMMENT "Installing plugin to: ${Wireshark_PLUGIN_INSTALL_DIR}/epan"
+)
+
+string(TOLOWER "${PROJECT_NAME}-${PROJECT_VERSION}" _pkgname)
+
+add_custom_target(package_prep
+	COMMAND ${CMAKE_COMMAND} -E make_directory  ${CMAKE_BINARY_DIR}/${_pkgname}
+	COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/README $<TARGET_FILE:hello> ${CMAKE_BINARY_DIR}/${_pkgname}
+)
+
+add_custom_target(package
+	COMMAND ${CMAKE_COMMAND} -E tar czf ${CMAKE_BINARY_DIR}/${_pkgname}.tar.gz --format=gnutar -- ${CMAKE_BINARY_DIR}/${_pkgname}
+)
+add_dependencies(package package_prep)
+
+add_custom_target(package_zip
+	COMMAND ${CMAKE_COMMAND} -E tar cf ${CMAKE_BINARY_DIR}/${_pkgname}.zip --format=zip -- ${CMAKE_BINARY_DIR}/${_pkgname}
+)
+add_dependencies(package_zip package_prep)
diff --git a/doc/plugins.example/README b/doc/plugins.example/README
new file mode 100644
index 0000000..27d6f48
--- /dev/null
+++ b/doc/plugins.example/README
@@ -0,0 +1,35 @@
+
+This is an example of how to build a Wireshark plugin out-of-tree. This
+is an alternative, more recent way to build Wireshark binary plugins,
+than the one in 'README.plugins', that describes in detail how to
+include a new plugin into the project source tree (here called in-tree
+build). Building a plugin out-of-tree doesn't require rebuilding the whole
+Wireshark source tree every time.
+
+You always need to rebuild plugins for each major.minor Wireshark version.
+Binary compatibility is never guaranteed between those releases and Wireshark
+will explicitly check for which version the plugin was built and refuse
+to load it otherwise.
+
+Note that the out-of-tree method builds the plugin using CMake's Config-file
+mechanism[1] for configuration. In other words the plugin build system uses
+the Wireshark headers that were installed on the system using "make install"
+or equivalent (as configured from WiresharkConfig.cmake). This is not the same
+as an in-tree build.
+
+You should of course adapt this trivial example to your own needs.
+
+To build/install the plugin:
+
+$ mkdir build && cd build
+$ cmake ..
+$ make
+$ sudo make install
+
+If your WiresharkConfig.cmake file is not in one of the standard cmake search
+paths you will have to tell cmake where to find it. You can do so using
+CMAKE_PREFIX_PATH, for example:
+
+$ cmake -DCMAKE_PREFIX_PATH="/opt/wireshark" ..
+
+[1]https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html#config-file-packages
diff --git a/doc/plugins.example/hello.c b/doc/plugins.example/hello.c
new file mode 100644
index 0000000..7a252c8
--- /dev/null
+++ b/doc/plugins.example/hello.c
@@ -0,0 +1,58 @@
+/* hello.c
+ *
+ * Wireshark - Network traffic analyzer
+ * By Gerald Combs <gerald@wireshark.org>
+ * Copyright 1998 Gerald Combs
+ *
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ */
+
+#define WS_BUILD_DLL
+#include <wireshark.h>
+#include <epan/packet.h>
+#include <epan/proto.h>
+
+#ifndef VERSION
+#define VERSION "0.0.0"
+#endif
+
+WS_DLL_PUBLIC_DEF const char plugin_version[] = VERSION;
+WS_DLL_PUBLIC_DEF const int plugin_want_major = WIRESHARK_VERSION_MAJOR;
+WS_DLL_PUBLIC_DEF const int plugin_want_minor = WIRESHARK_VERSION_MINOR;
+
+WS_DLL_PUBLIC void plugin_register(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", plugin_version);
+    return tvb_captured_length(tvb);
+}
+
+static void
+proto_register_hello(void)
+{
+    proto_hello = proto_register_protocol("Wireshark Hello Plugin", "Hello WS", "hello_ws");
+    handle_hello = create_dissector_handle(dissect_hello, proto_hello);
+    register_postdissector(handle_hello);
+}
+
+static void
+proto_reg_handoff_hello(void)
+{
+    /* empty */
+}
+
+void
+plugin_register(void)
+{
+    static proto_plugin plug;
+
+    plug.register_protoinfo = proto_register_hello;
+    plug.register_handoff = proto_reg_handoff_hello; /* or NULL */
+    proto_register_plugin(&plug);
+}