Crystal is typically accompanied by Shards, its dependency manager.
It manages dependencies for Crystal projects and libraries with reproducible installs across computers and systems.
Shards is usually distributed with Crystal itself. Alternatively, a separate shards
package may be available for your system.
To install from source, download or clone the repository and run make CRFLAGS=--release
. The compiled binary is in bin/shards
and should be added to PATH
.
shards
requires the presence of a shard.yml
file in the project folder (working directory). This file describes the project and lists dependencies that are required to build it. A default file can be created by running shards init
. The file's contents are explained in the Writing a Shard guide and a detailed description of the file format is provided by the shard.yml specification.
Running shards install
resolves and installs the specified dependencies. The installed versions are written into a shard.lock
file for using the exact same dependency versions when running shards install
again.
If your shard builds an application, both shard.yml
and shard.lock
should be checked into version control to provide reproducible dependency installs. If it is only a library for other shards to depend on, shard.lock
should not be checked in, only shard.yml
. It's good advice to add it to .gitignore
(the crystal init
does this automatically when initializing a lib
repository).
shards [<options>...] [<command>]
If no command is given, install
will be run by default.
shards build
: Builds an executableshards check
: Verifies dependencies are installedshards init
: Generates a new shard.yml
shards install
: Resolves and installs dependenciesshards list
: Lists installed dependenciesshards prune
: Removes unused dependenciesshards update
: Resolves and updates dependenciesshards version
: Shows version of a shardTo see the available options for a particular command, use --help
after a command.
Common options:
--version
: Prints the version of shards
.-h, --help
: Prints usage synopsis.--no-color
: Disabled colored output.--production
: Runs in release mode. Development dependencies won't be installed and only locked dependencies will be installed. Commands will fail if dependencies in shard.yml
and shard.lock
are out of sync (used by install
, update
, check
and list
command)-q, --quiet
: Decreases the log verbosity, printing only warnings and errors.-v, --verbose
: Increases the log verbosity, printing all debug statements.shards build
shards build [<targets>] [<options>...]
Builds the specified targets in bin
path. If no targets are specified, all are built. This command ensures all dependencies are installed, so it is not necessary to run shards install
before.
All options following the command are delegated to crystal build
.
shards check
shards check
Verifies that all dependencies are installed and requirements are satisfied.
Exit status:
0
: Dependencies are satisfied.1
: Dependencies are not satisfied.shards init
shards init
Initializes a shard folder and creates a shard.yml
.
shards install
shards install
Resolves and installs dependencies into the lib
folder. If not already present, generates a shard.lock
file from resolved dependencies, locking version numbers or Git commits.
Reads and enforces locked versions and commits if a shard.lock
file is present. The install command may fail if a locked version doesn't match a requirement, but may succeed if a new dependency was added, as long as it doesn't generate a conflict, thus generating a new shard.lock
file.
shards list
shards list
Lists the installed dependencies and their versions.
shards prune
shards prune
Removes unused dependencies from lib folder.
shards update
shards update
Resolves and updates all dependencies into the lib folder again, whatever the locked versions and commits in the shard.lock
file. Eventually generates a new shard.lock
file.
shards version
shards version [<path>]
Prints the version of the shard.
To the extent possible under law, the persons who contributed to this workhave waived
all copyright and related or neighboring rights to this workby associating CC0 with it.
https://crystal-lang.org/docs/the_shards_command/