install.txt

这是一个C程序分析工具

Metre
Copyright (c) 1993-1995 by Paul Long  All rights reserved.

This file contains installation instructions to enable a system
administrator to build, verify, and install the Metre tools, Mtree and
Metre. It also contains a brief description of how to modify the Metre
tools or write a new one.


Building Metre
--------------
The simplest way to build the Metre metrics tool is to use one of the
following commands according to which development environment you are
using. They are for Borland (MS-DOS), Microsoft (MS-DOS), Sun (SunOS),
and Gnu (UNIX), respectively. Extrapolate from these examples for other
environments. To build the Mtree call-tree tool instead, replace "metre"
with "mtree" and "metrules" with "trerules". That is all there is to it.

   bcc -A -w-rch -w-ccc -w-eff -emetre.exe metrules.c ytab.c lex_yy.c
   cl -Za -w -Femetre.exe metrules.c ytab.c lex_yy.c
   acc -w -o metre metrules.c ytab.c lex_yy.c -lm
   gcc -ansi -w -o metre metrules.c ytab.c lex_yy.c -lm


Portability

Metre is portable across operating systems (e.g., MS-DOS, UNIX, ULTRIX,
and VMS), Standard C compilers (e.g., Sun acc, Gnu gcc, Borland bcc, and
Microsoft cl), and various flavors of lex (i.e., AT&T lex, MKS lex,
Abraxas pclex, and flex) and yacc (i.e., AT&T yacc, MKS yacc, Abraxas
pcyacc, and bison).


Detailed Instructions

The following explains in more detail how to build the Metre metrics
tool whos behavior is defined by the set of rules in the metrules.c
file. As described above, to build the call-hierarchy tool, Mtree,
instead, replace "metre" with "mtree" and "metrules" with "trerules".
While this section discusses how to build and test the tools "by hand,"
makefiles are also included which do this for you. There is one for UNIX
(makefile.unx) and one for MS-DOS (makefile.dos). Read their comments
for more information on how to use them.

Metre is distributed as a set of lex, yacc, and Standard C files. With
the C source and header files, you should be able to build an executable
for any environment that has a Standard C compiler. You must use a
Standard, or "ANSI," C compiler to build Metre. A pre-ANSI, K&R C
compiler, such as cc, will not work.

For example, to build the Metre metrics tool with Borland's MS-DOS C
compiler, use this command:

   bcc -A -w-rch -w-ccc -w-eff -emetre.exe metrules.c ytab.c lex_yy.c

If you have lex and yacc, you can modify the lex and yacc specifications
in scan.l and gram.y, respectively, and regenerate the parser's C source
files. However, you are better off just using the lex_yy.c, ytab.c, and
ytab.h files that I provide. Although these files were generated by MKS
lex/yacc under MS-DOS, they should compile under any operating system
(see the section, lex_yy.c Assumes ASCII, below).

In addition to there being no benefit to regenerating these intermediate
files for the sole purpose of regenerating them, the reason to use my
lex_yy.c is that lexers generated from my lex specification by flex and
pclex do not make the source line available for printing diagnostics and
copying input to output. This is not the fault of either of these tools.
It is because I am more familiar with MKS and AT&T lex and have not
taken the time to discover how to do this with flex and pclex.

If you have MKS lex/yacc and have modified the parser which is defined
in scan.l and gram.y, you can regenerate the intermediate C files with
these two commands under MS-DOS before compiling and linking everything:

   yacc -d gram.y
   lex scan.l

The -d tells yacc to generate a token header file that the lex
specification includes. Being an MS-DOS implementation, this header file
is called ytab.h instead of the normal, UNIX y.tab.h. So if you use a
yacc that generates y.tab.h, you need to either rename it to ytab.h or
change the #include directive in scan.l to include y.tab.h instead of
ytab.h. I prefer the former so that I do not have to change the source
file. For example, under SunOS using AT&T lex/yacc and Sun's ANSI C
compiler, acc, the Metre executable can be built from the ground up with
these commands:

   yacc -d gram.y
   mv y.tab.h ytab.h
   lex scan.l
   acc -o metre metrules.c y.tab.c lex.yy.c -lm

If you use flex and bison instead of lex and yacc, replace "lex" on the
command line with "flex" and "yacc" with "bison". With bison, also use
the -y command-line option so that it generates files with yacc-like
names. The -lm option at the end of the acc command line links in the
math library that contains the definition of log10() which metrules.c
references. This math library does not need to be linked in when
building the Mtree call-hierarchy tool.


