diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2011-10-11 23:15:45 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2011-10-11 23:15:45 +0300 |
commit | 24a87761b4398c48d554ae44861b33a98c4c39e4 (patch) | |
tree | e2c719f29aa2f48afde056c1b1a508738d312520 | |
parent | 17372c73a7605c1a2815c7389259cab3b8443f3f (diff) | |
download | cflow-24a87761b4398c48d554ae44861b33a98c4c39e4.tar.gz cflow-24a87761b4398c48d554ae44861b33a98c4c39e4.tar.bz2 |
Final cleanup before the release.release-1_4
* NEWS: Update.
* README: Update.
* doc/cflow.texi: Update.
* src/main.c (symbol_override): pass allocated argument to install.
* src/parser.c (yyparse): Return 0.
-rw-r--r-- | NEWS | 2 | ||||
-rw-r--r-- | README | 16 | ||||
-rw-r--r-- | doc/cflow.texi | 184 | ||||
-rw-r--r-- | src/main.c | 2 | ||||
-rw-r--r-- | src/parser.c | 4 |
5 files changed, 115 insertions, 93 deletions
@@ -2,13 +2,13 @@ GNU cflow NEWS -- history of user-visible changes. 2011-10-11 Copyright (C) 2005, 2006, 2007, 2009, 2010, 2011 Sergey Poznyakoff See the end of file for copying conditions. Please send cflow bug reports to <bug-cflow@gnu.org>. -Version 1.4 (Git) +Version 1.4, 2011-10-11 * Symbol aliases The `--symbol' option has been extended to allow for defining symbol aliases. Aliases are useful for declaring reserved words such as `__restrict' or `__inline'. For example, @@ -1,22 +1,20 @@ GNU cflow README -Copyright (C) 2005, 2010 Sergey Poznyakoff +Copyright (C) 2005, 2010, 2011 Sergey Poznyakoff See the end of file for copying conditions. * Introduction This file contains brief information about configuring, and installing GNU cflow. It is *not* intended as a replacement for the documentation, instead it is provided as a brief reference only. Please be sure to read the accompanuing documentation before using the utility. See section `Documentation' below. -Please read *all* sections of this `README' file before starting -configuration. Also make sure you read `INSTALL' if you are not -familiar with them already. Refer to file `ABOUT-NLS' for information -regarding internationalization. +For the generic configuration options, see the file `INSTALL'. +Refer to file `ABOUT-NLS' for information regarding internationalization. * History The GNU cflow was initially written in 1997, when I needed a utility that could display the control flow in a C program. The latest updates date back to 1999. Then, as I no longer needed the package, it fell into @@ -51,12 +49,18 @@ configuration option: --enable-debug, which compiles the package with cflow. * Installation After running `./configure' and `make', run `make install'. +* Configuration File + +The file src/cflow.rc provides a working configuration file for use +with gcc. See the documentation, sections 6.1 "Syntactic classes" and +6.3 "GCC Initialization", for more information. + * Documentation Complete user manual in texinfo format is provided. After the installation, it will be accessible by running `info cflow'. To read it before installing the package, run `info -f doc/cflow' from the package source root directory. @@ -67,13 +71,13 @@ http://www.gnu.org/software/texinfo for information on where to obtain it. * Bug reporting. Send bug reports and suggestions to <bug-cflow@gnu.org>. * Copyright Information: -Copyright (C) 2005, Sergey Poznyakoff +Copyright (C) 2005, 2010, 2011 Sergey Poznyakoff Permission is granted to anyone to make or distribute verbatim copies of this document as received, in any medium, provided that the copyright notice and this permission notice are preserved, thus giving the recipient permission to redistribute in turn. diff --git a/doc/cflow.texi b/doc/cflow.texi index 82bd028..dfb1fdf 100644 --- a/doc/cflow.texi +++ b/doc/cflow.texi @@ -1,8 +1,7 @@ \input texinfo @c -*-texinfo-*- -@smallbook @c %**start of header @setfilename cflow.info @settitle GNU cflow @c %**end of header @setchapternewpage odd @@ -141,56 +140,56 @@ files. It is a good idea to add a node @samp{POSIX} discussing this.} @chapter Simple Ways to Analyze Programs with @command{cflow}. Let's begin our acquaintance with the GNU @command{cflow} utility with an example. Suppose you have a simple implementation of @command{whoami} command and you wish to obtain a graph of function dependencies. Here is the program: -@smallexample +@example @verbatiminclude whoami.c -@end smallexample +@end example Running @command{cflow} produces the following output: @cindex GNU Output Format, an example -@smallexample +@example @group $ @kbd{cflow whoami.c} main() <int main (int argc,char **argv) at whoami.c:26>: fprintf() who_am_i() <int who_am_i (void) at whoami.c:8>: getpwuid() geteuid() getenv() fprintf() printf() @end group -@end smallexample +@end example @cindex GNU Output Format described @anchor{GNU Output Format} This is a direct call graph showing @dfn{caller---callee} dependencies in the input file. Each line starts with a function name, followed by a pair of parentheses to indicate that it is a function. If this function is defined in one of the input files, the line continues by displaying, within a pair of angle brackets, a function @dfn{signature} and the location of its definition. If the function calls another functions, the line ends with a colon. For example, the line -@smallexample +@example main() <int main (int argc,char **argv) at whoami.c:25>: -@end smallexample +@end example @noindent shows that function @code{main} is defined in file @file{whoami.c} at line 25, as @code{int main (int argc, char **argv)}. Terminating colon indicates that @code{main} invokes other functions. The lines following this one show which functions are called by -@code{main}. Each such line is indented by fixed amount of white space -(by default four spaces) for each nesting level. +@code{main}. Each such line is indented by a fixed amount of white space +(by default, four spaces) for each nesting level. @cindex @option{--omit-symbol-names} option introduced @cindex @option{--omit-arguments} option introduced @anchor{omit signature parts} Usually @command{cflow} prints a full function signature. However, sometimes you may wish to omit some part of it. Several options are @@ -198,15 +197,15 @@ provided for this purpose. To print signatures without function names, use @option{--omit-symbol-names} option. To omit argument list, use @option{--omit-arguments}. These options can be needed for a variety of reasons, one of them being to make the resulting graph more compact. To illustrate their effect, here is how would the first line of the above graph look if you had used both @option{--omit-} options: -@smallexample +@example main() <int () at whoami.c:25>: -@end smallexample +@end example @cindex start symbol @cindex @option{--main} command line option introduced @cindex @option{-m} command line option introduced @anchor{start symbol} By default, @command{cflow} starts outputting direct graph from @@ -214,29 +213,29 @@ the function called @code{main}. It is convenient when analyzing a set of input files comprising an entire @code{C} program. However, there are circumstances where a user would want to see only a part of the graph starting on particular function. @command{Cflow} allows to select such function using @option{--main} (@option{-m}) command line option. Thus, running -@smallexample +@example cflow --main who_am_i whoami.c -@end smallexample +@end example @noindent on the above file will produce following graph: -@smallexample +@example @group who_am_i() <int who_am_i (void) at whoami.c:8>: getpwuid() geteuid() getenv() fprintf() printf() @end group -@end smallexample +@end example @node Direct and Reverse @chapter Two Types of Flow Graphs. @cindex @option{--reverse} @cindex @option{-r} In the previous chapter we have discussed @dfn{direct graphs}, @@ -245,13 +244,13 @@ displaying @i{caller---callee} dependencies. Another type of @dfn{callee---caller} dependencies. To produce a reverse graph, run @command{cflow} with @option{--reverse} (@option{-r}) command line option. For example, using a sample @file{whoami.c}: @cindex reverse graph, example @cindex reverse tree, example -@smallexample +@example @group $ @kbd{cflow --reverse whoami.c} fprintf(): who_am_i() <int who_am_i (void) at whoami.c:8>: main() <int main (int argc,char **argv) at whoami.c:26> main() <int main (int argc,char **argv) at whoami.c:26> @@ -268,30 +267,30 @@ main() <int main (int argc,char **argv) at whoami.c:26> printf(): who_am_i() <int who_am_i (void) at whoami.c:8>: main() <int main (int argc,char **argv) at whoami.c:26> who_am_i() <int who_am_i (void) at whoami.c:8>: main() <int main (int argc,char **argv) at whoami.c:26> @end group -@end smallexample +@end example This output consists of several subgraphs, each describing callers for a particular function. Thus, the first subgraph tells that the function @code{fprintf} is called from two functions: @code{who_am_i} and @code{main}. First of them is, in turn, also called directly by @code{main}. @cindex @option{--brief} command line option introduced @cindex @option{-b} command line option introduced @anchor{--brief} The first thing that draws attention in the above output is that the subgraph starting with @code{who_am_i} function is repeated several -times. This is @dfn{verbose} output. To make it brief, use +times. This is a @dfn{verbose} output. To make it brief, use @option{--brief} (@option{-b}) command line option. For example: @cindex brief output, an example of -@smallexample +@example @group $ @kbd{cflow --brief --reverse whoami.c} fprintf(): who_am_i() <int who_am_i (void) at whoami.c:8>: main() <int main (int argc,char **argv) at whoami.c:26> main() <int main (int argc,char **argv) at whoami.c:26> [see 3] @@ -303,32 +302,32 @@ getpwuid(): who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2] main() <int main (int argc,char **argv) at whoami.c:26> [see 3] printf(): who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2] who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2] @end group -@end smallexample +@end example @cindex brief output described In brief output, once a subgraph for a given function is written, subsequent instances of calls to that function contain only its definition and the @dfn{reference} to the output line where the expanded subgraph can be found. @cindex @option{--number} command line option introduced @cindex @option{-n} command line option introduced @anchor{--number} - If the output graph is large it can be tedious to find out the + If the output graph is large, it can be tedious to find out the required line number (unless you use @dfn{Emacs cflow-mode}, @pxref{Emacs}). For such cases a special option @option{--number} (@option{-n}) is provided, which makes @command{cflow} begin each line of the output with a @dfn{reference number}, that is the ordinal number of this line in the output. With this option, the above output will look like: -@smallexample +@example $ @kbd{cflow --number --brief --reverse whoami.c} @group 1 fprintf(): 2 who_am_i() <int who_am_i (void) at whoami.c:8>: 3 main() <int main (int argc,char **argv) at whoami.c:26> 4 main() <int main (int argc,char **argv) at whoami.c:26> [see 3] @@ -340,13 +339,13 @@ $ @kbd{cflow --number --brief --reverse whoami.c} 10 who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2] 11 main() <int main (int argc,char **argv) at whoami.c:26> [see 3] 12 printf(): 13 who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2] 14 who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2] @end group -@end smallexample +@end example Of course, @option{--brief} and @option{--number} options take effect for both direct and reverse flow graphs. @node Output Formats @chapter Various Output Formats. @@ -375,23 +374,23 @@ found, the line ends with an empty pair of angle brackets. @option{--format=posix} (@option{-f posix}) has been given, or environment variable @env{POSIXLY_CORRECT} was set. The output graph in POSIX format for our sample @file{whoami.c} file will look as follows: -@smallexample +@example $ @kbd{cflow --format=posix whoami.c} 1 main: int (int argc,char **argv), <whoami.c 26> 2 fprintf: <> 3 who_am_i: int (void), <whoami.c 8> 4 getpwuid: <> 5 geteuid: <> 6 getenv: <> 7 fprintf: <> 8 printf: <> -@end smallexample +@end example It is not clear from the @acronym{POSIX} specification whether the output should contain argument lists in function declarations, or not. By default @command{cflow} will print them. However, some programs, analyzing @command{cflow} output expect them to be absent. If you use such a program, add @option{--omit-arguments} option to @@ -418,33 +417,33 @@ with exactly one horizontal tabulation character per nesting level, with an additional tab character for zeroth level and without argument lists in function declaration. So, to produce an output suitable for @command{cflow2vcg}, invoke @command{cflow} as follows@footnote{(@xref{ASCII Tree, level-indent}, for the detailed description of @option{--level-indent} option}: -@smallexample +@example @group @kbd{cflow --format=posix --omit-arguments \ --level-indent='0=\t' --level-indent='1=\t' \ --level-indent=start='\t'} @end group -@end smallexample +@end example You can use the following script to visualize call graphs using the three tools: -@smallexample +@example @group #! /bin/sh cflow --format=posix --omit-arguments \ --level-indent='0=\t' --level-indent='1=\t' \ --level-indent=start='\t' $* | cflow2vcg | xvcg - @end group -@end smallexample +@end example @node Recursive Calls @chapter Handling Recursive Calls. @cindex Recursive functions Sometimes programs contain functions that recursively call themselves. GNU output format provides a special indication for such @@ -456,20 +455,20 @@ reference line number where the @dfn{recursion root} definition was displayed. To illustrate this, let's consider the following program, that prints recursive listing of a directory, allowing to cut off at the arbitrary nesting level: -@smallexample +@example @verbatiminclude d.c -@end smallexample +@end example Running @command{cflow} on this program produces the following graph: @anchor{sample flowchart} -@smallexample +@example $ @kbd{cflow --number d.c} 1 main() <int main (int argc,char **argv) at d.c:85>: 2 fprintf() 3 atoi() 4 printdir() <void printdir (int level,char *name) at d.c:42> (R): 5 getcwd() @@ -486,13 +485,13 @@ $ @kbd{cflow --number d.c} 16 S_ISDIR() 17 putchar() 18 printdir() <void printdir (int level,char *name) at d.c:42> (recursive: see 4) 19 closedir() -@end smallexample +@end example The @code{printdir} description in line 4 shows that the function is recursive. The recursion call is shown in line 18. @node Symbols @chapter Controlling Symbol Types @@ -502,13 +501,13 @@ above output: the function @code{_exit} is missing, although according to the source file it is called twice by @code{printdir}. It is because by default @command{cflow} omits from its output all symbols beginning with underscore character. To include these symbols as well, specify @option{-i _} (or @option{--include _}) command line option. Continuing our example: -@smallexample +@example $ @kbd{cflow --number -i _ d.c} 1 main() <int main (int argc,char **argv) at d.c:85>: 2 fprintf() 3 atoi() 4 printdir() <void printdir (int level,char *name) at d.c:42> (R): 5 getcwd() @@ -526,13 +525,13 @@ $ @kbd{cflow --number -i _ d.c} 17 S_ISDIR() 18 putchar() 19 printdir() <void printdir (int level,char *name) at d.c:42> (recursive: see 4) 20 closedir() -@end smallexample +@end example @cindex @option{-i} introduced @cindex @option{--include} introduced @cindex Symbol classes defined @anchor{--include} In general, @option{--include} takes an argument specifying a @@ -552,13 +551,13 @@ is a single option, in spite of @code{-s} beginning with a minus sign. Since this might be confusing, we prefer using @samp{^} instead of @samp{-} to denote symbol exclusion.}) command line option. Our sample program @file{d.c} defines static function @code{isdir}, running @command{cflow -i ^s}, completely omits this function and its callees from the resulting graph: -@smallexample +@example $ @kbd{cflow --number -i ^s d.c} 1 main() <int main (int argc,char **argv) at d.c:85>: 2 fprintf() 3 atoi() 4 printdir() <void printdir (int level,char *name) at d.c:42> (R): 5 getcwd() @@ -571,13 +570,13 @@ $ @kbd{cflow --number -i ^s d.c} 12 strcmp() 13 putchar() 14 printdir() <void printdir (int level,char *name) at d.c:42> (recursive: see 4) 15 closedir() -@end smallexample +@end example Actually, the exclusion sign (@samp{^} or @samp{-}) can be used any place in @option{-i} argument, not only at the beginning. Thus, option @option{-i _^s} means ``@i{include symbols, beginning with underscore and exclude static functions}''. Several @option{-i} options accumulate, so the previous example can also be written as @@ -587,13 +586,13 @@ accumulate, so the previous example can also be written as contain only functions. You can, however, request displaying variables as well, by using symbol class @samp{x}. This class contains all @dfn{data symbols}, both global and static, so to include these in the output, use option @option{-i x}. For example: @anchor{x flowchart} -@smallexample +@example $ @kbd{cflow --number -i x d.c} 1 main() <int main (int argc,char **argv) at d.c:85>: 2 fprintf() 3 stderr 4 max_level <int max_level at d.c:37> 5 atoi() @@ -617,13 +616,13 @@ $ @kbd{cflow --number -i x d.c} 23 max_level <int max_level at d.c:37> 24 putchar() 25 printdir() <void printdir (int level,char *name) at d.c:42> (recursive: see 6) 26 closedir() -@end smallexample +@end example Now, lines 3, 4, 16 and 23 show data symbols, with their definitions when available. Notice, however, lines 7 and 8. Why both type name @code{DIR} and automatic variable @code{dir} are listed as data? @@ -635,15 +634,15 @@ encountering a @code{typedef}, it registers the defined symbol as a @dfn{type}. Now, @code{DIR} is not declared in @file{d.c}, so @command{cflow} has no way of knowing it is a data type. So, it supposes it is a variable. But then the input: -@smallexample +@example DIR *dir; -@end smallexample +@end example @noindent is parsed as an @emph{expression}, meaning ``multiply @code{DIR} by @code{dir}''. Of course, it is wrong. There are two ways to help @@ -658,52 +657,52 @@ concentrate on the first method. @cindex @option{--symbol} introduced @anchor{--symbol} The command line option @option{--symbol} (@option{-s}) declares a @dfn{syntactic class} of the symbol. Its argument consists of two strings separated by a colon: -@smallexample +@example --symbol @var{sym}:@var{class} -@end smallexample +@end example @noindent The first string, @var{sym} is a @code{C} identifier to be recorded in the symbol table. The second string, @var{class}, specifies a class to be associated with this symbol. In particular, if @var{class} is @samp{type}, the symbol @var{sym} will be recorded as a @code{C} type definition. Thus, to fix the above output, run: -@smallexample +@example $ @kbd{cflow --number -i x --symbol DIR:type d.c} -@end smallexample +@end example @cindex Parameter wrapper defined @cindex @code{__P}, special handling using @option{--symbol} Another important symbol type is a @dfn{parameter wrapper}. It is a kind of a macro, often used in sources that are meant to be compatible with pre-@acronym{ANSI} compilers to protect parameter declarations in function prototypes. For example, in the declaration below, taken from @file{/usr/include/resolv.h}, @code{__P} is a parameter wrapper: -@smallexample +@example void res_npquery __P((const res_state, const u_char *, int, FILE *)); -@end smallexample +@end example For @command{cflow} to be able to process such declarations, declare @code{__P} as a wrapper, for example: -@smallexample +@example cflow --symbol __P:wrapper *.c -@end smallexample +@end example In both examples above the reason for using the @option{--symbol} option was that @command{cflow} was unable to -determine what the given symbol was either because it did not +determine what the given symbol was, either because it did not see the type definition, as it was in case with @samp{DIR}, or -the macro definition was not expanded. Both cases are better +because the macro definition was not expanded. Both cases are better solved by using @dfn{preprocess mode}, described in the next chapter. Nevertheless, even with preprocessor, the @option{--symbol} option remains useful, as shown in the following sections. @menu @@ -723,20 +722,21 @@ following classes: @table @asis @item keyword @itemx kw A keyword, like @samp{if}, @samp{when} etc. @item modifier -Type modifier, i.e. a symbol appearing after data type to modify its +Type modifier, i.e. the symbol appearing after a data type to modify its meaning, like @samp{*}. @item qualifier Declaration qualifier. Can appear both before C declaration (much like @samp{static} or @samp{extern}) and after a data type (like modifiers). +@cindex __extension__ You would usually declare a @command{gcc} keyword @samp{__extension__} as a qualifier: @example --symbol __extension__:qualifier @end example @@ -745,12 +745,13 @@ as a qualifier: A C identifier. @item type A C data type, like @samp{int}, @samp{char}, etc. @item wrapper +@cindex __attribute__ That has two meanings. First, it can be used to declare parameter wrappers when running @command{cflow} without preprocessor. This usage was described above. Second, it indicates any symbol that can appear in a declaration either before an identifier or before a terminating semicolon and optionally followed by a parenthesized expression list. @@ -771,22 +772,34 @@ construct: --symbol @var{newsym}:=@var{oldsym} @end example As a result of this option, the symbol @var{newsym} is declared to be the equivalent of @var{oldsym}. +@cindex __restrict Symbol aliasing can be regarded as defining the symbol class by example of another symbol. It is useful for some special keywords, such as @samp{__restrict}: @example --symbol __restrict:=restrict @end example @node GCC Initialization @section GCC Initialization +@cindex gcc +@cindex __inline +@cindex __inline__ +@cindex __const__ +@cindex __const +@cindex __restrict +@cindex __extension__ +@cindex __attribute__ +@cindex __asm__ +@cindex __nonnull +@cindex __wur The following is a recommended set of @command{cflow} initialization options for use with @command{gcc}. We suggest you to put them in your @file{cflow.rc} file (@pxref{Configuration}). @example --symbol __inline:=inline @@ -815,13 +828,13 @@ avoiding the necessity to define special symbols using preprocessing, run the utility with @option{--cpp} (@option{--preprocess}) command line option. For our sample file @file{d.c}, this mode gives: @cindex @option{--cpp} option, an example @cindex @option{--preprocess} option, an example -@smallexample +@example $ @kbd{cflow --cpp -n d.c} 1 main() <int main (int argc,char **argv) at d.c:85>: 2 fprintf() 3 atoi() 4 printdir() <void printdir (int level,char *name) at d.c:42> (R): 5 getcwd() @@ -837,13 +850,13 @@ $ @kbd{cflow --cpp -n d.c} 15 perror() 16 putchar() 17 printdir() <void printdir (int level,char *name) at d.c:42> (recursive: see 4) 18 closedir() -@end smallexample +@end example Compare this graph with the one obtained without @option{--cpp} option (@pxref{sample flowchart}). As you see, the reference to @code{S_ISDIR} is gone: the macro has been expanded. Now, try running @code{cflow --cpp --number -i x d.c} and compare the result with the graph obtained without preprocessing (@pxref{x @@ -870,15 +883,15 @@ output flow graph using @option{--level-indent} option. The simplest use for this option is to change the default indentation per nesting level. To do so, give the option a numeric argument specifying the number of columns to indent for each nesting level. For example, the following command sets the indentation level to 2, which is half of the default: -@smallexample +@example cflow --level-indent 2 d.c -@end smallexample +@end example @noindent It can be used, for instance, to keep the graph within the page margins. However, @option{--level-indent} can do much more than that. Each @@ -916,17 +929,17 @@ nesting level). The @dfn{end marker 0} is for non-terminal nodes, and As for indent fills, @dfn{indent fill 1} is used to represent graph edge, whereas @dfn{fill 0} is used to keep the output properly aligned. To demonstrate this, let's consider following sample program: -@smallexample +@example @group @verbatiminclude foo.c @end group -@end smallexample +@end example @noindent Now, let's represent line elements by the following strings: @multitable @columnfractions 0.2 0.8 @item start @tab @samp{::} @@ -948,33 +961,33 @@ allowed in @var{string} is the notation @code{@var{C}x@var{N}}, where notation means ``@i{repeat character @var{C} @var{N} times}''. However, character @samp{x} looses its special meaning if used at the beginning of the string. This command will produce the following output: -@smallexample +@example @group ::+-main() <int main () at foo.c:3>: :: +-f() <int f () at foo.c:11>: :: | \-h() :: \-g() @end group -@end smallexample +@end example @cindex @option{--tree} introduced @cindex @option{-T} introduced Thus, we obtained an @dfn{ASCII art} representation of the call tree. GNU @command{cflow} provides a special option @option{--tree} (@option{-T}), which is a shortcut for @code{--level '0= ' --level '1=| ' --level end0='+-' --level end1='\\-'}. The following is an example of flow graph produced with this option. The source file @file{wc.c} is a simple implementation of UNIX @command{wc} command, @xref{Source of wc command}. @anchor{ascii tree} -@smallexample +@example @group $ @kbd{cflow --tree --brief --cpp wc.c} +-main() <int main (int argc,char **argv) at wc.c:127> +-errf() <void errf (char *fmt,...) at wc.c:34> | \-error_print() | <void error_print (int perr,char *fmt,va_list ap) at wc.c:22> @@ -998,13 +1011,13 @@ $ @kbd{cflow --tree --brief --cpp wc.c} | count_t wcount,count_t lcount) at wc.c:57> | \-printf() \-report() <void report (char *file,count_t ccount, count_t wcount,count_t lcount) at wc.c:57> [see 17] @end group -@end smallexample +@end example @node Cross-References @chapter Cross-Reference Output. @cindex Cross-References introduced @cindex @option{--xref} option introduced @@ -1012,20 +1025,20 @@ $ @kbd{cflow --tree --brief --cpp wc.c} GNU @command{cflow} is also able to produce @dfn{cross-reference listings}. This mode is enabled by @option{--xref} (@option{-x}) command line option. Cross-reference output lists each symbol occurrence on a separate line. Each line shows the identifier and the source location where it appears. If this location is where the symbol is defined, it is additionally marked with an asterisk and followed by -the definition. For example, here is a fragment of cross-reference +the definition. For example, here is a fragment of a cross-reference output for @file{d.c} program: -@smallexample +@example printdir * d.c:42 void printdir (int level,char *name) printdir d.c:74 printdir d.c:102 -@end smallexample +@end example It shows that the function @code{printdir} is defined in line 42 and referenced twice, in lines 74 and 102. The symbols included in cross-reference listings are controlled by @option{--include} option (@pxref{--include}). In addition to @@ -1077,25 +1090,30 @@ configuration file. The value of the @option{-D} option will be added to the preprocessor command line and will be processed by the shell, so be careful to properly quote its argument. The rule of thumb is: ``@i{use the same quoting you would have used in the shell command line}''. For example, to run @command{cc -E} as a preprocessor, you can use the following configuration file: -@smallexample +@example @group --cpp='cc -E' -DHAVE_CONFIG_H --DSQUARE\\\(x\\\)=x*x +-D__extension__\\\(c\\\)= @end group -@end smallexample +@end example + +@cindex __extension__() + By the way, the above example shows a way of coping +with the @samp{__extension__()} construct used by @command{gcc}, i.e. by +defining it to an empty string. @cindex Option cancellation It may sometimes be necessary to cancel the effect of a command line option. For example, you might specify @option{--brief} in your configuration file, but then occasionally need to obtain verbose -graph. To cancel effect of any GNU @command{cflow} option that does +graph. To cancel the effect of any GNU @command{cflow} option that does not take arguments, prepend @samp{no-} to the corresponding long option name. Thus, specifying @option{--no-brief} cancels the effect of the previous @option{--brief} option. @node Makefiles @chapter Using @command{cflow} in Makefiles. @@ -1118,57 +1136,57 @@ options you wish to use. The variable can be empty, its main purpose is making it possible to override @command{cflow} options by running @command{make CFLOW_FLAGS=@dots{} chart}. @item For each @var{program} from your @code{@var{dir}_PROGRAMS} list, for which you want to generate a flow chart, add the following statements: -@smallexample +@example @group @var{program}_CFLOW_INPUT=$(@var{program}_OBJECTS:.$(OBJEXT)=.c) @var{program}.cflow: @var{program}_CFLOW_INPUT cflow.rc Makefile CFLOWRC=@var{path-to-your-cflow.rc} \ cflow -o$@@ $(CFLOW_FLAGS) $(DEFS) \ $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) \ $(CPPFLAGS) \ $(@var{program}_CFLOW_INPUT) @end group -@end smallexample +@end example @noindent Replace @var{program} with program name and @var{path-to-your-cflow.rc} with the full file name of your @file{cflow.rc} file (if any). If you do not wish to use preprocessing, remove from the @command{cflow} command line all variables, except @code{CFLOW_FLAGS}. @item If there are several programs built by this @file{Makefile.am}, you may wish to add a special rule, allowing to create all flow charts with a single command, for example: -@smallexample +@example flowcharts: @var{prog1}.cflow @var{prog2}.cflow ... -@end smallexample +@end example @end itemize As an example, here are the relevant statements which we use in @command{cflow} @file{src/Makefile.am}: -@smallexample +@example @group EXTRA_DIST=cflow.rc CFLOW_FLAGS=-i^s cflow_CFLOW_INPUT=$(cflow_OBJECTS:.$(OBJEXT)=.c) cflow.cflow: $(cflow_CFLOW_INPUT) cflow.rc Makefile CFLOWRC=$(top_srcdir)/src/cflow.rc \ cflow -o$@@ $(CFLOW_FLAGS) $(DEFS) \ $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) \ $(CPPFLAGS) \ $(cflow_CFLOW_INPUT) @end group -@end smallexample +@end example @node Options @chapter Complete Listing of @command{cflow} Options. This chapter contains an alphabetical listing of all @command{cflow} command line options, with brief descriptions and cross references to more in-depth explanations in the body of the @@ -1208,26 +1226,26 @@ declarations}. This might speed up the processing in some cases. @bullet{} Run the specified preprocessor command. @xref{Preprocessing}. @cindex @option{-D} @cindex @option{--define} @item -D @var{name}[=@var{defn}] @itemx --define=@var{name}[=@var{defn}] - Predefine @var{name} as a macro. Implies @option{-cpp} + Predefine @var{name} as a macro. Implies @option{--cpp} (@pxref{Preprocessing}). @cindex @option{-d} @cindex @option{--depth} @item -d @var{number} @itemx --depth=@var{number} Set the depth at which the flow graph is cut off. For example, @option{--depth=5} means the graph will contain function calls up to the 5th nesting level. @cindex @option{--debug} @item --debug[=@var{number}] - Set debugging level. Default @var{number} is 1. Use this option + Set debugging level. The default @var{number} is 1. Use this option if you are developing and/or debugging @command{cflow}. @cindex @option{--emacs} @cindex @option{--no-emacs} @item --emacs @bullet{} Prepend the output with a line telling Emacs to use @code{cflow} @@ -1292,13 +1310,13 @@ For more information, @xref{Symbols}. @item --level-indent=@var{string} Use @var{string} when indenting to each new level. @xref{ASCII Tree}. @cindex @option{-m} @cindex @option{--main} @item -m @var{name} -@item --main=@var{name} +@itemx --main=@var{name} Assume main function to be called @var{name}. @xref{start symbol}. @cindex @option{-n} @cindex @option{--number} @cindex @option{--no-number} @item -n @@ -1364,13 +1382,13 @@ use this option. @cindex @option{-s} @cindex @option{--symbol} @item -s @var{sym}:@var{class} @itemx --symbol=@var{sym}:@var{class} @itemx --symbol=@var{newsym}:=@var{oldsym} @anchor{symbol types} - In first form, registers symbol @var{sym} in the syntactic class + In the first form, registers symbol @var{sym} in the syntactic class @var{class}. Valid class names are: @samp{keyword} (or @samp{kw}), @samp{modifier}, @samp{qualifier}, @samp{identifier}, @samp{type}, @samp{wrapper}. Any unambiguous abbreviation of the above is also accepted. @xref{Syntactic classes}. In the second form (with the @samp{:=} separator), defines @@ -1443,19 +1461,19 @@ sources. providing a major mode for visiting flow charts in GNU Emacs. If you have a working @command{emacs} on your machine, the module will be installed somewhere in your Emacs @code{load-path}. To load the module at startup, add the following lines to your @file{.emacs} or @file{site-start.el} file: -@smalllisp +@lisp @group (autoload 'cflow-mode "cflow-mode") (setq auto-mode-alist (append auto-mode-alist '(("\\.cflow$" . cflow-mode)))) @end group -@end smalllisp +@end lisp @noindent @cindex @option{--emacs} introduced @anchor{--emacs} The second statement associates @code{cflow-mode} with any file having suffix @file{.cflow}. If you prefer to have another suffix for flow @@ -1516,15 +1534,15 |