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

cargo-tree - نمایش ساختار درختی گراف وابستگی‌ها

cargo tree [options]

این دستور درختی از وابستگی‌ها را در ترمینال نمایش می‌دهد. نمونه‌ای از یک پروژهٔ ساده که به بستهٔ “rand” وابسته است:

myproject v0.1.0 (/myproject)
`-- rand v0.7.3
    |-- getrandom v0.1.14
    |   |-- cfg-if v0.1.10
    |   `-- libc v0.2.68
    |-- libc v0.2.68 (*)
    |-- rand_chacha v0.2.2
    |   |-- ppv-lite86 v0.2.6
    |   `-- rand_core v0.5.1
    |       `-- getrandom v0.1.14 (*)
    `-- rand_core v0.5.1 (*)
[build-dependencies]
`-- cc v1.0.50

بسته‌هایی که با (*) علامت‌گذاری شده‌اند “تکرارزدایی” شده‌اند. وابستگی‌های این بسته پیش‌تر در جای دیگری از گراف نشان داده شده‌اند و به همین دلیل تکرار نمی‌شوند. برای تکرار موارد مشابه، از گزینهٔ --no-dedupe استفاده کنید.

پرچم -e می‌تواند برای انتخاب انواع وابستگی جهت نمایش به کار رود. نوع “features” خروجی را تغییر می‌دهد تا ویژگی‌های فعال‌شده توسط هر وابستگی را نمایش دهد. برای مثال، cargo tree -e features:

myproject v0.1.0 (/myproject)
`-- log feature "serde"
    `-- log v0.4.8
        |-- serde v1.0.106
        `-- cfg-if feature "default"
            `-- cfg-if v0.1.10

در این درخت، myproject با ویژگی serde به log وابسته است. log نیز به نوبهٔ خود با ویژگی‌های پیش‌فرض (“default”) به cfg-if وابسته است. هنگام استفاده از -e features، استفاده از پرچم -i برای نمایش چگونگی جریان یافتن ویژگی‌ها به درون یک بسته می‌تواند مفید باشد. برای جزئیات بیشتر مثال‌های زیر را ببینید.

این دستور گرافی را نشان می‌دهد که بسیار نزدیک‌تر به گراف یکپارچه‌شده از نظر ویژگی‌ها است که توسط Cargo ساخته خواهد شد، نه صرفاً آنچه در Cargo.toml فهرست کرده‌اید. برای نمونه، اگر وابستگی یکسانی را هم در [dependencies] و هم در [dev-dependencies] مشخص کرده باشید اما با ویژگی‌های فعال متفاوت، این دستور ممکن است همهٔ ویژگی‌ها را ادغام کرده و یک (*) را روی یکی از وابستگی‌ها برای مشخص کردن مورد تکراری نمایش دهد.

در نتیجه، برای یک نمای کلی تقریباً معادل با آنچه cargo build انجام می‌دهد، دستور cargo tree -e normal,build بسیار نزدیک است؛ برای یک نمای کلی تقریباً معادل با آنچه cargo test انجام می‌دهد، cargo tree بسیار نزدیک است. با این حال، تطابق دقیق با آنچه Cargo قرار است بسازد تضمین نمی‌شود، چرا که فرایند کامپایل پیچیده است و به عوامل متعدد گوناگونی بستگی دارد.

برای کسب اطلاعات بیشتر دربارهٔ یکپارچه‌سازی ویژگی‌ها، این بخش اختصاصی https://doc.rust-lang.org/cargo/reference/features.html#feature-unification را بررسی کنید.

-i spec, --invert spec

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

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

--prune spec

بستهٔ داده‌شده را از نمایش درخت وابستگی هرس (حذف) می‌کند.

--depth depth

حداکثر عمق نمایش درخت وابستگی. برای مثال، عمق ۱ وابستگی‌های مستقیم را نمایش می‌دهد.

اگر مقدار داده‌شده workspace باشد، در عوض تنها وابستگی‌هایی را نشان می‌دهد که عضو فضای کاری جاری هستند.

--no-dedupe

وابستگی‌های تکراری را تکرارزدایی نمی‌کند. معمولاً هنگامی که یک بسته وابستگی‌های خود را یک‌بار نمایش داده باشد، در تکرارهای بعدی وابستگی‌های آن دوباره نمایش داده نمی‌شوند و یک علامت (*) گنجانده می‌شود تا نشان دهد قبلاً نمایش داده شده است. این پرچم باعث می‌شود آن موارد تکراری دوباره تکرار شوند.

-d, --duplicates

تنها وابستگی‌هایی را نمایش می‌دهد که در چندین نسخه وجود دارند (شامل --invert نیز می‌شود). هنگامی که همراه با پرچم -p استفاده شود، تنها موارد تکراری درون زیردرخت بستهٔ داده‌شده را نمایش می‌دهد.

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

-e kinds, --edges kinds

انواع وابستگی جهت نمایش. فهرستی از مقادیر جداشده با کاما را دریافت می‌کند:
•all — نمایش همهٔ انواع یال‌ها.
•normal — نمایش وابستگی‌های عادی.
•build — نمایش وابستگی‌های ساخت (build).
•dev — نمایش وابستگی‌های توسعه (dev).
•features — نمایش ویژگی‌های فعال‌شده توسط هر وابستگی. اگر این تنها نوع ارائه‌شده باشد، به‌طور خودکار انواع دیگر وابستگی را نیز در بر می‌گیرد.
•no-normal — عدم درج وابستگی‌های عادی.
•no-build — عدم درج وابستگی‌های ساخت.
•no-dev — عدم درج وابستگی‌های توسعه.
•no-proc-macro — عدم درج وابستگی‌های ماکروی رویه‌ای (procedural macro).

