For external plugins to install and work properly, they must follow some structural guidelines regarding their file hierarchy.
Let's have a look at the prototypic file hierarchy of an elaborate plugin archive. You don’t have to include all of these directories and/or files for a plugin to work (read on to learn what’s absolutely necessary), consider this a “best practice” example:
plugin_name/ inst/ rkward/ plugins/ plugin_name.xml plugin_name.js plugin_name.rkh ... po/ ll/ LC_MESSAGES/ rkward__plugin_name_rkward.mo rkward__plugin_name_rkward.ll.po rkward__plugin_name_rkward.pot tests/ testsuite_name/ RKTestStandards.sometest_name.rkcommands.R RKTestStandards.sometest_name.rkout ... testsuite.R plugin_name.pluginmap ... ChangeLog README AUTHORS LICENSE DESCRIPTION
Note
In this example, all occasions of plugin_name, testsuite_name and sometest_name are to be replaced with their correct names, accordingly. Also, ll is a placeholder for a language abbreviation (e.g., “de”, “en” or “es”).
Tip
You do not have to create this file hierarchy by hand. If you use the function rk.plugin.skeleton()
from the rkwarddev package, it will automatically create all necessary files and directories for you, except the po
directory which is created and managed by the translation script.
It is mandatory to include at least three files: a .pluginmap
, a plugin .xml description and a plugin .js file. That is, even the "plugins" directory is optional. It might just help to give your files some order, especially if you include more that one plugin/dialog in the archive, which is of course no problem. You can have as many directories for the actual plugin files as you see fit, they just have to resemble the .pluginmap
, respectively. It is also possible to even include several .pluginmap
files, if it fits your needs, but you should include them all in “plugin_name.pluginmap” then.
Each R package must have a valid DESCRIPTION
file, which is also crucial for RKWard recognizing it as a plugin provider. Most of the information it carries is also needed in the plugin Meta-information and possibly dependencies, but in a different format (the R documentation explains the DESCRIPTION
file in detail).
In addition to the general contents of a DESCRIPTION
file, make sure to also include the line “Enhances: rkward”. This will cause RKWard to automatically scan the package for plugins if it is installed. An example DESCRIPTION
file looks like this:
Package: SquaretheCircle Type: Package Title: Square the circle Version: 0.1-3 Date: 2011-09-19 Author: E.A. Dölle <doelle@eternalwondermaths.example.org> Maintainer: A. Assistant <alterego@eternalwondermaths.example.org> Enhances: rkward Description: Squares the circle using Heisenberg compensation. License: GPL LazyLoad: yes URL: http://eternalwondermaths.example.org/23/stc.html Authors@R: c(person(given="E.A.", family="Dölle", role="aut", email="doelle@eternalwondermaths.example.org"), person(given="A.", family="Assistant", role=c("cre", "ctb"), email="alterego@eternalwondermaths.example.org"))
Tip
You do not have to write this file by hand. If you use the function rk.plugin.skeleton()
from the rkwarddev package and provide all necessary information via the “about” option, it will automatically create a working DESCRIPTION
file for you.
ChangeLog
, README
, AUTHORS
, LICENSE
should be self-explaining and are entirely optional. Actually, they won’t be interpreted by RKWard, so they are rather meant to carry additional information that might be relevant e.g. for distributors. Most of their relevant content (author credits, licence terms etc.) will be included in the actual plugin files anyway, though (see the section on meta-information). Note that all of these files could also be placed somewhere in the "inst" directory, if you want them not only to be present in the source archive but the installed package as well.
Another optional directory is "tests", which is meant to provide files needed for automated plugin testing. These tests are helpful to quickly check if your plugins still work with new versions of R or RKWard. If you want to include tests, you should really restrain yourself to the naming scheme and hierarchy shown here. That is, tests should reside in a directory called tests
, which includes a file testsuite.R
and a folder with tests standards named after the appropriate test suite. You can, however, provide more than one test suite; in that case, if you don’t want to append them all in the one testsuite.R
file, you can split them in e.g. one file for each test suite and create one testsuite.R
with source()
calls for each suite file. In either case, create separate subdirectories with test
standards for each defined suite.
The benefits of upholding to this structure is that plugin tests can be run simply by calling rktests.makplugintests()
from the rkwardtests package without additional arguments. Have a look at the online documentation on Automated Plugin Testing for further details.