Description: This tutorial explains how to set up a code analysis using the tool QA-C++.

Tutorial level: ADVANCED

Set up QAC++ on a new system

Download and install QA-C++

Download/unpack installation files and create link to "...-current" folder. Using such links is convenient to integrate new versions of QA-C++. If you need to upgrade an existing system change the link to the current installation folder.

Installation:

• QACPP-x.x.x-.tar: Covers QAC++ programm (--> qac++-current):

• wrapper-x.x.tar: Used to perform analysis and compilation (--> wrapper-current)

• Reprise-x.x.tar: Reprise license server
• prlgcc.zip: Programm to create compiler-personality-file:
• (QAR-x.x.tar: QA-Report)

Download:

• QAC++-3.0.1

• Wrapper-3.1

• Reprise-9.0

• prlgcc-4.1

Remark:

• If you're using a 64-bit system install 32-bit-libs which are necessary for QA-C++

sudo apt-get install ia32-libs

Configure QAC++

Create compiler personality file

Create compiler-personality-file using prlgcc:

cd ~/prlgcc
mkdir personalities
./prlgcc.pl QACPP -pe /home/_USER_/prlgcc/personalities

Now, open the created personality file and add following lines to the top:

-SD "<feff>="

-SD GTEST_HAS_TR1_TUPLE=0
-SD GTEST_USE_OWN_TR1_TUPLE=1

Modify header file

Now, open prlg++.h

cd ~/prlgcc/personalities/prlforceinclude
gedit prlg++.h

and change line

extern "C" void* memset(void*,int,unsigned int);

to

extern "C" void* memset(void*,int,PRQA_SIZE_T);

Wrapper settings

Firstly, switch to the wrapper-installation-folder and copy the wrapper-config-file twice, one for C-file- the other for C++-file-analysis.

cd ~/wrapper-current
cp wrapper_unix.cfg wrapper_qacpp.cfg
cp wrapper_unix.cfg wrapper_qac.cfg

Configure the wrapper_qacpp.cfg:

• Set COMPILER_SETTINGS_FILE=/home/_your_user_/prlgcc/personalities/_your_personality_file_
• Set ANALYSER=QACPP
• Set ANALYSER_BASE=/home/_your_user_/qacpp-current
• Set FILELIST=filelist.lst
• Set STOP_ON_FAIL=0 (or 1: If set to 1, the analysis/compilation will stop as soon as an level 9 error occured)

**Secondly, in version wrapper-3.1 you have to alter some lines of code. Thus, open the file wrapper.pl and uncommand line 1013 - 1018:

cd ~/wrapper-current
gedit wrapper.pl

Reprise settings

Move your current license-file into the Reprise installation folder.

mv _your_license_file_ ~/Reprise

Create profile

Switch to the QA-C++ installation folder, create and modify the profile:

cd ~/qacpp-current
./install.qac++

Now, a profile was created inside the QA-C++ installation folder. Open the file and modify line

QACPPPATH=/home/user/qacpp-3.0.1-R; export QACPPPATH

to

QACPPPATH=/home/user/qacpp-current; export QACPPPATH

Common settings

Disable sudos password-request to prevent interrupts during updates. Type

sudo visudo

and change line

"%admin ALL=(ALL) ALL"

to

%admin ALL=(ALL) NOPASSWD:ALL

Use the chroot with various linux distributions

If you use the jenkins_tools to run analysis with different linux distributions which differ from your system-distro, additional steps are required:

• See step 2.1/2.2: For each Linux distribution the personality file hast to be created separately. Therefore, install the prlgcc on the proper distribution and name the folder "prlgcc_DISTRO", whereas DISTRO represents the linux distribution name. Afterwards copy this folder to your system where the analysis will be execute. Do not forget to modify the additional personality files according the instructions in 2.1/2.2. Also open the personality file and replace all paths that include a username. Make sure your username is used. To pretend this step, create the "prlgcc_DISTRO" under the same username as you have. The paths within the personality file will contain the correct username then.
• See step 2.3: Create additional wrapper-config-files for each distribution and name them "wrapper_qacpp_DISTRO.cfg".

Section 'Set up Jenkins_tools':

• See 3.2: Create for each wrapper-config the wrapper-script and name them "wrapper_g++_DISTRO". Make sure, that you refer to the proper wrapper-config-file.
• See 3.3: Create a subfolder for each rostoolchain and name them rostoolchain_DISTRO.

Set up Jenkins_tools

Firstly, follow the installation instructions for QA-C++.

Install Jenkins_tools

Install the debian package:

sudo apt-get install python-jenkins-tools

