What's all this Jenkins stuff anyhow? (Part 2)

In part 1 of this blog, we took a quick look at the key elements of a Continuous Integration (CI) platform and reviewed some of the software required to make this a useful tool for the embedded developer. Specifically we focussed our attention on Jenkins, but much of what we discussed is relevant to Hudson, Bamboo and many other CI platforms that are available on the market.

In this post we are going to go into more detail regarding how a project is actually configured in Jenkins and what you need to consider.

On the main Jenkins page, there is an entry named "New Item" on the left hand side. Clicking here takes you to a page where the new project can be named and assigned a "project type". Our focus here will be on a "Freestyle Project" (Figure 1) which allows us to create a simple project that can download our code from our repository and check the project builds as expected. It is worth noting that, once you have one or more projects on the system, you can use them as templates for a new project - just scroll down a little further and use the text-entry field "Copy from" (Figure 2).

From here, there are a series of fields that are grouped into various topics that you need to fill in. The names are listed across the top of the browser window and stay there as you scroll down, with the current group highlighted in bold type. The groups are as follows:

• General - Mostly meta data regarding your project (name, description)
• Source Code Management - Configuration of access to the repository where your code is installed
• Build Triggers - What should trigger a build of your project
• Build Environment - What to do if the build gets stuck for any reason
• Build - The rules to actually build your project from the source code
• Post-build Actions - What to do once the project build process is complete.

One of the biggest challenges of using such a platform is understanding what to fill in and where, so we'll provide you with some screen shots of how we have been using it. The project itself is very simple and is hosted on BitBucket. The application code is essentially an Arduino sketch that implements a thermostat.

General - Here we can modify the name of our project if so desired. It is also valuable to add a description, especially if you have several builds that differ only in their use of compiler switches for testing purposes. The results of builds are kept from one time to the next, but to delete those old builds you can tick the appropriate box. Another useful check-box here is the "Disable this project" for when you want to disable, rather than delete, test projects or projects that are not fully configured. Don't overlook the '?' symbol on the right hand side of the page - the help is very well written and successfully explains most functionality.

Source Code Management - This section allows us to tell Jenkins where to find the code that belongs to our project and the type of repository we are using. Our BitBucket repository is implemented using git. Just provide the URL to the project (typically highlighted on the web page of your repository), add your credentials and the branch to use and you're ready to go!

Build Triggers - This determines when, and how often, the project is going to be built and what will trigger the build. We have been using the scheduler which is configured to trigger Monday to Friday between 0900 and 1859 up to 5 times a day. The schedule is described using a format very similar to cron. If you haven't used cron, the help provides a good overview of how to set up the scheduler with some examples.

Build Environment - Yes, sometimes things go wrong, but that shouldn't bring the whole house of cards tumbling down too. Our experience has shown that, with this very simple project, the most likely problem is that the code cannot be downloaded from the repository in a reasonable amount of time. The "Likely stuck" strategy uses heuristics to determine if the build process is stuck and, if so, it aborts the process.

Build - Now, with all that behind us, we can concentrate on the process and rules behind actually building our code. Since we're running Jenkins on Windows, we have selected "Execute Windows batch command". The first command uses make to 'clean' our project. This ensures that all source code changes are included in the build. The second command uses make again to actually compile our project, just as if we had done it manually from the command line.

Post-build Actions - At the moment, there is nothing to add here, since Jenkins will automatically report back whether the build succeeded or failed through the dashboard, as shown below:

If you've got this far - congratulations! Now you are able to see if anything has happened to your code base that will stop the project from compiling. This alone doesn't, however, prove whether your code actually does that which you intended it to do…

In our next post we will show how a debugging environment, such as winIDEA, can be linked with Jenkins to download your application code into a target microcontroller as part of the process. In addition, we will be executing Original Binary Code (OBC) tests on the target to make sure the code actually functions as we intended.

In the mean time, Happy BugHunting!