Devtools: Facultativement roxygéniser (ou exécuter le code R personnalisé) avant la construction

Je pense qu'il est important d'avoir un champ BuildDepends car cela peut être utilisé pour vérifier que vous avez (par exemple) la bonne version de roxygen2.

Dans ce cas, il n'est peut-être pas nécessaire de prendre en charge la syntaxe simple document = TRUE .

Je pense que la solution à tous les problèmes est qu'un référentiel sur github est utilisé à la fois pour la gestion des sources et la distribution des packages. Les fichiers Rd ne doivent jamais être suivis par git dans le référentiel source ; d'autre part, les fichiers Rd doivent être suivis et partagés via github dans le référentiel de packages.

Conceptuellement, nous avons quelque chose comme,

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

Je veux appeler l'action de src à package tant que build, mais build signifie quelque chose de différent dans R, alors appelons-le prebuild ici.

Une solution consiste à obtenir deux référentiels, un pour les fichiers source, tels que RPackageFoo-dev, et un pour la distribution de packages, tels que RPackageFoo. Ensuite, avec un script, tel qu'un git hook, nous pouvons mettre à jour automatiquement le référentiel de distribution du package. Avec un tel paramètre, tout le monde peut installer le package à partir du référentiel de packages sans aucun problème, et les développeurs, qui utilisent le référentiel source, doivent gérer eux-mêmes le processus de pré-construction. Le coût ici est que nous devons gérer deux référentiels, et certains utilisateurs et développeurs peuvent ne pas remarquer que le pkg a deux référentiels.

Une autre solution consiste à intégrer la pré-construction dans les outils de développement et à laisser les utilisateurs gérer eux-mêmes la pré-construction. Espérons que ce soit indolore pour les développeurs et les utilisateurs, avec l'aide de devtools. Pour que cela fonctionne vraiment comme prévu, la procédure de pré-construction doit être suffisamment simple pour être gérée par n'importe quelle machine, y compris Windows. Si devtools doivent gérer la dépendance du bâtiment et que les utilisateurs peuvent avoir à installer un tas de packages ou même différentes versions d'un package, alors il est trop complexe de pousser le travail aux utilisateurs, et les développeurs devraient le faire le levage de charges lourdes, si possible.

Ou, nous pouvons continuer à utiliser un référentiel pour la gestion de src et la distribution de pkg, et créer un script et configurer pour gérer facilement les fichiers "compilés" dans git. Je trouve l'article Traiter les fichiers compilés dans Git utile. Les configurations de base sont,

• définissez .gitattributes pour que git diff ignorent tous les fichiers compilés
• définir le pilote de fusion git afin que git merge utilise toujours la version locale des fichiers compilés
• définir git hook pour que les fichiers Rd soient mis à jour avant de les pousser vers github

Le piège potentiel est que le pilote git merge et le hook git ne peuvent pas être synchronisés par git et doivent être définis manuellement par tous les développeurs. La bonne nouvelle est, je suppose, qu'un réglage incorrect par un autre développeur ne gâchera pas votre référentiel. Un autre problème est que vous ne pourrez peut-être pas gérer la demande d'extraction sur github, car il ne prend pas en charge le lecteur de fusion. En fait, le seul moyen de s'assurer que les fichiers Rd sont correctement mis à jour est de les précompiler localement et de les envoyer à github. Je ne pense pas prévoir tous les problèmes possibles, car c'est en quelque sorte trop complexe pour moi.

La beauté de install_github est que vous pouvez installer n'importe quelle ref ou même pull request. Toute technique de mise en miroir devra fournir cela pour être d'utilisation équivalente.

Je suis d'accord que la pré-construction dans devtools doit être indolore pour l'utilisateur.

L'article sur le stockage des fichiers compilés est une bonne solution, mais la configuration est légèrement compliquée. Toutes les mises à jour des fichiers .Rd ne provoquent pas de conflit de fusion. Si un petit outil s'occupait de ces détails, super !

@hadley : Pouvons-nous nous mettre d'accord pour rendre la dépendance BuildDepends facultative pour build et install mais obligatoire pour check et release ? Je pense qu'autrement, l'exigence selon laquelle "la pré-construction doit être indolore pour l'utilisateur" ne peut pas être satisfaite facilement. C'est "seulement" de la documentation, si l'utilisateur en a besoin, il peut prendre les mesures appropriées pour s'assurer qu'elle est installée ; sinon, il n'est pas nécessaire d'interrompre l'installation car une dépendance est manquante.

Je jouais avec l'idée d'automatiser l'outil de construction et de déploiement pour travis-ci . Le référentiel du projet est disponible sur r-deploy-git . Il n'en est qu'à ses débuts et semble bien fonctionner avec mon package r factice . Au moins, ça montre que c'est faisable. Espérons qu'un script fiable sera disponible dans un proche avenir, avec l'aide de tous.

