R Academy · Lektion

Paketstruktur med usethis och devtools

Skapa en paketkatalog samt DESCRIPTION och NAMESPACE med hjälpfunktioner från usethis.

Lektion 1 av 413 steg

Paketstruktur med usethis och devtools är en gratis lektion i R Academy på CoddyKit. Detta är lektion 1 av 4. Du kan läsa vilka 3 lektioner som helst i den här lärvägen kostnadsfritt i sin helhet – därefter låser CoddyKit PRO upp alla lektioner, plus praktisk övning med en inbyggd kodredigerare och en AI-lärare dygnet runt. Den ingår i lärvägen för R Academy, och Era framsteg synkroniseras mellan webben och CoddyKit-appen. Kursen i R Academy innehåller totalt 4 lektioner.

Varför skapa ett R-paket?

Ett R-paket är det vanligaste sättet att dela återanvändbar kod, data och dokumentation. Även om Ni aldrig publicerar paketet på CRAN innebär paketering av koden att Ni följer god praxis: dokumenterade funktioner, enhetstester och ett tydligt namespace. devtools och usethis gör processen enkel.

Skapa paketets grundstruktur

usethis::create_package('~/mypackage') skapar en katalog med alla filer som krävs: DESCRIPTION, NAMESPACE och katalogen R/. Det nya projektet öppnas automatiskt i 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

Filen DESCRIPTION

Filen DESCRIPTION är paketets manifest. Viktiga fält:

Title — beskrivning på en rad (title case, ingen punkt)
Version — semantisk version (t.ex. 0.1.0)
Author / Authors@R — paketets författare
Depends — nödvändig R-version
Imports — paket som paketet anropar
License — t.ex. 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

Lägga till funktioner med use_r()

usethis::use_r('my_function') skapar R/my_function.R och öppnar filen för redigering. Varje fil i R/ bör innehålla en eller en liten grupp nära relaterade funktioner. Använd inte anrop till source() i paketfiler.

# 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() — utvecklingsloopen

devtools::load_all() (kortkommandot Ctrl+Shift+L i RStudio) simulerar installation och inläsning av paketet. Det läser in alla filer i R/ i den aktuella sessionen utan att faktiskt installera paketet. Detta är kärnan i den iterativa utvecklingscykeln.

# 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() — fullständig granskning

devtools::check() (Ctrl+Shift+E) kör R CMD check — den omfattande testsvit som används av CRAN. Den kontrollerar dokumentation, tester, exempel, namespace och mycket mer. Sikta på 0 ERRORs, 0 WARNINGs och så få NOTEs som möjligt.

# 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

Katalogstrukturen för R/

Alla källfiler placeras i R/. Vanliga konventioner:

En fil per funktionsfamilj (t.ex. R/utils.R, R/plot_helpers.R)
R/data.R för dokumentation av dataset
R/zzz.R för hookarna .onLoad() och .onAttach()

Inga underkataloger i R/ — alla filer ligger på toppnivån.

# 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

Katalogen man/

man/ innehåller hjälpfiler i formatet .Rd, en för varje exporterad funktion. Ni bör aldrig redigera dessa manuellt — de genereras från roxygen2-kommentarer av devtools::document(). Checka in dem tillsammans med källkoden.

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

Katalogen tests/

usethis::use_testthat() skapar katalogen tests/testthat/ och lägger till testthat i DESCRIPTION. Skriv testfiler med namnet test-*.R i den katalogen. Kör alla tester med 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')

Lägga till beroenden på rätt sätt

Använd aldrig library(pkg) i paketets källfiler. Gör i stället följande:

Lägg till paketet i Imports i DESCRIPTION med usethis::use_package('dplyr')
Anropa funktioner med pkg::function() eller lägg till @importFrom pkg function i roxygen2
Använd Suggests för paket som endast behövs i exempel eller tester

# 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
# }

Sammanfattning av arbetsflödet för paketutveckling

Den standardiserade iterativa cykeln för utveckling av R-paket:

create_package() — skapa grundstrukturen en gång
use_r('name') — skapa en källfil
Skriv och dokumentera funktioner (roxygen2)
load_all() — läs in paketet i sessionen för interaktiv testning
document() — generera om man/ och NAMESPACE
test() — kör enhetstester
check() — fullständig R CMD check

Snabbkontroll: DESCRIPTION-fält

Vilket DESCRIPTION-fält listar de R-paket som paketet anropar direkt (hårda beroenden)?

Besvara frågan i den interaktiva lektionen

Sammanfattning av paketstrukturen

Viktiga filer och kommandon för utveckling av R-paket:

usethis::create_package() — skapa grundstrukturen med DESCRIPTION, NAMESPACE, R/
DESCRIPTION — metadata för Title, Version, Imports och License
usethis::use_r('name') — lägg till en källfil i R/
devtools::load_all() — snabb iterativ omladdning (Ctrl+Shift+L)
devtools::document() — generera om man/ från roxygen2
devtools::check() — fullständig R CMD check med målet 0 fel/varningar
Placera aldrig library() i paketets källkod — använd pkg::fn()

Gratis att börja

Lär dig R med en AI-lärare – gratis

Skriv och kör riktig kod i webbläsaren, få omedelbar hjälp av en AI-lärare dygnet runt och fortsätt där du slutade – på webben eller i appen.

Kurser: 43
Lektioner: 159

Börja lära dig gratis Visa hela kursen

Vanliga frågor

Är lektionen ”Paketstruktur med usethis och devtools” gratis?

Ja – du kan läsa vilka 3 lektioner som helst i lärvägen R Academy, inklusive ”Paketstruktur med usethis och devtools”, kostnadsfritt i sin helhet här på webben. Därefter låser CoddyKit PRO upp alla lektioner, plus interaktiv övning med en inbyggd kodredigerare och en AI-lärare dygnet runt. Kursen i R Academy innehåller totalt 4 lektioner.

Vad lär jag mig i ”Paketstruktur med usethis och devtools”?

Skapa en paketkatalog samt DESCRIPTION och NAMESPACE med hjälpfunktioner från usethis. Ni övar på R Academy med praktisk kod som körs direkt i webbläsaren, medan en AI-handledare som är tillgänglig dygnet runt svarar på Era frågor under lektionen.

Behöver jag någon erfarenhet för att börja lära mig R Academy?

Du behöver inga förkunskaper. Utbildningen i R Academy på CoddyKit är upplagd för allt från nybörjare till avancerade elever, så att du kan börja här eller från början och gå fram i din egen takt. Detta är lektion 1 av 4.

Hur lång tid tar lektionen ”Paketstruktur med usethis och devtools”?

De flesta CoddyKit-lektioner tar cirka 5–10 minuter. Varje lektion är kort och interaktiv, så att du gör stadiga framsteg och kan fortsätta precis där du slutade – på webben eller i appen.

Kan jag skriva och köra kod i den här R Academy-lektionen?

Ja. Varje R Academy-lektion innehåller en inbyggd kodredigerare, så att du kan skriva och köra riktig kod direkt i webbläsaren och få omedelbar AI-feedback – utan lokal installation.

Alla lektioner i den här kursen

← Tillbaka till R Academy