Affinché le estensioni esterne siano installate e funzionino correttamente, devono seguire alcune linee guida strutturali relative alla loro gerarchia dei file.
Diamo un'occhiata al prototipo di gerarchia dei file di un complesso archivio di estensione. Non è necessario includere tutte queste cartelle e/o file per far funzionare un'estensione (continuare a leggere per sapere cosa è assolutamente necessario), considerare questo un esempio di «best practice»:
nome_estensione/
inst/
rkward/
plugins/
nome_estensione.xml
nome_estensione.js
nome_estensione.rkh
...
po/
ll/
LC_MESSAGES/
rkward__nome_estensione_rkward.mo
rkward__nome_estensione_rkward.ll.po
rkward__nome_estensione_rkward.pot
tests/
testsuite_name/
RKTestStandards.nome_test.rkcommands.R
RKTestStandards.nome_test.rkout
...
pacchettotest.R
nome_estensione.pluginmap
...
ChangeLog
README
AUTHORS
LICENSE
DESCRIPTION
Nota
In questo esempio, tutte le occorrenze di plugin_name, testsuite_name e sometest_name devono essere sostituite con i loro nomi corretti, di conseguenza. Inoltre, ll è un segnaposto per un'abbreviazione linguistica (ad es., «de», «en» o «es»).
Suggerimento
Non è necessario creare questa gerarchia di file a mano. Se si utilizza la funzione rk.plugin.skeleton() dal pacchetto rkwarddev, creerà automaticamente per voi tutti i file e le cartelle necessari, tranne la cartella po creata e gestita dallo script di traduzione.
È obbligatorio includere almeno tre file: un .pluginmap, una descrizione .xml e un file .js dell'estensione. Cioè, anche la cartella «plugins» è facoltativa. Potrebbe essere utile dare un po' di ordine ai propri file, soprattutto se si includono più di un'estensione/finestra nell'archivio, il che ovviamente non è un problema. Per i file dell'estensione è possibile avere tutte le cartelle che si ritengono opportune, devono solo assomigliare rispettivamente a .pluginmap. È anche possibile includere diversi file .pluginmap, se soddisfano le vostre esigenze, ma dovreste includerli tutti in «plugin_name.pluginmap».
Ogni pacchetto di R deve avere un file DESCRIPTION valido, anch'esso fondamentale per RKWard per riconoscerlo come fornitore di estensioni. La maggior parte delle informazioni che contiene sono necessarie anche nelle Meta-informazioni dell'estensione e possibilmente nelle dipendenze, ma in un formato diverso (la documentazione di R spiega il file DESCRIPTION in dettaglio).
Oltre ai contenuti generali di un file DESCRIPTION, assicurarsi di includere anche la riga «Enhances:rkward». Ciò avvierà una scansione automatica da parte di RKWard del pacchetto alla ricerca di estensioni, se è installato. Un file DESCRIPTION di esempio è simile al seguente:
Package: QuadraturadelCerchio
Type: Package
Title: Squadra il cerchio
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: Trova la quadratura del cerchio utilizzando la compensazione di Heisenberg.
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"))
Suggerimento
Non è necessario scrivere questo file a mano. Se si utilizza la funzione rk.plugin.skeleton() dal pacchetto rkwarddev e si forniscono tutte le informazioni necessarie tramite l'opzione «about», creerà automaticamente un file DESCRIPTION funzionante per te.
ChangeLog, README, AUTHORS, LICENSE dovrebbero essere autoesplicativi e sono del tutto facoltativi. In realtà, non saranno interpretati da RKWard, quindi sono piuttosto destinati a contenere informazioni aggiuntive che potrebbero essere rilevanti ad es. per i distributori. La maggior parte dei loro contenuti rilevanti (riconoscimenti dell'autore, termini di licenza ecc;) saranno comunque inclusi nei file effettivi dell'estensione (vedere la sezione sulle meta-informazioni). Tenere presente che tutti questi file potrebbero anche essere posizionati da qualche parte nella cartella «inst», se volete che siano presenti non solo nell'archivio sorgente, ma anche nel pacchetto installato.
Un'altra cartella facoltativa è «tests», che ha lo scopo di fornire i file necessari per test automatizzati delle estensioni. Questi test sono utili per verificare rapidamente se le proprie estensioni funzionano ancora con le nuove versioni di R o RKWard. Se desiderate includere dei test, dovreste davvero limitarvi allo schema di denominazione e alla gerarchia mostrati qui. Cioè, i test dovrebbero risiedere in una cartella chiamata tests, che include un file testsuite.R e una cartella con gli standard dei test che prendono il nome dalla suite di test appropriata. Potete, tuttavia, fornire più di una suite di test; in tal caso, se non volete aggiungerli tutti in un unico file testsuite.R, potete dividerli in ad es. un file per ogni suite di test e creare un file testsuite.R con chiamate source() per ogni file di suite. In entrambi i casi, creare sottocartelle separate con standard di test per ciascuna suite definita.
I vantaggi di sostenere questa struttura sono che i test delle estensioni possono essere eseguiti semplicemente invocando rktests.makplugintests() dal pacchetto rkwardtests senza argomenti aggiuntivi. Dare un'occhiata alla documentazione in linea su Test automatico delle estensioni per ulteriori dettagli.