![](/trunk5/en/kdoctools5-common/top-kde.jpg)
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.
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ó.
É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.
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.
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.