wiki:StandardsChecking/Setup
Last modified 6 years ago Last modified on 01/15/2013 12:37:06 PM

Coding Standards Setup

OBSOLETE C++: Parasoft CPPTEST OBSOLETE

Parasoft is no longer used for standards checking of DM Software. Good product but Project couldn't support the desktop licenses for every developer.

Contrary to original expectations, cpptest will not be available for direct developer use. The cost of the single license CLI interface precludes acquisition of additional CLI-endowed licenses. A motivated developer could acquire a single license for a standalone GUI version. However, the setup for the standalone GUI version is non-trivial. What follows below is the setup for the CLI version. The setup for the GUI version is less automated; it will be documented when the distribution for a GUI-only version is installed.

A single user license is available on the cpptest server hosted on tracer.ncsa.uiuc.edu. Due to cpptest installation constraints, the code operates best under a single user account. In our case, the account is 'buildbot' in honor of the future use of cpptest in automatic standards checking via the nightly build process.

A second license has been purchased for use in generating LSST Standards-compliant Parasoft Rules. It does not have the command line interface to cpptest that buildbot at tracer.ncsa.uiuc.edu has available.

Setup VNC Tracer Access for Buildbot

Tracer is a virtual machine, hosted at NCSA, which itself hosts the Parasoft Standards Checker cpptest. VNC is used to access system: tracer. The following discusses VNC server and VNC client setup.

Account

  • Contact Bill Baker to get your ssh public key installed into the 'buildbot' account on tracer.ncsa.uiuc.edu.

