dot_command.md

The stack dot command

stack dot [--[no-]external] [--[no-]include-base] [--depth DEPTH]
          [--prune PACKAGES] [TARGET] [--flag PACKAGE:[-]FLAG]
          [--test] [--bench] [--global-hints]

A package and its dependencies and the direct dependency relationships between them form a directed graph. Graphviz is open source software that visualises graphs. It provides the DOT language for defining graphs and the dot executable for drawing directed graphs. Graphviz is available to download for Linux, Windows, macOS and FreeBSD.

stack dot produces output, to the standard output stream, in the DOT language to represent the relationships between your packages and their dependencies.

By default:

• external dependencies are excluded from the output. Pass the flag --external to include external dependencies;
• the base package and its dependencies are included in the output. Pass the flag --no-include-base to exclude base and its dependencies;
• there is no limit to the depth of the resolution of dependencies. Pass the --depth <depth> option to limit the depth;
• all relevant packages are included in the output. Pass the --prune <packages> option to exclude the specified packages (including project packages), where <packages> is a list of package names separated by commas;
• for all relevant project packages, relevant dependencies are included in the output. However, each project package for which dependencies are included can be specified as a target argument. The argument uses the same format as the stack build command but components of project packages are ignored. Non-project packages are also ignored;
• Cabal flags are as specified by the package description files and the project-level configuration file (stack.yaml, by default). Pass the option --flag <package_name>:<flag_name> or --flag <package_name>:-<flag_name> to set or unset a Cabal flag. This option can be specified multiple times;
• test components of project packages are excluded from the output. Pass the flag --test to include test components;
• benchmark components of project packages are excluded from the output. Pass the flag --bench to include benchmark components; and
• global packages for the specified version of GHC are those specified by the global package database of an installed GHC. Pass the flag --global-hints to use a hint file for global packages. If a hint file is used, GHC does not need to be installed.

Examples

The following examples are based on a version of the wreq package. In each case, the output from stack dot is piped as an input into Graphviz's dot executable, and dot produces output in the form of a PNG file named wreq.png.

• A simple example:

  stack dot | dot -Tpng -o wreq.png
  

  

• Include external dependencies:

  stack dot --external | dot -Tpng -o wreq.png
  

  

• Include external dependencies, limit the depth and save the output from stack dot as an intermediate file (wreq.dot).

  stack dot --external --depth 1 > wreq.dot
  dot -Tpng -o wreq.png wreq.dot
  

• Include external dependencies, exclude base and limit the depth:

  stack dot --no-include-base --external --depth 1 | dot -Tpng -o wreq.png
  

  

• Include external dependencies and prune base and other packages:

  stack dot --external --prune base,lens,wreq-examples,http-client,aeson,tls,http-client-tls,exceptions | dot -Tpng -o wreq.png
  

  

• Include external dependencies, prune base and other packages, and use a different Graphviz executable to draw the graph:

  Graphviz's twopi executable draws graphs in a radial layout.

  stack dot --external --prune base,lens,wreq-examples,http-client,aeson,tls,http-client-tls,exceptions | twopi -Groot=wreq -Goverlap=false -Tpng -o wreq.png