SHARD.YML(5)                     File Formats                     SHARD.YML(5)

نام (NAME)
       shard.yml - متاداده‌های پروژه‌های مدیریت‌شده توسط shards(1)

توضیحات (DESCRIPTION)
       فایل shard.yml یک فایل YAML حاوی متاداده‌های مربوط به پروژه‌ای است که
       توسط shards مدیریت می‌شود و به عنوان یک shard شناخته می‌شود. این فایل
       باید حداقل شامل ویژگی‌های name و version به همراه ویژگی‌های اختیاری دیگر
       باشد.

       هم کتابخانه‌ها و هم برنامه‌های کاربردی از shard.yml بهره‌مند می‌شوند.

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

قالب (FORMAT)
       نام فایل باید shard.yml باشد و یک فایل معتبر YAML با کدگذاری UTF-8
       باشد.  این فایل نباید شامل ویژگی‌های تکراری در هیچ نگاشتی (mapping)
       باشد.  باید از تورفتگی ۲ فاصله (space) استفاده کند.  نباید از ویژگی‌های
       پیشرفته YAML استفاده کند، بلکه تنها نگاشت‌های ساده، توالی‌ها (sequences)
       و رشته‌ها مجاز هستند (طرحواره Failsafe).

ویژگی‌های الزامی (REQUIRED ATTRIBUTES)
       name
           نام پروژه (رشته، الزامی).

           •   باید یکتا باشد.

           •   باید ۵۰ کاراکتر یا کمتر باشد.

           •   باید با حروف کوچک (a-z) باشد.

           •   نباید شامل crystal باشد.

           •   می‌تواند شامل ارقام (0-9) باشد اما نباید با رقم آغاز شود.

           •   می‌تواند شامل زیرخط (underscore) یا خط تیره (dash) باشد اما
               نباید با آن‌ها شروع شده یا پایان یابد.

           •   نباید دارای زیرخط‌ها یا خط تیره‌های متوالی باشد.

           مثال‌ها: minitest، mysql2، battery-horse.

       version
           شماره نسخه پروژه (رشته، الزامی).

           •   باید شامل ارقام باشد.

           •   می‌تواند شامل نقطه و خط تیره باشد اما نباید به صورت متوالی
               بیایند.

           •   می‌تواند شامل یک حرف برای مشخص کردن 'پیش‌انتشار (prerelease)'
               باشد.

           مثال‌ها: 1.2.3، 2.0.0.1، 1.0.0.alpha، 2.0.0-rc1 یا 2016.09.

           اگرچه Shards آن را اجبار نمی‌کند، پیروی از یک طرح نسخه‌بندی منطقی
           مانند نسخه‌بندی معنایی (Semantic Versioning) <http://semver.org> یا
           نسخه‌بندی تقویمی (Calendar Versioning) <http://calver.org> اکیداً
           توصیه می‌شود.

