Updating plugin docs to recent changes.

doc/devel/plugins.rst

@@ -3,7 +3,7 @@
 Writing Bro Plugins
 ===================
 
-Bro is internally moving to a plugin structure that enables extending
+Bro internally provides plugin API that enables extending
 the system dynamically, without modifying the core code base. That way
 custom code remains self-contained and can be maintained, compiled,
 and installed independently. Currently, plugins can add the following
@@ -42,13 +42,13 @@ certain structure. To get started, Bro's distribution provides a
 helper script ``aux/bro-aux/plugin-support/init-plugin`` that creates
 a skeleton plugin that can then be customized. Let's use that::
 
-    # mkdir rot13-plugin
-    # cd rot13-plugin
-    # init-plugin Demo Rot13
+    # init-plugin ./rot13-plugin Demo Rot13
 
-As you can see the script takes two arguments. The first is a
-namespace the plugin will live in, and the second a descriptive name
-for the plugin itself. Bro uses the combination of the two to identify
+As you can see the script takes three arguments. The first is a
+directory inside which the plugin skeleton will be create; it
+shouldn't exist it. The second is namespace the plugin will live in,
+and the third a descriptive name for the plugin itself relative to the
+namespace. Bro uses the combination of namespace and name to identify
 a plugin. The namespace serves to avoid naming conflicts between
 plugins written by independent developers; pick, e.g., the name of
 your organisation. The namespace ``Bro`` is reserved for functionality
@@ -82,18 +82,22 @@ The syntax of this file is just like any other ``*.bif`` file; we
 won't go into it here.
 
 Now we can already compile our plugin, we just need to tell the
-configure script put in place by ``init-plugin`` where the Bro source
-tree is located (Bro needs to have been built there first)::
+configure script that ``init-plugin`` put in place where the Bro
+source tree is located (Bro needs to have been built there first)::
 
+    # cd rot13-plugin
     # ./configure --bro-dist=/path/to/bro/dist && make
     [... cmake output ...]
 
-Now our ``rot13-plugin`` directory has everything that it needs
-for Bro to recognize it as a dynamic plugin. Once we point Bro to it,
-it will pull it in automatically, as we can check with the ``-N``
+This builds the plugin in a subdirectory ``build/``. In fact, that
+subdirectory *becomes* the plugin: when ``make`` finishes, ``build/``
+has everything it needs for Bro to recognize it as a dynamic plugin.
+
+Let's try that. Once we point Bro to the ``build/`` directory, it will
+pull in our new plugin automatically, as we can check with the ``-N``
 option::
 
-    # export BRO_PLUGIN_PATH=/path/to/rot13-plugin
+    # export BRO_PLUGIN_PATH=/path/to/rot13-plugin/build
     # bro -N
     [...]
     Plugin: Demo::Rot13 - <Insert brief description of plugin> (dynamic, version 1)
@@ -153,24 +157,28 @@ Once we install it, it works again::
 The installed version went into
 ``<bro-install-prefix>/lib/bro/plugins/Demo_Rot13``.
 
-We can distribute the plugin in either source or binary form by using
-the Makefile's ``sdist`` and ``bdist`` target, respectively. Both
-create corrsponding tarballs::
+One can distribute the plugin independently of Bro for others to use.
+To distribute in source form, just remove the ``build/`` (``make
+distclean`` does that) and then tar up the whole ``rot13-plugin/``
+directory. Others then follow the same process as above after
+unpacking. To distribute the plugin in binary form, the build process
+conviniently creates a corresponding tarball in ``build/dist/``. In
+this case, it's called ``Demo_Rot13-0.1.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
+further files by specifying them in the plugin's ``CMakeLists.txt``
+through the ``bro_plugin_dist_files`` macro; the skeleton does that
+for ``README``, ``VERSION``, ``CHANGES``, and ``COPYING``. To use the
+plugin through the binary tarball, just unpack it and point
+``BRO_PLUGIN_PATH`` there; or copy it into
+``<bro-install-prefix>/lib/bro/plugins/`` directly.
 
