Bro plugins should support a patch version (x.y.z)

CHANGES

@@ -1,3 +1,6 @@
+2.6-beta2-16 | 2018-09-29 21:30:31 -0500
+
+  * Add an optional plugin patch version (Jon Zeolla)
 
 2.6-beta2-14 | 2018-09-25 16:38:29 -0500
 

NEWS

@@ -544,6 +544,11 @@ Changed Functionality
   indicated whether each Bro process was the "parent" or "child", but this
   is no longer relevant because each Bro node now runs as a single process.
 
+- Bro's Plugin framework now allows a patch version.  If a patch version is not
+  provided, it will default to 0.  To specify this, modify the plugin
+  Configuration class in your ``src/Plugin.cc` and set
+  ``config.version.patch``.
+
 Removed Functionality
 ---------------------
 

doc/devel/plugins.rst

@@ -99,7 +99,7 @@ option::
     # export BRO_PLUGIN_PATH=/path/to/rot13-plugin/build
     # bro -N
     [...]
-    Demo::Rot13 - <Insert description> (dynamic, version 0.1)
+    Demo::Rot13 - <Insert description> (dynamic, version 0.1.0)
     [...]
 
 That looks quite good, except for the dummy description that we should
@@ -115,6 +115,7 @@ is about.  We do this by editing the ``config.description`` line in
         config.description = "Caesar cipher rotating a string's characters by 13 places.";
         config.version.major = 0;
         config.version.minor = 1;
+        config.version.patch = 0;
         return config;
         }
     [...]
@@ -124,14 +125,14 @@ Now rebuild and verify that the description is visible::
     # make
     [...]
     # bro -N | grep Rot13
-    Demo::Rot13 - Caesar cipher rotating a string's characters by 13 places. (dynamic, version 0.1)
+    Demo::Rot13 - Caesar cipher rotating a string's characters by 13 places. (dynamic, version 0.1.0)
 
 Bro can also show us what exactly the plugin provides with the
 more verbose option ``-NN``::
 
     # bro -NN
     [...]
-    Demo::Rot13 - Caesar cipher rotating a string's characters by 13 places. (dynamic, version 0.1)
+    Demo::Rot13 - Caesar cipher rotating a string's characters by 13 places. (dynamic, version 0.1.0)
         [Function] Demo::rot13
     [...]
 
@@ -166,7 +167,7 @@ unpacking.
 
 To distribute the plugin in binary form, the build process
 conveniently creates a corresponding tarball in ``build/dist/``. In
-this case, it's called ``Demo_Rot13-0.1.tar.gz``, with the version
+this case, it's called ``Demo_Rot13-0.1.0.tar.gz``, with the version
 number coming out of the ``VERSION`` file that ``init-plugin`` put
 into place. The binary tarball has everything needed to run the
 plugin, but no further source files. Optionally, one can include
@@ -395,7 +396,7 @@ let's get that in place::
     % 'btest-diff output' failed unexpectedly (exit code 100)
     % cat .diag
     == File ===============================
-    Demo::Rot13 - Caesar cipher rotating a string's characters by 13 places. (dynamic, version 0.1)
+    Demo::Rot13 - Caesar cipher rotating a string's characters by 13 places. (dynamic, version 0.1.0)
         [Function] Demo::rot13
 
     == Error ===============================

src/plugin/Plugin.cc

@@ -445,6 +445,8 @@ void Plugin::Describe(ODesc* d) const
 			d->Add(config.version.major);
 			d->Add(".");
 			d->Add(config.version.minor);
+			d->Add(".");
+			d->Add(config.version.patch);
 			d->Add(")");
 			}
 		else

src/plugin/Plugin.h

@@ -69,16 +69,26 @@ extern const char* hook_name(HookType h);
 struct VersionNumber {
 	int major; //< Major version number;
 	int minor; //< Minor version number;
+	int patch; //< Patch version number;
 
 	/**
 	 *  Constructor.
 	 */
-	VersionNumber()	{ major = minor = -1; }
+	VersionNumber()	{
+		/**
+		 * Major and minor versions are required.
+		 */
+		major = minor = -1;
+		/**
+		 * Patch version is optional, and set to 0 if not manually set.
+		 */
+		patch = 0;
+	}
 
 	/**
 	 *  Returns true if the version is set to a non-negative value.
 	 */
-	explicit operator bool() const { return major >= 0 && minor >= 0; }
+	explicit operator bool() const { return major >= 0 && minor >= 0 && patch >= 0; }
 };
 
 /**

testing/btest/Baseline/plugins.bifs-and-scripts-install/output

@@ -1,4 +1,4 @@
-Demo::Foo - <Insert description> (dynamic, version 0.1)
+Demo::Foo - <Insert description> (dynamic, version 0.1.0)
     [Function] hello_plugin_world
     [Event] plugin_event
 

testing/btest/Baseline/plugins.bifs-and-scripts/output

@@ -1,4 +1,4 @@
-Demo::Foo - <Insert description> (dynamic, version 0.1)
+Demo::Foo - <Insert description> (dynamic, version 0.1.0)
     [Function] hello_plugin_world
     [Event] plugin_event
 

testing/btest/Baseline/plugins.file/output

@@ -1,4 +1,4 @@
-Demo::Foo - A Foo test analyzer (dynamic, version 1.0)
+Demo::Foo - A Foo test analyzer (dynamic, version 1.0.0)
     [File Analyzer] Foo (ANALYZER_FOO)
     [Event] foo_piece
 

testing/btest/Baseline/plugins.init-plugin/output

@@ -1,3 +1,3 @@
-Demo::Foo - <Insert description> (dynamic, version 0.1)
+Demo::Foo - <Insert description> (dynamic, version 0.1.0)
 
 ===

testing/btest/Baseline/plugins.pktdumper/output

@@ -1,4 +1,4 @@
-Demo::Foo - A Foo packet dumper (dynamic, version 1.0)
+Demo::Foo - A Foo packet dumper (dynamic, version 1.0.0)
     [Packet Dumper] FooPktDumper (dumper prefix: "foo")
 
 ===

testing/btest/Baseline/plugins.plugin-nopatchversion/output

@@ -0,0 +1 @@
+Testing::NoPatchVersion - Testing a plugin without a specified patch version (dynamic, version 0.1.0)

testing/btest/Baseline/plugins.plugin-withpatchversion/output

@@ -0,0 +1 @@
+Testing::WithPatchVersion - Testing a plugin with a specified patch version (dynamic, version 0.1.4)

testing/btest/Baseline/plugins.protocol/output

@@ -1,4 +1,4 @@
-Demo::Foo - A Foo test analyzer (dynamic, version 1.0)
+Demo::Foo - A Foo test analyzer (dynamic, version 1.0.0)
     [Analyzer] Foo (ANALYZER_FOO, enabled)
     [Event] foo_message
 

testing/btest/Baseline/plugins.reader/output

@@ -1,4 +1,4 @@
-Demo::Foo - A Foo test input reader (dynamic, version 1.0)
+Demo::Foo - A Foo test input reader (dynamic, version 1.0.0)
     [Reader] Foo (Input::READER_FOO)
 
 ===

testing/btest/Baseline/plugins.writer/output

@@ -1,4 +1,4 @@
-Demo::Foo - A Foo test logging writer (dynamic, version 1.0)
+Demo::Foo - A Foo test logging writer (dynamic, version 1.0.0)
     [Writer] Foo (Log::WRITER_FOO)
 
 ===

testing/btest/README

@@ -20,17 +20,17 @@ Significant Subdirectories
 	Packet captures utilized by the various BTest tests.
 
 * scripts/
-    This hierarchy of tests emulates the hierarchy of the Bro scripts/
+	This hierarchy of tests emulates the hierarchy of the Bro scripts/
-    directory.
+	directory.
 
 * coverage/
-    This collection of tests relates to checking whether we're covering
+	This collection of tests relates to checking whether we're covering
-    everything we want to in terms of tests, documentation, and which
+	everything we want to in terms of tests, documentation, and which
-    scripts get loaded in different Bro configurations.  These tests are
+	scripts get loaded in different Bro configurations.  These tests are
-    more prone to fail as new Bro scripts are developed and added to the
+	more prone to fail as new Bro scripts are developed and added to the
-    distribution -- checking the individual test's comments is the best
+	distribution -- checking the individual test's comments is the best
-    place to check for more details on what exactly the test is checking
+	place to check for more details on what exactly the test is checking
-    and hints on how to fix it when it fails.
+	and hints on how to fix it when it fails.
 
 Running Tests
 =============

testing/btest/plugins/file-plugin/src/Plugin.cc

@@ -16,5 +16,6 @@ plugin::Configuration Plugin::Configure()
 	config.description = "A Foo test analyzer";
 	config.version.major = 1;
 	config.version.minor = 0;
+	config.version.patch = 0;
 	return config;
 	}

testing/btest/plugins/hooks-plugin/src/Plugin.cc

@@ -29,6 +29,7 @@ plugin::Configuration Plugin::Configure()
 	config.description = "Exercises all plugin hooks";
 	config.version.major = 1;
 	config.version.minor = 0;
+	config.version.patch = 0;
 	return config;
 	}
 

testing/btest/plugins/logging-hooks-plugin/src/Plugin.cc

@@ -21,6 +21,7 @@ plugin::Configuration Plugin::Configure()
 	config.description = "Exercises Log hooks";
 	config.version.major = 1;
 	config.version.minor = 0;
+	config.version.patch = 0;
 	return config;
 	}
 

testing/btest/plugins/pktdumper-plugin/src/Plugin.cc

@@ -16,5 +16,6 @@ plugin::Configuration Plugin::Configure()
 	config.description = "A Foo packet dumper";
 	config.version.major = 1;
 	config.version.minor = 0;
+	config.version.patch = 0;
 	return config;
 	}

testing/btest/plugins/pktsrc-plugin/src/Plugin.cc

@@ -16,5 +16,6 @@ plugin::Configuration Plugin::Configure()
 	config.description = "A Foo packet source";
 	config.version.major = 1;
 	config.version.minor = 0;
+	config.version.patch = 0;
 	return config;
 	}

testing/btest/plugins/plugin-nopatchversion-plugin/src/Plugin.cc

@@ -0,0 +1,16 @@
+
+#include "Plugin.h"
+
+namespace plugin { namespace Testing_NoPatchVersion { Plugin plugin; } }
+
+using namespace plugin::Testing_NoPatchVersion;
+
+plugin::Configuration Plugin::Configure()
+	{
+	plugin::Configuration config;
+	config.name = "Testing::NoPatchVersion";
+	config.description = "Testing a plugin without a specified patch version";
+	config.version.major = 0;
+	config.version.minor = 1;
+	return config;
+	}

testing/btest/plugins/plugin-nopatchversion.bro

@@ -0,0 +1,5 @@
+# @TEST-EXEC: ${DIST}/aux/bro-aux/plugin-support/init-plugin -u . Testing NoPatchVersion
+# @TEST-EXEC: cp -r %DIR/plugin-nopatchversion-plugin/* .
+# @TEST-EXEC: ./configure --bro-dist=${DIST} && make
+# @TEST-EXEC: BRO_PLUGIN_PATH=$(pwd) bro -N Testing::NoPatchVersion >> output
+# @TEST-EXEC: btest-diff output

testing/btest/plugins/plugin-withpatchversion-plugin/src/Plugin.cc

@@ -0,0 +1,17 @@
+
+#include "Plugin.h"
+
+namespace plugin { namespace Testing_WithPatchVersion { Plugin plugin; } }
+
+using namespace plugin::Testing_WithPatchVersion;
+
+plugin::Configuration Plugin::Configure()
+	{
+	plugin::Configuration config;
+	config.name = "Testing::WithPatchVersion";
+	config.description = "Testing a plugin with a specified patch version";
+	config.version.major = 0;
+	config.version.minor = 1;
+	config.version.patch = 4;
+	return config;
+	}

testing/btest/plugins/plugin-withpatchversion.bro

@@ -0,0 +1,5 @@
+# @TEST-EXEC: ${DIST}/aux/bro-aux/plugin-support/init-plugin -u . Testing WithPatchVersion
+# @TEST-EXEC: cp -r %DIR/plugin-withpatchversion-plugin/* .
+# @TEST-EXEC: ./configure --bro-dist=${DIST} && make
+# @TEST-EXEC: BRO_PLUGIN_PATH=$(pwd) bro -N Testing::WithPatchVersion >> output
+# @TEST-EXEC: btest-diff output

testing/btest/plugins/protocol-plugin/src/Plugin.cc

@@ -16,5 +16,6 @@ plugin::Configuration Plugin::Configure()
 	config.description = "A Foo test analyzer";
 	config.version.major = 1;
 	config.version.minor = 0;
+	config.version.patch = 0;
 	return config;
 	}

testing/btest/plugins/reader-plugin/src/Plugin.cc

@@ -15,5 +15,6 @@ plugin::Configuration Plugin::Configure()
 	config.description = "A Foo test input reader";
 	config.version.major = 1;
 	config.version.minor = 0;
+	config.version.patch = 0;
 	return config;
 	}

testing/btest/plugins/reporter-hook-plugin/src/Plugin.cc

@@ -19,6 +19,7 @@ plugin::Configuration Plugin::Configure()
 	config.description = "Exercise Reporter Hook";
 	config.version.major = 1;
 	config.version.minor = 0;
+	config.version.patch = 0;
 	return config;
 	}
 

testing/btest/plugins/writer-plugin/src/Plugin.cc

@@ -15,5 +15,6 @@ plugin::Configuration Plugin::Configure()
 	config.description = "A Foo test logging writer";
 	config.version.major = 1;
 	config.version.minor = 0;
+	config.version.patch = 0;
 	return config;
 	}