A basic wrapper around shard

Community
,
1

cpm

Crystal Package Manager — a tiny wrapper around shards that saves you from hunting URLs.

Why I Built This

I got tired of this workflow:

  1. Want to add kemal to my project
  2. Open browser
  3. Search “kemal crystal shard”
  4. Click GitHub
  5. Copy the URL
  6. Paste into shard.yml
  7. Run shards install

That’s 7 steps for something that should be 1.

cpm fixes this:

cpm add kemal   # Done.

No browser. No copy-paste. No remembering URLs.

shards is great at installing dependencies. But it doesn’t help you find them. cpm fills that gap and gets out of the way.

Install

curl -fsSl https://raw.githubusercontent.com/slick-lab/cpm/main/install.sh | sudo bash

Usage

# Initialize a project
cpm init
cpm init --cache    # also creates ~/.cpm/cache.txt

# Search for packages
cpm search kemal
cpm search kemal --auto   # pick top result automatically

# Add a dependency
cpm add kemal

# Remove a dependency
cpm remove kemal

# Then use shards as normal
shards install
shards prune
shards update

How it works

cpm doesn’t replace shards. It just makes the shard.yml part easier:

  • cpm search queries GitHub for Crystal shards
  • cpm add checks your cache, writes to shard.yml
  • shards handles the actual downloading and version resolution

We keep a simple ~/.cpm/cache.txt:

kemal	https://github.com/kemalcr/kemal
pg	https://github.com/will/crystal-pg

No JSON. No metadata. Just names and URLs.

Why not just use shards?

shards is perfect for what it does: resolving versions and installing dependencies.

But shards assumes you already know:

  • The exact package name
  • The GitHub URL
  • Whether it’s maintained

cpm helps with discovery. Then shards takes over.

2

Very cool!

3

What excellent news and work.
I was waiting for this.

4

I like the basic idea of this tool.

The algorithm is simple. It searches for a library name using the GitHub API. It sorts the results by the number of stars. Then it selects the repository with the most stars.

https://api.github.com/search/repositories?
q=kemal+language:crystal&sort=stars&per_page=5

This is similar to the “I’m Feeling Lucky” button on Google. So, in some cases, it may choose the wrong repository.

It is not difficult to point out this weakness. But I hesitate to be too critical of this method, because I probably would not have noticed the inconvenience that this tool tries to solve. I probably would not have come up with this solution either.

After using computers for a long time, our ideas tend to become fixed. This method is simple, but it may be practically good enough in most cases.

5

you can use the command without the --auto flag it displays a list of repos for you to choose from.

Alternatively you can edit ~/.cpm/cache.txt and include shards you mostly use

the add command reads the cache before performing a search

6

Currently, when the cache does not exist, cpm add runs search --auto.

This means that if the user has not run cpm search beforehand, cpm add may add the top repository in the search results to shard.yml without confirmation.

It may be better to require users to pass --auto explicitly when they want automatic selection. If --auto is not specified, cpm add could show candidates, as the normal search command does, and let the user choose one.

As another point, if cpm searches only GitHub, users cannot find projects hosted elsewhere.
Some developers choose not to host their projects on GitHub because they do not like its UI or social features, or because GitHub itself is a company-operated service and is not open source.

However, supporting every hosting service requires time and effort. So I think it is reasonable for the author to decide where to draw the line.

7

Okay thanks for the feedback