Strukturen hos ett insticksprogrampaket

För att externa insticksprogram ska installeras och fungera riktigt, måste de följa några strukturella tumregler när det gäller deras filhierarki.

Filhierarki

Låt oss ta en titt på en prototypliknande filhierarki för ett komplicerat insticksprogramarkiv. Man behöver inte inkludera alla de här katalogerna och/eller filerna för att ett insticksprogram ska fungera (läs vidare för att ta reda på vad som är absolut nödvändigt). Betrakta det här som en bästa metodens exempel:

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
                

Notera

I exemplet ska alla förekomster av plugin_name, testsuite_name och sometest_name ersättas med de riktiga namnen. Dessutom är ll en platsmarkör för en språkförkortning (t.ex. de, en eller sv).

Tips

Du behöver inte skapa filhierarkin för hand. Om funktionen rk.plugin.skeleton() från paketet rkwarddev, skapar den automatiskt alla nödvändiga filer och kataloger åt dig, utom katalogen po som skapas och hanteras av översättningsskriptet.

Grundläggande insticksprogramkomponenter

Det är nödvändig att inkludera minst tre filer: en .pluginmap, en .xml-beskrivning av ett insticksprogram, och en .js-fil för ett insticksprogram. Det vill säga, till och med katalogen "plugins" är valfri. Den kan dock hjälpa till att ge filerna en viss ordning, särskilt om mer än ett insticksprogram eller dialog inkluderas i arkivet, vilket förstås inte är något problem. Det går att ha så många kataloger för själva insticksprogramfilerna som anses lämpligt, de måste bara likna respektive .pluginmap. Det är också till och med möjligt att inkludera flera .pluginmap-filer, om det passar behoven, men då bör alla inkluderas i plugin_name.pluginmap.

Varje R-paket måste ha en giltig beskrivningsfil, DESCRIPTION, som också är väsentlig för att RKWard ska känna igen att den tillhandahåller ett insticksprogram. Det mesta av informationen den bär med sig behövs också i insticksprogrammets meta-information och möjligen beroenden, men med ett annat format (R-dokumentationen förklarar beskrivningsfilen DESCRIPTION i detalj).

Förutom det allmänna innehållet i DESCRIPTION-filen, se till att också inkludera raden Enhances: rkward. Det gör att RKWard automatiskt söker igenom paketet efter insticksprogram om det är installerat. Ett exempel på en DESCRIPTION-fil ser ut så här:

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

Tips

Du måste inte skriva filen för hand. Om du använder funktionen rk.plugin.skeleton() från paketet rkwarddev och tillhandahåller all nödvändig information via alternativet about, skapas automatiskt en fungerande DESCRIPTION-fil åt dig.

Ytterligare information (valfri)

ChangeLog, README, AUTHORS, LICENSE bör vara självförklarliga och är helt valfria. I själva verket tolkas de inte av RKWard, så de är istället avsedda att innehålla ytterligare information som kan vara relevant för t.ex. distributörer. Det mesta av deras relevanta innehåll (erkännanden av upphovsmän, licensvillkor, etc.)är dock ändå inkluderade i själva insticksprogrammets filer (se avsnittet om meta-information). Observera att alla filerna skulle också kunna placeras någonstans i katalogen "Inst", om man inte vill att de bara ska vara tillgängliga i källkodsarkivet utan också i det installerade paketet.

Automatiserad test av insticksprogram (valfri)

En annan valfri katalog är "tests", som är avsett att tillhandahålla filer som behövs för automatiserad test av insticksprogram. Testerna är användbara för att snabbt kontrollera om insticksprogrammet fortfarande fungerar med nya versioner av R eller RKWard. Om du vill inkludera tester, bör du verkligen begränsa dig till namnkonventionen och hierarkin som visas här. Det vill säga, tester ska finnas i en katalog som heter tests, som inkluderar filen testsuite.R och en katalog med teststandarder namngivna efter lämplig testsvit. Du kan dock tillhandahålla mer än en testsvit: I så fall, om du inte vill lägga till alla i en enda testsuite.R, kan de t.ex. delas upp i en fil för varje testsvit och en testsuite.R skapas som har anrop till varje svit med source(). I båda fall, skapa separata underkataloger med teststandarder för varje definierad svit.

Fördelen med att upprätthålla strukturen är att tester av insticksprogram kan helt enkelt köras genom att anropa rktests.makplugintests() från paketet rkwardtests utan ytterligare argument. Ta en titt på dokumentationen på nätet i Automated Plugin Testing för ytterligare information.