0Pricing
R Academy · Lección

Estructura de paquetes con usethis y devtools

Cree la estructura de un directorio de paquete, DESCRIPTION y NAMESPACE con las funciones auxiliares de usethis.

Estructura de paquetes con usethis y devtools es una lección gratuita de R Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de R Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de R Academy incluye 4 lecciones en total.

¿Por qué crear un paquete de R?

Un paquete de R es la forma estándar de compartir código, datos y documentación reutilizables. Aunque nunca publique en CRAN, empaquetar su código impone buenas prácticas: funciones documentadas, pruebas unitarias y un espacio de nombres claro. devtools y usethis simplifican el proceso.

Crear la estructura básica de un paquete

usethis::create_package('~/mypackage') crea un directorio con todos los archivos necesarios: DESCRIPTION, NAMESPACE y un directorio R/. Abre automáticamente el nuevo proyecto en 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

El archivo DESCRIPTION

El archivo DESCRIPTION es el manifiesto del paquete. Sus campos principales son:

  • Title — descripción en una línea (en formato de título y sin punto)
  • Version — versión semántica (por ejemplo, 0.1.0)
  • Author / Authors@R — autor del paquete
  • Depends — versión de R requerida
  • Imports — paquetes que utiliza su paquete
  • License — por ejemplo, MIT o 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

Añadir funciones con use_r()

usethis::use_r('my_function') crea R/my_function.R y lo abre para editarlo. Cada archivo de R/ debe contener una función o un pequeño grupo de funciones estrechamente relacionadas. No utilice llamadas a source() dentro de los archivos del paquete.

# 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() — El ciclo de desarrollo

devtools::load_all() (atajo de teclado Ctrl+Shift+L en RStudio) simula la instalación y carga del paquete. Carga todos los archivos de R/ en la sesión actual sin instalar realmente el paquete. Este es el núcleo del ciclo de desarrollo 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() — La auditoría completa

devtools::check() (Ctrl+Shift+E) ejecuta R CMD check, el conjunto exhaustivo de comprobaciones utilizado por CRAN. Comprueba la documentación, las pruebas, los ejemplos, el espacio de nombres y mucho más. Procure obtener 0 ERRORs, 0 WARNINGs y el menor número posible de NOTEs.

# 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

Estructura del directorio R/

Todos los archivos de código fuente deben estar en R/. Convenciones habituales:

  • Un archivo por familia de funciones (por ejemplo, R/utils.R, R/plot_helpers.R)
  • R/data.R para la documentación de conjuntos de datos
  • R/zzz.R para los hooks .onLoad() y .onAttach()

No incluya subdirectorios dentro de R/; todos los archivos deben estar en el nivel superior.

# 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

El directorio man/

man/ contiene archivos de ayuda .Rd, uno por cada función exportada. Nunca debe editarlos manualmente; se generan a partir de los comentarios de roxygen2 mediante devtools::document(). Confírmelos junto con el código fuente.

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

El directorio tests/

usethis::use_testthat() crea el directorio tests/testthat/ y añade testthat a DESCRIPTION. Escriba archivos de prueba con nombres test-*.R dentro de ese directorio. Ejecute todas las pruebas 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')

Añadir dependencias correctamente

Nunca utilice library(pkg) dentro de los archivos de código fuente del paquete. En su lugar:

  • Añada el paquete a Imports en DESCRIPTION con usethis::use_package('dplyr')
  • Llame a las funciones con pkg::function() o añada @importFrom pkg function en roxygen2
  • Utilice Suggests para los paquetes que solo se necesiten en ejemplos o pruebas
# 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
# }

Resumen del flujo de trabajo de desarrollo de paquetes

El ciclo iterativo estándar para desarrollar paquetes de R:

  1. create_package() — crear la estructura básica una sola vez
  2. use_r('name') — crear un archivo de código fuente
  3. Escribir y documentar las funciones (roxygen2)
  4. load_all() — cargar el paquete en la sesión para realizar pruebas interactivas
  5. document() — volver a generar man/ y NAMESPACE
  6. test() — ejecutar las pruebas unitarias
  7. check() — ejecutar la comprobación completa de R CMD

Comprobación rápida: campos de DESCRIPTION

¿Qué campo de DESCRIPTION enumera los paquetes de R que su paquete utiliza directamente (dependencias estrictas)?

Repaso de la estructura de un paquete

Archivos y comandos clave para desarrollar paquetes de R:

  • usethis::create_package() — crear la estructura básica con DESCRIPTION, NAMESPACE y R/
  • DESCRIPTION — metadatos de Title, Version, Imports y License
  • usethis::use_r('name') — añadir un archivo de código fuente a R/
  • devtools::load_all() — recarga iterativa rápida (Ctrl+Shift+L)
  • devtools::document() — volver a generar man/ a partir de roxygen2
  • devtools::check() — comprobación completa de R CMD orientada a obtener 0 errores y 0 advertencias
  • Nunca incluya library() en el código fuente del paquete; utilice pkg::fn()

Preguntas frecuentes

¿La lección «Estructura de paquetes con usethis y devtools» es gratis?

Sí — el texto completo de «Estructura de paquetes con usethis y devtools» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de R Academy, actualiza a CoddyKit PRO. El curso de R Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Estructura de paquetes con usethis y devtools»?

Cree la estructura de un directorio de paquete, DESCRIPTION y NAMESPACE con las funciones auxiliares de usethis. Practicas R Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar R Academy?

No se requiere experiencia previa. R Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.

¿Cuánto tiempo toma la lección «Estructura de paquetes con usethis y devtools»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de R Academy?

Sí. Cada lección de R Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Estructura de paquetes con usethis y devtools
  2. Documentación de funciones con roxygen2
  3. Pruebas unitarias con testthat
  4. Envío a CRAN y mantenimiento de paquetes
← Volver a R Academy