CARGO-INSTALL(1)

General Commands Manual

CARGO-INSTALL(1)

نام (NAME)

cargo-install - ساخت و نصب باینری Rust

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

cargo install [گزینه‌ها] crate[@version]…
cargo install [گزینه‌ها] --path path
cargo install [گزینه‌ها] --git url [crate…]
cargo install [گزینه‌ها] --list

توضیحات (DESCRIPTION)

این دستور مجموعهٔ محلی کریت‌های باینری نصب‌شده توسط Cargo را مدیریت می‌کند. تنها بسته‌هایی که دارای هدف‌های اجرایی [[bin]] یا [[example]] هستند قابلیت نصب دارند، و تمامی فایل‌های اجرایی در پوشهٔ bin واقع در ریشهٔ نصب قرار می‌گیرند. به‌طور پیش‌فرض تنها باینری‌ها نصب می‌شوند و نمونه‌ها (examples) نصب نخواهند شد.

ریشهٔ نصب به ترتیب اولویت زیر تعیین می‌شود:

•گزینهٔ --root

•متغیر محیطی CARGO_INSTALL_ROOT

•مقدار پیکربندی Cargo برای install.root https://doc.rust-lang.org/cargo/reference/config.html

•متغیر محیطی CARGO_HOME

•$HOME/.cargo

منابع متعددی وجود دارند که می‌توان یک کریت را از آن‌ها نصب کرد. منبع پیش‌فرض crates.io است، اما پرچم‌های --git، --path و --registry می‌توانند این منبع را تغییر دهند. اگر منبع حاوی بیش از یک بسته باشد (مانند crates.io یا یک مخزن git با چندین کریت)، آرگومان crate برای مشخص کردن این‌که کدام کریت باید نصب شود الزامی است.

کریت‌های دریافت‌شده از crates.io می‌توانند به صورت اختیاری نسخهٔ مورد نظر را از طریق پرچم --version تعیین کنند، و به همین ترتیب بسته‌های حاصل از مخازن git نیز می‌توانند شاخه، برچسب یا بازبینی (revision) مد نظر را مشخص نمایند. اگر یک کریت دارای چندین باینری باشد، با استفاده از آرگومان --bin می‌توان تنها یکی از آن‌ها را به صورت گزینشی نصب کرد؛ همچنین در صورت تمایل به نصب نمونه‌ها، می‌توان از آرگومان --example استفاده نمود.

اگر بسته از قبل نصب شده باشد، در صورتی که نسخهٔ نصب‌شده به‌روز به نظر نرسد، Cargo آن را مجدداً نصب خواهد کرد. در صورت تغییر هر یک از مقادیر زیر، Cargo اقدام به نصب مجدد بسته می‌کند:

•نسخه و منبع بسته.

•مجموعه نام‌های باینری‌های نصب‌شده.

•ویژگی‌های (features) انتخاب‌شده.

•پروفایل (--profile).

•معماری مقصد (--target).

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

اگر منبع crates.io یا --git باشد، کریت به‌طور پیش‌فرض در یک دایرکتوری مقصد موقت ساخته خواهد شد. برای جلوگیری از این رفتار، دایرکتوری مقصد را می‌توان با تنظیم متغیر محیطی CARGO_TARGET_DIR روی یک مسیر دلخواه مشخص کرد. این کار به‌ویژه برای کش کردن خروجی‌های ساخت در سامانه‌های یکپارچه‌سازی مداوم (CI) کاربرد دارد..SS "کار با فایل قفل (Dealing with the Lockfile)" به‌طور پیش‌فرض، فایل Cargo.lock که همراه با بسته قرار دارد نادیده گرفته خواهد شد. این بدان معناست که Cargo مجدداً محاسبه خواهد کرد که از کدام نسخه‌های وابستگی‌ها استفاده کند، و احتمالاً از نسخه‌های جدیدتری که از زمان انتشار بسته منتشر شده‌اند استفاده می‌کند. پرچم --locked می‌تواند برای وادار کردن Cargo به استفاده از فایل Cargo.lock موجود در بسته (در صورت وجود) به کار رود. این ویژگی می‌تواند برای اطمینان از ساخت‌های بازتولیدپذیر (reproducible builds) و استفاده از همان مجموعه دقیق وابستگی‌هایی که هنگام انتشار بسته در دسترس بودند، مفید باشد. همچنین اگر نسخه جدیدتری از یک وابستگی منتشر شود که دیگر روی سیستم شما ساخته نمی‌شود یا مشکلات دیگری دارد، کاربردی است. نکته منفی استفاده از --locked این است که هیچ‌گونه اصلاحیه یا به‌روزرسانی برای هیچ‌یک از وابستگی‌ها دریافت نخواهید کرد. توجه داشته باشید که Cargo تا نسخه 1.37 شروع به انتشار فایل‌های Cargo.lock نکرد؛ بدین معنا که بسته‌های منتشرشده با نسخه‌های پیشین، فایل Cargo.lock در دسترس نخواهند داشت.

