Sebastien Rousseau
تواصل معي ›

LibMake: Rust Library Scaffold Generator

Scaffold a production-ready Rust library with CI, tests, and docs in under 60 seconds

4 دقيقة قراءة
Banner for: LibMake: Rust Library Scaffold Generator

الملخص التنفيذي / النقاط الرئيسية

  • LibMake ⧉ هي أداة Rust CLI مفتوحة المصدر تُثبَّت عبر cargo install libmake، وتُنشئ هيكلاً متكاملاً لمكتبة من علامات CLI أو ملف إعداد (TOML أو YAML أو JSON أو CSV)، يشمل المخرجات Cargo.toml والمصدر والاختبارات والقياسات والتوثيق وCI في استدعاء واحد.
  • المشروع المُنشأ يتبع اصطلاحات Rust API Guidelines: تعليقات التوثيق على مستوى الوحدة والعناصر في src/lib.rs، و#![deny(missing_docs)] في جذر الحزمة، وربط README بتوثيق الحزمة عبر #![doc = include_str!("../README.md")].
  • وضع ملف الإعداد (--config libmake.toml) يُتيح للفرق إيداع ملف واحد يُحدد قالب المكتبة بالكامل—المؤلف والترخيص والتصنيفات وإصدار Rust وMSRV وعنوان URL للمستودع—مما يجعل إنشاء الهيكل قابلاً للتكرار والمقارنة في Git.
  • سير عمل GitHub Actions المُنشأ بواسطة LibMake يختبر على سلاسل أدوات Rust stable وbeta وnightly، ويُطبّق clippy -D warnings، ويفحص rustfmt، ويُشغّل cargo-audit للثغرات المعروفة في شجرة الاعتماديات.
  • قوالب Tera تُشغّل توليد الكود: تشحن LibMake بمجموعة قوالب افتراضية لكنها تقبل دليل قوالب مخصصاً عبر --template، فلا حاجة لإنشاء نسخة من الأداة لدعم تخطيطات المشاريع غير القياسية والملفات المُنشأة الإضافية.

LibMake ⧉ هي أداة Rust CLI ومكتبة مفتوحة المصدر تُنشئ هيكلاً متكاملاً لمشروع مكتبة من استدعاء واحد. تسد الفجوة بين cargo new --lib (الذي ينشئ Cargo.toml وsrc/lib.rs الحدّيّيْن فحسب) والإعداد الجاهز للإنتاج (الذي يتطلب إضافة تعليقات التوثيق وCI وأُطر الاختبار وبنية القياس وCONTRIBUTING.md وملفات الترخيص يدوياً).

تستعرض هذه المقالة ما تُنشئه LibMake، وكيفية عمل وضعَي ملف الإعداد وCLI، وبنية CI المُنشأة، ونظام القوالب.

التثبيت والاستخدام الأساسي #

تُنشر LibMake على crates.io وتُثبَّت عبر Cargo:

cargo install libmake

الاستدعاء الأدنى لـ CLI ينشئ مكتبة مُسمّاة في الدليل الحالي:

libmake \
  --author "Jane Smith" \
  --email "jane@example.com" \
  --name "my_library" \
  --description "A Rust library for doing useful things" \
  --version "0.1.0" \
  --licence "MIT OR Apache-2.0" \
  --repository "https://github.com/example/my_library" \
  --rustversion "1.70.0" \
  --edition "2021" \
  --output "my_library"

تشمل العلامات الاختيارية الإضافية --categories و--keywords و--homepage و--documentation و--readme و--build.

وضع ملف الإعداد #

للاستخدام الجماعي، يمكن التعبير عن جميع علامات CLI في ملف إعداد TOML:

# libmake.toml
author      = "Jane Smith"
email       = "jane@example.com"
name        = "my_library"
description = "A Rust library for doing useful things"
version     = "0.1.0"
licence     = "MIT OR Apache-2.0"
repository  = "https://github.com/example/my_library"
rustversion = "1.70.0"
edition     = "2021"
output      = "my_library"
categories  = ["algorithms", "data-structures"]
keywords    = ["rust", "library"]

يُستدعى على النحو التالي:

libmake --config libmake.toml

تقبل LibMake أيضاً صيغ الإعداد JSON وYAML وCSV عبر علامات --config-json و--config-yaml و--config-csv على التوالي. إيداع libmake.toml في جذر المستودع يُتيح لكل مساهم خطاً أساسياً قابلاً للتكرار، وتكون التغييرات على إعداد القالب مرئية في مقارنات Git.

بنية المشروع المُنشأة #

يُنشئ استدعاء LibMake التخطيط التالي:

my_library/
├── .github/
│   └── workflows/
│       └── release.yml     # full CI matrix
├── benches/
│   └── lib_benchmarks.rs   # Criterion benchmark stub
├── src/
│   └── lib.rs              # doc-commented, deny(missing_docs)
├── tests/
│   └── lib_tests.rs        # integration test stub
├── CONTRIBUTING.md
├── Cargo.toml              # complete metadata
├── LICENSE-APACHE
├── LICENSE-MIT
└── README.md

