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.
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.
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.
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.
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.