README

   1
   2                 graph-includes toolkit
   3                 ======================
   4
   5 IN SHORT
   6 --------
   7
   8 Graph-includes creates a graph of dependencies between source-files
   9 and/or groups of source-files, with an emphasis on getting readable
  10 and usable graphs even for large projects.
  11
  12 Usability of the dependency graphs are currently improved by:
  13 - customizable grouping of several source files into a single node
  14 - transitive reduction of the graph
  15
  16 It currently supports graphing the C/C++ #include relationship, using
  17 graphviz.
  18
  19
  20 IMPORTANT NOTICE
  21 ----------------
  22
  23 This tool is still under development, and the default project class
  24 may not suit your needs: being still somewhat ad-hoc, it may not be
  25 able to resolve the #include directives into your header files.
  26 Specify --verbose twice to get an idea of whether you suffer from
  27 this.
  28
  29 In the meantime, "--class uniqueincludes" may help you, especially if
  30 your filenames are unique across your whole project.
  31
  32
  33 INSTALLATION INSTRUCTIONS
  34 -------------------------
  35
  36 Like standard perl packages.  Eg:
  37
  38 $ perl Makefile.PL prefix=/usr/local
  39 $ make
  40 $ su
  41 # make install
  42
  43
  44 New versions can be found at http://ydirson.free.fr/soft/graph-includes/.
  45
  46
  47 HOW TO TAKE ADVANTAGE OF THIS TOOL TO IMPROVE YOUR CODE
  48 -------------------------------------------------------
  49
  50 1. on the spirit of dependency cleanup
  51
  52 When developping a project of medium size (we'll talk mostly C/C++
  53 here, but that will apply to most languages), expecially with many
  54 people writing code, it is quite easy to get to a point where each
  55 file (out of several tens of hundreds of files) depends on too many
  56 other files.
  57
  58 The most obvious relation is the #include one.  The more #includes a
  59 file has, the more time it takes to build - especially when those
  60 included files #include themselves a bunch of other files.  For a
  61 project of about 100 files, just producing a graph of all those files,
  62 with arrows representing the #include dependencies, will usually give
  63 an unreadable graph, and will show very little about possible
  64 improvements.
  65
  66 A less obvious relation appears more clearly when you consider not
  67 files by themselves, but the set of files made of an interface and the
  68 matching implementation.  Let's consider two such sets, made of the
  69 files a.h, a.c, b.h, b.c.  a.c includes b.h, and b.c includes a.h, and
  70 each implementation, following good practice, includes its own
  71 interface.  A simple dependency graph as described above would show
  72 such a graph:
  73
  74         a.c -> b.h
  75            \  /|
  76             \/
  77             /\
  78            /  \|
  79         b.c -> a.h
  80
  81 If OTOH we represent those sets of files instead of the files
  82 themselves, we now have something like:
  83
  84         a <--> b
  85
  86 This shows much more clearly that those two modules are intrinsicately
  87 related.  In many cases, this will express that whenever you use the
  88 a.o file resulting from the build of a.c, you'll need to link b.o as
  89 well, and vice versa.  This will be the case when each file uses the
  90 headers to get function prototypes.  Then hunting for abusive
  91 dependencies will allow, for example, to select with finer grain which
  92 of those modules of code will need to go into which executable, thus
  93 producing lighter executables.
  94
  95 In other cases, headers would just have been used to access a type
  96 definition from b.h, and the associated b.o would not be needed.  In
  97 such cases, you may want to consider splitting such "low-level"
  98 declarations into their own headers.  Not only this would simplify the
  99 graph, allowing you to get a better grasp on your source code, but it
 100 can also lead to faster compilations, since each file will be able
 101 include less unrelated definitions.
 102
 103
 104 2. possible strategies to help locating abusive dependencies
 105
 106 More to be written.
 107
 108
 109
 110 COMMAND-LINE USAGE
 111 ------------------
 112
 113 See "graph-includes -help".
 114
 115
 116 EXISTING PROJECT CLASSES
 117 ------------------------
 118
 119 To be written.  See "IMPORTANT NOTICE" above.
 120
 121
 122 DEFINING YOUR OWN PROJECT CLASS
 123 -------------------------------
 124
 125 See graphincludes::project::wesnoth in the examples/ dir as an example.
 126
 127
 128 CAVEATS
 129 -------
 130
 131 - this script only handles explicitely-declared dependencies, it
 132   won't detect it if eg. a prototype cut'n'paste was used instead of
 133   using the correct #include, but you shouldn't do that anyway :)
 134
 135
 136 TODO
 137 ----
 138
 139 - write more documentation
 140 - get out of the ad-hoc include resolution
 141 - modularization (finish the restructuring into a cleaner and more modular design)
 142   - include syntax definition
 143   - graph output syntax (allow to generate tulip graphs)
 144   - provide a simple hash-based filelabel implementation
 145   - use hash-based constructors (eg. like CGI.pm)
 146   - find the accessory classes as easily as possible (like nagios-plugins ?)
 147   - separate styling from project classes
 148 - presentation
 149   - generalize the special_edge() mechanism
 150   - optionally show labels or count for files in a node and color arcs
 151     according to them
 152   - optionally show external references
 153   - draw cycles in a given color
 154   - draw a specific path
 155   - allow setting fg color for a specific group level
 156   - provide automatic coloring schemes
 157   - color intra-group edges with the same color as nodes (post-processing ?)
 158   - support for printable dot graphs (smaller, splitted by paper-sized page)
 159   - allow to draw lower-level node when there is none for the
 160     requested level (eg. on -show 2 2)
 161   - allow to request drawing of who in a high-level node points to
 162     another node (ie. violates some constraint)
 163   - label edges with the number of explicit inclusions flowing through them
 164   - investigate candidate tools for hyperbolic layout ?
 165 - CLI impovements
 166   - recursive directory search to avoid long command-lines
 167   - provide support for cpp-like -I flags
 168 - provide an interactive tool to help understanding a project's
 169   structure.  Maybe with graphviz' lefty, or as a specialized tulip
 170   gui ?
 171 - bugs
 172   - the "default" class is not yet generally usable, as it makes a
 173     couple of assumptions on the source layout
 174   - transitive reduction may not be complete, some more edges could
 175     possibly be dropped - wesnoth tree at 2005-03-25 exhibits the problem
 176     with the "display -> builder -> animated -> image" path
 177
 178
 179 LICENSE
 180 -------
 181
 182     Copyright (c) 2005 Yann Dirson <ydirson@altern.org>
 183
 184     This program is free software; you can redistribute it and/or modify
 185     it under the terms of the GNU General Public License, version 2,
 186     as published by the Free Software Foundation.
 187
 188     This program is distributed in the hope that it will be useful,
 189     but WITHOUT ANY WARRANTY; without even the implied warranty of
 190     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 191     GNU General Public License for more details.