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

cargo-check - بررسی بستهٔ جاری

cargo check [گزینه‌ها]

یک بستهٔ محلی و تمام وابستگی‌های آن را برای یافتن خطاها بررسی می‌کند. این دستور اساساً بسته‌ها را بدون انجام مرحلهٔ نهایی تولید کد کامپایل می‌کند، که بسیار سریع‌تر از اجرای cargo build است. کامپایلر فایل‌های فراداده (metadata) را روی دیسک ذخیره می‌کند تا در صورت عدم تغییر کد منبع، در اجراهای بعدی مجدداً استفاده شوند. برخی از هشدارها و خطاها تنها در طول مرحلهٔ تولید کد صادر می‌شوند، بنابراین طبیعتاً با cargo check گزارش نخواهند شد.

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

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

-p spec…, --package spec…

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

--workspace

تمام اعضای فضای کاری را بررسی می‌کند.

--all

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

--exclude SPEC…

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

هنگامی که هیچ گزینه‌ای برای انتخاب هدف مشخص نشود، cargo check تمام اهداف باینری و کتابخانه‌ای بسته‌های انتخاب‌شده را بررسی می‌کند. باینری‌هایی که دارای required-features مفقود باشند نادیده گرفته می‌شوند.

ارسال پرچم‌های انتخاب هدف، تنها اهداف مشخص‌شده را بررسی می‌کند.

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

--lib

کتابخانهٔ بسته را بررسی می‌کند.

--bin name…

باینری مشخص‌شده را بررسی می‌کند. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob یونیکس پشتیبانی می‌کند.

--bins

تمام اهداف باینری را بررسی می‌کند.

--example name…

نمونهٔ (example) مشخص‌شده را بررسی می‌کند. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob یونیکس پشتیبانی می‌کند.

--examples

تمام اهداف نمونه را بررسی می‌کند.

--test name…

آزمون یکپارچه‌سازی (integration test) مشخص‌شده را بررسی می‌کند. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob یونیکس پشتیبانی می‌کند.

--tests

تمام اهدافی را که پرچم مانیفست test = true برای آن‌ها تنظیم شده است بررسی می‌کند. به‌طور پیش‌فرض این شامل کتابخانه و باینری‌های ساخته‌شده به‌عنوان آزمون‌های واحد، و آزمون‌های یکپارچه‌سازی است. توجه داشته باشید که این کار هرگونه وابستگی مورد نیاز را نیز می‌سازد، بنابراین هدف کتابخانه ممکن است دو بار ساخته شود (یک بار به‌عنوان آزمون واحد، و یک بار به‌عنوان وابستگی برای باینری‌ها، آزمون‌های یکپارچه‌سازی و غیره). اهداف را می‌توان با تنظیم پرچم test در تنظیمات مانیفستِ آن هدف فعال یا غیرفعال کرد.

--bench name…

بنچ‌مارک مشخص‌شده را بررسی می‌کند. این پرچم می‌تواند چندین بار مشخص شود و از الگوهای عمومی glob یونیکس پشتیبانی می‌کند.

--benches

تمام اهدافی را که پرچم مانیفست bench = true برای آن‌ها تنظیم شده است بررسی می‌کند. به‌طور پیش‌فرض این شامل کتابخانه و باینری‌های ساخته‌شده به‌عنوان بنچ‌مارک، و اهداف بنچ‌مارک است. توجه داشته باشید که این کار هرگونه وابستگی مورد نیاز را نیز می‌سازد، بنابراین هدف کتابخانه ممکن است دو بار ساخته شود (یک بار به‌عنوان بنچ‌مارک، و یک بار به‌عنوان وابستگی برای باینری‌ها، بنچ‌مارک‌ها و غیره). اهداف را می‌توان با تنظیم پرچم bench در تنظیمات مانیفستِ آن هدف فعال یا غیرفعال کرد.

--all-targets

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

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

-F features, --features features

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

--all-features

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

--no-default-features

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

--target triple

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

مقادیر ممکن:

