R Academy · درس

بنية الحزم باستخدام usethis وdevtools

أنشئ هيكل مجلد الحزمة وملفي DESCRIPTION وNAMESPACE باستخدام مساعدات usethis

بنية الحزم باستخدام usethis وdevtools درس مجاني في R Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 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 بيان الحزمة. وتشمل حقوله الأساسية ما يلي:

Title — وصف في سطر واحد (بحالة العنوان ومن دون نقطة)
Version — إصدار دلالي (مثل 0.1.0)
Author / Authors@R — مؤلف الحزمة
Depends — إصدار R المطلوب
Imports — الحزم التي تستدعيها حغمتك
License — مثل 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 لـ hooks الخاصة بـ .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:

create_package() — إنشاء الهيكل مرة واحدة
use_r('name') — إنشاء ملف مصدر
كتابة الدوال وتوثيقها (roxygen2)
load_all() — تحميل الحزمة إلى الجلسة لاختبارها تفاعليًا
document() — إعادة إنشاء man/ وNAMESPACE
test() — تشغيل اختبارات الوحدات
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» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة R Academy، انتقل إلى CoddyKit PRO. تتضمن دورة R Academy 4 دروس في المجموع.

ماذا ستتعلم في «بنية الحزم باستخدام usethis وdevtools»؟

أنشئ هيكل مجلد الحزمة وملفي DESCRIPTION وNAMESPACE باستخدام مساعدات usethis تتمرن على R Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ R Academy؟

لا تُشترط خبرة سابقة. R Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «بنية الحزم باستخدام usethis وdevtools»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس R Academy هذا؟

نعم. كل درس في R Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى R Academy