6. Command-line usage for graph-includes

See "graph-includes --help".

Please note that this tool does not allow do access the full power and flexibility of DEPS. A new one, to be called deps-grapher is planned for subsequent releases, but not enough of the new design has been implemented yet to start working on this new tool.

6.1. output type

The default output is a .dot file on standard output, suitable for formatting by dot (from the graphviz toolkit), or interactive editing by dotty (also from graphviz). Alternatively, a graph file for the Tulip graph visualizer can be generated instead using "--renderer=tulip".

You can ask graph-includes to do the formatting for you, eg. using "--output=<file>.<suffix>". It will run "dot -T<suffix>", so that "--output=mydeps.ps" or "--output=mydeps.jpg" will have the expected behaviour. If your suffix is not known to dot, it will complain itself, so asking for --output=foo.bar will cause a message like:

Warning: language bar not recognized, use one of: canon cmap cmapx dia dot fig gd gd2 gif hpgl imap ismap jpeg jpg mif mp pcl pic plain plain-ext png ps ps2 svg svgz vrml vtx wbmp xdot

If you intend to print the result on paper, the default layout will likely be too large. You can use --paper=a4 to select parameters that will produce a smaller graph and spilt it into pages. This flag also changes the default output format to postscript. Be warned that dot may not honor the page-splitting parameter for all output formats.

Since the transitive reduction can take time, you may like the --verbose switch, which will show a progress bar.

6.2. what to draw

The files to be analyzed are given as non-option arguments, and can be explicitely specified, or found by recursing in directories. Eg, to analyse foo.c in current directory, as well as all C/C++ files in the src/ directory, use:

$ graph-includes foo.c src/

When an directory argument is specified, it is searched for files whose name matches a specific regexp pattern, whose default value depends on the specified language (see --language below). This pattern can be overriden using the --fileregexp option. Eg, to match in addition to .c and .h files, those with an additional .tmpl suffix, you could write:

$ graph-includes -I src -fileregexp '\.[ch](\.tmpl)?$' src/

How dependencies get extracted from the source files depend on the language used in those files. You can specify it with the --language flag. Default value is C (which should also be used for other languages based on the C preprocessor, like C++). There is also some partial support for perl - see comments in lib/graphincludes/extractor/perl.pm for more details.

In order to tell the #include resolver where to look for included files, you can use the cpp-like -I (aka. --Include) flag. Eg:

$ graph-includes -I src src/

Dependencies not found in the project (ie. files appearing in #include but not given on command-line) are listed as "not found" in the graph-includes.report file for diagnostics purposes, unless they are found in a system directory. System directories are declared in a similar fashion, with the --sysInclude option. Eg:

$ graph-includes -I src -sysI /opt/foo/include src/

Language extractor have some knowledge about default system include dirs: the C extractor knows about /usr/include, and the Perl extractor asks perl itself.

To avoid having useless information on the graph, --prefixstrip=<prefix> can be used to avoid repeating a given prefix in all node labels. Typically:

$ graph-includes --prefixstrip=src/ src/

6.3. how to draw

Files and their inter-dependency build up the first of all graphs, named files. Transformations can then be applied to such graphs, producing new graphs. Production of those new graphs define a transformation graph, whose nodes are our graphs, and whose edges denotes which graphs were used in producing which other graphs.

Typically, files will be grouped in a hierarchy of groups. "Level 0 groups" typically containing just one file, are the nodes of the files graph. Groups hierarchies are defined by the selected project class, selected by the --class=<class> option. See below for descriptions of the project classes available by default, and for instructions to write customized project classes.

Note

In graph-includes 0.11 and earlier, when a given node of level n is not part of a group at level n+1, it still appears at that level, as if it was the only member of a group. This is not the case any more. To achieve a similar result in DEPS 0.12, the relevant graphs must be merged using the consolidate transformation.

The range of group levels to be drawn is selected with --consolidate=<min>-<max>, which defaults to 1-1. Eg, for class "default", whose group levels are defined as:

0

one file per group

1

what/ever.* go into a what/ever group (usually interface + implementation)

2

what/* go into a what group, supposing top-level directories denote modules of some sort

Group levels below "min" or above "max" are not displayed as nodes. If a file is not a member of any group between "min" and "max" levels, it will simply not be represented.

Another way of using the grouping feature is to color nodes according to the group(s) they belong to, using a class-defined color scheme, possibly modified by --color <n>:<label>=<color>[,<label>=<color>…] options, where <n> is the group level in which the group name <label> will receive a background of the specified color, which can be defined either by a named X11 color (like "blue" or "palegreen"), or by a RGB color using the standard X11 "#RRGGBB" syntax.

The number of grouping levels to be colored is limited by the renderer to be used. As of 0.11, the dot renderer only supports coloring 2 group levels. Groups of a lower level than the minimal level requested to --consolidate cannot be colored, for obvious reasons.

For those wanting to see what edges the transitive reduction dropped, the --showdropped will add them to the graph in a different color. Be prepared for your computer room to get a noticeable temperature increase for anything else than a small set of files with only few dependencies.

OTOH, --focus=node-label will do the same, but only for the dependencies of a specified node. That should prevent the nasty effects described above, and will be useful for various purposes, including debugging the transitive reducer.

People still getting cold may also like to circumvent the transitive-reduction engine completely, using --alldeps. The author assumes no responsibility for losses of mental health induced by trying to make any serious use of the resulting graph.