HOWTO make a plugin

Types of plugins

In JANA, one can use plugins to provide JEventProcessors, JFactory, and JEventSource classes to supplement an existing executable. Actually, all a plugin really does is get attached to the process where it is given access to the JApplication object and the memory space of the program. This can be used for any number of things including things like ROOTSpy which doesn't create any of the above objects, but needs to access ROOT global memory. In most cases though, you will want to create a plugin that supplies one of the above listed JANA classes. Scripts exist for creating skeletons of each of these. Below are a brief descriptions of each to help you select which type best suits your project.

It should be noted that both JANA and DANA provide mkplugin and mkfactory_plugin scripts. The terminology "JANA" refers to the basic framework that does not contain any Hall-D or GlueX specific code. DANA refers to the Hall-D/GlueX implementation of JANA that adds specializations. Usually, you will want the DANA version that comes with the sim-recon code and should already be first in your PATH.

JEventProcessor

This is the most common type of plugin. It would typically be used to create and fill histograms and trees. A JEventProcessor class has an evnt method that gets called for every event regardless of how many threads are running. Create one with the mkplugin script like this:

> mkplugin MyTestPlugin
HALLD_HOME environment variable is set. Assuming DANA package.
(to use JANA instead, pass the "-j" option)

Generating files for plugin MyTestPlugin ....

 - JEventProcessor_MyTestPlugin.h
 - JEventProcessor_MyTestPlugin.cc
 - SConstruct

This will create a directory called MyTestPlugin that the 3 generated files will be placed into. You should be able to compile this right away, but before doing so, make sure your environment correctly indicates where you want to install it. The installation location will be in the directory tree pointed to by your HALLD_MY environment variable if it is set. Otherwise it will be installed in the directory tree pointed to by your HALLD_HOME environment variable. For example, you can do the following:

> setenv HALLD_MY $PWD
> cd MyTestPlugin
> scons install

Whenever a DANA program is run, the correct subdirectory of whatever your HALLD_MY is set to will be searched for any requested plugins. Use this by indicating the plugin on the command line when running a DANA program. For example:

> hd_root -PPLUGINS=MyTestPlugin file.evio

JFactory

This is less common and used if you wish to either add a factory or even replace an existing factory in an executable. Factories in JANA are classes that produce data objects that the framework passes around. A factory object is produced for every thread and every type of data object in the reconstruction. You might use this if you wanted to try developing say, a new track finder algorithm. To create a factory plugin use the mkfactory_plugin script:

> mkfactory_plugin MyTestFactoryPlugin

Generating files for factory plugin MyTestFactoryPlugin ....
 - MyTestFactoryPlugin.h
 - MyTestFactoryPlugin_factory.h
 - MyTestFactoryPlugin_factory.cc
 - JFactoryGenerator_MyTestFactoryPlugin.h
 - SConstruct

Similar to above, you'll want to set you HALLD_MY environment variable and build/install it with scons:

> setenv HALLD_MY $PWD
> cd MyTestFactoryPlugin
> scons install

Use with a DANA program by setting the PLUGINS configuration parameter:

> hd_root -PPLUGINS=MyTestFactoryPlugin file.evio

Note that if a plugin provides a factory that generates the same type of data objects as one already compiled into the executable, then the one in the plugin will have priority and be used. Similarly, if more than one plugin provide such a factory, then the first plugin listed will be used.

JEventSource

This type of plugin is uncommon. It is basically used to provide support for a different file format. An event source's job is to read data from a file and create data objects from it. To be useful, these data objects must be ones that can be used as inputs to existing factories. JANA does not actually have a script to make a plugin of this type, but does have a script to generate files of the appropriate classes from which to build a plugin. To make a JEventSource plugin, do the following (where JSON is just and example name):

> mkdir MyEventSourcePlugin
> cd MyEventSourcePlugin
> mkeventsource JSON

Generating file for event source of type JSON ....
 - JEventSourceGenerator_JSON.h
 - JEventSourceGenerator_JSON.cc
 - JEventSource_JSON.h
 - JEventSource_JSON.cc

Create an instance of the JEventSourceGenerator_JSON 
class and use it in a JANA application by registering it
with the JApplication object with something like:

  app->AddEventSourceGenerator(new JFactoryGenerator_JSON);

You'll need to copy in the SConstruct file by hand:

> cp $HALLD_HOME/src/SBMS/SConstruct.plugin ./SConstruct

Now, to give the plugin the appropriate routine that gets called when the plugin is attached (and therefore actually makes this a JANA plugin) paste the following snippet to the top of the JEventSource_JSON.cc file.

#include <JANA/JApplication.h>
extern "C"{
void InitPlugin(JApplication *app){
	InitJANAPlugin(app);
	app->AddEventSourceGenerator(new JEventSourceGenerator_JSON);
}
} // "C"

Now you are finally ready to compile and install:

> setenv HALLD_MY $PWD/..  # assume we are already in MyEventSourcePlugin directory
> scons install

Finally, use it in the standard way:

> hd_root -PPLUGINS= MyEventSourcePlugin file.json

Contact

For questions contact: David Lawrence davidl@jlab.org x5567