انواع وابستگی normal، build، dev و all را نمی‌توان با انواع وابستگی no-normal، no-build یا no-dev ترکیب کرد.

پیش‌فرض normal,build,dev است.

--target triple

پالایش وابستگی‌های منطبق با target triple https://doc.rust-lang.org/cargo/appendix/glossary.html#target مشخص‌شده. پیش‌فرض، پلتفرم میزبان است. برای شامل کردن تمام مقاصد، از مقدار all استفاده کنید.

--charset charset

مجموعه نویسه‌های مورد استفاده برای درخت را انتخاب می‌کند. مقادیر معتبر “utf8” یا “ascii” هستند. در صورت مشخص نشدن، cargo مقدار مناسب را به‌طور خودکار انتخاب خواهد کرد.

-f format, --format format

رشته قالب‌بندی را برای هر بسته تعیین می‌کند. مقدار پیش‌فرض “{p}” است.

این یک رشته دلخواه است که برای نمایش هر بسته استفاده خواهد شد. رشته‌های زیر با مقدار متناظر خود جایگزین می‌شوند:

•{p}, {package} — نام بسته.
•{l}, {license} — مجوز بسته.
•{r}, {repository} — نشانی اینترنتی (URL) مخزن بسته.
•{f}, {features} — فهرستی جداشده با کاما از ویژگی‌های فعال‌شده بسته.
•{lib} — نام کتابخانه بسته، همان‌گونه که در دستور use استفاده می‌شود.

--prefix prefix

نحوه نمایش هر خط را تعیین می‌کند. مقدار prefix می‌تواند یکی از موارد زیر باشد:
•indent (پیش‌فرض) — هر خط را با تورفتگی به صورت درختی نمایش می‌دهد.
•depth — نمایش به صورت فهرست، در حالی که عمق عددی قبل از هر مدخل چاپ می‌شود.
•none — نمایش به صورت یک فهرست مسطح.

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

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

-p spec…, --package spec…

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

--workspace

تمام اعضای موجود در فضای کاری را نمایش می‌دهد.

--exclude SPEC…

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

--manifest-path path

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

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

-v, --verbose

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

-q, --quiet

عدم چاپ پیام‌های گزارش (log) کارگو. همچنین می‌تواند با مقدار پیکربندی 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 تعیین شود.

+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.نمایش درخت برای بسته در دایرکتوری فعلی: 
cargo tree
2.نمایش تمام بسته‌هایی که به بستهٔ syn وابستگی دارند: 
cargo tree -i syn
3.نمایش ویژگی‌های فعال‌شده در هر بسته: 
cargo tree --format "{p} {f}"
4.نمایش تمام بسته‌هایی که چندین بار ساخته شده‌اند. این اتفاق زمانی می‌تواند رخ دهد که چندین نسخهٔ ناسازگار با semver در درخت ظاهر شوند (مانند 1.0.0 و 2.0.0). 
cargo tree -d
5.توضیح این که چرا ویژگی‌ها برای بستهٔ syn فعال شده‌اند: 
cargo tree -e features -i syn

پرچم -e features برای نمایش ویژگی‌ها استفاده می‌شود. پرچم -i برای معکوس کردن گراف استفاده می‌شود تا بسته‌هایی را که به syn وابستگی دارند نمایش دهد. نمونه‌ای از آنچه نمایش داده خواهد شد:

syn v1.0.17
|-- syn feature "clone-impls"
|   `-- syn feature "default"
|       `-- rustversion v1.0.2
|           `-- rustversion feature "default"
|               `-- myproject v0.1.0 (/myproject)
|                   `-- myproject feature "default" (command-line)
|-- syn feature "default" (*)
|-- syn feature "derive"
|   `-- syn feature "default" (*)
|-- syn feature "full"
|   `-- rustversion v1.0.2 (*)
|-- syn feature "parsing"
|   `-- syn feature "default" (*)
|-- syn feature "printing"
|   `-- syn feature "default" (*)
|-- syn feature "proc-macro"
|   `-- syn feature "default" (*)
`-- syn feature "quote"
    |-- syn feature "printing" (*)
    `-- syn feature "proc-macro" (*)

برای خواندن این گراف، می‌توانید زنجیره را برای هر ویژگی از ریشه دنبال کنید تا ببینید چرا گنجانده شده است. برای مثال، ویژگی “full” توسط کریت rustversion اضافه شده است که خود از myproject (با ویژگی‌های پیش‌فرض) گنجانده شده، و myproject بسته‌ای است که در خط فرمان انتخاب شده است. تمامی ویژگی‌های دیگر syn توسط ویژگی “default” اضافه شده‌اند (“quote” توسط “printing” و “proc-macro” اضافه شده است که هر دوی آنها جزو ویژگی‌های پیش‌فرض هستند).

اگر در ارجاع متقابل ورودی‌های تکرارزدایی‌شدهٔ (*) با مشکل مواجه شدید، پرچم --no-dedupe را امتحان کنید تا خروجی کامل را دریافت نمایید. cargo(1), cargo-metadata(1)