CodeSonar Plug-in for Eclipse: Tutorial

• Before You Start
• Files
• Set Up the Sample Project
• Build and Analyze the Project
• View the Analysis Results
• Eclipse Plug-in Links

Before You Start

If you have not already installed the CodeSonar plug-in for Eclipse, install and configure it now.

1. Ensure all prerequisites have been satisfied. (This includes installing CodeSonar and Eclipse if they are not already installed.)
   You will need the Eclipse CDT plug-in for this tutorial, so make sure you install it if it is not already present.
2. Install the CodeSonar plug-in.
3. Configure the CodeSonar plug-in.
4. Create a working directory for the tutorial.
5. Identify the hub you will use to manage the analysis results and ensure that it is running. For detailed instructions, see Make Sure the Hub Is Ready.

Files

We use the sample BasicProj.c and Makefile files provided with the Basic Tutorial.

• Save copies of BasicProj.c and Makefile to your working directory.

Set Up the Sample Project

Now set up the sample Eclipse project ready for building and analyzing with CodeSonar.

1. Start Eclipse, if it is not already running.
2. Create a new Eclipse project containing the tutorial files.
   1. Select File > New > Project from the main menu bar.
      A New Project dialog will open.
   2. Click C/C++ > Makefile Project With Existing Code to select it.
   3. Click the Next button.
   4. Enter csBasicEclipse in the Project Name field.
   5. Click the Browse button next to the Existing Code Location field, then use the Browse For Folder dialog that opens to select your working directory.
   6. Make sure the C checkbox is selected (the C++ checkbox can be either selected or deselected - it doesn't matter).
   7. Select your regular toolchain from the list of Toolchain for Indexer Settings candidates.
   8. Click Finish.
      The csBasicEclipse project will now be shown in the Project Explorer panel.
3. Set the project's analysis mode to Hook mode, and specify a CodeSonar hub to manage the analysis results. You will only need to do this once for each project.
   1. In Project Explorer, right-click on the csBasicEclipse project.
      A menu will open.
   2. Select CodeSonar > Properties from the menu.
      Eclipse will display the Properties dialog for the project, with the CodeSonar project properties selected.
   3. Enter your hub location in the Hub field.
   4. Click the Hub settings button (to the right of the Hub field).
      The hub connection settings dialog will open.
   5. Select a hub authentication mode: Anonymous only, Password, or Certificate.

      If your CodeSonar hub is configured to allow anonymous analysis and anonymous browsing, you can select Anonymous only. Otherwise, you will need to provide hub user account credentials to authenticate and authorize these operations: either username and password, or user certificate and private key.
      

   6. Enter the additional information required for your selected authentication mode, if any.

      Anonymous only	no further information required.
      Password	select/deselect Try Anonymous First according to your preference, then enter the Username and Password for a hub user account on the hub specified in the Hub address field.
      Certificate	enter the Certificate location for the user certificate you will use for hub authentication, and the Private key location for the private key corresponding to that certificate. If the private key requires a password, enter the Private key password.

   7. Click OK to go back to the Properties dialog.
   8. Select one of the analysis management radio buttons at the bottom of the Properties dialog. This setting depends on whether or not you are using CodeSonar SaaS.

      CodeSonar SaaS:	SaaS Analysis
      otherwise:	Local Analysis

   9. Click Apply and Close.
   10. Right-click on the project again, and select CodeSonar > Enable > Hook Build from the menu.
       A dialog will open, explaining that enabling hook build will trigger a clean on the selected project.
   11. Click the OK button in the dialog.
       A small CodeSonar icon will appear on the project, indicating that CodeSonar has been enabled.
       

Build and Analyze the Project

The Eclipse project is now set up to work with CodeSonar.

1. In the Project Explorer, right-click on the csBasicEclipse project.
   A menu will open.
2. Select CodeSonar > Build/Analyze Project from the menu.
   The Analysis Report view will open to show the progress and current results of the analysis.

   You m ay be prompted to perform one or more of the following.

   Accept the CodeSonar License	If this is the first time you are building a project and you have not yet accepted the CodeSonar license agreement, CodeSonar will print the text of the agreement and ask whether you want to accept it. Accept the license to proceed with the build. (If you accidentally click the wrong button, causing CodeSonar to abandon the build, just re-run the build command.)
   Provide hub user account credentials	If you specified Password- or Certificate-based authentication for the project while setting up but did not provide credentials for an account with sufficient permissions, you will be prompted to provide them.
   User Account Control	If User Account Control is enabled, your system may request permission for cs_uac_daemonize.exe from CodeSecure, Inc to continue. Click Continue to proceed.
   Service Authentication	[Windows only] If you are running CodeSonar with services, you may be asked to provide Windows service authentication. See CodeSonar As A Windows Service for more information.

View the Analysis Results

The Analysis Report view will look (something) like the following.

Initially the view will show the Overview tab.

• The panel on the left provides summary information about the analysis and its findings.
• The panel on the right contains links to additional information presented in the CodeSonar web GUI.

We will look at some the warnings issued by the analysis.

1. Switch to the Warnings tab.
   
2. If necessary, resize the columns so you can read the table contents comfortably.
3. Double-click the table entry for the "Null Pointer Dereference" warning that occurs on line 17.
   
   • The source listing for BasicProj.c will open, and scroll to the warning location.
   • The Warning view for the warning will open.
4. Look at the source listing.
   
   Information about the warning is overlaid on the listing.
   • The source code at the warning location is highlighted.
   • A warning marker is shown in the left margin at the warning location.
   • Orange markings to the right of the scrollbar show warning locations within the file (including the location of the current warning).
5. Look at the Warning view.
   
   
   • The Warning view header contains basic identifying information about the warning, in the following format.
     Warning_Class at File_Name: line_num id=warning_id
   • Initially the view will show the Code tab, which contains an annotated code excerpt that shows the context in which the warning was issued.
6. Scroll through the Warning view to see its contents.
7. Try hovering and clicking on various elements to see what happens. For example:
   • macro names such as NULL
   • line numbers
   • control flow markings , , and (in the left margin, to the right of the line numbers)
   • data event markings (in the left margin, to the left of the line numbers)
   • the source file path (at the top of the excerpt)
   • excerpt expansion links and (at the top and bottom of the excerpt)
   • "See related event" links
8. Switch to the Notes tab.
   
9. Use the pull-down menus to specify a Priority, State, Finding, and Owner for this warning.
10. Enter a note in the Note field.
11. Click the Save button. The Change History will update to include a notification for the changes you just made.
    These changes were made on the CodeSonar hub, so all hub users will be able to see them.
12. Click (at the top right of the Warning view).
    The web GUI Warning Report page for this warning will open in your web browser.
13. Check to confirm that your updated warning annotations are displayed in the web GUI.

This is the end of the Eclipse Tutorial. If you like, you can go to the tutorial index and choose another tutorial exercise.

Eclipse Plug-in Links

The following sections provide detailed information about installing and using the CodeSonar plug-in for Eclipse.

• Install and Configure the Plug-in
• Build and Analyze a Project
• Import Analysis Results
• View Analysis Results
• Preferences and Properties