تخصيص نسخ مشروع بلغة رست ونشرها على crates.io

سنتعرّف هنا على كيفية تخصيص نُسَخ المشروع builds المختلفة باستخدام ما يُدعى حسابات الإصدار release profiles، ثمّ سنستعرض كيفيّة إضافة مشاريعك بلغة رست على موقع crates.io.

تخصيص نسخ مشروع مع حسابات الإصدار وضبطها في كارجو cargo

حسابات الإصدار في رست هي حسابات قابلة للتعديل customizable ومعرّفة مسبقًا بالعديد من الإعدادات المختلفة التي تسمح للمبرمج بأن يمتلك تحكمًا أكبر على العديد من الخيارات لتصريف الشيفرة البرمجية، إذ أن كل حساب مضبوط بصورةٍ مستقلة عن الآخر.

لدى كارجو حسابين أساسيين، هما: حساب dev وهو حساب يستخدمه كارجو عندما تنفّذ cargo build وحساب release يستخدمه كارجو عندما تنفّذ cargo build --release. حساب dev معرَّف بإعدادات تصلح لعملية التطوير، وحساب release مُعرَّف بإعدادت تصلح لإطلاق نسخ جديدة.

قد تكون أسماء الحسابات هذه ضمن خرج نسخ مشروعك مألوفة:

$ cargo build
    Finished dev [unoptimized + debuginfo] target(s) in 0.0s
$ cargo build --release
    Finished release [optimized] target(s) in 0.0s

حسابات dev و release هي الحسابات التي يستخدمها المصرّف.

يمتلك كارجو إعدادات افتراضية لكلٍ من الحسابات التي تُطبَّق عندما لا تُحدد بوضوح بإضافة أية أقسام [profile.*‎] إلى ملف cargo.toml الخاص بالمشروع، إذ عند إضافة قسم [profile.*‎] لأي حساب تريد التعديل عليه، فأنت تُعيد الكتابة على أي من الإعدادات الفرعية الخاصة بالإعدادات الافتراضية. مثلاً، هذه هي القيم الأساسية لإعدادات opt-level لكل من الحسابين dev و release.

اسم الملف: cargo.toml

[profile.dev]
opt-level = 0

[profile.release]
opt-level = 3

تتحكم إعدادات opt-level بعدد التحسينات التي ستطبقها رست على شيفرتك البرمجية، بمجال من 0 إلى 3، مع الانتباه إلى أن تطبيق أي تحسينات إضافية سيزيد من وقت التصريف، لذا إذا كنت في مرحلة التطوير وتصرّف شيفرتك البرمجية بصورةٍ متكررة، فستحتاج إلى تحسينات أقل لتُصرف أسرع حتى لو كانت الشيفرة البرمجية الناتجة تعمل أبطأ. ستكون القيمة لكلٍ من opt-level و dev افتراضيًا هي 0، وعندما تكون جاهزاً لإصدار شيفرتك البرمجية، فمن الأفضل أن تقضي وقتاً أكثر بالتصريف إذ أنك ستصرّف الشيفرة البرمجية لمرة واحدة فقط في وضع الإصدار، لكنك ستشغّل البرنامج عدّة مرات، إذًا يُقايض وضع الإصدار وقت التصريف الطويل مقابل شيفرة برمجية تعمل على نحوٍ أسرع، وهذا هو السبب في كون القيمة الأساسية opt-level للحساب release هي 3.

يمكنك تجاوز القيمة الافتراضية بإضافة قيمة مختلفة لها في Cargo.toml، فإذا أردنا مثلًا أن يكون مستوى التحسين هو 1 في حساب التطوير، يمكننا إضافة هذين السطرين في ملف Cargo.toml الخاص بالمشروع:

اسم الملف: Cargo.toml

[profile.dev]
opt-level =1

تعيد هذه الشيفرة تعريف الإعداد الافتراضي 0، وعندما ننفّذ cargo build، سيستخدم كارجو الإعدادات الافتراضية لحساب dev إضافةً إلى التعديلات التي أجريناها على opt-level، ولأننا ضبطنا opt-level إلى القيمة 1، سيطبّق كارجو تحسينات أكثر من التحسينات التي يطبقها في الوضع الافتراضي، ولكن ليس أكثر من التحسينات الموجودة في إصدار البناء.

للحصول على لائحة كاملة من خيارات الضبط والقيم الافتراضية لكل حساب راجع توثيق كارجو.

