3. How to View CodePeer Output

We recommend using either GPS or GNATbench to view CodePeer messages, because these IDEs provide powerful source navigation capabilities not available in e.g. the HTML report, which can help review and understand messages more easily.

3.1. Viewing CodePeer Output in GPS

3.1.1. CodePeer Report Window

When you open a CodePeer report (using one of the CodePeer menu items, see Running CodePeer from GPS), the locations view is filled with messages from the CodePeer run, and the following report window is displayed:

_images/codepeer-report.jpg

The report window has two tabs: Messages and Race conditions. The first tab provides a summary of all messages and filtering capabilities, and the second provides a summary of potential race conditions found.

On the left side of the messages window, there is a main area listing all files for which messages have been generated, with information organized hierarchically by project, file and subprograms. You can click on any file to display the first message on this file in the locations view. See Using the Locations View and Reviewing Messages for more details on the use of the locations view.

Similarly, you can double click on any file or subprogram to jump to the corresponding source editor, which will be displayed with their corresponding CodePeer annotations.

For each of these entities, three columns displaying the number of high, medium and low messages corresponding to the current filter selection (see Using Filters).

In addition for projects and source files, two additional columns are available, displaying the Passed checks (number and percentage of checks that CodePeer has analyzed automatically without finding any potential run-time error) and the Total checks (total number of checks verified by CodePeer).

Different kinds of filters are available on the right side of the window. Clicking on each of these filters will show/hide the corresponding messages in the locations view. This way, you can easily concentrate on e.g. high ranking messages only, or on a specific category (e.g. validity check) during your review of the messages.

The filters are divided into three kinds:

  • Message categories

    This section (the first column on the right of the file summary) lists all the message categories found in the current analysis in two groups: warnings and checks. In addition, it lists all CWEs found in the current analysis when displaying of CWEs is enabled. By default, all categories found are enabled, and you can select/unselect all categories in each group at once by clicking on the check box left to the Warning categories (or Check categories, or CWE categories) label, or individually by checking each item. See Description of Messages for more details on the meaning of each category.

    CWE categories filter applies for all kinds of messages. When some CWE is selected in filter all messages with this CWE are displayed (even when not selected in Warning categories and Check categories filters). Precondition messages are displayed when related checks has selected CWE.

  • Message history

    By default, new (added) and current (unchanged) messages are displayed. You can also select old (removed) messages that are no longer present in the last review, or concentrate on added message only and ignore baseline (unchanged) messages. This is particularly useful when using CodePeer on legacy code, without having to review previously found messages, and concentrate on messages found after new changes, to analyze the impact of these new changes.

  • Message ranking

    By default, GPS only displays the most interesting messages (ranked medium and high). Once you have reviewed these messages, reviewing the low messages can be useful. It can also help understanding some messages to display the low and/or informational messages, which can provide additional information.

  • Message review status

    By default, GPS displays messages with the unclassified, pending and bug review statuses. You can change this default setting by checking or unchecking the corresponding boxes (in particular to view not a bug, false positive and intentional review statuses).

On the top of the race conditions window, there is a list of shared objects. Clicking on shared object will open a list of entry points in the bottom of the race conditions window and automatically scroll the Locations window to simplify access to locations where shared objects are used.

On the bottom side of the race conditions window, a list of entry points and kind of access is displayed for the currently selected shared object. Clicking on row of this view opens source editor at scroll it to point of access to shared object.

3.1.2. Using the Locations View and Reviewing Messages

When you open a CodePeer report (see Running CodePeer from GPS), the locations view at the bottom part of GPS is filled with messages from the CodePeer run. For example:

_images/codepeer-locations.jpg

You can click on any of these messages, and GPS will open a source editor containing the relevant source file, at the listed source location. You can also use the Filter panel available from the contextual menu in the locations view in order to display only messages containing a specific text pattern.

For more details on how to use the locations view, see the GPS documentation directly, which explains how this view is managed.

In addition, an Edit icon is displayed in front of each CodePeer message. Clicking on this icon allows posting a manual review of the message. It is possible to review single or multiple messages at once. See Reviewing Messages for more information about use of message review dialogs.

3.1.3. Reviewing Messages

