Estructura d'un paquet de connector

Perquè els connectors externs s'instal·lin i funcionin correctament han de seguir algunes directrius estructurals pel que fa a la seva jerarquia de fitxers.

Jerarquia de fitxers

Donem un cop d'ull a la jerarquia de fitxers prototípica d'un arxiu de connectors elaborat. No heu d'incloure tots aquests directoris i/o fitxers perquè funcioni un connector (llegiu per a saber què és absolutament necessari), considereu això un exemple de «millor pràctica»:

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
                

Nota

En aquest exemple, tots els casos de plugin_name, testsuite_name i sometest_name s'han de substituir pels seus noms correctes, d'acord amb això. A més, ll és un marcador de posició per a una abreviatura de l'idioma (p. ex., «de», «en» o «es»).

Suggeriment

No heu de crear aquesta jerarquia de fitxers a mà. Si utilitzeu la funció rk.plugin.skeleton() del paquet rkwarddev, es crearan automàticament tots els fitxers i directoris necessaris, excepte el directori po que es crea i gestiona amb l'script de traducció.

Components bàsics del connector

És obligatori incloure almenys tres fitxers: un .pluginmap, una descripció .xml del connector i un fitxer .js del connector. És a dir, fins i tot el directori "plugins" és opcional. Pot ajudar a donar una mica d'ordre als vostres fitxers, especialment si incloeu més d'un connector/diàleg a l'arxiu, que no és cap problema per descomptat. Podeu tenir tants directoris per als fitxers de connectors reals com creieu oportú, només s'han d'assemblar al .pluginmap, respectivament. També és possible incloure diversos fitxers .pluginmap, si s'adapta a les vostres necessitats, però llavors hauríeu d'incloure'ls tots a «plugin_name.pluginmap».

Cada paquet R ha de tenir un fitxer DESCRIPTION vàlid, el qual també és crucial per al RKWard reconeixent-lo com a proveïdor de connectors. La major part de la informació que porta també és necessària en el connector Meta-information i possiblement dependencies, però en un format diferent (la documentació de l'R explica el fitxer DESCRIPTION en detall).

A més del contingut general d'un fitxer DESCRIPTION, assegureu-vos també d'incloure la línia «Enhances: rkward». Això farà que el RKWard escanegi automàticament el paquet cercant connectors si està instal·lat. Un exemple de fitxer DESCRIPTION té aquest aspecte:

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

Suggeriment

No heu d'escriure aquest fitxer a mà. Si utilitzeu la funció rk.plugin.skeleton() del paquet rkwarddev i proporcioneu tota la informació necessària a través de l'opció «about», es crearà automàticament un fitxer DESCRIPTION que funciona.

Informació addicional (opcional)

ChangeLog, README, AUTHORS, LICENSE haurien de ser autoexplicatius i són totalment opcionals. En realitat, no seran interpretats pel RKWard, de manera que estan més aviat destinats a portar informació addicional que podria ser rellevant, p. ex., per als distribuïdors. La majoria del seu contingut rellevant (crèdits d'autor, termes de llicència, etc.) s'inclourà de totes maneres en els fitxers dels connectors reals (vegeu la secció sobre metainformació). Tingueu en compte que tots aquests fitxers també es poden col·locar en algun lloc del directori "inst", si voleu que no només estiguin presents a l'arxiu d'origen, sinó també al paquet instal·lat.

Proves automatitzades de connectors (opcional)

Un altre directori opcional és "tests", que està destinat a proporcionar els fitxers necessaris per a proves automatitzades de connectors. Aquestes proves són útils per a comprovar ràpidament si els connectors encara funcionen amb versions noves de l'R o del RKWard. Si voleu incloure proves, realment hauríeu de restringir-vos a l'esquema de noms i jerarquia que es mostra aquí. És a dir, les proves han de residir en un directori anomenat tests, que inclou un fitxer testsuite.R i una carpeta amb estàndards de proves anomenats després del conjunt de proves apropiat. No obstant això, podeu proporcionar més d'un conjunt de proves; en aquest cas, si no voleu afegir-les totes en el conjunt de proves testsuite.R, podeu dividir-los, p. ex., un fitxer per a cada paquet de proves i crear un testsuite.R amb crides source() a cada fitxer de la suite. En qualsevol cas, creeu subdirectoris separats amb estàndards de prova per a cada suite definida.

Els avantatges de mantenir aquesta estructura és que les proves dels connectors es poden executar simplement cridant rktests.makplugintests() del paquet rkwardtests sense arguments addicionals. Consulteu la documentació en línia de Proves de connectors automatitzades per a més detalls.