This app note provides information on how to use Riviera-PRO in batch mode using JenkinsвЂ™s tool for Linux. 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.
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.
Figure 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 8 is recommended. Follow the steps below to download and run Jenkins.
Open a terminal in the same directory where Jenkins is stored and run jar -xvf jenkins.war.
Browse to http://localhost:8080 and follow the instructions to complete the installation.
We will go step-by-step to understand the execution of the Riviera-PRO example using Jenkins.
Upon entering the username and password you will be directed to the user home screen.
Figure 2: Welcome to Jenkins
To manage Jenkins, click on the Manage Jenkins option from the left-hand menu side. By doing so, users can get various configuration options for Jenkins.
Figure 3: Manage Jenkins
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.
Adds, removes or disables/enables plugins that extends the functionality of Jenkins.
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.
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.
It is a convenient way to view the Jenkins log files in real time. It is used for troubleshooting.
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.
Click on New Item on the left-hand side of Dashboard.
Figure 4: New Item
Click Freestyle project.
Once the item name has been finalized, the configuration window opens up as shown below.
Figure 5: Item Configuration
Inside, the configuration window, click Build Triggers tab.
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 them. Different steps are: Execute Windows batch command, Execute Shell, and Invoke top-level Maven targets. In our case, because we are using the Linux to invoke Riviera-PRO, we will choose the option "Execute Shell". As soon as we select it, the following window opens.
Figure 6: Build Window
Inside the command window, we call the setenv file to set the environment variable of Riviera-PRO.
Next, we provide the command "sh" to execute the vsimsa file.
sh ./vsimsa -do /edatools/Aldec/Riviera-PRO-2020.10-x64/examples/coverage/coverage_database/keyboard_controller/src/runme.do
Below are the script commands that would be executed when the build occurs.
Figure 7: Script Commands
Next, click Save.
Click Build Now.
Under Build History, click on the most recent build. It will invoke the batch mode tool and execute the script. Inside Jenkins, if your build is successful, you shall see following Console log and the following Riviera-PRO console log.
Figure 8: Console Output
Figure 9: Riviera-PRO Script Execution
Go to your home directory where the script is stored. The simulation database will be stored there.
Note: If you want the html files to be created for the coverage results, you can include its commands in the script that you execute.
Figure 10: Cumulative Coverage Results
Figure 11: Test 1 Results
Figure 12: Test 2 Results
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.
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.