How crystal-lang/shards works
Main Components
• Command Line Interface (CLI) Module:
• Located in the src directory (src/cli.cr and src/commands/*), this module parses user commands such as init, install, update, prune, and version.
• It routes input commands to the corresponding functionality.
• Dependency Configuration & Parsing:
• Handles reading, parsing, and writing the shard.yml and shard.lock files.
• This component is responsible for interpreting the user-defined dependency definitions.
• Dependency Resolution Engine:
• The heart of the project lies in the dependency resolution logic.
• Two parts here:
▪ The core resolution logic in the src (files like src/molinillo_solver.cr, src/resolvers/*) initiates dependency checks and applies resolution rules.
▪ The “molinillo” library (found in lib/molinillo) implements general dependency graph handling. It includes modules for dealing with the dependency graph, handling delegates (resolution state, specification providers), and error handling.
• Resolvers for External Sources:
• Found in src/resolvers (with specific files for git, hg, fossil, path, crystal, etc.), these components retrieve dependency versions and metadata from external sources.
• Build/Infrastructure and Testing Components:
• Makefiles, CI configurations (.circleci, .github/workflows) and the specs (unit and integration tests) ensure a robust development and deployment process.
Relationships and Interactions
• The CLI accepts commands and delegates tasks to the application core.
• The configuration component reads shard.yml/shard.lock to supply dependency definitions.
• The main dependency resolution engine, supported by the molinillo library, consumes these definitions and builds/updates a dependency graph.
• Based on dependency requirements, the specific resolvers (git, hg, etc.) are invoked to fetch metadata, retrieve available versions, and enforce semver rules.
• Interaction flows:
▪ The CLI triggers the resolution process.
▪ The resolution engine uses the molinillo dependency graph to compute a valid set of dependencies.
▪ Resolvers interact with external repositories or local sources as needed.
▪ Results get stored back into shard.lock.
Architectural Patterns and Design Principles
• Modular Design: Separating the CLI layer, the core dependency resolution engine, and external source resolvers.
• Separation of Concerns: Each directory (src, lib, spec) is clearly segmented to manage commands, logic, and tests independently.
• Reusability & Extensibility: The molinillo library is a reusable dependency solver, and the resolvers are cleanly abstracted to allow extension to new source types.