This section contains the following topics:
Creating and Loading a Database
Panorama analyzes your code and builds a database of information about it. This happens during a Panorama session when you press the CREATE DATABASE button on the MAIN menu. Panorama uses that database until you exit Panorama or you do one of the following:
CREATE a new database, or
LOAD a previously created database.
NOTE: Because test coverage and performance data are stored in separate data files, you do not need to rebuild the database to examine new data generated by tests run between the saving and reloading of the database (as long as your source code remains unchanged).
Panorama is easy to use. The following is a simplified diagram that shows the basic steps for operating Panorama.
Panorama Main Window
After you have started Panorama C/C++ (see "How to start Panorama C/C++"), the MAIN menu will come up. From here you can perform operations such as specifying the source program you wish to analyze by writing an input bin (.hsi) file, creating or loading a database for the analysis results, or running specific tools in the Panorama C/C++ environment.
The MAIN menu is subdivided into three sections: the menu bar, the tool bar, and the input bin. For more information on the menu bar, see "Menu Bar" . For more information on the input bin, see "Input Bin List".
Most of the commonly-used functions in the menu bar can be easily accessed by pressing the tool bar buttons directly on the MAIN menu.
The following is a brief description of each of the buttons on tool bar of the MAIN menu.
Load makefile: Loads the makefile of the user's program.
Load .hsi file: Loads the.hsi (input bin) file, which specifies the source
program.
Save .HSI FILE
saves the .hsi (input bin) file.
Make(create database): Creates the database for your program to store analysis
results.
Load .dbs file: Loads the database, which is the repository of all the information
gathered from Panorama's static and dynamic analysis of your program.
OO-Test:
Allows you to plan, run, and measure your testing effort; provides comprehensive
multi-level test coverage analysis (classes/function/block/branch/condition/loop
boundary/segment/condition-segment).
OO-Browser:
Generates active structure charts: function charts, class charts, and overview
charts. This button is inactive until you have specified the target program and created
the database.
OO-Diagrammer:
Generates active logic diagrams: J-Diagrams, J-Flows, and ActionPlus Diagrams.
This button is inactive until you have specified the target program and created the
database.
OO-SQA:
Generates software quality assurance metrics results: weighted bar graphs, Kiviat
Diagrams, object-oriented metrics histograms, multiple metrics diagrams, and reports.
This button is inactive until you have specified the target program and created the
database.
OO-Analyzer:
Generates active tables and charts on different aspects of your program: classes,
functions, complexity, performance,global and static variables, etc. This button is inactive
until you have specified the target program and created the database.
SELECT SUBSET
Allows you to select a subset of the files in your program, and view only the analysis results for these files. This button is inactive until you have specified the target program and created the database.
Stop:Stops all Panorama C/C++ operations on the current database.
Help:Provides on-line help for using Panorama C/C++.
With Panorama C/C++, you don't have to manually specify the source files in your program. Panorama can automatically generate the data base and an input bin file from the makefile of your program.
If your program does not have a makefile, skip to the next section "Input Bin List" .
To
load in a Makefile:
The LOAD MAKEFILE menu will come up.
All the files in that directory will be listed in the FILES list.
Alternatively, you can change directory using the DIRECTORY list, which lists all the subdirectories under the current directory. Just click on the name of the subdirectory to change to it. The new working directory will be shown in the FILTER field.
The filename you have selected will be displayed in the SELECTION box.
The content of the Makefile will be displayed in the Input Bin
Now that you have loaded in your makefile, you can directly go to the section "Creating and Loading a Database"
It is recommended to use a makefile for all purposes. If your program does not contain a makefile, you must first specify the target program to be examined using an Input Bin List.
Note: When the Input Bin List is used, Panorama will only generate static information about your program (no test coverage data).
Specifying the code you want to examine
You can specify the source files and the corresponding CPP directives for your target program in the INPUT BIN on the MAIN menu. You can make a new list each time you start Panorama C/C++, or you can save the list in a Panorama input (.hsi) file for later reloading.
An input bin file can be designed using any text editor.
To design a new Input Bin List using Panorama
1. Click on the EDIT in the MAIN MENU.
2. Type in the source files and the corresponding CPP directives in Panorama’s main window.
To save the contents of the INPUT BIN
The SAVE dialog box will pop up.
All the .hsi files in that directory will be listed in the FILES list.
Alternatively, you can change directory using the DIRECTORY list, which lists all the subdirectories under the current directory. Just click on the name of the subdirectory to change to it. The new working directory will be shown in the FILTER field.
NOTE: If you wish to list all the files in a directory, the correct FILTER format is the directory name followed by “*”, not the directory name alone.
The filename you have selected will be displayed in the SELECTION box.
Check the bottom of the MAIN menu for any messages.
If you do not want to save your edits, click CANCEL on the SAVE dialog box to close the dialog box.
Composing or modifying an Input Bin list and then saving it in an .hsi file is one way to prepare an .hsi file. Alternatively, you can create an .hsi file with UNIX commands. Change to the directory that contains your source files and use the following command to create an .hsi file:
CPP DIRECTIVES and other analysis options
For Panorama to analyze code correctly, all CPP directives in your makefile must be specified in the input bin.
Panorama recognizes three CPP directives when it parses your list of source file names: -D, -U, and -I.
-Dname: Defines a symbol name for preprocessing. This is equivalent to #define name in the source code.
-Uname: Undefines a previously set symbol name definition. This is the inverse of the -D option.
-Ipathname: Adds a pathname to the list of directories in which Panorama searches for #include files. Panorama searches for #include files in the directory containing the source file, the default include directory, and any directories named using the -I option.
-yH: Indicates also analyzing the system header files included in user programs dynamically and/or statically.
-CC=<compiler> indicates the full path name of the C++ compiler to be used
-cc=<:compiler>:: indicates the full path of the C compilerto be used
-dd=<ddfile path>: Specifies the full name of the ddfiles storing the test coverage data (it has the meaning only in the case that the input-bin file is generated from a makefile automatically)
(See your CPP documentation for more about these directives, and for information about the search order of include files.)
Placement of CPP directives in the input bin is significant in Panorama. Directives that are listed alone on a line in the input bin are considered global and apply to all source and .hsi files listed below them (but may be overridden by options at the top of nested .hsi files). Directives placed immediately after a file name on a line apply to that file only. For instance:
-I/mnt/test/incl
/mnt/test/demo_sparc/exprtst.cc -DSPARC
-CC=/usr/CC/sun4/CC
/mnt/test/demo_sparc/function.cc
/mnt/test/demo_sparc/symbol.cc
The "-I/mnt/test/incl" directive specifies where Panorama will look for header files for all the source files,
The "-DSPARC" directive instructs Panorama to define a macro named "SPARC" which has no value. This is typically used to specify that code between "#ifdef" and "#endif" is to be analyzed. This directive only applies to /mnt/test/demo_sparc/exprtst.cc.
To reload a previously saved .HSI List
The LOAD dialog box will pop up.
All the .hsi files in that directory will be listed in the FILES list.
Alternatively, you can change directory using the DIRECTORY list, which lists all the subdirectories under the current directory. Just click on the name of the subdirectory to change to it. The new working directory will be shown in the FILTER field.
NOTE: If you wish to list all the files in a directory, the correct FILTER format is the directory name followed by “*”, not the directory name alone.
The filename you have selected will be displayed in the SELECTION box.
Check the bottom of the MAIN menu for any messages.
The contents of the .hsi file you have loaded will be displayed in the MAIN menu.
You can edit the INPUT BIN using motif text editor operations by clicking the Edit button first.
Panorama C/C++ statically and dynamically analyzes your source program and builds a database of information about it. But before Panorama can start its analysis, you must specify the database (.dbs) file for it to store the information.
The OO-Browser, OO-Diagrammer, OO-Analyzer, and OO-SQA buttons on the MAIN menu are inactive until you have either created or loaded a database.
To create a database
After you have specified a target program using its makefile ( "Loading a Makefile" ) or an INPUT BIN list (see "Input Bin List" ), you can create a database for you program.
The CREATE DATABASE FILE dialog box will pop up.
(if you loaded an input-bin file rather than a makefile, Panorama will build the data base with the same name as the input-bin file but have .dbs suffix without showing this dialog box )
All the .dbs files in that directory will be listed in the FILES list.
Alternatively, you can change directory using the DIRECTORY list, which lists all the subdirectories under the current directory. Just click on the name of the subdirectory to change to it. The new working directory will be shown in the FILTER field.
NOTE: If you wish to list all the files in a directory, the correct FILTER format is the directory name followed by “*”, not the directory name alone.
The filename you have selected will be displayed in the SELECTION box.
Check the bottom of the MAIN menu for any messages.
If you do not want to create the database, click CANCEL on the SAVE dialog box to close the dialog box.
If you have used a .hsi file, a static database will be created at this point.
If you have used a makefile to specify your program, both the .hsi file and the database (for test coverage data) will be generated together. Follow the steps below to complete the database creation process.
To generate input bin file and a database
The DBS AND INPUT BIN FILE GENERATION menu will come up.
DYNAMIC AND STATIC ANALYSIS -- for while performing instrumenting (for test coverage data).
STATIC ANALYSIS ONLY -- for while simulating the running of your program.
C++ Compiler:
C Compiler:
DD PATH indicates the path that the test coverage data files to be generated (this field cannot be modified) (HSI NAME -- the path and the file name of the .hsi file to be generated. But in the new version, the HSI NAME will be automatically determined as the same as the data base name but different suffix (.hsi )).(This field cannot be modified).
MAKE START DIRECTORY -- the directory in which the make command should be initiated. (this field cannot be modified).
MAKE COMMAND -- the actual make command typed in when compiling manually, such as "make -f mymkfile."
BUILD ALL -- to disregard time dependencies in compiling the program.
UPDATE INCREMENTALLY -- to follow time dependencies in compiling the file.
WITH SYSTEM HEADER FILE ANALYSIS - to also analyze the system header files included in the program(It’s spent a lot of time).
An xterm window will pop up. If all the selections and specifications are correct, Panorama will begin to generate the input bin file.
When the input bin file has been generated, you can select to retain or close the xterm window. To close the INPUT BIN FILE GENERATOR window, press CANCEL.
Note for "static analysis only"
If you have defined a compiler macro "CC=..." in your makefile, you must specify the compiler name in the Panorama command. The default compiler is CC.
After the database has been successfully created, you can activate the individual tools in Panorama by pressing the correct tool bar buttons on the MAIN menu.
NOTE: In some cases you may wish to stop the database creation process. You can do so by pressing the STOP button on the MAIN menu.
To reload a previously saved database
If you have already created a database from a previous session, you can start a Panorama session by loading an existing database.
The LOAD dialog box will pop up.
All the .dbs files in that directory will be listed in the FILES list.
Alternatively, you can change directory using the DIRECTORY list, which lists all the subdirectories under the current directory. Just click on the name of the subdirectory to change to it. The new working directory will be shown in the FILTER field.
NOTE: If you wish to list all the files in a directory, the correct FILTER format is the directory name followed by “*”, not the directory name alone.
The filename you have selected will be displayed in the SELECTION box.
Check the bottom of the MAIN menu for any messages.
After the database has been successfully loaded, the tools buttons of the MAIN menu will become active.
Database files and incremental analysis
The first time Panorama C/C++ analyzes your entire program, it creates both an overall database file and various component database files (one for each source file -- .cc, .C, .c, and .h -- in the program). The overall database is stored in the filename you have specified in the CREATE DATABASE dialog box. The component database files are stored in the dbs subdirectory under the directory containing the overall database. These component database files contain all static analysis results for the code you have specified. The overall database file contains the information for linking the component database files to form a database.
Panorama adopts the approach of incremental analysis. It re-builds a component database file only if its source file has been changed. Panorama compares the modification time of the (existing) component database file with its source. If the component database file is missing, or if it is out of date with respect to its source, Panorama will then re-analyze its source. If you wish to force Panorama C/C++ to re-analyze all the source files, just remove the component database files under the dbs subdirectory.
Note: Incremental analysis applies as long as the makefile or .hsi file has not been modified.
An important feature of Panorama is its ability to graphically represent data from both static and dynamic analysis of your program in many formats, such as on J-charts in OO-Browser, on J-Diagrams and J-Flows in OO-Diagrammer, on metrics diagrams in OO-SQA, and in tables and charts in OO-Analyzer, in diagrams and reports in OO-Test.
Static analysis data (program structure, complexity, compactness, etc.) are derived directly from your source code. Dynamic data, however, must be generated separately before they can be displayed using different tools.
Where do dynamic data come from?
Dynamic analysis data (performance and test coverage data) must be captured during actual runs of your program. To capture performance or test coverage data, you must run a version of your program that has been compiled using your compiler’s profiling options or the Panorama test coverage data capture utility.
Compiling your code for dynamic analysis
When you specify your program using a makefile, preparation for capturing test coverage data has already been done. Just run your program using OO-Test (see Panorama /OO-Test) to accumulate test coverage data.
To capture run-time performance data, compile your program using your compiler’s -p option. Then run it to accumulate performance data in a mon.out(default filename) file.
Panorama supports test coverage on many different levels, from the more general class and function levels to the more detailed block, branch, segment, condition-decision and condition-segment levels. You can select the right level depending on your testing needs.
Panorama not only shows the percentage of code executed, but also the number of times it has been executed.
To view test coverage data in OO-Browser, OO-Diagram, OO-Analyzer, and OO-SQA, you must first capture the data using OO-Test (see Panorama/OO-Test).
The run-time performance data show (in milli-seconds) the duration of execution of a function incorporated in the program. The number of times the function was called is also shown. The performance data come from real execution of the program under testing.
Receiving the run-time performance data
The performance data are generated by compiling (using your compiler) the source code with the -p option and then running the program. The performance data are kept in a mon.out profile file generated while the executable program is running.
In order to prepare performance data for a Panorama session, you should follow these steps:
NOTE: preparing the performance data and preparing the test coverage data should be done separately.
The menu bar on the MAIN menu contains six buttons: FILE, TOOLS, SUBSET, PROPERTIES, ABOUT, and HELP. Some of the buttons open up pull-down menus with additional selections.
Click on the FILE button on the MAIN menu bar to open the FILE pull-down menu
The LOAD .HSI FILE and SAVE .HSI FILE buttons allow you to specify your source program (see "Input Bin List" ). The LOAD DBS, and CREATE DBS buttons allow you to specify the corresponding database (see "Creating and Loading a Database"), just like the tool bar buttons on the MAIN menu.
Clickon PRINT to print the content of the INPUT BIN to the default printer.
Click onQUIT to exit Panorama C/C++.
Click on the TOOLS button on the MAIN menu bar to open the TOOLS pull-down menu
From the menu, click a button to run OO-Browser, OO-Diagrammer, OO-SQA, OO-Analyzer, or OO-Test. It is same as pressing the corresponding tool bar buttons on the MAIN menu. Click STOP to stop all applications of Panorama.
Sometimes you may be interested in only a small part of the software system. For example, instead of looking at test coverage results for the entire system, you may wish to view the results for just the part you have written. You can do so using subset selection from the MAIN menu.
After you have first create or load an input bin list, you can then select from the list of files in your source program a subset of files that you are interested in. Then in each individual Panorama tools you initiate from the MAIN menu, you can specify whether to follow this subset selection. If you choose to follow it, only the analysis results for the selected files will be shown and tabulated accordingly.
Selecting a Subset
The SUBSET SELECTION box will come up.
You can also open the SUBSET SELECTION box by pressing the SELECT SUBSET button on the MAIN menu.
Note:
If the file list is empty, please check the following:
All the files in the program are selected as default.
To unselect a file, click the filename.
The subset selection has been completed. You can change it (by following the same steps) only if no tools are active.
Viewing Subset Selection
You can view the subset selection you have made, but you cannot modify it.
To modify your subset selection, use SELECT SUBSET (see "Selecting a Subset" above).
You can set properties for how your source code should analyzed. This should be done before creating the database.
The PROPERTIES menu will come up.
The old versions of C++ do not support true nested scopes. If WITH NESTED SCOPE is not selected, Panorama will analyze C++ programs in which nested types are “hoisted” to the scope of enclosing class; otherwise the implementation of true nested types is assumed.
For example, if all your source files are in ~/project/src, and the input bin lists only the source filenames (no path), then you should set .HSI RELATIVE DIRECTORY to ~/project/src.
The default is the directory from which you started Panorama C/C++.
Click ABOUT on the menu bar to get more information about the Panorama C/C++ environment you are using, such as how many individual tools have been activated.