ویژگی‌های اختیاری (OPTIONAL ATTRIBUTES)
       authors
           فهرستی از نویسندگان، به همراه رایانامه تماس آن‌ها (اختیاری) (توالی
           رشته‌ها).

           •   هر نویسنده باید یک نام داشته باشد.

           •   هر نویسنده می‌تواند یک آدرس رایانامه در میان نویسه‌های علامت
               زاویه‌دار (< و >) داشته باشد.

           مثال:

               authors:
               - Ary
               - Julien Portalier <julien@example.org>

       crystal
           محدودیتی برای مشخص کردن نسخه‌های پشتیبانی‌شده کریستال (crystal). این
           مقدار معمولاً محدودیت‌های کران پایین و کران بالا را بیان می‌کند (رشته،
           توصیه‌شده).

           هنگام حل وابستگی‌ها، از این اطلاعات استفاده نمی‌شود. پس از تعیین
           وابستگی‌ها، shards بررسی می‌کند که آیا انتظار می‌رود همه آن‌ها با نسخه
           جاری کریستال کار کنند یا خیر. در غیر این صورت، هشداری برای
           وابستگی‌های ناسازگار نمایش داده می‌شود. نسخه‌های حل‌شده نصب می‌شوند و
           استفاده از آن‌ها با مسئولیت خودتان خواهد بود.

           مقادیر معتبر تا حد زیادی مشابه مقادیر dependencies.version هستند:

           •   شماره نسخه دارای یک عملگر پیشوندی: <، <=، >، >=، != یا ~>.

           •   صرفاً علامت "*" اگر هر نسخه‌ای قابل قبول باشد (در صورت عدم تعیین،
               این حالت پیش‌فرض است).

           •   نیازمندی‌های چندگانه را می‌توان با کاما از هم جدا کرد.

           یک رفتار قدیمی و خاص وجود دارد (که استفاده از آن توصیه نمی‌شود)
           زمانی که تنها یک شماره نسخه به عنوان مقدار استفاده می‌شود: دقیقاً
           مانند بررسی >= کار می‌کند؛ یعنی x.y.z به صورت ">= x.y.z" تفسیر
           می‌شود.

           همچنین می‌توانید کران بالا را کمتر از نسخه اصلی (major) بعدی (آینده)
           کریستال تعیین کنید، زیرا هیچ تضمینی وجود ندارد که کتابخانه شما را
           دچار شکست یا ناسازگاری نکند.

           مثال:

               crystal: ">= 0.35, < 2.0"

       dependencies
           فهرستی از وابستگی‌های مورد نیاز (نگاشت).

           هر وابستگی با نام وابستگی به عنوان کلید (رشته) آغاز می‌شود و سپس
           فهرستی از ویژگی‌ها (نگاشت) می‌آید که به نوع حل‌کننده (resolver) بستگی
           دارد.

           مثال:

               dependencies:
                 minitest:
                   github: ysbaddaden/minitest.cr
                   version: 0.1.0

       development_dependencies
           فهرستی از وابستگی‌های مورد نیاز برای کار روی توسعه پروژه، اما
           غیرضروری برای ساخت و اجرای پروژه (نگاشت).

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

           وابستگی‌های توسعه از همان ساختار و الگوی وابستگی‌ها پیروی می‌کنند.

           مثال:

               development_dependencies:
                 minitest:
                   github: ysbaddaden/minitest.cr
                   version: ~> 0.1.3

       description
           یک خط توضیح کوتاه درباره پروژه (رشته، توصیه‌شده).

       documentation
           نشانی اینترنتی (URL) به وب‌سایتی که مستندات پروژه را برای مرور
           آنلاین فراهم می‌کند (رشته).

       executables
           فهرستی از فایل‌های اجرایی که باید نصب شوند (توالی).

           فایل‌های اجرایی می‌توانند از هر نوع یا زبانی باشند (مانند شل، باینری،
           روبی)، باید در پوشه bin مربوط به Shard وجود داشته باشند، و بیت
           اجرایی آن‌ها تنظیم شده باشد (در پلتفرم‌های POSIX). هنگامی که به عنوان
           وابستگی برای پروژه دیگری نصب می‌شوند، فایل‌های اجرایی در پوشه bin آن
           پروژه کپی خواهند شد.

           فایل‌های اجرایی همیشه در آخرین مرحله و پس از اجرای اسکریپت
           postinstall نصب می‌شوند، بنابراین کتابخانه‌ها می‌توانند هنگام نصب توسط
           Shards، فایل‌های اجرایی را بسازند. نصب فایل‌های اجرایی را می‌توان با
           ارسال فلگ --skip-executables غیرفعال کرد.

           مثال:

               executables:
               - micrate
               - icr

       homepage
           نشانی وب (URL) صفحه اصلی پروژه (رشته).

       libraries
           فهرستی از کتابخانه‌های اشتراکی که shard سعی می‌کند به آن‌ها پیوند
           (link) بخورد (نگاشت).

           این فیلد صرفاً جنبه اطلاع‌رسانی دارد و به عنوان روشی استاندارد برای
           شناسایی وابستگی‌های غیرکریستالی در shardها، چه برای ابزارها و چه
           برای انسان‌ها به کار می‌رود.

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

           این نگاشت باید از نام soname بدون هیچ پسوند، مسیر یا نسخه‌ای (برای
           مثال libsqlite3 برای /usr/lib/libsqlite3.so.0.8.6) به یک محدودیت
           نسخه باشد.

           محدودیت نسخه ساختار زیر را دارد:

           •   می‌تواند یک شماره نسخه باشد.

           •   می‌تواند "*" باشد اگر هر نسخه‌ای قابل قبول باشد.

           •   شماره نسخه می‌تواند دارای یک عملگر پیشوندی باشد: <، <=، >، >=،
               != یا ~>.

               libraries:
                 libQt5Gui: "*"
                 libQt5Help: "~> 5.7"
                 libQtBus: ">= 4.8"

       license
           یک عبارت مجوز SPDX
           <https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions>
           یا نشانی وب (URL) به فایل مجوز (رشته، توصیه‌شده).

           سازمان ابتکار منبع‌باز (OSI) فهرستی
           <https://opensource.org/licenses-old/category> از مجوزهای متن‌باز و
           شناسه‌های SPDX متناظر آن‌ها را منتشر کرده است.

           مثال‌ها: Apache-2.0، GPL-3.0-or-later، Apache-2.0 OR MIT، Apache-2.0
           WITH Swift-exception،  <https://example.com/LICENSE>.

       repository
           نشانی وب (URL) مخزن مرجع پروژه (رشته، توصیه‌شده).

           نشانی URL باید بدون نیاز به تغییر با ابزارهای متداول سامانه کنترل
           نسخه (VCS) سازگار باشد.  پروتکل‌های http/https نسبت به طرح‌های
           اختصاصی VCS مانند git ارجحیت دارند.  توصیه می‌شود که این نشانی
           اینترنتی به صورت عمومی در دسترس باشد.

           نسخه‌های کپی از یک shard (مانند آینه‌ها، شاخه‌های توسعه و غیره) باید
           به همان نشانی مخزن مرجع اشاره کنند، حتی اگر در مکان‌های متفاوتی
           میزبانی شوند.

           مثال:

               repository: "https://github.com/crystal-lang/shards"

       scripts
           قلاب‌های اسکریپت (script hooks) برای اجرا. در حال حاضر فقط
           postinstall پشتیبانی می‌شود.

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

           postinstall
               قلاب postinstall مربوط به یک وابستگی، هر زمان که آن وابستگی در
               پروژه‌ای که به آن نیاز دارد نصب یا ارتقا یابد، اجرا خواهد شد.
               این قلاب می‌تواند برای کامپایل کردن یک کتابخانه C، ساخت
               ابزارهایی برای کمک به توسعه پروژه، یا هر کار دیگری به کار رود.

               اسکریپت از داخل دایرکتوری نصب وابستگی اجرا خواهد شد، به عنوان
               مثال lib/foo برای یک Shard به نام foo.

               مثال:

                   scripts:
                     postinstall: cd src/libfoo && make

       targets
           فهرستی از هدف‌های قابل ساخت (targets) برای کامپایل (نگاشت).

           هر هدف با نام هدف به عنوان کلید (رشته) آغاز می‌شود و به دنبال آن
           فهرستی از ویژگی‌ها (نگاشت) می‌آید. نام هدف، همان نام فایل باینری
           ساخته‌شده است که در پوشه bin پروژه ایجاد می‌شود.

           مثال:

               targets:
                 server:
                   main: src/server/cli.cr
                 worker:
                   main: src/worker.cr

           مثال بالا bin/server را از src/server/cli.cr و bin/worker را از
           src/worker.cr خواهد ساخت.

           main
               مسیری به فایل منبع برای کامپایل (رشته).