There are two forms of CodePeer message review dialog: one to review single messages and another to review multiple messages. Which dialog will be used depends on how many messages are selected in the Locations view before clicking on the edit icon.

_images/codepeer-single_review.jpg _images/codepeer-multiple_review.jpg

The New Status drop-down box allows selecting the review status of the message. The review status is initially set to Unclassified and can be set to Pending, Not A Bug, Intentional, False Positive, or Bug.

The Approved By text box allows the name of the reviewer to be recorded.

The Comment text box allows the reviewer to enter an explanation/justification for the message.

The single-message review dialog displays a history of the changes related to that message, while the multiple-message review dialog displays a list of messages to be reviewed along with their ranking and review status.

3.1.4. Reviewing CodePeer Annotations

CodePeer generates as-built documentation for each subprogram that it analyzes. This documentation is presented in the form of virtual comments at the beginning of each subprogram in a source-editor window. This as-built documentation includes annotations in the form of Preconditions, Presumptions, Postconditions, Test Vectors, etc. which characterize the functioning of the subprogram, as determined by a global static analysis of the subprogram and the routines that it calls, directly or indirectly. For more details on the form of these annotations, see Description of Annotations. For more details on using these annotations as part of code review, see Use Annotations for Code Reviews.

The virtual comments are not actually added to your source code; they are only visible when viewing the source in a GPS source-editor window. You may hide the annotations using the CodePeer ‣ Hide annotations item in the source editor’s contextual menu. You may display them again using the contextual menu item CodePeer ‣ Show annotations.

3.1.5. Backtraces view

When Backtraces view is open (it is open by default, or can be open by Tools->Views->Backtraces menu), clicking on a check message in the Locations view opens the Backtraces view. This view provides a list of source locations where the information in the selected message originated. In other words, these are places where CodePeer learned about the range of values of the variables or expressions mentioned in the message.

_images/codepeer-backtraces.jpg

Clicking on a source location in the Backtraces view opens a source window that shows the listed source location in the relevant source file.

3.1.6. Using the source editor’s tooltip to display values

Tooltips in the GPS source editor display the set of possible values for objects under the mouse cursor, if this information is available.

This can be disabled by the CodePeer ‣ Display values item in the source editor’s contextual menu. When disabled, GPS displays the default contents of the tooltip.

3.1.7. Source Navigation

Using the GPS source navigation can be very useful for understanding CodePeer messages, verifying that messages are indeed relevant, and modifying the source code.

In particular, using the Find all references and Find all local references contextual menu, as well as Goto body will help significantly with reviewing messages.

In some cases navigation information might not be available. In this case you might see these options indicated as “best guess” and clicking on them might not do anything. How the data needed for source navigation are generated is controlled by the GPS “Build mode” scenario variable. You can check the value of this variable by selecting menu item Tools/Views/Scenario and then looking in the Scenario window (typically on the left side of the screen) for the “Build mode” variable. It should be in “codepeer” mode if you want to use source navigation without building using GNAT.

Overall there are three possibilities:

  1. You have only CodePeer installed (and not GNAT).
  2. You have both CodePeer and GNAT installed, but you want to use CodePeer to generate your cross-reference information;
  3. You have both CodePeer and GNAT installed, but you want to build using GNAT to generate your cross-reference information.

In cases (1) and (2), the Build mode should be “codepeer.” In case (3), the Build mode should be “default” or anything but “codepeer.”

For more information on GPS source navigation capabilities, see the GPS User’s Guide.

3.2. Viewing CodePeer Output in GNATbench

3.2.1. CodePeer Problem Details View

When you run CodePeer (using one of the CodePeer menu items, see Running CodePeer from GNATbench), the CodePeer Problem Details view is filled with messages from the CodePeer run, and the following view is displayed:

_images/codepeer_problem_details.jpg

The messages generated by CodePeer are shown in this view. The messages are associated with source files. For each filename, the message shows the line and column number, message ranking (high/medium/low) and a brief description of the problem. If you click on the message in the CodePeer Problem Details view, the corresponding message will be highlighted in the editor window.

Different kinds of filters are available on the top right side of the bottom window. Click on the View menu icon (inverted triangle icon) and then select Filter By submenu. You will see the following list of filters:

  • High ranking messages
  • Medium ranking messages
  • Low ranking messages
  • Warnings
  • Show All

