shard.yml.adoc

= shard.yml(5)
:date: {localdate}
:shards_version: {shards_version}
:man manual: File Formats
:man source: shards {shards_version}

== NAME
shard.yml - metadata for projects managed by shards(1)

== DESCRIPTION

The file _shard.yml_ is a YAML file with metadata about a project managed by shards, known as a *shard*. It must contain at least _name_ and _version_ attributes plus optional additional attributes.

Both libraries and applications will benefit from `shard.yml`.

The metadata for libraries are expected to have more information (e.g., list of
authors, description, license) than applications that may only have a name, version and
dependencies.

== FORMAT

The file must be named _shard.yml_ and be a valid YAML file with UTF-8 encoding.
It must not contain duplicate attributes in any mapping.
It should use an indent of 2 spaces.
It should not use advanced YAML features, only simple mappings, sequences and
strings (Failsafe Schema).

== REQUIRED ATTRIBUTES
*name*::
  The name of the project (string, required).
+
--
- It must be unique.
- It must be 50 characters or less.
- It should be lowercase (a-z).
- It should not contain _crystal_.
- It may contain digits (0-9) but not start with one.
- It may contain underscores or dashes but not start/end with one.
- It must not have consecutive underscores or dashes.
--
+
Examples: _minitest_, _mysql2_, _battery-horse_.

*version*::
  The version number of the project (string, required).
+
--
- It must contain digits.
- It may contain dots and dashes but not consecutive ones.
- It may contain a letter to make it a 'prerelease'.
--
+
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 like
http://semver.org/[Semantic Versioning] or http://calver.org/[Calendar Versioning]
is highly recommended.

== OPTIONAL ATTRIBUTES
*authors*::
  A list of authors, along with their contact email (optional) (sequence of string).
+
--
- Each author must have a name.
- Each author may have an email address, within angle bracket (_<_ and _>_)
  chars.
--
+
*Example:*
+
[source,yaml]
----
authors:
- Ary
- Julien Portalier <julien@example.org>
----

*crystal*::
A restriction to indicate which are the supported crystal versions. This will
usually express a lower and upper-bound constraints (string, recommended)
+
When resolving dependencies, this information is not used. After dependencies
have been determined shards checks all of them are expected to work with
the current crystal version. If not, a warning appears for the offending
dependencies. The resolved versions are installed and can be used at your
own risk.
+
The valid values are mostly the same as for _dependencies.version_:
+
--
* A version number prefixed by an operator: _<_, _\<=_, _>_, _>=_, _!=_ or _~>_.
* Just _"*"_ if any version will do (this is the default if unspecified).
* Multiple requirements can be separated by commas.
--
There is a special legacy behavior (its use is discouraged) when just a version
number 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't
break your library.
+
*Example:*
+
[source,yaml]
----
crystal: ">= 0.35, < 2.0"
----

*dependencies*::
A list of required dependencies (mapping).
+
Each dependency begins with the name of the dependency as a key (string) then a
list of attributes (mapping) that depend on the resolver type.
+
*Example:*
+
[source,yaml]
----
dependencies:
  minitest:
    github: ysbaddaden/minitest.cr
    version: 0.1.0
----

*development_dependencies*::
A list of dependencies required to work on the project, but not necessary
to build and run the project (mapping).
+
They will be installed for the main project or library itself.
When the library is installed as a dependency for another project the
development dependencies will never be installed.
+
Development dependencies follow the same scheme as dependencies.
+
*Example:*
+
[source,yaml]
----
development_dependencies:
  minitest:
    github: ysbaddaden/minitest.cr
    version: ~> 0.1.3
----

*description*::
  A single line description of the project (string, recommended).

*documentation*::
The URL to a website providing the project's documentation for online browsing (string).

*executables*::
A list of executables to be installed (sequence).
+
The executables can be of any type or language (e.g., shell, binary, ruby), must
exist 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:*
+
[source,yaml]
----
executables:
- micrate
- icr
----

*homepage*::
The URL of the project's homepage (string).

*libraries*::
A list of shared libraries the shard tries to link to (mapping).
+
This field is purely informational. It serves as a canonical way to discover
non Crystal dependencies in shards, both for tools as well as humans.
+
A shard must only list libraries it directly links to, it must not include
libraries that are only referenced by dependencies. It must include all libraries
it 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:
+
--
- It may be a version number.
- It may be _"*"_ if any version will do.
- The version number may be prefixed by an operator: _<_, _\<=_, _>_, _>=_, _!=_ or _~>_.
--
+
[source,yaml]
----
libraries:
  libQt5Gui: "*"
  libQt5Help: "~> 5.7"
  libQtBus: ">= 4.8"
