[[PageOutline]]

= Dependency analysis =

== Concerning terminology ==

We say that module A depends on module B (B -> A) if there is at least one function call from B to A. There is a cyclic dependency if B also depends directly (A -> B) or indirectly (e.g. A -> C -> B) on A.

Dependency can be defined on the function level as well. Function A:foo depends on function B:foo (B:foo -> A:foo) if B:foo calls A:foo. There is a cyclic dependency if B:foo also depends on A:foo, directly or indirectly.

Note that it is possible to have a cyclic dependency among modules while having no cyclic dependencies among their functions. For example, function calls from A:foo to B:foo and from B:foo2 to A:foo2 imply a cyclic dependency on the module level, but no one on the function level.

It is also possible to have dependencies between moduleblock. A moduleblock is a list containing modules ([A, B, ...]). Moduleblock X depends on moduleblock Y (Y -> X) if any of the modules of X depends on at least one of Y's modules. In the same way as before, a cyclic dependency can be defined as well.

== Capabilities ==

Mainly, you can check for cycles and dependencies among entities within the RefactorErl database. This means that the program looks for dependencies on the given level, and returns with a graph representation containing those dependencies.

In case of vast databases, dependencies can be very complex, and hard to represent. To avoid producing useless, huge dependency graphs, we provide some filter options that you can use for narrowing down the result.

== Filtering options ==

* '''Level''' - The result will only contain the dependencies based on the given level (function, module or moduleblock dependencies).
* '''Type''' - The result will contain all dependencies or only cyclic dependencies.
* '''Exclude''' - Entities depending on the '''exclude''' entities (directly or indirectly) and the '''exclude''' entities themselves are excluded from the result.
* '''Exclude_children''' - Entities depending on the '''exclude_children''' entities (directly or indirectly) are excluded from the result, but not the "exclude_children" entities.
* '''Exclude_lib''' - Entities residing in the '''exclude_lib''' libraries (but not subdirectories) are excluded from the result.
* '''Exclude_otp''' - The result will or will not contain the Erlang/OTP standard modules and functions.
* '''Starting_nodes''' - The result will only contain the '''starting_nodes''' entities and entities depending on them (directly or indirectly).
* '''Connection''' - The result will only contain the '''connection''' entities and the dependencies between the '''connection''' entities.
* '''Groups''' - Defines the moduleblocks, on which the dependency analysis will be made.

== Output ==

The output of the dependency analysis is a graph representation, where entities are nodes and dependencies are edges between these nodes (A -> B dependency would result as a directed edge from A node to B node). This representation can be text based (as erlang terms) or visual (described in a .dot graph file).

In the text based representation entities are enumerated with entities depending on them. An entity is described as its name or the corresponding id in the database, depending entities are put in a list.

== Visual representation ==

=== Function level ===

Function dependency graphs look like the following.

[[Image(function_graph.png, 512px)]]

* '''ROOT triangle''' represents a formal starting point
* '''Rectangle, deep purple''' nodes represent modules
* '''Rectangle, black''' nodes represent functions given in the connection option
* '''Hexagon, black''' nodes represent functions
* '''Ellipse, grey''' nodes represent functions which are part of an indirect dependency path

* '''Solid, continuous edge, black, normal arrowhead''' to modules from the root, and the from modules to their functions
* '''Dashed edge, black, normal arrowhead''' indicates that a function calls another function
* '''Dotted edge, grey, normal arrowhead''' indicates that a function calls another function and the edge is part of an indirect dependency path
* '''Dashed edge, red, special arrowhead''' indicates a function call, but also that it is a cyclic edge
* '''Dotted edge, red, normal arrowhead''' indicates a cyclic edge which is part of an indirect dependency path
* '''Dashed edge, green, normal arrowhead''' indicates an idirect dependency

=== Module level ===

Module dependency graphs look like the following.

[[Image(module_graph.png, 512px)]]

* '''Rectangle, deep purple''' nodes represent modules
* '''Rectangle, black''' nodes represent modules given in the connection option
* '''Ellipse, grey''' nodes represent modules which are part of an indirect dependency path

* '''Dashed edge, black, normal arrowhead''' indicates that a module calls another module
* '''Dotted edge, red, normal arrowhead''' indicates a call loop which is part of an indirect dependency path
* '''Dashed edge, red, special arrowhead''' indicates a call loop
* '''Dotted edge, grey, normal arrowhead''' indicates that a module calls another module and the edge is part of an indirect dependency path
* '''Dashed edge, green, normal arrowhead''' indicates an idirect dependency

=== Moduleblock level ===

Moduleblock dependency graphs look like the following.

[[Image(mb_graph.png, 512px)]]

* '''Hexagon, black''' nodes represent moduleblocks
* '''Rectangle table''' lists the modules of the moduleblocks

* '''Dashed edge, black, normal arrowhead''' indicates that a moduleblock calls another moduleblock
* '''Dashed edge, red, special arrowhead''' indicates a call loop

== Usage ==

Dependency analysis can be done via the following interfaces:
 * [ErlangShellInterface#Analysis Erlang shell]
 * [WebInterface/DependencyExaminations Old Web interface]
 * [wiki:Web2/DependencyExaminations New Web Interface]
 * [wiki:EmacsInterface Emacs]
 * [wiki:WxInterface/DepGraph Wx]
 * [wiki:QtInterface QT]