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

مثال‌ها: 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 اکیداً توصیه می‌شود.

مثال:

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

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

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

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

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

مثال:

crystal: ">= 0.35, < 2.0"

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

مثال:

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

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

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

مثال:

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

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

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

مثال:

executables:
- micrate
- icr

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

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

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

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

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

سازمان ابتکار منبع‌باز (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.

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

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

مثال:

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

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

postinstall

scripts:
  postinstall: cd src/libfoo && make

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

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

نشانی می‌تواند هر پروتکلی 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

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

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

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

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

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

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

مثال: bitbucket: tom/library

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

مثال: codeberg: tom/library

نشانی می‌تواند هر پروتکلی 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

نشانی می‌تواند هر پروتکلی 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

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

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

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

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