shards

Create a skeleton shard.yml file

$ shards init

$ shards install

$ shards update

$ shards list

$ shards version [path/to/dependency_directory]

shards command [options...] [arguments...]
shards [--version | --help]

install
    Downloads and installs all declared dependencies from shard.yml into the project's lib/ directory. If shard.lock exists, it ensures exact version reproducibility; otherwise, it resolves new versions and generates the lock file.

update
    Updates all project dependencies to their latest compatible versions based on the constraints in shard.yml. This action will regenerate the shard.lock file.

build
    Compiles the project and its dependencies into an executable. This command typically creates a binary in the bin/ directory.

run
    Executes the main file of the Crystal project. This is a convenient way to run the application or tests without explicitly building it first.

init
    Initializes a new Crystal project, setting up the basic directory structure and creating a boilerplate shard.yml file for quick starts.

exec command
    Executes a given shell command within the context of the project's dependencies, ensuring that required binaries or environment variables from installed shards are available.

--version
    Displays the version number of the shards tool currently installed on the system.

--help
    Shows general help information about shards or specific help for a particular command (e.g., shards install --help).

shards is the official dependency manager and build tool for the Crystal programming language. While not a standalone command provided by default on most Linux distributions, it is an integral part of the Crystal toolchain, installed alongside the Crystal compiler. It enables developers to manage project dependencies by fetching, installing, and updating external libraries defined in a shard.yml file. Beyond dependency management, shards provides functionalities for initializing new projects, building executables, and running project-specific tasks, significantly streamlining the development workflow for Crystal applications on Linux systems.

shards is not a universal Linux command-line utility but a specialized tool for Crystal language development. It requires the Crystal compiler to be installed on your system. Its functionality is strictly tied to Crystal projects and does not manage system-wide software packages like distribution-specific package managers (e.g., APT, DNF, Pacman).

The configuration file located at the root of a Crystal project. It defines project metadata (name, version, authors) and lists external dependencies with their names and version constraints. This file is crucial for shards to understand and resolve project requirements.

An automatically generated file that precisely records the versions of all direct and transitive dependencies used in a project. This file ensures that builds are reproducible across different development environments by locking dependency versions. It should always be committed to version control alongside shard.yml.

shards features a robust dependency resolution algorithm. It not only resolves direct project dependencies but also their sub-dependencies, ensuring that all required libraries are compatible and available. It manages version conflicts and provides feedback if an unresolvable dependency graph is detected.

shards was conceptualized and developed as a fundamental component of the Crystal language ecosystem from its early days. It quickly became the official and primary tool for managing dependencies and project structure in Crystal, evolving to support the language's growth and community needs. Its development parallels Crystal's focus on simplicity, performance, and developer experience, providing a consistent and efficient way to handle external code in Crystal projects.

crystal(1), git(1), npm(1) (Node.js package manager), bundler(1) (Ruby gem manager), mix(1) (Elixir build tool)