Devtools: Opcionalmente, oxigenize (ou execute o código R personalizado) antes de construir

Eu acho que é importante ter um campo BuildDepends porque ele pode ser usado para verificar se você tem (por exemplo) a versão correta do roxygen2.

Então, pode não haver necessidade de suportar a sintaxe document = TRUE simples.

Acho que o curso para todos os problemas é que um repositório no github é usado para gerenciamento de código-fonte e distribuição de pacote. Os arquivos Rd nunca devem ser rastreados por git no repositório de origem; por outro lado, os arquivos Rd devem ser rastreados e compartilhados por meio do github no repositório de pacotes.

Conceitualmente, temos algo como,

       prebuild, such as generate Rd
  Src ====================================> Package

Eu quero chamar a ação de src a package como construção, mas build significa algo diferente em R, então vamos chamá-la de pré-construção aqui.

Uma solução é obter dois repositórios, um para arquivos de origem, como RPackageFoo-dev, e outro para distribuição de pacotes, como RPackageFoo. Então, com algum script, como um gancho git, podemos atualizar o repositório de distribuição de pacote automaticamente. Nessa configuração, todos podem instalar o pacote do repositório de pacotes sem nenhum problema, e os desenvolvedores, que usam o repositório de origem, precisam cuidar do processo de pré-construção por conta própria. O custo aqui é que temos que lidar com dois repositórios, e alguns usuários e desenvolvedores podem não perceber que o pacote tem dois repositórios.

Outra solução é incorporar a pré-construção em devtools e permitir que os usuários lidem com a pré-construção sozinhos. Felizmente, é fácil para desenvolvedores e usuários, com a ajuda de devtools. Para fazer com que realmente funcione conforme o esperado, o procedimento de pré-construção deve ser fácil o suficiente para ser executado por qualquer máquina, incluindo o Windows. Se devtools tem que lidar com a dependência de construção e os usuários podem ter que instalar um monte de pacotes ou mesmo versões diferentes de um pacote, então é muito complexo empurrar o trabalho para os usuários, e os desenvolvedores devem fazer o levantamento de peso, se possível.

Ou podemos continuar usando um repositório para o gerenciamento src e distribuição de pacotes, e construir algum script e configurar para lidar com arquivos "compilados" no git facilmente. Acho o artigo Lidando com arquivos compilados no Git útil. As configurações básicas são,

• definir .gitattributes para que git diff ignore todos os arquivos compilados
• defina o driver git merge para que git merge sempre use a versão local dos arquivos compilados
• configure o git hook para que os arquivos Rd sejam atualizados antes de enviar para o github

A armadilha potencial é que o git merge driver e o git hook não podem ser sincronizados pelo git e devem ser configurados manualmente por todos os desenvolvedores. A boa notícia é, eu acho, configuração inadequada por outro desenvolvedor não bagunçará seu repositório. Outro problema é que você pode não conseguir lidar com a solicitação de pull no github, pois ele não oferece suporte para unidade de mesclagem. Na verdade, a única maneira de garantir que os arquivos Rd sejam atualizados corretamente é pré-compilar localmente e enviar para o github. Eu não acho que estou prevendo todos os problemas possíveis, pois é de alguma forma muito complexo para mim.

A beleza de install_github é que você pode instalar qualquer ref ou até mesmo pull request. Qualquer técnica de espelhamento terá que fornecer isso para ter um uso equivalente.

Eu concordo que a pré-construção em devtools deve ser indolor para o usuário.

O artigo sobre como armazenar arquivos compilados é uma boa solução, mas a configuração é um pouco complicada. Nem todas as atualizações de .Rd arquivos causam um conflito de mesclagem. Se uma pequena ferramenta cuidasse desses detalhes - ótimo!

@hadley : Podemos concordar em tornar a dependência BuildDepends opcional para build e install mas obrigatória para check e release ? Acho que, de outra forma, o requisito de que "a pré-construção deve ser indolor para o usuário" não pode ser satisfeito facilmente. É "apenas" documentação, se o usuário precisar, ele pode tomar as medidas adequadas para garantir que ela seja instalada; caso contrário, não há necessidade de abortar a instalação porque uma dependência está faltando.

Eu estava brincando com a ideia de automatizar a ferramenta de construção e implantação para travis-ci . O repositório do projeto está disponível em r-deploy-git . Está no estágio inicial e parece funcionar bem com meu pacote fictício r . Pelo menos, mostra que é factível. Esperançosamente, um script confiável estará disponível em um futuro próximo, com a ajuda de todos.

