Devtools: Opcionalmente, oxigenizar (o ejecutar código R personalizado) antes de compilar

Creo que es importante tener un campo BuildDepends porque se puede usar para verificar que tiene (por ejemplo) la versión correcta de roxygen2.

Entonces puede que no sea necesario admitir la sintaxis simple document = TRUE .

Creo que el curso para todos los problemas es que se usa un repositorio en github tanto para la administración de fuentes como para la distribución de paquetes. Los archivos Rd nunca deben ser rastreados por git en el repositorio de origen; por otro lado, los archivos Rd deben ser rastreados y compartidos a través de github en el repositorio de paquetes.

Conceptualmente, tenemos algo como,

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

Quiero llamar a la acción de src a package como compilación, pero build significa algo diferente en R, así que llamémoslo precompilar aquí.

Una solución es obtener dos repositorios, uno para los archivos fuente, como RPackageFoo-dev, y otro para la distribución de paquetes, como RPackageFoo. Luego, con algún script, como un git hook, podemos actualizar el repositorio de distribución de paquetes automáticamente. Bajo tal configuración, todos pueden instalar el paquete desde el repositorio de paquetes sin ningún problema, y ​​los desarrolladores, que usan el repositorio de origen, deben manejar el proceso de compilación previa por sí mismos. El costo aquí es que tenemos que manejar dos repositorios, y algunos usuarios y desarrolladores pueden no notar que pkg tiene dos repositorios.

Otra solución es incrustar la precompilación en devtools y dejar que los usuarios se encarguen de la precompilación por sí mismos. Con suerte, es indoloro tanto para los desarrolladores como para los usuarios, con la ayuda de devtools. Para que realmente funcione como se esperaba, el procedimiento de precompilación debería ser lo suficientemente fácil como para ser manejado por cualquier máquina, incluido Windows. Si devtools tiene que manejar la dependencia del edificio y los usuarios pueden tener que instalar un montón de paquetes o incluso diferentes versiones de un paquete, entonces es demasiado complejo llevar el trabajo a los usuarios, y los desarrolladores deberían hacerlo. el trabajo pesado, si es posible.

O podemos seguir usando un repositorio tanto para la administración de src como para la distribución de pkg, y construir un script y configurarlo para manejar archivos "compilados" en git fácilmente. Encuentro útil el artículo Tratar con archivos compilados en Git . Las configuraciones básicas son,

• establecer .gitattributes para que git diff omita todos los archivos compilados
• configure el controlador git merge para que git merge siempre use la versión local de los archivos compilados
• configure git hook para que los archivos Rd se actualicen antes de presionar a github

El problema potencial es que git merge driver y git hook no pueden sincronizarse con git y deben ser configurados manualmente por todos los desarrolladores. La buena noticia es, supongo, que la configuración incorrecta de otro desarrollador no afectará a su repositorio. Otro problema es que es posible que no pueda manejar la solicitud de extracción en github, ya que no es compatible con la unidad de combinación. En realidad, la única forma de asegurarse de que los archivos Rd se actualicen correctamente es precompilarlos localmente y enviarlos a github. No creo que pueda prever todos los problemas posibles, ya que de alguna manera es demasiado complejo para mí.

La belleza de install_github es que puede instalar cualquier ref o incluso una solicitud de extracción. Cualquier técnica de duplicación deberá proporcionar esto para que sea de uso equivalente.

Estoy de acuerdo en que la preconstrucción en devtools tiene que ser indolora para el usuario.

El artículo sobre el almacenamiento de archivos compilados es una buena solución, pero la configuración es un poco complicada. No todas las actualizaciones de archivos .Rd provocan un conflicto de fusión. Si una pequeña herramienta se ocupara de esos detalles, ¡genial!

@hadley : ¿Podemos acordar que la dependencia BuildDepends opcional para build y install pero obligatoria para check y release ? Creo que, de lo contrario, el requisito de que "la preconstrucción debe ser indolora para el usuario" no se puede satisfacer fácilmente. Es "solo" documentación, si el usuario la necesita, puede tomar las medidas adecuadas para asegurarse de que esté instalada; si no, no es necesario cancelar la instalación porque falta una dependencia.

Estaba jugando con la idea de automatizar la construcción y la implementación de la herramienta por travis-ci . El repositorio del proyecto está disponible en r-deploy-git . Está en una etapa inicial y parece funcionar bien con mi paquete dummy r . Al menos, muestra que es factible. Con suerte, un guión confiable estará disponible en un futuro cercano, con la ayuda de todos.

