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 HOW TO TAKE ADVANTAGE OF THIS TOOL TO IMPROVE YOUR CODE
  45 -------------------------------------------------------
  46
  47 1. on the spirit of dependency cleanup
  48
  49 When developping a project of medium size (we'll talk mostly C/C++
  50 here, but that will apply to most languages), expecially with many
  51 people writing code, it is quite easy to get to a point where each
  52 file (out of several tens of hundreds of files) depends on too many
  53 other files.
  54
  55 The most obvious relation is the #include one.  The more #includes a
  56 file has, the more time it takes to build - especially when those
  57 included files #include themselves a bunch of other files.  For a
  58 project of about 100 files, just producing a graph of all those files,
  59 with arrows representing the #include dependencies, will usually give
  60 an unreadable graph, and will show very little about possible
  61 improvements.
  62
  63 A less obvious relation appears more clearly when you consider not
  64 files by themselves, but the set of files made of an interface and the
  65 matching implementation.  Let's consider two such sets, made of the
  66 files a.h, a.c, b.h, b.c.  a.c includes b.h, and b.c includes a.h, and
  67 each implementation, following good practice, includes its own
  68 interface.  A simple dependency graph as described above would show
  69 such a graph:
  70
  71         a.c -> b.h
  72            \  /|
  73             \/
  74             /\
  75            /  \|
  76         b.c -> a.h
  77
  78 If OTOH we represent those sets of files instead of the files
  79 themselves, we now have something like:
  80
  81         a <--> b
  82
  83 This shows much more clearly that those two modules are intrinsicately
  84 related.  In many cases, this will express that whenever you use the
  85 a.o file resulting from the build of a.c, you'll need to link b.o as
  86 well, and vice versa.  This will be the case when each file uses the
  87 headers to get function prototypes.  Then hunting for abusive
  88 dependencies will allow, for example, to select with finer grain which
  89 of those modules of code will need to go into which executable, thus
  90 producing lighter executables.
  91
  92 In other cases, headers would just have been used to access a type
  93 definition from b.h, and the associated b.o would not be needed.  In
  94 such cases, you may want to consider splitting such "low-level"
  95 declarations into their own headers.  Not only this would simplify the
  96 graph, allowing you to get a better grasp on your source code, but it
  97 can also lead to faster compilations, since each file will be able
  98 include less unrelated definitions.
  99
 100
 101 2. possible strategies to help locating abusive dependencies
 102
 103 More to be written.
 104
 105
 106
 107 COMMAND-LINE USAGE
 108 ------------------
 109
 110 See "graph-includes -help".
 111
 112
 113 EXISTING PROJECT CLASSES
 114 ------------------------
 115
 116 To be written.  See "IMPORTANT NOTICE" above.
 117
 118
 119 DEFINING YOUR OWN PROJECT CLASS
 120 -------------------------------
 121
 122 See graphincludes::project::wesnoth in the examples/ dir as an example.
 123
 124
 125 CAVEATS
 126 -------
 127
 128 - this script only handles explicitely-declared dependencies, it
 129   won't detect it if eg. a prototype cut'n'paste was used instead of
 130   using the correct #include, but you shouldn't do that anyway :)
 131
 132
 133 TODO
 134 ----
 135
 136 - write more documentation
 137 - modularization (finish the restructuring into a cleaner and more modular design)
 138   - include syntax definition
 139   - graph output syntax (allow to generate tulip graphs)
 140   - provide a simple hash-based filelabel implementation
 141   - use hash-based constructors (eg. like CGI.pm)
 142   - find the accessory classes as easily as possible (like nagios-plugins ?)
 143 - presentation
 144   - optionally show labels or count for files in a node and color arcs
 145     according to them
 146   - optionally show external references
 147   - draw cycles in a given color
 148   - draw a specific path
 149   - allow setting fg color for a specific group level
 150   - provide automatic coloring schemes
 151   - color intra-group edges with the same color as nodes (post-processing ?)
 152   - support for printable dot graphs (smaller, splitted by paper-sized page)
 153   - allow to draw lower-level node when there is none for the requested level (eg. on -show 2 2)
 154   - allow to attach explanations to selected edges, optionally with
 155     constraint=false (eg. when they are discussable and cause cycle,
 156     to show how to make things better)
 157   - allow to request drawing of who in a high-level node points to
 158     another node (ie. violates some constraint)
 159   - investigate candidate tools for hyperbolic layout ?
 160 - CLI impovements
 161   - recursive directory search to avoid long command-lines
 162   - provide support for cpp-like -I flags
 163 - bugs
 164   - the "default" class is not yet generally usable, as it makes a
 165     couple of assumptions on the source layout
 166   - transitive reduction may not be complete, some more edges could
 167     possibly be dropped - wesnoth tree at 2005-03-25 exhibits the problem
 168     with the "display -> builder -> animated -> image" path
 169
 170
 171 LICENSE
 172 -------
 173
 174     Copyright (c) 2005 Yann Dirson <ydirson@altern.org>
 175
 176     This program is free software; you can redistribute it and/or modify
 177     it under the terms of the GNU General Public License, version 2,
 178     as published by the Free Software Foundation.
 179
 180     This program is distributed in the hope that it will be useful,
 181     but WITHOUT ANY WARRANTY; without even the implied warranty of
 182     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 183     GNU General Public License for more details.