نام (NAME)

shards - مدیر وابستگی‌های زبان Crystal

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

shards [<general_options>...] [<command>] [<command_options>...]

توضیحات (DESCRIPTION)

وابستگی‌های پروژه‌ها و کتابخانه‌های Crystal را با امکان نصب‌های تکرارپذیر در میان رایانه‌ها و سیستم‌های گوناگون مدیریت می‌کند.

نحوه استفاده (USAGE)

shards به وجود یک فایل shard.yml در پوشهٔ پروژه (دایرکتوری کاری) نیاز دارد. این فایل پروژه را توصیف کرده و وابستگی‌های لازم برای ساخت آن را فهرست می‌کند. برای اطلاعات بیشتر دربارهٔ قالب آن، shard.yml(5) را ببینید. یک فایل پیش‌فرض را می‌توان با اجرای shards init ایجاد کرد.

اجرای shards install وابستگی‌های مشخص‌شده را حل‌وفصل و نصب می‌کند. نگارش‌های نصب‌شده در یک فایل shard.lock نوشته می‌شوند تا هنگام اجرای مجدد shards install، دقیقاً از همان نگارش‌های وابستگی استفاده شود.

اگر شارد شما یک برنامه کاربردی می‌سازد، هر دو فایل shard.yml و shard.lock باید در سیستم کنترل نسخه ثبت شوند تا نصب تکرارپذیر وابستگی‌ها تضمین گردد. اگر این پروژه صرفاً کتابخانه‌ای است که دیگر شاردها به آن وابسته هستند، shard.lock نباید ثبت شود و تنها shard.yml باید در کنترل نسخه قرار گیرد. توصیه می‌شود آن را به .gitignore اضافه کنید.

دستورها (COMMANDS)

اگر هیچ commandی داده نشود، دستور install به‌طور پیش‌فرض اجرا خواهد شد.

برای مشاهدهٔ گزینه‌های موجود برای یک دستور مشخص، از --help پس از دستور استفاده کنید.

build [<targets>] [<build_options>...]

هدف‌های (<targets>) مشخص‌شده را در مسیر bin می‌سازد. اگر هدفی مشخص نشود، همهٔ آن‌ها ساخته می‌شوند. این دستور اطمینان حاصل می‌کند که تمام وابستگی‌ها نصب شده‌اند، بنابراین نیازی به اجرای قبلی shards install نیست.

تمامی گزینه‌های <build_options> که پس از این دستور می‌آیند به crystal build واگذار می‌شوند.

check

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

وضعیت خروج:

0

وابستگی‌ها برآورده شده‌اند.

1

وابستگی‌ها برآورده نشده‌اند.

init

یک فایل پیش‌فرض shard.yml را در پوشهٔ جاری مقداردهی اولیه می‌کند.

install [--frozen] [--without-development] [--production] [--skip-postinstall] [--skip-executables] [--jobs=N]

وابستگی‌ها را حل‌وفصل کرده و در پوشهٔ lib نصب می‌کند. اگر از قبل موجود نباشد، یک فایل shard.lock از وابستگی‌های حل‌شده تولید کرده و شماره‌های نگارش یا کامیت‌های Git را قفل می‌کند.

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

--frozen

دقیقاً نگارش‌های قفل‌شده از shard.lock را نصب می‌کند. در صورت عدم وجود shard.lock با خطا مواجه می‌شود.

--without-development

وابستگی‌های توسعه (development) را نصب نمی‌کند.

--production

همانند --frozen و --without-development.

--skip-postinstall

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

--skip-executables

فایل‌های اجرایی را نصب نمی‌کند.

--jobs

تعداد بارگیری‌های موازی مخازن (پیش‌فرض: 8). در حال حاضر فقط برای git.

list [--tree]

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

مشخص کردن --tree وابستگی‌های تو در تو را به جای یک فهرست مسطح، به صورت درختی مرتب می‌کند.

lock [--update [<shards>...]]

وابستگی‌ها را حل‌وفصل کرده و همانند دستور install فایل shard.lock را ایجاد یا به‌روزرسانی می‌کند، اما هرگز وابستگی‌ها را نصب نمی‌کند.

مشخص کردن --update از همان رفتار دستور update پیروی می‌کند.

outdated [--pre]

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

هنگامی که --pre مشخص شود، نگارش‌های پیش‌انتشار نیز در نظر گرفته می‌شوند.

prune

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

update [<shards>...]

بدون توجه به نگارش‌های قفل‌شده در فایل shard.lock، تمامی وابستگی‌ها را در پوشهٔ lib حل‌وفصل و به‌روزرسانی می‌کند. در نهایت یک فایل shard.lock جدید تولید می‌کند.

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

version [<path>]

نگارش کنونی شارد واقع در path (پیش‌فرض دایرکتوری جاری است) را چاپ می‌کند.

برای مشاهدهٔ گزینه‌های موجود برای یک دستور مشخص، از --help پس از دستور استفاده کنید.

گزینه‌های عمومی (GENERAL OPTIONS)