Warning Suppression

Without the -w command-line compiler options which you may have noticed,
I get various warnings depending on which compiler I am using. These
warnings can be safely ignored. The Borland compiler warns about
unreachable code, condition always being true/false, and code having no
effect. The Sun ANSI C compiler warns about -1 (~0) not fitting as an
initializer for yy_check[] in lex_yy.c. The Sun and Microsoft C
compilers both generate signed-vs-unsigned-chars warnings regarding
yytext[]. These warnings are a result of 1) having source that is
compilable under various development environments and 2) the parser
being machine-generated. If you have problems after you build the Metre
tools, you should probably rebuild them without the -w options and see
if you notice anything suspicious in the diagnostics.


End-of-line Caveat

Remember that MS-DOS and UNIX use different end-of-line characters, and
I suppose that there are environments out there that use other
characters. If your compiler chokes mysteriously on a source file that I
have provided, make sure that it is in the correct format for your
development environment. If not, you must convert it. For this, I use
flip and mud, a couple of MS-DOS tools that I downloaded from somewhere.


Macintosh Portability

I cannot tell you conclusively whether Metre is portable to the Mac. In
theory, you should not have a problem at all if you have access to a lex
and are able to regenerate the lexer from scan.l and not use the
lex_yy.c that I provide. (Be careful, though. I have heard that,
especially on the Mac, you need to make sure that your lexer is
compatible with your compiler--that, specifically, they agree about the
internal value of newline.)

You may have a problem, however, if you use my lex_yy.c. You see, lex
generates a lexer that indexes into tables based on the value of
characters. I generated lex_yy.c as an ASCII lexer (see the section,
lex_yy.c Assumes ASCII, below) that uses the value, 10, as the internal
value of newline. All of the C compilers I know about for MS-DOS, UNIX,
and VMS also use this as the internal value of newline. Programs
compiled with them work great with lex_yy.c.

On the Mac, however, things are not so rosy. At least one Mac C compiler
uses 13 for newline (and 10 for \r, curiously enough). Without
modification, the lexer in lex_yy.c would report all newlines as
non-standard characters because it sees 13 instead of the value for
newline that it expects, 10. There is hope, though--I modified the lexer
to handle this.

If the lexer detects that your compiler's internal value for newline is
not what it expects, it makes the substitution as each character is read
in. That simple. These characters are never displayed as part of an
output string, all other newlines in the program that get displayed, for
example, are left alone, and the lexer sees the newline that it was
built to recognize. I have thought about this a lot, and a couple of Mac
guys agree with me that this should work. However, it does not.

The reported problem once the modification is made (I do not have a Mac
on which to test any of this stuff) is that sometimes the lexer somehow
misses a newline and grafts two lines together. Specifically, it
complained about the '#' character in a #line directive. It must have
not been able to recognize beginning-of-line that the newline would have
presented.

So, where are we? I left the modification in so that lex_yy.c should
work on any system, not just the Mac, regardless of the internal value
of newline. I cannot explain why it has been reported to fail on the
Mac. In truth, I have only heard from one Mac guy. Perhaps there was
something peculiar about his development environment that we overlooked.
Perhaps it will work on another Mac. Perhaps yours.

If you would like to take a shot at it, the user was kind enough to give
me the following commands that he used to build Metre under MPW 3.1.

   C metrules.c; C ytab.c; C lex_yy.c
   Link -t MPST -c 'MPS ' -o metre <0xB6>
      -sn STDIO=Main -sn INTENV=Main -sn %A5Init=Main <0xB6>
      ytab.c.o lex_yy.c.o metrules.c.o <0xB6>
      "{Libraries}"Stubs.o "{CLibraries}"StdCLib.o <0xB6>
      "{CLibraries}"Math.o "{Libraries}"Runtime.o <0xB6>
      "{Libraries}"Interface.o "{Libraries}"ToolLibs.o

He said that <0xB6> is where a line-continuation character with that
value goes. I assume that if you are a Mac user, you know how to type in
such a character at your keyboard--I have no idea.

If you get lex_yy.c to work correctly on a Mac, please send me some
email. I would love to hear about it.


lex_yy.c Assumes ASCII

