0Pricing
R Academy · Урок

Структура пакета с usethis и devtools

Создавайте структуру каталога пакета, DESCRIPTION и NAMESPACE с помощью вспомогательных средств usethis

«Структура пакета с usethis и devtools» — бесплатный урок R Academy на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения R Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс R Academy содержит 4 уроков всего.

Зачем создавать пакет R?

Пакет R — стандартный способ делиться повторно используемым кодом, данными и документацией. Даже если Вы никогда не будете публиковать пакет в CRAN, упаковка кода помогает соблюдать хорошие практики: документировать функции, писать модульные тесты и поддерживать понятное пространство имён. devtools и usethis делают этот процесс простым.

Создание структуры пакета

usethis::create_package('~/mypackage') создаёт каталог со всеми необходимыми файлами: DESCRIPTION, NAMESPACE и каталогом R/. Новый проект автоматически открывается в 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

Файл DESCRIPTION

Файл DESCRIPTION — это манифест пакета. Его основные поля:

  • Title — однострочное описание (каждое слово с прописной буквы, без точки)
  • Version — семантическая версия (например, 0.1.0)
  • Author / Authors@R — автор пакета
  • Depends — требуемая версия R
  • Imports — пакеты, вызываемые Вашим пакетом
  • License — например, 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

Добавление функций с помощью use_r()

usethis::use_r('my_function') создаёт файл R/my_function.R и открывает его для редактирования. Каждый файл в R/ должен содержать одну функцию или небольшую группу тесно связанных функций. Не используйте вызовы source() внутри файлов пакета.

# 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() — цикл разработки

devtools::load_all() (сочетание клавиш Ctrl+Shift+L в RStudio) имитирует установку и загрузку пакета. Эта команда загружает все файлы из R/ в текущий сеанс, фактически не устанавливая пакет. Это основа итеративного цикла разработки.

# 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() — полная проверка

devtools::check() (Ctrl+Shift+E) запускает R CMD check — полный набор проверок, используемый CRAN. Команда проверяет документацию, тесты, примеры, пространство имён и многое другое. Стремитесь к 0 ERROR, 0 WARNING и как можно меньшему числу 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

Структура каталога R/

Все исходные файлы помещаются в R/. Распространённые соглашения:

  • Один файл на семейство функций (например, R/utils.R, R/plot_helpers.R)
  • R/data.R для документации наборов данных
  • R/zzz.R для обработчиков .onLoad() и .onAttach()

Внутри R/ не должно быть подкаталогов — все файлы находятся на верхнем уровне.

# 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

Каталог man/

Каталог man/ содержит справочные файлы .Rd — по одному для каждой экспортируемой функции. Никогда не редактируйте их вручную — они создаются из комментариев roxygen2 с помощью devtools::document(). Добавляйте их в систему контроля версий вместе с исходным кодом.

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

Каталог tests/

usethis::use_testthat() создаёт каталог tests/testthat/ и добавляет testthat в DESCRIPTION. Создавайте в этом каталоге файлы тестов с именами test-*.R. Запускайте все тесты с помощью 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')

Корректное добавление зависимостей

Никогда не используйте library(pkg) внутри исходных файлов пакета. Вместо этого:

  • Добавьте пакет в Imports файла DESCRIPTION с помощью usethis::use_package('dplyr')
  • Вызывайте функции через pkg::function() или добавьте @importFrom pkg function в roxygen2
  • Используйте Suggests для пакетов, необходимых только в примерах или тестах
# 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:

  1. create_package() — один раз создать структуру
  2. use_r('name') — создать исходный файл
  3. Написать и документировать функции (roxygen2)
  4. load_all() — загрузить пакет в сеанс для интерактивного тестирования
  5. document() — заново создать man/ и NAMESPACE
  6. test() — запустить модульные тесты
  7. check() — выполнить полную проверку R CMD

Быстрая проверка: поля DESCRIPTION

В каком поле DESCRIPTION перечислены пакеты R, которые Ваш пакет вызывает напрямую (жёсткие зависимости)?

Итоги по структуре пакета

Основные файлы и команды для разработки пакета R:

  • usethis::create_package() — создать структуру с DESCRIPTION, NAMESPACE, R/
  • DESCRIPTION — метаданные Title, Version, Imports, License
  • usethis::use_r('name') — добавить исходный файл в R/
  • devtools::load_all() — быстро перезагрузить пакет в ходе итеративной разработки (Ctrl+Shift+L)
  • devtools::document() — заново создать man/ из roxygen2
  • devtools::check() — выполнить полную проверку R CMD с целью получить 0 ошибок и предупреждений
  • Никогда не помещайте library() в исходный код пакета — используйте pkg::fn()

Часто задаваемые вопросы

Урок «Структура пакета с usethis и devtools» бесплатный?

Да — полный текст урока «Структура пакета с usethis и devtools» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс R Academy, подпишись на CoddyKit PRO. Курс R Academy содержит 4 уроков всего.

Чему я научусь в уроке «Структура пакета с usethis и devtools»?

Создавайте структуру каталога пакета, DESCRIPTION и NAMESPACE с помощью вспомогательных средств usethis Ты практикуешь R Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать R Academy?

Предыдущий опыт не требуется. R Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Структура пакета с usethis и devtools»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке R Academy?

Да. Каждый урок R Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Структура пакета с usethis и devtools
  2. Документирование функций с roxygen2
  3. Модульное тестирование с testthat
  4. Публикация в CRAN и сопровождение пакета
← Назад к R Academy