Language Guide: Crystal
Tutorials & 2.0 Sample Apps > Language Guide: Crystal
This guide will help you get started with a minimal Crystal application on CircleCI.
Overview
If you’re in a rush, just copy the sample configuration below into a .circleci/config.yml
in your project’s root directory and start building.
You can view an example Crystal project at the following link:
In the project you will find a commented CircleCI configuration file .circleci/config.yml
.
The application uses Crystal 0.27 and Kemal 0.25. Both Crystal and Kemal are
developing quickly. Altering the Docker image to the :latest
version may cause
breaking changes.
Sample configuration
version: 2 # use CircleCI 2.0
jobs: # a collection of jobs
build:
working_directory: ~/demo_app
docker: # run build steps with docker
- image: crystallang/crystal:0.27.0 # primary docker container; all `steps` will run here.
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
steps: # a collection of executable steps
- checkout # checks out source code to working directory
- restore_cache: # Restore dependency cache
# Read about caching dependencies: https://circleci.com/docs/2.0/caching/
key: dependency-cache-{{ checksum "shard.lock" }}
- run:
name: Install dependencies.
command: shards install
- save_cache: # Step to save dependency cache
key: dependency-cache-{{ checksum "shard.lock" }}
paths:
- ./lib
- run:
name: test
command: crystal spec
# See https://circleci.com/docs/2.0/deployment-integrations/ for deploy examples
Config walkthrough
Every config.yml
starts with the version
key.
This key is used to issue warnings about breaking changes.
version: 2
A run is comprised of one or more jobs.
Because this run does not use workflows,
it must have a build
job.
Use the working_directory
key
to specify where a job’s steps
run.
By default, the value of working_directory
is ~/project
, where project
is a literal string.
The steps of a job occur in a virtual environment called an executor. In this example, we use the official Crystal Docker image as our primary container. All commands for a job execute in this container.
jobs:
build:
working_directory: ~/demo_app
docker:
- image: crystallang/crystal:0.27.0
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
After choosing containers for a job, create steps
to run specific commands.
Use the checkout
step
to check out source code. By default, source code is checked out to the path specified by working_directory
.
To save time between runs, consider caching dependencies or source code.
Use the save_cache
step
to cache certain files or directories. In this example, the installed packages (“Shards”) are cached.
Use the restore_cache
step
to restore cached files or directories. In this example, we use a checksum of
the shard.lock
file to determine if the dependency cache has changed.
steps: #
- checkout
- restore_cache:
key: dependency-cache-{{ checksum "shard.lock" }}
- run:
name: Install dependencies.
command: shards install
- save_cache:
key: dependency-cache-{{ checksum "shard.lock" }}
paths:
- ./lib
Finally, we run crystal spec
to run the project’s test suite.
- run:
name: test
command: crystal spec
Great! You’ve set up CircleCI 2.0 for a basic Crystal application.
Deploy
See the Deploy document for example deploy target configurations.