GitHub: Continuous Integration with Travis CI

worker

cs CZE

Travis CI is a Continuous Integration solution, available to the GitHub users out of the box. In particular, it provides build and unit test automation, triggered on each push or pull request. The results can be reported to one or more e-mail addresses or on the project site. The free version of Travis CI is available for public GitHub repositories, there also exists a paid version which can be used for private GitHub repositories. This makes the tool very suitable for Open Source projects hosted on GitHub.

Quicklinks:

Supported systems, languages and tools

Travis CI provides support for multitude of programming languages, including C++, Java, Ruby, Perl, Python, PHP, Scala etc. The article is further focused on C++ projects, for information about other languages please refer to the Travis CI Languages documentation.

The standard operating system run by the build workers is Linux, although there is some activity to also provide multi-OS support (Mac OS X builders).

For C++, the officially supported build tools are make, CMake and SCons; but in the fact it is possible to run any command or script to initiate the build, and to install any tool you need to build the project (e.g. via apt-get or wget), thanks to the pre-script configuration: For example, you can fetch Boost library to the builder node and use Boost.Build (b2/bjam) to build.

Signing up to Travis CI

To start using the Travis CI service, you first need to sign in with your GitHub credentials. On the page https://travis-ci.org/, press the “Sign in with GitHub” link in the upper right corner of the page:

Travis CI: Sign in

Sign in the Travis CI

If you are not logged in the GitHub, the GitHub login page will ask to enter the login name and password. Once you are logged in the GitHub, it will ask to authorize the Travis CI application to access your GitHub profile. You need to click on “Authorize application” to start using Travis CI:

Travis CI: Authorize

Authorize Travis CI to access GitHub

The Travis CI application needs access to retrieve the commit information and to install Git hooks, which will trigger the start of automatic build after each push to GitHub or a after a pull request.

Enable Travis CI for a project

Before starting to use the Travis CI for a particular project, the project needs to be enabled in the Travis CI configuration. To enable a project, open the Profile page ( https://travis-ci.org/profile/ ). There you can enable or disable individual projects by pressing the “On/Off” button. If you do not see a new project in the list of projects, synchronize the project list with the GitHub account by pressing the “Sync now” button:

Travis CI: Enable a project

Enable a project in Travis CI

Create the Travis CI script (“.travis.yml”)

The Travis CI build is driven by ".travis.yml" file, looked up in the root of the project Git repository. You need to provide that file and push it with the next commit, so that the Travis CI application will know, what do you actually want it to do when the automated build is triggered. That means, the ".travis.yml" file is then part of the project and can be tracked by Git the same way as any other file in the project.

This is an example of some basic Travis CI configuration for C++:

language: cpp
compiler:
  - gcc
  - clang
script: make && make test
notifications:
  email:
    recipients:
      - user1@somewhere.com
      - user2@somewhere.com
    on_success: change
    on_failure: always

This configuration provides the following functionality:

  • set the programming language to C++
  • build with both gcc and clang compilers – the compiler command for the particular build job is set into the "$(CXX)" environment variable
  • the command to start the build in the “script” setting (you can run any commands or scripts, as long as they are available either on the Travis CI builder or in the Git repository)
  • notification options: send notification e-mails to the specified e-mail addresses for each failure and once the failure is recovered

Further information about these options:

Before pushing the new change containing the ".travis.yml" file to GitHub (and after each change of the file), it is highly recommended to check the correctness of the file by the Travis WebLint validator.

Now the new commit with the ".travis.yml" file can be pushed to GitHub to start the automated build.

Inspection of the build results

The results of the last automated build can be checked on the Travis CI home page:

Travis CI: Last build

Travis CI: Last build

It takes some time until the build is started (usually it is scheduled within minutes). You can click on a particular project to see the status of the project, or use the tabs to browse the build history, pull requests etc.

You can click on the particular build job to see the flow of the build task (this is especially needed in case of build failures):

Travis CI: Build job

Travis CI build job

The build result status can be linked to, for example in the projects "README.md" file. You can get the URL of the build status image after clicking on it in the upper right corner (note that the image link is project and optionally branch specific). You can select various formats of the link, including Markdown, from the list box on the left:

Travis CI: Build result link

Link to Travis CI build result image

Examples

Some examples of Travis CI builds are available on my GitHub/Travis CI profiles:

Advanced Travis CI usage

Use of Boost

To use the Boost library in a C++ project, there are principally two options:

  1. Re-distribute the Boost library within the source code.
  2. Use the Boost library installed in the system.

The option 1. has some advantages (you can be sure that the project will always build with the version of Boost distributed with the project), but also some disadvantages (the build will generally take much longer, you will also need to script the build of the Boost in scope of the project build process, and it will put more stress on the Travis CI nodes – the build always starts in a new clean virtual sandbox, where everything needs to be build from scratch).
If the first option is what you want, you might also consider use of the official Boost.org Modular Boost repositories available on GitHub (they can be directly used as Git submodules).

I’ll only go into the second option in greater detail, as that is the option I normally prefer.

For the build on the local machine, you can have the Boost library installed somewhere in the system. For example, under Ubuntu Linux this can be easily done by calling:

$ sudo apt-get install libboost-dev

As you might already guessed, the Boost library is not available on the Travis CI worker nodes by default. It needs to be installed in the scope of the task by putting the install commands into the ".travis.yml" file (either into “before_script” or “before_install” steps). The Travis CI Linux nodes run the Ubuntu Linux distribution, thus the Boost packages can be installed by using the "apt-get" command as above.

The recommended option is to only install the Boost modules necessary for the actual project by adding the following lines to the ".travis.yml" file:

before_script:
  - sudo apt-get update -qq
  - sudo apt-get install libboost-thread-dev libboost-system-dev libboost-test-dev

That will install Boost.Thread, Boost.System and Boost.Test modules (if the project does not use Boost.Test module, the “libboost-test-dev” package should be removed from the line).

Or you can install the default (“usual”) Boost modules by:

before_script:
  - sudo apt-get update -qq
  - sudo apt-get install libboost-dev

Or all Boost modules by:

before_script:
  - sudo apt-get update -qq
  - sudo apt-get install libboost-all-dev

Note that the first option (installing the required modules only) should be preferred in general. Not only it puts less stress on the build nodes (which need to download and install the packages into the virtual machine within every build job), but it will also result in faster builds (for the very same reason).

To see an example of project build with Boost usage, you can take a look at the https://github.com/emaskovsky/coding-puzzle-brackets project on my GitHub profile, which is using Boost.Thread, Boost.Asio and Boost.Test modules.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s