Clicking on each of these filters will show the messages of that ranking in the CodePeer Problem Details view. At present the filters support filtering the messages by message ranking (high/medium/low) and showing messages corresponding only to warnings.

In the editor window the problems are identified by special markers (red flag for high ranking messages, orange flag for medium ranking messages and yellow flag for low ranking messages). If you hover over these markers, you can see the details of the message.

3.2.2. Reviewing CodePeer Messages

To review CodePeer messages, select the message in the CodePeer Problem Details View by double clicking on the message. A dialog window titled “CodePeer Message Review” would pop up. You can change the status of the message from the “New Status” pull down menu. Also you can add the name of the person reviewing the message in the “Approved By” text field and can add comments in the “Comment” text box. You can modify any of the fields. To save the changes, press OK. Below is the screen shot of the “CodePeer Message Review” screen.

_images/codepeer_messagereview.jpg

You can see a history of the changes related to that message in the “Audit trail” text area.

3.2.3. CodePeer Annotation Details View

When CodePeer finishes its analysis, it also creates annotation markers for the sources. The editor ruler will show the annotation markers on the first line of every method. Clicking on an annotation marker, brings up the CodePeer Annotation Details view which looks as shown below.

_images/codepeer_annotations.jpg

This view displays the preconditions and postconditions that characterize a method. It also shows any unanalyzed calls for the method, and any presumptions made about their effects. It also shows the test vectors for the method.

3.2.4. Race Condition Details View

When the user right clicks on a project and selects Codepeer ‣ View Race Condition menu,it opens the Race Condition Details view in the bottom pane.

There is a table of potentially shared objects on the bottom left side of the view. Clicking on a shared object will update the “Access Summary” table and “Access Details” tree view for the selected object. By default both “Access Summary” table and “Access Details” tree show the entries for the first object in the “Potentially Shared Objects” table.

The “Access Summary” table lists the entry points and kind of accesses for the currently selected object.

The “Access Details” tree view lists all the references to the object organized by access type (read/update). It also lists the filename and line number where the object is accessed. Clicking on an entry in the “Access Details” view will highlight the particular line in the file in the editor window. The Race Condition Details view looks like as shown below:

_images/codepeer_racereport.jpg

All the tables in this view can be resized.

3.3. HTML Output

3.3.1. Browser Requirements

The output of CodePeer may be browsed via recent versions of any browser, e.g. Internet Explorer, Firefox or Chrome. Verify that your browser’s security level is set to enable JavaScript, to allow popup windows, and to allow the JavaScript to raise and lower windows (see below).

On Internet Explorer, you will need to allow windows to use iactive content (i.e. JavaScript) by going to Tools ‣ Internet Options ‣ ...Advanced, scrolling down to the Security check boxes, and checking the box that says Allow active content to run in files on My Computer.

On Firefox, you will need to allow JavaScript to raise and lower windows. This is done by going to Tools ‣ Options ‣ Content ‣ Advanced button next to the Enable JavaScript (which should be checked also), and then making sure that the Raise or lower windows box is checked.

3.3.2. Location and Format of Output

CodePeer’s output is generated in the Output_Directory. Output is generated in two formats, both of which preserve the Ada package/source file hierarchy. The HTML format is suitable for display by a browser. It is produced under the html subdirectory of the Output_Directory. A more traditional interleaved source and message listing is produced under the list subdirectory of the Output_Directory. The contents of the list subdirectory may be displayed with any ASCII text viewer. See Text Output for more details.

To look at the output, point your browser at html/index.html, in the Output_Directory.

3.3.3. Running the CodePeer Web Server

CodePeer comes with a web server which can optionally be run after an analysis to serve the HTML Output and to allow users to manually review messages. You can run the CodePeer web server by providing the path to the output directory and specify a port to serve requests from the command line, for example:

$ codepeer_ws codepeer/my_project.output 8080

The default port is 8080, so you can omit this optional value.

You can then open a browser and specify a URL of the form http://localhost:8080/ (localhost will work if you are using the same machine for the web server and for the web browser, otherwise you will need to replace localhost with the name of the machine where codepeer_ws is launched).

To stop the web server you need to press Ctrl-C, which will clean up lock files and shutdown cleanly the web server.

