Structuur van een plugin-pakket

Opdat externe plugins goed installeren en werken, is het nodig dat zij voldoen aan enkele structurele regels met betrekking tot hun bestandshiërarchie.

Bestandshiërarchie

Kijken we naar de prototype bestandshiërarchie van een bewerkelijk pluginarchief. U heeft niet alle genoemde directories en/of bestanden nodig om het te laten werken (lees verder voor wat werkelijk nodig is). Beschouw dit als een best practice-voorbeeld:

plugin_name/
                inst/
                        rkward/
                                plugins/
                                        plugin_naam.xml
                                        plugin_naam.js
                                        plugin_naam.rkh
                                        ...
                                po/
                                        ll/
                                                LC_MESSAGES/
                                                        rkward__plugin_naam_rkward.mo
                                        rkward__plugin_naam_rkward.ll.po
                                        rkward__plugin_naam_rkward.pot
                                tests/
                                        testsuite_naam/
                                                RKTestStandards.eentest_naam.rkcommands.R
                                                RKTestStandards.eentest_naam.rkout
                                                ...
                                        testsuite.R
                                plugin_name.pluginmap
                                ...
        ChangeLog
        README
        AUTHORS
        LICENSE
        DESCRIPTION
                

Opmerking

In dit voorbeeld moeten alle voorkomens van plugin_naam, testsuite_naam en eentest_naam worden vervangen door de juiste namen. Ook is ll een plaatshouder voor een taalcode (bijv., nl (Nederlands), en of es).

Tip

U hoeft deze bestandshiërarchie niet zelf te maken. Indien u de functie rk.plugin.skeleton() uit het rkwarddev-pakket gebruikt, maakt het automatisch alle nodige bestanden en directories voor u aan, behalve de po-directory, die wordt aangemaakt en beheerd door de vertaalscript.

Basis plugin-componenten

Het is verplicht ten minste drie bestanden bij te sluiten: een .pluginmap, een plugin .xml -beschrijving en een plugin .js-bestand. Dat betekent dat zelfs de "plugins"-directory optioneel is. Het kan helpen als u uw bestandenenigszins ordent, zeker als u meerdere plugins/dialogen in het archief opneemt, wat natuurlijk geen probleem is. U kunt net zoveel directories gebruiken voor de pluginbestanden als u nodig vindt, zij hoeven slechts te lijken op de .pluginmap. Het is ook mogelijk diverse .pluginmap-bestanden bij te sluiten, indien dit nodig is, maar u moet ze in dat geval allemaal opnemen in plugin_naam.pluginmap.

Elk R-pakket moet een geldig DESCRIPTION-bestand (bestand met een BESCHRIJVING) hebben, dat ook cruciaal is voor RKWard en waarin staat dat het een plugin bevat. De meeste informatie erin is ook nodig in de plugin Meta-informatie (informatie over de plugin) en mogelijke dependencies, maar in een ander format (de R-documentatie verklaart het DESCRIPTION-bestand in detail).

Naast de algemene inhoud van een DESCRIPTION- bestand, moet u ook zorgen voor de regel Enhances: rkward (verbetert rkward). Hierdoor zal RKWard automatisch het pakket naar plugins doorzoeken bij installatie. Een voorbeeld van een DESCRIPTION-bestand ziet er als volgt uit: 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: Cirkelkwadratuur met 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

U hoeft dit bestand niet zelf te schrijven. Indien u de functie rk.plugin.skeleton() uit het rkwarddev-pakket gebruikt en alle nodige informatie geeft via de about-optie, dan maakt het automatisch een werkend DESCRIPTION-bestand aan voor u.

Bijkomende informatie (optioneel)

ChangeLog, README, AUTHORS, LICENSE moeten voor zichzelf spreken en zijn geheel optioneel. In feite worden die niet geïnterpreteerd door RKWard, dus zijn die alleen bedoeld voor het doorgeven van informatie die van belang kan zijn voor bijv. distributeurs. De meeste informatie (over de auteurs, licentiebepalingen etc.) worden toch wel gegeven in de plugin-bestanden (zie de sectie over meta-informatie). Merk op dat al deze bestanden ook kunnen worden geplaatst ergens in de "inst"-directory, indien u wilt dat ze niet alleen in het bronarchief (source archive), maar ook in het geïnstalleerde pakket aanwezig zijn.

Geautomatiseerd testen van plugins (optioneel)

Een andere optionele directory is "tests", met daarin bestanden die nodig zijn voor het automatisch testen van plugins. Deze tests zijn nuttig voor het snel controleren of uw plugins nog wel werken met de nieuwe versies van R of RKWard. Indien u deze tests wilt gebruiken, dan moet u u heel goed houden aan het het hier beschreven namenschema en hiërarchie. Dit betekent dat de tests in een directory met de naam tests moeten zijn, waaronder een bestand testsuite.R en een map met teststandaarden die genoemd zijn naar de bijbehorende test-suite. U kunt echter meerdere test-suites beschikbaar stellen. In dat geval hoeft u ze niet allemaal in één testsuite.R-bestand op te nemen. U kunt ze opsplitsen in bijv. een bestand voor elke test-suite en een testsuite.R aanmaken met source()-aanroepen voor elk bestand in de suite. In beide gevallen moet u aparte subdirectories aanmaken met teststandaarden voor elke gedefinieerde suite. Een suite (zeg: swiet) is een aantal bij elkaar behorende programma's.

Het nut van het zich houden aan deze structuur is dat het testen van plugin eenvoudig kan worden gedaan met rktests.makplugintests() in het rkwardtests-pakket zonder extra argumenten. Zie ook de online-documentatie Automatisch plugin-testen voor nadere details.