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

cargo-rustc - کامپایل بستهٔ جاری و ارسال گزینه‌های اضافی به کامپایلر

cargo rustc [options] [-- args]

هدف مشخص‌شده برای بستهٔ جاری (یا بستهٔ مشخص‌شده با -p در صورت ارائه) به همراه تمام وابستگی‌های آن کامپایل خواهد شد. تمام args مشخص‌شده به فراخوانی نهایی کامپایلر ارسال خواهند شد، نه به هیچ‌یک از وابستگی‌ها. توجه داشته باشید که کامپایلر همچنان آرگومان‌هایی مانند -L، --extern و --crate-type را بدون قید و شرط دریافت خواهد کرد، و args مشخص‌شده صرفاً به فراخوانی کامپایلر افزوده می‌شوند.

برای مستندات مربوط به پرچم‌های rustc به https://doc.rust-lang.org/rustc/index.html مراجعه کنید.

این دستور مستلزم آن است که در هنگام ارائهٔ آرگومان‌های اضافی، تنها یک هدف در حال کامپایل باشد. اگر بیش از یک هدف برای بستهٔ جاری در دسترس باشد، باید از فیلترهای --lib، --bin و غیره برای انتخاب هدف کامپایل شونده استفاده شود.

جهت ارسال پرچم‌ها به تمام فرایندهای کامپایلری که توسط Cargo ایجاد می‌شوند، از متغیر محیطی RUSTFLAGS به نشانی https://doc.rust-lang.org/cargo/reference/environment-variables.html یا مقدار پیکربندی build.rustflags به نشانی https://doc.rust-lang.org/cargo/reference/config.html استفاده کنید.

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

-p spec, --package spec

بسته‌ای که باید ساخته شود. برای قالب SPEC به cargo-pkgid(1) مراجعه کنید.

هنگامی که هیچ گزینهٔ انتخابی برای هدف تعیین نشود، cargo rustc تمام اهداف دودویی و کتابخانه‌ای بستهٔ انتخاب‌شده را خواهد ساخت.

اهداف دودویی در صورتی که یک آزمون یکپارچه‌سازی یا بنچمارک برای ساخت انتخاب شده باشد، به‌طور خودکار ساخته می‌شوند. این به آزمون یکپارچه‌سازی اجازه می‌دهد تا فایل دودویی را اجرا کرده و رفتار آن را بیازماید. متغیر محیطی CARGO_BIN_EXE_<name> به نشانی https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates هنگام ساخت و اجرای آزمون یکپارچه‌سازی تنظیم می‌شود تا بتواند با استفاده از ماکروی env به نشانی https://doc.rust-lang.org/std/macro.env.html یا تابع var به نشانی https://doc.rust-lang.org/std/env/fn.var.html مکان فایل اجرایی را پیدا کند.

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

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

--lib

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

--bin name…

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

--bins

تمام اهداف دودویی را می‌سازد.

--example name…

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

--examples

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

--test name…

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

--tests

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

--bench name…

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

--benches

تمام اهدافی را که پرچم مانیفست bench = true برای آن‌ها تنظیم شده است، می‌سازد. به‌طور پیش‌فرض این شامل کتابخانه و فایل‌های دودویی ساخته‌شده به‌عنوان بنچمارک، و اهداف bench است. توجه داشته باشید که این کار همچنین هرگونه وابستگی مورد نیاز را خواهد ساخت، بنابراین هدف lib ممکن است دو بار ساخته شود (یک بار به‌عنوان بنچمارک، و یک بار به‌عنوان وابستگی برای فایل‌های دودویی، بنچمارک‌ها و غیره). اهداف را می‌توان با تنظیم پرچم 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

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

مقادیر ممکن:

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

-r, --release

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

--profile name

ساخت با نمایه داده‌شده.

زیرفرمان rustc با نمایه‌های نام‌گذاری‌شده زیر با رفتارهای ویژه‌ای برخورد خواهد کرد:

•check — به همان روش دستور cargo-check(1) با نمایه dev می‌سازد.
•test — به همان روش دستور cargo-test(1) می‌سازد، و ساخت در حالت آزمایشی را فعال می‌کند که آزمون‌ها و گزینه cfg با نام test را فعال خواهد کرد. برای جزئیات بیشتر، rustc tests https://doc.rust-lang.org/rustc/tests/index.html را ببینید.
•bench — به همان روش دستور cargo-bench(1) می‌سازد، شبیه به نمایه test.

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

--timings

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

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

--crate-type crate-type

ساخت برای نوع کریت داده‌شده. این پرچم فهرستی از ۱ یا چند نوع کریت که با کاما از هم جدا شده‌اند را می‌پذیرد که مقادیر مجاز آن همانند فیلد crate-type در مانیفست برای پیکربندی یک مقصد Cargo است. برای مقادیر ممکن، فیلد crate-type https://doc.rust-lang.org/cargo/reference/cargo-targets.html#the-crate-type-field را ببینید.

اگر مانیفست شامل یک فهرست باشد و --crate-type ارائه شود، مقدار آرگومان خط فرمان بر آنچه در مانیفست است برتری خواهد داشت.

این پرچم تنها هنگام ساخت یک مقصد کتابخانه‌ای lib یا example کار می‌کند.

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

عدم چاپ پیام‌های گزارش (log) مربوط به 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

قالب خروجی برای پیام‌های خطایابی (diagnostic). می‌تواند چندین بار مشخص شود و شامل مقادیری است که با کاما از هم جدا شده‌اند. مقادیر معتبر:
•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 با خطا خارج خواهد شد:
•فایل قفل (lock file) وجود نداشته باشد.
•کارگو (Cargo) به دلیل تحلیل متفاوت وابستگی‌ها تلاش کند فایل قفل را تغییر دهد.

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

--offline

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

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

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

--frozen

معادل تعیین هر دو گزینهٔ --locked و --offline به‌صورت هم‌زمان است.

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

-j N, --jobs N

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

--keep-going

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

برای نمونه، اگر بسته کنونی به وابستگی‌های fails و works وابسته باشد که ساخت یکی از آن‌ها با شکست مواجه می‌شود، cargo rustc -j1 ممکن است موردی را که با موفقیت ساخته می‌شود بسازد یا نسازد (بسته به اینکه Cargo ابتدا ساخت کدام‌یک را برای اجرا انتخاب کرده باشد)، در حالی که cargo rustc -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.بررسی اینکه آیا بسته شما (بدون احتساب وابستگی‌ها) از کد ناامن (unsafe) استفاده می‌کند: 
cargo rustc --lib -- -D unsafe-code
2.آزمایش یک پرچم تجربی روی کامپایلر nightly، مانند این مورد که اندازه هر نوع داده (type) را چاپ می‌کند: 
cargo rustc --lib -- -Z print-type-sizes
3.رونویسی فیلد crate-type در Cargo.toml با استفاده از گزینه خط فرمان: 
cargo rustc --lib --crate-type lib,cdylib

cargo(1), cargo-build(1), rustc(1)