iCobra GUI Overview and User Manual

Introduction

$ cd Cobra/src
$ icobra *.[ch]

$ icobra *.h *.c

Navigating the Displays

Figure 1 -- iCobra display on startup.

• The large white window on the left is where the tool displays results of queries or query libraries.

• The bottom window, labeled "commands:" is for user-input, though is not intended to be the primary way to use this interface. It merely gives a way to type in more detailed query commands that do not have direct support through the already predefined search options. One can, for instance, type the command sequence
  mark main; display
  or more tersely:
  m main; d

  and the results will appear in the results window.

• The vertical panel to the right of the main results window shows the names of all files that were specified on the command line, and that are now in Cobra database. (The standard Cobra tool runs in the background and communicates with the iCobra front-end.) Clicking on one of the filenames will display its contents in the results window. Figure 2 shows the display after clicking the cobra.h filename.

Figure 2 -- The display after clicking the filename cobra.h in the filenames list.

To the right of the main iCobra window is a menu listing the names of all query libraries that the tool finds in the rules/main directory of the standard Cobra installation. Figure 3 shows the display after we click on the first of these query libraries, named basic.cobra.

Figure 3 -- The display after clicking on the basics.cobra query library in the menu to the right of the main iCobra window.

A new window to the right of the rule library panel is displayed, with one row for each of the checks that are performed as part of this library set that has results to report. Many other checks are made, but if they do not match any part of the source code being analyzed then the corresponding check doesn't appear in the blue menu list on the far right in Figure 3. If none of the checks have matches to report, no results panel is shown.

The next step is now to select one of the results in the menu on the far right, and display the resulting matches. The first of the checks, called Shadow, checks for function names that are also used as variables elsewhere in the code.

Figure 4 -- The display after selecting the Menu Item named Shadow.

After selecting it, a new panel with numbers is shown -- shown in Figure 4. There are as many numbers displayed as there are matches to report of the pattern. In this case there are 6 matches. Clicking on a match displays the result (look for the little > symbol in the display that points at the line matched), and it marks the number in green to help you remember that you've inspected this report. In Figure 5 we see the state of this panel after having selected and displayed the first match (on the left), and then the last (#6). The result of the last selection is shown in the main results window (on the left in Figure 5).

Figure 5 -- Selections of matches (right) and results of the 9th match shown in the main results window (left).

The match that is shown (Figure 5) points at (look for the > symbol in the left margin) a line with a variable named name. To check where a function with the same name could be defined within this set of source files we can now type in a more detailed query, as shown in Figure 6.

First note that the command window already contains some commands that iCobra synthesized for us to display the things we were interested in. The command dp Shadow 6, for instance, display the match 6 from the pattern set named Shadow, using the dp (display pattern) query command.

We now first typed a reset command (abbreviated to "r"), which also clears the results panel, followed by a "mark name (" command, to mark all locations that contain a token named name that is likely used as a function name because it is followed by an open round brace. (We used the abbreviated version of the command: "m"). Next, to cause the results to be displayed in the top results window we use a display command (abbreviated here to d).

Be careful placing the cursor at the bottom line in the query command window at the bottom of the main display -- if not placed at the very end, in the left margin, whatever is typed simply edits the command window but is not issued as a command. And, for course, remember to add that display command to see results, or else you'll be staring at a blank screen and wonder why nothing showed up after issuing that query command. Figure 6 shows two occurrences of the token sequence "name (", one for the definition of the function, and one for a call of the same. So indeed, the variable "name" is used both as a plain scalar variable and as a function name in this code.

Figure 6 -- The display after typing the query sequence "r; m back; d" in the command window.

Using the Menus

Figure 7 -- The File Menu.

Clicking on the Find Menu (Figure 8) opens a new window just below the main iCobra window.

Figure 8 -- The Find Menu.

The bottom row can be used to type in the name of an item that we're looking for in the source text. The window provides a choice of six different types of tokens to search for, by selecting the corresponding radio button. We can match on a function definition, function calls, typedef declarations, macro definitions, structure or union declarations, or variable declarations. After typing in the search box, the matching items appear in the top results window, if any. The results window remains blank if no matches are found. In Figure 8 we searched for Macro Definitions for the word PARAMS, producing a match in file cobra_links.c on line 671. Of course, had we not selected the Macro Definitions button in the Find Menu panel, but instead searched for Variable Declarations, no results would have been shown.

The View Menu (Figure 9) allows us to set the mode in which iCobra displays the results of query libraries (cf. Figures 4 and 5). There are four options, with the Context mode as the initial default. The current mode is also always displayed in the upper right hand of the main iCobra window. (See for instance in Figure 6, the upper-right corner which shows ViewMode: Context.)

