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

cargo-add - افزودن وابستگی‌ها به فایل مانیفست Cargo.toml

cargo add [گزینه‌ها] crate…
cargo add [گزینه‌ها] --path path
cargo add [گزینه‌ها] --git url [crate…]

این دستور می‌تواند وابستگی‌ها را اضافه کرده یا تغییر دهد.

منبع وابستگی را می‌توان با موارد زیر مشخص کرد:

•crate@version: دریافت از یک رجیستری با قید نگارش “version”
•--path path: دریافت از path مشخص‌شده
•--git url: دریافت از یک مخزن git در url

اگر هیچ منبعی مشخص نشود، بهترین تلاش برای انتخاب یک منبع صورت خواهد گرفت، شامل:

•وابستگی‌های موجود در سایر جدول‌ها (مانند dev-dependencies)
•اعضای workspace
•آخرین نسخهٔ منتشرشده در رجیستری

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

پس از اجرای موفقیت‌آمیز، ویژگی‌های https://doc.rust-lang.org/cargo/reference/features.html فعال (+) و غیرفعال (-) وابستگیِ مشخص‌شده در خروجی دستور فهرست خواهند شد.

--git url

آدرس اینترنتی Git برای افزودن crate مشخص‌شده از آن https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories.

--branch branch

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

--tag tag

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

--rev sha

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

--path path

مسیر سیستم فایل https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-path-dependencies به crate محلی برای افزودن.

--base base

مبنای مسیر (path base https://doc.rust-lang.org/cargo/reference/unstable.html#path-bases) مورد استفاده هنگام افزودن crate محلی.

ناپایدار (تنها در nightly) https://doc.rust-lang.org/cargo/reference/unstable.html#path-bases

--registry registry

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

--dev

افزودن به عنوان یک وابستگی توسعه https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#development-dependencies.

--build

افزودن به عنوان یک وابستگی ساخت https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#build-dependencies.

--target target

افزودن به عنوان وابستگی برای سکوی هدف داده‌شده https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies.

برای جلوگیری از بسط‌های غیرمنتظره در پوسته، می‌توانید در اطراف هر هدف از علامت نقل‌قول استفاده کنید، مانند --target 'cfg(unix)'.

--dry-run

در عمل تغییرات را در مانیفست ثبت نمی‌کند

--rename name

تغییر نام https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml وابستگی.

--optional

علامت‌گذاری وابستگی به عنوان اختیاری https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies.

--no-optional

علامت‌گذاری وابستگی به عنوان ضروری https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies.

--public

علامت‌گذاری وابستگی به صورت عمومی (public).

این وابستگی می‌تواند در API عمومی کتابخانه شما مورد ارجاع قرار گیرد.

ناپایدار (فقط nightly) https://doc.rust-lang.org/cargo/reference/unstable.html#public-dependency

--no-public

علامت‌گذاری وابستگی به صورت خصوصی (private).

اگرچه می‌توانید از این crate در پیاده‌سازی خود استفاده کنید، اما نمی‌توان در API عمومی شما به آن ارجاع داد.

ناپایدار (فقط nightly) https://doc.rust-lang.org/cargo/reference/unstable.html#public-dependency

--no-default-features

غیرفعال‌سازی ویژگی‌های پیش‌فرض https://doc.rust-lang.org/cargo/reference/features.html#dependency-features.

--default-features

فعال‌سازی مجدد ویژگی‌های پیش‌فرض https://doc.rust-lang.org/cargo/reference/features.html#dependency-features.

-F features, --features features

فهرستی از ویژگی‌ها برای فعال‌سازی https://doc.rust-lang.org/cargo/reference/features.html#dependency-features که با فاصله یا کاما از یکدیگر جدا شده‌اند. هنگام افزودن چندین crate، ویژگی‌های یک crate خاص را می‌توان با نحو package-name/feature-name فعال کرد. این پرچم می‌تواند چندین بار مشخص شود که تمام ویژگی‌های تعیین‌شده را فعال می‌کند.

-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 مشخص شود.

--manifest-path path

مسیر فایل Cargo.toml. به طور پیش‌فرض، Cargo فایل Cargo.toml را در دایرکتوری فعلی یا هر یک از دایرکتوری‌های والد جستجو می‌کند.

-p spec, --package spec

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

--ignore-rust-version

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

--locked

تضمین می‌کند که دقیقاً از همان وابستگی‌ها و نسخه‌هایی استفاده شود که هنگام ایجاد اولیهٔ فایل موجود Cargo.lock استفاده شده بودند. در صورت بروز هر یک از شرایط زیر، Cargo با خطا خارج خواهد شد:
•فایل قفل (lock file) وجود نداشته باشد.
•سامانهٔ Cargo به دلیل حل متفاوت وابستگی‌ها، برای تغییر فایل قفل تلاش کند.

این گزینه می‌تواند در محیط‌هایی که در آن‌ها ساخت‌های قطعی و تکرارپذیر (deterministic builds) مورد نیاز است، مانند خطوط لولهٔ 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.

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

•0: عملیات Cargo با موفقیت انجام شد.
•101: عملیات Cargo با شکست مواجه شد.

1.افزودن regex به‌عنوان یک وابستگی 
cargo add regex
2.افزودن trybuild به‌عنوان یک وابستگی توسعه (dev-dependency) 
cargo add --dev trybuild
3.افزودن نسخه‌ای قدیمی‌تر از nom به‌عنوان یک وابستگی 
cargo add nom@5
4.افزودن پشتیبانی از سریال‌سازی ساختارهای داده به json با استفاده از deriveها 
cargo add serde serde_json -F serde/derive
5.افزودن windows به‌عنوان یک وابستگی ویژه پلتفرم در cfg(windows) 
cargo add windows --target 'cfg(windows)'

cargo(1), cargo-remove(1)