-    # make sdist
-    [...]
-    Source distribution in build/sdist/Demo_Rot13.tar.gz
-
-    # make bdist
-    [...]
-    Binary distribution in build/Demo_Rot13-darwin-x86_64.tar.gz
-
-The source archive will contain everything in the plugin directory
-except any generated files. The binary archive will contain anything
-needed to install and run the plugin, i.e., just what ``make install``
-puts into place as well. As the binary distribution is
-platform-dependent, its name includes the OS and architecture the
-plugin was built on.
+Before distributing your plugin, you should edit some of the meta
+files that ``init-plugin`` puts in place. Edit ``README`` and
+``VERSION``, and update ``CHANGES`` when you make changes. Also put a
+license file in place as ``COPYING``; if BSD is fine, you find a
+template in ``COPYING.edit-me``.
 
 Plugin Directory Layout
 =======================
@@ -179,7 +187,7 @@ A plugin's directory needs to follow a set of conventions so that Bro
 (1) recognizes it as a plugin, and (2) knows what to load.  While
 ``init-plugin`` takes care of most of this, the following is the full
 story. We'll use ``<base>`` to represent a plugin's top-level
-directory.
+directory. With the skeleton, ``<base>`` corresponds to ``build/``.
 
 ``<base>/__bro_plugin__``
     A file that marks a directory as containing a Bro plugin. The file
@@ -205,6 +213,8 @@ directory.
     Directory with auto-generated Bro scripts that declare the plugin's
     bif elements. The files here are produced by ``bifcl``.
 
+Any other files in ``<base>`` are ignored by Bro.
+
 By convention, a plugin should put its custom scripts into sub folders
 of ``scripts/``, i.e., ``scripts/<script-namespace>/<script>.bro`` to
 avoid conflicts. As usual, you can then put a ``__load__.bro`` in
@@ -229,15 +239,19 @@ their source directory (after ``make`` and setting Bro's
 install``).
 
 ``make install`` copies over the ``lib`` and ``scripts`` directories,
-as well as the ``__bro_plugin__`` magic file and the ``README`` (which
-you should customize). One can add further CMake ``install`` rules to
-install additional files if needed.
+as well as the ``__bro_plugin__`` magic file and any further
+distribution files specified in ``CMakeLists.txt`` (e.g., README,
+VERSION). You can find a full list of files installed in
+``build/MANIFEST``. Behind the scenes, ``make install`` really just
+copies over the binary tarball in ``build/dist``. 
 
-``init-plugin`` will never overwrite existing files, so it's safe to
-rerun in an existing plugin directory; it only put files in place that
-don't exist yet. That also provides a convenient way to revert a file
-back to what ``init-plugin`` created originally: just delete it and
-rerun.
+``init-plugin`` will never overwrite existing files. If its target
+directory already exists, it will be default decline to do anything.
+You can run it with ``-u`` instead to update an existing plugin,
+however it will never overwrite any existing files; it will only put
+in place files it doesn't find yet. To revert a file back to what
+``init-plugin`` created originally, delete it first and then rerun
+with ``-u``.
 
 Activating a Plugin
 ===================
@@ -375,7 +389,7 @@ Now let's add a custom test that ensures that our bif works
 correctly::
 
     # cd tests
-    # cat >plugin/rot13.bro
+    # cat >rot13/bif-rot13.bro
 
     # @TEST-EXEC: bro %INPUT >output
     # @TEST-EXEC: btest-diff output
@@ -415,7 +429,7 @@ Debugging Plugins
 =================
 
 If your plugin isn't loading as expected, Bro's debugging facilities
-can help to illuminate what's going on. To enable, recompile Bro
+can help illuminate what's going on. To enable, recompile Bro
 with debugging support (``./configure --enable-debug``), and
 afterwards rebuild your plugin as well. If you then run Bro with ``-B
 plugins``, it will produce a file ``debug.log`` that records details
@@ -435,7 +449,6 @@ replaced with a simple dash. Example: If the plugin is called
 output will be recorded to ``debug.log`` if Bro's compiled in debug
 mode.
 
-
 Documenting Plugins
 ===================