Note that the CodePeer database is locked when the web server is running. You need to stop it before doing a new analysis or if you want to access to results from GPS. If you do not need to review messages manually, then you can access the html/index.html file directly instead of using the CodePeer web server.

3.3.4. Back and Forward Buttons

The back button (<<) and forward button(>>) are located in CodePeer’s titlebar. Use these buttons to navigate through the command history associated with the large right panel of the main window. These buttons will work more predictably than the browser’s built-in back and forward buttons, because of the multi-frame user interface provided by CodePeer. The browser’s built-in back and forward buttons work fine with the other windows (Message History, Race Conditions, and Help windows).

3.3.5. Main Window

The Main Window is composed of up to four panels, with a titlebar across the top. The Partition Panel in the upper-left panel contains a list of the partitions into which CodePeer has broken up the system for more efficient analysis. Click on All Partitions to display all directories and files, or click on a named partition to filter directories and files to those inspected within that partition. The Partition Panel will not be present if the analysis was performed as a whole and no partitions are created. The -level max command line switches instruct CodePeer to avoid making partitions; CodePeer will also not create partitions if the analysis is small enough for the available amount of memory.

The Directories Panel on the left, below the Partitions Panel (if your project has partitions), lists all directories in which CodePeer found source code. Click on All Files to list all files associated with all directories in the Files Panel, below. If you are viewing only a single partition, click on Partition n Files to list only those files within partition n in the files panel. Click on a single directory to list only its files in the Files Panel.

The Files Panel on the left, below the Directories Panel, lists source files analyzed by CodePeer. A - to the left of the file indicates that the file has been dropped since the Base Code Review; a + indicates that the file has been added since the Base Code Review. Initially, the Files Panel shows all of the source files in the system, across directories and partitions. Filter the list by selecting a single partition in the Partitions Panel. You may also filter the list by selecting Partition n Files or a single directory in the Directories Panel. Click on a file name to view the File Summary, described below.

In the title bar itself, in the upper right corner, there is a summary of the overall number of checks performed by CodePeer:

Total Checks Analyzed    340
Total Checks Passed      338
Percentage Passed     99.41%

This is a summary of the total number of Ada run-time checks analyzed by CodePeer in the overall test case, and how many of them were proved to never fail. In the above case, there were only two run-time checks that might fail, and CodePeer will have generated a message for each one. Note that “Total Checks Analyzed” counts only Ada run-time checks and checks for uninitialized variables; it does not include other kinds of analysis performed by CodePeer, such as dead and redundant code analysis, race-condition analysis, etc.

In the Main Panel on the right, you may click on one of three tabbed views: CodePeer Overview, File Summary, and File Source.

The CodePeer Overview view shows the review’s File Hot Spots, a sorted list of files, those with the most important messages listed first. Importance is ranked according to an algorithm that considers the number, a calculated degree of priority, and newness of messages. In the header, the Current Code Review shows the date and number of the run that generated this output, whereas the Base shows the date and number of the Base Code Review. The Base Code Review is a prior run against which the Current Code Review is compared, to determine changes since a prior run.

For each of the files, a set of columns shows the numbers of high, medium, and low ranking messages. The higher the ranking, the more interesting the message, and the greater the likelihood the indicated line of code would fail when executed. Each ranking category has three columns: base, deltas, and now. The base shows the total number of messages that were found in the Base Code Review in each file. The now column shows the total number of messages that are found in each file for the Current Code Review. The deltas column shows how many unique messages were dropped and/or added between the base and Current Code Review in the form dropped/added, e.g. -2/+5 means that two messages were dropped and five new ones were added. Click on an individual file name to display its File Summary.

If any of the files have been added (+) or dropped (-) since the Base Code Review, the File Hot Spots table will have a -/+ column to mark the file in this way. Dropped files (i.e., files that were present in the Base Code Review, but are not in the Current Code Review) appear at the end of the table, after the files for the Current Code Review. Clicking on the name of a dropped file will bring you to its File Summary view, but because the file is not part of the Current Code Review, you will not be able to access its File Source view.

