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

cargo-run - اجرای باینری یا مثال بسته فعلی در پروژه‌های Rust

cargo run [گزینه‌ها] [-- آرگومان‌ها]

یک فایل اجرایی (باینری) یا مثال از بسته محلی را اجرا می‌کند.

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

برخلاف cargo-test(1) و cargo-bench(1)، دستور cargo run دایرکتوری کاری فایل باینری در حال اجرا را روی دایرکتوری کاری فعلی تنظیم می‌کند؛ دقیقاً همانند زمانی که برنامه مستقیماً در شل اجرا می‌شود.

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

-p spec, --package spec

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

هنگامی که هیچ گزینه انتخاب هدفی مشخص نشده باشد، cargo run هدف باینری را اجرا می‌کند. اگر چندین هدف باینری وجود داشته باشد، باید با ارسال فلگ هدف یکی را انتخاب کنید. همچنین می‌توانید فیلد default-run را در بخش [package] فایل Cargo.toml مشخص کنید تا نام باینری پیش‌فرض برای اجرا تعیین شود.

--bin name

اجرای باینری مشخص‌شده.

--example name

اجرای مثال مشخص‌شده.

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

--target triple

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

-v, --verbose

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

-q, --quiet

عدم چاپ پیام‌های لاگ cargo. همچنین با مقدار پیکربندی term.quiet در config https://doc.rust-lang.org/cargo/reference/config.html قابل تنظیم است.

--color when

کنترل زمان استفاده از خروجی رنگی. مقادیر معتبر:
•auto (پیش‌فرض): تشخیص خودکار پشتیبانی ترمینال از رنگ.
•always: همیشه رنگ‌ها را نمایش بده.
•never: هرگز رنگ‌ها را نمایش نده.

همچنین با مقدار پیکربندی term.color در config https://doc.rust-lang.org/cargo/reference/config.html قابل تنظیم است.

--message-format fmt

قالب خروجی پیام‌های عیب‌یابی (diagnostics). می‌تواند چندین بار مشخص شود و شامل مقادیر جداشده با کاما است. مقادیر معتبر:
•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 و موارد دیگر همچنان صادر می‌شوند. با 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 خود را به کریت‌هایی که به‌صورت محلی بارگیری شده‌اند محدود می‌کند، حتی اگر نسخه جدیدتری بر اساس کپی محلی فهرست موجود باشد. برای بارگیری وابستگی‌ها قبل از آفلاین شدن، دستور cargo-fetch(1) را ببینید.

همچنین با مقدار پیکربندی net.offline در config 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 در config https://doc.rust-lang.org/cargo/reference/config.html مشخص شود. پیش‌فرض، تعداد پردازنده‌های منطقی است. اگر عدد منفی باشد، حداکثر تعداد وظایف موازی را روی تعداد پردازنده‌های منطقی به‌علاوه مقدار ارائه‌شده تنظیم می‌کند. اگر رشته default داده شود، مقدار را به حالت پیش‌فرض بازمی‌گرداند. نباید 0 باشد.

--keep-going

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

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

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

•0: اجرای Cargo با موفقیت انجام شد.
•101: اجرای Cargo با خطا مواجه شد.

1.ساخت بسته محلی و اجرای هدف باینری اصلی آن (با فرض وجود تنها یک باینری): 
cargo run
2.اجرای یک مثال با آرگومان‌های اضافی: 
cargo run --example exname -- --exoption exarg1 exarg2

cargo(1), cargo-build(1)