'\" t
.\"     Title: shard.yml
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.23
.\"      Date: 2025-01-23
.\"    Manual: File Formats
.\"    Source: shards 0.19.1
.\"  Language: Persian
.\"
.TH "SHARD.YML" "5" "2025-01-23" "shards 0.19.1" "File Formats"
.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)"
shard.yml \- متاداده‌های پروژه‌های مدیریت‌شده توسط shards(1)
.SH "توضیحات (DESCRIPTION)"
.sp
فایل \fIshard.yml\fP یک فایل YAML حاوی متاداده‌های مربوط به پروژه‌ای است که توسط shards مدیریت می‌شود و به عنوان یک \fBshard\fP شناخته می‌شود. این فایل باید حداقل شامل ویژگی‌های \fIname\fP و \fIversion\fP به همراه ویژگی‌های اختیاری دیگر باشد.
.sp
هم کتابخانه‌ها و هم برنامه‌های کاربردی از \f(CRshard.yml\fP بهره‌مند می‌شوند.
.sp
انتظار می‌رود متاداده‌های کتابخانه‌ها اطلاعات بیشتری (مانند فهرست نویسندگان، توضیحات، مجوز) در مقایسه با برنامه‌های کاربردی داشته باشند که ممکن است تنها نام، نسخه و وابستگی‌ها را شامل شوند.
.SH "قالب (FORMAT)"
.sp
نام فایل باید \fIshard.yml\fP باشد و یک فایل معتبر YAML با کدگذاری UTF\-8 باشد.
این فایل نباید شامل ویژگی‌های تکراری در هیچ نگاشتی (mapping) باشد.
باید از تورفتگی ۲ فاصله (space) استفاده کند.
نباید از ویژگی‌های پیشرفته YAML استفاده کند، بلکه تنها نگاشت‌های ساده، توالی‌ها (sequences) و رشته‌ها مجاز هستند (طرحواره Failsafe).
.SH "ویژگی‌های الزامی (REQUIRED ATTRIBUTES)"
.sp
\fBname\fP
.RS 4
نام پروژه (رشته، الزامی).
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
باید یکتا باشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
باید ۵۰ کاراکتر یا کمتر باشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
باید با حروف کوچک (a\-z) باشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
نباید شامل \fIcrystal\fP باشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
می‌تواند شامل ارقام (0\-9) باشد اما نباید با رقم آغاز شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
می‌تواند شامل زیرخط (underscore) یا خط تیره (dash) باشد اما نباید با آن‌ها شروع شده یا پایان یابد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
نباید دارای زیرخط‌ها یا خط تیره‌های متوالی باشد.
.RE
.sp
مثال‌ها: \fIminitest\fP، \fImysql2\fP، \fIbattery\-horse\fP.
.RE
.sp
\fBversion\fP
.RS 4
شماره نسخه پروژه (رشته، الزامی).
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
باید شامل ارقام باشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
می‌تواند شامل نقطه و خط تیره باشد اما نباید به صورت متوالی بیایند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
می‌تواند شامل یک حرف برای مشخص کردن \*(Aqپیش‌انتشار (prerelease)\*(Aq باشد.
.RE
.sp
مثال‌ها: \fI1.2.3\fP، \fI2.0.0.1\fP، \fI1.0.0.alpha\fP، \fI2.0.0\-rc1\fP یا \fI2016.09\fP.
.sp
اگرچه Shards آن را اجبار نمی‌کند، پیروی از یک طرح نسخه‌بندی منطقی مانند
.URL "http://semver.org" "نسخه‌بندی معنایی (Semantic Versioning)" ""
یا
.URL "http://calver.org" "نسخه‌بندی تقویمی (Calendar Versioning)"
اکیداً توصیه می‌شود.
.RE
.SH "ویژگی‌های اختیاری (OPTIONAL ATTRIBUTES)"
.sp
\fBauthors\fP
.RS 4
فهرستی از نویسندگان، به همراه رایانامه تماس آن‌ها (اختیاری) (توالی رشته‌ها).
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
هر نویسنده باید یک نام داشته باشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
هر نویسنده می‌تواند یک آدرس رایانامه در میان نویسه‌های علامت زاویه‌دار (\fI<\fP و \fI>\fP) داشته باشد.
.RE
.sp
\fBمثال:\fP
.sp
.if n .RS 4
.nf
.fam C
authors:
\- Ary
\- Julien Portalier <julien@example.org>
.fam
.fi
.if n .RE
.RE
.sp
\fBcrystal\fP
.RS 4
محدودیتی برای مشخص کردن نسخه‌های پشتیبانی‌شده کریستال (crystal). این مقدار معمولاً محدودیت‌های کران پایین و کران بالا را بیان می‌کند (رشته، توصیه‌شده).
.sp
هنگام حل وابستگی‌ها، از این اطلاعات استفاده نمی‌شود. پس از تعیین وابستگی‌ها، shards بررسی می‌کند که آیا انتظار می‌رود همه آن‌ها با نسخه جاری کریستال کار کنند یا خیر. در غیر این صورت، هشداری برای وابستگی‌های ناسازگار نمایش داده می‌شود. نسخه‌های حل‌شده نصب می‌شوند و استفاده از آن‌ها با مسئولیت خودتان خواهد بود.
.sp
مقادیر معتبر تا حد زیادی مشابه مقادیر \fIdependencies.version\fP هستند:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
شماره نسخه دارای یک عملگر پیشوندی: \fI<\fP، \fI<=\fP، \fI>\fP، \fI>=\fP، \fI!=\fP یا \fI~>\fP.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
صرفاً علامت \fI"*"\fP اگر هر نسخه‌ای قابل قبول باشد (در صورت عدم تعیین، این حالت پیش‌فرض است).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
نیازمندی‌های چندگانه را می‌توان با کاما از هم جدا کرد.
.RE
.sp
یک رفتار قدیمی و خاص وجود دارد (که استفاده از آن توصیه نمی‌شود) زمانی که تنها یک شماره نسخه به عنوان مقدار استفاده می‌شود: دقیقاً مانند بررسی \f(CR>=\fP کار می‌کند؛ یعنی \fIx.y.z\fP به صورت \fI">= x.y.z"\fP تفسیر می‌شود.
.sp
همچنین می‌توانید کران بالا را کمتر از نسخه اصلی (major) بعدی (آینده) کریستال تعیین کنید، زیرا هیچ تضمینی وجود ندارد که کتابخانه شما را دچار شکست یا ناسازگاری نکند.
.sp
\fBمثال:\fP
.sp
.if n .RS 4
.nf
.fam C
crystal: ">= 0.35, < 2.0"
.fam
.fi
.if n .RE
.RE
.sp
\fBdependencies\fP
.RS 4
فهرستی از وابستگی‌های مورد نیاز (نگاشت).
.sp
هر وابستگی با نام وابستگی به عنوان کلید (رشته) آغاز می‌شود و سپس فهرستی از ویژگی‌ها (نگاشت) می‌آید که به نوع حل‌کننده (resolver) بستگی دارد.
.sp
\fBمثال:\fP
.sp
.if n .RS 4
.nf
.fam C
dependencies:
  minitest:
    github: ysbaddaden/minitest.cr
    version: 0.1.0
.fam
.fi
.if n .RE
.RE
.sp
\fBdevelopment_dependencies\fP
.RS 4
فهرستی از وابستگی‌های مورد نیاز برای کار روی توسعه پروژه، اما غیرضروری برای ساخت و اجرای پروژه (نگاشت).
.sp
آن‌ها برای خود پروژه اصلی یا کتابخانه نصب خواهند شد. هنگامی که کتابخانه به عنوان وابستگی برای پروژه دیگری نصب می‌شود، وابستگی‌های توسعه هرگز نصب نخواهند شد.
.sp
وابستگی‌های توسعه از همان ساختار و الگوی وابستگی‌ها پیروی می‌کنند.
.sp
\fBمثال:\fP
.sp
.if n .RS 4
.nf
.fam C
development_dependencies:
  minitest:
    github: ysbaddaden/minitest.cr
    version: ~> 0.1.3
.fam
.fi
.if n .RE
.RE
.sp
\fBdescription\fP
.RS 4
یک خط توضیح کوتاه درباره پروژه (رشته، توصیه‌شده).
.RE
.sp
\fBdocumentation\fP
.RS 4
نشانی اینترنتی (URL) به وب‌سایتی که مستندات پروژه را برای مرور آنلاین فراهم می‌کند (رشته).
.RE
.sp
\fBexecutables\fP
.RS 4
فهرستی از فایل‌های اجرایی که باید نصب شوند (توالی).
.sp
فایل‌های اجرایی می‌توانند از هر نوع یا زبانی باشند (مانند شل، باینری، روبی)، باید در پوشه \fIbin\fP مربوط به Shard وجود داشته باشند، و بیت اجرایی آن‌ها تنظیم شده باشد (در پلتفرم‌های POSIX). هنگامی که به عنوان وابستگی برای پروژه دیگری نصب می‌شوند، فایل‌های اجرایی در پوشه \fIbin\fP آن پروژه کپی خواهند شد.
.sp
فایل‌های اجرایی همیشه در آخرین مرحله و پس از اجرای اسکریپت \fIpostinstall\fP نصب می‌شوند، بنابراین کتابخانه‌ها می‌توانند هنگام نصب توسط Shards، فایل‌های اجرایی را بسازند. نصب فایل‌های اجرایی را می‌توان با ارسال فلگ \fI\-\-skip\-executables\fP غیرفعال کرد.
.sp
\fBمثال:\fP
.sp
.if n .RS 4
.nf
.fam C
executables:
\- micrate
\- icr
.fam
.fi
.if n .RE
.RE
.sp
\fBhomepage\fP
.RS 4
نشانی وب (URL) صفحه اصلی پروژه (رشته).
.RE
.sp
\fBlibraries\fP
.RS 4
فهرستی از کتابخانه‌های اشتراکی که shard سعی می‌کند به آن‌ها پیوند (link) بخورد (نگاشت).
.sp
این فیلد صرفاً جنبه اطلاع‌رسانی دارد و به عنوان روشی استاندارد برای شناسایی وابستگی‌های غیرکریستالی در shardها، چه برای ابزارها و چه برای انسان‌ها به کار می‌رود.
.sp
یک shard فقط باید کتابخانه‌هایی را فهرست کند که مستقیماً به آن‌ها پیوند می‌خورد، و نباید شامل کتابخانه‌هایی باشد که صرفاً توسط وابستگی‌ها ارجاع داده شده‌اند. باید همه کتابخانه‌هایی را که مستقیماً به آن‌ها پیوند می‌خورد شامل شود، صرف‌نظر از اینکه یکی از وابستگی‌ها نیز به آن پیوند خورده باشد یا خیر.
.sp
این نگاشت باید از نام soname بدون هیچ پسوند، مسیر یا نسخه‌ای (برای مثال \fIlibsqlite3\fP برای \fI/usr/lib/libsqlite3.so.0.8.6\fP) به یک محدودیت نسخه باشد.
.sp
محدودیت نسخه ساختار زیر را دارد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
می‌تواند یک شماره نسخه باشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
می‌تواند \fI"*"\fP باشد اگر هر نسخه‌ای قابل قبول باشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
شماره نسخه می‌تواند دارای یک عملگر پیشوندی باشد: \fI<\fP، \fI<=\fP، \fI>\fP، \fI>=\fP، \fI!=\fP یا \fI~>\fP.
.RE
.sp
.if n .RS 4
.nf
.fam C
libraries:
  libQt5Gui: "*"
  libQt5Help: "~> 5.7"
  libQtBus: ">= 4.8"
.fam
.fi
.if n .RE
.RE
.sp
\fBlicense\fP
.RS 4
یک \c
.URL "https://spdx.github.io/spdx\-spec/v3.0.1/annexes/spdx\-license\-expressions" "عبارت مجوز SPDX"
یا نشانی وب (URL) به فایل مجوز (رشته، توصیه‌شده).
.sp
سازمان ابتکار منبع‌باز (OSI) \c
.URL "https://opensource.org/licenses\-old/category" "فهرستی" ""
از مجوزهای متن‌باز و شناسه‌های SPDX متناظر آن‌ها را منتشر کرده است.
.sp
مثال‌ها: \fIApache\-2.0\fP، \fIGPL\-3.0\-or\-later\fP، \fIApache\-2.0 OR MIT\fP،
\fIApache\-2.0 WITH Swift\-exception\fP، \fI\c
.URL "https://example.com/LICENSE" "" "\fP."
.RE
.sp
\fBrepository\fP
.RS 4
نشانی وب (URL) مخزن مرجع پروژه (رشته، توصیه‌شده).
.sp
نشانی URL باید بدون نیاز به تغییر با ابزارهای متداول سامانه کنترل نسخه (VCS) سازگار باشد.
پروتکل‌های \fIhttp\fP/\fIhttps\fP نسبت به طرح‌های اختصاصی VCS مانند \fIgit\fP ارجحیت دارند.
توصیه می‌شود که این نشانی اینترنتی به صورت عمومی در دسترس باشد.
.sp
نسخه‌های کپی از یک shard (مانند آینه‌ها، شاخه‌های توسعه و غیره) باید به همان نشانی مخزن مرجع اشاره کنند، حتی اگر در مکان‌های متفاوتی میزبانی شوند.
.sp
\fBمثال:\fP
.sp
.if n .RS 4
.nf
.fam C
repository: "https://github.com/crystal\-lang/shards"
.fam
.fi
.if n .RE
.RE
.sp
\fBscripts\fP
.RS 4
قلاب‌های اسکریپت (script hooks) برای اجرا. در حال حاضر فقط \fIpostinstall\fP پشتیبانی می‌شود.
.sp
ابزار Shards ممکن است پس از اقدامات خاصی، اسکریپت‌ها را به صورت خودکار اجرا کند. خود اسکریپت‌ها صرفاً دستورات شل هستند.
.sp
\fBpostinstall\fP
.RS 4
قلاب \fIpostinstall\fP مربوط به یک وابستگی، هر زمان که آن وابستگی در پروژه‌ای که به آن نیاز دارد نصب یا ارتقا یابد، اجرا خواهد شد. این قلاب می‌تواند برای کامپایل کردن یک کتابخانه C، ساخت ابزارهایی برای کمک به توسعه پروژه، یا هر کار دیگری به کار رود.
.sp
اسکریپت از داخل دایرکتوری نصب وابستگی اجرا خواهد شد، به عنوان مثال \fIlib/foo\fP برای یک Shard به نام \fIfoo\fP.
.sp
\fBمثال:\fP
.sp
.if n .RS 4
.nf
.fam C
scripts:
  postinstall: cd src/libfoo && make
.fam
.fi
.if n .RE
.RE
.RE
.sp
\fBtargets\fP
.RS 4
فهرستی از هدف‌های قابل ساخت (targets) برای کامپایل (نگاشت).
.sp
هر هدف با نام هدف به عنوان کلید (رشته) آغاز می‌شود و به دنبال آن فهرستی از ویژگی‌ها (نگاشت) می‌آید. نام هدف، همان نام فایل باینری ساخته‌شده است که در پوشه \fIbin\fP پروژه ایجاد می‌شود.
.sp
\fBمثال:\fP
.sp
.if n .RS 4
.nf
.fam C
targets:
  server:
    main: src/server/cli.cr
  worker:
    main: src/worker.cr
.fam
.fi
.if n .RE
.sp
مثال بالا \fIbin/server\fP را از \fIsrc/server/cli.cr\fP و \fIbin/worker\fP را از \fIsrc/worker.cr\fP خواهد ساخت.
.sp
\fBmain\fP
.RS 4
مسیری به فایل منبع برای کامپایل (رشته).
.RE
.RE
.SH "ویژگی‌های وابستگی (DEPENDENCY ATTRIBUTES)"
.sp
هر وابستگی حداقل به یک ویژگی نیاز دارد که حل‌کننده (resolver) آن وابستگی را مشخص کند. این ویژگی‌ها می‌توانند \fIpath\fP، \fIgit\fP، \fIgithub\fP، \fIgitlab\fP، \fIbitbucket\fP یا \fIcodeberg\fP باشند.
.sp
\fBpath\fP
.RS 4
یک مسیر محلی (رشته).
.sp
کتابخانه به صورت یک پیوند نمادین (symlink) به مسیر محلی نصب خواهد شد.
ویژگی \fIversion\fP الزامی نیست، اما در صورت وجود برای اعتبارسنجی وابستگی به کار خواهد رفت.
.RE
.sp
\fBgit\fP
.RS 4
نشانی اینترنتی (URL) مخزن گیت (رشته).
.sp
نشانی می‌تواند \c
.URL "https://git\-scm.com/docs/git\-clone#_git_urls" "هر پروتکلی"
باشد که توسط گیت پشتیبانی می‌شود، از جمله SSH، GIT و HTTPS.
.sp
مخزن گیت کلون خواهد شد و فهرست نسخه‌ها (و فایل \fIshard.yml\fP مربوطه) از تگ‌های گیت (مانند \fIv1.2.3\fP) استخراج می‌شود.
.sp
یکی از ویژگی‌های دیگر (\fIversion\fP، \fItag\fP، \fIbranch\fP یا \fIcommit\fP) الزامی است. در صورت عدم وجود، Shards ارجاع HEAD را نصب خواهد کرد.
.sp
\fBمثال:\fP \fIgit: git://git.example.org/crystal\-library.git\fP
.RE
.sp
\fBgithub\fP
.RS 4
نشانی مخزن گیت‌هاب به صورت \fIuser/repo\fP (رشته).
.sp
حل‌کننده \fIgit\fP را گسترش می‌دهد و دقیقاً مانند آن عمل می‌کند.
.sp
\fBمثال:\fP \fIgithub: ysbaddaden/minitest.cr\fP
.RE
.sp
\fBgitlab\fP
.RS 4
نشانی مخزن گیت‌لب به صورت \fIuser/repo\fP (رشته).
.sp
حل‌کننده \fIgit\fP را گسترش می‌دهد و دقیقاً مانند آن عمل می‌کند.
.sp
تنها با وابستگی‌های میزبانی‌شده روی \fIgitlab.com\fP تطابق دارد. برای نمونه‌های نصب‌شده شخصی گیت‌لب، باید از حل‌کننده عمومی \fIgit\fP استفاده کنید.
.sp
\fBمثال:\fP \fIgitlab: thelonlyghost/minitest.cr\fP
.RE
.sp
\fBbitbucket\fP
.RS 4
نشانی مخزن بیت‌باکت به صورت \fIuser/repo\fP (رشته).
.sp
حل‌کننده \fIgit\fP را گسترش می‌دهد و دقیقاً مانند آن عمل می‌کند.
.sp
\fBمثال:\fP \fIbitbucket: tom/library\fP
.RE
.sp
\fBcodeberg\fP
.RS 4
نشانی مخزن کدبرگ به صورت \fIuser/repo\fP (رشته).
.sp
حل‌کننده \fIgit\fP را گسترش می‌دهد و دقیقاً مانند آن عمل می‌کند.
.sp
\fBمثال:\fP \fIcodeberg: tom/library\fP
.RE
.sp
\fBhg\fP
.RS 4
نشانی اینترنتی (URL) مخزن مرکوریال (رشته).
.sp
نشانی می‌تواند \c
.URL "https://www.mercurial\-scm.org/repo/hg/help/clone" "هر پروتکلی"
باشد که توسط مرکوریال پشتیبانی می‌شود، از جمله SSH و HTTPS.
.sp
مخزن مرکوریال کلون خواهد شد و فهرست نسخه‌ها (و فایل \fIshard.yml\fP مربوطه) از تگ‌های مرکوریال (مانند \fIv1.2.3\fP) استخراج می‌شود.
.sp
یکی از ویژگی‌های دیگر (\fIversion\fP، \fItag\fP، \fIbranch\fP، \fIbookmark\fP یا \fIcommit\fP) الزامی است. در صورت عدم وجود، Shards نشانک \fI@\fP یا \fItip\fP را نصب خواهد کرد.
.sp
\fBمثال:\fP \fIhg: \c
.URL "https://hg.example.org/crystal\-library" "" "\fP"
.RE
.sp
\fBfossil\fP
.RS 4
یک نشانی مخزن \c
.URL "https://www.fossil\-scm.org" "Fossil" ""
(رشته).
.sp
نشانی می‌تواند \c
.URL "https://fossil\-scm.org/home/help/clone" "هر پروتکلی"
باشد که توسط Fossil پشتیبانی می‌شود، از جمله SSH و HTTPS.
.sp
مخزن Fossil کلون خواهد شد و فهرست نسخه‌ها (و فایل \fIshard.yml\fP مربوطه) از تگ‌های Fossil (مانند \fIv1.2.3\fP) استخراج می‌شود.
.sp
یکی از ویژگی‌های دیگر (\fIversion\fP، \fItag\fP، \fIbranch\fP یا \fIcommit\fP) الزامی است. در صورت عدم وجود، Shards شاخه \fItrunk\fP را نصب خواهد کرد.
.sp
\fBمثال:\fP \fIfossil: \c
.URL "https://fossil.example.org/crystal\-library" "" "\fP"
.RE
.sp
\fBversion\fP
.RS 4
یک نیازمندی نسخه (رشته).
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
می‌تواند یک شماره نسخه صریح باشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
می‌تواند نویسه عام \fI"*"\fP باشد اگر هر نسخه‌ای قابل قبول باشد (این حالت پیش‌فرض است). در این حالت، Shards آخرین نسخه دارای تگ (یا HEAD اگر هیچ نسخه تگ‌خورده‌ای موجود نباشد) را نصب خواهد کرد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
شماره نسخه می‌تواند دارای یک عملگر پیشوندی باشد: \fI<\fP، \fI<=\fP، \fI>\fP، \fI>=\fP، \fI!=\fP یا \fI~>\fP.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
نیازمندی‌های چندگانه را می‌توان با کاما از هم جدا کرد.
.RE
.sp
مثال‌ها: \fI1.2.3\fP، \fI>= 1.0.0\fP، \fI>= 1.0.0, < 2.0\fP یا \fI~> 2.0\fP.
.sp
بیشتر عملگرهای نسخه مانند \fI>= 1.0.0\fP خودتوضیح‌دهنده هستند، اما عملگر \fI~>\fP مفهوم ویژه‌ای دارد.
این عملگر حداقل نسخه را مشخص می‌کند، اما به آخرین رقم مشخص‌شده اجازه افزایش می‌دهد، به استثنای شماره نسخه اصلی (major):
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fI~> 0.3.5\fP دقیقاً برابر با \fI>= 0.3.5 and < 0.4.0\fP است.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fI~> 2.0.3\fP دقیقاً برابر با \fI>= 2.0.3 and < 2.1\fP است.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fI~> 2.1\fP دقیقاً برابر با \fI>= 2.1 and < 3.0\fP است.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fI~> 0.3\fP دقیقاً برابر با \fI>= 0.3 and < 1.0\fP است.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fI~> 1\fP دقیقاً برابر با \fI>= 1.0 and < 2.0\fP است.
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B "نکته (Note)"
.ps -1
.br
.sp
اگرچه \fI2.1.0\-dev\fP دقیقاً پیش از \fI2.1.0\fP قرار دارد، اما محدودیت نسخه‌ای مانند \fI~> 2.0.3\fP آن را نصب نخواهد کرد زیرا فقط بخش \fI.3\fP می‌تواند تغییر کند ولی بخش \fI2.0\fP ثابت است.
.sp .5v
.RE
.sp
\fBbranch\fP
.RS 4
شاخه مشخص‌شده از یک وابستگی گیت، یا شاخه نام‌گذاری‌شده از یک وابستگی مرکوریال یا Fossil را نصب می‌کند (رشته).
.RE
.sp
\fBcommit\fP
.RS 4
کامیت مشخص‌شده از یک وابستگی گیت، مرکوریال یا Fossil را نصب می‌کند (رشته).
.RE
.sp
\fBtag\fP
.RS 4
تگ مشخص‌شده از یک وابستگی گیت، مرکوریال یا Fossil را نصب می‌کند (رشته).
.RE
.sp
\fBbookmark\fP
.RS 4
نشانک (bookmark) مشخص‌شده از یک وابستگی مرکوریال را نصب می‌کند (رشته).
.RE
.SH "مثال‌ها (EXAMPLES)"
.sp
در اینجا نمونه‌ای از فایل \fIshard.yml\fP برای کتابخانه‌ای به نام \fIshards\fP در نسخه \fI1.2.3\fP به همراه چند وابستگی آورده شده است:
.sp
.if n .RS 4
.nf
.fam C
name: shards
version: 1.2.3
crystal: \*(Aq>= 0.35.0\*(Aq

authors:
\- Julien Portalier <julien@example.com>
license: MIT

description: |
  Dependency manager for the Crystal Language

dependencies:
  openssl:
    github: datanoise/openssl.cr
    branch: master

development_dependencies:
  minitest:
    git: https://github.com/ysbaddaden/minitest.cr.git
    version: "~> 0.1.0"

libraries:
  libgit2: ~> 0.24

scripts:
  postinstall: make ext

targets:
  shards:
    main: src/shards.cr
.fam
.fi
.if n .RE
.SH "نویسنده (AUTHOR)"
.sp
نوشته‌شده توسط Julien Portalier و پروژه کریستال.
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBshards\fP(1)