Create a file which is called pbuilderrc in your home directory. Make sure that you use the correct user-name instead of '_your_user_'.

sudo sh -c 'echo "MIRRORSITE=http://apt-mirror/packages/ubuntu" > /home/_your_user/.pbuilderrc'

• That creates a pbuilderc-file in your home directory including the appropriate mirror. If you want to add mirrors modify this file.

Use own jenkins-server

If you want to use your own jenkins server follow the instructions below.

Set up Jenkins

Install and run

wget -q -O - http://pkg.jenkins-ci.org/debian/jenkins-ci.org.key | sudo apt-key add -
sudo sh -c 'echo deb http://pkg.jenkins-ci.org/debian binary/ > /etc/apt/sources.list.d/jenkins.list'
sudo apt-get update
sudo apt-get install jenkins

Jenkins uses port 8080 by default. Make sure that no other process is using it. Alternatively, change the default port.

Now, you have access to your own jenkins-server:

http://localhost:8080

Configure

To sign in as an user jenkins need to be configured. Go through the following links and check the appropriate boxes:

• Go to "Manage Jenkins"
• Go to "Configure System"
• check "Enable security"
• in Access Control check "Jenkin's own user database" and "allow user's to sign up"

Now, create your own user. Go to the start page and click on the "sign up"-button in the top right corner.

Set up own jenkins_tools

Clone from git

To use your own jenkins_server the jenkins_tools-scripts need to be changed occasionally. Therefore it is necessary to run an own modified version of jenkins_tools.

Clone the jenkins_tools from github:

git clone https://github.com/ros-infrastructure/jenkins_tools.git

• REMARK: The installation of the debian package of jenkins_tools is also necessary (see above).

Configure

• To use the modified version change your path in shell:

export PATH=_path_to_cloned_jenkins_tools/:$PATH

• Open the file chroot_dispatch.sh and replace the git-repository:

cd /scripts/
gedit chroot_dispatch.sh

Change

git clone http://github.com/ros-infrastructure/jenkins_scripts.git

to

https://github.com/bosch-ros-pkg/jenkins_tools.git

• Open file run_jenkins.py and replace the jenkins_server_address:

cd /src/jenkins_tools/
gedit run_jenkins.py

Change

JENKINS_SERVER = 'http://jenkins.willowgarage.com:8080/'

to

JENKINS_SERVER = 'http://localhost:8080

• Set destination folder for results on server. Open file push_results_to_server.py and change line

ROS_WIKI_SERVER = 'ubuntu@ec2-184-169-231-58.us-west-1.compute.amazonaws.com:~/doc'

to

ROS_WIKI_SERVER = 'your wiki-server'

Setups

Create mount folder

Switch to your home-directory and create a folder called chroot_configs

mkdir chroot_configs

This folder will be mounted during the execution of the chroot environment. It should contain following files and subfolders:

• keypair.pem (ssh keypair for uploading analysis results to wiki server)

• rostoolchain.cmake (see below)

• wrapper_g++ (see below)

• qaverify.yaml (see below)

• set_qacpp_path.sh (see below)

To set the QA-C++ path inside the chroot-environment we use a shell script called set_qacpp_path.sh. Create this file and add following content.

#!/bin/sh

# QA-C++
source $HOME/qacpp-current/.profile
export PATH=$PATH:$HOME/qacpp-current/bin

# QAVerify
#export PATH=$PATH:$HOME/qaverify-current/server/bin
#export PATH=$PATH:$HOME/qaverify-current/client/bin

# QA-C++ GNU Make Wrapper 
export PATH=$PATH:$HOME/wrapper-current

Make script executable:

chmod 755 set_qacpp_path.sh

Create wrapper_g++

The following files should be push to the "chroot_configs" folder (see Setup Jenkins_tools subsection 3. Setup).

Create a shell script called wrapper_g++ and add the following content.

#!/bin/bash
$HOME/wrapper-current/wrapper.pl -wcf $HOME/wrapper-current/wrapper_qacpp.cfg g++ $@

Make executable:

chmod 755 wrapper_g++

Create rostoolchain.cmake

Create a file called rostoolchain.cmake which refers to the wrapper_g++ file. Add follwoing content:

set(CMAKE_CXX_COMPILER _path_to_wrapper_g++_/wrapper_g++)

* In combination with jenkins_tools no ROS installation is required on your system. Therefore you can skip the next step if you use the jenkins_tools only!

* Move this file to the ros-folder.

sudo mv rostoolchain.cmake /opt/ros/electric/ros/rostoolchain.cmake

Create server.yaml

You need to provide authorization data to access the jenkins server. Therefore create a yaml-file called server.yaml

