'\" t
.\"     Title: shards
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.23
.\"      Date: 2025-01-23
.\"    Manual: Shards Manual
.\"    Source: shards 0.19.1
.\"  Language: English
.\"
.TH "SHARDS" "1" "2025-01-23" "shards 0.19.1" "Shards Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "نام (NAME)"
shards \- مدیر وابستگی‌های زبان Crystal
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBshards\fP [\fI<general_options>\fP...] [\fI<command>\fP] [\fI<command_options>\fP...]
.SH "توضیحات (DESCRIPTION)"
.sp
وابستگی‌های پروژه‌ها و کتابخانه‌های Crystal را با امکان نصب‌های تکرارپذیر در میان رایانه‌ها و سیستم‌های گوناگون مدیریت می‌کند.
.SH "نحوه استفاده (USAGE)"
.sp
\fIshards\fP به وجود یک فایل \fIshard.yml\fP در پوشهٔ پروژه (دایرکتوری کاری) نیاز دارد. این فایل پروژه را توصیف کرده و وابستگی‌های لازم برای ساخت آن را فهرست می‌کند. برای اطلاعات بیشتر دربارهٔ قالب آن، \fBshard.yml\fP(5) را ببینید. یک فایل پیش‌فرض را می‌توان با اجرای \fIshards init\fP ایجاد کرد.
.sp
اجرای \fIshards install\fP وابستگی‌های مشخص‌شده را حل‌وفصل و نصب می‌کند. نگارش‌های نصب‌شده در یک فایل \fBshard.lock\fP نوشته می‌شوند تا هنگام اجرای مجدد \fIshards install\fP، دقیقاً از همان نگارش‌های وابستگی استفاده شود.
.sp
اگر شارد شما یک برنامه کاربردی می‌سازد، هر دو فایل \fBshard.yml\fP و \fBshard.lock\fP باید در سیستم کنترل نسخه ثبت شوند تا نصب تکرارپذیر وابستگی‌ها تضمین گردد. اگر این پروژه صرفاً کتابخانه‌ای است که دیگر شاردها به آن وابسته هستند، \fBshard.lock\fP \fIنباید\fP ثبت شود و تنها \fBshard.yml\fP باید در کنترل نسخه قرار گیرد. توصیه می‌شود آن را به \fB.gitignore\fP اضافه کنید.
.SH "دستورها (COMMANDS)"
.sp
اگر هیچ \fIcommand\fPی داده نشود، دستور \fBinstall\fP به‌طور پیش‌فرض اجرا خواهد شد.
.sp
برای مشاهدهٔ گزینه‌های موجود برای یک دستور مشخص، از \fI\-\-help\fP پس از دستور استفاده کنید.
.sp
\fBbuild\fP [\fI<targets>\fP] [\fI<build_options>\fP...]
.RS 4
هدف‌های (\fI<targets>\fP) مشخص‌شده را در مسیر \fBbin\fP می‌سازد. اگر هدفی مشخص نشود، همهٔ آن‌ها ساخته می‌شوند.
این دستور اطمینان حاصل می‌کند که تمام وابستگی‌ها نصب شده‌اند، بنابراین نیازی به اجرای قبلی \fBshards install\fP نیست.
.sp
تمامی گزینه‌های \fI<build_options>\fP که پس از این دستور می‌آیند به \fBcrystal build\fP واگذار می‌شوند.
.RE
.sp
\fBcheck\fP
.RS 4
بررسی می‌کند که آیا همهٔ وابستگی‌ها نصب شده و نیازمندی‌ها برآورده شده‌اند یا خیر.
.sp
وضعیت خروج:
.sp
\fB0\fP
.RS 4
وابستگی‌ها برآورده شده‌اند.
.RE
.sp
\fB1\fP
.RS 4
وابستگی‌ها برآورده نشده‌اند.
.RE
.RE
.sp
\fBinit\fP
.RS 4
یک فایل پیش‌فرض \fIshard.yml\fP را در پوشهٔ جاری مقداردهی اولیه می‌کند.
.RE
.sp
\fBinstall\fP [\-\-frozen] [\-\-without\-development] [\-\-production] [\-\-skip\-postinstall] [\-\-skip\-executables] [\-\-jobs=N]
.RS 4
وابستگی‌ها را حل‌وفصل کرده و در پوشهٔ \fIlib\fP نصب می‌کند. اگر از قبل موجود نباشد، یک فایل \fIshard.lock\fP از وابستگی‌های حل‌شده تولید کرده و شماره‌های نگارش یا کامیت‌های Git را قفل می‌کند.
.sp
در صورت وجود فایل \fIshard.lock\fP، نگارش‌ها و کامیت‌های قفل‌شده را خوانده و اعمال می‌کند. در صورتی که یک نگارش قفل‌شده با نیازمندی مطابقت نداشته باشد ممکن است دستور \fBinstall\fP شکست بخورد، اما در صورتی که وابستگی جدیدی اضافه شده باشد، تا زمانی که تداخلی ایجاد نکند موفق خواهد شد و یک فایل \fIshard.lock\fP جدید تولید خواهد کرد.
.sp
\-\-frozen
.RS 4
دقیقاً نگارش‌های قفل‌شده از \fIshard.lock\fP را نصب می‌کند. در صورت عدم وجود \fIshard.lock\fP با خطا مواجه می‌شود.
.RE
.sp
\-\-without\-development
.RS 4
وابستگی‌های توسعه (development) را نصب نمی‌کند.
.RE
.sp
\-\-production
.RS 4
همانند \fI\-\-frozen\fP و \fI\-\-without\-development\fP.
.RE
.sp
\-\-skip\-postinstall
.RS 4
اسکریپت‌های پس از نصب (postinstall) وابستگی‌ها را اجرا نمی‌کند.
.RE
.sp
\-\-skip\-executables
.RS 4
فایل‌های اجرایی را نصب نمی‌کند.
.RE
.sp
\-\-jobs
.RS 4
تعداد بارگیری‌های موازی مخازن (پیش‌فرض: 8). در حال حاضر فقط برای git.
.RE
.RE
.sp
\fBlist\fP [\-\-tree]
.RS 4
وابستگی‌های نصب‌شده و نگارش‌های آن‌ها را فهرست می‌کند.
.sp
مشخص کردن \fI\-\-tree\fP وابستگی‌های تو در تو را به جای یک فهرست مسطح، به صورت درختی مرتب می‌کند.
.RE
.sp
\fBlock\fP [\-\-update [<shards>...]]
.RS 4
وابستگی‌ها را حل‌وفصل کرده و همانند دستور \fBinstall\fP فایل \fIshard.lock\fP را ایجاد یا به‌روزرسانی می‌کند، اما هرگز وابستگی‌ها را نصب نمی‌کند.
.sp
مشخص کردن \fI\-\-update\fP از همان رفتار دستور \fBupdate\fP پیروی می‌کند.
.RE
.sp
\fBoutdated\fP [\-\-pre]
.RS 4
وابستگی‌های قدیمی‌شده را فهرست می‌کند.
.sp
هنگامی که \fI\-\-pre\fP مشخص شود، نگارش‌های پیش‌انتشار نیز در نظر گرفته می‌شوند.
.RE
.sp
\fBprune\fP
.RS 4
وابستگی‌های استفاده‌نشده را از پوشهٔ \fIlib\fP حذف می‌کند.
.RE
.sp
\fBupdate\fP [<shards>...]
.RS 4
بدون توجه به نگارش‌های قفل‌شده در فایل \fIshard.lock\fP، تمامی وابستگی‌ها را در پوشهٔ \fIlib\fP حل‌وفصل و به‌روزرسانی می‌کند.
در نهایت یک فایل \fIshard.lock\fP جدید تولید می‌کند.
.sp
مشخص کردن \fIshards\fP فقط این وابستگی‌ها را به‌روزرسانی می‌کند و تلاش می‌کند تا جای ممکن در قبال سایر وابستگی‌ها محتاطانه عمل کرده و به نگارش‌های قفل‌شده در فایل \fIshard.lock\fP پایبند بماند.
.RE
.sp
\fBversion\fP [\fI<path>\fP]
.RS 4
نگارش کنونی شارد واقع در \fIpath\fP (پیش‌فرض دایرکتوری جاری است) را چاپ می‌کند.
.RE
.sp
برای مشاهدهٔ گزینه‌های موجود برای یک دستور مشخص، از \fB\-\-help\fP پس از دستور استفاده کنید.
.SH "گزینه‌های عمومی (GENERAL OPTIONS)"
.sp
\-\-version
.RS 4
نگارش \fIshards\fP را چاپ می‌کند.
.RE
.sp
\-h, \-\-help
.RS 4
خلاصهٔ کاربرد دستور را چاپ می‌کند.
.RE
.sp
\-\-no\-color
.RS 4
خروجی رنگی را غیرفعال می‌کند.
.RE
.sp
\-\-local
.RS 4
حافظهٔ نهان (cache) مخزن راه دور را به‌روزرسانی نمی‌کند. در عوض، Shards از رونوشت‌های محلی موجود در حافظهٔ نهان استفاده خواهد کرد (ببینید \fBSHARDS_CACHE_PATH\fP).
اگر یک وابستگی در حافظهٔ نهان در دسترس نباشد، دستور با شکست مواجه می‌شود.
.RE
.sp
\-q, \-\-quiet
.RS 4
میزان پرگویی گزارش‌ها را کاهش می‌دهد و فقط هشدارها و خطاها را چاپ می‌کند.
.RE
.sp
\-v, \-\-verbose
.RS 4
میزان پرگویی گزارش‌ها را افزایش می‌دهد و تمام گزاره‌های اشکال‌زدایی را چاپ می‌کند.
.RE
.SH "نصب (INSTALLATION)"
.sp
معمولاً Shards همراه با خود Crystal توزیع می‌شود. در غیر این صورت، ممکن است بستهٔ \fIshards\fP جداگانه‌ای برای سیستم شما موجود باشد.
.sp
برای نصب از کد مبدأ،
.URL "https://github.com/crystal\-lang/shards" "مخزن" ""
را بارگیری یا clone کنید و دستور
\fBmake CRFLAGS=\-\-release\fP را اجرا کنید. باینری کامپایل‌شده در \fIbin/shards\fP قرار دارد و باید به \fBPATH\fP اضافه شود.
.SH "متغیرهای محیطی (ENVIRONMENT VARIABLES)"
.sp
SHARDS_OPTS
.RS 4
امکان ارسال گزینه‌های عمومی را در قالب یک متغیر محیطی فراهم می‌کند.
\fBمثال\fP: \fISHARDS_OPTS="\-\-no\-color" shards update\fP
.RE
.sp
SHARDS_CACHE_PATH
.RS 4
مسیر حافظهٔ نهان را تعیین می‌کند. در این پوشه، shards رونوشت‌های محلی مخازن راه دور را ذخیره می‌کند.
پیش‌فرض \fI.cache/shards\fP در دایرکتوری خانگی (\fI$XDG_CACHE_HOME\fP یا \fI$HOME\fP) یا دایرکتوری جاری است.
.RE
.sp
SHARDS_INSTALL_PATH
.RS 4
مکانی را که وابستگی‌ها در آن نصب می‌شوند تعیین می‌کند.
پیش‌فرض \fIlib\fP است.
.RE
.sp
SHARDS_BIN_PATH
.RS 4
مکانی را که فایل‌های اجرایی در آن نصب می‌شوند تعیین می‌کند.
پیش‌فرض \fIbin\fP است.
.RE
.sp
CRYSTAL_VERSION
.RS 4
نگارش crystal را مشخص می‌کند که وابستگی‌ها باید با توجه به آن حل‌وفصل شوند.
پیش‌فرض خروجیِ \fIcrystal env CRYSTAL_VERSION\fP است.
.RE
.sp
SHARDS_OVERRIDE
.RS 4
مکان جایگزینی را برای \fIshard.override.yml\fP تعیین می‌کند.
.RE
.SH "فایل‌ها (FILES)"
.sp
shard.yml
.RS 4
یک پروژهٔ shard را به همراه وابستگی‌های آن توصیف می‌کند.
برای مستندات به \fBshard.yml\fP(5) مراجعه کنید.
.RE
.sp
shard.override.yml
.RS 4
امکان بازنویسی منبع و محدودیت وابستگی‌ها را فراهم می‌کند. یک مکان جایگزین را می‌توان با متغیر محیطی \fBSHARDS_OVERRIDE\fP پیکربندی کرد.
.sp
این فایل حاوی یک سند YAML با یک کلید واحدِ \fBdependencies\fP است. معنای آن همانند آنچه در \fBshard.yml\fP آمده می‌باشد. پیکربندی وابستگی در این فایل بر پیکربندی موجود در \fBshard.yml\fP یا هر \fBshard.yml\fP متعلق به وابستگی‌ها اولویت دارد.
.sp
موارد کاربرد آن شامل رونوشت‌های کاری محلی، تحمیل یک نگارش خاص از وابستگی علی‌رغم محدودیت‌های ناسازگار، اصلاح یک وابستگی، و بررسی سازگاری با نگارش‌های منتشرنشدهٔ وابستگی‌ها است.
.RE
.sp
shard.lock
.RS 4
فایل قفلی که اطلاعات مربوط به نگارش‌های نصب‌شده را ذخیره می‌کند.
.sp
اگر شارد شما یک برنامه کاربردی می‌سازد، \fBshard.lock\fP باید در کنترل نسخه ثبت شود تا نصب تکرارپذیر وابستگی‌ها تضمین گردد.
.sp
اگر صرفاً کتابخانه‌ای برای وابستگی دیگر شاردها است، \fBshard.lock\fP \fIنباید\fP ثبت شود و تنها \fBshard.yml\fP ثبت گردد. توصیه می‌شود که آن را به \fB.gitignore\fP اضافه کنید.
.RE
.SH "گزارش باگ‌ها (BUGS)"
.sp
گزارش باگ‌های shards به \c
.URL "https://github.com/crystal\-lang/shards/issues" "" ""
.sp
صفحهٔ اصلی زبان Crystal: \c
.URL "https://crystal\-lang.org" "" ""
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
.sp
حق نشر © 2025 Julien Portalier.
.sp
.URL "http://www.apache.org/licenses/LICENSE\-2.0" "مجوز Apache 2.0" ""
.sp
این نرم‌افزار آزاد است: شما در تغییر و بازتوزیع آن آزاد هستید.
هیچ ضمانتی وجود ندارد، تا حدی که قانون اجازه می‌دهد.
.SH "نویسندگان (AUTHORS)"
.sp
نوشته شده توسط Julien Portalier و پروژهٔ Crystal.
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBshard.yml\fP(5)