path: root/pkgtools/pkgdepgraph/files/pkgdepgraph.1

.\"	$NetBSD: pkgdepgraph.1,v 1.4 2003/03/06 21:13:13 atatat Exp $
.\"
.\" Copyright (c) 2002, 2003 by Andrew Brown <atatat@netbsd.org>
.\" Absolutely no warranty.
.\"
.Dd March 6, 2003
.Dt PKGDEPGRAPH 1
.Sh NAME
.Nm pkgdepgraph
.Nd visual representation of installed packages
.Sh SYNOPSIS
.Nm
.Op Fl CcDfgLloRv
.Op Fl d Ar pkg_dbdir
.Op Fl O Ar package
.Op Fl P Ar pkgsrcdir
.Op Fl t Ar target
.Op Fl U Ar package
.Op Pa data ...
.Sh DESCRIPTION
.Nm
emits a
.Pa 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
.Pa +BUILD_INFO
and
.Pa +REQUIRED_BY
in order to gather its data.
.Pp
.Nm
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
.Xr lintpkgsrc 1 
.Fl i ,
.Xr audit-packages 1 ,
or the output from a previous incantation of this program.
.Pp
In the latter case,
.Nm
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.
.Pp
The graph defaults to black, but if data from
.Xr lintpkgsrc 1
.Fl i
or
.Pa audit-packages
is given, or if a specific package is asserted to be out of date (via the
.Fl O
option), then nodes (and edges leading from them) will be colored in
the following manner:
.Bl -tag -width purple
.It green
The package is completely up to date.
.It orange
The package is up to date, but some of its dependencies require updating.
.It red
The package is out of date or has had a security advisory issued
against it, and should be replaced.
.It purple
The package was not found in the local pkgsrc tree.
.It blue
The package depends on something not found in the local pkgsrc tree.
.It 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 presence of the
.Nm
package.
.El
.Pp
The options are as follows:
.Bl -tag -width package
.It Fl C
Asserts
.Fl c
and adds
.Dq CLEANDEPENDS=YES
so that all rebuilt dependencies are cleaned as well.
.It Fl c
Inserts a
.Dq make clean
command in the set of instructions to rebuild packages (see the
.Fl R
option) after they are installed.
The
.Fl c
option used to enable graph coloring, but now graph coloring is done
automatically if any coloring data is given.
.It Fl D
Instead of the standard graph output,
.Nm
lists the packages that need to be deleted, in
.Dq least required first
order, so that they can be deleted without any dependency problems.
This is a good first step to take before rebuilding all your packages
that are out of date (see the
.Fl R
option).
.It Fl d Ar pkg_dbdir
The location of the package database files.
This defaults to the value of the
.Pa PKG_DBDIR
environment variable, if it is set, or to
.Pa @PKG_DBDIR@ .
.It Fl f
Force a rebuild of all dependent packages.
This option is for use in conjunction with the
.Fl U
option to force a rebuild of all the dependencies of a package to be
updated.
.It Fl g
Add package subgraph groupings.
This places all packages with a common prefix (e.g.,
.Dq p5
or
.Dq gimp )
in a subgraph with a line around it so you can visually associate
packages.
.It Fl L
Limit the graph to those packages that are out of date
or ultimately depend on some package that is.
.It Fl l
Adds package
.Dq location
information to the labels on the nodes.
This is the path to the package under the local pkgsrc tree.
.It Fl P Ar pkgsrcdir
The root of the pkgsrc source tree.
This defaults to the value of the
.Pa PKGSRCDIR
environment variable, if it is set, or to
.Pa @PKGSRCDIR@ .
.It Fl O Ar package
Marks
.Ar 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
.Xr lintpkgsrc 1
.Fl i
for graph coloring information.
.It Fl o
Adds a package
.Dq 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
.Dq leaf
nodes numbered one.
.It Fl R
Instead of the standard graph output, emits a series of
.Xr 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
.Fl D
option).
.It Fl t Ar target
Changes the target of the
.Fl R
output from
.Dq install
to
.Ar target
in case you want to
.Dq make package
or some other target.
.It Fl U Ar package
Generates a graph with only the out of date dependencies of
.Ar package
marked in red (ie, packages that are out of date but not dependencies
of
.Ar package
will not be considered out of date).
This will show the entire effect of deleting all related packages in
order to update the dependencies of the given package.
If the
.Fl f
option is used, then all the dependencies of
.Ar package
will be marked as out of date and the effect on the installed package
base will be accordingly greater.
.It Fl v
Adds the package version number to the node's label in the graph.
.El
.Sh ENVIRONMENT
.Ss PKG_DBDIR
Where to find registered packages instead of
.Pa @PKG_DBDIR@ .
.Ss PKGSRCDIR
Where the pkgsrc tree is located instead of
.Pa @PKGSRCDIR@ .
.Sh EXAMPLES
The default output:
.Bd -literal -offset indent
$ pkgdepgraph | dotty -
.Ed
.Pp
To generate colored graph output for later use, and a postscript image
of it:
.Bd -literal -offset indent
$ lintpkgsrc -i \*[Gt] pkgdepgraph.in
$ audit-packages \*[Gt]\*[Gt] pkgdepgraph.in
$ pkgdepgraph -clv pkgdepgraph.in \*[Gt] pkgdepgraph.dot
$ dot -Tps pkgdepgraph.dot \*[Gt] pkgdepgraph.ps
.Ed
.Pp
To generate a graph of just the out-of-date nodes as a gif:
.Bd -literal -offset indent
$ pkgdepgraph -L pkgdepgraph.in \*[Gt] out-of-date.dot
$ dot -Tgif out-of-date.dot \*[Gt] out-of-date.gif
.Ed
.Pp
To make a list of packages that need to be removed in order to bring
all packages up to date:
.Bd -literal -offset indent
$ pkgdepgraph -D pkgdepgraph.in \*[Gt] delete_order
$ pkgdepgraph -R pkgdepgraph.in \*[Gt] rebuild.sh
.Ed
.Pp
To subsequently delete all out of date and stale packages:
.Bd -literal -offset indent
$ pkg_delete `cat delete_order`
$ sh rebuild.sh
.Ed
.Pp
The last step 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.
.Pp
You can also
.Dq make clean
wherever you like when the 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.
.Bd -literal -offset indent
$ pkgdepgraph -D pkgdepgraph.in \*[Gt] delete_order
$ pkgdepgraph -R pkgdepgraph.in \*[Gt]\*[Gt] rebuild.sh
$ pkg_delete `cat delete_order`
$ sh rebuild.sh
.Ed
.Pp
It is important to note that if you have specifically installed a
particular package that is a dependency, and another package (or other
packages) exist that can satisfy the same dependency, you should
probably pre-install that particular package.
There is no guarantee that the typical processing order will install
the same package.
.Pp
A similar task is to update all the out of date dependencies of an
package, rebuild the package, and any others that might share the same
dependencies:
.Bd -literal -offset indent
$ pkgdepgraph -U mozilla -D pkgdepgraph.in \*[Gt] delete_order
$ pkgdepgraph -U mozilla -R pkgdepgraph.in \*[Gt] rebuild.sh
$ pkg_delete `cat delete_order`
$ sh rebuild.sh
.Ed
.Pp
Or perhaps to rebuild a specific package and all packages which depend
on it:
.Bd -literal -offset indent
$ pkgdepgraph -O glib -D \*[Gt] delete_order
$ pkgdepgraph -O glib -R \*[Gt] rebuild.sh
$ pkg_delete `cat delete_order`
$ sh rebuild.sh
.Ed
.Pp
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:
.Bd -literal -offset indent
$ pkgdepgraph out-of-date.dot | dot -Tps \*[Gt] current.ps
.Ed
.Sh SEE ALSO
.Xr dot 1 ,
.Xr dotty 1 ,
.Xr lintpkgsrc 1
.Sh AUTHORS
.An Andrew Brown Aq atatat@netbsd.org
.Sh BUGS
.Nm
was written in
.Xr perl 1 ,
but I believe the balance of code layout and comments is actually
reasonable, despite what you may think of perl.