url: 'your_url'
username: 'your_user'
password: 'your_password'

• Note: The url is not used inside the jenkins_tools, but is fixed to the willow garage server. If you want to use your own jenkins server you need to modify the script "run_jenkins.py". Refer the global variable JENKINS_SERVER to your server-path.

Move this file to the appropriate path. If the path doesn't exist create it:

mv server.yaml ~/.ros/catkin-debs/

Create qaverify.yaml

You need to provide authorization data to access the qaverify server. Therefore create a yaml-file called qaverify.yaml

user: 'your_user'
password: 'your_password'

Move this file within the chroot_configs-folder.

*Fix bug in pbuilder

If you are using lucid a bug in pbuilder need to be fixed. In Precise the bug would have fixed already.

Download the appropriate patch and run it. You can find more details to that topic and the patch-file under this link: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=627086 (Search for: pbuilder_slashrunfix.diff)

Run Jenkins_tools

Start license server

Firstly, start the Reprise license server. Switch to the Reprise installation folder and start rlm.

cd ~/Reprise
rlm

The server has to run during the analysis otherwise the it will fail.

Run script locally

Before you start a job on jenkins you can run the script locally to check weather your script is working. Therefore you need to create a workspace folder:

cd
mkdir workspace_jenkins

Use this command:

run_chroot_local 'ubuntu_distro' 'arch' 'workspace' 'script' 'stack/meta-package' 'build_system'

Example:

run_chroot_local lucid amd64 $HOME/workspace/ code_quality_analysis electric turtlebot dry

Run script on jenkins

To run a job on jenkins use this command:

run_chroot_jenkins_now 'ubuntu_distro' 'arch' 'email' 'script' 'stack/meta-package' 'build_system'

Example:

run_chroot_jenkins_now lucid amd64 best_email@ever.com code_quality_analysis electric turtlebot dry

Analysis independent from Jenkins

If you want to run the analysis on your ROS stack/metapackage without having a repository accessible by all ROS community members and therefore not listed within the *.rosdistro file, please follow these instruction.

Install QA-C++

Firstly, make sure that you have QA-C++ and it's components (including wrapper) installed, if you don't follow the instructions in section "1. Download and install QA-C++".

Configure wrapper

Follow the instruction in subsection "2.3 Wrapper settings"

Create wrapper_g++

Generally, the "wrapper_g++"-file can be created in any folder. But you should create the file inside the wrapper installation folder, if you don't have occasion to do it otherwise.

Create a shell script called wrapper_g++ and add the following content.

#!/bin/bash
$HOME/wrapper-current/wrapper.pl -wcf $HOME/wrapper-current/wrapper_qacpp.cfg g++ $@

Make executable:

chmod 755 wrapper_g++

Create rostoolchain.cmake

The "rostoolchain.cmake" has to be pushed into the ROS_ROOT folder. This folder changes with the distribution of ROS:

• Groovy/Fuerte: opt/ros/(groovy or fuerte)/share/ros
• Electric/Diamondback: opt/ros/(electric or diamondback)/ros

Create a file called rostoolchain.cmake which refers to the wrapper_g++ file you have created before. Add follwoing content:

set(CMAKE_CXX_COMPILER _path_to_wrapper_g++_/wrapper_g++)

Test analysis

After you have followed the steps before the analysis will be performed every time you use "rosmake" to build your stack.

Example

This example performs the analysis on stack "filters" using electric.

In your electric workspace folder clone the source code of the stack:

cd ws_electric
hg clone https://kforge.ros.org/common/filters

After that, switch to the stack's folder and type:

cd ~/ws_electric
cd filters
rosmake --pre-clean

• the --pre-clean option takes care of older cmake-files which prevent that the analysis is performed in case of calling rosmake twice without changing any source code.

Message Browser

The .i, .met and .err files created from QA-C++ are located within the build folder, for instance:

cd build/CMakeFiles/transfer_function.dir/src

Open the message browser using the command line:

viewer QACPP -list filelist.lst

You should now see the messages created by QA-C++.

QAVerify

To use QAVerify execute following lines. Make sure you use your variables instead of the placeholder in the commands!

#Phase 1: Transform data to internal file format

qaimport QACPP -po qav::code=all -po qav::output=/snapshots/NAME.qav qav::prqavcs=$HOME/qaverify-current/client/bin/prqavcs.xml -list PATH_TO/filelist.lst

#Phase 2: Upload to QAVerify

upload -prqavcs $HOME/qaverify-current/client/bin/prqavcs.xml -host localhost -user XXX -pass XXX -db PROJECT_NAME -prod QACPP /snapshots/NAME.qav