CARGO-PUBLISH(1) General Commands Manual CARGO-PUBLISH(1)

cargo-publish - بارگذاری یک بسته در رجیستری

cargo publish [options]

این دستور یک فایل فشرده و قابل توزیع .crate شامل کد منبع بسته در دایرکتوری جاری ایجاد کرده و آن را در یک رجیستری بارگذاری می‌کند. رجیستری پیش‌فرض https://crates.io است. این دستور مراحل زیر را انجام می‌دهد:

1.انجام چند بررسی، از جمله:
•بررسی کلید package.publish در مانیفست برای محدودیت‌های مربوط به رجیستری‌هایی که مجاز به انتشار در آن‌ها هستید.
2.ایجاد یک فایل .crate با دنبال کردن مراحل موجود در cargo-package(1).
3.بارگذاری crate در رجیستری. سرور بررسی‌های بیشتری را روی crate انجام خواهد داد.
4.کلاینت با ارسال درخواست‌های مکرر منتظر نمایان شدن بسته در نمایه (index) می‌ماند، و ممکن است با پایان مهلت زمانی (timeout) مواجه شود. در این صورت، باید تکمیل فرایند را به صورت دستی بررسی کنید. این پایان مهلت زمانی اثری بر بارگذاری نخواهد داشت.

این دستور مستلزم احراز هویت شما با استفاده از cargo-login(1) یا متغیرهای محیطی فیلدهای پیکربندی registry.token https://doc.rust-lang.org/cargo/reference/config.html#registrytoken و registries.<name>.token https://doc.rust-lang.org/cargo/reference/config.html#registriesnametoken است.

برای جزئیات بیشتر درباره بسته‌بندی و انتشار، مرجع مستندات https://doc.rust-lang.org/cargo/reference/publishing.html را ببینید.

--dry-run

انجام تمام بررسی‌ها بدون بارگذاری.

--no-verify

عدم اعتبارسنجی محتویات از طریق ساخت (build) آن‌ها.

--allow-dirty

اجازه به بسته‌بندی دایرکتوری‌های کاری حاوی تغییرات ثبت‌نشده (uncommitted) در سامانه کنترل نسخه (VCS).

--index index

نشانی URL مربوط به نمایه (index) رجیستری مورد استفاده.

--registry registry

نام رجیستری برای انتشار. نام‌های رجیستری در فایل‌های پیکربندی Cargo https://doc.rust-lang.org/cargo/reference/config.html تعریف می‌شوند. در صورت مشخص نشدن، و چنانچه فیلد package.publish https://doc.rust-lang.org/cargo/reference/manifest.html#the-publish-field در Cargo.toml با یک رجیستری واحد وجود داشته باشد، در آن رجیستری منتشر خواهد شد. در غیر این صورت از رجیستری پیش‌فرض استفاده می‌کند که توسط کلید پیکربندی registry.default https://doc.rust-lang.org/cargo/reference/config.html#registrydefault مشخص می‌شود و مقدار پیش‌فرض آن crates-io است.

به‌طور پیش‌فرض، زمانی که هیچ گزینه‌ای برای انتخاب بسته داده نشود، بسته‌های انتخاب‌شده به فایل مانیفست انتخابی بستگی دارند (در صورتی که --manifest-path مشخص نشده باشد، بر اساس دایرکتوری کاری فعلی). اگر مانیفست ریشه یک فضای کاری (workspace) باشد، اعضای پیش‌فرض فضای کاری انتخاب می‌شوند، در غیر این صورت تنها بسته تعریف‌شده توسط مانیفست انتخاب خواهد شد.

اعضای پیش‌فرض یک فضای کاری را می‌توان به‌صراحت با کلید workspace.default-members در مانیفست ریشه تنظیم کرد. در صورت عدم تنظیم، یک فضای کاری مجازی شامل تمام اعضای فضای کاری خواهد بود (معادل ارسال --workspace)، و یک فضای کاری غیرمجازی تنها شامل خود crate ریشه خواهد بود.

-p spec…, --package spec…

فقط بسته‌های مشخص‌شده را منتشر می‌کند. برای ساختار SPEC، cargo-pkgid(1) را ببینید. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای متداول glob یونیکس مانند *، ? و [] پشتیبانی می‌کند. با این حال، برای جلوگیری از بسط تصادفی الگوهای glob توسط شل پیش از پردازش Cargo، باید در اطراف هر الگو از علامت‌های نقل‌قول تکی یا جفتی استفاده کنید.

--workspace

تمام اعضای موجود در فضای کاری را منتشر می‌کند.

--all

نام مستعار منسوخ‌شده برای --workspace.

--exclude SPEC…

مستثنی کردن بسته‌های مشخص‌شده. باید همراه با پرچم --workspace استفاده شود. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای متداول glob یونیکس مانند *، ? و [] پشتیبانی می‌کند. با این حال، برای جلوگیری از بسط تصادفی الگوهای glob توسط شل پیش از پردازش Cargo، باید در اطراف هر الگو از علامت‌های نقل‌قول تکی یا جفتی استفاده کنید.

