Language Guide: Crystal

6 months ago • 1 min read

Cloud Server v3.x Server v2.x

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:

• Demo Crystal Project on GitHub

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
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 for a basic Crystal application.

Deploy

See the Deploy document for example deploy target configurations.

---

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

• Suggest an edit to this page (please read the contributing guide first).
• To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
• CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

---

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.