بسته‌های Rust (crate)

مدیر بستهٔ Rust، یعنی **cargo**، می‌تواند crateها را از بیش از یک رجیستری بیاورد. یک بار زرین را به آن معرفی می‌کنید و از آن به بعد `cargo publish`، `cargo add` و `cargo build` با زرین همان‌طور کار می‌کنند که با crates.io. > فقط می‌خواهید crates.io سریع‌تر دانلود شود؟ به هیچ‌کدام از این صفحه نیاز ندارید: [آینهٔ crates.io](/docs/fa/package-mirrors#crateهای-rust) را ببینید. خود Rust نصب نمی‌شود چون static.rust-lang.org در دسترس نیست؟ [rustup از راه زرین](/docs/fa/package-mirrors#خود-rust-rustup) را ببینید. ## زرین را به cargo معرفی کنید (یک بار برای هر رایانه) فایل `~/.cargo/config.toml` را باز کنید (یا بسازید)؛ فایل تنظیماتی که cargo هر بار می‌خواند. این را اضافه کنید: ```toml [registries.zaryn] index = "sparse+https://api.zaryn.xyz/v1/packages/cargo/index/" ``` - `[registries.zaryn]` به رجیستری نام کوتاه `zaryn` می‌دهد که در دستورها به کار می‌برید. - `index` جایی است که cargo می‌پرسد چه crateها و چه نسخه‌هایی هست. `sparse+` یعنی برای هر crate یک فایل کوچک می‌خواهد، نه فهرست همه چیز. ## توکن بگیرید و وارد شوید در [بسته‌ها](/packages) دکمهٔ **ساخت توکن انتشار** را بزنید و توکن را کپی کنید. سپس: ```bash cargo login --registry zaryn ``` وقتی cargo پرسید، توکن را بچسبانید. cargo آن را در `~/.cargo/credentials.toml` نگه می‌دارد، پس فقط یک بار لازم است. ## انتشار در `Cargo.toml` بخش `[package]` باید `description` و `license` داشته باشد. بگویید کجا می‌شود منتشرش کرد: ```toml [package] name = "hello-zaryn" version = "0.1.0" edition = "2021" description = "Says hello" license = "MIT" publish = ["zaryn"] # فقط زرین؛ هیچ‌وقت اشتباهی در crates.io منتشر نمی‌شود ``` سپس: ```bash cargo publish --registry zaryn ``` cargo یک بار crate را می‌سازد تا مطمئن شود کامپایل می‌شود، آن را در یک فایل `.crate` می‌گذارد و بارگذاری می‌کند. crate بی‌درنگ در [بسته‌ها](/packages) دیده می‌شود. برای انتشار اصلاحیه، `version` را بالا ببرید (مثلاً `0.1.1`) و دوباره `cargo publish --registry zaryn` را اجرا کنید. نسخه‌ای که منتشر شده جایگزین نمی‌شود. ## استفاده در پروژهٔ دیگر ```bash cargo add --registry zaryn hello-zaryn ``` این خط به `Cargo.toml` اضافه می‌شود (دستی هم می‌توانید بنویسید): ```toml [dependencies] hello-zaryn = { version = "0.1", registry = "zaryn" } ``` `cargo build` آن را از زرین دانلود می‌کند. crate شما می‌تواند مثل همیشه به crateهای crates.io وابسته باشد؛ cargo هر کدام را از جای خودش می‌آورد. ## crateهای خصوصی (پریمیوم) crate در صفحهٔ خودش خصوصی می‌شود: از [بسته‌ها](/packages) بازش کنید و **خصوصی کردن** را بزنید. فقط شما، یا اعضای سازمانی که مالکش است، می‌توانند ببینند و نصبش کنند. خواندن crate خصوصی در هر درخواست به توکن نیاز دارد، پس از راه نام دومی می‌رود: ```toml [registries.zaryn-private] index = "sparse+https://api.zaryn.xyz/v1/packages/cargo/private/index/" credential-provider = "cargo:token" ``` ```bash cargo login --registry zaryn-private cargo add --registry zaryn-private my-secret-crate ``` فهرست خصوصی crateهای عمومی شما را هم نشان می‌دهد، پس یک تیم می‌تواند فقط از `zaryn-private` استفاده کند. ## دستورهای روزمره | برای… | اجرا کنید | |---|---| | جست‌وجوی crate در زرین | `cargo search --registry zaryn hello` | | پنهان کردن نسخهٔ خراب | `cargo yank --registry zaryn --version 0.1.0 hello-zaryn` | | برگرداندنش | `cargo yank --registry zaryn --version 0.1.0 --undo hello-zaryn` | yank چیزی را پاک نمی‌کند: پروژه‌هایی که `Cargo.lock`شان از قبل آن نسخه را دارد ساخته می‌شوند. فقط پروژه‌های تازه انتخابش نمی‌کنند. ## وقتی چیزی درست کار نمی‌کند | cargo می‌گوید | یعنی | راه‌حل | |---|---|---| | `401` یا "this index needs a token" | cargo برای این رجیستری توکن ندارد | `cargo login --registry zaryn` (یا `zaryn-private`) | | "this token can't publish packages" | توکن مجوز `package:write` ندارد | در [بسته‌ها](/packages) توکن تازه بسازید | | "this package name belongs to someone else" | حساب دیگری زودتر این نام را منتشر کرده | نام دیگری انتخاب کنید | | "crate `foo_bar` already exists…" | `foo-bar` و `foo_bar` یک نام حساب می‌شوند، مثل crates.io | نام دیگری انتخاب کنید | | "this version is already published" | نسخه‌ها جایگزین نمی‌شوند | `version` را در `Cargo.toml` بالا ببرید | | "package storage on the Free plan is full" | بسته‌ها و ایمیج‌هایتان ۵۰۰ مگابایت شده‌اند | نسخه‌های yankشده هم حساب می‌شوند؛ [پریمیوم](/billing) ۱۰۰ گیگابایت دارد | | `no matching package named …` | نام رجیستری اشتباه است، یا crate خصوصی از راه `zaryn` خواسته شده | `registry =` را در `Cargo.toml` بررسی کنید | ## پشت صحنه زرین به پروتکل خود cargo حرف می‌زند: فهرست sparse (یک فایل برای هر crate با همهٔ نسخه‌ها، وابستگی‌ها و featureهایش)، نشانی دانلود، و API انتشار، yank و جست‌وجو. هر فایل `.crate` با هش SHA-256 اش نگه داشته می‌شود و همان هش در فهرست هست؛ پس cargo هر دانلود را می‌سنجد و فایلی را که جور نباشد رد می‌کند.