--version

نگارش shards را چاپ می‌کند.

-h, --help

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

--no-color

خروجی رنگی را غیرفعال می‌کند.

--local

حافظهٔ نهان (cache) مخزن راه دور را به‌روزرسانی نمی‌کند. در عوض، Shards از رونوشت‌های محلی موجود در حافظهٔ نهان استفاده خواهد کرد (ببینید SHARDS_CACHE_PATH). اگر یک وابستگی در حافظهٔ نهان در دسترس نباشد، دستور با شکست مواجه می‌شود.

-q, --quiet

میزان پرگویی گزارش‌ها را کاهش می‌دهد و فقط هشدارها و خطاها را چاپ می‌کند.

-v, --verbose

میزان پرگویی گزارش‌ها را افزایش می‌دهد و تمام گزاره‌های اشکال‌زدایی را چاپ می‌کند.

نصب (INSTALLATION)

معمولاً Shards همراه با خود Crystal توزیع می‌شود. در غیر این صورت، ممکن است بستهٔ shards جداگانه‌ای برای سیستم شما موجود باشد.

برای نصب از کد مبدأ، مخزن https://github.com/crystal-lang/shards را بارگیری یا clone کنید و دستور make CRFLAGS=--release را اجرا کنید. باینری کامپایل‌شده در bin/shards قرار دارد و باید به PATH اضافه شود.

متغیرهای محیطی (ENVIRONMENT VARIABLES)

SHARDS_OPTS

امکان ارسال گزینه‌های عمومی را در قالب یک متغیر محیطی فراهم می‌کند. مثال: SHARDS_OPTS="--no-color" shards update

SHARDS_CACHE_PATH

مسیر حافظهٔ نهان را تعیین می‌کند. در این پوشه، shards رونوشت‌های محلی مخازن راه دور را ذخیره می‌کند. پیش‌فرض .cache/shards در دایرکتوری خانگی ($XDG_CACHE_HOME یا $HOME) یا دایرکتوری جاری است.

SHARDS_INSTALL_PATH

مکانی را که وابستگی‌ها در آن نصب می‌شوند تعیین می‌کند. پیش‌فرض lib است.

SHARDS_BIN_PATH

مکانی را که فایل‌های اجرایی در آن نصب می‌شوند تعیین می‌کند. پیش‌فرض bin است.

CRYSTAL_VERSION

نگارش crystal را مشخص می‌کند که وابستگی‌ها باید با توجه به آن حل‌وفصل شوند. پیش‌فرض خروجیِ crystal env CRYSTAL_VERSION است.

SHARDS_OVERRIDE

مکان جایگزینی را برای shard.override.yml تعیین می‌کند.

فایل‌ها (FILES)

shard.yml

یک پروژهٔ shard را به همراه وابستگی‌های آن توصیف می‌کند. برای مستندات به shard.yml(5) مراجعه کنید.

shard.override.yml

امکان بازنویسی منبع و محدودیت وابستگی‌ها را فراهم می‌کند. یک مکان جایگزین را می‌توان با متغیر محیطی SHARDS_OVERRIDE پیکربندی کرد.

این فایل حاوی یک سند YAML با یک کلید واحدِ dependencies است. معنای آن همانند آنچه در shard.yml آمده می‌باشد. پیکربندی وابستگی در این فایل بر پیکربندی موجود در shard.yml یا هر shard.yml متعلق به وابستگی‌ها اولویت دارد.

موارد کاربرد آن شامل رونوشت‌های کاری محلی، تحمیل یک نگارش خاص از وابستگی علی‌رغم محدودیت‌های ناسازگار، اصلاح یک وابستگی، و بررسی سازگاری با نگارش‌های منتشرنشدهٔ وابستگی‌ها است.

shard.lock

فایل قفلی که اطلاعات مربوط به نگارش‌های نصب‌شده را ذخیره می‌کند.

اگر شارد شما یک برنامه کاربردی می‌سازد، shard.lock باید در کنترل نسخه ثبت شود تا نصب تکرارپذیر وابستگی‌ها تضمین گردد.

اگر صرفاً کتابخانه‌ای برای وابستگی دیگر شاردها است، shard.lock نباید ثبت شود و تنها shard.yml ثبت گردد. توصیه می‌شود که آن را به .gitignore اضافه کنید.

گزارش باگ‌ها (BUGS)

گزارش باگ‌های shards به https://github.com/crystal-lang/shards/issues

صفحهٔ اصلی زبان Crystal: https://crystal-lang.org

کپی‌رایت و تکثیر (COPYRIGHT)

مجوز Apache 2.0 http://www.apache.org/licenses/LICENSE-2.0

این نرم‌افزار آزاد است: شما در تغییر و بازتوزیع آن آزاد هستید. هیچ ضمانتی وجود ندارد، تا حدی که قانون اجازه می‌دهد.

نویسندگان (AUTHORS)

نوشته شده توسط Julien Portalier و پروژهٔ Crystal.

همچنین ببینید (SEE ALSO)

shard.yml(5)