0Pricing
R Academy · บทเรียน

โครงสร้างแพ็กเกจด้วย usethis และ devtools

สร้างโครงร่างไดเรกทอรีแพ็กเกจ DESCRIPTION และ NAMESPACE ด้วยตัวช่วยของ usethis

โครงสร้างแพ็กเกจด้วย usethis และ devtools เป็นบทเรียน R Academy ฟรีบน CoddyKit นี่คือบทเรียนที่ 1 จากทั้งหมด 4 บทเรียน คุณสามารถอ่านบทเรียนทั้งหมดด้านล่างฟรี — จากนั้นลองปฏิบัติด้วยตัวคุณเองในเบราว์เซอร์พร้อมตัวแก้ไขโค้ดในตัวและติวเตอร์ AI ตลอด 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 คือรายการข้อมูลประจำแพ็กเกจ ฟิลด์สำคัญมีดังนี้:

  • ชื่อเรื่อง — คำอธิบายหนึ่งบรรทัด (ใช้รูปแบบตัวพิมพ์ใหญ่ในชื่อเรื่อง และไม่ใส่จุดท้ายประโยค)
  • เวอร์ชัน — เวอร์ชันตามหลักความหมาย (เช่น 0.1.0)
  • ผู้เขียน / Authors@R — ผู้เขียนแพ็กเกจ
  • Depends — เวอร์ชัน R ที่ต้องใช้
  • Imports — แพ็กเกจที่แพ็กเกจของคุณเรียกใช้
  • สัญญาอนุญาต — เช่น 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 ERRORs, 0 WARNINGs และมี NOTEs ให้น้อยที่สุด

# 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 check อย่างครบถ้วน

ตรวจสอบอย่างรวดเร็ว: ฟิลด์ 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 check อย่างครบถ้วน โดยตั้งเป้าให้มีข้อผิดพลาด/คำเตือนเป็น 0
  • ห้ามใส่ library() ในต้นฉบับแพ็กเกจ — ให้ใช้ pkg::fn()

คำถามที่พบบ่อย

บทเรียน “โครงสร้างแพ็กเกจด้วย usethis และ devtools” ฟรีหรือไม่

ใช่ — ข้อความเต็มของ “โครงสร้างแพ็กเกจด้วย usethis และ devtools” ฟรีให้อ่านที่นี่บนเว็บ เพื่อปฏิบัติแบบโต้ตอบ (ตัวแก้ไขโค้ดในตัวและติวเตอร์ AI ตลอด 24/7) และปลดล็อคส่วนที่เหลือของคอร์ส R Academy ให้อัปเกรดเป็น CoddyKit PRO คอร์ส R Academy มีบทเรียนทั้งหมด 4 บทเรียน

คุณจะเรียนรู้อะไรในบทเรียน “โครงสร้างแพ็กเกจด้วย usethis และ devtools”

สร้างโครงร่างไดเรกทอรีแพ็กเกจ DESCRIPTION และ NAMESPACE ด้วยตัวช่วยของ usethis คุณปฏิบัติ R Academy ด้วยโค้ดที่ใช้งานได้จริงที่คุณเรียกใช้โดยตรงในเบราว์เซอร์ และติวเตอร์ AI ตลอด 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