0Pricing
R Academy · Lekcja

Struktura pakietu za pomocą usethis i devtools

Utwórz szkielet katalogu pakietu, pliki DESCRIPTION i NAMESPACE za pomocą funkcji pomocniczych usethis.

Struktura pakietu za pomocą usethis i devtools to bezpłatna lekcja R Academy na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej R Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs R Academy zawiera 4 lekcji w sumie.

Dlaczego warto utworzyć pakiet R?

Pakiet R to standardowy sposób udostępniania wielokrotnie używanego kodu, danych i dokumentacji. Nawet jeśli nigdy nie opublikują Państwo pakietu w CRAN, spakowanie kodu wymusza stosowanie dobrych praktyk: udokumentowanych funkcji, testów jednostkowych i przejrzystej przestrzeni nazw. devtools i usethis upraszczają ten proces.

Tworzenie szkieletu pakietu

usethis::create_package('~/mypackage') tworzy katalog zawierający wszystkie wymagane pliki: DESCRIPTION, NAMESPACE oraz katalog R/. Nowy projekt jest automatycznie otwierany w 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

Plik DESCRIPTION

Plik DESCRIPTION to manifest pakietu. Jego najważniejsze pola:

  • Title — jednozdaniowy opis (każde słowo wielką literą, bez kropki)
  • Version — wersja semantyczna (np. 0.1.0)
  • Author / Authors@R — autor pakietu
  • Depends — wymagana wersja R
  • Imports — pakiety, których funkcje wywołuje Państwa pakiet
  • License — np. 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

Dodawanie funkcji za pomocą use_r()

usethis::use_r('my_function') tworzy plik R/my_function.R i otwiera go do edycji. Każdy plik w katalogu R/ powinien zawierać jedną funkcję lub niewielką grupę ściśle powiązanych funkcji. W plikach pakietu nie należy używać wywołań 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() — cykl tworzenia pakietu

devtools::load_all() (skrót klawiaturowy Ctrl+Shift+L w RStudio) symuluje instalowanie i ładowanie pakietu. Wczytuje wszystkie pliki z katalogu R/ do bieżącej sesji bez faktycznego instalowania pakietu. To podstawa iteracyjnego cyklu tworzenia pakietu.

# 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() — pełny audyt

devtools::check() (Ctrl+Shift+E) uruchamia R CMD check — kompleksowy zestaw kontroli używany przez CRAN. Sprawdza dokumentację, testy, przykłady, przestrzeń nazw i wiele innych elementów. Należy dążyć do uzyskania 0 błędów ERROR, 0 ostrzeżeń WARNING oraz możliwie małej liczby komunikatów 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

Struktura katalogu R/

Wszystkie pliki źródłowe należy umieszczać w katalogu R/. Typowe konwencje:

  • Jeden plik na rodzinę funkcji (np. R/utils.R, R/plot_helpers.R)
  • R/data.R na dokumentację zbiorów danych
  • R/zzz.R na funkcje .onLoad() i .onAttach()

W katalogu R/ nie należy tworzyć podkatalogów — wszystkie pliki powinny znajdować się na najwyższym poziomie.

# 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

Katalog man/

Katalog man/ zawiera pliki pomocy .Rd, po jednym dla każdej eksportowanej funkcji. Nigdy nie należy edytować ich ręcznie — są generowane z komentarzy roxygen2 przez devtools::document(). Pliki te należy zatwierdzać w repozytorium razem z kodem źródłowym.

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

Katalog tests/

usethis::use_testthat() tworzy katalog tests/testthat/ i dodaje testthat do sekcji DESCRIPTION. Pliki testów o nazwach test-*.R należy umieszczać w tym katalogu. Wszystkie testy można uruchomić za pomocą 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')

Prawidłowe dodawanie zależności

W plikach źródłowych pakietu nigdy nie należy używać library(pkg). Zamiast tego:

  • Należy dodać pakiet do sekcji Imports w pliku DESCRIPTION za pomocą usethis::use_package('dplyr')
  • Wywoływać funkcje za pomocą pkg::function() lub dodać @importFrom pkg function w roxygen2
  • Używać sekcji Suggests dla pakietów potrzebnych wyłącznie w przykładach lub testach
# 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
# }

Podsumowanie procesu tworzenia pakietu

Standardowy iteracyjny cykl tworzenia pakietu R:

  1. create_package() — jednorazowe utworzenie szkieletu
  2. use_r('name') — utworzenie pliku źródłowego
  3. Napisanie i udokumentowanie funkcji (roxygen2)
  4. load_all() — wczytanie pakietu do sesji w celu interaktywnego testowania
  5. document() — ponowne wygenerowanie katalogu man/ i pliku NAMESPACE
  6. test() — uruchomienie testów jednostkowych
  7. check() — pełne sprawdzenie za pomocą R CMD check

Szybkie sprawdzenie: pola DESCRIPTION

W którym polu DESCRIPTION znajdują się pakiety R, których Państwa pakiet bezpośrednio używa (twarde zależności)?

Podsumowanie struktury pakietu

Najważniejsze pliki i polecenia związane z tworzeniem pakietów R:

  • usethis::create_package() — tworzy szkielet z plikami DESCRIPTION, NAMESPACE i katalogiem R/
  • DESCRIPTION — metadane Title, Version, Imports i License
  • usethis::use_r('name') — dodaje plik źródłowy do katalogu R/
  • devtools::load_all() — szybkie iteracyjne ponowne wczytanie (Ctrl+Shift+L)
  • devtools::document() — ponownie generuje katalog man/ z roxygen2
  • devtools::check() — pełne sprawdzenie R CMD check, którego celem jest 0 błędów i ostrzeżeń
  • Nie należy umieszczać library() w kodzie źródłowym pakietu — należy używać pkg::fn()

Często zadawane pytania

Czy lekcja „Struktura pakietu za pomocą usethis i devtools” jest bezpłatna?

Tak — pełny tekst „Struktura pakietu za pomocą usethis i devtools” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu R Academy, przejdź na CoddyKit PRO. Kurs R Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Struktura pakietu za pomocą usethis i devtools”?

Utwórz szkielet katalogu pakietu, pliki DESCRIPTION i NAMESPACE za pomocą funkcji pomocniczych usethis. Ćwiczysz R Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć R Academy?

Nie wymagamy żadnego doświadczenia. R Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.

Ile czasu zajmuje lekcja „Struktura pakietu za pomocą usethis i devtools”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji R Academy?

Tak. Każda lekcja R Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Struktura pakietu za pomocą usethis i devtools
  2. Dokumentowanie funkcji za pomocą roxygen2
  3. Testy jednostkowe za pomocą testthat
  4. Przesyłanie pakietu do CRAN i jego utrzymanie
← Powrót do R Academy