يتضمن ملف src/lib.rs المُنشأ تعليق توثيق على مستوى الحزمة، و#![deny(missing_docs)]، و#![doc = include_str!("../README.md")] لسحب README إلى rustdoc، ونوعاً عاماً بتعليق توثيق مرتبط. تتبع هذه الخيارات اشتراط Rust API Guidelines بأن تحتوي جميع العناصر العامة على توثيق.

يستخدم ملف benches/lib_benchmarks.rs المُنشأ Criterion.rs ويتطلب إضافة criterion كاعتمادية تطوير، تُدرجها LibMake في Cargo.toml تلقائياً.

سير عمل GitHub Actions CI #

يُشغّل ملف .github/workflows/release.yml المُنشأ خمس مهام في كل دفع وطلب سحب:

المهمة سلسلة الأدوات ما تفحصه
test stable وbeta وnightly (مصفوفة) cargo test --all-features
clippy stable cargo clippy -- -D warnings
fmt stable cargo fmt --check
audit stable cargo audit (يُثبَّت cargo-audit في المهمة)
doc stable cargo doc --no-deps (يفشل عند نقص التوثيق)

تحمل مهمة nightly continue-on-error: true حتى لا تحجب نكسة nightly عمليات الدمج، مع إظهار الفشل في تشغيل سير العمل.

القوالب باستخدام Tera #

تستخدم LibMake محرك قوالب Tera—بنية صياغة شبيهة بـ Jinja2 لـ Rust—لتصيير جميع الملفات المُنشأة. يستقبل كل قالب بنية الإعداد الكاملة كسياق:

{{ name }}            → my_library
{{ author }}          → Jane Smith
{{ edition }}         → 2021
{{ description }}     → A Rust library for doing useful things

تُدعم دلائل القوالب المخصصة عبر علامة --template:

libmake --config libmake.toml --template ./my_templates/

يجب أن يعكس الدليل المخصص بنية القالب الافتراضية (نفس أسماء الملفات). يتجاوز أي ملف موجود في الدليل المخصص القالب المدمج المقابل؛ والملفات غير الموجودة في الدليل المخصص تعود إلى الإصدار المدمج. يُتيح هذا التجاوزات الجزئية—على سبيل المثال، استبدال قالب سير عمل CI فقط مع الإبقاء على قوالب src/lib.rs وCargo.toml الافتراضية.

الأسئلة الشائعة #

كيف تختلف LibMake عن cargo new --lib؟ ينشئ cargo new --lib مشروعاً أدنى يحتوي فقط على Cargo.toml وsrc/lib.rs (يحمل كتلة #[cfg(test)] واحدة). تُنشئ LibMake البنية الكاملة—اختبارات تكامل وقياسات أداء وCI وCONTRIBUTING.md وملفات ترخيص مزدوجة وsrc/lib.rs موثقاً توثيقاً صحيحاً—مُهيَّأةً ببيانات المشروع الفعلية لا بعناصر نائبة.

هل يمكن استخدام LibMake مع فضاء عمل Cargo موجود؟ تُنشئ LibMake دليل حزمة مستقلة. لإضافة الحزمة المُنشأة إلى فضاء عمل موجود، أضف مسار المخرجات إلى مصفوفة members في Cargo.toml الجذرية. لا تُعدّل LibMake ملفات فضاء العمل الموجودة.

هل يمكنني تحديث قوالب الهيكل بعد الإنشاء الأولي؟ تُنشئ LibMake الملفات مرةً واحدة؛ فهي لا تتتبع المشاريع المُنشأة سابقاً ولا تُحدّثها. لاعتماد قوالب مُحدَّثة، يُنصح بإعادة تشغيل LibMake في دليل مؤقت ومقارنة النتيجة بالحزمة الموجودة، مع تطبيق التغييرات المطلوبة بشكل انتقائي.

ما إصدارات Rust وقيم MSRV التي تدعمها LibMake؟ تقبل LibMake أي نص لـ --edition و--rustversion وتكتب القيم مباشرةً في Cargo.toml. لا تتحقق من كون الإصدار أو MSRV المحدد إصداراً حقيقياً من Rust، لذا يتحمل المستدعون مسؤولية توفير قيم صحيحة.

المراجع #

  1. Rousseau, S. LibMake — A code generator to reduce repetitive tasks and build high-quality Rust libraries. GitHub, 2023. https://github.com/sebastienrousseau/libmake
  2. The Rust Programming Language. Rust API Guidelines. GitHub, 2023. https://rust-lang.github.io/api-guidelines/
  3. The Cargo Book. Package Layout. The Rust Programming Language, 2023. https://doc.rust-lang.org/cargo/guide/project-layout.html
  4. Keats, V. et al. Tera — A template engine inspired by Jinja2 and Django templates. GitHub, 2023. https://keats.github.io/tera/

آخر مراجعة .

آخر مراجعة .