cvstatic(1)

NAME
     cvstatic - static analysis tool

SYNOPSIS
     cvstatic [-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.

     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.

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
     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
          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.

FILES
     cvstatic.fileset
     cvstatic.xref
     cvstatic.index
     cvstatic.posting
     /usr/lib/WorkShop/cvstaticpp

SEE ALSO
     Help