R Academy · Pelajaran

Struktur Pakej dengan usethis dan devtools

Bina rangka direktori pakej, DESCRIPTION dan NAMESPACE dengan pembantu usethis.

Pelajaran 1 daripada 413 langkah

Struktur Pakej dengan usethis dan devtools ialah pelajaran R Academy percuma di CoddyKit. Ini ialah pelajaran 1 daripada 4. Sebanyak 3 pelajaran dalam laluan pembelajaran ini boleh dibaca sepenuhnya secara percuma — selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan praktikal dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran R Academy, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus R Academy merangkumi sejumlah 4 pelajaran.

Mengapa Membina Pakej R?

Pakej R ialah cara piawai untuk berkongsi kod, data dan dokumentasi yang boleh digunakan semula. Walaupun anda tidak pernah menerbitkannya ke CRAN, membungkus kod anda membantu menguatkuasakan amalan baik: fungsi yang didokumentasikan, ujian unit dan ruang nama yang jelas. devtools dan usethis menjadikan proses ini mudah.

Mencipta Rangka Pakej

usethis::create_package('~/mypackage') mencipta direktori dengan semua fail yang diperlukan: DESCRIPTION, NAMESPACE dan direktori R/. Projek baharu itu dibuka dalam RStudio secara automatik.

# 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

Fail DESCRIPTION

Fail DESCRIPTION ialah manifes pakej. Medan utamanya:

Title — perihalan satu baris (huruf besar pada awal perkataan, tanpa noktah)
Version — versi semantik (contohnya, 0.1.0)
Author / Authors@R — pengarang pakej
Depends — versi R yang diperlukan
Imports — pakej yang dipanggil oleh pakej anda
License — contohnya, 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

Menambah Fungsi dengan use_r()

usethis::use_r('my_function') mencipta R/my_function.R dan membukanya untuk penyuntingan. Setiap fail dalam R/ hendaklah mengandungi satu fungsi atau sekumpulan kecil fungsi yang berkaitan rapat. Jangan gunakan panggilan source() dalam fail pakej.

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

devtools::load_all() (pintasan papan kekunci Ctrl+Shift+L dalam RStudio) mensimulasikan pemasangan dan pemuatan pakej. Fungsi ini memuatkan semua fail dalam R/ ke dalam sesi semasa tanpa memasangnya. Inilah teras kitaran pembangunan berulang.

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

devtools::check() (Ctrl+Shift+E) menjalankan R CMD check — set pemeriksaan menyeluruh yang digunakan oleh CRAN. Fungsi ini memeriksa dokumentasi, ujian, contoh, ruang nama dan banyak lagi. Sasarkan 0 ERROR, 0 WARNING dan NOTA sesedikit mungkin.

# 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

Struktur Direktori R/

Semua fail sumber diletakkan dalam R/. Konvensyen umum:

Satu fail bagi setiap keluarga fungsi (contohnya, R/utils.R, R/plot_helpers.R)
R/data.R untuk dokumentasi set data
R/zzz.R untuk cangkuk .onLoad() dan .onAttach()

Tiada subdirektori dalam R/ — semua fail berada pada aras teratas.

# 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

Direktori man/

man/ mengandungi fail bantuan .Rd, satu bagi setiap fungsi yang dieksport. Anda jangan sekali-kali menyuntingnya secara manual — fail ini dijana daripada ulasan roxygen2 oleh devtools::document(). Serahkannya bersama-sama fail sumber anda.

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

Direktori tests/

usethis::use_testthat() mencipta direktori tests/testthat/ dan menambah testthat kepada DESCRIPTION. Tulis fail ujian bernama test-*.R dalam direktori itu. Jalankan semua ujian dengan 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')

Menambah Kebergantungan dengan Betul

Jangan gunakan library(pkg) dalam fail sumber pakej. Sebaliknya:

Tambah pakej itu kepada Imports dalam DESCRIPTION dengan usethis::use_package('dplyr')
Panggil fungsi dengan pkg::function() atau tambah @importFrom pkg function dalam roxygen2
Gunakan Suggests untuk pakej yang hanya diperlukan dalam contoh atau ujian

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

Ringkasan Aliran Kerja Pembangunan Pakej

Kitaran berulang piawai untuk pembangunan pakej R:

create_package() — cipta rangka sekali sahaja
use_r('name') — cipta fail sumber
Tulis dan dokumentasikan fungsi (roxygen2)
load_all() — muatkan ke dalam sesi untuk pengujian interaktif
document() — jana semula man/ dan NAMESPACE
test() — jalankan ujian unit
check() — R CMD check penuh

Semakan Pantas: Medan DESCRIPTION

Medan DESCRIPTION yang manakah menyenaraikan pakej R yang dipanggil secara langsung oleh pakej anda (kebergantungan wajib)?

Jawab dalam pelajaran interaktif

Imbas Kembali Struktur Pakej

Fail dan perintah utama untuk pembangunan pakej R:

usethis::create_package() — cipta rangka dengan DESCRIPTION, NAMESPACE, R/
DESCRIPTION — metadata Title, Version, Imports, License
usethis::use_r('name') — tambah fail sumber kepada R/
devtools::load_all() — muat semula berulang dengan pantas (Ctrl+Shift+L)
devtools::document() — jana semula man/ daripada roxygen2
devtools::check() — R CMD check penuh dengan sasaran 0 ralat/amaran
Jangan letakkan library() dalam sumber pakej — gunakan pkg::fn()

Percuma untuk bermula

Pelajari R dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus: 43
Pelajaran: 159

Mula belajar secara percuma Lihat kursus penuh

Soalan Lazim

Adakah pelajaran “Struktur Pakej dengan usethis dan devtools” percuma?

Ya — sebanyak 3 pelajaran dalam laluan pembelajaran R Academy, termasuk “Struktur Pakej dengan usethis dan devtools”, boleh dibaca sepenuhnya secara percuma di web ini. Selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan interaktif dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Kursus R Academy merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Struktur Pakej dengan usethis dan devtools”?

Bina rangka direktori pakej, DESCRIPTION dan NAMESPACE dengan pembantu usethis. Anda berlatih R Academy menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan R Academy?

Tiada pengalaman terdahulu diperlukan. Pembelajaran R Academy di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 1 daripada 4.

Berapa lamakah pelajaran “Struktur Pakej dengan usethis dan devtools” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran R Academy ini?

Ya. Setiap pelajaran R Academy menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

Struktur Pakej dengan usethis dan devtools
Mendokumentasikan Fungsi dengan roxygen2
Ujian Unit dengan testthat
Penyerahan CRAN dan Penyelenggaraan Pakej

← Kembali ke R Academy