Por devtools , creo que sería una buena idea tener una forma de distinguir un paquete "souce" y un paquete "prebuild". Para un paquete "fuente", se debe llamar a la compilación previa para generar archivos, como archivos Rd, y ​​los desarrolladores de pkg pueden usar cualquier herramienta que deseen, incluido make , ya que asumimos que cualquiera que instale el paquete "src" como desarrolladores o usuarios avanzados. Para un paquete "prediseñado", debe seguir el estándar CRAN y se puede instalar con R CMD INSTALL .

Un problema con la ejecución de document() como parte del proceso install_github() es que los archivos .Rd resultantes no están completamente determinados por el contenido de la fuente del paquete. Pueden depender de paquetes externos, por ejemplo:

• Si usa @inheritParams de algo de un paquete diferente, la versión de ese paquete es importante. A veces, la documentación cambia entre versiones. (Este es un problema que encontré en el pasado).
• Los archivos .Rd de salida dependen de la versión de roxygen2.

Por un lado, podría pensar que esto es bueno, porque estos cambios en los paquetes externos no dan como resultado confirmaciones "adicionales" en el código fuente de su paquete. Pero, por otro lado, hay un gran problema: si está lanzando un paquete a CRAN, no hay un compromiso que corresponda al contenido exacto de lo que se creó y se envió a CRAN, porque lo que se envía depende tanto del código fuente como del ecosistema R en tu ordenador.

Aún puede mantener una rama de versiones "liberadas" que contenga los archivos oxigenizados:

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

Aquí, A hasta G representan la rama de desarrollo, y R1 y R2 son lanzamientos; los archivos .Rd están contenidos en la rama de lanzamiento.

Los otros problemas que mencionó podrían mitigarse con un enfoque similar a packrat . (Realmente usar packrat requeriría rstudio / packrat # 31.) Si bien esto parece excesivo solo para la tarea en cuestión, esto también permite una "actualización controlada" de las dependencias; consulte los comentarios en el tema vinculado.

Este número y el número 523 me están empezando a hacer pensar que tal vez deberíamos ofrecer esto como una opción ...

También me di cuenta de que otro posible problema del usuario final es que, al volver a documentar, las entradas en NAMESPACE pueden depender de qué paquetes están cargados actualmente. Esto es algo que he visto con métodos S3 y genéricos.

Creo que esto podría manejarse incluyendo algún código R en el árbol github, que es ejecutado por devtools::install_github (o más bien devtools::install en general).

Hay un par de preguntas sobre _cómo_:

• Dónde poner el código R. Esto probablemente sea simple, y podría ir a un archivo que build() ignora, por ejemplo, build_package.R .
• Cómo evitar el problema mencionado por @wch . Esto se puede hacer arreglando las versiones del paquete de construcción, por ejemplo, agregando un campo BuildDependencies a DESCRIPTION , que puede especificar la versión exacta del paquete que desea usar para la construcción. Ejemplos:

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

o incluso esto para depender de una versión exacta:

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

Esto también resolvería el problema que teníamos a veces cuando varios paquetes usan diferentes versiones de roxygen2, y luego varios desarrolladores también tienen varias versiones.

Acabo de leer este hilo y me di cuenta de que @hadley estaba sugiriendo esencialmente lo mismo desde el principio ...

Me alegra que la gente tenga tiempo para implementar esto, puedo ver el uso y entiendo que la gente tiene religión sobre el seguimiento de archivos compilados ...

Pero para la mayoría de los usuarios, la creación de archivos Rd localmente será una fuente de muchos errores intratables. Eso los llevará a molestar a los autores de los paquetes y a Hadley ... ¿Podría ser prudente recomendar de manera destacada el almacenamiento de los archivos .Rd preconstruidos si no son expertos en usar su paquete?

Esto es similar con los paquetes que necesitan compilación: en Windows, necesita Rtools. Creo que los usuarios no expertos no deberían tener que usar install_github en primer lugar, pero esto requiere cierta infraestructura, por ejemplo, como se describe en rpkg / rep .

Amén de evitar Rtools para usuarios de Windows. "CRAN 2.0" suena bien, aunque las estrictas comprobaciones que imponen aumentan la confianza en la integridad del código.

Creo que esto se maneja mejor en otro lugar. Actualmente, install_github() es una forma muy común de instalar paquetes y tener que ejecutar código adicional antes de la instalación agregará mucha complejidad.

¿Apoyaría un argumento document = TRUE por build() ?

Este antiguo problema se ha bloqueado automáticamente. Si cree que ha encontrado un problema relacionado, presente un nuevo problema (con reprex) y enlace a este problema. https://reprex.tidyverse.org/