نشر وحدة مصرفة crate على crates.io

استخدمنا حزم من crates.io مثل اعتماديات dependencies لمشاريعنا، لكن يمكنك أيضًا أن تشارك شيفرتك مع أشخاص آخرين عن طريق نشر حزمتك الخاصة. يوزِّع تسجيل الوحدة المُصرَّفة crates في crates.io الشيفرة المصدرية للحزم الخاصة بك، بحيث تكون الشيفرة المُستضافة مفتوحة المصدر.

لدى رست وكارجو ميزات تجعل حزمتك المنشورة أسهل إيجادًا من قبل الأشخاص واستخدامها وسنتحدث عن بعض هذه المزايا ثم سنشرح كيف تنشر حزمة.

كتابة تعليقات توثيق مفيدة

سيساعد توثيق حزمتك بدقة المستخدمين الآخرين على معرفة كيف ومتى يستخدمونها، لذا يُعد استثمار الوقت في كتابة التوثيق أمرًا مجديًا. ناقشنا سابقًا كيف تعلّق شيفرة رست باستخدام خطين مائلين "//". لدى رست أيضًا نوع محدد من التعليقات للتوثيق تعرف بتعليق التوثيق documentation comment والذي سيولّد بدوره توثيق HTML. يعرض الملف المكتوب باستخدام HTML محتويات تعليقات التوثيق لعناصر الواجهة البرمجية API العامة والموجهة للمبرمجين المهتمين بمعرفة كيفية استخدام وحدة مصرفة بغض النظر عن كيفية عملها وراء الكواليس.

تستخدم تعليقات التوثيق ثلاثة خطوط مائلة "///" بدلاً من خطّين، وتدعم صيغة ماركداون Markdown لتنسيق النص، إذ يكفي وضع تعليقات النص مباشرةً قبل العنصر الذي يوَثّق. تُظهر الشيفرة 1 تعليقات التوثيق لدالة add_one في وحدة مصرفة تدعى my_crate.

اسم الملف: src/lib.rs

/// أضف واحد إلى الرقم المُعطى
///
/// # أمثلة
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}

[الشيفرة 1- تعليق التوثيق لدالة]

نقدم هنا وصفًا عما تفعله دالة add_one، ابدأ القسم بعنوان Examples ثم ضع شيفرة تعبّر عن كيفية استخدام الدالة add_one، ويمكننا توليد توثيق HTML من تعليق التوثيق هذا عن طريق تنفيذ cargo doc، إذ يشغّل هذا الأمر أداة rustdoc الموزّعة مع رست وتضع توثيق HTML المولّد في المجلد "target/doc".

سيبني تنفيذ cargo doc --open ملف HTML للتوثيق الحالي لوحدتك المصرفة (وأيضًا توثيق كل ما يعتمد على وحدتك المصرفة) ويفتح النتيجة في متصفح ويب للسهولة. انتقل إلى الدالة add_one وسترى كيف يتحول النص في تعليقات التوثيق، كما يظهر في الشكل 1:

[الشكل 1: توثيق HTML لدالة add_one]

الأقسام شائعة الاستخدام

استخدمنا عنوان ماركداون ‎# Examples في الشيفرة 1 لإنشاء قسم في ملف HTML بالعنوان "Examples" وهذه بعض الأجزاء الشائعة الأخرى التي يستخدمها مؤلفو الوحدات المصرفة في توثيقهم:

الهلع Panics: السيناريوهات التي تتوقف بها الدوال المُضمنة بالتوثيق، ويجب على مستخدمي الدالة الذين لا يريدون لبرامجهم أن تتوقف ألا يستدعوا الدالة في هذه الحالات.
الأخطاء Errors: إذا أعادت الدالة القيمة Result واصفةً أنواع الأخطاء التي قد حصلت للشيفرة البرمجية المُستدعاة والظروف التي قد تسببت بحدوث الأخطاء التي تعيدها، تكون هذه المعلومات مفيدة للمستخدمين ويمكنهم بهذا أن يكتبوا شيفرة تستطيع التعامل مع الأنواع المختلفة من الأخطاء بعدة طرق.
الأمان Safety: إذا استُدعيَت الدالة unsafe (نناقش عدم الأمان Unsafety لاحقًا)، يجب أن يكون هناك قسمٌ يشرح سبب عدم أمان الدالة ويغطي الأنواع اللا متغايرة invariants التي تتوقعها الدالة من المستخدمين.

