Structure of a plugin package

For external plugins to install and work properly, they must follow some structural guidelines regarding their file hierarchy.

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 don't 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.

Basic plugin components

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 don't 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.

Additional information (optional)

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.

Automated plugin testing (optional)

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.