elisp-depmap.el

This repo has migrated to GitLab

https://gitlab.com/mtekman/elisp-depmap.el

(The copy here is archived. Please see the above link for the latest developments)

A library to generate a dependency map for elisp projects.

Generates a GraphViz-compatible DOT file representation of all the top-level definitions in an elisp project, and represents the connections between them.

The idea is that your code should be structured in an untangled way (i.e. split into standalone libraries contained within specific files), and the graphviz diagram generated by this package should help you know whether you need to refactor your project.

Installation

(use-package elisp-depmap
  :bind (("C-c M-d" . elisp-depmap-graphviz-digraph)
         ("C-c M-g" . elisp-depmap-graphviz)
         ("C-c M-s" . elisp-depmap-makesummarytable))
  :config ((elisp-depmap-exec-file "~/graphviz2.dot")))

Usage

Within an elisp package directory, run either

1. elisp-depmap-graphviz

   Generates an undirected graph. Useful if the project contains only one file. Each node is a function coloured by file, and shaped by variable or function type (e.g. setq, defvar, defcustom, defun, defsubst, defmacro). Each edge indicates that a function is linked to another. Border width indicates the size of the function.

2. elisp-depmap-graphviz-digraph

   Generates a directed graph with clustered subgraphs (as in the above image). Useful if the project contains multiple files, where functions from the same file are contained under the same subgraph, and an arrow from a source node/function to a target node/function indicates that the source node was called by the target.

3. elisp-depmap-makesummarytable

   Generates a summary table of functions, variables and files - including the number of lines of a function and number of references.

Customization

Variable (prefix: elisp-depmap)	Type	Default	Group	Info
parse-hashtablesize	integer	50	Parsing	Size of hashtable storing variables/functions. Increase for large projects with many definitions.
parse-function-shapes	alist	(see defn.)	Parsing	Alist of variable and function types and Graphviz Shapes. Supports elisp types and common-lisp types. Easily extendable.
secondhelp-regexreferences	string	(see defn.)	Parsing	Regular expression to catch references to top-level definitions.
graph-subclustergroups	plist	(see defn.)	Styling	Classes of sub-subgraph clusters. A plist of :keyword '([types]) pairs, where the sub-subgraph is given the name of the keyword, and clusters group all declared types.
graph-indentwidth	integer	4	Styling	Size of each indentation in spaces inside the DOT file. Does not affect resultant image.
graph-stripprojectname	boolean	t	Styling	Strip away the file name from the prefix of the function.
graph-filecolorsymbols	alist	(see defn.)	Styling	A list of (color . "prefix") pairs, where each entry will be used to color a file, and replace the file prefix with “prefix” if graph-stripprojectname is enabled.
graph-decorate	plist	(see defn.)	Styling	Keywords can be :edge, :node, :graph, :subgraph and :subsubgraph. Values are alists specifying Graphviz Attributes.
graph-linemod	integer	10	Styling	Line scaling modifier. Higher reduces the border width.
exec-file	string	~/graphviz2.dot	Command	Location of DOT file, Org (summary table) file, and Graphviz file.
exec-outext	string	png	Command	Output Graphviz file type.
exec-commandargs	string	(empty)	Command	Extra command line arguments for running DOT.