The ONL Tutorial
Preliminaries
Installing your first plugin involves these steps:
- Create your own plugin directory.
- Write and compile the plugin in your plugin directory.
- Load the plugin into an SPC.
- load a filter to divert traffic to the plugin.
- Create an instance of the plugin.
- Bind the plugin instance to the filter.
The RLI is used in all but the first two steps.
After installation, you can communicate with your plugin as well
as get periodic data from your plugin through the RLI.
This section will lead you through your first plugin -- the
COUNTER plugin -- and in the process give you
a brief tour of the plugin facilities.
Let's prepare to create your first plugin.
In the examples, we assume that the plugin directory
is myplugins in your ONL home directory, but
it can be any allowable Unix file name.
Start by creating your own plugin directory:
client> ssh onl.arl.wustl.edu
onlusr> mkdir myplugins # subdirectory in home directory
Note that you will be directed to the ONL users host
onlusr when you SSH to onl.arl.wustl.edu.
You can always SSH to onlusr even if you don't have an active
experiment.
Your home directory will be mounted on that host.
Each plugin (class) will be developed in a separate subdirectory
of myplugins.
Now, copy some useful scripts, documentation and skeleton code
to the myplugin directory.
Note that these commands will recursively copy files and therefore
will create the subdirectories myplugins/bin, myplugins/doc and
myplugins/template.
cp -R ~onl/stdPlugins/bin myplugins # scripts
cp -R ~onl/stdPlugins/doc myplugins # documentation
cp -R ~onl/stdPlugins/template myplugins # template files
The above bin directory contains the perl script newplugin.pl
which is useful for creating new plugin directories from templates.
The doc directory contains the README file gives a brief
summary of how to create a plugin.
The template directory contains skelton files that are
used by the newplugins.pl perl script desribed later.
You will also notice that ~onl/stdPlugins/ also contains
several plugin directories including COUNTER-200,
a plugin almost identical to the ones we will develop here.
The ~onl/stdPlugins/ directory contains prewritten plugins
that are made available by the RLI as a default.
In this section, we will be writing our own plugin which we will
include with the standard prewritten ones.
Since much of the source code base for a plugin is the same,
there are two common ways to start:
- Copy the files from one of the standard plugin directories and
suitably modify the code; or
- Use the newplugin.pl perl script to create the starting code base.
We will now describe the second method since it will be obvious
how to apply the first method if you understand the second.
Let's create a new plugin called mycounter with a plugin ID of 1100.
The plugin ID is a positive integer that is unique among the standard
plugins and your personal plugins.
The plugin name should be unique among the standard plugin and your
personal plugin names.
Enter the following:
cd myplugins
./bin/newplugins.pl mycounter 1100
The newplugins.pl perl script:
- Makes the directory mycounter-1100;
- Copies the file TEMPLATE.c from the
template directory to the file
mycounter-1100/mycounter.c after replacing every
occurrence of the string <TEMPLATE>
with the string mycounter and every occurrence of
the string <MYID> with the string 1100.
- Repeats the previous step creating the files mycounter.h,
stdinc.h, and Makefile using TEMPLATE.h,
stdinc.h and Makefile from the template
directory respectively.
The file mycounter-1100/mycounter.c now contains the skeleton code
required of all plugins; i.e., all of the code to aid in the functions
to load/unload, create/free, bind/unbind, handle a packet and handle a
message from the CP.
Now, all we need to do is to add code specific to our application.
Revised: Tue, Aug 14, 2006
TOC
