Travis CI is currently known as the most prevalent cloud CI service. Although it does not have an official support for Common Lisp, Roswell almost eliminates the otherwise huge amount of effort for testing your Common Lisp product.

Disclaimer: This document is based on Roswell v0.0.3.44 or above, so the content might change in the near future. Check the time stamp of this article and if it seems obsoleted --- contact us (or make it up to date yourself!!!).

Before getting started, sign up to Travis CI and enable the testing for your repository at your profile page.

Basic .travis.yml

Travis CI's build process can be customized with a file named .travis.yml, which Travis assumes to be located at the project root. (cf. Customizing the Build - Travis CI) Below is a simple .travis.yml example which runs the unit test for quri, an improved/faster replacement for PURI URI encoder/decoder, with the latest SBCL binary:

language: common-lisp
sudo: required

install:
  - curl -L https://raw.githubusercontent.com/roswell/roswell/release/scripts/install-for-ci.sh | sh

script:
  - ros -s prove -e '(or (prove:run :quri-test) (uiop:quit -1))'

This basic template is fully functional. However, in order to use the latest and complete testing environment, you should add several options to the yaml file.

Advanced .travis.yml

Fast forward, the resulting script is shown below. You can use this as a template.

language: common-lisp
sudo: false

addons:
  apt:
    packages:
      - libc6-i386

env:
  global:
    - PATH=~/.roswell/bin:$PATH
    - ROSWELL_INSTALL_DIR=$HOME/.roswell
  matrix:
    - LISP=sbcl-bin
    - LISP=ccl-bin
    - LISP=abcl
    - LISP=clisp
    - LISP=ecl
    - LISP=cmucl
    - LISP=alisp

matrix:
  allow_failures:
    - env: LISP=clisp
    - env: LISP=abcl
    - env: LISP=ecl
    - env: LISP=cmucl
    - env: LISP=alisp

install:
  - curl -L https://raw.githubusercontent.com/roswell/roswell/release/scripts/install-for-ci.sh | sh
  - ros install prove
  - ros install fukamachi/fast-http
  - ros install fukamachi/quri

cache:
  directories:
    - $HOME/.roswell
    - $HOME/.config/common-lisp

script:
  - run-prove quri-test.asd

Step by Step Instruction

Tests with multiple implementations

The foremost important feature in automated continuous testing is to run the tests on multiple implementations. env.matrix in .travis.yml enables this feature, and Travis creates a new build for each Lisp implementations. When $LISP is set, Roswell's CI installer sets up the corresponding Lisp implementation, so no need to installing and running each implementation manually.

language: common-lisp
sudo: required

+env:
+  matrix:
+    - LISP=sbcl-bin
+    - LISP=ccl-bin
+    - LISP=abcl
+    - LISP=clisp
+    - LISP=ecl

...

Ignore the failures on some implementations

You might think that the tests on some implementations are less important than on the others. In that case, add matrix.allow_failures directive. cf. Rows that are Allowed to Fail - Travis CI

env:
  matrix:
    - LISP=sbcl-bin
    - LISP=ccl-bin
    - LISP=abcl
    - LISP=clisp
    - LISP=ecl

+matrix:
+  allow_failures:
+    - env: LISP=clisp

Installing the latest dependencies

You may wonder how you can run the test using a latest version of a library which is not yet included in the quicklisp. Libraries at GitHub can be installed with ros install <github username>/<github repos> like this:

install:
  - curl -L https://raw.githubusercontent.com/roswell/roswell/release/scripts/install-for-ci.sh | sh
+  # Using the latest fast-http and quri
+  - ros install fukamachi/fast-http
+  - ros install fukamachi/quri

Activating the container-based infrastructure

When sudo field is set to false in the yaml configuration, i.e. sudo: false, Travis CI uses its new container-based infrastructure. We can expect faster launch time of the tests compared to the old infrastructure.

For sbcl and ccl, following .travis.yml just works.

language: common-lisp
-sudo: required
+sudo: false

env:
  global:
    - PATH=~/.roswell/bin:$PATH
+    - ROSWELL_INSTALL_DIR=$HOME/.roswell
  matrix:
    - LISP=sbcl-bin
    - LISP=ccl-bin

install:
  - curl -L https://raw.githubusercontent.com/roswell/roswell/release/scripts/install-for-ci.sh | sh

script:
  - ros -s prove -e '(or (prove:run :quri-test) (uiop:quit -1))'

To use the new infrastructure for clisp, abcl, alisp or cmucl, add the following lines to the yaml file:

addons:
  apt:
    packages:
      - libc6-i386
      - openjdk-7-jre

This is because clisp, abcl, alisp or cmucl requies openjdk-7-jre, clisp and libc-i386 to be installed via APT, respectively.

Directory caching

Directory caching makes the launch time even faster. cf. Caching Dependencies and Directories - Travis CI

language: common-lisp
sudo: false

env:
  global:
    - PATH=~/.roswell/bin:$PATH
    - ROSWELL_INSTALL_DIR=$HOME/.roswell
  matrix:
    - LISP=sbcl-bin
    - LISP=ccl-bin

install:
  - curl -L https://raw.githubusercontent.com/roswell/roswell/release/scripts/install-for-ci.sh | sh

+cache:
+  directories:
+    - $HOME/.roswell
+    - $HOME/.config/common-lisp

script:
  - ros -s prove -e '(or (prove:run :quri-test) (uiop:quit -1))'

Using Roswell script (run-prove)

Some libraries provide their Roswell scripts, like prove's run-prove command. Install these commands via e.g. ros install prove. Make sure ~/.roswell/bin is already in the $PATH.

language: common-lisp
sudo: required

env:
  global:
    - PATH=~/.roswell/bin:$PATH       # !!! IMPORTANT !!!
  matrix:
    - LISP=sbcl-bin
    - LISP=ccl-bin
    - LISP=abcl
    - LISP=clisp
    - LISP=ecl

matrix:
  allow_failures:
    - env: LISP=clisp

install:
  - curl -L https://raw.githubusercontent.com/roswell/roswell/release/scripts/install-for-ci.sh | sh
+  - ros install prove

script:
-  - ros -s prove -e '(or (prove:run :quri-test) (uiop:quit -1))'
+  - run-prove quri-test.asd