Travis and Coveralls integration

Setup

We'll be adding TravisCI and Coveralls integration to a Boost library. Let's take a Boost.LexicalCast as an example. At the end we'll get ​something like this.

Travis requires some access permissions to the repository that are usually provided by Boostorg Admins. However bothering Admins is actually not required:

• go to the Boost project page (in our example it would be ​https://github.com/boostorg/lexical_cast)
• press the "Fork" button at the top right corner. Now you have a copy of the boost project in your account.
• clone the original boostorg repo or use an existing clone. Change directory to the clone folder (cd boost_maintain/boost/libs/lexical_cast/)
• add our forked repo as another remote host for default push: git remote set-url --add origin git@github.com:<your_login>/lexical_cast.git. If everything is right, you'll see something like this if you execute git remote -v:

  origin	git@github.com:boostorg/lexical_cast.git (fetch)
  origin	git@github.com:boostorg/lexical_cast.git (push)
  origin	git@github.com:<your_login>/lexical_cast.git (push)
  

• log in into ​Travis
• go to the ​https://travis-ci.org/profile/ and enable builds for the forked project.
• log into ​Coverals.
• go to the ​https://coveralls.io/repos/new and add a forked repo.

• now add the .travis.yml file, tune the README.md and commit changes:

  cp ../variant/.travis.yml ./                                 # Copying .travis.yml from Boost.Variant
  sed -i 's/IGNORE_COVERAGE=.*/IGNORE_COVERAGE=/g' .travis.yml # Reseting files to ignore in coverage tests report
  git add .travis.yml                                          # Adding .travis.yml for next commit
  
  cp ../variant/README.md ./                                   # Copying README.md from Boost.Variant
  sed -i 's/variant/lexical_cast/g' README.md                  # Replacing `variant` with `lexical_cast`
  sed -i 's/apolukhin/<your_login>/g' README.md                # Replace `apolukhin` login name wuth your own login name
  gedit README.md                                              # ... editing README.md in editor
  git add README.md                                            # Adding README.md for next commit
  
  git commit -m "Travis and Coveralls integration"             # Committing changes to GIT
  git push                                                     # push changes to boostorg and forked repo using one command
  

That's it! If everything is done right, you'll see the build process going on TravisCI and after ~20 minutes results will be visible in README.md view on github.

Coveralls tuning

Investigating the results

After successful run of TravisCI and Coveralls we'll see tests coverage results displayed in README.md view on github. Time to investigate the results!

• click on the results ​https://coveralls.io/r/apolukhin/lexical_cast?branch=develop
• click on the build number to see detailed coverage description
• click on the source file you wish to investigate

Setting sources location

Chances are high, that Coveralls will fail to automatically detect source location. In that case you need to

• set "Git repo root directory:" to /home/travis/boost-local/
• set "Git repo sub directory: :" to include/ (or src/ in case of a source file in src/ folder)

If everything is done right you'll see the source file with highlighted lines. Green lines are covered by tests, red lines are in binary file and are not covered by test, gray lines are not in a test's binary file (there's no code in tests that uses/compile that line).

Ignoring specified files coverage

Sometimes files from other projects could appear in coverage reports. To disable those files edit .travis.yml file and set IGNORE_COVERAGE= to files that must be ignored. IGNORE_COVERAGE variable understands wildcards, so you could disable files just like this:

    - IGNORE_COVERAGE='*/boost/progress.hpp */filesystem/src/path.cpp */numeric/conversion/converter_policies.hpp'