metre.1

这是一个C程序分析工具

.TH METRE 1 "3 April 1995"
.SH NAME
metre \- software-metrics tool for Standard (ANSI/ISO) C
.SH SYNOPSIS
.B metre
[
.B \-a
] [
.B \-c
] [
.B \-C
] [
.BI \-D name =
.cc +
... ]
+cc .
.if n .ti +5
[
.BI \-D name = def
.cc +
... ] [
+cc .
.B \-H
] [
.BI \-m metric
.cc +
... ]
+cc .
.if n .ti +5
.if t .ti +.5i
[
.BI \-o output-file
] [
.B \-s
] [
.BI \-S subst-file
.cc +
... ]
+cc .
.if n .ti +5
[
.BI \-T stroud-number
] [
.B \-w
] [
.I input-file
.cc +
... ]
+cc .
.LP
.B metre
.BI \-f resp-file
.TP
.B metre \-h
.SH DESCRIPTION
.LP
.B metre
reports the following metrics, where applicable, at the function, module
(file), and project level. For each metric, it reports the minimum,
maximum, average, and total, where applicable.
.LP
.RS
.RS
.ti -5
McCabe's cyclomatic complexity
.RB ( cyc ).
.LP
.ti -5
Myers' extended complexity
.RB ( exc ).
.LP
.ti -5
Halstead's program length
.RB ( pln ),
program vocabulary
.RB ( pvc ),
program volume
.RB ( pvl ),
program level
.RB ( plv ),
programming effort
.RB ( pef ),
intelligence content
.RB ( inc ),
programming time (in hours)
.RB ( ptm ),
and language level
.RB ( llv ).
.LP
.ti -5
Number of source
.RB ( scl ),
code
.RB ( cdl ),
comment
.RB ( cml ),
and blank lines
.RB ( bll ).
.LP
.ti -5
Number of executable
.RB ( exs ),
declaration
.RB ( dcs ),
and preprocessor
.RB ( pps )
statements.
.LP
.ti -5
Backfired function points
.RB ( fnp ).
.LP
.ti -5
Maximum control depth
.RB ( mcd ).
.LP
.ti -5
Identifier count
.RB ( idc )
and length
.RB ( idl ).
.LP
.ti -5
Number of functions
.RB ( fnc )
and modules
.RB ( mdc ).
.LP
.RE
.RE
See the
.B \-m
option for a description of how the metric abbreviations are used.
.LP
.B metre
generates a warning if it encounters a
.B goto
or
.B continue
statement or multiple
.B return
statements in a function. It also generates a warning if it encounters
indention accomplished by both spaces
.I and
tabs.
.LP
Input, which must be valid
.I Standard C
code, is taken from the list of
.IR input-file s
that are named on the command line. If no
.IR input-file s
are specified, input is taken from standard input. Output is written to
standard output or, if the
.B \-o
option is used, to the
.IR output-file .
.SH OPTIONS
Options may appear in any order and may be interspersed with
.IR input-file s.
There are no spaces between an option and its argument. Options cannot be
combined into a single argument.
.TP
.B \-a
Adjust backfired function points based on cyclomatic complexity.
.TP
.B \-c
Generate data in horizontal, comma-separated-value format
.RI ( CSV )
in the same order as the normal, vertical output. This allows the data to
be more easily used by another program or imported into a database or
spreadsheet. You will probably also want to suppress warnings with the
.B \-w
option so that warnings will not be interspersed with the CSV data.
.IP
The options that effect whether certain metrics are reported also work
for the CSV output. For example, the Halstead metrics are only reported
if the
.B \-H
option is specified or a Halstead metric is selected, for example,
.BR \-mpln .
If a value is not printed, its comma seperator is not printed either.
In other words, there is never an empty field, e.g., "
.B ,,
".
.TP
.B \-C
Causes the input stream to be interspersed with the output stream.
.TP
.BI \-D name =
Remove all occurences of
.I name
from the input stream. Can be repeated any number of times.
.TP
.BI \-D name = def
Replace all occurences of
.I name
in the input stream with
.IR def .
Can be repeated any number of times. The
.B \-D
option may be enough to convert any compiler-specific extensions you are
using to something that
.B metre
understands as Standard C syntax. For example, since Borland uses
.B cdecl
in its
.B stdio.h
file, I have to use the following command to get
.B metre
to accept it:
.RS
.IP
.B metre \-Dcdecl= metrules.i
.RE
.IP
This defines cdecl as a null string, effectively removing all
occurrences from the input stream. There may also be a situation where a
lexeme used in a declaration could be converted to another, as in the
following:
.RS
.IP
.B metre \-Dselector=int foo.i
.RE
.IP
The lexeme,
.BR selector ,
is a type specifier recognized by Intel's iRMX C compiler.
.IP
Depending on which command-line interpreter, or shell, you are using,
quoting a definition option may allow you to specify expansion text
that contains imbedded spaces, such as
.B
"\-Dulong=unsigned long"
.cc +
.
+cc .
.TP
.BI \-f resp-file
Read all command-line options from a
.IR "response file" .
For example,
.BR \-fmetre.cmd ,
causes
.B metre
to ignore any other arguments on the command line and use whatever
arguments are in the file,
.BR metre.cmd . 
The arguments in this file can be specified on one or more lines. Any input
or output redirection must be specified on the command line,
however. A response file is especially useful when
.B metre
is executed repeatedly with a large number of command-line arguments,
such as file names or
.B \-D
options.
.TP
.B \-h
Display help.
.TP
.B \-H
Calculate the Halstead metrics.
.B metre
does not normally calculate them because of the extra processing required.
.TP
.BI \-m metric
Print the
.I metric
identified by this abbreviation, for example,
.BR \-mfnp .
The abbreviations from which one can choose appear in parentheses
following the metrics listed in the
.B DESCRIPTION
section. If none are specified, all are printed (after taking the
.B \-H
option into consideration). If one or more are specified, only
those that are specified are printed. This option can be specified more
than once. For example,
.BR "\-mcyc \-mexc" ,
would print only the cyclomatic and extended complexity metrics.
.TP
.BI \-o output-file
Redirect output to a file, e.g.,
.BR \-oout.txt .
This is provided for environments such as VMS that do not have
command-line redirection.
.TP
.B \-s
Only display the summaries (module summary, and if more than one module,
module summaries and project summary). In other words, this suppresses
the function-specific information.
.TP
.BI \-S subst-file
Substitute
.I input-file
name. Since
.B metre
reports the name of the
.I input-file
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
.B \-S
option can be used to specify the name of the original file, e.g.,
.BR \-Smyfile.c .
This option can be repeated so that each instance specifies a
.I subst-file
name for each
.IR input-file ,
respectively. If you entered this line:
.RS
.IP
.B metre \-Sa.c \-Sb.c a.i b.i
.RE
.IP
the
.B metre
output would use the name,
.BR a.c ,
for the first file
.RB ( a.i )
and
.B b.c
for the second file
.RB ( b.i ).
.TP
.BI \-T stroud-number
This is the highest number of "moments" per second that humans can perceive.
It ranges from 5 to 20 moments per second, maybe a little less. Halstead uses
18 in his book,
.IR "Elements of Software Science" ,
so
.B metre
uses a default
.I stroud-number
of 18 for its calculation of
.I Programming
.IR Time .
You can specify another value. For example,
.B \-T10
specifies a
.I stroud-number
of 10.
.TP
.B \-w
Suppress warning diagnostics.
.SH NOTES
.LP
This is the man page for the
.B metre
software-metrics tool that is part of the Metre source-code distribution.
.LP
.B metre
refers to lines by number in an
.I input-file
unless it encounters a line directive, for example,
.IP
.B
#line 5 "startup.c"
.LP
or
.IP
.B
# 503 "main.c" 2
.LP
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 can, you
probably want to instruct it to do so.
.LP
.B metre
ignores preprocessor directives (from
.B #
to end-of-line) other than line
directives, so if your preprocessor passes any through, such as
.BR #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
.B metre
without being preprocessed.
.LP
While this is a UNIX man page,
.B metre
is portable across operating systems. This explains references that may seem
out of place or redundant for the UNIX environment, such as the
.B \-o
option.
.SH "SEE ALSO"
The man page or other documentation for your Standard C compiler or
preprocessor.
.LP
The documentation file,
.BR metre.doc ,
which accompanies the Metre source-code distribution.
.SH BUGS
While
.B metre
recognizes C comments, for example,
.BR "/* a comment */" ,
it does not recognize
C++ comments\-those that begin with
.BR // .
.LP
The
.B \-C
option only works if
.B metre
was built with an MKS or AT&T lexer and not a flex or pclex lexer. The
lexer distributed with
.B metre
is an MKS lexer. If built with a flex or pclex lexer, this option is ignored.
.LP
.B 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
.BR metre .
.LP
All typedefs are treated as if they have file scope.
.LP
Structure members cannot have the same name as a visible typedef.