The shards command¶
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
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
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.
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.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
crystal init does this automatically when initializing a
shards [<options>...] [<command>]
If no command is given,
install will be run by default.
shards build: Builds an executable
shards check: Verifies dependencies are installed
shards init: Generates a new
shards install: Resolves and installs dependencies
shards list: Lists installed dependencies
shards prune: Removes unused dependencies
shards update: Resolves and updates dependencies
shards version: Shows version of a shard
To see the available options for a particular command, use
--help after a command.
--version: Prints the version of
-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.lockare out of sync (used by
-q, --quiet: Decreases the log verbosity, printing only warnings and errors.
-v, --verbose: Increases the log verbosity, printing all debug statements.
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
Verifies that all dependencies are installed and requirements are satisfied.
0: Dependencies are satisfied.
1: Dependencies are not satisfied.
Initializes a shard folder and creates a
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
Lists the installed dependencies and their versions.
Removes unused dependencies from lib folder.
Resolves and updates all dependencies into the lib folder again, whatever the locked versions and commits in the
shard.lock file. Eventually generates a
shards version [<path>]
Prints the version of the shard.