whouses 0.15

whouses Perl module is an impact analysis in a clearmake build environment.

SYNOPSIS

Run this script with the -help option for usage details. Here are some additional sample usages with explanations:

whouses foobar.h

Shows all DOs that make use of any file matching /foobar.h/.

whouses -recurse foobar.h

Same as above but follows the chain of derived files recursively.

whouses -exact foobar.h

Shows all DOs that make use of the specified file. The -exact flag suppresses pattern matching and shows only DOs which reference the exact file.

Whouses provides a limited form of "impact analysis" in a clearmake build environment. This is different from traditional impact analysis (see TRUE CODE ANALYSIS COMPARED below for details). In particular, it operates at the granularity of files rather than language elements.

Whouses is best described by example. Imagine you have a VOB /vobs_sw in which you build the incredibly simple application foo from foo.c. You have a Makefile which compiles foo.c to foo.o and then links it to produce foo. And lets further assume youve just done a build using clearmake.

Thus, foo is a derived object (DO) which has a config record (CR) showing how it was made. Whouses analyzes that CR and prints the data in easy-to-read indented textual format. For instance:

% whouses -do foo foo.c
/vobs_sw/src/foo.c =>
/vobs_sw/src/foo.o

The -do foo points to the derived object from which to extract and analyze the CR; it will be implicit in the remaining examples. The output indicates that foo.o uses foo.c, or in other words that foo.c is a contributor to foo.o. If we add the -recurse flag:

% whouses -r foo.c
/vobs_sw/src/foo.c =>
/vobs_sw/src/foo.o
/vobs_sw/src/foo

We see all files to which foo.c contributes, indented according to how many generations removed they are. If we now add -terminals

% whouses -r -t foo.c
/vobs_sw/src/foo.c =>
/vobs_sw/src/foo

Intermediate targets such as foo.o are suppressed so we see only the "final" targets descended from foo.c.

We can also go in the other direction using -backward:

% whouses -b -e foo
/vobs_sw/src/foo <=
/vobs_sw/src/foo.o

Which shows foo.o as a progenitor of foo. Note that the arrow (<=) is turned around to indicate -backward mode. We also introduced the -exact flag here. By default, arguments to whouses are treated as patterns, not file names, and since foo has no extension it would have matched foo.c and foo.o as well. Use of -exact suppresses pattern matching.

Of course we can go backward recursively as well:

% whouses -back -exact -recurse foo
/vobs_sw/src/foo <=
/vobs_sw/src/foo.o
/vobs_sw/src/foo.c
/vobs_sw/src/foo.h
/vobs_sw/src/bar.h

And discover that foo.h and bar.h were also used.

When used recursively in the forward direction, this script answers the question "if I change file X, which derived files will need to be rebuilt"? This is the classic use, the one for which it was written. When used recursively in the backward direction it can depict the entire dependency tree in an easily readable format.

Because extracting a recursive CR can be quite slow for large build systems, whouses provides ways of dumping the CR data to a file representation for speed. Use of -save:

% whouses -do foo -save ...

will write out the data to foo.crdb. Subsequently, if foo.crdb exists it will be used unless a new the -do flag is used. See also the -db and -fmt flags.

The default save format is that of Data::Dumper. It was chosen because it results in a nicely indented, human-readable text format file.