Show internal dependencies in your OCaml/Reason/Dune project.
Input: the root folder of your project
Output: a graph in the dot format
Example:
$ dune-deps | tred | dot -Tpng > deps.png
Running dune-deps on itself gives us this dependency graph:
Legend: diamond = executable, white ellipse = local library, grey ellipse = external library
This is the graph we obtain for the source code of opam, an elaborate project of over 50K lines of code:
From opam:
$ opam update
$ opam install dune-deps
From the git repo:
$ make
$ make test
$ make install
For producing a 2D image of the graph, we rely on the dot command
from Graphviz.
Additionally, it is often desirable to remove excessive edges to make
the graph more readable. We consider "excessive" an edge that can be
removed without changing the reachability from a node to another. This
transformation is called
transitive reduction
and is performed by tred, normally installed as part of the Graphviz
suite.
Produce a graph for the whole project without knowing anything about it. This graph may be unreadable, but it gives a sense of the project's complexity. Use the canonical command pipeline for this:
$ cd my-project
$ dune-deps | tred | dot -Tpng > deps.png
It can be useful to keep this graph embedded in your rich-text readme.
The markdown syntax, for including an image in a README.md file, is:
You can have this graph automatically created and updated if your project is hosted on GitHub. All you have to do is copy a config file into your project.
As a project grows, its graph becomes wider. Some basic dependencies
may be used directly by many components, resulting in many edges all
tangled up.
Transitive reduction
as performed by tred helps with that but is not always sufficient.
For better results, you can build a graph only for selected
components. Specify dune files or selected
subfolders directly on the command line. Something like this:
$ dune-deps src/lib-foo src/lib-bar src/lib-baz | tred | dot -Tpng > deps.png
The --hourglass or -h option restricts the graph to the
dependencies and reverse dependencies of the specified libraries.
This is useful to eliminate independent components that may clutter
the view.
This example restricts the graph to the dependencies and reverse
dependencies of the opam-client library:
$ dune-deps -h opam-client | tred | dot -Tpng > opam-client.png
Compare this with the full graph of the opam project shown above.
Other options are provided for showing only the dependencies, or only
the reverse dependencies. It is also possible to do so for multiple
nodes of interest. See dune-deps --help for details.
You can see this by showing all the direct dependencies, i.e. a plain run without transitive reduction:
$ dune-deps | dot -Tpng > deps.png
The resulting graph can be messy, but the number of arrows pointing to the node of interest should give you the answer you're looking for.
Note that this assumes dune files are properly written with all the
direct dependencies listed. If some code uses a module Foo directly, the
library foolib providing Foo must be declared as a dependency. In
such case, declare dependencies as (libraries foolib barlib) even if
barlib itself depends on foolib.
Dune-deps was initiated by Martin Jambon. It is distributed free of charge under the terms of a BSD license.
Software maintenance takes time, skill, and effort. Please contribute to open-source projects to the best of your ability. Talk to your employer about it today.