0Pricing
R Academy · Lezione

Struttura dei pacchetti con usethis e devtools

Crei la struttura della directory del pacchetto, DESCRIPTION e NAMESPACE con gli helper di usethis

Struttura dei pacchetti con usethis e devtools è una lezione R Academy gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento R Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso R Academy include 4 lezioni in totale.

Perché creare un pacchetto R?

Un pacchetto R è il modo standard per condividere codice, dati e documentazione riutilizzabili. Anche se non pubblicherà mai il pacchetto su CRAN, organizzare il codice in un pacchetto impone buone pratiche: funzioni documentate, test unitari e uno spazio dei nomi chiaro. devtools e usethis rendono il processo semplice.

Creazione della struttura di base di un pacchetto

usethis::create_package('~/mypackage') crea una directory con tutti i file necessari: DESCRIPTION, NAMESPACE e una directory R/. Apre automaticamente il nuovo progetto in 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

Il file DESCRIPTION

Il file DESCRIPTION è il manifesto del pacchetto. I campi principali sono:

  • Title — descrizione su una riga (in stile titolo, senza punto)
  • Version — versione semantica (ad esempio 0.1.0)
  • Author / Authors@R — autore del pacchetto
  • Depends — versione richiesta di R
  • Imports — pacchetti chiamati dal pacchetto
  • License — ad esempio 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

Aggiunta di funzioni con use_r()

usethis::use_r('my_function') crea R/my_function.R e lo apre per la modifica. Ogni file in R/ dovrebbe contenere una funzione o un piccolo gruppo di funzioni strettamente correlate. Non usi chiamate a source() nei file del pacchetto.

# 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() — Il ciclo di sviluppo

devtools::load_all() (scorciatoia da tastiera Ctrl+Shift+L in RStudio) simula l'installazione e il caricamento del pacchetto. Carica tutti i file in R/ nella sessione corrente senza installarli realmente. Questo costituisce il fulcro del ciclo di sviluppo iterativo.

# 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 completo

devtools::check() (Ctrl+Shift+E) esegue R CMD check — la suite completa utilizzata da CRAN. Controlla documentazione, test, esempi, spazio dei nomi e altro. Punti a ottenere 0 ERROR, 0 WARNING e il minor numero possibile di 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 struttura della directory R/

Tutti i file sorgente vanno inseriti in R/. Convenzioni comuni:

  • Un file per ogni famiglia di funzioni (ad esempio R/utils.R, R/plot_helpers.R)
  • R/data.R per la documentazione dei dataset
  • R/zzz.R per gli hook .onLoad() e .onAttach()

Nessuna sottodirectory all'interno di R/: tutti i file si trovano al livello superiore.

# 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

La directory man/

man/ contiene i file della guida .Rd, uno per ogni funzione esportata. Non deve mai modificarli manualmente: vengono generati dai commenti roxygen2 tramite devtools::document(). Esegua il commit insieme al codice sorgente.

# 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
')

La directory tests/

usethis::use_testthat() crea la directory tests/testthat/ e aggiunge testthat a DESCRIPTION. Scriva nella directory file di test denominati test-*.R. Esegua tutti i test con 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')

Aggiunta corretta delle dipendenze

Non usi mai library(pkg) nei file sorgente del pacchetto. Proceda invece nel modo seguente:

  • Aggiunga il pacchetto a Imports in DESCRIPTION con usethis::use_package('dplyr')
  • Chiami le funzioni con pkg::function() oppure aggiunga @importFrom pkg function in roxygen2
  • Usi Suggests per i pacchetti necessari solo negli esempi o nei test
# 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
# }

Riepilogo del flusso di sviluppo di un pacchetto

Il ciclo iterativo standard per lo sviluppo di pacchetti R:

  1. create_package() — crea la struttura di base una sola volta
  2. use_r('name') — crea un file sorgente
  3. Scriva e documenti le funzioni (roxygen2)
  4. load_all() — carica il pacchetto nella sessione per i test interattivi
  5. document() — rigenera man/ e NAMESPACE
  6. test() — esegue i test unitari
  7. check() — esegue il controllo completo R CMD check

Verifica rapida: campi di DESCRIPTION

Quale campo di DESCRIPTION elenca i pacchetti R chiamati direttamente dal pacchetto (dipendenze forti)?

Riepilogo della struttura del pacchetto

File e comandi principali per lo sviluppo di pacchetti R:

  • usethis::create_package() — crea la struttura di base con DESCRIPTION, NAMESPACE, R/
  • DESCRIPTION — metadati Title, Version, Imports, License
  • usethis::use_r('name') — aggiunge un file sorgente a R/
  • devtools::load_all() — ricaricamento iterativo rapido (Ctrl+Shift+L)
  • devtools::document() — rigenera man/ da roxygen2
  • devtools::check() — esegue il controllo completo R CMD check puntando a zero errori e avvisi
  • Non inserisca library() nel codice sorgente del pacchetto: usi pkg::fn()

Domande Frequenti

La lezione «Struttura dei pacchetti con usethis e devtools» è gratuita?

Sì — il testo completo di «Struttura dei pacchetti con usethis e devtools» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso R Academy, passa a CoddyKit PRO. Il corso R Academy include 4 lezioni in totale.

Cosa imparerò in «Struttura dei pacchetti con usethis e devtools»?

Crei la struttura della directory del pacchetto, DESCRIPTION e NAMESPACE con gli helper di usethis Eserciti R Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare R Academy?

Non è richiesta alcuna esperienza precedente. R Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «Struttura dei pacchetti con usethis e devtools»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione R Academy?

Sì. Ogni lezione R Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Struttura dei pacchetti con usethis e devtools
  2. Documentazione delle funzioni con roxygen2
  3. Test unitari con testthat
  4. Invio a CRAN e manutenzione dei pacchetti
← Torna a R Academy