CARGO-PACKAGE(1)

General Commands Manual

CARGO-PACKAGE(1)

نام (NAME)

cargo-package - بسته‌بندی بسته محلی در یک tarball قابل توزیع

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

cargo package [گزینه‌ها]

توضیحات (DESCRIPTION)

این دستور یک فایل فشرده و قابل توزیع با پسوند .crate شامل کد منبع بسته در دایرکتوری جاری ایجاد می‌کند. فایل خروجی در دایرکتوری target/package ذخیره خواهد شد. این فرمان مراحل زیر را انجام می‌دهد:

1.بارگذاری و بررسی فضای کاری جاری و انجام برخی بررسی‌های اولیه.

•وابستگی‌های مبتنی بر مسیر (path dependencies) مجاز نیستند مگر اینکه دارای کلید version باشند. Cargo کلید path را برای وابستگی‌ها در بسته‌های منتشرشده نادیده می‌گیرد. بخش dev-dependencies این محدودیت را ندارد.

2.ایجاد فایل فشرده‌ی .crate.

•فایل اصلی Cargo.toml بازنویسی و نرمال‌سازی می‌شود.

•بخش‌های [patch]، [replace] و [workspace] از مانیفست حذف می‌شوند.

•فایل Cargo.lock همواره گنجانده می‌شود. در صورت نبود، یک فایل قفل جدید ایجاد می‌شود مگر اینکه از پرچم --exclude-lockfile استفاده شده باشد. در صورتی که پرچم --locked تعیین گردد، دستور cargo-install(1) از فایل قفل بسته‌بندی‌شده استفاده خواهد کرد.

•یک فایل .cargo_vcs_info.json قرار داده می‌شود که در صورت موجود بودن، حاوی اطلاعاتی پیرامون هش checkout فعلی VCS و همچنین پرچمی مبنی بر دست‌خورده بودن (dirty) درخت کاری است.

•پیوندهای نمادین (Symlinks) به فایل‌های مقصد خود تخت و تبدیل می‌شوند.

•فایل‌ها و دایرکتوری‌ها بر اساس قوانین ذکر شده در فیلدهای [include] و [exclude] https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields اضافه یا مستثنی می‌شوند.

3.استخراج فایل .crate و ساخت آن جهت اطمینان از امکان‌پذیر بودن فرآیند ساخت.

•این کار بسته شما را از ابتدا بازسازی می‌کند تا اطمینان حاصل شود که می‌تواند از یک وضعیت دست‌نخورده ساخته شود. می‌توان از پرچم --no-verify برای صرف‌نظر از این مرحله استفاده کرد.

4.بررسی اینکه اسکریپت‌های ساخت هیچ‌یک از فایل‌های منبع را دستکاری نکرده باشند.

فهرست فایل‌های گنجانده‌شده را می‌توان از طریق فیلدهای include و exclude در مانیفست مدیریت کرد.

برای جزئیات بیشتر پیرامون بسته‌بندی و انتشار، مرجع https://doc.rust-lang.org/cargo/reference/publishing.html را ببینید.

قالب .cargo_vcs_info.json (.cargo_vcs_info.json format)

یک فایل .cargo_vcs_info.json در قالب زیر تولید خواهد شد:

{
  "git": {
    "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302",
    "dirty": true
  },
  "path_in_vcs": ""
}

مقدار dirty نشان می‌دهد که آیا درخت کاری Git در زمان ساخته شدن بسته دست‌خورده بوده است یا خیر.

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

سازگاری این فایل تحت همان خط‌مشی خروجی JSON در دستور cargo-metadata(1) حفظ و مدیریت می‌شود.

توجه داشته باشید که این فایل اطلاعات VCS را به صورت یک تصویر لحظه‌ای بر مبنای نهایت تلاش ممکن (best-effort) ارائه می‌دهد. با این حال، اصالت و منشأ بسته اعتبارسنجی نمی‌شود. هیچ تضمینی وجود ندارد که کد منبع درون tarball دقیقاً با اطلاعات VCS مطابقت داشته باشد..SH "گزینه‌ها (OPTIONS)"

گزینه‌های بسته (Package Options)

-l, --list

چاپ فایل‌های موجود در بسته بدون ساخت آن.

--no-verify

محتویات را با ساختن آن‌ها راستی‌آزمایی نمی‌کند.

--no-metadata

هشدارهای مربوط به نبود متاداده‌های قابل استفاده برای انسان (مانند توضیحات یا پروانه) را نادیده می‌گیرد.

--allow-dirty

اجازه می‌دهد دایرکتوری‌های کاری دارای تغییرات ثبت‌نشده در VCS بسته‌بندی شوند.

--exclude-lockfile

هنگام بسته‌بندی، فایل قفل (lock file) را لحاظ نمی‌کند.

این پرچم برای استفادهٔ عمومی نیست. برخی ابزارها ممکن است انتظار حضور یک فایل قفل را داشته باشند (مانند cargo install --locked). پیش از استفاده از این گزینه، گزینه‌های دیگر را در نظر بگیرید.

--index index

آدرس URL مربوط به نمایهٔ (index) رجیستری مورد استفاده.

--registry registry

نام رجیستری برای بسته‌بندی؛ برای جزئیات بیشتر دربارهٔ پیکربندی نام‌های رجیستری، cargo publish --help را ببینید. بسته‌ها در این رجیستری منتشر نخواهند شد، اما اگر در حال بسته‌بندی چندین crate وابسته به یکدیگر باشیم، فایل‌های قفل با این فرض که وابستگی‌ها در این رجیستری منتشر خواهند شد تولید می‌شوند.

--message-format fmt

قالب پیام خروجی را مشخص می‌کند. در حال حاضر، این گزینه فقط با --list کار می‌کند و قالب فهرست فایل‌ها را تحت تأثیر قرار می‌دهد. این ویژگی ناپایدار است و به -Zunstable-options نیاز دارد. قالب‌های معتبر خروجی:

•human (پیش‌فرض): نمایش در قالب یک فایل در هر خط.

•json: تولید اطلاعات JSON ماشین‌خوان دربارهٔ هر بسته. یک بسته در هر خط JSON (به صورت Newline delimited JSON).

{
  /* The Package ID Spec of the package. */
  "id": "path+file:///home/foo#0.0.0",
  /* Files of this package */
  "files" {
    /* Relative path in the archive file. */
    "Cargo.toml.orig": {
      /* Where the file is from.
         - "generate" for file being generated during packaging
         - "copy" for file being copied from another location.
      */
      "kind": "copy",
      /* For the "copy" kind,
         it is an absolute path to the actual file content.
         For the "generate" kind,
         it is the original file the generated one is based on.
      */
      "path": "/home/foo/Cargo.toml"
    },
    "Cargo.toml": {
      "kind": "generate",
      "path": "/home/foo/Cargo.toml"
    },
    "src/main.rs": {
      "kind": "copy",
      "path": "/home/foo/src/main.rs"
    }
  }
}

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

گزینه‌های کامپایل (Compilation Options)

--target triple

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

--target-dir directory

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

انتخاب ویژگی (Feature Selection)

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

--manifest-path path

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

--locked

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

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

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

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

--offline

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

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

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

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

+toolchain

اگر Cargo با rustup نصب شده باشد، و نخستین آرگومان cargo با + آغاز شود، به‌عنوان نام یک زنجیره‌ابزار 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 را اجرا کنید.