'\" t
.TH "CARGO\-BENCH" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "نام (NAME)"
cargo\-bench \- اجرای بنچ‌مارک‌های یک بسته
.SH "خلاصه دستور (SYNOPSIS)"
\fBcargo bench\fR [\fIoptions\fR] [\fIbenchname\fR] [\fB\-\-\fR \fIbench\-options\fR]
.SH "توضیحات (DESCRIPTION)"
کامپایل و اجرای بنچ‌مارک‌ها.
.sp
آرگومان فیلتر بنچ‌مارک \fIbenchname\fR و تمام آرگومان‌های پس از
دو خط تیره (\fB\-\-\fR) به باینری‌های بنچ‌مارک و در نتیجه به
\fIlibtest\fR (چارچوب درونی rustc برای آزمون واحد و سنجش کارایی دقیق) ارسال می‌شوند. اگر
آرگومان‌ها را هم به Cargo و هم به باینری ارسال می‌کنید، آرگومان‌های پس از \fB\-\-\fR به
باینری و آرگومان‌های پیش از آن به Cargo فرستاده می‌شوند. برای جزئیات درباره آرگومان‌های
libtest خروجی \fBcargo bench \-\- \-\-help\fR را مشاهده کنید و فصل کتاب rustc
درباره نحوه کارکرد آزمون‌ها را در
<https://doc.rust\-lang.org/rustc/tests/index.html>\& بررسی نمایید.
.sp
به‌عنوان مثال، دستور زیر فقط بنچ‌مارکی با نام \fBfoo\fR را اجرا می‌کند (و از سایر
بنچ‌مارک‌های دارای نام مشابه مانند \fBfoobar\fR صرف‌نظر می‌کند):
.sp
.RS 4
.nf
cargo bench \-\- foo \-\-exact
.fi
.RE
.sp
بنچ‌مارک‌ها با گزینه \fB\-\-test\fR در \fBrustc\fR ساخته می‌شوند که با
پیوند دادن کد شما با libtest یک فایل اجرایی ویژه ایجاد می‌کند. این فایل اجرایی
به‌طور خودکار تمام توابعی را که با مشخصه \fB#[bench]\fR نشانه‌گذاری شده‌اند اجرا می‌کند.
Cargo پرچم \fB\-\-bench\fR را به مهار آزمون (test harness) ارسال می‌کند تا مشخص سازد صرف‌نظر از اینکه
مهار آزمون libtest باشد یا یک مهار سفارشی، تنها بنچ‌مارک‌ها اجرا شوند.
.sp
مهار آزمون libtest را می‌توان با تنظیم \fBharness = false\fR در تنظیمات
مانیفست هدف غیرفعال کرد؛ در این حالت، کد شما باید تابع \fBmain\fR اختصاصی
خود را برای مدیریت اجرای بنچ‌مارک‌ها ارائه دهد.
.RS 3
.ll -5
.sp
\fBنکته\fR:
\fIمشخصه \f(BI#[bench]\fI\fR <https://doc.rust\-lang.org/nightly/unstable\-book/library\-features/test.html>
در حال حاضر ناپایدار (unstable) بوده و تنها در
\fIکانال nightly\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>\& در دسترس است.
بسته‌هایی در
\fIcrates.io\fR <https://crates.io/keywords/benchmark> موجودند که ممکن است به
اجرای بنچ‌مارک‌ها روی کانال پایدار (stable) کمک کنند، مانند
\fICriterion\fR <https://crates.io/crates/criterion>\&.
.br
.RE
.ll
.sp
به‌طور پیش‌فرض، \fBcargo bench\fR از \fIپروفایل \f(BIbench\fI\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html#bench> استفاده می‌کند که
بهینه‌سازی‌ها را فعال و اطلاعات اشکال‌زدایی را غیرفعال می‌سازد. اگر نیاز به اشکال‌زدایی
یک بنچ‌مارک دارید، می‌توانید از گزینه خط فرمان \fB\-\-profile=dev\fR برای جابه‌جایی به
پروفایل dev استفاده کنید. سپس می‌توانید بنچ‌مارک با امکان اشکال‌زدایی فعال را درون یک
اشکال‌زدا (debugger) اجرا نمایید.
.SS "دایرکتوری کاری بنچ‌مارک‌ها (Working directory of benchmarks)"
دایرکتوری کاری هر بنچ‌مارک روی دایرکتوری ریشه بسته‌ای که بنچ‌مارک به آن تعلق دارد
تنظیم می‌شود.
تنظیم دایرکتوری کاری بنچ‌مارک‌ها روی دایرکتوری ریشه بسته، این امکان را فراهم می‌آورد
که بنچ‌مارک‌ها صرف‌نظر از این‌که \fBcargo bench\fR از کجا اجرا شده باشد، با استفاده از مسیرهای
نسبی به‌طور قابل‌اطمینان به فایل‌های بسته دسترسی داشته باشند.
.SH "گزینه‌ها (OPTIONS)"
.SS "گزینه‌های بنچ‌مارک (Benchmark Options)"
.sp
\fB\-\-no\-run\fR
.RS 4
کامپایل بنچ‌مارک‌ها، اما بدون اجرای آن‌ها.
.RE
.sp
\fB\-\-no\-fail\-fast\fR
.RS 4
اجرای همه بنچ‌مارک‌ها صرف‌نظر از شکست. بدون این پرچم، Cargo پس از
شکست اولین فایل اجرایی خارج خواهد شد. مهار آزمون Rust همه بنچ‌مارک‌های درون
فایل اجرایی را تا پایان اجرا خواهد کرد؛ این پرچم تنها برای فایل اجرایی
به‌طور کلی اعمال می‌شود.
.RE.SS "انتخاب بسته (Package Selection)"
به‌طور پیش‌فرض، هنگامی که هیچ گزینهٔ انتخاب بسته‌ای مشخص نشده باشد، بسته‌های انتخاب‌شده به فایل مانیفستِ انتخاب‌شده وابسته هستند (بر پایهٔ دایرکتوری کاری فعلی، اگر \fB\-\-manifest\-path\fR داده نشده باشد). اگر مانیفست، ریشهٔ یک فضای کاری (workspace) باشد، اعضای پیش‌فرض فضای کاری انتخاب می‌شوند؛ در غیر این صورت، تنها بسته‌ای که توسط مانیفست تعریف شده است انتخاب خواهد شد.
.sp
اعضای پیش‌فرض یک فضای کاری را می‌توان به‌صراحت با کلید
\fBworkspace.default\-members\fR در مانیفست ریشه تعیین کرد. اگر این مقدار تنظیم نشده باشد، یک
فضای کاری مجازی شامل تمام اعضای فضای کاری خواهد بود (معادل ارسال
\fB\-\-workspace\fR)، و یک فضای کاری غیرمجازی فقط خودِ کریت ریشه را شامل می‌شود.
.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\-\-all\fR
.RS 4
نام مستعار منسوخ‌شده برای \fB\-\-workspace\fR\&.
.RE
.sp
\fB\-\-exclude\fR \fISPEC\fR\[u2026]
.RS 4
مستثنی کردن بسته‌های مشخص‌شده. باید در کنار پرچم
\fB\-\-workspace\fR استفاده شود. این پرچم می‌تواند چندین بار مشخص شود و از
الگوهای عمومی glob در یونیکس مانند \fB*\fR، \fB?\fR و \fB[]\fR\& پشتیبانی می‌کند. با این حال، برای جلوگیری از
بسط تصادفی الگوهای glob توسط پوسته پیش از آن‌که Cargo آن‌ها را پردازش کند، باید
پیرامون هر الگو از علامت نقل‌قول تکی یا جفتی استفاده کنید.
.RE
.SS "انتخاب هدف (Target Selection)"
هنگامی که هیچ گزینهٔ انتخاب هدفی مشخص نشده باشد، \fBcargo bench\fR هدف‌های
زیر را از بسته‌های انتخاب‌شده می‌سازد:
.sp
.RS 4
\h'-04'\(bu\h'+03'lib \[em] جهت پیوند با باینری‌ها و بنچمارک‌ها استفاده می‌شود
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'bins (تنها در صورتی که هدف‌های بنچمارک ساخته شوند و ویژگی‌های موردنیاز در دسترس باشند)
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'lib به‌صورت بنچمارک
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'bins به‌صورت بنچمارک
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'هدف‌های بنچمارک
.RE
.sp
رفتار پیش‌فرض را می‌توان با تنظیم پرچم \fBbench\fR برای آن هدف
در تنظیمات مانیفست تغییر داد. تنظیم نمونه‌ها به \fBbench = true\fR باعث ساخت و
اجرای نمونه به‌عنوان یک بنچمارک می‌شود و تابع \fBmain\fR نمونه را با
بستر آزمون libtest جایگزین می‌کند.
.sp
تنظیم هدف‌ها به \fBbench = false\fR از سنجش کارایی آن‌ها به‌طور پیش‌فرض
جلوگیری می‌کند. گزینه‌های انتخاب هدف که یک هدف را با نام مشخص می‌کنند (مانند
\fB\-\-example foo\fR) پرچم \fBbench\fR را نادیده گرفته و همیشه هدف مشخص‌شده را
مورد سنجش کارایی قرار می‌دهند.
.sp
برای اطلاعات بیشتر دربارهٔ تنظیمات به ازای هر هدف، به \fIConfiguring a target\fR <https://doc.rust\-lang.org/cargo/reference/cargo\-targets.html#configuring\-a\-target>
مراجعه کنید.
.sp
هدف‌های باینری در صورتی که یک آزمون یکپارچه‌سازی یا بنچمارک برای سنجش کارایی
انتخاب شده باشد، به‌طور خودکار ساخته می‌شوند. این به آزمون یکپارچه‌سازی اجازه می‌دهد
تا فایل باینری را برای ارزیابی و آزمودن رفتار آن اجرا کند.
\fIمتغیر محیطی\fR \fBCARGO_BIN_EXE_<name>\fR
<https://doc.rust\-lang.org/cargo/reference/environment\-variables.html#environment\-variables\-cargo\-sets\-for\-crates>
هنگام ساخت و اجرای آزمون یکپارچه‌سازی تنظیم می‌شود تا بتواند با استفاده از
\fIماکروی \f(BIenv\fI\fR <https://doc.rust\-lang.org/std/macro.env.html> یا
\fIتابع \f(BIvar\fI\fR <https://doc.rust\-lang.org/std/env/fn.var.html> مکان فایل اجرایی
را پیدا کند.
.sp
ارسال پرچم‌های انتخاب هدف، تنها هدف‌های مشخص‌شده را
مورد سنجش کارایی قرار می‌دهد.
.sp
توجه داشته باشید که پرچم‌های \fB\-\-bin\fR، \fB\-\-example\fR، \fB\-\-test\fR و \fB\-\-bench\fR نیز
از الگوهای عمومی glob در یونیکس مانند \fB*\fR، \fB?\fR و \fB[]\fR\& پشتیبانی می‌کنند. با این حال، برای جلوگیری از
بسط تصادفی الگوهای glob توسط پوسته پیش از آن‌که Cargo آن‌ها را پردازش کند، باید
پیرامون هر الگوی glob از نقل‌قول تکی یا جفتی استفاده کنید.
.sp
\fB\-\-lib\fR
.RS 4
سنجش کارایی کتابخانهٔ بسته.
.RE
.sp
\fB\-\-bin\fR \fIname\fR\[u2026]
.RS 4
سنجش کارایی باینری مشخص‌شده. این پرچم می‌تواند چندین بار مشخص شود
و از الگوهای عمومی glob در یونیکس پشتیبانی می‌کند.
.RE
.sp
\fB\-\-bins\fR
.RS 4
سنجش کارایی تمام هدف‌های باینری.
.RE
.sp
\fB\-\-example\fR \fIname\fR\[u2026]
.RS 4
سنجش کارایی نمونهٔ مشخص‌شده. این پرچم می‌تواند چندین بار مشخص شود
و از الگوهای عمومی glob در یونیکس پشتیبانی می‌کند.
.RE
.sp
\fB\-\-examples\fR
.RS 4
سنجش کارایی تمام هدف‌های نمونه (example).
.RE
.sp
\fB\-\-test\fR \fIname\fR\[u2026]
.RS 4
سنجش کارایی آزمون یکپارچه‌سازی مشخص‌شده. این پرچم می‌تواند چندین بار
مشخص شود و از الگوهای عمومی glob در یونیکس پشتیبانی می‌کند.
.RE
.sp
\fB\-\-tests\fR
.RS 4
سنجش کارایی تمام هدف‌هایی که پرچم مانیفست \fBtest = true\fR برای آن‌ها
تنظیم شده است. به‌طور پیش‌فرض این شامل کتابخانه و باینری‌های ساخته‌شده به‌عنوان
آزمون‌های واحد (unittest)، و آزمون‌های یکپارچه‌سازی است. توجه داشته باشید که این کار همچنین هرگونه
وابستگی مورد نیاز را می‌سازد، بنابراین ممکن است هدف lib دو بار ساخته شود (یک بار به‌عنوان
آزمون واحد، و بار دیگر به‌عنوان وابستگی برای باینری‌ها، آزمون‌های یکپارچه‌سازی و غیره).
هدف‌ها را می‌توان با تنظیم پرچم \fBtest\fR در تنظیمات مانیفست برای آن هدف،
فعال یا غیرفعال کرد.
.RE
.sp
\fB\-\-bench\fR \fIname\fR\[u2026]
.RS 4
سنجش کارایی بنچمارک مشخص‌شده. این پرچم می‌تواند چندین بار
مشخص شود و از الگوهای عمومی glob در یونیکس پشتیبانی می‌کند.
.RE
.sp
\fB\-\-benches\fR
.RS 4
سنجش کارایی تمام هدف‌هایی که پرچم مانیفست \fBbench = true\fR برای
آن‌ها تنظیم شده است. به‌طور پیش‌فرض این شامل کتابخانه و باینری‌های ساخته‌شده
به‌عنوان بنچمارک، و هدف‌های bench است. توجه داشته باشید که این کار همچنین هرگونه
وابستگی مورد نیاز را می‌سازد، بنابراین ممکن است هدف lib دو بار ساخته شود (یک بار به‌عنوان
بنچمارک، و بار دیگر به‌عنوان وابستگی برای باینری‌ها، بنچمارک‌ها و غیره).
هدف‌ها را می‌توان با تنظیم پرچم \fBbench\fR در تنظیمات مانیفست برای آن هدف،
فعال یا غیرفعال کرد.
.RE
.sp
\fB\-\-all\-targets\fR
.RS 4
سنجش کارایی تمام هدف‌ها. این معادل مشخص کردن \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\& است.
.RE.SS "انتخاب ویژگی‌ها (Feature Selection)"
پرچم‌های ویژگی به شما امکان می‌دهند مشخص کنید کدام ویژگی‌ها فعال شوند. زمانی که هیچ
گزینه‌ای برای ویژگی‌ها مشخص نشود، ویژگی \fBdefault\fR برای هر بستهٔ انتخاب‌شده
فعال می‌شود.
.sp
برای جزئیات بیشتر، \fIمستندات ویژگی‌ها\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
را ببینید.
.sp
\fB\-F\fR \fIfeatures\fR, 
\fB\-\-features\fR \fIfeatures\fR
.RS 4
فهرستی از ویژگی‌ها برای فعال‌سازی که با فاصله یا کاما از یکدیگر جدا شده‌اند. ویژگی‌های اعضای
فضای کاری (workspace) را می‌توان با ساختار \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 "گزینه‌های کامپایل (Compilation Options)"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
اجرای بنچ‌مارک برای معماری هدف مشخص‌شده. این پرچم می‌تواند چندین بار مشخص شود. مقدار پیش‌فرض،
معماری میزبان است. ساختار کلی این سه‌تایی به صورت
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\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، که در داخل با هدف سیستم میزبان جایگزین خواهد شد. این گزینه به‌ویژه زمانی مفید است که در حال کامپایل متقاطع برخی crateها هستید و نمی‌خواهید ماشین میزبان خود را به عنوان یک هدف مشخص کنید (برای مثال، یک \fBxtask\fR در یک پروژهٔ مشترک که ممکن است توسط میزبان‌های متعددی روی آن کار شود).
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'مسیری به یک مشخصات هدف سفارشی. برای اطلاعات بیشتر \fICustom Target Lookup Path\fR <https://doc.rust\-lang.org/rustc/targets/custom.html#custom\-target\-lookup\-path> را ببینید.
.RE
.sp
این مقدار همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBbuild.target\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\& مشخص شود.
.sp
توجه داشته باشید که تعیین این پرچم باعث می‌شود Cargo در حالت متفاوتی اجرا شود که در آن
مصنوعات هدف در یک دایرکتوری جداگانه قرار می‌گیرند. برای جزئیات بیشتر به مستندات
\fIحافظهٔ موقت ساخت\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> مراجعه کنید.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
اجرای بنچ‌مارک با نمایهٔ (profile) مشخص‌شده.
برای جزئیات بیشتر دربارهٔ نمایه‌ها به \fIمرجع\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> مراجعه کنید.
.RE
.sp
\fB\-\-timings\fR
.RS 4
اطلاعات مربوط به مدت‌زمان هر کامپایل را چاپ می‌کند و اطلاعات همروندی را در طول زمان دنبال
می‌نماید.
.sp
در پایان فرایند ساخت، فایلی به نام \fBcargo\-timing.html\fR در دایرکتوری
\fBtarget/cargo\-timings\fR نوشته خواهد شد. در صورتی که بخواهید اجرای قبلی را بررسی کنید،
یک گزارش اضافی با برچسب زمان در نام فایل آن نیز ذخیره می‌شود. این گزارش‌ها صرفاً برای
مطالعه توسط انسان مناسب هستند و داده‌های زمان‌بندی ماشین‌خوان ارائه نمی‌دهند.
.RE
.SS "گزینه‌های خروجی (Output Options)"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
دایرکتوری مربوط به تمام مصنوعات تولیدشده و فایل‌های میانی. همچنین می‌تواند با متغیر محیطی
\fBCARGO_TARGET_DIR\fR یا \fIمقدار پیکربندی\fR \fBbuild.target\-dir\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&
تعیین شود. پیش‌فرض آن پوشهٔ \fBtarget\fR در ریشهٔ فضای کاری است.
.RE
.SS "گزینه‌های نمایش (Display Options)"
به‌طور پیش‌فرض، بستر آزمایش Rust خروجی اجرای بنچ‌مارک را پنهان می‌کند تا نتایج خوانا
باقی بمانند. خروجی بنچ‌مارک را می‌توان (مثلاً برای اشکال‌زدایی) با ارسال
\fB\-\-no\-capture\fR به باینری‌های بنچ‌مارک بازیابی کرد:
.sp
.RS 4
.nf
cargo bench \-\- \-\-no\-capture
.fi
.RE
.sp
\fB\-v\fR, 
\fB\-\-verbose\fR
.RS 4
استفاده از خروجی پرگو (verbose). می‌تواند دو بار مشخص شود تا خروجی \[lq]خیلی پرگو\[rq] نمایش
داده شود که شامل اطلاعات بیشتری مانند هشدارهای وابستگی و خروجی اسکریپت ساخت است.
همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBterm.verbose\fR
<https://doc.rust\-lang.org/cargo/reference/config.html>\& مشخص شود.
.RE
.sp
\fB\-q\fR, 
\fB\-\-quiet\fR
.RS 4
پیام‌های ثبت وقایع (log) ابزار cargo را چاپ نمی‌کند.
همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBterm.quiet\fR
<https://doc.rust\-lang.org/cargo/reference/config.html>\& مشخص شود.
.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
<https://doc.rust\-lang.org/cargo/reference/config.html>\& مشخص شود.
.RE
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
قالب خروجی برای پیام‌های عیب‌یابی. می‌تواند چندین بار مشخص شود و شامل مقادیری است که
با کاما از هم جدا شده‌اند. مقادیر معتبر:
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBhuman\fR (پیش‌فرض): نمایش در یک قالب متنی انسان‌خوان. با \fBshort\fR و \fBjson\fR تداخل دارد\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBshort\fR: ارسال پیام‌های متنی کوتاه‌تر و انسان‌خوان. با \fBhuman\fR و \fBjson\fR تداخل دارد\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBjson\fR: ارسال پیام‌های JSON به خروجی استاندارد (stdout). برای جزئیات بیشتر به
\fIمرجع\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
مراجعه کنید. با \fBhuman\fR و \fBshort\fR تداخل دارد\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBjson\-diagnostic\-short\fR: تضمین می‌کند که فیلد \fBrendered\fR در پیام‌های JSON حاوی خروجی نمایشی \[lq]کوتاه\[rq] حاصل از rustc باشد. نمی‌تواند همراه با \fBhuman\fR یا \fBshort\fR استفاده شود\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBjson\-diagnostic\-rendered\-ansi\fR: تضمین می‌کند که فیلد \fBrendered\fR در پیام‌های JSON شامل کدهای رنگی توکار ANSI برای حفظ طرح رنگ پیش‌فرض rustc باشد. نمی‌تواند همراه با \fBhuman\fR یا \fBshort\fR استفاده شود\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBjson\-render\-diagnostics\fR: به Cargo دستور می‌دهد که پیام‌های عیب‌یابی rustc را در پیام‌های JSON چاپ‌شده قرار ندهد، بلکه خود Cargo پیام‌های عیب‌یابی JSON دریافتی از rustc را نمایش دهد. پیام‌های عیب‌یابی JSON خودِ Cargo و سایر پیام‌های دریافتی از rustc همچنان ارسال می‌شوند. نمی‌تواند همراه با \fBhuman\fR یا \fBshort\fR استفاده شود\&.
.RE
.RE.SS "گزینه‌های مانیفست (Manifest Options)"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
مسیر فایل \fBCargo.toml\fR. به‌طور پیش‌فرض، Cargo فایل \fBCargo.toml\fR را در دایرکتوری جاری یا هر یک از دایرکتوری‌های والد جستجو می‌کند.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
نادیده گرفتن مشخصهٔ \fBrust\-version\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) مد نظر است، مانند خطوط لولهٔ CI، استفاده شود.
.RE
.sp
\fB\-\-offline\fR
.RS 4
از دسترسی Cargo به شبکه به هر دلیلی جلوگیری می‌کند. بدون این پرچم، اگر Cargo نیاز به دسترسی به شبکه داشته باشد و شبکه در دسترس نباشد، با خطا متوقف می‌شود. با این پرچم، Cargo در صورت امکان تلاش خواهد کرد بدون شبکه به کار خود ادامه دهد.
.sp
توجه داشته باشید که این کار ممکن است منجر به تفکیک وابستگیِ متفاوتی نسبت به حالت برخط (online) شود. Cargo خود را به crateهایی که به‌صورت محلی دانلود شده‌اند محدود می‌کند، حتی اگر طبق نسخهٔ محلی نمایه (index)، نسخهٔ جدیدتری موجود باشد. برای دانلود وابستگی‌ها پیش از رفتن به حالت آفلاین، دستور \fBcargo\-fetch\fR(1) را ببینید.
.sp
همچنین می‌تواند با \fIمقدار پیکربندی\fR \fBnet.offline\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\& مشخص شود.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
معادل تعیین هر دو گزینهٔ \fB\-\-locked\fR و \fB\-\-offline\fR به‌طور هم‌زمان\&.
.RE
.SS "گزینه‌های عمومی (Common Options)"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
اگر Cargo با rustup نصب شده باشد، و اولین آرگومان \fBcargo\fR با \fB+\fR آغاز شود، به‌عنوان نام زنجیره ابزار (toolchain) متعلق به rustup تفسیر خواهد شد (مانند \fB+stable\fR یا \fB+nightly\fR).
برای اطلاعات بیشتر درباره نحوه کارکرد جایگزینی زنجیره ابزارها، \fIمستندات rustup\fR <https://rust\-lang.github.io/rustup/overrides.html> را ببینید.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR یا \fIPATH\fR
.RS 4
یک مقدار پیکربندی Cargo را بازنویسی می‌کند. آرگومان باید در ساختار نحوی TOML به‌صورت \fBKEY=VALUE\fR باشد، یا به‌صورت مسیری به یک فایل پیکربندی اضافی ارائه شود. این پرچم می‌تواند چندین بار مشخص شود.
برای اطلاعات بیشتر، \fIبخش بازنویسی‌های خط فرمان\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> را ببینید.
.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 <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> در دسترس است و برای فعال‌سازی به پرچم \fB\-Z unstable\-options\fR نیاز دارد (ببینید: \fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.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.SS "گزینه‌های گوناگون (Miscellaneous Options)"
آرگومان \fB\-\-jobs\fR بر ساخت فایل اجرایی بنچ‌مارک اثر می‌گذارد، اما
بر تعداد ریسه‌های مورد استفاده هنگام اجرای بنچ‌مارک‌ها اثرگذار نیست. بستر
آزمون Rust بنچ‌مارک‌ها را به صورت ترتیبی در یک تک‌ریسه اجرا می‌کند.
.sp
\fB\-j\fR \fIN\fR, 
\fB\-\-jobs\fR \fIN\fR
.RS 4
تعداد کارهای موازی برای اجرا. همچنین می‌تواند با
\fIمقدار پیکربندی\fR \fBbuild.jobs\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\& مشخص شود. پیش‌فرض،
تعداد CPUهای منطقی است. اگر منفی باشد، بیشینهٔ تعداد
کارهای موازی را برابر با تعداد CPUهای منطقی به‌علاوهٔ مقدار ارائه‌شده تنظیم می‌کند. اگر
رشتهٔ \fBdefault\fR داده شود، مقدار را دوباره به پیش‌فرض بازمی‌گرداند.
نباید 0 باشد.
.RE
.sp
اگرچه \fBcargo bench\fR شامل کامپایل می‌شود، اما گزینهٔ \fB\-\-keep\-going\fR را
ارائه نمی‌دهد. از \fB\-\-no\-fail\-fast\fR برای اجرای هرچه بیشتر بنچ‌مارک‌ها بدون
توقف در نخستین شکست استفاده کنید. برای \[lq]کامپایل\[rq] کردن بیشترین بنچ‌مارک‌های ممکن، از
\fB\-\-benches\fR برای ساخت جداگانهٔ باینری‌های بنچ‌مارک استفاده کنید. برای نمونه:
.sp
.RS 4
.nf
cargo build \-\-benches \-\-release \-\-keep\-going
cargo bench \-\-no\-fail\-fast
.fi
.RE
.SH "محیط (ENVIRONMENT)"
برای جزئیات دربارهٔ متغیرهای محیطی که Cargo می‌خواند،
\fIمرجع\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> را ببینید.
.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'ساخت و اجرای تمام بنچ‌مارک‌های بستهٔ کنونی:
.sp
.RS 4
.nf
cargo bench
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'تنها اجرای یک بنچ‌مارک مشخص درون یک هدف بنچ‌مارک معین:
.sp
.RS 4
.nf
cargo bench \-\-bench bench_name \-\- modname::some_benchmark
.fi
.RE
.RE
.SH "همچنین ببینید (SEE ALSO)"
\fBcargo\fR(1), \fBcargo\-test\fR(1)