Crystal is a young and perspective language. Currently it is in the alpha stage but the language is growing very quickly, more and more people are interested in Crystal. I believe it’s a time to create a new popular shard. Shard is a project written in Crystal, like a gem for Ruby or crate for Rust. The goal of this tutorial is to show you a simple and easy way to create and publish the new shard.
Creating a Shard
To start a new project with Crystal use
crystal init command:
Here I’m passing
app argument to
crystal init command because I am making a binary program. If you want to make a library instead you have to use
crystal init command with type
crystal init -h for more information.
Let’s print out again what was generated for us:
At the root of your project directory is placed
shard.yml file. This is where you will declare your project dependencies. We will talk about it a bit later in Adding dependencies section.
spec directory is used for testing your sources. Crystal has it’s own built-in testing library called
Spec and it is very similar to Ruby’s Rspec. We will write tests for our project in Writing tests section.
Code for your package is placed inside the
src directory and it has the same convention as for Ruby project: one Crystal file with the same name as your shard. Other project related files are placed inside
src/hallo/ directory (currently there is only
Let’s add some code to let our shard be able to say “Hello” to the world. Here is how
src/hallo.rb looks after update:
Now we can build our file and check whether it compiles or not:
If compiler successfully compiles our file, you will have a new executable file
hallo in your root directory. Let’s try and run it:
Nothing was printed. Why? Because our executable only defines a new module and a method inside and we do not call it. Let’s create a real executable and print to the console “Hello, world!”.
Adding an executable
Currently Crystal does not have a convention where to place executable files. Let’s add it to the root directory. Create
./greeter.cr file with the following content:
Let’s build our executable and then run it again:
Awesome, we can run it. But the real project can be big and it could not be so easy to build or run it. So, somewhere we need to define rules that our project requires to be build to simplify a life for other developers or project’s users. This is where
Makefile comes. Here is a tiny example:
Makefile we build our
--release flag that is extremely important for production applications.
-o $(OUT_DIR)/greeter defines a destinations file, in our example it is
bin/greeter. Let’s build it:
After running this command
bin/greeter file should have been created. Run it with:
Congratulations, we have been just created our fancy Crystal shard and we are able to build and run it. Awesome!
Shards might not be so useful if there wouldn’t a way to easily reuse it in your project. Fortunately, Crystal is integrated with shards project to manage project dependencies. Follow the instructions to install it at the beginning. And then let’s make our project dependent on emoji.cr shard that is able to emojize strings.
Firstly, we need to add a dependency to our
Secondly, we need to load our dependencies with
crystal deps command:
It will clone defined dependencies to
.shards/ directory. Let’s now use emoji shard in our project. Rewrite
src/hallo.cr to the following:
On the second line we require emoji shard and then use it to emojize a message. Let’s also rewrite a
./greeter.cr executable file:
Here we want to print a custom message if user passes it to the executable via command line, and print default message (“Hello, world!”) if nothing was passed. Let’s build and run it:
We can see that our binary works as expected and emoji shard has been successfully used as a dependency. Looks easy, right? It’s time to add some tests.
Writing tests for your shard is very important. It will ensure that your code works, help you to be assured that your change does not break something and help others to know that your shard does it’s job. Actually, tests are a good place to view how your project works in details.
You may say that using BDD (or TDD) practice we have to write our tests first. And you will be completely correct. But, usually, it is much easier to understand a tutorial writing code first and then tests.
Crystal has it’s own built-in testing library called
Spec. Let’s add basic tests for our module:
We can run tests with
crystal spec command:
To test your project on Travis CI, here is a sample
It has been already generated with
crystal init command. Just add it to you project if you haven’t done it already.
Now we can write tests and test our shard on Travis. Awesome! It’s a time to document our code.
Documenting your code
Crystal documentation supports a markdown syntax. Let’s add some docs with examples:
After that we can generate documentation locally with
crystal docs command:
It will generate documentation in
doc folder. Just open
doc/index.html in your browser and review a pretty formatted documentation of your shard. Looks easy!
This is a simple and easy to use tutorial that shows how to create the new shard in Crystal language, add an executable, dependencies, write tests and document a code. I hope you are full of ideas for new projects and you are on the way to make a new shard. Crystallians are waiting for you!
The best place to learn how to create a new shard is to look at the existed ones. The list of all available shards you may find at Crystalshards and the most popular and useful projects are at Awesome Crystal.