Travis CI

Now that we have fully documented the library, we are ready to add automation. Automation means we don't have to remember to run doxygen, or compile every platform every time. Automation will do this for you after every commit or pull request! You'll make fewer mistakes and get better pulls from the community. We'll be using Travis CI, a very popular and well run Continuous Integration service. You might be wondering - how much is the monthly subscription? Nothing! For open source libraries, you can run travis free of cost at travis-ci.org

(Adafruit pays for the .com version of the service which we use a lot for internal repositories, and we recommend paying for it if you're building anything commercial because it's soooo worth it.)

Sign up for Travis

Use your GitHub login to register for Travis. This is required

Once logged in, you can Sync your account and Search for the repository you want to automate

Flick the switch to turn on Travis for that repository

Nothing will happen quite yet. That's OK! We have to add our Travis config file to the repository

Travis YML

Travis will create a fully new computer image every time and run your shell script instructions to compile the code and document it.

Here is our demo configuration file:

language: c
sudo: false
cache:
  directories:
    - ~/arduino_ide
    - ~/.arduino15/packages/
git:
  depth: false
  quiet: true
env:
  global:
     - ARDUINO_IDE_VERSION="1.8.5"
     - PRETTYNAME="Adafruit FT6206 Arduino Library"
# Optional, will default to "$TRAVIS_BUILD_DIR/Doxyfile"
#    - DOXYFILE: $TRAVIS_BUILD_DIR/Doxyfile

before_install:
   - source <(curl -SLs https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/install.sh)

install:
   - arduino --install-library "Adafruit ILI9341","Adafruit GFX Library"

script:
   - build_main_platforms

# Generate and deploy documentation
after_success:
  - source <(curl -SLs  https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/library_check.sh)
  - source <(curl -SLs  https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/doxy_gen_and_deploy.sh)

And here's what it all means:

language: c This part is easy, we're going to be compiling C / C++ code.
sudo: false means We don't need root on the container (if you don't need it, don't use it!)

# Blacklist
branches:
  except:
- gh-pages

This means we will not perform the full compile/documentation step on when we push to the gh-pages branch. This is so we don't accidentally trigger Travis to run twice after we push the documentation

env:
  global:
- PRETTYNAME="Adafruit FT6206 Arduino Library"

This is the 'nice pretty' name of the library, which will be displayed at the header of the documentation. You must change this to avoid confusion!

        before_install:
- source <(curl -SLs https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/install.sh)
  
  

This step will install Arduino on your virtual computer and set up the board types as well, such as Uno, ESP8266, Zero, Due, etc! It's just a shell script so you can check it out at the URL to see what its' doing

install:
- arduino --install-library "Adafruit ILI9341","Adafruit GFX Library"

This line adds more configuration setup. The text after the - is literally a bash shell command. We're calling the Arduino binary on the command line and instructing it to do stuff like install some libraries. If you do not need to install any libraries or any other configuration steps, just remove these two lines.

script:
- build_main_platforms

This calls a function we created in the before_install step, when we ran that shell script from adafruit/travis-ci-arduino

We have a few different functions, but this one will build for the main platforms we aim to support: Arduino UNO (ATmega328P), Leonardo (ATmega32u4), Zero (ATSAMD21), Due (ATSAMX), and ESP8266

# Generate and deploy documentation
after_success:
  - source <(curl -SLs  https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/library_check.sh)
- source <(curl -SLs  https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/doxy_gen_and_deploy.sh)

Lastly we have two more scripts we run. library_check.sh, at this time, is an empty hook but we hope to add some things like checking format of the library and looking for missing or misformatted lines.  You can remove this.

doxy_gen_and_deploy.sh Is the script that will do the doxygen generation and then push the pages to your gh-pages branch

Don't forget you'll need that empty gh-page branch if you want to have the doxygen pages pushed for you, see earlier in the guide!

Add travis.yml To Library

OK now you are ready! Grab our example travis.yml file from https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/example_travis.yml, rename it .travis.yml and place in your library repository.

Edit it as we explain above, in particular edit the PRETTYNAME variable and change the extra-library-installation line as necessary!

Save, commit and push the new .travis.yml file to your master branch

Checking Status

You can now check out the status of your build by visiting http://travis-ci.org

If you have multiple repositories, they'll appear on the left hand side. Yellow means working, green means pass and red means fail.

Failure/Passes

After every commit you may get an email or notification that Travis failed, or if it succeeded after failing you can get one too

Lets go and check out in the build log avialable at https://travis-ci.org/yourgithubaccount/repositoryname

In this case, you can see we failed to compile the sensorapi.ino demo when running the zero test (SAMD21) due to an #include "avr/delay.h" now we know we need to either #ifdef it out or restructure our code.

Travis builds take 5 minutes or so, so you're best off doing fast iterative tests locally. After you've fixed the bug and tested it locally, commit and push!

This time, with any luck, you'll pass the main compilation tests!

However your CI will probably still fail because we cannot 'push' the documentation to gh-pages so the last thing we have to do is give Travis CI permission to push to our repository

Adding Write Permissions

Log in to GitHub again and visit https://github.com/settings/tokens

Click on Generate New Token

You'll need to set up the scope for this token, give it a nice name (you can have one token per repository or one token for all your repos)

And, if it's a public repo, click public_repo (otherwise you'll need to click all of repo for the access)

Now click Generate Token to get your key, which will be a bunch of numbers and letters. Keep this token safe! It's the same as your GitHub login!

Back in your Travis CI page, go to the Settings for your repository

Scroll down to the Environment Variables section and create a new variable called GH_REPO_TOKEN then paste in the generated token in the box

Make sure that "Display value in build log" is OFF!!!

Save it, your token is now stored safely and securely

Final Run and Check!

Now you can re-trigger a Travis build from the menu

This time, success!

And if you look at your GitHub activity history you will see that 'you' pushed the code documentation in a Travis build

And at github.io you'll see your newly updated documentation!

And in the main repo, our Travis tag says its passing! Congrats, its a little tough the first time to do all these steps but once you get the hang of it, you'll be glad you did it later

Last updated on Jan 18, 2018 Published on Jan 18, 2018