CARGO-FIX(1)

General Commands Manual

CARGO-FIX(1)

نام (NAME)

cargo-fix - اصلاح خودکار هشدارهای کامپایلر در کد منبع Rust

خلاصه دستور (SYNOPSIS)

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

توضیحات (DESCRIPTION)

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

اجرای cargo fix در پشت صحنه دستور cargo-check(1) را اجرا می‌کند. هرگونه هشدار قابل اعمال روی کریت شما به‌صورت خودکار برطرف می‌شود (در صورت امکان) و تمام هشدارهای باقی‌مانده پس از اتمام فرآیند بررسی نمایش داده خواهند شد. برای نمونه، اگر می‌خواهید تمام اصلاحات را روی بسته فعلی اعمال کنید، می‌توانید دستور زیر را اجرا نمایید:

cargo fix

که رفتاری مشابه cargo check --all-targets دارد.

دستور cargo fix تنها قادر به اصلاح کدهایی است که معمولاً با cargo check کامپایل می‌شوند. اگر کدی به‌طور شرطی با ویژگی‌های اختیاری (features) فعال شده باشد، لازم است آن ویژگی‌ها را فعال کنید تا آن کد مورد تحلیل قرار گیرد:

cargo fix --features foo

به‌طور مشابه، برای سایر عبارت‌های cfg مانند کدهای مختص به یک پلتفرم خاص، باید گزینه --target را ارسال کنید تا کد برای آن هدف مشخص اصلاح شود.

cargo fix --target x86_64-pc-windows-gnu

در صورت بروز هرگونه مشکل در cargo fix یا داشتن هرگونه سوال یا درخواست ویژگی جدید، لطفاً در آدرس https://github.com/rust-lang/cargo یک گزارش مشکل (issue) ثبت کنید.

مهاجرت نسخه زبانی (Edition migration)

زیردستور cargo fix همچنین می‌تواند برای مهاجرت یک بسته از یک نسخه زبانی (edition) https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html به نسخه بعدی استفاده شود. روال کلی به این صورت است:

1.دستور cargo fix --edition را اجرا کنید. اگر پروژه شما چندین ویژگی (feature) دارد، استفاده از فلگ --all-features را نیز در نظر بگیرید. همچنین اگر پروژه‌تان کدهای مختص پلتفرم دارد که توسط ویژگی‌های cfg کنترل می‌شوند، ممکن است بخواهید cargo fix --edition را چند بار با فلگ‌های مختلف --target اجرا کنید.

2.فایل Cargo.toml را ویرایش کرده و فیلد edition https://doc.rust-lang.org/cargo/reference/manifest.html#the-edition-field را روی نسخه زبانی جدید تنظیم کنید.

3.آزمون‌های پروژه خود را اجرا کنید تا مطمئن شوید همه چیز هنوز کار می‌کند. اگر هشدارهای جدیدی صادر شد، می‌توانید اجرای مجدد cargo fix (بدون فلگ --edition) را برای اعمال پیشنهادات ارائه‌شده توسط کامپایلر در نظر بگیرید.

و امیدواریم کار تمام باشد! فقط به یاد داشته باشید که طبق هشدارهای ذکر شده در بالا، cargo fix نمی‌تواند کدهای مربوط به ویژگی‌های غیرفعال یا عبارت‌های cfg را به‌روزرسانی کند. همچنین در برخی موارد نادر، کامپایلر قادر به مهاجرت خودکار تمام کد به نسخه جدید نیست و این امر ممکن است پس از ساخت پروژه با نسخه جدید، نیازمند اعمال تغییرات دستی باشد.

گزینه‌ها (OPTIONS)

گزینه‌های اصلاح (Fix options)

--broken-code

اصلاح کد حتی اگر از قبل دارای خطاهای کامپایلر باشد. این گزینه زمانی مفید است که cargo fix در اعمال تغییرات ناموفق باشد. این گزینه تغییرات را اعمال کرده و کد خراب را در پوشه کاری باقی می‌گذارد تا بتوانید آن را بررسی کرده و به‌صورت دستی اصلاح کنید.

--edition

اعمال تغییراتی که کد را به نسخه زبانی (edition) بعدی به‌روزرسانی می‌کند. این گزینه نسخه زبانی را در مانیفست Cargo.toml تغییر نمی‌دهد و این کار باید پس از پایان کار cargo fix --edition به‌صورت دستی انجام شود.

