In this section we are going to use Travis CI as our continuous-integration service. Travis CI is mostly used for building and running tests for projects hosted at GitHub. It supports different programming languages and for our particular case, it supports the Crystal language.
Note:If you are new to continuous integration (or you want to refresh the basic concepts) we may start reading the core concepts guide.
Now let's see some examples!
latest
and nightly
A first (and very basic) Travis CI config file could be:
# .travis.yml language: crystal
That's it! With this config file, Travis CI by default will run crystal spec
. Now, we just need to go to Travis CI dashboard to add the GitHub repository.
Let's see another example:
# .travis.yml language: crystal crystal: - latest - nightly script: - crystal spec - crystal tool format --check
With this configuration, Travis CI will run the tests using both Crystal latest
and nightly
releases on every push to a branch on your Github repository.
Note: When creating a Crystal project using crystal init
, Crystal creates a .travis.yml
file for us.
Let's suppose we want to pin a specific Crystal release (maybe we want to make sure the shard compiles and works with that version) for example Crystal 0.31.1.
Travis CI only provides runners to latest
and nightly
releases directly and so, we need to install the requested Crystal release manually. For this we are going to use Docker.
First we need to add Docker as a service in .travis.yml
, and then we can use docker
commands in our build steps, like this:
# .travis.yml language: minimal services: - docker script: - docker run -v $PWD:/src -w /src crystallang/crystal:0.31.1 crystal spec
Note: We may read about different (languages)[https://docs.travis-ci.com/user/languages/] supported by Travis CI, included minimal.
Note: A list with the different official Crystal docker images is available at DockerHub.
latest
, nightly
and a specific Crystal release all together!Supported runners can be combined with Docker-based runners using a Build Matrix. This will allow us to run tests against latest
and nightly
and pinned releases.
Here is the example:
# .travis.yml matrix: include: - language: crystal crystal: - latest script: - crystal spec - language: crystal crystal: - nightly script: - crystal spec - language: bash services: - docker script: - docker run -v $PWD:/src -w /src crystallang/crystal:0.31.1 crystal spec
In native runners (language: crystal
), Travis CI already automatically installs shards dependencies using shards install
. To improve build performance we may add caching on top of that.
In a Docker-based runner we need to run shards install
explicitly, like this:
# .travis.yml language: bash services: - docker script: - docker run -v $PWD:/src -w /src crystallang/crystal:0.31.1 shards install - docker run -v $PWD:/src -w /src crystallang/crystal:0.31.1 crystal spec
Note: Since the shards will be installed in ./lib/
folder, it will be preserved for the second docker run command.
Our application or maybe some shards may required libraries and packages. This binary dependencies may be installed using different methods. Here we are going to show an example using the Apt command (since the Docker image we are using is based on Ubuntu)
Here is a first example installing the libsqlite3
development package using the APT addon:
# .travis.yml language: crystal crystal: - latest before_install: - sudo apt-get -y install libsqlite3-dev addons: apt: update: true script: - crystal spec
We are going to build a new docker image based on crystallang/crystal, and in this new image we will be installing the binary dependencies.
To accomplish this we are going to use a Dockerfile:
# Dockerfile FROM crystallang/crystal:latest # install binary dependencies: RUN apt-get update && apt-get install -y libsqlite3-dev
And here is the Travis CI configuration file:
# .travis.yml language: bash services: - docker before_install: # build image using Dockerfile: - docker build -t testing . script: # run specs in the container - docker run -v $PWD:/src -w /src testing crystal spec
Note: Dockerfile arguments can be used to use the same Dockerfile for latest, nightly or a specific version.
Travis CI may start services as requested.
For example, we can start a MySQL database service by adding a services:
section to our .travis.yml
:
# .travis.yml language: crystal crystal: - latest services: - mysql script: - crystal spec
Here is the new test file for testing against the database:
# spec/simple_db_spec.cr require "./spec_helper" require "mysql" it "connects to the database" do DB.connect ENV["DATABASE_URL"] do |cnn| cnn.query_one("SELECT 'foo'", as: String).should eq "foo" end end
When pushing this changes Travis CI will report the following error: Unknown database 'test' (Exception)
, showing that we need to configure the MySQL service and also setup the database:
# .travis.yml language: crystal crystal: - latest env: global: - DATABASE_NAME=test - DATABASE_URL=mysql://[email protected]/$DATABASE_NAME services: - mysql before_install: - mysql -e "CREATE DATABASE IF NOT EXISTS $DATABASE_NAME;" - mysql -u root --password="" $DATABASE_NAME < db/schema.sql script: - crystal spec
We are using a schema.sql
script to create a more readable .travis.yml
. The file ./db/schema.sql
looks like this:
-- schema.sql CREATE TABLE ... etc ...
Pushing these changes will trigger Travis CI and the build should be successful!
If we read Travis CI job log, we will find that every time the job runs, Travis CI needs to fetch the libraries needed to run the application:
Fetching https://github.com/crystal-lang/crystal-mysql.git Fetching https://github.com/crystal-lang/crystal-db.git
This takes time and, on the other hand, these libraries might not change as often as our application, so it looks like we may cache them and save time.
Travis CI uses caching to improve some parts of the building path. Here is the new configuration file with cache enabled:
# .travis.yml language: crystal crystal: - latest cache: shards script: - crystal spec
Let's push these changes. Travis CI will run, and it will install dependencies, but then it will cache the shards cache folder which, usually, is ~/.cache/shards
. The following runs will use the cached dependencies.
To the extent possible under law, the persons who contributed to this workhave waived
all copyright and related or neighboring rights to this workby associating CC0 with it.
https://crystal-lang.org/docs/guides/ci/travis.html