The File Summary view shows a file’s Hot Spots, a sorted list of subprograms, those with the most important messages listed first. As for the CodePeer Overview, importance is ranked according to an algorithm that considers the number, a calculated degree of priority, and newness of messages. The following section will list a summary table for each subprogram that has messages. If there are no messages for the file, there will be no Hot Spots or Subprogram Summary tables. The last section lists all subprograms, even those with no messages, with links to jump to the source for each subprogram. If a subprogram name has a hyperlink, clicking on it will bring you to the Subprogram Summary table in the File Summary view.

The File Source view shows an annotated source file listing for the current file. If no source was available for a .scil file that was reviewed, only the annotations will be displayed. The source is interspersed with preconditions and postconditions, lines with added message indicators (+ to the left of the line number), and color-coded hyperlinks to the messages. Click on the Precondition/Postcondition indicator (P/P) near the top of a subprogram’s definition to show a list of all preconditions and postconditions in the bottom view pane.

Click on a color-coded, hyperlinked line to show the associated message(s) in the bottom view pane. The colors are assigned according to the highest ranking message associated with any one line, red for high, orange for medium, yellow for low. Each message will show a blank or + indicator (+ indicating this message is new in the Current Code Review), a message category, a high/medium/low ranking indicator, and a detailed text description. Click on Prev Msg or Next Msg to view the previous or subsequent message for the file, respectively. Click on the Edit Icon, the image of a pencil-and-paper to the left of the ranking indicator, to open the Per File Message Status Window.

Click on the CodePeer Overview, File Summary, or File Source tabs to alternate between views. Remember to use the << and >> buttons in CodePeer titlebar to navigate back and forward, respectively, between viewed pages. (Avoid using the browser’s default back and forward buttons, since they may lose track of your view state information.)

3.3.6. Race Conditions Window

Click on the Race Conditions button in the titlebar to view their Race Conditions report. The button is suppressed if the analysis was performed with the -no-race-conditions command line option. See Identify Possible Race Conditions for a description of how to interpret the results of the race condition analysis.

3.3.7. Message History Window

Click on the History button in the titlebar to view the Message History report. This button is visible only if a Database_Dir has been specified in the library file (see above) for the Current Code Review and the user has not specified the -no-error-history command line option. This report contains a table of the number of messages identified in every review, in total and grouped by each directory of sources, since the database was created. Each row corresponds to a review. The row of the baseline review appears darker.

At the bottom of the Message History report is a histogram of the total number of errors over time, with one column per review.

Note: For the Message History Report, each message in the database is evaluated relative to the Current Code Review, the current Base Code Review, and the current MessagePatterns.xml file. As a result, the message counts for prior reviews may vary from those counts that were reported at the time of the actual review.

3.3.8. Message Status

Click the Messages button in the titlebar to open the Message Status Overview window. This window contains a system-wide summary of the messages organized by Message Category, and again by source file. The Message Status Overview allows you to sort/filter system-wide summaries of messages and to access per-file summaries.

3.3.9. Message Category Table

For each row in the Message Category table, the message count for each category is further broken down by High/Medium/Low ranking.

Uncheck the select box for a message category to suppress that category from appearing in the Source File Table.

3.3.10. Source File Table

Each row in the Source File table is uniquely defined by source file and message category. The message counts are subtotaled for each category of messages in a source file. As with the Message Category Table, each file-category row has High/Medium/Low ranking columns. File-category rows with zero messages are not shown.

Click on a column header to sort the display by that criterion. Sorting large tables can take a long time. While the sort is being performed, the column header will be highlighted, and a Stop Sort button will appear at the top of the window. You may continue working in other areas of the browser while a sort is running, although performance may be slowed. The Stop Sort button will disappear when the sort finishes. Click on the Stop Sort button to s a sort before it finishes.

3.3.12. Per-File Message Status Window/Editing Messages

The Per-File Message Status window provides a detailed, sortable list of messages for a single source file. You can modify the status of a message by changing its ranking and/or adding comments to it by using the GPS interface and CodePeer web server. These changes will be reflected and displayed in the HTML report. Additionally, the complete change history for a message is displayed.

At the upper-left of the window, the Filter Options grid contains checkboxes to control which messages are displayed. for History options, check added to select messages that were not in the Base Code Review but appear in the Current Code Review, dropped to display messages that appear in the base but not in the Current Code Review, and unchanged to display messages that appear both in the Base and Current Code Review. For Probability, check High, Medium, Low, Info and Suppressed to display messages with corresponding current rankings.