lex_yy.c contains tables that were built assuming an ASCII encoding of
characters. It, therefore, will not work on a non-ASCII system, such as
one that uses EBCDIC. If you intend to use Metre on a non-ASCII system,
you must generate a new lexer from the lex specification in scan.l with
a lex that builds tables for your encoding scheme. There is also a way
to define the character set in the lex specification for an otherwise
ASCII lex. "This is left as an exercise to the reader."


Certified Output

You can determine whether your executables were built correctly by
comparing the results of the following commands with the corresponding
"certifiably correct" output files, metrules.out and trerules.out, which
are included with this distribution.

        metre -DBOOLEAN=int -Dva_list=int -H -a metrules.c
        mtree -DBOOLEAN=int -rrules -l -t trerules.c

For example, using the UNIX diff and rm commands:

        metre -DBOOLEAN=int -Dva_list=int -H -a metrules.c >tmp.tmp
        diff metrules.out tmp.tmp
        mtree -DBOOLEAN=int -rrules -l -t trerules.c >tmp.tmp
        diff trerules.out tmp.tmp
        rm tmp.tmp

Under MS-DOS, you would use fc and del in place of diff and rm,
respectively.

The -D command-line option instructs Metre to use int whenever it
encounters BOOLEAN in metrules.c so that you do not need to run a
preprocessor first. (Read the Adaptability section for more information
about using the -D option.) Metre then displays various metrics about
the code contained in the file. Note that for most non-trivial C
programs, you have to run the source through a C preprocessor first.
Also, you only need to specify "-DBOOLEAN=int -Dva_list=int" for this
test, not every time you run Metre.

NOTE: Due to the floating-point calculations performed by Metre and the
varying internal floating-point representations and rounding schemes of
C compilers, some data generated by your copy of Metre may be slightly
different than the data in the certified output files.


Man Pages

Metre comes with the man pages, metre.1 and mtree.1, for use with the
UNIX man command. Copy them to a directory where man will find them.
They contain the same information as the metre.doc file, so you are not
missing any crucial information if you are running on a non-UNIX system
and have no way to access man pages.


fcnrules.c

The file, fcnrules.c, contains a small set of rules for a tool that
writes each function out to a separate file whose name is the name of
the function. It is mainly provided to show the variety of things that
can be done with Metre. Unlike the other tools, it is not generally
useful and is not practical for environments with minimal file-name
lengths, such as MS-DOS. For these reasons, there is no further mention
or support for it in the distribution. For example, the make files will
not build it. Read the comments in fcnrules.c for further information,
and build it in the same way as the other tools.



Modifying Metre
---------------
Like Abraxas' CodeCheck product, Metre is rule-based. Different behavior
is obtained by simply modifying or replacing the rules in the rules file
(metrules.c for example) rather than modifying the more complex code of
the parser (in scan.l and gram.y) that is the core of Metre. As a matter
of fact, most of the tool-specific behavior described in this document
is implemented with rules. Therefore, for your own good, make changes to
the rules file if at all possible. Only tinker with gram.y and scan.l if
the behavior you seek cannot be expressed with rules using the existing
parser.

Note: The metrules.c file contains rules that reflect my own programming
sensibilities. For example, it generates a warning if a function has
more than one return statement. If you do not like this, remove the
rule.

The parser can be used to construct other tools. Think of it as a basic,
easy-to-use parser for Standard C. As an example, by only providing a
few rules and not modifying the parser at all, I built a special version
of the UNIX tool, diff, that has the dual granularity of text lines and
C functions. My version indicates whether a function has been removed or
added, and if a function has been modified, it names it and then
generates the normal diff output showing which lines have been added,
removed, or modified.

There must always be a rules() function linked with the parser. It
contains a set of "rules" that define how the resulting executable
behaves. With no rules, for example, void rules(void){}, the result is
just a C syntax checker. A rule is of the following form:

         if (<trigger>)
            <action>

Trigger is an expression of terms taken from the structs and functions
declared in the provided metre.h header file. See the rules files (e.g.,
metrules.c) for examples. See the metre.h file for other possibilities.

A rule should NEVER have an else, although the action may contain if's
with else's. The rule's else would effectively be executed ALL THE TIME
except when the trigger occurs. Not a pretty sight.

Action is any statement, including the compound statement, {...}. Here
are some examples:

         if (keyword("goto"))
            ++fcn_gotos;

         if (fcn.begin)
         {
            fcn_gotos = 0;
            fcn_continues = 0;
            fcn_returns = 0;
            fcn_depth_max = 0;
         }