لا تحتاج معظم تعليقات التوثيق لكل هذه الأقسام، لكن هذه لائحة جيدة تذكرك بالجوانب التي سيهتم مستخدمو شيفرتك البرمجية بمعرفتها.

استخدام تعليقات التوثيق مثل اختبارات

يساعد إضافة كُتَل من الشيفرات البرمجية على أنها مثال ضمن تعليقات التوثيق فهم كيفية استخدام مكتبتك، ولفعل هذا الأمر مزايا إضافية: إذ أن تنفيذ cargo test سينفذ بدوره أمثلة الشيفرة البرمجية في توثيقك مثل اختبارات. لا شيء أفضل من توثيق يحتوي على أمثلة، لكن لا شيء أسوأ من أمثلة لا تعمل لأن الشيفرة البرمجية قد تغيرت منذ وقت كتابة التوثيق. نحصل على قسم في نتائج الاختبارات إذا نفّذنا الأمر cargo test مع توثيق دالة add_one من الشيفرة 1 على النحو التالي:

      Doc-tests my_crate

running 1 test
test src/lib.rs - add_one (line 5) ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.27s

الآن إذا غيرنا إما الدالة أو المثال بحيث يهلع الماكرو assert_eq!‎ في المثال وينفّذ cargo test مرةً أخرى، سنرى أن اختبارات التوثيق تلاحظ أن شيفرة المثال والشيفرة البرمجية لا يتزامنان مع بعضهما بعضًا.

تعليق العناصر المحتواة

يضيف أسلوب التعليق "!//" التوثيق إلى العنصر الذي يحتوي على التعليقات بدلاً من العناصر التي تلي التعليقات، ونستخدم عادةً تعليقات المستند هذه داخل ملف الوحدة المصرفة الجذر (src/lib.rs اصطلاحًا)، أو داخل وحدة ما لتوثيق الوحدة المصرفة، أو الوحدة ككُل. على سبيل المثال، لإضافة التوثيق التي يصف الغرض من الوحدة المصرّفة my_crate التي تحتوي على الدالة add_one، نضيف تعليقات التوثيق التي تبدأ بـ "!//" إلى بداية الملف src/lib.rs، كما هو موضح في الشيفرة 2:

اسم الملف: src/lib.rs

//! # My Crate
//!
//! `my_crate` is a collection of utilities to make performing certain
//! calculations more convenient.

/// Adds one to the number given.
// --snip--

[الشيفرة 2: توثيق الوحدة المصرفة my_crate ككل]

لاحظ عدم وجود أي شيفرة برمجية بعد آخر سطر يبدأ بـ "!//"، وذلك لأننا بدأنا التعليقات بـ "!//" بدلاً من "///". نوثّق العنصر الذي يحتوي على هذا التعليق بدلاً من العنصر الذي يتبع هذا التعليق، وفي هذه الحالة، يكون هذا العنصر هو ملف src/lib.rs، وهو الوحدة المصرفة الجذر، إذ تصف هذه التعليقات كامل الوحدة المصرفة.

عندما ننفّذ cargo doc --open، تظهر هذه التعليقات على الصفحة الأولى من توثيق my_crate أعلى قائمة العناصر العامة في الوحدة المصرفة، كما هو موضح في الشكل 2:

[الشكل 2: التوثيق المولَّد للوحدة المصرّفة my_crate متضمنًا التعليق الذي يصف كل الوحدة المصرفة]

تُعد تعليقات التوثيق داخل العناصر مفيدةً لوصف الوحدات المصرفة والوحدات خصوصًا. استخدمها لشرح الغرض العام من الحاوية container لمساعدة المستخدمين على فهم تنظيم الوحدة المصرفة.

تصدير واجهة برمجية عامة Public API ملائمة باستخدام pub use

يُعد هيكل الواجهة البرمجية العامة أحد النقاط المهمة عند نشر وحدة مصرفة، إذ يكون الأشخاص الذين يستخدمون الوحدة المصرفة الخاصة بك أقل دراية منك بهيكلية الوحدة، وقد يواجهون صعوبةً في إيجاد الأجزاء التي يريدون استخدامها إذا كانت الوحدة المصرفة الخاصة بك تحتوي على تسلسل هرمي كبير.

