Using Riviera-PRO in Batch mode using Jenkins Software-Github Collaboration

Introduction

This app note provides information on how to use Riviera-PRO in batch mode using Jenkins-Github tool collaboration. To understand the whole process, we will go through the explanation of all the important segments. To get started, let us understand the tool Jenkins first.

What is Jenkins?

Jenkins is a self-contained, open source automation server which can be used to automate all sorts of tasks such as building, testing, and deploying software. Jenkins can be installed through native system packages, Docker, or even run standalone by any machine with the Java Runtime Environment installed. It is a powerful application that allows continuous integration and continuous delivery of projects, regardless of the platform you are working on. It is an open-source application that can handle any kind of build or continuous integration. You can integrate it with a number of testing and deployment technologies.

Why Jenkins?

Jenkins is a software that allows continuous integration. Jenkins will be installed on a server where the central build will take place. The following flow chart demonstrates a very simple workflow of how Jenkins works.

Fig 1- Jenkins Flowchart

What is Continuous Integration?

Continuous Integration is a development practice that requires developers to integrate code into a shared repository at regular intervals. Continuous Integration requires the developers to have frequent builds. Common practice is that whenever a code commit occurs, a build should be triggered. The standalone Jenkins distribution requires a minimum of Java 7, though Java 8 is recommended. Follow the steps below to download and run Jenkins.

Download Jenkins
Open up a terminal window in the same directory where Jenkins is stored and run "java -jar jenkins.war"
Browse to http://localhost:8080 and follow the instructions to complete the installation.

Jenkins-Git-Riviera-PRO Regression Testing:

We will go step by step to understand the execution of Riviera-PRO example using Jenkins-Git.

1] Creating Repositories in Github:

Go to Github.com - create your account and click on New Repository.
Give a name to your repository. Keep it Public or private as per your need.
Click on Create Repository. You will be directed to a branch called "master"
Assuming you already have your design files prepared, upload them using "Upload Files" option.
After uploading the necessary files, click on "Commit Changes".
For several people working on a single design, you can create separate branches and hence whenever the design has been modified from the original one called "master", you can pull the request and bring those changes to "master" and avoid the extra hassle.
Once you are done going through all of above, click on "Clone or Download" and copy the link of the repository representing appropriate branch. There is a subtle use of that link, which we will see in Jenkins part.

2] Jenkins - Git Collaboration:

Fig 2 - Jenkins Home Screen

On entering the user id and password, you will be directed to the user home screen.

Fig 3 - On logging in

Jenkins-Git Setup

For this, click on "Manage Jenkins" option on the left hand side. In the next screen, click on "Manage Plugins".

Fig 4 - Manage Jenkins

Manage Plugins adds,removes or disables/enables plugins that extends the functionality of Jenkins. Click on it to check if the Github plugin is already installed. The Git plugin allows use of Git as a build SCM(Software Configuration Management) including repository browsers for several providers. A recent Git runtime is required as a pre-requisite.Interaction with the Git runtime is performed by the use of the JENKINS:Git Client Plugin which is only tested on official Git client. After having checked that, go back to "Manage Jenkins" option and click on "Global Tool Configuration". In the Global Tool Configuration, Click on Git Installations and provide the path to Git executable located in your directory. If you have not downloaded the Git executable yet, go to https://desktop.github.com/ and download GitHub desktop version for your appropriate OS. Once downloaded, go to https://github.com/ , create your profile and sign up. Click on "New Repository".

Jenkins Management

To manage Jenkins, click on the "Manage Jenkins" option from the left hand menu side. By doing so, user can get various configuration options for Jenkins by clicking it. We will discuss some of the management options .

Configuration System

This is where one can manage paths to the various tools to use in builds, such as the JDKs, the versions of Ant and Maven, as well as security options, email servers and other system-wide configuration details. Jenkins adds the required configuration fields dynamically after the plugins are installed.

Reload Configuration from Disk

Jenkins stores all its system and build job configuration details as XML files which is stored in the Jenkins home directory. The build history is also stored in the Jenkins home directory. If you migrate build jobs from one Jenkins instance to another, or archiving old building jobs, you will need to add or remove the corresponding build job directories to Jenkins's builds directory. One can simply use the "Reload Configuration from Disk" option to reload the Jenkins system and build job configurations directly.

System Information

This screen displays a list of all the current Java system properties and system environment variables. Here once can check exactly what version of Java Jenkins is running under and all.

System Log

It is a convenient way to view the Jenkins log files in real time. It is used for troubleshooting.

Load Statistics

It displays graphical data on how busy the Jenkins instance is in terms of the number of concurrent builds and the length of the build queue which gives an idea of how long your builds needs to wait before being executed and all. These statistics can give a good idea of whether extra capacity or extra build nodes are required from an infrastructure perspective.