----

*license*::
  An http://opensource.org/[OSI license] name or an URL to a license file
(string, recommended).

*repository*::
The URL of the project's canonical repository (string, recommended).
+
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 same
canonical repository address, even if hosted at different locations.
+
*Example:*
+
[source,yaml]
----
repository: "https://github.com/crystal-lang/shards"
----

*scripts*::
  Script hooks to run. Only _postinstall_ is supported.
+
Shards may run scripts automatically after certain actions. The scripts
themselves are mere shell commands.

*postinstall*:::
The _postinstall_ hook of a dependency will be run whenever that dependency is
installed or upgraded in a project that requires it. This may be used to compile
a C library, to build tools to help working on the project, or anything else.
+
The script will be run from the dependency's installation directory, for example
_lib/foo_ for a Shard named _foo_.
+
*Example:*
+
[source,yaml]
----
scripts:
  postinstall: cd src/libfoo && make
----

*targets*::
A list of targets to build (mapping).
+
Each target begins with the name of the target as a key (string), then a list of
attributes (mapping). The target name is the built binary name, created in the
_bin_ folder of the project.
+
*Example:*
+
[source,yaml]
----
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*:::
A path to the source file to compile (string).

== DEPENDENCY ATTRIBUTES

Each dependency needs at least one attribute that defines the resolver for this
dependency. Those can be _path_, _git_, _github_, _gitlab_, _bitbucket_.

*path*::
A local path (string).
+
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.

*git*::
A Git repository URL (string).
+
The URL may be https://git-scm.com/docs/git-clone#_git_urls[any protocol]
supported by Git, which includes SSH, GIT and HTTPS.
+
The Git repository will be cloned, the list of versions (and associated
_shard.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_

*github*::
GitHub repository URL as _user/repo_ (string)
+
Extends the _git_ resolver, and acts exactly like it.
+
*Example:* _github: ysbaddaden/minitest.cr_

*gitlab*::
GitLab repository URL as _user/repo_ (string).
+
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_

*bitbucket*::
Bitbucket repository URL as _user/repo_ (string).
+
Extends the _git_ resolver, and acts exactly like it.
+
*Example:* _bitbucket: tom/library_

*hg*::

A Mercurial repository URL (string).
+
The URL may be https://www.mercurial-scm.org/repo/hg/help/clone[any protocol]
supported by Mercurial, which includes SSH and HTTPS.
+
The Mercurial repository will be cloned, the list of versions (and associated
_shard.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_

*fossil*::

A https://www.fossil-scm.org[Fossil] repository URL (string).
+
The URL may be https://fossil-scm.org/home/help/clone[any protocol]
supported by Fossil, which includes SSH and HTTPS.
+
The Fossil repository will be cloned, the list of versions (and associated
_shard.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_

*version*::
A version requirement (string).
+
--
- It may be an explicit version number.
- It may be _"*"_ wildcard if any version will do (this is the default).
  Shards will then install the latest tagged version (or HEAD if no tagged
  version available).
- The version number may be prefixed by an operator: _<_, _\<=_, _>_, _>=_, _!=_ or _~>_.
- Multiple requirements can be separated by commas.
--
+
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:
--
- _~> 0.3.5_ is identical to _>= 0.3.5 and < 0.4.0_.
- _~> 2.0.3_ is identical to _>= 2.0.3 and < 2.1_.
- _~> 2.1_ is identical to _>= 2.1 and < 3.0_.
- _~> 0.3_ is identical to _>= 0.3 and < 1.0_.
- _~> 1_ is identical to _>= 1.0 and < 2.0_.
--

NOTE: 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.

*branch*::
  Install the specified branch of a git dependency, or the named branch
  of a mercurial or fossil dependency (string).

*commit*::
  Install the specified commit of a git, mercurial, or fossil dependency
  (string).

*tag*::
  Install the specified tag of a git, mercurial, or fossil dependency
  (string).

*bookmark*::
  Install the specified bookmark of a mercurial dependency (string).

== Example:

Here is an example _shard.yml_ for a library named _shards_ at version _1.2.3_
with some dependencies:

[source,yaml]
----
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
Written by Julien Portalier and the Crystal project.

== SEE ALSO
*shards*(1)