تناولنا سابقًا كيفية جعل العناصر عامة باستخدام الكلمة المفتاحية pub، وإضافة العناصر إلى نطاق باستخدام الكلمة المفتاحية use. ومع ذلك، قد لا تكون الهيكلية المنطقية بالنسبة لك أثناء تطوير الوحدة المصرفة مناسبةً للمستخدمين، إذ قد ترغب في تنظيم الهياكل الخاصة بك ضمن تسلسل هرمي يحتوي على مستويات متعددة، ولكن قد يواجه بعض الأشخاص مشاكلًا بخصوص وجود نوع ما عرّفته في مكان عميق ضمن التسلسل الهرمي وذلك عندما يرغبون باستخدامه، كما قد يسبب الاضطرار إلى إدخال المسار التالي بعض الازعاج:

use my_crate::some_module::another_module::UsefulType;‎

بدلًا من استخدام:

use my_crate::UsefulType;‎

الخبر السار هو أنه إذا لم يكن الهيكل مناسبًا للآخرين لاستخدامه من مكتبة أخرى، فلن تضطر إلى إعادة ترتيب التنظيم الداخلي، إذ يمكنك إعادة تصدير العناصر بدلًا من ذلك لإنشاء هيكل عام مختلف عن هيكلتك الخاصة باستخدام pub use. تأخذ عملية إعادة التصدير عنصرًا عامًا من مكان ما وتجعله عامًا في مكان آخر، كما لو جرى تعريفه في موقع آخر عوضًا عن ذلك.

على سبيل المثال، لنفترض أننا أنشأنا مكتبة باسم art لنمذجة المفاهيم الفنية، بحيث يوجد داخل هذه المكتبة وحدتان: وحدة kinds تحتوي على معدّدَين enums باسم PrimaryColor و SecondaryColor ووحدة utils تحتوي على دالة تدعى mix، كما هو موضح في الشيفرة 3:

اسم الملف: src/lib.rs

//! # Art
//!
//! مكتبة لنمذجة المفاهيم الفنية

pub mod kinds {
    /// الألوان الأساسية طبقًا لنموذج‪ ‪‪‪RYB  
    pub enum PrimaryColor {
        Red,
        Yellow,
        Blue,
    }

    /// الألوان الثانوية طبقًا لنموذج‪ RYB
    pub enum SecondaryColor {
        Orange,
        Green,
        Purple,
    }
}

pub mod utils {
    use crate::kinds::*;

    /// دمج لونين أساسيين بقيم متساوية لإنشاء لون ثانوي
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        // --snip--
    }
}

[الشيفرة 3: مكتبة art التي تحتوي على عناصر منظمة ضمن الوحدتين kinds و utils]

يوضح الشكل 3 كيف ستبدو الصفحة الأولى لتوثيق الوحدة المصرفة التي أُنشئت بواسطة cargo doc:

[الشكل 3: الصفحة الأولى لتوثيق art الذي توضّح الوحدتين kinds و utils]

لاحظ أن النوعين PrimaryColor و SecondaryColor غير مُدرجين في الصفحة الأولى وكذلك دالة mix، إذ يجب علينا النقر على kinds و utils لرؤيتهما.

ستحتاج وحدة مصرفة أخرى تعتمد على هذه المكتبة إلى عبارات use، لتجلب العناصر الموجودة في art إلى النطاق، وبالتالي تحديد هيكل الوحدة المعرّفة حاليًا. تُظهر الشيفرة 4 مثالاً على الوحدة المصرفة التي تستخدم عناصر PrimaryColor و mix من الوحدة المصرفة art:

اسم الملف: src/main.rs

use art::kinds::PrimaryColor;
use art::utils::mix;

fn main() {
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}

[الشيفرة 4: وحدة مصرفة تستخدم عناصر الوحدة المصرفة art مع تصدير هيكلها الداخلي]

ينبغي على مؤلف الشيفرة في الشيفرة 4 التي تستخدم الوحدة المصرفة art أن يعرّف أن PrimaryColor موجود في الوحدة kinds وأن mix موجودة في الوحدة utils. هيكل الوحدة المصرفة art مناسب أكثر للمطورين العاملين على الوحدة المصرفة art مقارنةً بمن سيستخدمها، إذ لا يحتوي الهيكل الداخلي على أي معلومات مفيدة لشخص يحاول فهم كيفية استخدام الوحدة المصرفة art، بل يتسبب الهيكل الداخلي باللّبس لأن المطورين الذين يستخدمونها يجب أن يعرفوا أيّ المسارات التي يجب عليهم الذهاب إليها كما يجب عليهم تحديد أسماء الوحدات في عبارات use.