The four options for setting the main View Mode are: Tokens, Context, Marked, and JSON. In the default Context mode, each match found is displayed with a few lines of source text around it, and the main line of the match marked with a small > symbol in the left margin. (Similar to the output of a "d" or "display" command in a session with the background Cobra tool.) If the View Mode is set to Tokens, which causes the results panel to only show only the matching tokens for a query. (Similar to the output of a "l" or "list" command in the main Cobra tool.)

Figure 9 -- The View Menu.

If the View Mode is set to Marked, the exact extent of a match is indicated within each matched source line, with small up-arrows below the printed text. (Similar to the output of a "p" or "pre" command in the main Cobra tool.)

Finally, in View Mode JSON, the matches from a pattern search are displayed in JSON format (allowing them also to be saved in that form with the File Menu option Save Results, cf. Figure 6).

The Options Menu (Figure 10) has just two choices. The first allows us to toggle the display of line numbers in file listings (e.g., after clicking on a filename in the list shown to the right of the main Results window, cf. Figure 2).

Figure 10 -- The Options Menu.

The second option is to invert the display of the Results window from black letters on a white background to white letters on a black background, or vice versa. Both these options were enabled in Figure 10.

The Pattern Sets Menu (Figure 11) gives access to some of the more powerful tools in Cobra.

Figure 11 -- The Pattern Sets Menu.

There are four options in this menu. The first can be used to restart the Predefined Checks Panel (Figures 1, 2, 3), in case you deleted it.

The second option, Read Patterns from File, allows us to read in a new set of previously defined patterns from a file. The format of the file is a simple list of pattern expressions and caption commands, as for instance in:

$ cat userdefined.icobra
pe One: while ( 0 )
ps caption One Foo
pe Two: while ( 1 )
ps caption Two Goo
$

The third option, Define New Pattern Sets, allows us to define new pattern sets directly through the GUI, rather than reading them from an external file. Selecting this option opens up a new window to the right of the main iCobra panel, as shown in Figure 12.

Figure 12 -- Defining New Pattern Sets.

The top entry box is used to give a new to the new pattern set query. The second entry is for providing a brief explanation of what the search is for, and the bottom entry box is used to define the actual pattern to be used. Typing a return character in any of the three boxes will invoke the search, though if any of the boxes is left blank a warning will be issued instead.

The last option in the menu, Apply Operations on Sets, can be used to define set operations on existing, named, pattern sets. Selecting it displays a new window, shown in Figure 13.

Figure 13 -- The Set Operations Menu.

Three types of set operations are available: intersection, union, or set subtraction. In the three entry boxes we define the two source sets and the new name for the set that will hold the results of the operation (which could be empty of course).

The Metrics Panel

Figure 14 -- The Metrics Panel.

The six charts shown here describe identifier lengths in characters, function lengths in lines, the number of parameters of functions, the number of functions per file, the comment ratios of files and the cyclomatic complexity numbers for the files in the set. Each of these charts is created from data that is generated by a specific script in the Cobra rules directory, and that could therefore be modified by the user if needed.

For each metric there is normally a limit that should not be exceeded. This limit, or maximum value, is indicated with a vertical orange line. For identifiers this limit is often taken to be 32 characters, because early compilers did not distinguish identifiers that differed beyond that prefix. The entries that exceed the limit are shown in orange, the ones that meet the limit are in soft green.

The Heatmap Panel

Figure 15 -- The Heatmap Panel.

By clicking on the filename (or anywhere in a rectangle) a new window will pop up that shows the contents of the file itself, with the lines with warnings color-coded, as showin in Figure 16.

Figure 16 -- Navigating the warnings in file cobra_te.c.

The top bar shows the total number of warnings in the file (in this case 40) and the number of different pattern sets they are in (in this case 4). The warnings can be inspected with the navigation buttons in the upper-right of the window. << moves the view to the first match, >> to the last, and the > and < buttons move one warning forward or backward, respectively.

The name of the pattern set for a warning is shown in the upper right as well, and a simple color code is used to distinguish warnings from different sets (though no more than seven different color codes are used). The navigation panel also gives the name of the pattern set matched and its color code used for the currently displayed match.

The Warnings Panel

Figure 17 -- The Warnings Panel.

This time, clicking on one of the names in a rectangle brings up the pattern set window where you can make selections of which warning to display in the main results panel. In Figure 18, for example, we clicked on the rectangle labeled Macros and see the selection window with all 58 matches found for this pattern.

Figure 18 -- Navigating Warnings from the Macro Pattern.

After clicking on, say, the match numbered 28 the results panel will show a macro named is_bound (pointed to by the > in the left margin). And indeed, the parameter named n is not enclosed in round braces in the expansion of the macro on the right, as shown in Figure 19. (We manually rearranged the panels a bit for this Figure.)

Figure 19 -- Match #28 of the Macro Warnings.

The Help Panel

Figure 20 -- The Help Panel.

Links