0Pricing
R Academy · Leçon

Structure d’un paquet avec usethis et devtools

Créez l’ossature du répertoire d’un paquet, ainsi que DESCRIPTION et NAMESPACE, avec les assistants d’usethis.

Structure d’un paquet avec usethis et devtools est une leçon R Academy gratuite sur CoddyKit. Ceci est la leçon 1 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage R Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours R Academy comprend 4 leçons au total.

Pourquoi créer un package R ?

Un package R est la méthode standard pour partager du code, des données et de la documentation réutilisables. Même si vous ne publiez jamais votre package sur CRAN, le fait de regrouper votre code en package impose de bonnes pratiques : des fonctions documentées, des tests unitaires et un espace de noms clair. devtools et usethis simplifient le processus.

Créer l’ossature d’un package

usethis::create_package('~/mypackage') crée un répertoire contenant tous les fichiers requis : DESCRIPTION, NAMESPACE et un répertoire R/. Le nouveau projet s’ouvre automatiquement dans RStudio.

# library(usethis)
# library(devtools)
#
# usethis::create_package('~/mypackage')
#
# Creates:
# mypackage/
#   DESCRIPTION     <- package metadata
#   NAMESPACE       <- exported symbols (auto-managed by roxygen2)
#   R/              <- your R source files
#   .Rbuildignore   <- files to exclude from package builds

Le fichier DESCRIPTION

Le fichier DESCRIPTION est le manifeste du package. Ses principaux champs sont les suivants :

  • Titre — description sur une ligne (casse de titre, sans point)
  • Version — version sémantique (par exemple 0.1.0)
  • Auteur / Authors@R — auteur du package
  • Depends — version de R requise
  • Imports — packages appelés par votre package
  • License — par exemple MIT, GPL-3
# DESCRIPTION example:
# Package: mypackage
# Title: Tools for Analyzing Survey Data
# Version: 0.1.0
# Authors@R: person('Alice', 'Smith', email='alice@example.com', role=c('aut','cre'))
# Description: Provides helper functions for cleaning and summarizing survey responses.
# Depends: R (>= 4.1.0)
# Imports: dplyr, stringr
# License: MIT + file LICENSE

Ajouter des fonctions avec use_r()

usethis::use_r('my_function') crée R/my_function.R et l’ouvre pour modification. Chaque fichier de R/ doit contenir une fonction ou un petit groupe de fonctions étroitement liées. N’utilisez pas d’appels à source() dans les fichiers du package.

# usethis::use_r('add')  # creates R/add.R
#
# Write your function in R/add.R:
# add <- function(x, y) {
#   if (!is.numeric(x) || !is.numeric(y)) stop('x and y must be numeric')
#   x + y
# }
#
# Then document it with roxygen2 comments above the function.

devtools::load_all() — La boucle de développement

devtools::load_all() (raccourci clavier Ctrl+Shift+L dans RStudio) simule l’installation et le chargement du package. Cette commande source tous les fichiers de R/ dans la session actuelle sans effectuer réellement l’installation. C’est le cœur du cycle de développement itératif.

# Development loop:
# 1. Edit R/add.R
# 2. devtools::load_all()   # Ctrl+Shift+L
# 3. add(2, 3)              # test interactively
# 4. Go to step 1
#
# load_all() is much faster than install.packages()
# because it skips compilation and installation steps.

devtools::check() — L’audit complet

devtools::check() (Ctrl+Shift+E) exécute R CMD check — la suite complète utilisée par CRAN. Elle vérifie la documentation, les tests, les exemples, l’espace de noms et bien plus encore. Visez 0 ERROR, 0 WARNING et le moins possible de NOTE.

# devtools::check()  # runs R CMD check
#
# Common errors to fix:
# ERROR:   Undocumented function 'add' => add roxygen2 docs
# WARNING: No NAMESPACE file => run devtools::document()
# NOTE:    No examples => add @examples in roxygen2
# NOTE:    Dependencies in DESCRIPTION not used => clean up Imports

La structure du répertoire R/

Tous les fichiers sources vont dans R/. Conventions courantes :

  • Un fichier par famille de fonctions (par exemple R/utils.R, R/plot_helpers.R)
  • R/data.R pour la documentation des jeux de données
  • R/zzz.R pour les points d’ancrage .onLoad() et .onAttach()

Aucun sous-répertoire dans R/ : tous les fichiers se trouvent au premier niveau.