Pour devtools , je pense que ce serait une bonne idée d'avoir un moyen de distinguer un package "souce" et un package "prebuild". Pour un package "source", prebuild doit être appelé pour générer des fichiers, tels que des fichiers Rd, et les développeurs de pkg peuvent utiliser tous les outils qu'ils souhaitent, y compris make , car nous supposons que quiconque installe le package "src" en tant que développeurs ou utilisateurs expérimentés. Pour un package "préconstruit", il doit suivre la norme CRAN et peut être installé avec R CMD INSTALL .

Un problème avec l'exécution de document() dans le cadre du processus install_github() est que les fichiers .Rd résultants ne sont pas entièrement déterminés par le contenu de la source du package. Ils peuvent dépendre de packages externes, par exemple :

• Si vous utilisez @inheritParams partir de quelque chose d'un package différent, la version de ce package est importante. Parfois, la documentation change entre les versions. (C'est un problème que j'ai rencontré dans le passé.)
• Les fichiers .Rd de sortie dépendent de la version de roxygen2.

D'une part, vous pourriez penser que c'est une bonne chose, car ces modifications apportées aux packages externes n'entraînent pas de commits "supplémentaires" dans le code source de votre package. Mais d'un autre côté, il y a un gros problème : si vous publiez un package vers CRAN, il n'y a pas de commit qui correspond au contenu exact de ce qui est construit et envoyé au CRAN, car ce qui est envoyé dépend à la fois du code source et de l'écosystème R sur ton ordinateur.

Vous pouvez toujours maintenir une branche de versions "publiées" qui contient les fichiers roxygénés :

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

Ici, A jusqu'à G représentent la branche de développement, et R1 et R2 sont des versions ; les fichiers .Rd sont contenus dans la branche release.

Les autres problèmes que vous avez mentionnés pourraient être atténués par une approche de type packrat . (Utiliser réellement packrat nécessiterait rstudio/packrat#31.) Bien que cela semble exagéré uniquement pour la tâche à accomplir, cela permet également une "mise à niveau contrôlée" des dépendances - voir les commentaires dans le problème lié.

Ce numéro et #523 commencent à me faire penser que nous devrions peut-être proposer cela en option...

J'ai également réalisé qu'un autre problème possible pour l'utilisateur final est que, lors de la re-documentation, les entrées dans NAMESPACE peuvent dépendre des packages actuellement chargés. C'est quelque chose que j'ai vu avec les méthodes S3 et les génériques.

Je pense que cela pourrait être géré en incluant du code R dans l'arborescence github, qui est exécuté par devtools::install_github (ou plutôt devtools::install en général).

Il y a quelques questions sur le _comment_ :

• Où mettre le code R. C'est probablement simple, et cela pourrait simplement aller dans un fichier ignoré par build() , par exemple build_package.R .
• Comment éviter le problème mentionné par @wch . Cela peut être fait en corrigeant les versions du package de construction, par exemple en ajoutant un champ BuildDependencies à DESCRIPTION , qui peut spécifier la version exacte du package que vous souhaitez utiliser pour la construction. Exemples:

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

ou même ceci pour dépendre d'une version exacte :

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

Cela résoudrait également le problème que nous rencontrions parfois lorsque divers packages utilisent différentes versions de roxygen2, et que divers développeurs ont également différentes versions.

Je viens de relire ce fil et je me suis rendu compte que @hadley suggérait essentiellement la même chose au tout début ......

Heureux si les gens ont le temps de mettre en œuvre cela, je peux voir l'utilité et je comprends que les gens ont une religion sur le suivi des fichiers construits...

Mais pour la plupart des utilisateurs, la création de fichiers Rd localement sera une source de nombreuses erreurs insolubles. Cela les amènera alors à embêter les auteurs de packages et Hadley... Il serait peut-être sage de recommander en évidence de stocker les fichiers .Rd pré-construits si des non-experts utilisent votre package ?

C'est similaire avec les packages qui nécessitent une compilation : Sous Windows, vous avez besoin de Rtools. Je pense que les utilisateurs non experts ne devraient pas avoir à utiliser install_github en premier lieu, mais cela nécessite une certaine infrastructure, par exemple, comme indiqué dans rpkg/rep .

amen à éviter Rtools pour les utilisateurs de Windows. "CRAN 2.0" sonne bien, bien que la vérification sévère qu'ils imposent renforce la confiance en l'intégrité du code.

Je pense que c'est mieux géré ailleurs. Actuellement, install_github() est un moyen très courant d'installer des packages et devoir exécuter du code supplémentaire avant l'installation va ajouter beaucoup de complexité.

Souhaitez-vous soutenir un argument document = TRUE pour build() ?

Cet ancien problème a été automatiquement verrouillé. Si vous pensez avoir trouvé un problème connexe, veuillez déposer un nouveau problème (avec reprex) et créer un lien vers ce problème. https://reprex.tidyverse.org/