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

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

خلاصه دستور (SYNOPSIS)
       cargo rustc [options] [-- args]

توضیحات (DESCRIPTION)
       هدف مشخص‌شده برای بستهٔ جاری (یا بستهٔ مشخص‌شده با -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> استفاده کنید.

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

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

   انتخاب هدف (Target Selection)
       هنگامی که هیچ گزینهٔ انتخابی برای هدف تعیین نشود، 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 بسته‌های انتخاب‌شده را فعال نمی‌کند.

   گزینه‌های کامپایل (Compilation Options)
       --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 کار
           می‌کند.

   گزینه‌های خروجی (Output Options)
       --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 Options)
       --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 را اجرا کنید.

   گزینه‌های متفرقه (Miscellaneous Options)
       -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) مراجعه کنید.

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

وضعیت خروج (EXIT STATUS)
       •   0: Cargo با موفقیت پایان یافت.

       •   101: فرایند Cargo با شکست مواجه شد.

مثال‌ها (EXAMPLES)
        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

همچنین ببینید (SEE ALSO)
       cargo(1), cargo-build(1), rustc(1)

                                                                CARGO-RUSTC(1)