ویژگی‌های وابستگی (DEPENDENCY ATTRIBUTES)
       هر وابستگی حداقل به یک ویژگی نیاز دارد که حل‌کننده (resolver) آن وابستگی
       را مشخص کند. این ویژگی‌ها می‌توانند path، git، github، gitlab، bitbucket
       یا codeberg باشند.

       path
           یک مسیر محلی (رشته).

           کتابخانه به صورت یک پیوند نمادین (symlink) به مسیر محلی نصب خواهد
           شد.  ویژگی version الزامی نیست، اما در صورت وجود برای اعتبارسنجی
           وابستگی به کار خواهد رفت.

       git
           نشانی اینترنتی (URL) مخزن گیت (رشته).

           نشانی می‌تواند هر پروتکلی
           <https://git-scm.com/docs/git-clone#_git_urls> باشد که توسط گیت
           پشتیبانی می‌شود، از جمله SSH، GIT و HTTPS.

           مخزن گیت کلون خواهد شد و فهرست نسخه‌ها (و فایل shard.yml مربوطه) از
           تگ‌های گیت (مانند v1.2.3) استخراج می‌شود.

           یکی از ویژگی‌های دیگر (version، tag، branch یا commit) الزامی است.
           در صورت عدم وجود، Shards ارجاع HEAD را نصب خواهد کرد.

           مثال: git: git://git.example.org/crystal-library.git

       github
           نشانی مخزن گیت‌هاب به صورت user/repo (رشته).

           حل‌کننده git را گسترش می‌دهد و دقیقاً مانند آن عمل می‌کند.

           مثال: github: ysbaddaden/minitest.cr

       gitlab
           نشانی مخزن گیت‌لب به صورت user/repo (رشته).

           حل‌کننده git را گسترش می‌دهد و دقیقاً مانند آن عمل می‌کند.

           تنها با وابستگی‌های میزبانی‌شده روی gitlab.com تطابق دارد. برای
           نمونه‌های نصب‌شده شخصی گیت‌لب، باید از حل‌کننده عمومی git استفاده کنید.

           مثال: gitlab: thelonlyghost/minitest.cr

       bitbucket
           نشانی مخزن بیت‌باکت به صورت user/repo (رشته).

           حل‌کننده git را گسترش می‌دهد و دقیقاً مانند آن عمل می‌کند.

           مثال: bitbucket: tom/library

       codeberg
           نشانی مخزن کدبرگ به صورت user/repo (رشته).

           حل‌کننده git را گسترش می‌دهد و دقیقاً مانند آن عمل می‌کند.

           مثال: codeberg: tom/library

       hg
           نشانی اینترنتی (URL) مخزن مرکوریال (رشته).

           نشانی می‌تواند هر پروتکلی
           <https://www.mercurial-scm.org/repo/hg/help/clone> باشد که توسط
           مرکوریال پشتیبانی می‌شود، از جمله SSH و HTTPS.

           مخزن مرکوریال کلون خواهد شد و فهرست نسخه‌ها (و فایل shard.yml
           مربوطه) از تگ‌های مرکوریال (مانند v1.2.3) استخراج می‌شود.

           یکی از ویژگی‌های دیگر (version، tag، branch، bookmark یا commit)
           الزامی است. در صورت عدم وجود، Shards نشانک @ یا tip را نصب خواهد
           کرد.

           مثال: hg:  <https://hg.example.org/crystal-library>

       fossil
           یک نشانی مخزن Fossil <https://www.fossil-scm.org> (رشته).

           نشانی می‌تواند هر پروتکلی <https://fossil-scm.org/home/help/clone>
           باشد که توسط Fossil پشتیبانی می‌شود، از جمله SSH و HTTPS.

           مخزن Fossil کلون خواهد شد و فهرست نسخه‌ها (و فایل shard.yml مربوطه)
           از تگ‌های Fossil (مانند v1.2.3) استخراج می‌شود.

           یکی از ویژگی‌های دیگر (version، tag، branch یا commit) الزامی است.
           در صورت عدم وجود، Shards شاخه trunk را نصب خواهد کرد.

           مثال: fossil:  <https://fossil.example.org/crystal-library>

       version
           یک نیازمندی نسخه (رشته).

           •   می‌تواند یک شماره نسخه صریح باشد.

           •   می‌تواند نویسه عام "*" باشد اگر هر نسخه‌ای قابل قبول باشد (این
               حالت پیش‌فرض است). در این حالت، Shards آخرین نسخه دارای تگ (یا
               HEAD اگر هیچ نسخه تگ‌خورده‌ای موجود نباشد) را نصب خواهد کرد.

           •   شماره نسخه می‌تواند دارای یک عملگر پیشوندی باشد: <، <=، >، >=،
               != یا ~>.

           •   نیازمندی‌های چندگانه را می‌توان با کاما از هم جدا کرد.

           مثال‌ها: 1.2.3، >= 1.0.0، >= 1.0.0, < 2.0 یا ~> 2.0.

           بیشتر عملگرهای نسخه مانند >= 1.0.0 خودتوضیح‌دهنده هستند، اما عملگر
           ~> مفهوم ویژه‌ای دارد.  این عملگر حداقل نسخه را مشخص می‌کند، اما به
           آخرین رقم مشخص‌شده اجازه افزایش می‌دهد، به استثنای شماره نسخه اصلی
           (major):

       •   ~> 0.3.5 دقیقاً برابر با >= 0.3.5 and < 0.4.0 است.

       •   ~> 2.0.3 دقیقاً برابر با >= 2.0.3 and < 2.1 است.

       •   ~> 2.1 دقیقاً برابر با >= 2.1 and < 3.0 است.

       •   ~> 0.3 دقیقاً برابر با >= 0.3 and < 1.0 است.

       •   ~> 1 دقیقاً برابر با >= 1.0 and < 2.0 است.

           نکته (Note)

           اگرچه 2.1.0-dev دقیقاً پیش از 2.1.0 قرار دارد، اما محدودیت نسخه‌ای
           مانند ~> 2.0.3 آن را نصب نخواهد کرد زیرا فقط بخش .3 می‌تواند تغییر
           کند ولی بخش 2.0 ثابت است.

       branch
           شاخه مشخص‌شده از یک وابستگی گیت، یا شاخه نام‌گذاری‌شده از یک وابستگی
           مرکوریال یا Fossil را نصب می‌کند (رشته).

       commit
           کامیت مشخص‌شده از یک وابستگی گیت، مرکوریال یا Fossil را نصب می‌کند
           (رشته).

       tag
           تگ مشخص‌شده از یک وابستگی گیت، مرکوریال یا Fossil را نصب می‌کند
           (رشته).

       bookmark
           نشانک (bookmark) مشخص‌شده از یک وابستگی مرکوریال را نصب می‌کند
           (رشته).

مثال‌ها (EXAMPLES)
       در اینجا نمونه‌ای از فایل shard.yml برای کتابخانه‌ای به نام shards در
       نسخه 1.2.3 به همراه چند وابستگی آورده شده است:

           name: shards
           version: 1.2.3
           crystal: '>= 0.35.0'

           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

نویسنده (AUTHOR)
       نوشته‌شده توسط Julien Portalier و پروژه کریستال.

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

shards 0.19.1                     2025-01-23                      SHARD.YML(5)