By default, added, unchanged, and dropped messages are displayed, for High and Medium ranking; Low, Info and Suppressed messages are hidden. You may check a box to show the corresponding messages, or uncheck the box to hide them. The filtering options selected affect all files, not just the one whose messages are currently being displayed.

Click on any of the hyperlinked column headers to sort by that column, which can be Status, +/-, Msg Id, Method, Line, or Message Category. Sorting columns in this window uses your browser’s built-in sorting capability, and may be unresponsive during a sort. Most sorts should complete in a reasonable amount of time.

The Msg Id column contains CodePeer-generated message identifiers used to uniquely identify each message. Click on a Msg Id to jump to the File Source view for that message.

When the HTML Output is served by the CodePeer Web Server, there is an additional Review/Edit/View button below the message ranking available to open the Edit Message Window (or the View Message window in the case of messages that have a corresponding pragma Annotate in the source).

3.3.13. Edit Message Window (Provide Message Review)

The Edit Message Window allows users to view and provide audit information for individual CodePeer messages as described below.

The Change History area displays the complete audit information available for the selected message. The Ranking field displays the ranking of the message.

The Set Review Status drop down box allows selecting the new review status of the message (set to the current status by default). The review status is initially set to Unclassified and can be set to Pending, Not A Bug, Intentional, False Positive or Bug. The Approved By text area allows the name of the reviewer to be recorded. The Add Comment text area allows the reviewer to enter an explanation/justification for the message (e.g., explain why the construct flagged by the message is not actually a bug).

The Save/Mark As Reviewed buttons save this review information in the database via the web server.

3.3.14. View Message Window (View Message Ranking)

The View Message Window provides audit information for the message including the audit set by the pragma Annotate in the source.

The Change History area displays the complete audit information available for the selected message. The Ranking field displays the ranking of the message as set by the pragma.

3.3.15. Annotations Report

Click the Annotations button in the titlebar to open the Annotations Report window. This window contains a system-wide summary of annotations per file, with deltas.

Click on a file name to get a detailed view of annotations per subprogram, including some history information, filterable by annotation kind, and whether the annotation is new, unchanged or dropped.

3.4. Text Output

You can get a compiler-like listing of messages generated by CodePeer by running codepeer with the -output-msg-only switch:

$ codepeer -Pmy_project -output-msg-only
alias.adb:10:11: high: validity check: Int is uninitialized here

The above command will run the codepeer_msg_reader utility, with the output directory as an argument. In other word, the above command is equivalent to:

$ codepeer_msg_reader codepeer/my_project.output
alias.adb:10:11: high: validity check: Int is uninitialized here

Note that you can also ask codepeer to perform its analysis and then run codepeer_msg_reader automatically via the -output-msg switch, e.g:

$ codepeer -Pmy_project -output-msg
no partitioning needed.
starting analysis
analyzing p__body.scil
analyzing p.scil
analysis complete.
2 .scil files processed.
updating DB and generating reports
finish updating DB at ...
alias.adb:10:11: high: validity check: Int is uninitialized here

