PKGDEPGRAPH(1) BSD General Commands Manual PKGDEPGRAPH(1)NAMEpkgdepgraph — visual representation of installed packages
SYNOPSISpkgdepgraph [-AaCcDeFfgLloRrsv] [-d pkg_dbdir] [-i impact] [-K packages]
[-M make] [-m target] [-O package] [-P pkgsrcdir]
[-S package] [-t target] [-U package] [data ...]
DESCRIPTIONpkgdepgraph emits a dot language description of the locally installed
packages, with the inter-dependencies reduced to a minimal set of edges.
It scans each directory under the package database directory for files
named +BUILD_INFO and +REQUIRED_BY in order to gather its data.
pkgdepgraph will also read any files passed to it as arguments (or stdin
if it is not connected to a tty), in search of output that resembles that
of either lintpkgsrc(1)-i, lintpkgsrc(1)-g, audit-packages(8), or the
output from a previous incantation of this program.
In the latter case, pkgdepgraph will recolor the graph passed as input
based, as usual, on information about currently installed pkgs. Packages
that are in the input graph, but not currently installed, will be colored
black, those that are installed will be colored green, and those that
remain out of date for some reason will remain red.
The graph defaults to black, but if data from lintpkgsrc(1)-i or
audit-packages is given, or if a specific package is asserted to be out
of date (via the -O option), then nodes (and edges leading from them)
will be colored in the following manner:
green The package is completely up to date.
orange The package is up to date, but some of its dependencies require
updating.
red The package is out of date or has had a security advisory issued
against it, and should be replaced.
purple The package was not found in the local pkgsrc tree.
blue The package depends on something not found in the local pkgsrc
tree.
black The package has been removed and not yet replaced, or the graph
is uncolored. The difference between an uncolored graph and a
graph that has been recolored almost entirely black as a result
of removing all the packages can be visually detected by the
color of the pkgdepgraph package with which the graph was recol‐
ored.
It is important to note that all installed packages fall into one (or
more) of the following categories:
installed Any installed package.
out of date Any package that can be upgraded.
stale Any package that depends on a package that is out of date.
leaf Any package that is not depended on by any other package.
Selecting the type or types of packages that are listed, and how the
information is put to use, can be controlled by the following options:
-A This option modifies the output of -R to use pkg_add(1) to rein‐
stall deleted packages, instead of building directly from the
pkgsrc tree.
-a All packages. This option can be specified more than once to
augment the meaning of “all” as it relates to the selected out‐
put mode. For the default graph output, this option has no
effect. When used with -m where the default output is the list
of out of date packages, one -a will make pkgdepgraph also list
stale packages, and a second -a will make it list all installed
packages.
-C Asserts -c and adds “CLEANDEPENDS=YES” so that all rebuilt
dependencies are cleaned as well.
-c Inserts a “make clean” command in the set of instructions to
rebuild packages (see the -R option) after they are installed.
The -c option used to enable graph coloring, but now graph col‐
oring is done automatically if any coloring data is given.
-D Instead of the standard graph output, pkgdepgraph lists the
packages that need to be deleted, in “least required first”
order, so that they can be deleted without any dependency prob‐
lems. This is a good first step to take before rebuilding all
your packages that are out of date (see the -R option). This
option is an alias for -as.
-d pkg_dbdir
The location of the package database files. This defaults to
the value of the PKG_DBDIR environment variable, if it is set,
or to /usr/var/db/pkg.
-e Adds an “existence check” to each of the lines of sh(1) style
output so that commands can be skipped if the package is already
installed.
-F Makes pkgdepgraph emit a series of sh(1) commands that will
fetch all the required distfiles for rebuilding out of date
packages. This option is an alias for -m fetch.
-f Force a rebuild of all dependent packages. This option is for
use in conjunction with the -U option to force a rebuild of all
the dependencies of a package to be updated.
-g Add package subgraph groupings. This places all packages with a
common prefix (e.g., “p5” or “gimp”) in a subgraph with a line
around it so you can visually associate packages.
-i impact
Specify the impact you want to allow when rebuilding packages.
The impact of a given package being rebuilt is a number that
reflects the longest path from the “top” of the installed pack‐
ages (those packages upon which most other packages depend) to
the “bottom” of the installed packages (those packages upon
which no other packages depend). A package that needs to be
rebuilt but has nothing above it in the tree requiring rebuild‐
ing and nothing below it has an impact of 0. Values of 10 or
more for impact will probably eliminate nothing from the rebuild
list. The value for impact can also be the name of a package to
be avoided when constructing the list of things to be rebuilt.
-K packages
The base location or url from which to install binary packages.
This defaults to the value of PKG_PATH, or to PACKAGES with
“/All” added to the end, or to the value determined for pkgsr‐
cdir (see the -P option) with “/packages/All” appended to it.
-L Limit the graph to those packages that are out of date or ulti‐
mately depend on some package that is. When used with -m or -s,
this limits the list to “leaf” packages that are out of date or
stale.
-l Adds package “location” information to the labels on the nodes.
This is the path to the package under the local pkgsrc tree.
-M make Sets the name or path of the proper make(1) program for the
sh(1) commands generated by the -R and -F options. Some systems
may have more than one make(1) command or the correct choice
might not be named “make”. The default value for this is taken
from the MAKE environment variable, if it is set, or is simply
“make”.
-m target
Emits generic sh(1) commands to “make target” for each listed
package. One interesting target to specify is '$*' since that
will yield a script that will pass its own command line argu‐
ments to make for processing.
-O package
Marks package as out of date so that you can see the impact of
deleting dependent packages and rebuilding everything. This
option can be used as a quick alternative to using the output
from lintpkgsrc(1)-i for graph coloring information.
-o Adds a package “order” number to each node's label. The number
indicates only the place of the node in the hierarchy, such that
each node has a number greater than that of anything which
depends on it, and with the “leaf” nodes numbered one.
-P pkgsrcdir
The root of the pkgsrc source tree. This defaults to the value
of the PKGSRCDIR environment variable, if it is set, or to
/usr/pkgsrc.
-R Instead of the standard graph output, emits a series of sh(1)
commands that will rebuild all the out of date packages by
rebuilding all the deleted leaf packages. Packages that are out
of date should be deleted first (see the -D option). This
option is an alias for -eLm target. See the -t option for a
description of what value is used for target.
-r Reverses the order in which the packages are listed.
-S package
Selects a subgraph of the installed package base around which to
generate output. By default, if a subgraph of package is
requested, only package and those packages immediately above and
below it in the graph will be listed. To select only those
immediately below, prefix a “-” to the package name. To select
all packages below package, prefix “--” to the package name. To
select packages above package, use “+” and “++” as appropriate.
To select all packages remotely connected to package, add “=” to
the beginning. Note: take care when using this option with gen‐
erated lists or sh scripts. Since the subgraph of packages
selected by this option may not include all stale or out of date
packages involved in a proper package update procedure, the
lists may be incomplete and can cause problems.
-s Print a simple list of packages instead of sh(1) commands. The
default output set for this command is out of date packages from
the entire package set. Use combinations of -a, -L, -O package,
and -S package to select more or other package lists.
-t target
Changes the target of the -R output from “install” to target in
case you want to “make package” or some other target.
-U package
Generates a graph with only the out of date dependencies of
package marked in red (ie, packages that are out of date but not
dependencies of package will not be considered out of date).
This will show the entire effect of deleting all related pack‐
ages in order to update the dependencies of the given package.
If the -f option is used, then all the dependencies of package
will be marked as out of date and the effect on the installed
package base will be accordingly greater.
-v Adds the package version number to the node's label in the
graph.
ENVIRONMENT
MAKE
The default name for the “make” program used in the sh(1) commands gener‐
ated by the -F and -R output modes.
PKG_DBDIR
Where to find registered packages instead of /usr/var/db/pkg.
PKGSRCDIR
Where the pkgsrc tree is located instead of /usr/pkgsrc.
PKG_PATH
PACKAGES
Two variables that can be used as a location for binary packages. See
the -A and -K options for more details.
EXAMPLES
The default output:
$ pkgdepgraph | dotty -
To generate graph output for later use, and a postscript image of it:
$ lintpkgsrc -i > pkgdepgraph.in
$ audit-packages >> pkgdepgraph.in
$ pkgdepgraph-lv pkgdepgraph.in > pkgdepgraph.dot
$ dot -Tps pkgdepgraph.dot > pkgdepgraph.ps
To generate a graph of just the out of date nodes as a gif:
$ pkgdepgraph-L pkgdepgraph.in > out-of-date.dot
$ dot -Tgif out-of-date.dot > out-of-date.gif
To make a list of packages that need to be removed in order to bring all
packages up to date:
$ pkgdepgraph-D pkgdepgraph.in > delete_order
$ pkgdepgraph-R pkgdepgraph.in > rebuild.sh
To rebuild everything that has no other rebuild requirements:
$ pkgdepgraph-D pkgdepgraph.in -i0 > delete_order
$ pkgdepgraph-R pkgdepgraph.in -i0 > rebuild.sh
Or, to rebuild everything except those things that would require rebuild‐
ing perl:
$ pkgdepgraph-D pkgdepgraph.in -iperl > delete_order
$ pkgdepgraph-R pkgdepgraph.in -iperl > rebuild.sh
To subsequently delete all out of date and stale packages:
$ pkg_delete `cat delete_order`
$ sh rebuild.sh
You may also find it useful to “pre-fetch” all the required distfiles for
the rebuild as below, so that you can do all the rebuilding while off-
line:
$ pkgdepgraph-F pkgdepgraph.in > fetch.sh
$ sh fetch.sh
Running the rebuild script will probably take a while, but if you need to
stop it or it stops by itself for any reason, you can rerun the script,
and it will pick up where it left off. If there are certain packages
that you want installed before others are reinstalled, feel free to
reorder the lines in the script.
You can also “make clean” wherever you like when the rebuild script is
not running, or even update your tree in between runs of the script,
though in the latter case, it would be prudent to resume the script in
the following manner so that any packages that are newly out of date are
removed and replaced.
$ pkgdepgraph-D pkgdepgraph.in > delete_order
$ pkgdepgraph-R pkgdepgraph.in >> rebuild.sh
$ pkg_delete `cat delete_order`
$ sh rebuild.sh
It is important to note that if you have specifically installed a partic‐
ular package that is a dependency, and another package (or other pack‐
ages) exist that can satisfy the same dependency, you should probably
pre-install that particular package. There is no guarantee that the typ‐
ical processing order will install the same package.
A similar task is to update all the out of date dependencies of an pack‐
age, rebuild the package, and any others that might share the same depen‐
dencies:
$ pkgdepgraph-U mozilla -D pkgdepgraph.in > delete_order
$ pkgdepgraph-U mozilla -R pkgdepgraph.in > rebuild.sh
$ pkg_delete `cat delete_order`
$ sh rebuild.sh
Or perhaps to rebuild a specific package and all packages which depend on
it:
$ pkgdepgraph-O glib -D > delete_order
$ pkgdepgraph-O glib -R > rebuild.sh
$ pkg_delete `cat delete_order`
$ sh rebuild.sh
Finally, to see the current state of the installed packages after some
packages have been deleted, and some (but perhaps not all) have been
reinstalled:
$ pkgdepgraph out-of-date.dot | dot -Tps > current.ps
SEE ALSOdot(1), dotty(1), lintpkgsrc(1)AUTHORS
Andrew Brown ⟨atatat@netbsd.org⟩
BUGSpkgdepgraph was written in perl(1), but I believe the balance of code
layout and comments is actually reasonable, despite what you may think of
perl.
The “rebuild” output, “fetch” output, and the generic “make target” out‐
put (see the -R, -F, and -m options) do not deal very well with packages
that have moved within the pkgsrc tree. Feeding the output of
lintpkgsrc(1)-g to pkgdepgraph can offset this (it contains the current
paths to all packages under PKGSRCDIR) but sometimes is necessary that
you edit the generated scripts by hand to work around this.
July 28, 2004