--target triple

برای معماری مقصد مشخص‌شده منتشر می‌کند. این پرچم را می‌توان چندین بار مشخص کرد. پیش‌فرض، معماری میزبان است. قالب کلی سه‌گانه (triple) به این صورت است: <arch><sub>-<vendor>-<sys>-<abi>.

مقدارهای ممکن:

•هر مقصد پشتیبانی‌شده در rustc --print target-list.
•"host-tuple"، که در درون با مقصد میزبان جایگزین خواهد شد. این گزینه به ویژه زمانی مفید است که در حال کامپایل متقاطع (cross-compiling) برخی crateها هستید و نمی‌خواهید ماشین میزبان خود را به عنوان یک مقصد مشخص کنید (برای نمونه، یک xtask در پروژه‌ای مشترک که ممکن است توسط چندین میزبان مختلف توسعه داده شود).
•مسیری به یک مشخصات مقصد سفارشی. برای اطلاعات بیشتر Custom Target Lookup Path https://doc.rust-lang.org/rustc/targets/custom.html#custom-target-lookup-path را ببینید.

این مقدار همچنین می‌تواند با مقدار پیکربندی build.target https://doc.rust-lang.org/cargo/reference/config.html مشخص شود.

توجه داشته باشید که تعیین این پرچم باعث می‌شود Cargo در حالت متفاوتی اجرا شود که در آن مصنوعات (artifacts) مقصد در یک دایرکتوری جداگانه قرار می‌گیرند. برای جزئیات بیشتر، مستندات build cache https://doc.rust-lang.org/cargo/reference/build-cache.html را ببینید.

--target-dir directory

دایرکتوری برای همهٔ مصنوعات و فایل‌های میانی تولیدشده. همچنین می‌تواند با متغیر محیطی CARGO_TARGET_DIR یا مقدار پیکربندی build.target-dir https://doc.rust-lang.org/cargo/reference/config.html مشخص شود. پیش‌فرض آن دایرکتوری target در ریشهٔ فضای کاری (workspace) است.

پرچم‌های ویژگی به شما اجازه می‌دهند تعیین کنید کدام ویژگی‌ها فعال باشند. هنگامی که هیچ گزینهٔ ویژگی مشخص نشده باشد، ویژگی default برای هر بستهٔ انتخاب‌شده فعال می‌شود.

برای جزئیات بیشتر، مستندات ویژگی‌ها https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options را ببینید.

-F features, --features features

فهرستی از ویژگی‌ها جداشده با فاصله یا کاما برای فعال‌سازی. ویژگی‌های اعضای فضای کاری را می‌توان با نحو package-name/feature-name فعال کرد. این پرچم را می‌توان چندین بار مشخص کرد که تمام ویژگی‌های مشخص‌شده را فعال می‌کند.

--all-features

تمام ویژگی‌های موجود در همهٔ بسته‌های انتخاب‌شده را فعال می‌کند.

--no-default-features

ویژگی default بسته‌های انتخاب‌شده را فعال نمی‌کند.

--manifest-path path

مسیر فایل Cargo.toml. به‌طور پیش‌فرض، Cargo فایل Cargo.toml را در دایرکتوری جاری یا هر یک از دایرکتوری‌های والد جستجو می‌کند.

--locked

تضمین می‌کند که دقیقاً همان وابستگی‌ها و نسخه‌هایی به کار می‌روند که در زمان تولید اولیهٔ فایل موجود Cargo.lock ثبت شده بودند. در صورت وقوع هر یک از حالت‌های زیر، Cargo با یک خطا خارج خواهد شد:
•فایل lock وجود نداشته باشد.
•‏Cargo به دلیل حل وابستگی متفاوت، برای تغییر دادن فایل lock تلاش کند.

این گزینه می‌تواند در محیط‌هایی که ساخت‌های قطعی (deterministic builds) مد نظر است، مانند خطوط لولهٔ یکپارچه‌سازی مداوم (CI) استفاده شود.

--offline

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

توجه داشته باشید که این ممکن است به حل وابستگی متفاوتی نسبت به حالت آنلاین منجر شود. Cargo خود را به crateهایی که به‌صورت محلی بارگیری شده‌اند محدود می‌کند، حتی اگر طبق نسخهٔ محلی نمایه (index)، نسخهٔ جدیدتری موجود باشد. برای بارگیری وابستگی‌ها پیش از رفتن به حالت آفلاین، دستور cargo-fetch(1) را ببینید.

همچنین می‌تواند با مقدار پیکربندی net.offline https://doc.rust-lang.org/cargo/reference/config.html مشخص شود.

--frozen

معادل مشخص کردن هم‌زمان هر دو پرچم --locked و --offline است.

-j N, --jobs N