You can also optionally specify the following codepeer_msg_reader switches:

  • -csv will display messages in a CSV format, suitable for use by other tools such as spreadsheets, and including more verbose information. See CSV Output for more details.

  • -out <file> specifies a file where messages are output, instead of standard output.

  • -hide-low will hide low ranking messages.

  • -security <standard|full>: if this switch is enabled, only messages which are relevant for a security analysis are generated. These are all the messages with an associated CWE id (see CWE Categorization of Messages). In other words, this switch acts as an additional filter on messages. If -security standard is used, then CodePeer assumes that the Ada code is compiled with checks on and that DoS (Denial of Service) issues are not a concern, and will as a result not generate any messages related to run-time checks. If you are interested also in run-time checks in the context of a security audit, you can use -security full instead.

  • -show-annotations also lists annotations (e.g. pre- and postconditions) computed by CodePeer, in addition to regular messages.

  • -show-header will show a header with extra information about the run including:

    • The date and time of CodePeer run
    • The CodePeer version that has generated this report
    • The host for which CodePeer is configured (e.g. Windows 32 bits)
    • The full command-line of the CodePeer invocation, including project file
    • The CodePeer switches specified in the project file
    • The current and base CodePeer run numbers (CodePeer run numbers start at 1 and increase sequentially on each execution of CodePeer)
    • The files excluded from analysis, if specified in the project file via the Excluded_Source_Files or Excluded_Source_Dirs attributes.

    Note that strictly speaking, when combined with -csv, this switch will generate a malformed CSV file. Since using -csv and -show-header provides useful information, this combination is allowed, and it is the user’s responsibility to postprocess (e.g. split) the output if needed.

  • -show-info will show informational messages such as which units were analyzed, mention of any limitation encountered during analysis, or any subprograms that could not be analyzed.

  • -show-removed will show messages that have been removed from the current run relative to the previous baseline run, interspersed with the normally displayed messages. When generating text messages, any removed messages will be marked with the designator “[removed]” immediately preceding the message’s ranking. In CSV message output, the “History” column will indicate removed for any removed messages.

  • -show-reviews will list also messages reviewed manually, with additional review information about current review status, date of review, name of reviewer and associated comment.

  • -show-reviews-only will list only messages reviewed manually, with a history of each review containing: review status, date of review, name of reviewer and associated comment.

3.5. Report File

If you want CodePeer to generate a report file in text format, you can combine some or all of the following switches, either on the command line or via CodePeer’s switches in the project file:

  • -output-msg
  • -out <report file>
  • -show-header
  • -show-info
  • -show-removed
  • -show-reviews

See Text Output for details on each of these switches.

For instance if you specify in your project file:

package CodePeer is
   for Switches use
     ("-level", "max", "-output-msg", "-out", "report_file.out", "-show-header", "-show-info");
end CodePeer;

The -out switch allows you to specify an output file when generating messages with -output-msg, instead of standard output which is the default.

Here is an example of a report file produced with the above switches:

date              : YYYY-MM-DD HH:MM:SS
codepeer version  : 3.0.1 (yyyymmdd)
host              : Windows 32 bits
command line      : codepeer -P my_project.gpr
codepeer switches : -level max -output-msg -out report_file.out -show-header -show-info
current run number: 4
base run number   : 1
excluded file     : /path/to/unit3.adb

unit1.ads:1:1: info: module analyzed: unit1
unit1.adb:3:1: info: module analyzed: unit1__body
unit2.adb:12:25: medium: divide by zero might fail: requires X /= 0
[...]

3.6. CSV Output

You can use the -csv switch via e.g. codepeer -output-msg[-only] -csv to generate messages in a CSV format, suitable for use by other tools such as spreadsheets, for example:

codepeer -Pprj -output-msg-only -csv -out messages.csv

Will generate a file messages.csv with the following contents: first a heading listing all columns:

File,Line,Column,Category,History,Has_Review,Ranking,Kind,Message,Classification,CWE,Checks,Primary_Checks,Subp,Timestamp,Approved By,Comment,Message_Id

then one line for each message, with each field separated by a comma, e.g:

f.adb,71,7,dead code,added,FALSE,low,warning,"dead code because F > 0",unclassified,"561","","",func,,,6

The columns available are:

Name Description
File Full pathname of the file containing the message
Line Line number of the message
Column Column number of the message
Category Category of the message, as listed in Description of Messages and Description of Annotations.
History added if message is new relative to the baseline, removed if message has been removed relative to the baseline, and unchanged otherwise
Has_Review TRUE if the message has been reviewed manually, FALSE otherwise
Ranking Ranking of the message (annotation, info, low, medium, high, suppressed)
Kind Message kind (check, warning, info, annotation)
Message Text of the message, surrounded by double quotes
Classification Review classification (unclassified, pending, false_positive, not_a_bug, bug)
CWE List of relevant Common Weakness Enumeration ids for the given message. See Description of Messages for more information about CWE.
Checks Only relevant for Precondition_Checks. This is a list of checks that contributed to the associated precondition.
Primary_Checks Same as above. The implied checks are omitted from the list.
Subp Fully qualified name of the enclosing subprogram
Timestamp Timestamp of the last review, if relevant.
Approved By Name of the review approver, if relevant.
Comment Last review comment, if relevant.
Message_Id Unique identifier of the message.