Examples: minitest, mysql2, battery-horse.

Examples: 1.2.3, 2.0.0.1, 1.0.0.alpha 2.0.0-rc1 or 2016.09.

While Shards doesn’t enforce it, following a rational versioning scheme likeSemantic Versioning <http://semver.org/> or Calendar Versioning <http://calver.org/> is highly recommended.

Example:

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

When resolving dependencies, this information is not used. After dependencieshave been determined shards checks all of them are expected to work withthe current crystal version. If not, a warning appears for the offendingdependencies. The resolved versions are installed and can be used at yourown risk.

The valid values are mostly the same as for dependencies.version:

There is a special legacy behavior (its use is discouraged) when just a versionnumber is used as the value: it works exactly the same as a >= check: x.y.z is interpreted as ">= x.y.z"

You are welcome to also specify the upper bound to be lower than the next(future) major Crystal version, because there’s no guarantee that it won’tbreak your library.

Example:

crystal: ">= 0.35, < 2.0"

Each dependency begins with the name of the dependency as a key (string) then alist of attributes (mapping) that depend on the resolver type.

Example:

dependencies:


  minitest:


    github: ysbaddaden/minitest.cr


    version: 0.1.0

They will be installed for the main project or library itself.When the library is installed as a dependency for another project thedevelopment dependencies will never be installed.

Development dependencies follow the same scheme as dependencies.

Example:

development_dependencies:


  minitest:


    github: ysbaddaden/minitest.cr


    version: ~> 0.1.3

The executables can be of any type or language (e.g., shell, binary, ruby), mustexist in the bin folder of the Shard, and have the executable bit set (on POSIX platforms). When installed as a dependency for another project the executables will be copied to the bin folder of that project.

Executables are always installed last, after the postinstall script is run, so libraries can build the executables when they are installed by Shards. Installation can be disabled by passing the flag --skip-executables.

Example:

executables:
- micrate
- icr

This field is purely informational. It serves as a canonical way to discovernon Crystal dependencies in shards, both for tools as well as humans.

A shard must only list libraries it directly links to, it must not includelibraries that are only referenced by dependencies. It must include all librariesit directly links to, regardless of a dependency doing it too.

It should map from the soname without any extension, path or version,for example libsqlite3 for /usr/lib/libsqlite3.so.0.8.6, to a version constraint.

The version constraint has the following format:

libraries:


  libQt5Gui: "*"


  libQt5Help: "~> 5.7"


  libQtBus: ">= 4.8"

The OSI publishes a list <https://opensource.org/licenses-old/category> of open source licenses and their corresponding SPDX identifiers.

Examples: Apache-2.0, GPL-3.0-or-later, Apache-2.0 OR MIT, Apache-2.0 WITH Swift-exception, <https://example.com/LICENSE>.

The URL should be compatible with typical VCS tools without modifications.http/https is preferred over VCS schemes like git. It is recommended that this URL is publicly available.

Copies of a shard (such as mirrors, development forks etc.) should point to the samecanonical repository address, even if hosted at different locations.

Example:

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

Shards may run scripts automatically after certain actions. The scriptsthemselves are mere shell commands.

postinstall

scripts:


  postinstall: cd src/libfoo && make

Each target begins with the name of the target as a key (string), then a list ofattributes (mapping). The target name is the built binary name, created in thebin folder of the project.

Example:

targets:


  server:


    main: src/server/cli.cr


  worker:


    main: src/worker.cr

The above example will build bin/server from src/server/cli.cr and bin/worker from src/worker.cr.

main

The library will be installed as a symlink to the local path.The version attribute isn’t required but will be used if present to validate the dependency.

The URL may be any protocol <https://git-scm.com/docs/git-clone#_git_urls> supported by Git, which includes SSH, GIT and HTTPS.

The Git repository will be cloned, the list of versions (and associatedshard.yml) will be extracted from Git tags (e.g., v1.2.3).

One of the other attributes (version, tag, branch or commit) is required. When missing, Shards will install the HEAD refs.

Example: git: git://git.example.org/crystal-library.git

Extends the git resolver, and acts exactly like it.

Example: github: ysbaddaden/minitest.cr

Extends the git resolver, and acts exactly like it.

Only matches dependencies hosted on gitlab.com. For personal GitLab installations, you must use the generic git resolver.

Example: gitlab: thelonlyghost/minitest.cr

Extends the git resolver, and acts exactly like it.

Example: bitbucket: tom/library

Extends the git resolver, and acts exactly like it.

Example: codeberg: tom/library

The URL may be any protocol <https://www.mercurial-scm.org/repo/hg/help/clone> supported by Mercurial, which includes SSH and HTTPS.

The Mercurial repository will be cloned, the list of versions (and associatedshard.yml) will be extracted from Mercurial tags (e.g., v1.2.3).

One of the other attributes (version, tag, branch, bookmark or commit) is required. When missing, Shards will install the @ bookmark or tip.

Example: hg: <https://hg.example.org/crystal-library>

The URL may be any protocol <https://fossil-scm.org/home/help/clone> supported by Fossil, which includes SSH and HTTPS.

The Fossil repository will be cloned, the list of versions (and associatedshard.yml) will be extracted from Fossil tags (e.g., v1.2.3).

One of the other attributes (version, tag, branch, or commit) is required. When missing, Shards will install trunk.

Example: fossil: <https://fossil.example.org/crystal-library>

Examples: 1.2.3, >= 1.0.0, >= 1.0.0, < 2.0 or ~> 2.0.

Most of the version operators, like >= 1.0.0, are self-explanatory, but the ~> operator has a special meaning. It specifies a minimum version, but allows the last digit specified to go up, excluding the major release number:

Even though 2.1.0-dev is strictly before 2.1.0, a version constraint like ~> 2.0.3
would not install it since only the .3 can change but the 2.0 part is fixed.

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