# Typical R/ directory for a small package:
# R/
#   add.R          <- add() function + documentation
#   subtract.R     <- subtract() function
#   utils.R        <- internal helpers (not exported)
#   data.R         <- documentation for bundled datasets
#   package.R      <- @docType package documentation

Le répertoire man/

man/ contient des fichiers d’aide .Rd, un par fonction exportée. Vous ne devez jamais les modifier manuellement : ils sont générés à partir des commentaires roxygen2 par devtools::document(). Validez-les avec vos fichiers sources.

# man/ is auto-generated:
# man/
#   add.Rd         <- generated from @title, @param etc. in R/add.R
#   subtract.Rd    <- generated from R/subtract.R
#
# Regenerate with:
# devtools::document()  # also updates NAMESPACE
#
# Never edit .Rd files directly -- changes will be overwritten
cat('Always edit roxygen2 comments, never man/*.Rd files directly
')

Le répertoire tests/

usethis::use_testthat() crée le répertoire tests/testthat/ et ajoute testthat à DESCRIPTION. Écrivez dans ce répertoire des fichiers de test nommés test-*.R. Exécutez tous les tests avec devtools::test() (Ctrl+Shift+T).

# Set up testing:
# usethis::use_testthat()
#
# Creates:
# tests/
#   testthat.R            <- runner script (do not edit)
#   testthat/
#     test-add.R          <- your test file
#
# Run tests:
# devtools::test()
# devtools::test_file('tests/testthat/test-add.R')

Ajouter correctement des dépendances

N’utilisez jamais library(pkg) dans les fichiers sources du package. À la place :

  • Ajoutez le package à Imports dans DESCRIPTION avec usethis::use_package('dplyr')
  • Appelez les fonctions avec pkg::function() ou ajoutez @importFrom pkg function dans roxygen2
  • Utilisez Suggests pour les packages nécessaires uniquement dans les exemples ou les tests
# Add a dependency:
# usethis::use_package('stringr')           # adds to Imports
# usethis::use_package('ggplot2', 'Suggests') # adds to Suggests
#
# In R/my_function.R:
# clean_names <- function(x) {
#   stringr::str_to_lower(stringr::str_trim(x))  # use pkg:: prefix
# }

Résumé du flux de développement d’un package

Le cycle itératif standard du développement d’un package R :

  1. create_package() — créer l’ossature une seule fois
  2. use_r('name') — créer un fichier source
  3. Écrire et documenter les fonctions (roxygen2)
  4. load_all() — charger le package dans la session pour effectuer des tests interactifs
  5. document() — régénérer man/ et NAMESPACE
  6. test() — exécuter les tests unitaires
  7. check() — effectuer la vérification complète avec R CMD check

Vérification rapide : champs de DESCRIPTION

Quel champ de DESCRIPTION répertorie les packages R appelés directement par votre package (dépendances obligatoires) ?

Récapitulatif de la structure d’un package

Principaux fichiers et commandes pour développer un package R :

  • usethis::create_package() — créer l’ossature avec DESCRIPTION, NAMESPACE et R/
  • DESCRIPTION — métadonnées Title, Version, Imports et License
  • usethis::use_r('name') — ajouter un fichier source à R/
  • devtools::load_all() — recharger rapidement le package de manière itérative (Ctrl+Shift+L)
  • devtools::document() — régénérer man/ à partir de roxygen2
  • devtools::check() — vérification complète avec R CMD check, en visant 0 erreur et 0 avertissement
  • Ne mettez jamais library() dans les sources du package : utilisez pkg::fn()

Questions Fréquemment Posées

La leçon « Structure d’un paquet avec usethis et devtools » est-elle gratuite ?

Oui — le texte complet de « Structure d’un paquet avec usethis et devtools » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours R Academy, passe à CoddyKit PRO. Le cours R Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Structure d’un paquet avec usethis et devtools » ?

Créez l’ossature du répertoire d’un paquet, ainsi que DESCRIPTION et NAMESPACE, avec les assistants d’usethis. Tu pratiques R Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer R Academy ?

Aucune expérience préalable n'est requise. R Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 1 sur 4.

Combien de temps prend la leçon « Structure d’un paquet avec usethis et devtools » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon R Academy ?

Oui. Chaque leçon R Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

  1. Structure d’un paquet avec usethis et devtools
  2. Documenter des fonctions avec roxygen2
  3. Tests unitaires avec testthat
  4. Soumission à CRAN et maintenance des paquets
← Retour à R Academy