metre.doc

这是一个C程序分析工具

Copyright (c) 1993-1995 by Paul Long All rights reserved.
Internet:   [e-mail] or [e-mail]          April 3, 1995
CompuServe: 72607,1506

                                Metre v2.3

Introduction
------------
Metre is a Standard C (ANSI/ISO) parser whos behavior is determined by a
set of rules. It is portable across operating systems, Standard C
compilers, and various flavors of lex and yacc. However, lex and yacc
are generally only needed if you modify the parser, which is not very
likely, or want to run the tools on a non-ASCII system, which is not
very common.

When the parser is linked with the rules specified in the accompanying
file, metrules.c, it becomes Metre, a software-metrics tool for
Standard C. When linked with trerules.c, it becomes Mtree, a tool that
prints call trees. See the sections, Metre Metrics Tool and Mtree
Call-Tree Tool, respectively, for tool-specific information. All other
sections apply to any tool built with Metre. For an explanation of how
to construct other tools, see the section, Modifying Metre, in the
accompanying install.txt file.

Note: The term, "Metre," is overloaded in that it is used to refer to
this entire product including the parser and the provided sets of rules
and to refer to the software-metrics tool. In other words, Metre is used
to build the Metre software-metrics tool, but it can also be used to
build other tools that have nothing to do with metrics, such as the
Mtree call-tree tool. "Metre" is overloaded because of its history--it
was originally intended to be solely a metrics tool.


Common Capabilities

There are capabilities common to all tools built with Metre. From the
command line, you can define identifers, provide substitute input-file
names, suppress warnings, provide name of file from which to read
command-line arguments, specify name of output file, interleave input
with output, and print help information. Input is taken from a list of
file names on the command line or from standard input if no files are
specified. These are described in more detail, below.


Input
-----
Metre does not perform preprocessing, so you should typically run your
source through a preprocessor first and then run the output of the
preprocessor into Metre. For example, with Borland's MS-DOS tool set:

         cpp -P- myfile.c

(The -P- tells the preprocessor not to include its non-Standard-C line
directives in the output.) In this case, the output would be called
myfile.i. This is the file that should be used with Metre, as in the
following:

         metre myfile.i

To facilitate piping, Metre takes its input from stdin if no file name
is specified on the command line. This way, if your preprocessor can
write its output to stdout, you do not need an intermediate file, as in,
cpp | metre.

Since Metre output refers to the input file by name and this may not be
the name of the original source file (for example, you ran the
preprocessor on it but the preprocessor did not generate line directives
which would contain the name of the original file), the -S option can be
used to specify the name of the original file, as in -Smyfile.c. Note
that this option can be repeated so that each one specifies a substitute
file name for each input file, respectively. If you entered the
following line:

         metre -Sa.c -Sb.c a.i b.i

the Metre output would use the name, "a.c", for the first file (a.i)
and "b.c" for the second file (b.i).

Metre refers to lines by number in its input file unless it encounters a
line directive, e.g., #line 5 "startup.c" or # 503 "main.c" 2. It
replaces the current line number and file name with whatever is
specified in the line directive. Some preprocessors can place line
directives in the output file that relate back to the original source
file. If yours does, you probably want to use this option.

While Metre recognizes C comments, for example, /* a comment */, it does
not recognize C++ comments--those that begin with //. Until Metre does,
there is a utility you can download in source form that converts C++
comments to C comments. I have not used it, so I cannot personally vouch
for it. It was written by Lars Wirzen ([e-mail]). If
you have WWW access, see

        http://www.cs.helsinki.fi/~wirzeniu/misc/ccmtcnvt.art,

or get it from the comp.sources.misc archives (ftp.uu.net, as
/usenet/comp.sources.misc/volume43/ccmtcnvt).

Standard C requires there to be one or more external declarations in a
translation unit. However, header files often contain preprocessor
directives but no external declarations. So that header files can be
parsed independent of any source files that may include them, Metre
makes external declarations optional in a translation unit.

Metre reads all command-line options from a "response file" if you use
the -f command-line option. For example, -fmetre.cmd, causes Metre to
ignore any other arguments on the command line and use whatever
arguments are in the file, metre.cmd. The arguments in this file can be
specified on one or more lines. Any input or output redirection must
continue to be specified on the command line, however. A response file
is useful when Metre is executed over and over with a large number of
command-line arguments, such as file names or -D options.


