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

cargo-build - کامپایل بسته جاری

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

کامپایل بسته‌های محلی و تمام وابستگی‌های آن‌ها.

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

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

-p spec…, --package spec…

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

--workspace

تمام اعضای موجود در فضای کاری را می‌سازد.

--all

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

--exclude SPEC…

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

زمانی که هیچ گزینه‌ای برای انتخاب هدف ارائه نشده باشد، cargo build تمام هدف‌های دودویی (binary) و کتابخانه‌ایِ بسته‌های انتخاب‌شده را می‌سازد. در صورتی که فایل‌های دودویی دارای required-features باشند که ناموجود است، نادیده گرفته می‌شوند.

اگر یک آزمون یکپارچه‌سازی یا بنچ‌مارک برای ساخت انتخاب شده باشد، هدف‌های دودویی به‌طور خودکار ساخته می‌شوند. این کار به آزمون یکپارچه‌سازی اجازه می‌دهد تا فایل دودویی را برای سنجش و آزمایش رفتار آن اجرا کند. متغیر محیطی 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 نیز از الگوهای عمومی glob در یونیکس مانند *، ? و [] پشتیبانی می‌کنند. با این حال، برای جلوگیری از بسط تصادفی الگوهای glob توسط پوسته پیش از پردازش آن‌ها توسط Cargo، باید در اطراف هر الگوی glob از نقل‌قول‌های تکی یا جفتی استفاده کنید.

--lib

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

--bin name…

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

--bins

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

--example name…

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

--examples

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

--test name…

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

--tests

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

--bench name…

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

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

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

-r, --release

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

--profile name

با نمایهٔ داده‌شده ساخت را انجام می‌دهد. برای جزئیات بیشتر در مورد نمایه‌ها، مرجع 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 در ریشهٔ فضای کاری است.

--artifact-dir directory

مصنوعات نهایی را در این دایرکتوری کپی می‌کند.

این گزینه ناپایدار است و فقط در کانال nightly https://doc.rust-lang.org/book/appendix-07-nightly-rust.html در دسترس است و برای فعال‌سازی به پرچم -Z unstable-options نیاز دارد. برای اطلاعات بیشتر https://github.com/rust-lang/cargo/issues/6790 را ببینید.

-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

قالب خروجی برای پیام‌های تشخیصی (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 حاوی رندر “short” از 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 موجود نباشد.
•برنامه Cargo به دلیل حل متفاوت وابستگی‌ها، برای تغییر فایل lock تلاش کند.

این گزینه می‌تواند در محیط‌هایی که ساخت‌های قطعی و تکرارپذیر مورد نیاز است، مانند خطوط لولهٔ CI، استفاده شود.

--offline

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

توجه داشته باشید که این کار ممکن است منجر به حل وابستگی متفاوتی نسبت به حالت برخط شود. Cargo خود را به crateهایی که به‌صورت محلی بارگیری شده‌اند محدود می‌کند، حتی اگر طبق نسخهٔ محلی نمایه، نسخهٔ جدیدتری وجود داشته باشد. برای بارگیری وابستگی‌ها قبل از آفلاین شدن، دستور 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). برای اطلاعات بیشتر در مورد نحوهٔ عملکرد جایگزینی toolchain، مستندات 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 build -j1 بسته به اینکه Cargo کدام یک را ابتدا برای اجرا انتخاب کند ممکن است بسته‌ای را که با موفقیت ساخته می‌شود بسازد یا نسازد؛ در حالی که دستور cargo build -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 build
2.ساخت همراه با بهینه‌سازی‌ها: 
cargo build --release

cargo(1), cargo-rustc(1)