کشف پیکربندی (Configuration Discovery)

این دستور در سطح سیستم یا کاربر عمل می‌کند، نه در سطح پروژه. این یعنی کشف پیکربندی محلی https://doc.rust-lang.org/cargo/reference/config.html#hierarchical-structure نادیده گرفته می‌شود. در عوض، کشف پیکربندی از $CARGO_HOME/config.toml آغاز می‌شود. اگر بسته با --path $PATH نصب شود، پیکربندی محلی استفاده خواهد شد که کشف آن از $PATH/.cargo/config.toml آغاز می‌گردد.

گزینه‌ها (OPTIONS)

گزینه‌های نصب (Install Options)

--vers version, --version version

مشخص کردن نسخه‌ای برای نصب. این مقدار می‌تواند یک الزام نسخه https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html مانند ~1.2 باشد تا Cargo تازه‌ترین نسخه را بر اساس الزام مشخص‌شده انتخاب کند. اگر نسخه دارای عملگر الزام (مانند ^ یا ~) نباشد، باید در قالب MAJOR.MINOR.PATCH باشد و دقیقاً همان نسخه را نصب خواهد کرد؛ برخلاف وابستگی‌های Cargo، با آن به عنوان یک الزام علامت هشتک (caret) برخورد نمی‌شود.

--git url

نشانی Git برای نصب crate مشخص‌شده از آن.

--branch branch

شاخه‌ای (branch) که هنگام نصب از git استفاده می‌شود.

--tag tag

برچسبی (tag) که هنگام نصب از git استفاده می‌شود.

--rev sha

کامیت مشخصی که هنگام نصب از git استفاده می‌شود.

--path path

مسیر سیستم‌فایل به crate محلی برای نصب از آن.

--list

فهرست کردن تمام بسته‌های نصب‌شده و نسخه‌های آن‌ها.

-n, --dry-run

(ناپایدار) انجام تمام بررسی‌ها بدون نصب.

-f, --force

اجبار به رونویسی crateها یا باینری‌های موجود. این گزینه زمانی که یک بسته یک باینری هم‌نام با بسته دیگری را نصب کرده باشد، می‌تواند استفاده شود. همچنین زمانی که چیزی در سیستم تغییر کرده و می‌خواهید مجدداً با آن بسازید، مانند نسخه جدیدتری از rustc، مفید است.

--no-track

به‌طور پیش‌فرض، Cargo بسته‌های نصب‌شده را با یک فایل متادیتا که در دایرکتوری ریشه نصب ذخیره می‌شود ردیابی می‌کند. این پرچم به Cargo می‌گوید که از آن فایل استفاده نکرده یا آن را ایجاد نکند. با این پرچم، Cargo از رونویسی هرگونه فایل موجود خودداری خواهد کرد مگر اینکه از پرچم --force استفاده شود. این پرچم همچنین توانایی Cargo را در محافظت در برابر چندین فراخوانی هم‌زمان Cargo برای نصب در یک زمان یکسان غیرفعال می‌کند.

--bin name…

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

--bins

تمام باینری‌ها را نصب می‌کند. این رفتار پیش‌فرض است.

--example name…

تنها مثال مشخص‌شده را نصب می‌کند.

--examples

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

--root dir

دایرکتوری برای نصب بسته‌ها در آن.

--registry registry

نام registry مورد استفاده. نام‌های registry در فایل‌های پیکربندی Cargo https://doc.rust-lang.org/cargo/reference/config.html تعریف شده‌اند. در صورت عدم تعیین، از registry پیش‌فرض استفاده می‌شود که توسط کلید پیکربندی registry.default تعریف شده و مقدار پیش‌فرض آن crates-io است.

--index index

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

نصب برای معماری مقصد مشخص‌شده. حالت پیش‌فرض معماری میزبان است. ساختار کلی سه‌تایی به‌صورت <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 value https://doc.rust-lang.org/cargo/reference/config.html نیز مشخص شود.

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

--target-dir directory

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

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

--debug

ساخت با پروفایل dev به‌جای پروفایل release. همچنین گزینهٔ --profile را برای انتخاب یک پروفایل خاص بر اساس نام ببینید.

--profile name

نصب با پروفایل داده‌شده. برای جزئیات بیشتر دربارهٔ پروفایل‌ها به مرجع https://doc.rust-lang.org/cargo/reference/profiles.html مراجعه کنید.

--timings

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

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

--ignore-rust-version

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

--locked

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

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

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

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

--offline

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

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

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

--frozen

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

گزینه‌های متفرقه (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 install -j1 ممکن است موردی را که ساختش موفقیت‌آمیز است بسازد یا نسازد (بسته به اینکه Cargo ابتدا اجرای کدام ساخت را انتخاب کرده باشد)، در حالی که cargo install -j1 --keep-going قطعاً هر دو ساخت را اجرا خواهد کرد، حتی اگر موردی که اول اجرا شده شکست بخورد.

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

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

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

•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 استفاده شود.

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