تعداد کارهای موازی برای اجرا. همچنین می‌تواند با مقدار پیکربندی build.jobs https://doc.rust-lang.org/cargo/reference/config.html مشخص شود. پیش‌فرض آن تعداد CPUهای منطقی است. اگر منفی باشد، حداکثر تعداد کارهای موازی را روی تعداد CPUهای منطقی به‌علاوهٔ مقدار ارائه‌شده تنظیم می‌کند. اگر رشتهٔ default ارائه شود، مقدار را به حالت پیش‌فرض بازمی‌گرداند. نباید 0 باشد.

--keep-going

تا جای ممکن بیشترین تعداد کریت (crate) در گراف وابستگی را می‌سازد، به جای اینکه با شکست اولین مورد در ساخت، فرایند متوقف شود.

برای مثال اگر بستهٔ کنونی به وابستگی‌های fails و works وابسته باشد که ساخت یکی از آن‌ها با شکست مواجه می‌شود، cargo publish -j1 ممکن است موردی را که موفق می‌شود بسازد یا نسازد (بسته به اینکه Cargo کدام‌یک از دو ساخت را ابتدا برای اجرا برگزیده باشد)، در حالی که cargo publish -j1 --keep-going قطعاً هر دو ساخت را اجرا خواهد کرد، حتی اگر موردی که ابتدا اجرا می‌شود شکست بخورد.

-v, --verbose

استفاده از خروجی با جزئیات بیشتر. برای خروجی “بسیار پرجزئیات” می‌تواند دو بار مشخص شود که شامل اطلاعات اضافی مانند هشدارهای وابستگی و خروجی اسکریپت ساخت است. همچنین می‌تواند با مقدار پیکربندی term.verbose https://doc.rust-lang.org/cargo/reference/config.html مشخص شود.

-q, --quiet

پیام‌های لاگ cargo را چاپ نمی‌کند. همچنین می‌تواند با مقدار پیکربندی term.quiet https://doc.rust-lang.org/cargo/reference/config.html مشخص شود.

--color when

زمان استفاده از خروجی رنگی را کنترل می‌کند. مقادیر معتبر:
•auto (پیش‌فرض): به‌طور خودکار وجود پشتیبانی از رنگ در ترمینال را تشخیص می‌دهد.
•always: همیشه رنگ‌ها را نمایش می‌دهد.
•never: هرگز رنگ‌ها را نمایش نمی‌دهد.

همچنین می‌تواند با مقدار پیکربندی term.color https://doc.rust-lang.org/cargo/reference/config.html مشخص شود.

+toolchain

اگر Cargo با rustup نصب شده باشد و اولین آرگومان cargo با + شروع شود، به عنوان نام زنجیره ابزار (toolchain) ابزار rustup تفسیر خواهد شد (مانند +stable یا +nightly). برای اطلاعات بیشتر در مورد چگونگی کارکرد بازنویسی زنجیره ابزار، به مستندات rustup https://rust-lang.github.io/rustup/overrides.html مراجعه کنید.

--config KEY=VALUE یا PATH

یک مقدار پیکربندی Cargo را بازنویسی می‌کند. آرگومان باید در ساختار دستوری TOML به‌صورت KEY=VALUE باشد، یا به عنوان مسیر یک فایل پیکربندی اضافی ارائه شود. این پرچم می‌تواند چندین بار مشخص شود. برای اطلاعات بیشتر به بخش بازنویسی‌های خط فرمان https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides مراجعه کنید.

-C PATH

دایرکتوری کاری فعلی را پیش از اجرای هرگونه عملیات مشخص‌شده تغییر می‌دهد. این موضوع مواردی از قبیل مکانی که cargo به‌طور پیش‌فرض به دنبال مانیفست پروژه (Cargo.toml) می‌گردد، و همچنین دایرکتوری‌های جستجو شده برای کشف .cargo/config.toml را تحت تأثیر قرار می‌دهد. این گزینه باید پیش از نام دستور قرار گیرد، برای مثال cargo -C path/to/my-project build.

این گزینه تنها در کانال nightly https://doc.rust-lang.org/book/appendix-07-nightly-rust.html در دسترس است و برای فعال‌سازی به پرچم -Z unstable-options نیاز دارد (به #10098 https://github.com/rust-lang/cargo/issues/10098 مراجعه کنید).

-h, --help

اطلاعات راهنما را چاپ می‌کند.

-Z flag

پرچم‌های ناپایدار (فقط ویژهٔ nightly) برای Cargo. برای جزئیات بیشتر، cargo -Z help را اجرا کنید. برای جزئیات درباره متغیرهای محیطی که Cargo می‌خواند، مرجع https://doc.rust-lang.org/cargo/reference/environment-variables.html را ببینید.

•0: اجرای Cargo با موفقیت انجام شد.
•101: اجرای Cargo ناموفق بود و کامل نشد.

1.انتشار بسته فعلی: 
cargo publish

cargo(1), cargo-package(1), cargo-login(1)