Structure of a plugin package

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"))
			

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.