لإزالة التنظيم الداخلي من الواجهة البرمجية العامة يمكننا تعديل شيفرة الوحدة المصرفة art في الشيفرة 3 لإضافة تعليمات pub use لإعادة تصدير العناصر للمستوى العلوي كما هو موضح في الشيفرة 5:

اسم الملف: src/lib.rs

//! # Art
//!
//! مكتبة لنمذجة المفاهيم الفنية

pub use self::kinds::PrimaryColor;
pub use self::kinds::SecondaryColor;
pub use self::utils::mix;

pub mod kinds {
    // --snip--
}

pub mod utils {
    // --snip--
}

[الشيفرة 5: إضافة تعليمات pub use لإعادة تصدير العناصر]

سيُدرِج توثيق الواجهة البرمجية التي يولدها الأمر cargp doc لهذه الوحدة المصرفة ويعيد تصديرها على الصفحة الأولى كما هو موضح في الشكل 4 جاعلًا النوعَين PrimaryColor و SecondaryColor ودالة mix أسهل للإيجاد.

[الشكل 4: الصفحة الأولى لتوثيق art التي تعرض عمليات إعادة التصدير]

يمكن لمستخدمي الوحدة المصرفة art أن يروا ويستخدموا الهيكلة الداخلية من الشيفرة 3 كما هو موضح في الشيفرة 4 أو يمكنهم استخدام هيكل أكثر سهولة للاستخدام في الشيفرة 5 كما هو موضح في الشيفرة 6:

اسم الملف: src/main.rs

use art::mix;
use art::PrimaryColor;

fn main() {
    // --snip--
}

[الشيفرة 6: برنامج يستخدم العناصر المعاد تصديرها من الوحدة المصرفة art]

يمكن -في الحالات التي يوجد فيها العديد من الوحدات المتداخلة nested modules- أن تحدث عملية إعادة تصدير الأنواع في المستوى العلوي باستخدام pub use فرقًا واضحًا على تجربة الأشخاص في استخدام الوحدة المصرّفة. الاستخدام الشائع الآخر للتعليمة pub use هو إعادة تصدير تعريفات الاعتمادية في الوحدة المصرفة الحالية لجعل تعريفات تلك الوحدة المصرفة جزءًا من الواجهة البرمجية العامة لوحدتك المصرفة.

يُعد إنشاء بنية واجهة برمجية عامة مفيدة فنًا أكثر من كونه علمًا، ويمكنك تكرار المحاولة حتى تعثر على واجهة برمجية تعمل بصورةٍ أفضل لمستخدميها، ويمنحك اختيار pub use مرونةً في كيفية هيكلة وحدتك المصرفة داخليًا وفصل هذه الهيكلة الداخلية عما تقدمه للمستخدمين. ألقِ نظرةً على الشيفرات البرمجية الخاصة ببعض الوحدات المصرفة التي ثبّتتها لمعرفة ما إذا كانت هيكلتها الداخلية مختلفة عن الواجهة البرمجية العامة.

إنشاء حساب Crates.io

قبل أن تتمكن من نشر أي وحدات مصرفة، تحتاج إلى إنشاء حساب على crates.io والحصول على رمز واجهة برمجية مميز API token، ولفعل ذلك، انقر على زر الصفحة الرئيسية على crates.io وسجّل الدخول عبر حساب غيت هب GitHub، إذ يُعد حساب غيت هب أحد المتطلبات حاليًا، ولكن قد يدعم الموقع طرقًا أخرى لإنشاء حساب في المستقبل. بمجرد تسجيل الدخول، اذهب إلى إعدادات حسابك على https://crates.io/me واسترجع مفتاح API. ثم نفّذ الأمر cargo login باستخدام مفتاح API الخاص بك، كما يلي:

$ cargo login abcdefghijklmnopqrstuvwxyz012345

يُعلم هذا الأمر كارجو برمز API الخاص بك وتخزينه محليًا في "‎~/.cargo/credentials". لاحظ أن هذا الرمز هو سر، فلا تشاركه مع أي شخص آخر، وإذا شاركته مع أي شخص لأي سبب من الأسباب، فيجب عليك إبطاله وإنشاء رمز مميز جديد على crates.io.

