How to use Travis-CI for research

This guide explains how to use Travis-CI for automated integration and testing of research software.

This guide is aimed at...

• Research staff and students

Introduction

What follows is a short guide to getting started with using Travis-CI for research. More detailed documentation can be found in the Travis documentation. Especially the documentation of different Travis environments is useful as a reference documenting which software is preinstalled on the various Travis instances. This guide assumes that you already have your code in version control on Github.com.

• How to setup GitHub for a research project

Instructions

The first step is to activate Travis-CI on your repository. Visit travis-ci.org for public or travis-ci.com for private repositories and sign in with your Github account. Here you should find a list of your repositories where you can activate Travis for each individual repository. If you don't find a particular repository check that you have admin rights to it on Github. Once Travis has been activated you should add the build and test instructions to your repository.

The configuration of Travis is managed in the a .travis.yml file in the root of your code repository. The file is in YAML format and contains the steps needed to build, install and test the code in the repository.

As an example we will look at how to install and test a small python project. More python specific details can be found at Travis web site:

language: python
python: 
  - "3.6"
install:
  - pip install -r requirements.txt
script: 
  - py.test

This very simple script selects a Travis machine with python 3.6 installed and installs the dependencies from a requirements.txt file in the root of the repository and uses py.test to run the tests found in the repository. The install: and script: sections define small samples of Bash scripts which are executed in order to install and test the program. In this small example they are both single line but it is possible to add more complex sections. This can be done either by adding additional lines one after the other e.g.:

language: python
python: 
  - "3.6"
install:
  - pip install -r requirements.txt
  - pip install OptionalDependency
script: 
  - py.test

Or by the use of the pipe character | to create multiline scripts language:

language: python
python: 
  - "3.6"
install:
  - |
    pip install -r requirements.txt
    pip install OptionalDependency
script: 
  - py.test

Several other more sections and more advanced features are available see the Travis documentation. For projects that have additional dependencies it may be necessary to install additional software before building and running the tests. The Travis Linux instances are based on Ubuntu 12.04 and Ubuntu 14.04 and it is possible to install packages from their respective repositories via the build in package manager apt. Note that the default Travis machine type is using Docker containers and  have some restrictions on which packages are allowed to be installed and does not allow the use of sudo. Below is a small example of a c++ project using CMake as a build tool and Doxygen for document generation:

language: cxx
addons:
  apt:
    packages:
      - doxygen
      - nameofdependencypackagetoinstall
    script:
      - |
        mkdir build
        cd build
        cmake ..
        make
        ctest --output-on-failure  

This guide has only covered the very basic of what is possible to do with Travis. You can also use Travis to upload documentation or compiled binaries following a successful test, measure code coverage and much more. If you have any questions about the use of Travis please do get in touch via Email.