'\" t .TH "CARGO\-PACKAGE" "1" .nh .ad l .ss \n[.ss] 0 .SH "نام (NAME)" cargo\-package \- بسته‌بندی بسته محلی در یک tarball قابل توزیع .SH "خلاصه دستور (SYNOPSIS)" \fBcargo package\fR [\fIگزینه‌ها\fR] .SH "توضیحات (DESCRIPTION)" این دستور یک فایل فشرده و قابل توزیع با پسوند \fB\&.crate\fR شامل کد منبع بسته در دایرکتوری جاری ایجاد می‌کند. فایل خروجی در دایرکتوری \fBtarget/package\fR ذخیره خواهد شد. این فرمان مراحل زیر را انجام می‌دهد: .sp .RS 4 \h'-04' 1.\h'+01'بارگذاری و بررسی فضای کاری جاری و انجام برخی بررسی‌های اولیه. .sp .RS 4 \h'-04'\(bu\h'+03'وابستگی‌های مبتنی بر مسیر (path dependencies) مجاز نیستند مگر اینکه دارای کلید version باشند. Cargo کلید path را برای وابستگی‌ها در بسته‌های منتشرشده نادیده می‌گیرد. بخش \fBdev\-dependencies\fR این محدودیت را ندارد. .RE .RE .sp .RS 4 \h'-04' 2.\h'+01'ایجاد فایل فشرده‌ی \fB\&.crate\fR. .sp .RS 4 \h'-04'\(bu\h'+03'فایل اصلی \fBCargo.toml\fR بازنویسی و نرمال‌سازی می‌شود. .RE .sp .RS 4 \h'-04'\(bu\h'+03'بخش‌های \fB[patch]\fR، \fB[replace]\fR و \fB[workspace]\fR از مانیفست حذف می‌شوند. .RE .sp .RS 4 \h'-04'\(bu\h'+03'فایل \fBCargo.lock\fR همواره گنجانده می‌شود. در صورت نبود، یک فایل قفل جدید ایجاد می‌شود مگر اینکه از پرچم \fB\-\-exclude\-lockfile\fR استفاده شده باشد. در صورتی که پرچم \fB\-\-locked\fR تعیین گردد، دستور \fBcargo\-install\fR(1) از فایل قفل بسته‌بندی‌شده استفاده خواهد کرد. .RE .sp .RS 4 \h'-04'\(bu\h'+03'یک فایل \fB\&.cargo_vcs_info.json\fR قرار داده می‌شود که در صورت موجود بودن، حاوی اطلاعاتی پیرامون هش checkout فعلی VCS و همچنین پرچمی مبنی بر دست‌خورده بودن (dirty) درخت کاری است. .RE .sp .RS 4 \h'-04'\(bu\h'+03'پیوندهای نمادین (Symlinks) به فایل‌های مقصد خود تخت و تبدیل می‌شوند. .RE .sp .RS 4 \h'-04'\(bu\h'+03'فایل‌ها و دایرکتوری‌ها بر اساس قوانین ذکر شده در \fIفیلدهای \f(BI[include]\fI و \f(BI[exclude]\fR \& اضافه یا مستثنی می‌شوند. .RE .RE .sp .RS 4 \h'-04' 3.\h'+01'استخراج فایل \fB\&.crate\fR و ساخت آن جهت اطمینان از امکان‌پذیر بودن فرآیند ساخت. .sp .RS 4 \h'-04'\(bu\h'+03'این کار بسته شما را از ابتدا بازسازی می‌کند تا اطمینان حاصل شود که می‌تواند از یک وضعیت دست‌نخورده ساخته شود. می‌توان از پرچم \fB\-\-no\-verify\fR برای صرف‌نظر از این مرحله استفاده کرد. .RE .RE .sp .RS 4 \h'-04' 4.\h'+01'بررسی اینکه اسکریپت‌های ساخت هیچ‌یک از فایل‌های منبع را دستکاری نکرده باشند. .RE .sp فهرست فایل‌های گنجانده‌شده را می‌توان از طریق فیلدهای \fBinclude\fR و \fBexclude\fR در مانیفست مدیریت کرد. .sp برای جزئیات بیشتر پیرامون بسته‌بندی و انتشار، \fIمرجع\fR را ببینید. .SS "قالب .cargo_vcs_info.json (.cargo_vcs_info.json format)" یک فایل \fB\&.cargo_vcs_info.json\fR در قالب زیر تولید خواهد شد: .sp .RS 4 .nf { "git": { "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302", "dirty": true }, "path_in_vcs": "" } .fi .RE .sp مقدار \fBdirty\fR نشان می‌دهد که آیا درخت کاری Git در زمان ساخته شدن بسته دست‌خورده بوده است یا خیر. .sp مقدار \fBpath_in_vcs\fR برای بسته‌های موجود در زیردایرکتوری‌های مخزن کنترل نسخه، روی یک مسیر نسبی نسبت به مخزن تنظیم خواهد شد. .sp سازگاری این فایل تحت همان خط‌مشی خروجی JSON در دستور \fBcargo\-metadata\fR(1) حفظ و مدیریت می‌شود. .sp توجه داشته باشید که این فایل اطلاعات VCS را به صورت یک تصویر لحظه‌ای بر مبنای نهایت تلاش ممکن (best\-effort) ارائه می‌دهد. با این حال، اصالت و منشأ بسته اعتبارسنجی نمی‌شود. هیچ تضمینی وجود ندارد که کد منبع درون tarball دقیقاً با اطلاعات VCS مطابقت داشته باشد..SH "گزینه‌ها (OPTIONS)" .SS "گزینه‌های بسته (Package Options)" .sp \fB\-l\fR, \fB\-\-list\fR .RS 4 چاپ فایل‌های موجود در بسته بدون ساخت آن. .RE .sp \fB\-\-no\-verify\fR .RS 4 محتویات را با ساختن آن‌ها راستی‌آزمایی نمی‌کند. .RE .sp \fB\-\-no\-metadata\fR .RS 4 هشدارهای مربوط به نبود متاداده‌های قابل استفاده برای انسان (مانند توضیحات یا پروانه) را نادیده می‌گیرد. .RE .sp \fB\-\-allow\-dirty\fR .RS 4 اجازه می‌دهد دایرکتوری‌های کاری دارای تغییرات ثبت‌نشده در VCS بسته‌بندی شوند. .RE .sp \fB\-\-exclude\-lockfile\fR .RS 4 هنگام بسته‌بندی، فایل قفل (lock file) را لحاظ نمی‌کند. .sp این پرچم برای استفادهٔ عمومی نیست. برخی ابزارها ممکن است انتظار حضور یک فایل قفل را داشته باشند (مانند \fBcargo install \-\-locked\fR). پیش از استفاده از این گزینه، گزینه‌های دیگر را در نظر بگیرید. .RE .sp \fB\-\-index\fR \fIindex\fR .RS 4 آدرس URL مربوط به نمایهٔ (index) رجیستری مورد استفاده. .RE .sp \fB\-\-registry\fR \fIregistry\fR .RS 4 نام رجیستری برای بسته‌بندی؛ برای جزئیات بیشتر دربارهٔ پیکربندی نام‌های رجیستری، \fBcargo publish \-\-help\fR را ببینید. بسته‌ها در این رجیستری منتشر نخواهند شد، اما اگر در حال بسته‌بندی چندین crate وابسته به یکدیگر باشیم، فایل‌های قفل با این فرض که وابستگی‌ها در این رجیستری منتشر خواهند شد تولید می‌شوند. .RE .sp \fB\-\-message\-format\fR \fIfmt\fR .RS 4 قالب پیام خروجی را مشخص می‌کند. در حال حاضر، این گزینه فقط با \fB\-\-list\fR کار می‌کند و قالب فهرست فایل‌ها را تحت تأثیر قرار می‌دهد. این ویژگی ناپایدار است و به \fB\-Zunstable\-options\fR\& نیاز دارد. قالب‌های معتبر خروجی: .sp .RS 4 \h'-04'\(bu\h'+03'\fBhuman\fR (پیش‌فرض): نمایش در قالب یک فایل در هر خط. .RE .sp .RS 4 \h'-04'\(bu\h'+03'\fBjson\fR: تولید اطلاعات JSON ماشین‌خوان دربارهٔ هر بسته. یک بسته در هر خط JSON (به صورت Newline delimited JSON). .sp .RS 4 .nf { /* The Package ID Spec of the package. */ "id": "path+file:///home/foo#0.0.0", /* Files of this package */ "files" { /* Relative path in the archive file. */ "Cargo.toml.orig": { /* Where the file is from. \- "generate" for file being generated during packaging \- "copy" for file being copied from another location. */ "kind": "copy", /* For the "copy" kind, it is an absolute path to the actual file content. For the "generate" kind, it is the original file the generated one is based on. */ "path": "/home/foo/Cargo.toml" }, "Cargo.toml": { "kind": "generate", "path": "/home/foo/Cargo.toml" }, "src/main.rs": { "kind": "copy", "path": "/home/foo/src/main.rs" } } } .fi .RE .RE .RE.SS "انتخاب بسته (Package Selection)" به‌طور پیش‌فرض، هنگامی که هیچ گزینهٔ انتخاب بسته‌ای داده نشود، بسته‌های انتخاب‌شده به پروندهٔ مانیفستِ انتخاب‌شده بستگی دارند (بر اساس دایرکتوری کاری فعلی در صورتی که \fB\-\-manifest\-path\fR داده نشده باشد). اگر مانیفست ریشهٔ یک فضای کاری (workspace) باشد، اعضای پیش‌فرض فضای کاری انتخاب می‌شوند، در غیر این صورت تنها بسته‌ای که توسط مانیفست تعریف شده است انتخاب خواهد شد. .sp اعضای پیش‌فرض یک فضای کاری را می‌توان به‌صراحت با کلید \fBworkspace.default\-members\fR در مانیفست ریشه تنظیم کرد. اگر این کلید تنظیم نشده باشد، یک فضای کاری مجازی شامل تمام اعضای فضای کاری خواهد بود (معادل ارسال \fB\-\-workspace\fR)، و یک فضای کاری غیرمجازی تنها شامل خودِ کریت (crate) ریشه خواهد بود. .sp \fB\-p\fR \fIspec\fR\[u2026], \fB\-\-package\fR \fIspec\fR\[u2026] .RS 4 تنها بسته‌های مشخص‌شده را بسته‌بندی می‌کند. برای ساختار SPEC، \fBcargo\-pkgid\fR(1) را ببینید. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob در یونیکس مانند \fB*\fR، \fB?\fR و \fB[]\fR پشتیبانی می‌کند. با این حال، برای جلوگیری از بسط تصادفی الگوهای glob توسط شل پیش از پردازش آن‌ها توسط Cargo، باید در اطراف هر الگو از علامت نقل‌قول تکی یا دوگانه استفاده کنید. .RE .sp \fB\-\-workspace\fR .RS 4 تمام اعضای موجود در فضای کاری را بسته‌بندی می‌کند. .RE .sp \fB\-\-exclude\fR \fISPEC\fR\[u2026] .RS 4 بسته‌های مشخص‌شده را مستثنی می‌کند. باید همراه با پرچم \fB\-\-workspace\fR استفاده شود. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob در یونیکس مانند \fB*\fR، \fB?\fR و \fB[]\fR پشتیبانی می‌کند. با این حال، برای جلوگیری از بسط تصادفی الگوهای glob توسط شل پیش از پردازش آن‌ها توسط Cargo، باید در اطراف هر الگو از علامت نقل‌قول تکی یا دوگانه استفاده کنید. .RE .SS "گزینه‌های کامپایل (Compilation Options)" .sp \fB\-\-target\fR \fItriple\fR .RS 4 برای معماری مقصد (target) مشخص‌شده بسته‌بندی می‌کند. این پرچم می‌تواند چندین بار مشخص شود. پیش‌فرض، معماری میزبان (host) است. ساختار کلی سه‌گانه (triple) به‌صورت \fB\-\-\-\fR است\&. .sp مقادیر ممکن: .sp .RS 4 \h'-04'\(bu\h'+03'هر مقصد پشتیبانی‌شده در \fBrustc \-\-print target\-list\fR\&. .RE .sp .RS 4 \h'-04'\(bu\h'+03'\fB"host\-tuple"\fR که در داخل با مقصد میزبان جایگزین خواهد شد. این گزینه به‌ویژه زمانی مفید است که کریت‌هایی را به‌صورت متقاطع کامپایل می‌کنید و نمی‌خواهید ماشین میزبان خود را به عنوان یک مقصد مشخص کنید (برای مثال، یک \fBxtask\fR در یک پروژهٔ مشترک که ممکن است توسط چندین میزبان مختلف توسعه داده شود). .RE .sp .RS 4 \h'-04'\(bu\h'+03'مسیری به یک مشخصات سفارشی مقصد. برای اطلاعات بیشتر \fICustom Target Lookup Path\fR را ببینید. .RE .sp این مقدار همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBbuild.target\fR مشخص شود\&. .sp توجه داشته باشید که تعیین این پرچم باعث می‌شود Cargo در حالت متفاوتی اجرا شود که در آن مصنوعات (artifacts) مقصد در یک دایرکتوری جداگانه قرار می‌گیرند. برای جزئیات بیشتر مستندات \fIحافظه موقت ساخت (build cache)\fR را ببینید. .RE .sp \fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 دایرکتوری برای همهٔ مصنوعات تولیدشده و فایل‌های میانی. همچنین می‌تواند با متغیر محیطی \fBCARGO_TARGET_DIR\fR یا \fIمقدار پیکربندی\fR \fBbuild.target\-dir\fR مشخص شود\&. پیش‌فرض آن \fBtarget\fR در ریشهٔ فضای کاری است. .RE .SS "انتخاب ویژگی (Feature Selection)" پرچم‌های ویژگی به شما امکان می‌دهند فعال بودن ویژگی‌ها را کنترل کنید. هنگامی که هیچ گزینهٔ ویژگی داده نشود، ویژگی \fBdefault\fR برای هر بستهٔ انتخاب‌شده فعال می‌شود. .sp برای جزئیات بیشتر به \fIمستندات ویژگی‌ها\fR مراجعه کنید. .sp \fB\-F\fR \fIfeatures\fR, \fB\-\-features\fR \fIfeatures\fR .RS 4 فهرستی از ویژگی‌ها که با فاصله یا کاما از یکدیگر جدا شده‌اند تا فعال شوند. ویژگی‌های اعضای فضای کاری را می‌توان با نحو \fBpackage\-name/feature\-name\fR فعال کرد. این پرچم را می‌توان چندین بار مشخص کرد، که تمام ویژگی‌های مشخص‌شده را فعال می‌کند. .RE .sp \fB\-\-all\-features\fR .RS 4 تمام ویژگی‌های موجود همهٔ بسته‌های انتخاب‌شده را فعال می‌کند. .RE .sp \fB\-\-no\-default\-features\fR .RS 4 ویژگی \fBdefault\fR بسته‌های انتخاب‌شده را فعال نمی‌کند. .RE.SS "گزینه‌های مانیفست (Manifest Options)" .sp \fB\-\-manifest\-path\fR \fIpath\fR .RS 4 مسیر فایل \fBCargo.toml\fR. به‌طور پیش‌فرض، Cargo به دنبال فایل \fBCargo.toml\fR در دایرکتوری جاری یا هر یک از دایرکتوری‌های والد می‌گردد. .RE .sp \fB\-\-locked\fR .RS 4 اطمینان حاصل می‌کند که دقیقاً همان وابستگی‌ها و نسخه‌هایی به کار روند که هنگام تولید اولیهٔ فایل موجود \fBCargo.lock\fR استفاده شده بودند. در صورت وقوع هر یک از سناریوهای زیر، Cargo با یک خطا خارج خواهد شد: .sp .RS 4 \h'-04'\(bu\h'+03'فایل lock وجود نداشته باشد. .RE .sp .RS 4 \h'-04'\(bu\h'+03'‏Cargo به دلیل حل وابستگیِ متفاوت، برای تغییر فایل lock تلاش کند. .RE .sp می‌توان از این گزینه در محیط‌هایی که ساخت‌های قطعی (deterministic builds) مورد نیاز است، مانند خطوط لولهٔ CI استفاده کرد. .RE .sp \fB\-\-offline\fR .RS 4 از دسترسی Cargo به شبکه به هر دلیلی جلوگیری می‌کند. بدون این پرچم، اگر Cargo نیاز به دسترسی به شبکه داشته باشد و شبکه در دسترس نباشد، با یک خطا متوقف خواهد شد. با این پرچم، Cargo در صورت امکان تلاش خواهد کرد بدون شبکه به کار خود ادامه دهد. .sp توجه داشته باشید که این ممکن است منجر به حل وابستگی متفاوتی نسبت به حالت آنلاین شود. Cargo خود را به crateهایی که به‌صورت محلی دانلود شده‌اند محدود می‌کند، حتی اگر طبق نسخهٔ محلی نمایه، نسخهٔ جدیدتری موجود باشد. برای دانلود وابستگی‌ها قبل از آفلاین شدن، دستور \fBcargo\-fetch\fR(1) را ببینید. .sp همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBnet.offline\fR مشخص شود \&. .RE .sp \fB\-\-frozen\fR .RS 4 معادل تعیین هر دو گزینهٔ \fB\-\-locked\fR و \fB\-\-offline\fR به‌طور هم‌زمان است\&. .RE .SS "گزینه‌های متفرقه (Miscellaneous Options)" .sp \fB\-j\fR \fIN\fR, \fB\-\-jobs\fR \fIN\fR .RS 4 تعداد وظایف موازی برای اجرا. همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBbuild.jobs\fR مشخص شود \&. پیش‌فرض، تعداد پردازنده‌های منطقی است. اگر منفی باشد، حداکثر تعداد وظایف موازی را روی تعداد پردازنده‌های منطقی به‌علاوهٔ مقدار ارائه‌شده تنظیم می‌کند. اگر رشتهٔ \fBdefault\fR ارائه شود، مقدار را به حالت پیش‌فرض بازمی‌گرداند. نباید 0 باشد. .RE .sp \fB\-\-keep\-going\fR .RS 4 تا حد امکان بیشترین crateهای موجود در گراف وابستگی را می‌سازد، به جای اینکه با اولین خطای ساخت، فرآیند را متوقف کند. .sp برای مثال اگر بستهٔ فعلی به وابستگی‌های \fBfails\fR و \fBworks\fR وابسته باشد و ساخت یکی از آن‌ها با خطا مواجه شود، دستور \fBcargo package \-j1\fR ممکن است آن موردی را که ساختش موفق است بسازد یا نسازد (بسته به اینکه Cargo ابتدا کدام‌یک از این دو ساخت را برای اجرا انتخاب کند)، در حالی که دستور \fBcargo package \-j1 \-\-keep\-going\fR قطعاً هر دو ساخت را اجرا خواهد کرد، حتی اگر ساخت اول با خطا متوقف شود. .RE .SS "گزینه‌های نمایش (Display Options)" .sp \fB\-v\fR, \fB\-\-verbose\fR .RS 4 استفاده از خروجی پرگو. می‌تواند دو بار برای خروجی \[lq]بسیار پرگو\[rq] مشخص شود که شامل اطلاعات خروجی اضافی مانند هشدارهای وابستگی و خروجی اسکریپت ساخت است. همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBterm.verbose\fR مشخص شود \&. .RE .sp \fB\-q\fR, \fB\-\-quiet\fR .RS 4 پیام‌های لاگ cargo را چاپ نمی‌کند. همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBterm.quiet\fR مشخص شود \&. .RE .sp \fB\-\-color\fR \fIwhen\fR .RS 4 کنترل زمان استفاده از خروجی رنگی. مقادیر معتبر: .sp .RS 4 \h'-04'\(bu\h'+03'\fBauto\fR (پیش‌فرض): تشخیص خودکار در دسترس بودن پشتیبانی از رنگ در ترمینال. .RE .sp .RS 4 \h'-04'\(bu\h'+03'\fBalways\fR: همیشه رنگ‌ها را نمایش می‌دهد. .RE .sp .RS 4 \h'-04'\(bu\h'+03'\fBnever\fR: هرگز رنگ‌ها را نمایش نمی‌دهد. .RE .sp همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBterm.color\fR مشخص شود \&. .RE.SS "گزینه‌های عمومی (Common Options)" .sp \fB+\fR\fItoolchain\fR .RS 4 اگر Cargo با rustup نصب شده باشد، و نخستین آرگومان \fBcargo\fR با \fB+\fR آغاز شود، به‌عنوان نام یک زنجیره‌ابزار rustup تفسیر خواهد شد (مانند \fB+stable\fR یا \fB+nightly\fR). برای اطلاعات بیشتر درباره نحوه کارکرد جایگزینی زنجیره‌ابزار، \fIمستندات rustup\fR را ببینید. .RE .sp \fB\-\-config\fR \fIKEY=VALUE\fR یا \fIPATH\fR .RS 4 یک مقدار پیکربندی Cargo را بازنویسی می‌کند. آرگومان باید در قالب نحو TOML به‌صورت \fBKEY=VALUE\fR باشد، یا به‌صورت مسیری به یک فایل پیکربندی اضافی ارائه شود. این گزینه را می‌توان چندین بار مشخص کرد. برای اطلاعات بیشتر \fIبخش بازنویسی‌های خط فرمان\fR را ببینید. .RE .sp \fB\-C\fR \fIPATH\fR .RS 4 دایرکتوری کاری فعلی را پیش از اجرای هر عملیات مشخص‌شده تغییر می‌دهد. این امر مواردی مانند جایی که cargo به‌طور پیش‌فرض به دنبال مانیفست پروژه (\fBCargo.toml\fR) می‌گردد، و همچنین دایرکتوری‌های جستجو شده برای یافتن \fB\&.cargo/config.toml\fR را تحت تأثیر قرار می‌دهد. این گزینه باید پیش از نام دستور قرار گیرد، برای مثال \fBcargo \-C path/to/my\-project build\fR\&. .sp این گزینه فقط در \fIکانال nightly\fR در دسترس است و برای فعال‌سازی به پرچم \fB\-Z unstable\-options\fR نیاز دارد (به \fI#10098\fR مراجعه کنید). .RE .sp \fB\-h\fR, \fB\-\-help\fR .RS 4 اطلاعات راهنما را نمایش می‌دهد. .RE .sp \fB\-Z\fR \fIflag\fR .RS 4 پرچم‌های ناپایدار (فقط ویژه nightly) برای Cargo. برای جزئیات بیشتر \fBcargo \-Z help\fR را اجرا کنید. .RE .SH "محیط (ENVIRONMENT)" برای جزئیات درباره متغیرهای محیطی که Cargo می‌خواند، \fIمرجع\fR را ببینید. .SH "وضعیت خروج (EXIT STATUS)" .sp .RS 4 \h'-04'\(bu\h'+03'\fB0\fR: دستور Cargo با موفقیت پایان یافت. .RE .sp .RS 4 \h'-04'\(bu\h'+03'\fB101\fR: اجرای Cargo با شکست مواجه شد. .RE .SH "مثال‌ها (EXAMPLES)" .sp .RS 4 \h'-04' 1.\h'+01'ایجاد یک فایل فشرده \fB\&.crate\fR از بسته فعلی: .sp .RS 4 .nf cargo package .fi .RE .RE .SH "همچنین ببینید (SEE ALSO)" \fBcargo\fR(1), \fBcargo\-publish\fR(1)