إضافة بيانات وصفية لوحدة مصرفة جديدة

لنفترض أن لديك وحدة مصرفة تريد نشرها، ستحتاج قبل النشر إلى إضافة بعض البيانات الوصفية في قسم [package] داخل ملف Cargo.toml الخاص بالوحدة المصرفة.

ستحتاج وحدتك المصرفة إلى اسم مميز، إذ يُمكنك تسمية الوحدة المصرفة أثناء عملك على وحدة مصرفة محليًا كما تريد، ومع ذلك، تُخصَّص أسماء الوحدات المصرفة على crates.io على أساس من يأتي أولًا يُخدم أولًا first-come, first-served. بمجرد اختيار اسم لوحدة مصرفة ما، لا يمكن لأي شخص آخر نشر وحدة مصرفة بهذا الاسم. قبل محاولة نشر وحدة مصرفة، ابحث عن الاسم الذي تريد استخدامه، فإذا كان الاسم مستخدمًا، ستحتاج إلى البحث عن اسم آخر وتعديل حقل name في ملف Cargo.toml في قسم [package] لاستخدام الاسم الجديد للنشر، كما يلي:

اسم الملف: Cargo.toml

[package]
name = "guessing_game"

حتى إذا اخترت اسمًا مميزًا، عند تنفيذ cargo publish لنشر الوحدة المصرفة في هذه المرحلة، ستتلقى تحذيرًا ثم خطأ:

$ cargo publish
    Updating crates.io index
warning: manifest has no description, license, license-file, documentation, homepage or repository.
See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info.
--snip--
error: failed to publish to registry at https://crates.io

Caused by:
  the remote server responded with an error: missing or empty metadata fields: description, license. Please see https://doc.rust-lang.org/cargo/reference/manifest.html for how to upload metadata

تحدث هذه الأخطاء بسبب افتقاد بعض المعلومات المهمة؛ إذ أن الوصف والترخيص مطلوبان حتى يعرف الأشخاص ما تفعله الوحدة المصرفة الخاصة بك وتحت أي شروط يمكنهم استخدامها. أضف وصفًا في Cargo.toml بحيث يكون مجرد جملة أو جملتين، لأنه سيظهر مع الوحدة المصرفة الخاصة بك في نتائج البحث، أما بالنسبة لحقل license، فأنت بحاجة لمنح قيمة معرّف الترخيص.

تُدرج مؤسسة لينكس لتبادل بيانات حزم البرمجيات Linux Foundation’s Software Package Data Exchange -أو اختصارًا SPDX- المعرّفات التي يمكنك استخدامها لهذه القيمة. على سبيل المثال، لتحديد أنك رخّصت وحدتك المصرفة باستخدام ترخيص MIT، أضف معرف MIT:

اسم الملف: Cargo.toml

[package]
name = "guessing_game"
license = "MIT"

إذا أردت استخدام ترخيص غير موجود في SPDX، فأنت بحاجة إلى وضع نص هذا الترخيص في ملف، وتضمين الملف في مشروعك، ثم استخدام license-file لتحديد اسم هذا الملف بدلاً من ذلك من استخدام المفتاح license.

التوجيه بشأن الترخيص المناسب لمشروعك هو خارج نطاق هذا الكتاب. يرخِّص الكثير من الأشخاص في مجتمع رست مشاريعهم بنفس طريقة رست ألا وهي باستخدام ترخيص مزدوج من "MIT OR Apache-2.0". تدلّك هذه الممارسة على أنه بإمكانك أيضًا تحديد معرّفات ترخيص متعددة مفصولة بـ OR لتضمين تراخيص متعددة لمشروعك.

باستخدام الاسم المميز والإصدار والوصف والترخيص المضاف، أصبح ملف Cargo.toml الخاص بالمشروع جاهزًا للنشر على النحو التالي:

اسم الملف: Cargo.toml

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2021"
description = "A fun game where you guess what number the computer has chosen."
license = "MIT OR Apache-2.0"

[dependencies]

يصف توثيق كارجو البيانات الوصفية الأخرى التي يمكنك تحديدها للتأكد من أن الآخرين يمكنهم اكتشاف واستخدام وحدة التصريف الخاصة بك بسهولة أكبر.

النشر على Crates.io

