New ‘guix graph’ command

[ludo@gnu.org (Ludovic Courtès)]

[-- Attachment #1: Type: text/plain, Size: 938 bytes --]

Hi!

Here’s a long overdue ‘guix graph’ command (documentation below.)
Comments welcome!

Ludo’.


5.9 Invoking ‘guix graph’
=========================

Packages and their dependencies form a “graph”, specifically a directed
acyclic graph (DAG). It can quickly become difficult to have a mental
model of the package DAG, so the ‘guix graph’ command is here to provide
a visual representation of the DAG. ‘guix graph’ emits a DAG
representation in the input format of Graphviz
(http://www.graphviz.org/), so its output can be passed directly to
Graphviz’s ‘dot’ command, for instance.  The general syntax is:

     guix graph OPTIONS PACKAGE…

   For example, the following command generates a PDF file representing
the package DAG for the GNU Core Utilities, showing its build-time
dependencies:

     guix graph coreutils | dot -Tpdf > dag.pdf

   The output looks like this:


[-- Attachment #2: DAG --]
[-- Type: image/png, Size: 13378 bytes --]

[-- Attachment #3: Type: text/plain, Size: 828 bytes --]


   Nice little graph, no?

   But there’s more than one graph!  The one above is concise: it’s the
graph of package objects, omitting implicit inputs such as GCC, libc,
grep, etc.  It’s often useful to have such a concise graph, but
sometimes you want to see more details.  ‘guix graph’ supports several
types of graphs, allowing you to choose the level of details:

‘package’
     This is the default type, the one we used above.  It shows the DAG
     of package objects, excluding implicit dependencies.  It is
     concise, but filters out many details.

‘bag-emerged’
     This is the package DAG, _including_ implicit inputs.

     For instance, the following command:

          guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf

     ...  yields this bigger graph:


[-- Attachment #4: big DAG --]
[-- Type: image/png, Size: 621727 bytes --]

[-- Attachment #5: Type: text/plain, Size: 1414 bytes --]


     At the bottom of the graph, we see all the implicit inputs of
     GNU-BUILD-SYSTEM (*note ‘gnu-build-system’: Build Systems.).

     Now, note that the dependencies of those implicit inputs—that is,
     the “bootstrap dependencies” (*note Bootstrapping::)—are not shown
     here, for conciseness.

‘bag’
     Similar to ‘bag-emerged’, but this time including all the bootstrap
     dependencies.

‘derivations’
     This is the most detailed representation: It shows the DAG of
     derivations (*note Derivations::) and plain store items.  Compared
     to the above representation, many additional nodes are visible,
     including builds scripts, patches, Guile modules, etc.

   All the above types correspond to _build-time dependencies_.  The
following graph type represents the _run-time dependencies_:

‘references’
     This is the graph of “references” of a package output, as returned
     by ‘guix gc --references’ (*note Invoking guix gc::).

     If the given package output is not available in the store, ‘guix
     graph’ attempts to obtain dependency information from substitutes.

   The available options are the following:

‘--type=TYPE’
‘-t TYPE’
     Produce a graph output of TYPE, where TYPE must be one of the
     values listed above.

‘--list-types’
     List the supported graph types.