انتشار یک Crate

آموزش Rust

مقدمه

یکی از نقاط قوت بزرگ اکوسیستم Rust، رجیستری پکیج‌های عمومی آن، یعنی crates.io است. این وب‌سایت میزبان هزاران کتابخانه (crate) متن‌باز است که توسط جامعه توسعه‌دهندگان Rust ایجاد شده‌اند و شما می‌توانید به راحتی از آنها در پروژه‌های خود به عنوان وابستگی استفاده کنید. وقتی شما یک کتابخانه مفید می‌نویسید، می‌توانید با انتشار آن در crates.io، آن را با دیگران به اشتراک بگذارید.

در این درس، ما مراحل لازم برای آماده‌سازی و انتشار یک crate را بررسی خواهیم کرد.

آماده‌سازی یک Crate برای انتشار

قبل از انتشار، باید مطمئن شویم که crate ما دارای مستندات خوب و متادیتای لازم برای شناسایی در crates.io است.

افزودن متادیتای لازم

فایل Cargo.toml قلب پکیج شماست. برای اینکه Cargo بتواند پکیج شما را در crates.io منتشر کند، باید اطلاعات متادیتا را در بخش [package] این فایل تکمیل کنید.

  • name: نام پکیج شما.
  • version: شماره نسخه پکیج شما که از نسخه‌بندی معنایی (Semantic Versioning) پیروی می‌کند.
  • authors: نام و ایمیل شما.
  • edition: نسخه Rust که پکیج شما با آن سازگار است.
  • description: یک توضیح کوتاه درباره کاری که پکیج شما انجام می‌دهد.
  • license: شناسه لایسنس نرم‌افزاری که تحت آن پکیج خود را منتشر می‌کنید (مثلاً "MIT").
Copy Icon Cargo.toml 
[package]
name = "my_crate"
version = "0.1.0"
edition = "2021"
authors = ["Your Name <you@example.com>"]
description = "A short description of my crate."
license = "MIT"

تکمیل این اطلاعات به دیگران کمک می‌کند تا پکیج شما را پیدا کرده و به آن اعتماد کنند.

فرآیند انتشار

پس از تکمیل متادیتا و مستندات، فرآیند انتشار با استفاده از Cargo بسیار ساده است.

۱. ایجاد حساب کاربری در crates.io

ابتدا باید به وب‌سایت crates.io رفته و با استفاده از حساب کاربری GitHub خود، یک حساب ایجاد کنید.

۲. لاگین کردن با Cargo

پس از ایجاد حساب، باید در صفحه تنظیمات حساب خود یک توکن API ایجاد کنید. سپس، با استفاده از دستور cargo login و وارد کردن توکن، به Cargo اجازه می‌دهید تا از طرف شما پکیج‌ها را منتشر کند. 

$ cargo login YOUR_API_TOKEN

این توکن یک اطلاعات محرمانه است و نباید آن را با کسی به اشتراک بگذارید. Cargo آن را به صورت امن در کامپیوتر شما ذخیره می‌کند.

۳. انتشار پکیج

حالا همه چیز برای انتشار آماده است. با اجرای دستور cargo publish در پوشه پروژه خود، Cargo چند کار را انجام می‌دهد:

  1. پکیج شما را به صورت فشرده بسته‌بندی می‌کند.
  2. آن را در رجیستری crates.io آپلود می‌کند.
  3. اطلاعات متادیتای شما را در رجیستری ثبت می‌کند تا قابل جستجو باشد.
$ cargo publish

اگر همه چیز به درستی انجام شود، پکیج شما اکنون برای تمام دنیا در دسترس است و دیگران می‌توانند با افزودن آن به فایل Cargo.toml خود، از آن استفاده کنند.

انتشار نسخه‌های جدید

پس از انتشار نسخه اولیه، ممکن است بخواهید باگ‌ها را رفع کرده یا قابلیت‌های جدیدی اضافه کنید. برای انتشار یک نسخه جدید، کافیست شماره نسخه را در فایل Cargo.toml خود (بر اساس قوانین نسخه‌بندی معنایی) افزایش داده و سپس دوباره دستور cargo publish را اجرا کنید. crates.io از بازنویسی نسخه‌های قبلی جلوگیری می‌کند تا از پایداری پروژه‌هایی که به پکیج شما وابسته‌اند، محافظت کند.

حذف نسخه‌ها با cargo yank

شما نمی‌توانید یک نسخه از یک crate را به طور کامل از crates.io حذف کنید، زیرا این کار می‌تواند پروژه‌هایی را که به آن وابسته هستند، دچار مشکل کند. اما اگر یک نسخه مشکل‌دار را منتشر کرده‌اید، می‌توانید آن را "yank" کنید.

دستور cargo yank --vers VERSION_NUMBER به crates.io می‌گوید که پروژه‌های جدید نباید به این نسخه خاص وابسته شوند، اما تمام پروژه‌هایی که از قبل به آن وابسته بوده‌اند، همچنان می‌توانند آن را دانلود و استفاده کنند. این یک راه حل میانه برای جلوگیری از گسترش یک نسخه بد، بدون شکستن پروژه‌های موجود است.

در این درس با فرآیند انتشار یک crate در رجیستری عمومی crates.io آشنا شدیم. دیدیم که چگونه با افزودن متادیتا و استفاده از دستورات cargo login و cargo publish، می‌توانیم کدهای خود را به راحتی با جامعه بزرگ Rust به اشتراک بگذاریم. در درس بعدی، به بررسی «کاربرد Cargo Workspaces» خواهیم پرداخت، یک قابلیت قدرتمند برای مدیریت چندین پکیج مرتبط در یک پروژه واحد.