الآن وبعد أن أنشأت حسابًا، وحفظت رمز API، واخترت اسمًا للوحدة المصرفة، وحددت البيانات الوصفية المطلوبة، فأنت جاهزٌ للنشر، إذ يؤدي نشر وحدة مصرفة إلى رفع إصدار معين إلى crates.io ليستخدمه الآخرون.

كن حذرًا، لأن النشر دائم، ولا يمكن الكتابة فوق الإصدار مطلقًا، ولا يمكن حذف الشيفرة البرمجية. يتمثل أحد الأهداف الرئيسة لموقع crates.io بالعمل مثل أرشيف دائم للشيفرة البرمجية بحيث تستمر عمليات إنشاء جميع المشاريع التي تعتمد على الوحدات المصرفة من crates.io في العمل، والسماح بحذف نسخة ما سيجعل تحقيق هذا الهدف مستحيلًا، ومع ذلك، لا يوجد حد لعدد إصدارات الوحدات المصرفة التي يمكنك نشرها.

نفّذ الأمر cargo publish مرةً أخرى. يجب أن تنجح الآن:

$ cargo publish
    Updating crates.io index
   Packaging guessing_game v0.1.0 (file:///projects/guessing_game)
   Verifying guessing_game v0.1.0 (file:///projects/guessing_game)
   Compiling guessing_game v0.1.0
(file:///projects/guessing_game/target/package/guessing_game-0.1.0)
    Finished dev [unoptimized + debuginfo] target(s) in 0.19s
   Uploading guessing_game v0.1.0 (file:///projects/guessing_game)

تهانينا، فقد شاركت الآن الشيفرة الخاصة بك مع مجتمع رست، ويمكن لأي أحدٍ بسهولة إضافة الوحدة المصرفة الخاصة بك مثل اعتمادية لمشروعه.

نشر نسخة جديدة لوحدة مصرفة موجودة مسبقا

عندما تُجري تغييرات على الوحدة المصرفة الخاصة بك وتكون جاهزًا لطرح إصدار جديد، فإنك تغيّر قيمة version المحددة في ملف Cargo.toml الخاص بك وتعيد النشر. استخدم قواعد الإدارة الدلالية لنُسخ البرمجيات Semantic Versioning rules لتحديد رقم الإصدار التالي المناسب بناءً على التغييرات التي أجريتها، ومن ثم نفّذ cargo publish لرفع الإصدار الجديد.

تعطيل النسخ من Crates.io باستخدام cargo yank

على الرغم من أنه لا يمكنك إزالة الإصدارات السابقة للوحدة المصرفة، إلا أنه يمكنك منع أي مشاريع مستقبلية من إضافتها مثل اعتمادية جديدة، ويكون هذا مفيدًا عندما يُعطَّل إصدار الوحدة المصرفة لسبب أو لآخر، وفي مثل هذه الحالات، يدعم كارجو سحب yanking إصدار وحدة مصرفة.

يمنع سحب إصدار ما المشاريع الجديدة من الاعتماد على هذا الإصدار مع السماح لجميع المشاريع الحالية التي تعتمد عليه بالاستمرار، إذ يعني السحب أن جميع المشاريع التي تحتوي على Cargo.lock لن تتعطّل، ولن تستخدم أي ملفات Cargo.lock المستقبلية المنشأة الإصدار المسحوب.

لسحب نسخة من وحدة مصرفة، نفّذ cargo yank في دليل الوحدة المصرفة الذي نشرتَه سابقًا، وحدّد أي إصدار تريد إزالته. على سبيل المثال، إذا نشرنا وحدة مصرفة باسم guessing_game الإصدار 1.0.1 وأردنا انتزاعه، في مجلد المشروع guessing_game ننفّذ ما يلي:

$ cargo yank --vers 1.0.1
    Updating crates.io index
        Yank guessing_game@1.0.1

يمكنك أيضًا التراجع عن عملية السحب من خلال إضافة undo-- إلى الأمر والسماح للمشاريع بالاعتماد على الإصدار مرة أخرى:

$ cargo yank --vers 1.0.1 --undo
    Updating crates.io index
      Unyank guessing_game_:1.0.1

لا تحذف عملية السحب أي شيفرة برمجية، إذ من غير الممكن على سبيل المثال حذف بيانات حساسة رُفعَت بالخطأ. إذا حدث ذلك، يجب عليك إعادة تعيين تلك البيانات على الفور.

ترجمة -وبتصرف- لقسم من الفصل More About Cargo and Crates.io من كتاب The Rust Programming Language.