•هر مقصد پشتیبانی‌شده در rustc --print target-list.
•"host-tuple"، که در داخل با مقصد سیستم میزبان جایگزین خواهد شد. این گزینه به‌ویژه زمانی مفید است که در حال کامپایل متقابل (cross-compiling) برخی کریت‌ها هستید و نمی‌خواهید ماشین میزبان خود را به عنوان یک مقصد مشخص کنید (برای نمونه، یک 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 در حالت متفاوتی اجرا شود که در آن مصنوعات مقصد در یک دایرکتوری جداگانه قرار می‌گیرند. برای جزئیات بیشتر مستندات کَش ساخت https://doc.rust-lang.org/cargo/reference/build-cache.html را ببینید.

-r, --release

بررسی مصنوعات بهینه‌سازی‌شده با نمایه release. همچنین گزینه --profile را برای انتخاب یک نمایه خاص بر اساس نام ببینید.

--profile name

بررسی با نمایه داده‌شده.

به عنوان یک حالت خاص، مشخص کردن نمایه test همچنین بررسی در حالت آزمون را فعال می‌کند که بررسی آزمون‌ها را مقدور ساخته و گزینه cfg با نام test را فعال می‌کند. برای جزئیات بیشتر، آزمون‌های rustc https://doc.rust-lang.org/rustc/tests/index.html را ببینید.

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

--timings

خروجی دادن اطلاعات در مورد مدت زمانی که هر کامپایل طول می‌کشد، و ردگیری اطلاعات همزمانی در طول زمان.

یک فایل cargo-timing.html در پایان ساخت در دایرکتوری target/cargo-timings نوشته خواهد شد. در صورتی که بخواهید یک اجرای قبلی را بررسی کنید، یک گزارش اضافی با برچسب زمانی در نام فایل آن نیز نوشته می‌شود. این گزارش‌ها صرفاً برای استفاده انسان مناسب هستند و داده‌های زمان‌بندی ماشین‌خوان ارائه نمی‌دهند.

--target-dir directory

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

-v, --verbose

استفاده از خروجی پرچانه (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 مشخص شود.

--message-format fmt

قالب خروجی برای پیام‌های تشخیصی. می‌تواند چندین بار مشخص شود و از مقادیر جداشده با کاما تشکیل می‌شود. مقادیر معتبر:
•human (پیش‌فرض): نمایش در قالب متنی خوانا برای انسان. با short و json تداخل دارد.
•short: انتشار پیام‌های متنی کوتاه‌تر و خوانا برای انسان. با human و json تداخل دارد.
•json: انتشار پیام‌های JSON در خروجی استاندارد (stdout). برای جزئیات بیشتر به مرجع https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages مراجعه کنید. با human و short تداخل دارد.
•json-diagnostic-short: اطمینان حاصل می‌کند که فیلد rendered پیام‌های JSON شامل رندرینگ “کوتاه” از rustc باشد. نمی‌تواند همراه با human یا short استفاده شود.
•json-diagnostic-rendered-ansi: اطمینان حاصل می‌کند که فیلد rendered پیام‌های JSON شامل کدهای رنگی تعبیه‌شدهٔ ANSI برای رعایت طرح رنگ پیش‌فرض rustc باشد. نمی‌تواند همراه با human یا short استفاده شود.
•json-render-diagnostics: به Cargo دستور می‌دهد که پیام‌های تشخیصی rustc را در پیام‌های JSON چاپ‌شده نگنجاند، بلکه خود Cargo پیام‌های تشخیصی JSON دریافتی از rustc را رندر کند. پیام‌های تشخیصی JSON خود Cargo و دیگر پیام‌های دریافتی از rustc همچنان منتشر می‌شوند. نمی‌تواند همراه با human یا short استفاده شود.

--manifest-path path

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

--ignore-rust-version

مشخصات rust-version در بسته‌ها را نادیده می‌گیرد.

--locked

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

این گزینه ممکن است در محیط‌هایی که در آن‌ها ساخت‌های قطعی و بازتولیدپذیر مورد نیاز است، مانند خطوط لولهٔ 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 است.

+toolchain

اگر Cargo با rustup نصب شده باشد و اولین آرگومان cargo با + آغاز شود، به عنوان نام زنجیره ابزار 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 را اجرا کنید.

-j N, --jobs N

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

--keep-going

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

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

--future-incompat-report

نمایش گزارش future-incompat برای هرگونه هشدار ناسازگاری در آینده که در طول اجرای این دستور تولید شده است.

cargo-report(1) را ببینید.

برای جزئیات درباره متغیرهای محیطی که Cargo می‌خواند، مرجع https://doc.rust-lang.org/cargo/reference/environment-variables.html را ببینید.

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

1.بررسی بستهٔ محلی برای یافتن خطاها: 
cargo check
2.بررسی تمام هدف‌ها، از جمله آزمون‌های واحد: 
cargo check --all-targets --profile=test

cargo(1), cargo-build(1)