Setup VNC Server

  • Log into 'tracer.ncsa.uiuc.edu' under account 'buildbot'
    • ssh buildbot@tracer.ncsa.uiuc.edu
  • Check if a VNC server is already running for C++Test
    • ps -edalf | grep Xvnc | grep buildbo
  • If there is an existing vnc server running, then note the display number (tracer:#); it will be used when you start up your local vnc client.
  • If you need to start up the VNC server
    • vncserver -geometry widthxheight
      • For example: vncserver -geometry 1910x1100
    • You'll be asked to select a password for the VNC server if it's the first setup. This password will be used by all connecting VNC Clients.
  • For speed VNC startup, use the buildbot@tracer alias: startvnc which sets the geometry to 1270x900.

Stopping the VNC server

  • Ordinarily, leave the vncserver running.
  • Should you want to cleanly terminate the server:
    • vncserver -kill :<display#>
      • For example., for display "tracer:2", use vncserver -kill :2
  • For speed VNC stop, use the buildbot@tracer alias: stopvnc.

Setup local VNC Client

On Unix
  • Using the display number determined in the "Setup VNC Server" section above,
    • vncviewer <host>:<display#>
    • For example, for display "tracer:2", use vncviewer tracer.ncsa.uiuc.edu:2
    • You'll be asked for the password used to setup the VNC server on tracer.ncsa.uiuc.edu.

Sample CLI CPPTEST Use

# initialize LSST software environment
    l            # tracer alias:  'source ~/lsst/stacks/default/loadLSST.sh'

# build working directory tree
    mkdir -p ~/<user>/svnDms      # SVN source
    mkdir -p ~/<user>/cpptestDms  # Cpptest projects repository
    mkdir -p ~/<user>/reportsDms  # Collection directory for Cpptest reports

# extract SVN module, load into your local DMS source directory
    cd ~/<user>/svnDms

# extract SVN source directory, load into its eups module name
#   e.g. daf/base/trunk -> daf_base
    svn co $LSST_DMS/<module>/trunk <eupsModule>  

# prepare for scons build of extracted module;
# eups-setup dependencies for extracted module
    cd <eupsModule>
    setup  -r .  

# using scons, build Cpptest metadata for module
    cd <eupsModule>        
    cppscons   # tracer alias: scons setenv=1 CXX="cpptestscan g++"
    cd ../

# Create an Eclipse project for <eupsModule>
# Load under ~/<user>/cpptestDms/<eupsModule> 
  cpptestcli -bdf ~/<user>/svnDms/<eupsModule>/cpptestscan.bdf \
             -data ~/<user>/cpptestDms \
             -resource "<eupsModule> \
             -config util/CreateProjectOnly \
             -exclude **/*_wrap.cc \
             -exclude **/.sconf_temp/* \
             -exclude **/conftest_*.cpp \
             -report ~/<user>/reportsDms/<eupsModule> \
             -publish

Sample output of cpptestcli

$ cpptestcli -bdf "/home/buildbot/robyn/svnDms/base/cpptestscan.bdf" \
             -data "/home/buildbot/robyn/cpptestDms" \
             -resource "base" \
             -config "util/CreateProjectOnly" \
             -exclude **/*_wrap.cc \
             -exclude **/.sconf_temp/* \
             -exclude **/conftest_*.cpp \
             -report "/home/buildbot/robyn/reportsDms/base" \
             -publish
cpptestcli: Version 7.2.12.45 -- Copyright (C) 2003-2009 Parasoft Corporation
> [0%] Creating 1 project(s) from a build data file...
> [0%] Creating project "base"...
>>    [7%] Creating C Project... Opening 'base'.
>>    [13%] Creating C Project...
>>    [20%] Setting project description.
>>    [60%] Creating link.
>>    [62%] Refreshing '/base/.sconf_temp'.
>>    [79%] Creating link.
>>    [80%] Refreshing '/base'.
>>    [100%] Project "base" successfully created in /home/buildbot/robyn/cpptestDms/base.
> [100%] ...done
> [100%] ...finished, 1 of 1 project(s) successfully created.
> [100%] Done
> [0%] Running: Scope
> [7%] Computing scope
>>    [7%] Initializing
>>    [11%] Refreshing workspace
>>    [11%] Opening 'base'.
>>    [11%] Refreshing workspace
>>    [12%] Refreshing '/base'.
>>    [21%] Refreshing workspace
>>    [21%] Building
>>    [30%] Finding files
>>    [33%] Computing selection for base
>>    [36%] Finding files
>>    [40%] Applying scope filters
>>    [44%] Computing lines to check
> [51%] Preparing options
>>    [58%] Reporting scope results
Total Files: 0
Source Files to Check: 0
Total Source Lines: --
Source Lines to Check: --
Test Data Files: ---
Excluded Files: 0
> [76%] Finished
> [80%] Generating reports
> [100%] Done
[buildbot@tracer robyn]$ 

# Run coding standards test for <eupsModule> 
# Load report under ~/user>/reportDms/]<module> 
  cpptestcli -bdf "~/<user>/svnDms/<eupsModule>/cpptestscan.bdf" \
             -data "~/<user>/cpptestDms" \
             -resource "pex_exceptions" \
             -config "builtin://Parasoft's Recommended Rules" \
             -report "~/<user>/reportsDms/<eupsModule>" \
             -publish\
             -nobuild

# The report will be mailed to the manager (robyn) and the developer
  ....well, that is as soon as 'localoptions' is setup for each developer and 
      then included in cpptestcli usage above

Setup Buildbot CLI access to CPPTEST

Prerequisite: An LSST development environment is assumed to exist on the host system. We have a single license for CLI use of Parasoft cpptest so buildbot is the only user able to take advantage of the following LSST DM setup.

Once-Only Account Setup

The LSST scripts used to interface to cpptest, require a uniform directory layout. Prior to the initial use of the scripts, the following setup command must be done.

# build working directory tree
    mkdir -p ~/cppTestbed/sourceSVN          # SVN source
    mkdir -p ~/cppTestbed/workspaceCpptest   # Cpptest projects repository
    mkdir -p ~/cppTestbed/reportCpptest     # Collection directory for Cpptest reports

The layout will eventually fill-out, for example:

#  /home/buildbot/                        # master directory for ALL c++tests
#         globalExcludesCpptest.lst       # exclude src files based on patterns
#         template_localSettingsCpptest.def # template for developer email defn
#         cppTestbed/                     # developer's c++testing directory
#               localSettingsCpptest.def  # defines developer's email path
#               sourceSvn/                # source extracted from SVN
#                     daf_base/           # src from SVN into EUPS package name
#                           daf_base.bdf  # metadata built by cpptestscan
#                     pex_exceptions/
#                           pex_exceptions.bdf
#               reportCpptest/            # developer's c++test reports
#                     daf_base/           # reports under appr package name
#                     pex_exceptions
#               workspaceCpptest/         # developer's eclipse/c++test wkspace
#                     daf_base            # eclipse data for specific package
#                     pex_exceptions

On login

Initialize the LSST software environment

    source ~/lsst/stacks/default/loadLSST.sh         # on tracer use 'l' alias
    cppscons="scons setenv=1 CXX='cpptestscan g++'"  # setup alias; exists on tracer

Setting Up Source for CPPTEST

Extract from svn the source for the module-to-be-tested. Download into a directory named after the eups module name, e.g. daf/base -> daf_base.

    # position to your own directory for SVN-retrieved source
    cd ~/cppTestbed/sourceSvn
    * extract the module-to-be-tested
    svn co $LSST_DMS/<module>/trunk <eupsModule>  

In order to prepare for the scons build of module-to-be-tested, ensure that all modules upon which the module-to-be-tested is dependent are EUPS-current.

    cd <eupsModule>
    setup -r .

Building the CPPTEST Metadata

Using scons, build the cpptest metadata for the module-to-be-tested.

    cd <eupsModule>        
    cppscons       # alias cppscons="scons setenv=1 CXX='cpptestscan g++'"                 
    cd ../

Creating the CPPTEST Project associated with an EUPS Module

The cpptest project is created from the scons/cpptest metadata. This step is done only if the cpptest project associated with the eups module does not exist - either since the eups module is brand new or the associated cpptest project was deleted.

cd ~/cppTestbed
CreateProject.py  [ -e <email> ] <eupsModule>

CreateProject.py pex_harness  # default email to robyn@lsst.org

Running the Standards Checker

Initial Run After Project Create

The CreateReport.sh shell script runs either the C++ or Python Standards Checker then emails the Report to whomever is designated (or 'robyn' as default).

CreateReport.py <rule option> [ -e <email> ] <eupsModule>

CreateReport.py -r afw          # LSST C++ Required Rules
CreateReport.py -b pex_logging  # C++ bug detective
CreateReport.py -d daf_base     # LSST C++ Desirable Rules  
CreateReport.py -p ip_diffim    # LSST Python Checking

Note: as of 6 Jan 2010 - option -d exists but is not ready for Production use.

Subsequent Runs

Initialize environment for Report generation on freshly modified package:

l              # alias for 'source ~/lsst/stacks/default/loadLSST.sh'
cd <eupsModule>
svn update
setup -r .

Always completing with one or more :

CreateReport.py <rule option> [ -e <email> ] <eupsModule>

Interpreting the Results of the Coding Standards Check

Refer to CppStandardsChecking for this information.

Suppressing an Infraction Report on a Statement

Refer to CppStandardsChecking for this information.

CPPTEST Rulesets

The Rules

To explore the rulesets available from Parasoft or ourselves,

  • Bring up cpptest
  • Select C++test from top banner; select Test Configuration from drop-down menu.
Review the various Parasoft packaged Rulesets
  • from L frame: select Builtin-> Static Analysis; and
  • from R frame: select Rules Tree.
  • Now in L frame, select packaged Ruleset, all its rules will be selected in the R frame's Rules Tree. Browse as desired.
Review an existing User-defined ruleset
  • from L frame, select User-defined; select the ruleset of interest.
  • in R frame, you'll have the option to modify the Rules Tree by selecting Rules from the various Rule Packages.
    • open the package branch (select the triangle) and view what rules are currently selected.
    • in order to start 'fresh', check the box for a package - that selects all that package's rules; then check it again - that deselects all that package's rules.
  • you can select any rule, as desired.
  • when you're done, select 'Apply' to save your changes to your personal Rule Tree.
Create your own Ruleset
  • from L frame, select User-defined; select New
  • in R frame, you'll have the option to name your New Configuration and to modify the Rules Tree by selecting Rules from the various Rule Packages.
    • open the package branch (select the triangle) and view what rules are currently selected.
    • in order to start 'fresh', check the box for a package - that selects all that package's rules; then check it again - that deselects all that package's rules.
    • you can select any rule, as desired.
    • when you're done, select 'Apply' to save your changes to your personal Rule Tree.
Create LSST Coding Standards Rulesets

We built two LSST Rulesets based on the LSST C++ Standards which are targetted for different levels of severity:

  • CodingStandardsRequired - rules which are required unless there is justification to do otherwise in the specific situation.
  • CodingStandardsDesirable - rules which are highly recommended but can be neglected for aesthetics of layout or structural consistency, etc.

A third Ruleset is proposed

We also licensed a Ruleset from Parasoft called: BugDetective?, which scans for potential bugs in the source code, for example: array out of bounds access, uninitialized variable use, etc.

Setup Rule Developer GUI Access to CPPTEST

A single, standalone license for the GUI interface to cpptest has been purchased. The license is allocated for cpptest Rule development. The software will be acquired for installation soon.

This section is not ready; it's definitely not organized ....

  • The first time cpptest executes after a new installation, the web browser needs to be identified so that cpptest help will operate.
    • select Window->Preferences
    • expand in L frame: General
    • select in L frame: Web Browser
    • in R frame, Search... to find the directory containing the desired web browser, then select it.
    • in refreshed R frame, check the desired web browser, then select Apply, then selectOK.
    • For tracer, /usr/bin/firefox was setup as the web browser.
  • When cpptest starts up, it has a default workspace defined. A workspace is where all cpptest state is maintained. When a workspace is switched (try: File->Switch), cpptest restarts itself after a few seconds delay. [

Currently known workspaces are:

  • /home/buildbot/cppTestbed/workspaceCpptest - workspace setup for DM standards Check
  • /home/buildbot/Parasoft/cpptest/workspace - inactive workspace circa Day 1
  • /home/buildbot/robyn/cpptestWorkspace - inactive workspace used during cpptest testing

The last open workspace is the default for all subsequent activity so if you switch from the standard one at cppTestbed, remember to switch back when you['re done.

  • C++Test needs to access LSST development environment & software stack.
    • The current LSST software stack is installed in /home/buildbot/lsst/stacks/default which is a symbolic link to the actual stack directory.
  • Setup the LSST development environment using the buildbot@tracer alias l (lower-case L) to invoke source ~/lsst/stacks/default/loadLSST.sh
    • For example: l

GUI setup of Eclipse Projects

Parasoft assumes that all software is managed within an "Eclipse Project". We need to determine the best method to map our SVN/scons setup into the Eclipse framework so that it's easy to standards check both individual packages and/or the entire software stack.

  • Option: use the Eclipse plugin for direct SVN access in order to create and populate an Eclipse project; or
    • pro: should easy to keep package directories up-to-date
  • Option: use the Parasoft tool, cpptestscan to take an existing directory structure and its build process to generate an Eclipse project.
    • con: must be done every time user wants to standards check a package.
    • pro: should be able to automate this step
Eclipse and SVN

There are 2 Eclipse plug-ins providing Subversion repository access: subversive and subclipse.

Project Setup using cpptestscan

In order to statically analyze source-code files, you must first create a C++Test project for them, and the easiest way to do this is to use the "cpptestscan" utility, which comes with the software, to instrument the build file. When building an LSST package, I found that the following build command did the job: scons setenv=1 CXX="cpptestscan g++" This creates a file call cpptestscan.bdf in the current directory, which then can be used to create a project for the LSST package via GUI menus.

.......Extracted from Russ Laher's , "Results of Code-Checker Evaluations, October 1, 2008

NOTES
  • a single Eclipse project is generated for each module
  • If the Eclipse source directory is setup to mimic the SVN/DMS directory excluding the {trunk, tickets, tags} branches. I.e.
    DMS/base/{src/*, python/* lib/* etc}
    DMS/daf/base/{src/*, python/* lib/* etc}
    DMS/daf/persistence/{src/*, python/* lib/* etc}
    

Eclipse considers base and daf/base as the same module.

It is therefore necessary to use a unique name for the module directories. Since eups module names are unique, they will be used for the cpptest project names.

  • when deleting a project which is surplus to needs, be careful about selecting the option where contents of the project are also deleted. If the contents are accessed thru a link point, then only the link is removed but not the 'folder' contents being pointed to by the link. If contents are accessed through direct pathnames, then the source (and everything else) will be deleted.

Starting GUI cpptest =

In your local VNC client, startup the C++Test

  • For example: cpptest

Procedure to add new CPPTEST project via GUI

  • Use C/C++ Perspective
    • select: Window -> Open Perspective -> Other... -> C/C++ (not C++Test)
  • There are two methods of creating a project
    • Option 1: Best method since uses link on source files so won't remove source on project delete
      • select: File -> New -> Project -> C++ Project
  • Option 2: Don't use since use of explicit source path may lead to that directory's deletion when the project is deleted (unless careful with delete options)
    • select: File -> New -> Other...
    • in Wizard pop-up: C++Test -> Create project from build file

....

Python: Pylint Setup

Pylint Use

The CreateReport.sh shell script runs either the C++ or Python Standards Checker then emails the Report to whomever is designated (or 'robyn' as default).

CreateReport.py -p ip_diffim    # LSST Python Checking

For those wanting to pylint their files locally, the prototypical Python pylint command below selects the correct subset of python files found in the eupsModule directory.

Note the following is specifically targetted for buildbot at tracer.ncsa.uiuc.edu. However, pylint may be installed on any Developer's desktop and the command run locally using the LSST .pylintrc file at: $SVN/DMS/devenv/codecheck/trunk/pylintrc

cd ~/buildbot/cppTestbed/sourceSvn/<eupsModule>
find . -name .tests -prune -o -name "*[^Lib].py" -exec pylint {} \; \
                                >&     <outputFile>

Interpreting the Results of the Coding Standards Check

Refer to PythonStandardsChecking for this information.

Suppressing an Infraction Report on a Statement

Refer to PythonStandardsChecking for this information.