CVSTATIC(1)CVSTATIC(1)NAMEcvstatic - static analysis tool
SYNOPSIScvstatic [-batch] [-fileset <filename>] [-readonly] [-executable
<filename>] [-noindex] [-preprocess] [-mode SCANNER] [-mode PARSER]
DESCRIPTION
Cvstatic is a source code analysis tool designed to help programmers
understand the structure of a program. Cvstatic allows the programmer to
ask questions about a collection of files, such as "Who calls this
function", or "Who references this variable". Cvstatic supports C, C++,
and Fortran, and provides various ways to look at your program structure
graphically, in addition to providing textual results of queries.
GETTING STARTED
To get started, type "cvstatic" in the directory containing the source
files you wish to analyze. You can ask queries by selecting an item of
the Queries menu. For more details on the available Queries, see the
Cvstatic manual. Additional information on using cvstatic can also be
found below. You can also ask for on-line help by selecting an item from
the Help menu.
FILESET FILES
Cvstatic works on source files, and does not require the files to
represent a complete program. Because cvstatic is very forgiving of
syntax errors, and does not require completeness, cvstatic will work on
programs that will not yet compile. This makes it useful when developing
new code as well as porting existing code to new platforms.
Cvstatic also have a more detailed analysis mode called parser mode that
uses a real compiler front-end to analyze the code. This mode works only
on sources that do compile.
You must provide cvstatic with a set of files to analyze. Cvstatic
analyzes files found in a fileset, which is just a file that contains a
list of files, one file per line. By default cvstatic creates a fileset
containing the pattern *.[cCfF], which matches all C, Fortran, and C++
programs in the current directory. (Note: C++ has no standard suffix
conventions, and the pattern used by cvstatic may not match c++
conventions used at your site.) A fileset file can have any name you
like, but by default cvstatic looks for a file named cvstatic.fileset
when it starts up.
If the default fileset does not meet your needs, the fileset file can be
changed as needed. You can provide cvstatic with a manually-prepared list
by editing the fileset file with a text editor. If you have many
subdirectories, you may find it useful to use the find command to create
a fileset file. For example, the following command can be used to
generate a fileset containing all C files in the current directory and
all subdirectories.
Page 1
CVSTATIC(1)CVSTATIC(1)
find . -name \*.c -print > cvstatic.fileset
All fileset files must have "-cvstatic" as the first line. If the
fileset file is created by the user outside the Static Analyzer, the user
must edit the file to add this line at the beginning. If this line is
absent, cvstatic will fail to recognize file as a valid fileset.
You do not need to list header files in a file set. Cvstatic determines
what headers are actually used as it reads the source files. By default,
cvstatic looks in the current directory (the directory of the including
file) and then /usr/include for all headers. If you want cvstatic to look
elsewhere, just add lines like:
-I/usr/local/include
to the end of the file set.
You can also ask cvstatic to extract a fileset from an executable by
specifying -executable <filename> on the command line, or use cvstatic's
fileset editor to build a list for you.
In scanner mode, Cvstatic creates several database files from the sources
listed in the fileset file. The names of these files are based on the
name of the fileset file. By default, these files are named
cvstatic.xref, cvstatic.index, and cvstatic.posting. These files are
non-ascii database files used by cvstatic to rapidly look up information
in response to queries.
In parser mode, cvstatic creates a number of files beginning with "cvdb"
that compose a database of a different format from that produced in
scanner mode. cvstatic can analyze files in either mode and will produce
both kinds of database files.
By default, cvstatic checks the dates of all files in a fileset when it
starts up. If any files are newer than the database files, cvstatic
incrementally updates the database. This behavior can be changed in one
of two ways. Cvstatic can be started in readonly mode, by specifying a
-readonly flag on the command-line. Cvstatic can also be changed to
readonly mode interactively, by selecting the appropriate option in the
General Options dialog (brought up from the General Options... entry on
the Admin menu). You can also force the database to be completely rebuilt
at any time by choosing the Force Scan command on the Admin menu.
Readonly mode is useful for viewing files mounted on read-only file
systems. For example, a large project might build a cvstatic database
overnight on a fileserver. Individual users could view this database by
starting cvstatic in readonly mode, without having cvstatic try to
rebuild the database. For large filesets, using readonly mode can reduce
startup time significantly, because cvstatic will not check the time
stamps on every file. Note however, that using an outofdate database may
mean that the results do not match the files.
Page 2
CVSTATIC(1)CVSTATIC(1)QUERIES
Cvstatic supports a lengthy list of queries. Programmers can make queries
by selecting an item from the Queries menu in the main menu bar of
cvstatic. Some queries are always available, while other queries require
a "target" argument. For example, the query: "list all functions" does
not require an argument, while "who calls <function>" does require an
argument. Queries that require an argument take their argument from the
"Query Target" text field at the top of the main cvstatic window.
Queries are displayed in the current view, and are also recorded in the
history list to allow users to re-examine results of previous queries.
VIEWS
Cvstatic offers several different ways to view the results of a query.
The default view is the text view. Other views include the Call Tree
View, the Class Tree View, and the File Dependency View.
Text View
The Text View is the default view that appears when cvstatic is first
started. This view displays the results of each query as a list. Each
item in the list represents one result of the query. For example, if you
ask "who is called by main", you will see a list of all functions called
by the function main, along with the file in which the call occurred, (in
this case the same file as main), the line number, and a short code
segment.
Clicking the mouse on a line in the Text View selects both a line and a
column. The text in the selected column is placed in the Query target
area for future use as a query target. You can also double click on any
line to bring up an editor to view the source indicated by the line.
Call Tree View
The Call Tree View displays a call graph of the functions in the fileset.
By default, the call tree displays only the functions represented by the
results of a query. For example, a query like "who is called by main" is
displayed graphically as a tree one level deep with main as the root of
the tree. Less obvious, if you display the results of a query like "who
references x", all functions that reference the variable x will be
displayed. If any of these functions have caller/callee relationships,
these will be shown as well.
The Call Tree View supports three other display modes. In Incremental
Mode the results of all previous queries remain on the screen when new
queries are made. This allows the user to build up a call tree of an
interesting portion of code incrementally. The next mode, is to show All
Defined functions in the file set at all times. The results of various
queries are shown by annotating the appropriate nodes of the tree in
color. This mode is only appropriate for fairly small filesets. For large
numbers of functions, the tree quickly becomes unmanageable. The final
mode is to show the Complete Tree at all times. This mode is similar to
Page 3
CVSTATIC(1)CVSTATIC(1)
the All Defined mode, but displays not only all functions defined in the
file set but all known functions referenced within the fileset, including
library routines, system calls and so on.
Class Tree View
The Class Tree View is used for C++ programs and allows the programmer to
see superclass/subclass relationships between classes defined within the
fileset. The Class Tree View functions similarly to the Call Tree View.
File Dependency View
The File Dependency View displays include relationships between files The
File Dependency Tree View functions similarly to the Call Tree View. This
view is useful for seeing how include files are used, but also can be
used to provide a global view of the system. For example, displaying the
File Dependency View and making the query "who references x" would
display all files that contains references to the variable x.
COMMAND LINE OPTIONS
Cvstatic accepts the following options:
-batch -fileset [fileset name]
Run cvstatic in batch mode. Batch mode is useful if you want to
build a database for a very large program and don't want to wait
while it builds. (For example, you might run cvstatic overnight as
a "cron" job.) The fileset file must already exist in the immediate
directory for batch mode to work. Filename defaults to
cvstatic.fileset. Nothing is displayed when cvstatic is run in
batch mode. When the database is built, cvstatic exits. Batch mode
always forces a complete rebuild of the database.
The -fileset option needs to be given if the default fileset is not
being used.
-readonly
Run cvstatic using the current database files. Do not attempt to
update the database. The fileset file and database files must
already exist.
-fileset <file>
Tell cvstatic to use the given file as a fileset file instead of the
default cvstatic.fileset. Database filenames will be generated based
on the given name.
-preprocess
By default, cvstatic does not preprecess files in scanner mode.
Preprocessing destroys useful information and alters the programmers
view of the program. In general cvstatic tries to work on the
unaltered sources. However, for heavily ifdef'd code, it is
sometimes desirable to preproces ifdefs. If the -preprocess flag is
given, cvstatic will run a special preprocessor before scanning the
Page 4
CVSTATIC(1)CVSTATIC(1)
code. This preprocessor only handles ifdefs and defines. It does
not perform macro expansion, nor insert included code. It does read
include files to look for defines that might affect other ifdefs.
Preprocessing adds significantly to the time required to generate a
scanner-mode database file.
-noindex
By default, cvstatic creates three database files in scanner mode.
The first, cvstatic.xref contains cross reference listings. The
second two, cvstatic.index and cvstatic.posting, provide a way to
rapidly find items in the cvstatic.xref file. If the -noindex option
is specified, the index files will not be built, and cvstatic will
rely on a slower, linear search mode for all queries. The default
mode is significantly faster, particularly on large databases.
However, the index files take time to generate and require
approximately twice as much disk space as when the -noindex option
is used.
-executable <prog>
This option requests cvstatic to generate a fileset by extracting
the filenames used to build the named executable. This executable
must be unstripped. Although this may at times provide a convenient
way to create a fileset file, you will probably want to edit the
resulting fileset file, as this technique includes all files,
including system libraries, and other files that are probably
outside the fileset of interest.
-mode SCANNER
This option limits cvstatic to operating in scanner mode. File in
the parser-mode fileset will be ignored, and queries supported only
in parser mode will be unavailable. A parser-mode database is not
produced. In the absence of either -mode option, cvstatic analyzes
files in either mode and supports all queries.
-mode PARSER
This option limits cvstatic to operating in parser mode. File in
the scanner-mode fileset will be ignored, and queries supported only
in scanner mode will be unavailable. The files cvstatic.xref,
cvstatic.postings, and cvstatic.index are not produced. In the
absence of either -mode option, cvstatic analyzes files in either
mode and supports all queries.
WARNINGS
Cvstatic is intended for use with a single program. Attempting to analyze
filesets that represent multiple programs will produce unpredictable
results in the graphical views.
Cvstatic performs a static analysis. Therefore, it cannot do anything
reasonable with C++ virtual functions, or other indirect techniques for
calling functions.
Page 5
CVSTATIC(1)CVSTATIC(1)FILES
cvstatic.fileset
cvstatic.xref
cvstatic.index
cvstatic.posting
/usr/lib/WorkShop/cvstaticpp
SEE ALSO
Help
Page 6