Para devtools , acho que seria uma boa ideia ter uma maneira de distinguir um pacote "fonte" e um pacote "pré-compilado". Para um pacote "fonte", o prebuild deve ser chamado para gerar arquivos, como arquivos Rd, e os desenvolvedores do pkg podem usar qualquer ferramenta que quiserem, incluindo make , já que presumimos que qualquer um instalando o pacote "src" como desenvolvedores ou usuários avançados. Para um pacote "pré-construído", ele deve seguir o padrão CRAN e pode ser instalado com R CMD INSTALL .

Um problema com a execução de document() como parte do processo install_github() é que os arquivos .Rd resultantes não são totalmente determinados pelo conteúdo da fonte do pacote. Eles podem depender de pacotes externos, por exemplo:

• Se você usar @inheritParams de algo de um pacote diferente, a versão desse pacote é importante. Às vezes, a documentação muda entre as versões. (Este é um problema que encontrei no passado.)
• Os arquivos .Rd de saída dependem da versão do roxygen2.

Por um lado, você pode pensar que isso é bom, porque essas mudanças nos pacotes externos não resultam em commits "extras" no código-fonte do seu pacote. Mas, por outro lado, há um grande problema: se você está liberando um pacote para o CRAN, não há commit que corresponda ao conteúdo exato do que foi construído e enviado para o CRAN, porque o que é enviado depende tanto do código-fonte quanto do ecossistema R no seu computador.

Você ainda pode manter um ramo de versões "lançadas" que contém os arquivos roxygenized:

A===B===C===D===E===F===G===...
 \                   \
  R1==================R2=========...

Aqui, A até G representam o ramo de desenvolvimento, e R1 e R2 são lançamentos; os arquivos .Rd estão contidos no branch de lançamento.

Os outros problemas que você mencionou podem ser atenuados por uma abordagem do tipo packrat . (Usar realmente packrat exigiria rstudio / packrat # 31.) Embora pareça um exagero apenas para a tarefa em questão, também permite a "atualização controlada" das dependências - consulte os comentários no problema vinculado.

Este problema e o # 523 estão começando a me fazer pensar que talvez devêssemos oferecer isso como uma opção ...

Também percebi que outro possível problema do usuário final é que, ao documentar novamente, as entradas em NAMESPACE podem depender de quais pacotes estão carregados no momento. Isso é algo que vi com métodos S3 e genéricos.

Acho que isso poderia ser resolvido incluindo algum código R na árvore do github, que é executado por devtools::install_github (ou melhor, devtools::install em geral).

Existem algumas perguntas sobre _como_:

• Onde colocar o código R. Provavelmente, isso é simples e pode simplesmente ir para um arquivo que é ignorado por build() , por exemplo, build_package.R .
• Como evitar o problema mencionado por @wch . Isso pode ser feito corrigindo as versões do pacote construtor, por exemplo, adicionando um campo BuildDependencies a DESCRIPTION , que pode especificar a versão exata do pacote que você deseja usar para construir. Exemplos:

BuildDependencies: roxygen2 (= 4.0.1), Rcpp (>= 0.11)

ou mesmo isso para depender de uma versão exata:

BuildDependencies: http://github.com/hadley/roxygen/7759478a86f803c5222c19189a022134de251ccb

Isso também resolveria o problema que tínhamos às vezes, quando vários pacotes usam diferentes versões do roxygen2, e vários desenvolvedores também têm várias versões.

Acabei de ler este tópico e percebi que @hadley estava sugerindo essencialmente o mesmo no início ...

Fico feliz que as pessoas tenham tempo para implementar isso, eu posso ver o uso e entendo que as pessoas têm religião sobre o rastreamento de arquivos construídos ...

Mas para a maioria dos usuários, construir arquivos Rd localmente será uma fonte de muitos erros intratáveis. Isso os levará a incomodar os autores de pacotes e Hadley ... Seria sensato recomendar o armazenamento de arquivos .Rd pré-compilados se não especialistas estiverem usando seu pacote?

Isso é semelhante a pacotes que precisam de compilação: No Windows, você precisa do Rtools. Acho que usuários não especialistas não deveriam estar usando install_github em primeiro lugar, mas isso requer alguma infraestrutura, por exemplo, conforme descrito em rpkg / rep .

amen para evitar Rtools para usuários do Windows. "CRAN 2.0" parece bom, embora a verificação severa que eles impõem aumente a confiança sobre a integridade do código.

Acho que é melhor lidar com isso em outro lugar. Atualmente install_github() é uma forma muito comum de instalar pacotes e ter que executar código adicional antes da instalação irá adicionar muita complexidade.

Você apoiaria um argumento document = TRUE para build() ?

Este problema antigo foi bloqueado automaticamente. Se você acredita que encontrou um problema relacionado, registre um novo problema (com reprex) e crie um link para esse problema. https://reprex.tidyverse.org/