'\" t
.\"     Title: shards
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.20
.\"      Date: 2024-03-28
.\"    Manual: Shards Manual
.\"    Source: shards 0.18.0
.\"  Language: English
.\"
.TH "SHARDS" "1" "2024-03-28" "shards 0.18.0" "Shards Manual"
.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"
shards \- dependency manager for the Crystal Language
.SH "SYNOPSIS"
.sp
\fBshards\fP [\fI<general_options>\fP...] [\fI<command>\fP] [\fI<command_options>\fP...]
.SH "DESCRIPTION"
.sp
Manages dependencies for Crystal projects and libraries with reproducible
installs across computers and systems.
.SH "USAGE"
.sp
\fIshards\fP requires the presence of a \fIshard.yml\fP file in the project
folder (working directory). This file describes the project and lists
dependencies that are required to build it. See \fBshard.yml\fP(5) for more
information on its format. A default file can be created by running \fIshards init\fP.
.sp
Running \fIshards install\fP resolves and installs the
specified dependencies. The installed versions are written into a
\fBshard.lock\fP file for using the exact same dependency versions when
running \fIshards install\fP again.
.sp
If your shard builds an application, both \fBshard.yml\fP and \fBshard.lock\fP
should be checked into version control to provide reproducible
dependency installs.
If it is only a library for other shards to depend
on, \fBshard.lock\fP should \fInot\fP be checked in, only \fBshard.yml\fP. It’s good
advice to add it to \fB.gitignore\fP.
.SH "COMMANDS"
.sp
If no \fIcommand\fP is given, \fBinstall\fP command will be run by default.
.sp
To see the available options for a particular command, use \fI\-\-help\fP after the command.
.sp
\fBbuild\fP [\fI<targets>\fP] [\fI<build_options>\fP...]
.RS 4
Builds the specified \fI<targets>\fP in \fBbin\fP path. If no targets are specified,
all are built.
This command ensures all dependencies are installed, so it is not necessary
to run \fBshards install\fP before.
.sp
All \fI<build_options>\fP following the command are delegated to \fBcrystal build\fP.
.RE
.sp
\fBcheck\fP
.RS 4
Verifies that all dependencies are installed and requirements are satisfied.
.sp
Exit status:
.sp
\fB0\fP
.RS 4
Dependencies are satisfied.
.RE
.sp
\fB1\fP
.RS 4
Dependencies are not satisfied.
.RE
.RE
.sp
\fBinit\fP
.RS 4
Initializes a default \fIshard.yml\fP in the current folder.
.RE
.sp
\fBinstall\fP [\-\-frozen] [\-\-without\-development] [\-\-production] [\-\-skip\-postinstall] [\-\-skip\-executables] [\-\-jobs=N]
.RS 4
Resolves and installs dependencies into the \fIlib\fP folder. If not already
present, generates a \fIshard.lock\fP file from resolved dependencies, locking
version numbers or Git commits.
.sp
Reads and enforces locked versions and commits if a \fIshard.lock\fP file is
present. The \fBinstall\fP command may fail if a locked version doesn\(cqt match
a requirement, but may succeed if a new dependency was added, as long as it
doesn\(cqt generate a conflict, thus generating a new \fIshard.lock\fP file.
.sp
\-\-frozen
.RS 4
Strictly installs locked versions from \fIshard.lock\fP. Fails if \fIshard.lock\fP is missing.
.RE
.sp
\-\-without\-development
.RS 4
Does not install development dependencies.
.RE
.sp
\-\-production
.RS 4
same as \fI\-\-frozen\fP and \fI\-\-without\-development\fP
.RE
.sp
\-\-skip\-postinstall
.RS 4
Does not run postinstall of dependencies.
.RE
.sp
\-\-skip\-executables
.RS 4
Does not install executables.
.RE
.sp
\-\-jobs
.RS 4
Number of repository downloads to perform in parallel (default: 8). Currently only for git.
.RE
.RE
.sp
\fBlist\fP [\-\-tree]
.RS 4
Lists the installed dependencies and their versions.
.sp
Specifying \fI\-\-tree\fP arranges nested dependencies in a tree, instead of a flattened list.
.RE
.sp
\fBlock\fP [\-\-update [<shards>...]]
.RS 4
Resolves dependencies and creates or updates the \fIshard.lock\fP file as per
the \fBinstall\fP command, but never installs the dependencies.
.sp
Specifying \fI\-\-update\fP follows the same semantics as the \fBupdate\fP
command.
.RE
.sp
\fBoutdated\fP [\-\-pre]
.RS 4
Lists dependencies that are outdated.
.sp
When \fI\-\-pre\fP is specified, pre\-release versions are also considered.
.RE
.sp
\fBprune\fP
.RS 4
Removes unused dependencies from \fIlib\fP folder.
.RE
.sp
\fBupdate\fP [<shards>...]
.RS 4
Resolves and updates all dependencies into the \fIlib\fP folder,
whatever the locked versions in the \fIshard.lock\fP file.
Eventually generates a new \fIshard.lock\fP file.
.sp
Specifying \fIshards\fP will update these dependencies only, trying to be as
conservative as possible with other dependencies, respecting the locked versions
in the \fIshard.lock\fP file.
.RE
.sp
\fBversion\fP [\fI<path>\fP]
.RS 4
Prints the current version of the shard located at \fIpath\fP (defaults to current
directory).
.RE
.sp
To see the available options for a particular command, use \fB\-\-help\fP
after a command.
.SH "GENERAL OPTIONS"
.sp
\-\-version
.RS 4
Prints the version of \fIshards\fP.
.RE
.sp
\-h, \-\-help
.RS 4
Prints usage synopsis.
.RE
.sp
\-\-no\-color
.RS 4
Disables colored output.
.RE
.sp
\-\-local
.RS 4
Do not update remote repository cache. Instead, Shards will use the local copies
already present in the cache (see \fBSHARDS_CACHE_PATH\fP).
The command will fail if a dependency is unavailable in the cache.
.RE
.sp
\-q, \-\-quiet
.RS 4
Decreases the log verbosity, printing only warnings and errors.
.RE
.sp
\-v, \-\-verbose
.RS 4
Increases the log verbosity, printing all debug statements.
.RE
.SH "INSTALLATION"
.sp
Shards is usually distributed with Crystal itself. Alternatively, a
separate \fIshards\fP package may be available for your system.
.sp
To install from source, download or clone
.URL "https://github.com/crystal\-lang/shards" "the repository" ""
and run
\fBmake CRFLAGS=\-\-release\fP. The compiled binary is in \fIbin/shards\fP and
should be added to \fBPATH\fP.
.SH "ENVIRONMENT VARIABLES"
.sp
SHARDS_OPTS
.RS 4
Allows general options to be passed in as environment variable.
\fBExample\fP: \fISHARDS_OPTS="\-\-no\-color" shards update\fP
.RE
.sp
SHARDS_CACHE_PATH
.RS 4
Defines the cache location. In this folder, shards stores local copies of remote
repositories.
Defaults to \fI.cache/shards\fP in the home directory (\fI$XDG_CACHE_HOME\fP or \fI$HOME\fP)
or the current directory.
.RE
.sp
SHARDS_INSTALL_PATH
.RS 4
Defines the location where dependencies are installed.
Defaults to \fIlib\fP.
.RE
.sp
SHARDS_BIN_PATH
.RS 4
Defines the location where executables are installed.
Defaults to \fIbin\fP.
.RE
.sp
CRYSTAL_VERSION
.RS 4
Defines the crystal version that dependencies should be resolved against.
Defaults to the output of \fIcrystal env CRYSTAL_VERSION\fP.
.RE
.sp
SHARDS_OVERRIDE
.RS 4
Defines an alternate location of \fIshard.override.yml\fP.
.RE
.SH "FILES"
.sp
shard.yml
.RS 4
Describes a shard project including its dependencies.
See \fBshard.yml\fP(5) for documentation.
.RE
.sp
shard.override.yml
.RS 4
Allows overriding the source and restriction of dependencies. An alternative
location can be configured with the env var \fBSHARDS_OVERRIDE\fP.
.sp
The file contains a YAML document with a single \fBdependencies\fP key. It has the
same semantics as in \fBshard.yml\fP. Dependency configuration takes precedence over
the configuration in \fBshard.yml\fP or any dependency\(cqs \fBshard.yml\fP.
.sp
Use cases are local working copies, forcing a specific dependency version
despite mismatching constraints, fixing a dependency, checking compatibility
with unreleased dependency versions.
.RE
.sp
shard.lock
.RS 4
Lockfile that stores information about the installed versions.
.sp
If your shard builds an application, \fBshard.lock\fP should be checked into version
control to provide reproducible dependency installs.
.sp
If it is only a library for other shards to depend on, \fBshard.lock\fP should \fInot\fP
be checked in, only \fBshard.yml\fP. It’s good advice to add it to \fB.gitignore\fP.
.RE
.SH "REPORTING BUGS"
.sp
Report shards bugs to \c
.URL "https://github.com/crystal\-lang/shards/issues" "" ""
.sp
Crystal Language home page: \c
.URL "https://crystal\-lang.org" "" ""
.SH "COPYRIGHT"
.sp
Copyright © 2024 Julien Portalier.
.sp
.URL "http://www.apache.org/licenses/LICENSE\-2.0" "License Apache 2.0" ""
.sp
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.SH "AUTHORS"
.sp
Written by Julien Portalier and the Crystal project.
.SH "SEE ALSO"
.sp
\fBshard.yml\fP(5)