--edition-idioms

اعمال پیشنهادهایی که کد را به سبک ترجیحی و استاندارد برای نسخه زبانی فعلی ارتقا می‌دهد.

--allow-no-vcs

اصلاح کد حتی اگر هیچ سیستم کنترل نسخه‌ای (VCS) شناسایی نشود.

--allow-dirty

اصلاح کد حتی اگر در پوشه کاری تغییراتی وجود داشته باشد (شامل تغییرات استیج‌شده).

--allow-staged

اصلاح کد حتی اگر در پوشه کاری تغییرات استیج‌شده وجود داشته باشد.

انتخاب بسته (Package Selection)

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

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

-p spec…, --package spec…

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

--workspace

تمام اعضای موجود در فضای کاری را اصلاح می‌کند.

--all

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

--exclude SPEC…

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

انتخاب هدف (Target Selection)

هنگامی که هیچ گزینه انتخابی برای هدف مشخص نشده باشد، cargo fix تمام هدف‌ها را اصلاح می‌کند (فلگ --all-targets به‌صورت ضمنی اعمال می‌شود). باینری‌هایی که نیازمند ویژگی‌هایی (required-features) هستند که موجود نیستند، نادیده گرفته می‌شوند.

ارسال فلگ‌های انتخاب هدف، فقط هدف‌های مشخص‌شده را اصلاح می‌کند.

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

--lib

کتابخانه بسته را اصلاح می‌کند.

--bin name…

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

--bins

تمام هدف‌های باینری را اصلاح می‌کند.

--example name…

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

--examples

تمام هدف‌های نمونه را اصلاح می‌کند.

--test name…

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

--tests

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

--bench name…

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

--benches

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

--all-targets

تمام هدف‌ها را اصلاح می‌کند. این معادل تعیین --lib --bins --tests --benches --examples است.

انتخاب ویژگی (Feature Selection)

فلگ‌های ویژگی به شما امکان می‌دهند کنترل کنید کدام ویژگی‌ها فعال شوند. در صورت عدم تعیین گزینه‌های ویژگی، ویژگی 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 بسته‌های انتخاب‌شده را فعال نمی‌کند.

گزینه‌های کامپایل (Compilation Options)

--target triple

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

مقادیر ممکن:

•هر هدف پشتیبانی‌شده در rustc --print target-list.

•"host-tuple" که در داخل با هدف میزبان جایگزین می‌شود. این گزینه به‌ویژه زمانی مفید است که در حال کامپایل متقاطع برخی کریت‌ها هستید و نمی‌خواهید ماشین میزبان خود را به‌عنوان هدف مشخص کنید (مثلاً یک xtask در یک پروژه مشترک که ممکن است توسط میزبان‌های مختلفی روی آن کار شود).

•مسیری به یک مشخصات هدف سفارشی. برای اطلاعات بیشتر به مسیر جستجوی هدف سفارشی 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 در حالت متفاوتی اجرا شود که در آن مصنوعات هدف در یک پوشه جداگانه قرار می‌گیرند. برای جزئیات بیشتر به مستندات حافظه موقت ساخت (build cache) 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 نوشته خواهد شد. در صورتی که بخواهید به اجرای قبلی نگاهی بیندازید، یک گزارش اضافی همراه با برچسب زمان در نام فایل نیز ذخیره می‌شود. این گزارش‌ها فقط برای استفاده انسان مناسب هستند و داده‌های زمان‌بندی ماشین‌خوان ارائه نمی‌دهند.

گزینه‌های خروجی (Output Options)

--target-dir directory

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

گزینه‌های نمایش (Display Options)

-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 مشخص شود.

--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 Options)

--manifest-path path

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

--ignore-rust-version

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

--locked

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

•فایل lock وجود نداشته باشد.

•دستور Cargo تلاش کند فایل lock را به دلیل تفکیک متفاوت وابستگی‌ها تغییر دهد.

می‌توان از آن در محیط‌هایی که نیاز به ساخت‌های قطعی و قطعی‌گرا (deterministic) دارند، مانند خطوط لوله CI استفاده کرد.

--offline

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

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

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

--frozen

معادل مشخص کردن هر دو گزینه --locked و --offline به‌طور همزمان.

گزینه‌های عمومی (Common Options)

+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 را اجرا کنید.

گزینه‌های متفرقه (Miscellaneous Options)

-j N, --jobs N

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

--keep-going

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

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