Estrutura de um pacote de plugins

Para que os plugins externos sejam instalados e funcionem corretamente, eles devem seguir algumas diretrizes estruturais em relação à sua hierarquia de arquivos.

Hierarquia de arquivos

Vamos dar uma olhada na hierarquia de arquivos prototípica de um plugin elaborado. Você não precisa incluir todos esses diretórios e/ou arquivos para que um plugin funcione (continue lendo para saber o que é absolutamente necessário), considere isso um exemplo de boa prática:

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

Neste exemplo, todas as ocorrências de plugin_name, testsuite_name e sometest_name devem ser substituídas por seus nomes corretos, respectivamente. Além disso, ll é um marcador para uma abreviação de idioma (por exemplo, de, en ou es).

Dica

Você não precisa criar essa hierarquia de arquivos manualmente. Se você usar a função rk.plugin.skeleton() do pacote rkwarddev, ela criará automaticamente todos os arquivos e diretórios necessários para você, exceto o diretório po, que é criado e gerenciado pelo script de tradução.

Componentes de um plugin básico

É obrigatório incluir pelo menos três arquivos: um .pluginmap, um arquivo .xml com a descrição do plugin e um arquivo .js com a descrição do plugin. Ou seja, até mesmo o diretório "plugins" é opcional. Ele pode ajudar a organizar seus arquivos, principalmente se você incluir mais de um plugin/diálogo no arquivo, o que não é problema algum. Você pode ter quantos diretórios achar necessários para os arquivos de plugin, contanto que eles tenham nomes semelhantes aos do .pluginmap, respectivamente. Também é possível incluir vários arquivos .pluginmap, se isso atender às suas necessidades, mas você deve incluí-los todos em plugin_name.pluginmap.

Cada pacote R deve ter um arquivo DESCRIPTION válido, que também é crucial para o RKWard o reconhecer como um provedor de plugin. A maior parte das informações que ele contém também é necessária nas Meta-informações do plugin e possivelmente nas dependências, mas em um formato diferente (a documentação do R explica o arquivo DESCRIPTION em detalhes).

Além do conteúdo geral de um arquivo DESCRIPTION, certifique-se de incluir também a linha Aprimora: rkward. Isso fará com que o RKWard verifique automaticamente o pacote em busca de plugins, caso ele esteja instalado. Um exemplo de arquivo DESCRIPTION se parece com isto:

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

Dica

Você não precisa escrever este arquivo manualmente. Se você usar a função rk.plugin.skeleton() do pacote rkwarddev e fornecer todas as informações necessárias através da opção about, ela criará automaticamente um arquivo DESCRIPTION funcional para você.

Informações adicionais (opcional)

ChangeLog, README, AUTHORS, LICENSE devem ser autoexplicativos e são totalmente opcionais. Na verdade, eles não serão interpretados pelo RKWard, portanto, servem para conter informações adicionais que podem ser relevantes, por exemplo, para distribuidores. A maior parte do conteúdo relevante (créditos do autor, termos da licença por exemplo) já estará incluída nos arquivos do plugin (consulte a seção sobre meta-informações). Observe que todos esses arquivos também podem ser colocados em algum lugar no diretório "inst", se você quiser que eles estejam presentes não apenas no arquivo de origem, mas também no pacote instalado.

Teste automatizado de plugins (opcional)

Outro diretório opcional é "tests", que se destina a fornecer arquivos necessários para testes automatizados de plugins. Esses testes são úteis para verificar rapidamente se seus plugins ainda funcionam com novas versões do R ou do RKWard. Se você quiser incluir testes, é altamente recomendável restringir-se ao esquema de nomenclatura e hierarquia mostrados aqui. Ou seja, os testes devem residir em um diretório chamado tests, que inclui um arquivo testsuite.R e uma pasta com padrões de teste nomeados de acordo com o conjunto de testes apropriado. Você pode, no entanto, fornecer mais de um conjunto de testes; nesse caso, se não quiser anexá-los todos em um único arquivo testsuite.R, você pode dividi-los em, por exemplo; um arquivo para cada conjunto de testes e criar um arquivo testsuite.R com chamadas source() para cada arquivo de conjunto de testes. Em ambos os casos, crie subdiretórios separados com padrões de teste para cada conjunto de testes definido.

A vantagem de manter essa estrutura é que os testes de plugins podem ser executados simplesmente chamando rktests.makplugintests() do pacote rkwardtests sem argumentos adicionais. Consulte a documentação online em Testes Automatizados de Plugins para obter mais detalhes.