0Pricing
R Academy · Lektion

Paketstruktur mit usethis und devtools

Erstellen Sie mit usethis-Hilfsfunktionen ein Paketverzeichnis sowie DESCRIPTION und NAMESPACE

Paketstruktur mit usethis und devtools ist eine kostenlose R Academy-Lektion auf CoddyKit. Dies ist Lektion 1 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des R Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der R Academy-Kurs umfasst insgesamt 4 Lektionen.

Warum ein R-Paket erstellen?

Ein R-Paket ist die Standardmethode, um wiederverwendbaren Code, Daten und Dokumentation zu teilen. Auch wenn Sie nie auf CRAN veröffentlichen, sorgt das Verpacken Ihres Codes für gute Praktiken: dokumentierte Funktionen, Unit-Tests und einen klaren Namespace. devtools und usethis machen den Prozess unkompliziert.

Ein Paketgerüst erstellen

usethis::create_package('~/mypackage') erstellt ein Verzeichnis mit allen erforderlichen Dateien: DESCRIPTION, NAMESPACE und einem Verzeichnis R/. Das neue Projekt wird automatisch in RStudio geöffnet.

# 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

Die Datei DESCRIPTION

Die Datei DESCRIPTION ist das Paketmanifest. Ihre wichtigsten Felder:

  • Title — einzeilige Beschreibung (in Title Case, ohne Punkt)
  • Version — semantische Version (z. B. 0.1.0)
  • Author / Authors@R — Autor des Pakets
  • Depends — erforderliche R-Version
  • Imports — Pakete, die Ihr Paket aufruft
  • License — z. B. 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

Funktionen mit use_r() hinzufügen

usethis::use_r('my_function') erstellt R/my_function.R und öffnet die Datei zur Bearbeitung. Jede Datei in R/ sollte eine einzelne Funktion oder eine kleine Gruppe eng verwandter Funktionen enthalten. Verwenden Sie in Paketdateien keine Aufrufe von 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() — Der Entwicklungszyklus

devtools::load_all() (Tastenkürzel Strg+Umschalt+L in RStudio) simuliert die Installation und das Laden des Pakets. Der Befehl lädt alle Dateien in R/ in die aktuelle Sitzung, ohne das Paket tatsächlich zu installieren. Dies ist der Kern des iterativen Entwicklungszyklus.

# 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() — Die vollständige Prüfung

devtools::check() (Strg+Umschalt+E) führt R CMD check aus — die umfassende Testsuite, die von CRAN verwendet wird. Dabei werden Dokumentation, Tests, Beispiele, Namespace und vieles mehr geprüft. Streben Sie 0 ERRORs, 0 WARNINGs und so wenige NOTEs wie möglich an.

# 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

Die Verzeichnisstruktur von R/

Alle Quelldateien gehören in R/. Übliche Konventionen:

  • Eine Datei pro Funktionsgruppe (z. B. R/utils.R, R/plot_helpers.R)
  • R/data.R für die Dokumentation von Datensätzen
  • R/zzz.R für .onLoad()- und .onAttach()-Hooks

Keine Unterverzeichnisse innerhalb von R/ — alle Dateien liegen direkt dort.

# 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

Das Verzeichnis man/

man/ enthält .Rd-Hilfedateien, eine pro exportierter Funktion. Sie sollten diese niemals manuell bearbeiten — sie werden aus roxygen2-Kommentaren durch devtools::document() generiert. Committen Sie sie zusammen mit Ihrem Quellcode.

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

Das Verzeichnis tests/

usethis::use_testthat() erstellt das Verzeichnis tests/testthat/ und fügt testthat zu DESCRIPTION hinzu. Schreiben Sie Testdateien mit dem Namen test-*.R in dieses Verzeichnis. Führen Sie alle Tests mit devtools::test() (Strg+Umschalt+T) aus.

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

Abhängigkeiten korrekt hinzufügen

Verwenden Sie niemals library(pkg) in Quelldateien eines Pakets. Stattdessen:

  • Fügen Sie das Paket mit usethis::use_package('dplyr') in DESCRIPTION unter Imports hinzu
  • Rufen Sie Funktionen mit pkg::function() auf oder ergänzen Sie @importFrom pkg function in roxygen2
  • Verwenden Sie Suggests für Pakete, die nur in Beispielen oder Tests benötigt werden
# 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
# }

Zusammenfassung des Paketentwicklungs-Workflows

Der standardmäßige iterative Zyklus für die Entwicklung von R-Paketen:

  1. create_package() — einmalig das Gerüst erstellen
  2. use_r('name') — eine Quelldatei erstellen
  3. Funktionen schreiben und dokumentieren (roxygen2)
  4. load_all() — für interaktive Tests in die Sitzung laden
  5. document() — man/ und NAMESPACE neu generieren
  6. test() — Unit-Tests ausführen
  7. check() — vollständige R-CMD-Prüfung

Schnelltest: DESCRIPTION-Felder

Welches DESCRIPTION-Feld führt die R-Pakete auf, die Ihr Paket direkt aufruft (harte Abhängigkeiten)?

Rückblick auf die Paketstruktur

Wichtige Dateien und Befehle für die Entwicklung von R-Paketen:

  • usethis::create_package() — Gerüst mit DESCRIPTION, NAMESPACE und R/ erstellen
  • DESCRIPTION — Metadaten zu Title, Version, Imports und License
  • usethis::use_r('name') — eine Quelldatei zu R/ hinzufügen
  • devtools::load_all() — schnelles iteratives Neuladen (Strg+Umschalt+L)
  • devtools::document() — man/ aus roxygen2 neu generieren
  • devtools::check() — vollständige R-CMD-Prüfung mit dem Ziel von 0 Fehlern und 0 Warnungen
  • Platzieren Sie niemals library() im Paketquellcode — verwenden Sie pkg::fn()

Häufig gestellte Fragen

Ist die Lektion „Paketstruktur mit usethis und devtools“ kostenlos?

Ja — der vollständige Text von „Paketstruktur mit usethis und devtools“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des R Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der R Academy-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Paketstruktur mit usethis und devtools“?

Erstellen Sie mit usethis-Hilfsfunktionen ein Paketverzeichnis sowie DESCRIPTION und NAMESPACE Du übst R Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um R Academy zu starten?

Keine Vorkenntnisse erforderlich. R Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 1 von 4.

Wie lange dauert die Lektion „Paketstruktur mit usethis und devtools“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser R Academy-Lektion Code schreiben und ausführen?

Ja. Jede R Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

  1. Paketstruktur mit usethis und devtools
  2. Funktionen mit roxygen2 dokumentieren
  3. Unit-Tests mit testthat
  4. CRAN-Einreichung und Paketpflege
← Zurück zu R Academy