0Pricing
R Academy · Aula

Estrutura de pacotes com usethis e devtools

Crie a estrutura de um diretório de pacote, DESCRIPTION e NAMESPACE com os auxiliares do usethis.

Estrutura de pacotes com usethis e devtools é uma aula grátis de R Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de R Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de R Academy inclui 4 aulas no total.

Por que criar um pacote R?

Um pacote R é a forma padrão de compartilhar código, dados e documentação reutilizáveis. Mesmo que você nunca publique no CRAN, empacotar seu código impõe boas práticas: funções documentadas, testes unitários e um espaço de nomes claro. devtools e usethis tornam o processo simples.

Criando a estrutura básica de um pacote

usethis::create_package('~/mypackage') cria um diretório com todos os arquivos necessários: DESCRIPTION, NAMESPACE e um diretório R/. O novo projeto é aberto automaticamente no 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

O arquivo DESCRIPTION

O arquivo DESCRIPTION é o manifesto do pacote. Seus principais campos são:

  • Title — descrição em uma linha (em formato de título, sem ponto final)
  • Version — versão semântica (por exemplo, 0.1.0)
  • Author / Authors@R — autor do pacote
  • Depends — versão necessária do R
  • Imports — pacotes chamados pelo seu pacote
  • License — por exemplo, 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

Adicionando funções com use_r()

usethis::use_r('my_function') cria R/my_function.R e o abre para edição. Cada arquivo em R/ deve conter uma função ou um pequeno grupo de funções estreitamente relacionadas. Não use chamadas a source() dentro dos arquivos do pacote.

# 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() — O ciclo de desenvolvimento

devtools::load_all() (atalho de teclado Ctrl+Shift+L no RStudio) simula a instalação e o carregamento do pacote. Ele carrega todos os arquivos de R/ na sessão atual sem realizar uma instalação de fato. Esse é o núcleo do ciclo de desenvolvimento 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() — A auditoria completa

devtools::check() (Ctrl+Shift+E) executa R CMD check — o conjunto abrangente de verificações usado pelo CRAN. Ele verifica a documentação, os testes, os exemplos, o espaço de nomes e muito mais. Procure obter 0 ERROs, 0 AVISOs e o menor número possível de NOTAs.

# 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

A estrutura do diretório R/

Todos os arquivos de código-fonte devem ficar em R/. Convenções comuns:

  • Um arquivo por família de funções (por exemplo, R/utils.R, R/plot_helpers.R)
  • R/data.R para a documentação de conjuntos de dados
  • R/zzz.R para os ganchos .onLoad() e .onAttach()

Não use subdiretórios dentro de R/ — todos os arquivos ficam no nível 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

O diretório man/

man/ contém arquivos de ajuda .Rd, um para cada função exportada. Você nunca deve editá-los manualmente — eles são gerados a partir dos comentários do roxygen2 por devtools::document(). Faça o commit deles junto com o código-fonte.

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

O diretório tests/

usethis::use_testthat() cria o diretório tests/testthat/ e adiciona testthat a DESCRIPTION. Escreva arquivos de teste com nomes como test-*.R dentro desse diretório. Execute todos os testes com 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')

Adicionando dependências corretamente

Nunca use library(pkg) dentro dos arquivos de código-fonte do pacote. Em vez disso:

  • Adicione o pacote a Imports em DESCRIPTION com usethis::use_package('dplyr')
  • Chame as funções com pkg::function() ou adicione @importFrom pkg function ao roxygen2
  • Use Suggests para pacotes necessários apenas em exemplos ou testes
# 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
# }

Resumo do fluxo de desenvolvimento de um pacote

O ciclo iterativo padrão para o desenvolvimento de pacotes R:

  1. create_package() — criar a estrutura básica uma vez
  2. use_r('name') — criar um arquivo de código-fonte
  3. Escrever e documentar as funções (roxygen2)
  4. load_all() — carregar na sessão para testes interativos
  5. document() — regenerar man/ e NAMESPACE
  6. test() — executar os testes unitários
  7. check() — executar a verificação completa R CMD check

Verificação rápida: campos de DESCRIPTION

Qual campo de DESCRIPTION lista os pacotes R chamados diretamente pelo seu pacote (dependências obrigatórias)?

Recapitulação da estrutura de um pacote

Principais arquivos e comandos para o desenvolvimento de pacotes R:

  • usethis::create_package() — criar a estrutura básica com DESCRIPTION, NAMESPACE, R/
  • DESCRIPTION — metadados Title, Version, Imports, License
  • usethis::use_r('name') — adicionar um arquivo de código-fonte a R/
  • devtools::load_all() — recarregar rapidamente de forma iterativa (Ctrl+Shift+L)
  • devtools::document() — regenerar man/ a partir do roxygen2
  • devtools::check() — verificação completa R CMD check, buscando 0 erros/avisos
  • Nunca coloque library() no código-fonte do pacote — use pkg::fn()

Perguntas Frequentes

A aula “Estrutura de pacotes com usethis e devtools” é grátis?

Sim — o texto completo de “Estrutura de pacotes com usethis e devtools” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de R Academy, atualize para CoddyKit PRO. O curso de R Academy inclui 4 aulas no total.

O que vou aprender em “Estrutura de pacotes com usethis e devtools”?

Crie a estrutura de um diretório de pacote, DESCRIPTION e NAMESPACE com os auxiliares do usethis. Você pratica R Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar R Academy?

Nenhuma experiência prévia é necessária. R Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Estrutura de pacotes com usethis e devtools”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de R Academy?

Sim. Cada aula de R Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Estrutura de pacotes com usethis e devtools
  2. Documentando funções com roxygen2
  3. Testes unitários com testthat
  4. Submissão ao CRAN e manutenção de pacotes
← Voltar para R Academy