Output
------
Use the -C command-line option to cause the parser to copy its input to
its output, interspersing its reporting information with your source
file. This option only works if Metre is built with an MKS or AT&T lexer
and not a flex or pclex lexer. The lexer distributed with Metre,
lex_yy.c, is an MKS lexer.

Use the -o option to redirect output to a file, as in: -oout.txt. This
is provided for environments that do not have command-line redirection,
for example, VMS.

To suppress warning diagnostics, use the -w command-line option. To be
presented with help for a Metre tool use the -h command-line option.


Adaptibility
-------------
Metre ignores preprocessor directives (from # to end-of-line) other than
line directives, so if your preprocessor passes any through, such as
#pragmas, everything should be okay. This could also be useful if you
only rely on the preprocessor for simple substitution. If so, you might
be able to get away with running your C source file directly into Metre
without being preprocessed. This is done in the example in the Certified
Output subsection of the Building Metre section in the accompanying
install.txt file.

Some C compilers, such as Intel's iRMX C compiler, accept the dollar
sign ($) as a valid identifier character. Because of this and because
the dollar sign is not otherwise defined in C, Metre accepts identifiers
with a dollar sign. They are valid anywhere a letter is, for example,
$100, any$more, and mo$ are all valid identifiers to Metre. If you do
not want to allow it, change scan.l, run it through lex, and rebuild the
executable.

The define command-line option allows you to perform simple
substitutions within the input file. This may be enough to convert the
extensions used by your compiler to something that Metre understands as
Standard C syntax. For example, since Borland uses cdecl in its stdio.h
file, I have to use the following command to get Metre to accept it:

         metre -Dcdecl= metrules.i

This defines cdecl as a null string, effectively removing all
occurrences from Metre's input stream. There may also be a situation
where a lexeme used in a declaration could be converted to another, as
in the following:

         metre -Dselector=int foo.i

The lexeme, selector, is a type specifier recognized by Intel's iRMX C
compiler. Other examples include the storage-class specifiers, globaldef
and globalref, recognized by DEC's VAX C compiler. In this case, they
should be replaced by extern with the following:

         metre "-Dglobalref=extern" "-Dglobaldef=extern" foo.i

Note that when running Metre under DEC's VMS operating system, the
command-line options must be quoted because VMS's command-line
interpreter normally upshifts all command-line arguments. If not quoted,
Metre would see -DGLOBALREF=EXTERN and -DGLOBALDEF=EXTERN. In C,
GLOBALREF, GLOBALDEF, and EXTERN are not the same keywords as globalref,
globaldef, and extern. Therefore, globaldef and globalref would not be
replaced by extern.

Depending on which command-line interpreter, or shell, you are using,
such as MS-DOS' COMMAND.COM, quoting a definition option may also allow
you to specify expansion text that contains imbedded spaces, such as
"-Dulong=unsigned long". I have never needed to do this, but just keep
it in the back of your mind. It may come in handy someday.

Now I need to mention how to handle a situation about which several
people have asked me. "How can a get Metre to ignore the expansion of
the stdio.h macros, such as getc()?"  One answer is to modify your
stdio.h file so that if the manifest constant, Metre, is defined, it
provides function declarations instead of macro definitions. Then
preprocess your source files with "Metre" defined on the command line,
as in -DMetre. This is a trick that I found in Sun's stdio.h for
handling lint--apparently lint needlessly complains about these defines.

For example, Borland provides macros for the ferror(), feof(), getc(),
and putc() standard-I/O functions. The expanded code contains
expressions that could make your function appear to be more complex than
it is. Modify stdio.h with the following directives and function
declarations then run the preprocessor against your input file with the
-DMetre command-line option. Et voila, Metre is able to calculate a more
accurate complexity index.

   #ifdef Metre
   int ferror(FILE *);
   int feof(FILE *);
   int getc(FILE *);
   int putc(int, FILE *);
   #else
   ...   (The original defines for these functions go here.)
   #endif


Metre Metrics Tool
------------------
The set of rules in metrules.c defines the software-metrics tool, Metre.
Metre reports the following metrics at the function, module, and project
level, where applicable, and for each metric it reports the minimum,
maximum, average, and total, again where applicable.

         McCabe's cyclomatic complexity (cyc)
         Myers' extended complexity (exc)
         Halstead's program length (pln), program vocabulary (pvc),
                program volume (pvl), program level (plv), programming
                effort (pef), intelligence content (inc), programming
                time (in hours) (ptm), and language level (llv)
         Number of source (scl), code (cdl), comment (cml), and blank
                lines (bll)
         Number of executable (exs), declaration (dcs), and preprocessor
                (pps) statements
         Backfired function points (fnp)
         Maximum control depth (mcd)
         Identifier count (idc) and length (idl)
         Number of functions (fnc) and modules (mdc)

The abbreviation in parentheses following the metric is the name that
one can use in the -m command-line option. See the section, Controlling
Metre's Output, for more information.

Specifically, Metre reports these metrics for each function:

      Cyclomatic:      total
        Extended:      total
      Halstead Length: total
        Vocabulary:    total
        Volume:        total
        Level:         total
        Effort:        total
        Intelligence:  total
        Time (hours)   total
        Lang Level:    total
      Lines:           total
        Code:          total
        Comment:       total
        Blank:         total
      Exec Statements: total
      Decl Statements: total
      Max Depth:       total
      Identifiers:     total
        Length:        <min >max ~avg

these for each module:

      -Function-
      Cyclomatic:      <min >max ~avg
        Extended:      <min >max ~avg
      Halstead Length: <min >max ~avg
        Vocabulary:    <min >max ~avg
        Volume:        <min >max ~avg
        Level:         <min >max ~avg
        Effort:        <min >max ~avg
        Intelligence:  <min >max ~avg
        Time (hours)   <min >max ~avg total
        Lang Level:    <min >max ~avg
      Lines:           <min >max ~avg total
        Code:          <min >max ~avg total
        Comment:       <min >max ~avg total
        Blank:         <min >max ~avg total
      Exec Statements: <min >max ~avg
      Decl Statements: <min >max ~avg total
      Max Depth:       <min >max ~avg

      -Module-
      Lines:           total
        Code:          total
        Comment:       total
        Blank:         total
      Exec Statements: total
      Decl Statements: total
      PP Statements:   total
      Function Points: total
      Identifiers:     total
        Length:        <min >max ~avg
      Functions:       total

and these for each project if there is more than one module:

   -Function-
   Cyclomatic:      <min >max ~avg
     Extended:      <min >max ~avg
   Halstead Length: <min >max ~avg
     Vocabulary:    <min >max ~avg
     Volume:        <min >max ~avg
     Level:         <min >max ~avg
     Effort:        <min >max ~avg
     Intelligence:  <min >max ~avg
     Time (hours)   <min >max ~avg total
     Lang Level:    <min >max ~avg
   Lines:           <min >max ~avg total
     Code:          <min >max ~avg total
     Comment:       <min >max ~avg total
     Blank:         <min >max ~avg total
   Exec Statements: <min >max ~avg
   Decl Statements: <min >max ~avg total
   Max Depth:       <min >max ~avg

   -Module-
   Lines:           <min >max ~avg
     Code:          <min >max ~avg
     Comment:       <min >max ~avg
     Blank:         <min >max ~avg
   Exec Statements: <min >max ~avg
   Decl Statements: <min >max ~avg
   PP Statements:   <min >max ~avg
   Functions:       <min >max ~avg

   -Project-
   Lines:           total
     Code:          total
     Comment:       total
     Blank:         total
   Exec Statements: total
   Decl Statements: total
   PP Statements:   total
   Function Points: total
   Identifiers:     total
     Length:        <min >max ~avg
   Functions:       total
   Modules:         total

Cyclomatic is McCabe's cyclomatic complexity index; Extended is Glenford
Myers' extension to cyclomatic complexity; Lang Level refers to
Halstead's Language Level metric; Max Depth refers to the maximum
control depth; Exec, Decl, and PP Statements refer to executable,
declaration, and preprocessor statements.


Controlling Metre's Output

The abbreviations in parentheses following the metrics listed at the