Prepare for Shutdown

If there is a need to shutdown Jenkins, or the server Jenkins is running on, it is best not to do so when a build is being executed. To shut down Jenkins cleanly, user can use the Prepare for Shutdown link, which prevents any new builds from being started.

Next, the Global Tool Configuration as discussed previously, tells as whether we have the Git installed on our PC or not.

Fig 5 - Global Tool Configuration

Make sure that you have defined the path to Git executable in the Global Tool Configurations.
Click on "New Item"

Fig 6 - Item name declaration

Once the item name has been finalized, the configuration window opens up as per below.

Fig 7 - Item Configuration

Inside the configuration window, go to Source Code Management. Click on Git. As soon as you click on Git, Repository URL and Branches to build options will be available as below. In the Repository URL, paste the link you copied from Git Repository. In the Branches to build bracket, put the name of the branch you want. By default it will be "master".

Fig 8 - Source Code Management

Next, because we want to keep the regression testing automated, we need to tell Jenkins, at what time intervals we want it to check the repository if it has been changed by someone. Thus, the biggest advantage of Jenkins lies in this point. If several team members are working on a single design and because it would become too critical and cumbersome to find out what changes were made to design, Jenkins provides an approach to check repository at specific time intervals so that whenever a change has been made , a build will be triggered. In the below example, we have provided the cron syntax- each line consists of 5 fields separated by whitespace.

Fig 9 - Build Triggers

Next, Jenkins provides the build step through which it runs tests. It provides different support levels inside build step so that user can go through one convenient to him/her. Different steps are: Execute Windows batch command, Execute shell, Invoke Ant, Invoke Gradle script, Invoke top-level Maven targets, Run with timeout, Set build status to "pending" on Github commit. In our case, because we are using the batch command file to invoke Riviera-PRO, we will choose the option "Execute Windows batch command". As soon as we choose it, following window opens.

Fig 10 - Build Window

Inside the command window, we call the setenv.bat file to set the environment variable of Riviera-PRO. Next we provide the batch command "start" to execute the vsimsa.exe file . Usually whatever script we want to execute, we provide it along with the batch command that runs the vsimsa.exe file. For example, start C:\Aldec\Riviera-PRO-2016.06-x64\bin\vsimsa.exe -do C:\Aldec\Riviera-PRO-2016.06-x64\examples\coverage\coverage_database\keyboard_controller\src\runme.do

Below is the script commands that would be executed when the build occurs.

Fig 11 - Script Commands

Next save the configuration window settings and click on "build". It will invoke the batch mode tool ,with executing the script. Inside Jenkins, if your build is successful, you shall see following Console log.

Fig 12 - Jenkins Console Log

Fig 13 - Riviera-PRO invoked/Script Execution Batch mode

Go to your home directory where the script is stored. The simulation database would be stored there. If you want the html files to be created for the coverage results, you can include its commands in the script that you execute.

Fig 14 - Cumulative Coverage Results test1.html

Fig 15 - Coverage Results test2.html

Fig 16 - Coverage Results merged.html

Now because we have kept the build triggers to keep checking the repository every minute if there has been a change made to the design files in repository, it will keep checking continuously. If a change is made, from adding a new file to changing a line of code in one of several files inside repository, build will be triggered. Jenkins will re-run the test and provide new simulation database.

Advantages of Jenkins

Jenkins is a Continuous Integration Server.
This has the tremendous advantage of always knowing if all tests work and getting fast feedback. The fast feedback is important so you always know right after you broke the build (introduced changes that made either the compile/build cycle or the tests fail) what you did that failed and how to revert it.
If you only run your tests occasionally the problem is that a lot of code changes may have happened since the last time and it is rather hard to figure out which change introduced the problem. When it is run automatically on every push then it is always pretty obvious what and who introduced the problem.
CI is a process that most developers follow to keep their code base intact. It's mostly a common practice when you work in a group environment. For example, an analogy for this would be constructing a new home. There will be multiple contractors working on the site. So, if we have installed the window glasses and the paint person comes in and paints the house there are high chances that he will drop some paint on the glasses or end up breaking the glass. So, the inspector comes and checks it every day to see if something broke. The same process is applied for constructing a new code. CI system gathers all your code from different engineers and makes sure it compiles and builds fine.

References:

[1] Jenkins Official Website https://jenkins.io

[2] Github Official Website https://github.com/

[3] Jenkins Tutorial http://www.tutorialspoint.com/jenkins/

Disclaimer:

Many of the text in this application note were extracted from the referenced sources (Jenkins.com) regarding the open-source tools they provide. The intention of this application note is to consolidate and organize the data and present a simplified tool flow for the benefit of Aldec users.